stonecut 1.3.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonecut",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "CLI that drives PRD-driven development with agentic coding CLIs",
   "license": "MIT",
   "repository": {

package/src/execute.ts

@@ -11,10 +11,9 @@
 
 import { checkoutOrCreateBranch, createPr, pushBranch } from "./git";
 import { LocalSource } from "./local";
-import { slugifyBranchComponent } from "./naming";
 import { renderLocal } from "./prompt";
 import { Logger } from "./logger";
-import { defaultGitOps, runAfkLoop } from "./runner";
+import { defaultGitOps, formatTokens, runAfkLoop } from "./runner";
 import { getRunner } from "./runners/index";
 import type { Issue, IterationResult, Session } from "./types";
 
@@ -22,6 +21,22 @@ import type { Issue, IterationResult, Session } from "./types";
 // Stonecut report
 // ---------------------------------------------------------------------------
 
+/** Build the metrics parenthetical for a report line. */
+function formatMetrics(r: IterationResult): string {
+	const parts: string[] = [];
+	if (r.turns != null) {
+		parts.push(`${r.turns} turns`);
+	}
+	const totalTokens =
+		r.inputTokens != null || r.outputTokens != null
+			? (r.inputTokens ?? 0) + (r.outputTokens ?? 0)
+			: undefined;
+	if (totalTokens != null) {
+		parts.push(`${formatTokens(totalTokens)} tokens`);
+	}
+	return parts.length > 0 ? ` (${parts.join(", ")})` : "";
+}
+
 /**
  * Build the Stonecut Report section for a PR body.
  */
@@ -32,11 +47,12 @@ export function buildReport(
 ): string {
 	const lines = ["## Stonecut Report", `**Runner:** ${runnerName}`, ""];
 	for (const r of results) {
+		const metrics = formatMetrics(r);
 		if (r.success) {
-			lines.push(`- #${r.issueNumber} ${r.issueFilename}: completed`);
+			lines.push(`- #${r.issueNumber} ${r.issueFilename}: completed${metrics}`);
 		} else {
 			const reason = r.error || "unknown error";
-			lines.push(`- #${r.issueNumber} ${r.issueFilename}: failed — ${reason}`);
+			lines.push(`- #${r.issueNumber} ${r.issueFilename}: failed — ${reason}${metrics}`);
 		}
 	}
 
@@ -100,14 +116,14 @@ export async function executeLocal(
 	iterations: number | "all",
 	runnerName: string,
 ): Promise<void> {
-	const runner = getRunner(runnerName);
 	const source = new LocalSource(name);
-	const prdIdentifier = slugifyBranchComponent(name) || "spec";
-	const logger = new Logger(prdIdentifier);
+	const logger = new Logger();
+	const runner = getRunner(runnerName, logger);
 
 	const session: Session = { logger, git: defaultGitOps, runner, runnerName };
 
 	try {
+		logger.logFile(`PRD: ${name}`);
 		checkoutOrCreateBranch(branch);
 		console.log("");
 

package/src/logger.ts

@@ -14,10 +14,11 @@ export class Logger implements LogWriter {
 	private warnedRecreated = false;
 	private warnedUnavailable = false;
 
-	constructor(prdIdentifier: string) {
-		const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+	constructor() {
+		const now = new Date();
+		const timestamp = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}T${String(now.getHours()).padStart(2, "0")}-${String(now.getMinutes()).padStart(2, "0")}-${String(now.getSeconds()).padStart(2, "0")}`;
 		const logDir = resolve(".stonecut", "logs");
-		this.filePath = join(logDir, `${prdIdentifier}-${timestamp}.log`);
+		this.filePath = join(logDir, `${timestamp}.log`);
 		try {
 			mkdirSync(logDir, { recursive: true });
 			appendFileSync(this.filePath, "");
@@ -29,6 +30,10 @@ export class Logger implements LogWriter {
 
 	log(message: string): void {
 		console.log(message);
+		this.logFile(message);
+	}
+
+	logFile(message: string): void {
 		const ts = new Date().toISOString();
 		const fileWasMissing = !existsSync(this.filePath);
 		try {

package/src/runner.ts

@@ -39,6 +39,7 @@ export const defaultGitOps: GitOps = {
 /** Console-only logger for backward compatibility. */
 export const consoleLogger: LogWriter = {
 	log: (message: string) => console.log(message),
+	logFile: () => {},
 	close: () => {},
 };
 
@@ -124,7 +125,6 @@ export async function runAfkLoop<T extends { number: number }>(
 	const { logger, git, runner, runnerName } = session;
 
 	logger.log(`Session started — runner: ${runnerName}, iterations: ${iterations}`);
-	runner.logEnvironment(logger);
 	logger.log("");
 	const results: IterationResult[] = [];
 	const sessionStart = performance.now();
@@ -182,6 +182,9 @@ export async function runAfkLoop<T extends { number: number }>(
 				success: false,
 				elapsedSeconds: runResult.durationSeconds,
 				error: runResult.error,
+				turns: runResult.turns,
+				inputTokens: runResult.inputTokens,
+				outputTokens: runResult.outputTokens,
 			});
 
 			if (lastFailedIssueNumber === issue.number) {
@@ -209,6 +212,9 @@ export async function runAfkLoop<T extends { number: number }>(
 				success: false,
 				elapsedSeconds: runResult.durationSeconds,
 				error: errorMsg,
+				turns: runResult.turns,
+				inputTokens: runResult.inputTokens,
+				outputTokens: runResult.outputTokens,
 			});
 
 			if (lastFailedIssueNumber === issue.number) {
@@ -238,6 +244,9 @@ export async function runAfkLoop<T extends { number: number }>(
 				success: false,
 				elapsedSeconds: runResult.durationSeconds,
 				error: "commit failed after retries",
+				turns: runResult.turns,
+				inputTokens: runResult.inputTokens,
+				outputTokens: runResult.outputTokens,
 			});
 			// Commit failures always stop the session immediately
 			logger.log("Stopping session: unable to commit.");
@@ -264,6 +273,9 @@ export async function runAfkLoop<T extends { number: number }>(
 			issueFilename: name,
 			success: true,
 			elapsedSeconds: runResult.durationSeconds,
+			turns: runResult.turns,
+			inputTokens: runResult.inputTokens,
+			outputTokens: runResult.outputTokens,
 		});
 
 		lastFailedIssueNumber = null;
@@ -284,6 +296,19 @@ export async function runAfkLoop<T extends { number: number }>(
 	return results;
 }
 
+/** Format a token count as a human-readable string (e.g., 12400 → "12.4k"). */
+export function formatTokens(count: number): string {
+	if (count >= 1_000_000) {
+		const m = count / 1_000_000;
+		return m % 1 === 0 ? `${m}M` : `${parseFloat(m.toFixed(1))}M`;
+	}
+	if (count >= 1_000) {
+		const k = count / 1_000;
+		return k % 1 === 0 ? `${k}k` : `${parseFloat(k.toFixed(1))}k`;
+	}
+	return `${count}`;
+}
+
 /** Format seconds as a human-readable duration. */
 export function fmtTime(seconds: number): string {
 	if (seconds < 60) {
@@ -311,7 +336,18 @@ export function printSummary(
 	for (const r of results) {
 		const status = r.success ? "completed" : "failed";
 		const elapsed = fmtTime(r.elapsedSeconds);
-		logger.log(`  Issue ${r.issueNumber} (${r.issueFilename}): ${status} (${elapsed})`);
+		const details = [elapsed];
+		if (r.turns != null) {
+			details.push(`${r.turns} turns`);
+		}
+		const totalTokens =
+			r.inputTokens != null || r.outputTokens != null
+				? (r.inputTokens ?? 0) + (r.outputTokens ?? 0)
+				: undefined;
+		if (totalTokens != null) {
+			details.push(`${formatTokens(totalTokens)} tokens`);
+		}
+		logger.log(`  Issue ${r.issueNumber} (${r.issueFilename}): ${status} (${details.join(", ")})`);
 	}
 
 	logger.log("");

package/src/runners/claude.ts

@@ -1,94 +1,241 @@
 /**
- * ClaudeRunner — adapter for Claude Code CLI.
+ * ClaudeRunner — adapter for Claude Code via CLI subprocess.
  *
- * Spawns a headless Claude Code session, parses the JSON output to
- * determine success/failure, and translates error subtypes into
- * human-readable messages.
+ * Spawns `claude --print --output-format stream-json --verbose` and
+ * consumes stdout as newline-delimited JSON. Console gets concise
+ * progress (tool calls, errors); the log file captures the full
+ * event stream for debugging.
  */
 
-import type { LogWriter, Runner, RunResult } from "../types.js";
+import type { ChildResult, LogWriter, Runner, RunResult, SpawnFn } from "../types.js";
+
+const CLI_ARGS = [
+	"claude",
+	"--print",
+	"--output-format",
+	"stream-json",
+	"--verbose",
+	"--allowedTools",
+	"Bash,Edit,Read,Write,Glob,Grep",
+	"--permission-mode",
+	"acceptEdits",
+	"--no-session-persistence",
+];
+
+// ---------------------------------------------------------------------------
+// Subprocess spawning (injectable for tests)
+// ---------------------------------------------------------------------------
+
+async function* readLines(stream: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split("\n");
+			buffer = lines.pop()!;
+			for (const line of lines) {
+				if (line.trim()) yield line;
+			}
+		}
+		if (buffer.trim()) yield buffer;
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+function defaultSpawn(cmd: string[], stdin: string): ChildResult {
+	const proc = Bun.spawn(cmd, {
+		stdin: new Blob([stdin]),
+		stdout: "pipe",
+		stderr: "ignore",
+	});
+	return {
+		lines: readLines(proc.stdout),
+		exitCode: proc.exited,
+	};
+}
+
+let spawnFn: SpawnFn = defaultSpawn;
+
+/** @internal Replace the spawn function. Returns a restore function. */
+export function _setSpawnFn(fn: SpawnFn): () => void {
+	const prev = spawnFn;
+	spawnFn = fn;
+	return () => {
+		spawnFn = prev;
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Error subtype mapping
+// ---------------------------------------------------------------------------
 
 const ERROR_MESSAGES: Record<string, string> = {
 	error_max_turns: "max turns exceeded",
 	error_max_budget_usd: "max budget exceeded",
+	error_during_execution: "execution error",
+	error_max_structured_output_retries: "max structured output retries exceeded",
 };
 
+// ---------------------------------------------------------------------------
+// Runner implementation
+// ---------------------------------------------------------------------------
+
 export class ClaudeRunner implements Runner {
-	logEnvironment(logger: LogWriter): void {
-		const configDir = process.env.CLAUDE_CONFIG_DIR || "~/.claude (default)";
-		logger.log(`Claude config: ${configDir}`);
+	private logger: LogWriter;
+
+	constructor(logger: LogWriter) {
+		this.logger = logger;
 	}
 
 	async run(prompt: string): Promise<RunResult> {
 		const start = performance.now();
+		let child: ChildResult;
 
-		let proc: Awaited<ReturnType<typeof Bun.spawn>>;
 		try {
-			proc = Bun.spawn(
-				[
-					"claude",
-					"-p",
-					"--output-format",
-					"json",
-					"--allowedTools",
-					"Bash,Edit,Read,Write,Glob,Grep",
-				],
-				{ stdin: new Response(prompt), stdout: "pipe", stderr: "pipe" },
-			);
-		} catch {
-			return {
-				success: false,
-				exitCode: 1,
-				durationSeconds: (performance.now() - start) / 1000,
-				error: "claude binary not found in PATH",
-			};
+			child = spawnFn(CLI_ARGS, prompt);
+		} catch (error: unknown) {
+			const durationSeconds = (performance.now() - start) / 1000;
+			const msg = error instanceof Error ? error.message : String(error);
+
+			if (msg.includes("ENOENT") || msg.includes("not found") || msg.includes("spawn")) {
+				return { success: false, durationSeconds, error: "claude binary not found in PATH" };
+			}
+			return { success: false, durationSeconds, error: msg };
 		}
 
-		const exitCode = await proc.exited;
+		let result: Record<string, unknown> | undefined;
+
+		try {
+			for await (const line of child.lines) {
+				let parsed: Record<string, unknown>;
+				try {
+					parsed = JSON.parse(line);
+				} catch {
+					this.logger.logFile(`[claude] Malformed JSON line: ${line}`);
+					continue;
+				}
+
+				this.handleMessage(parsed);
+
+				if (parsed.type === "result") {
+					result = parsed;
+				}
+			}
+		} catch (error: unknown) {
+			const durationSeconds = (performance.now() - start) / 1000;
+			const msg = error instanceof Error ? error.message : String(error);
+			return { success: false, durationSeconds, error: msg };
+		}
+
+		const exitCode = await child.exitCode;
 		const durationSeconds = (performance.now() - start) / 1000;
 
-		const stdout = await new Response(proc.stdout as ReadableStream).text();
-		const output = stdout || undefined;
+		if (exitCode !== 0) {
+			return { success: false, durationSeconds, error: `claude exited with code ${exitCode}` };
+		}
 
-		if (output === undefined) {
-			return {
-				success: false,
-				exitCode,
-				durationSeconds,
-				error: `no output (exit code ${exitCode})`,
-			};
+		if (!result) {
+			return { success: false, durationSeconds, error: "no result message received" };
 		}
 
-		let data: unknown;
-		try {
-			data = JSON.parse(output);
-		} catch {
+		const sessionId = result.session_id as string | undefined;
+		const turns = result.num_turns as number | undefined;
+		const usage = result.usage as { input_tokens?: number; output_tokens?: number } | undefined;
+		const inputTokens = usage?.input_tokens;
+		const outputTokens = usage?.output_tokens;
+
+		this.logger.logFile(
+			`[claude] Result: ${result.subtype}, turns=${turns}, input=${inputTokens}, output=${outputTokens}`,
+		);
+
+		if (result.subtype === "success") {
 			return {
-				success: false,
-				exitCode,
+				success: true,
 				durationSeconds,
-				output,
-				error: "malformed JSON output",
+				output: result.result as string | undefined,
+				turns,
+				inputTokens,
+				outputTokens,
+				sessionId,
 			};
 		}
 
-		if (typeof data !== "object" || data === null || Array.isArray(data)) {
-			return {
-				success: false,
-				exitCode,
-				durationSeconds,
-				output,
-				error: "unexpected JSON output (not an object)",
-			};
+		const subtype = result.subtype as string;
+		const error = ERROR_MESSAGES[subtype] ?? `failed (${subtype})`;
+		const errors = result.errors as string[] | undefined;
+		const detail = errors?.length ? `: ${errors.join("; ")}` : "";
+		return {
+			success: false,
+			durationSeconds,
+			error: error + detail,
+			turns,
+			inputTokens,
+			outputTokens,
+			sessionId,
+		};
+	}
+
+	// -----------------------------------------------------------------------
+	// Message routing
+	// -----------------------------------------------------------------------
+
+	private handleMessage(message: Record<string, unknown>): void {
+		switch (message.type) {
+			case "assistant":
+				this.logAssistant(message);
+				break;
+			case "system":
+			case "user":
+			case "rate_limit_event":
+				this.logger.logFile(`[claude] ${message.type}: ${JSON.stringify(message)}`);
+				break;
+			case "result":
+				break;
+			default:
+				this.logger.logFile(`[claude] ${message.type}: ${JSON.stringify(message)}`);
+				break;
+		}
+	}
+
+	private logAssistant(message: Record<string, unknown>): void {
+		const msgBody = message.message as { content?: unknown[] } | undefined;
+		const content = msgBody?.content;
+
+		if (!Array.isArray(content)) {
+			this.logger.logFile(`[claude] Assistant message: ${JSON.stringify(message)}`);
+			return;
 		}
 
-		const subtype = (data as Record<string, unknown>).subtype ?? "";
-		if (subtype === "success") {
-			return { success: true, exitCode, durationSeconds, output };
+		for (const block of content) {
+			if (typeof block === "string" || block === null || typeof block !== "object") continue;
+			const b = block as Record<string, unknown>;
+			if (b.type === "tool_use") {
+				const target = this.toolTarget(b.name as string, b.input as Record<string, unknown>);
+				this.logger.log(`[claude] ${b.name}${target ? `: ${target}` : ""}`);
+			}
 		}
 
-		const error =
-			ERROR_MESSAGES[subtype as string] ?? `failed (${(subtype as string) || "unknown"})`;
-		return { success: false, exitCode, durationSeconds, output, error };
+		this.logger.logFile(`[claude] Assistant message: ${JSON.stringify(content)}`);
+	}
+
+	private toolTarget(name: string, input: Record<string, unknown>): string | undefined {
+		switch (name) {
+			case "Bash":
+				return typeof input.command === "string" ? input.command.slice(0, 80) : undefined;
+			case "Edit":
+			case "Read":
+			case "Write":
+				return typeof input.file_path === "string" ? input.file_path : undefined;
+			case "Glob":
+			case "Grep":
+				return typeof input.pattern === "string" ? input.pattern : undefined;
+			default:
+				return undefined;
+		}
 	}
 }

package/src/runners/codex.ts

@@ -1,81 +1,223 @@
 /**
- * CodexRunner — adapter for OpenAI Codex CLI.
+ * CodexRunner — adapter for Codex via CLI subprocess.
  *
- * Spawns a headless Codex session in full-auto mode, uses exit code as
- * the primary success signal, and extracts error details from JSONL
- * output on failure.
+ * Spawns `codex exec --json --dangerously-bypass-approvals-and-sandbox` and
+ * consumes stdout as newline-delimited JSON. Console gets concise
+ * progress (tool calls, file changes, turn boundaries, errors); the log
+ * file captures the full event stream for debugging.
  */
 
-import type { LogWriter, Runner, RunResult } from "../types.js";
+import type { ChildResult, LogWriter, Runner, RunResult, SpawnFn } from "../types.js";
 
-function extractError(stdout: string): string {
-	for (const raw of stdout.split("\n")) {
-		const line = raw.trim();
-		if (!line) continue;
+const CLI_ARGS = ["codex", "exec", "--json", "--dangerously-bypass-approvals-and-sandbox"];
 
-		let event: unknown;
-		try {
-			event = JSON.parse(line);
-		} catch {
-			continue;
-		}
-
-		if (typeof event !== "object" || event === null || Array.isArray(event)) {
-			continue;
-		}
-
-		const rec = event as Record<string, unknown>;
-		const eventType = rec.type;
+// ---------------------------------------------------------------------------
+// Subprocess spawning (injectable for tests)
+// ---------------------------------------------------------------------------
 
-		if (eventType === "turn.failed") {
-			const nested = rec.error;
-			if (typeof nested === "object" && nested !== null && !Array.isArray(nested)) {
-				const msg = (nested as Record<string, unknown>).message;
-				if (typeof msg === "string" && msg) return msg;
+async function* readLines(stream: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split("\n");
+			buffer = lines.pop()!;
+			for (const line of lines) {
+				if (line.trim()) yield line;
 			}
-		} else if (eventType === "error") {
-			const msg = rec.message;
-			if (typeof msg === "string" && msg) return msg;
 		}
+		if (buffer.trim()) yield buffer;
+	} finally {
+		reader.releaseLock();
 	}
+}
+
+function defaultSpawn(cmd: string[], stdin: string): ChildResult {
+	const proc = Bun.spawn(cmd, {
+		stdin: new Blob([stdin]),
+		stdout: "pipe",
+		stderr: "ignore",
+	});
+	return {
+		lines: readLines(proc.stdout),
+		exitCode: proc.exited,
+	};
+}
+
+let spawnFn: SpawnFn = defaultSpawn;
 
-	return "codex exited with non-zero status";
+/** @internal Replace the spawn function. Returns a restore function. */
+export function _setSpawnFn(fn: SpawnFn): () => void {
+	const prev = spawnFn;
+	spawnFn = fn;
+	return () => {
+		spawnFn = prev;
+	};
 }
 
+// ---------------------------------------------------------------------------
+// Runner implementation
+// ---------------------------------------------------------------------------
+
 export class CodexRunner implements Runner {
-	logEnvironment(_logger: LogWriter): void {
-		// No environment-specific config to log for Codex.
+	private logger: LogWriter;
+
+	constructor(logger: LogWriter) {
+		this.logger = logger;
 	}
 
 	async run(prompt: string): Promise<RunResult> {
 		const start = performance.now();
+		let child: ChildResult;
+
+		try {
+			child = spawnFn(CLI_ARGS, prompt);
+		} catch (error: unknown) {
+			const durationSeconds = (performance.now() - start) / 1000;
+			const msg = error instanceof Error ? error.message : String(error);
+
+			if (msg.includes("ENOENT") || (error as NodeJS.ErrnoException)?.code === "ENOENT") {
+				return { success: false, durationSeconds, error: "codex binary not found in PATH" };
+			}
+			return { success: false, durationSeconds, error: msg };
+		}
+
+		let threadId: string | undefined;
+		let turns = 0;
+		let inputTokens = 0;
+		let outputTokens = 0;
+		let failed = false;
+		let completed = false;
+		let errorMessage: string | undefined;
 
-		let proc: Awaited<ReturnType<typeof Bun.spawn>>;
 		try {
-			proc = Bun.spawn(["codex", "exec", "--full-auto", "--json", "--ephemeral", "-"], {
-				stdin: new Response(prompt),
-				stdout: "pipe",
-				stderr: "pipe",
-			});
-		} catch {
+			for await (const line of child.lines) {
+				let parsed: Record<string, unknown>;
+				try {
+					parsed = JSON.parse(line);
+				} catch {
+					this.logger.logFile(`[codex] Malformed JSON line: ${line}`);
+					continue;
+				}
+
+				this.logger.logFile(`[codex] ${parsed.type}: ${JSON.stringify(parsed)}`);
+
+				switch (parsed.type) {
+					case "thread.started":
+						threadId = parsed.thread_id as string;
+						break;
+					case "turn.started":
+						turns++;
+						completed = false;
+						break;
+					case "turn.completed":
+						completed = true;
+						this.logger.log(`[codex] Turn ${turns} completed`);
+						{
+							const usage = parsed.usage as
+								| { input_tokens?: number; output_tokens?: number }
+								| undefined;
+							inputTokens += usage?.input_tokens ?? 0;
+							outputTokens += usage?.output_tokens ?? 0;
+						}
+						break;
+					case "turn.failed":
+						failed = true;
+						{
+							const err = parsed.error as { message?: string } | undefined;
+							errorMessage = err?.message ?? "codex turn failed";
+						}
+						this.logger.log(`[codex] Error: ${errorMessage}`);
+						break;
+					case "error":
+						failed = true;
+						errorMessage = parsed.message as string;
+						this.logger.log(`[codex] Error: ${errorMessage}`);
+						break;
+					case "item.started":
+					case "item.completed":
+						this.logItem(parsed.type, parsed.item as Record<string, unknown>);
+						break;
+				}
+			}
+		} catch (error: unknown) {
+			const durationSeconds = (performance.now() - start) / 1000;
+			const msg = error instanceof Error ? error.message : String(error);
+			return { success: false, durationSeconds, error: msg };
+		}
+
+		const exitCode = await child.exitCode;
+		const durationSeconds = (performance.now() - start) / 1000;
+
+		if (exitCode !== 0) {
+			return { success: false, durationSeconds, error: `codex exited with code ${exitCode}` };
+		}
+
+		const status = failed ? "failed" : completed ? "success" : "incomplete";
+		this.logger.logFile(
+			`[codex] Result: ${status}, turns=${turns}, input=${inputTokens}, output=${outputTokens}`,
+		);
+
+		if (failed) {
 			return {
 				success: false,
-				exitCode: 1,
-				durationSeconds: (performance.now() - start) / 1000,
-				error: "codex binary not found in PATH",
+				durationSeconds,
+				error: errorMessage ?? "codex run failed",
+				turns,
+				inputTokens,
+				outputTokens,
+				sessionId: threadId,
 			};
 		}
 
-		const exitCode = await proc.exited;
-		const durationSeconds = (performance.now() - start) / 1000;
-
-		if (exitCode === 0) {
-			return { success: true, exitCode: 0, durationSeconds };
+		if (!completed) {
+			return {
+				success: false,
+				durationSeconds,
+				error: "no terminal event received from Codex",
+				turns,
+				inputTokens,
+				outputTokens,
+				sessionId: threadId,
+			};
 		}
 
-		const stdout = await new Response(proc.stdout as ReadableStream).text();
-		const error = extractError(stdout);
+		return {
+			success: true,
+			durationSeconds,
+			turns,
+			inputTokens,
+			outputTokens,
+			sessionId: threadId,
+		};
+	}
 
-		return { success: false, exitCode, durationSeconds, error };
+	private logItem(phase: string, item: Record<string, unknown>): void {
+		switch (item.type) {
+			case "command_execution":
+				if (phase === "item.started" && typeof item.command === "string") {
+					this.logger.log(`[codex] Bash: ${item.command.slice(0, 80)}`);
+				}
+				break;
+			case "file_change":
+				if (phase === "item.completed" && Array.isArray(item.changes)) {
+					for (const change of item.changes) {
+						if (typeof change?.path === "string") {
+							this.logger.log(`[codex] Edit: ${change.path}`);
+						}
+					}
+				}
+				break;
+			case "reasoning":
+				this.logger.logFile(`[codex] reasoning: ${item.text}`);
+				break;
+			case "error":
+				this.logger.log(`[codex] Error: ${item.message}`);
+				break;
+		}
 	}
 }

package/src/runners/index.ts

@@ -2,20 +2,20 @@
  * Runner registry — maps runner names to their implementations.
  */
 
-import type { Runner } from "../types.js";
+import type { LogWriter, Runner } from "../types.js";
 import { ClaudeRunner } from "./claude.js";
 import { CodexRunner } from "./codex.js";
 
-const RUNNERS: Record<string, new () => Runner> = {
+const RUNNERS: Record<string, new (logger: LogWriter) => Runner> = {
 	claude: ClaudeRunner,
 	codex: CodexRunner,
 };
 
-export function getRunner(name: string): Runner {
+export function getRunner(name: string, logger: LogWriter): Runner {
 	const Cls = RUNNERS[name];
 	if (!Cls) {
 		const available = Object.keys(RUNNERS).sort().join(", ");
 		throw new Error(`Unknown runner '${name}'. Available runners: ${available}`);
 	}
-	return new Cls();
+	return new Cls(logger);
 }

package/src/skills/stonecut-prd/SKILL.md

@@ -29,7 +29,7 @@ Check with the user that these modules match their expectations. Ask which modul
 
 Ask the user where to save the PRD:
 
-- **Local file** — Save as `.stonecut/specs/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID (e.g., `ASC-1`), a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/specs/<name>/` directory if it doesn't exist.
+- **Local file** — Save as `.stonecut/specs/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID, a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/specs/<name>/` directory if it doesn't exist.
 - **GitHub issue** — Create a GitHub issue using `gh issue create --label prd`. Before creating, ensure the `prd` label exists:
 
   ```bash
@@ -39,8 +39,6 @@ Ask the user where to save the PRD:
   fi
   ```
 
-If the project already has a `.stonecut/` directory, default to suggesting local. Otherwise, just ask.
-
 ### 6. Documentation impact check
 
 Before writing the PRD, ensure that documentation impact has been explicitly addressed. Based on everything you've learned from the interview and codebase exploration, analyze which user-facing documentation artifacts (README, CLI help text, docs/ content) would be affected by these changes.

package/src/types.ts

@@ -2,13 +2,25 @@
  * Core types and interfaces shared across the Stonecut CLI.
  */
 
+/** Return type from SpawnFn — stdout line stream and process exit code. */
+export interface ChildResult {
+	lines: AsyncIterable<string>;
+	exitCode: Promise<number>;
+}
+
+/** Injectable subprocess factory for runner testing. */
+export type SpawnFn = (cmd: string[], stdin: string) => ChildResult;
+
 /** Structured result from a single runner execution. */
 export interface RunResult {
 	success: boolean;
-	exitCode: number;
 	durationSeconds: number;
 	output?: string;
 	error?: string;
+	turns?: number;
+	inputTokens?: number;
+	outputTokens?: number;
+	sessionId?: string;
 }
 
 /** Result of a single afk iteration. */
@@ -18,12 +30,14 @@ export interface IterationResult {
 	success: boolean;
 	elapsedSeconds: number;
 	error?: string;
+	turns?: number;
+	inputTokens?: number;
+	outputTokens?: number;
 }
 
 /** Protocol that all runner adapters must satisfy. */
 export interface Runner {
 	run(prompt: string): Promise<RunResult>;
-	logEnvironment(logger: LogWriter): void;
 }
 
 /** Snapshot of the working tree state before a runner session. */
@@ -58,6 +72,8 @@ export interface Source<T> {
 /** Logger interface for session-scoped logging. */
 export interface LogWriter {
 	log(message: string): void;
+	/** Write a message only to the log file (not console). */
+	logFile(message: string): void;
 	close(): void;
 }