gnhf 0.1.12 → 0.1.14

package/README.md

@@ -192,11 +192,9 @@ When sleep prevention is enabled, `gnhf` uses the native mechanism for your OS:
 
 ## Debug Logs
 
-Set `GNHF_DEBUG_LOG_PATH` to capture lifecycle events as JSONL while debugging a run:
+Every run writes a JSONL debug log to `.gnhf/runs/<runId>/gnhf.log` alongside `notes.md`. Lifecycle events for the orchestrator, agent, and HTTP requests are captured with elapsed timings and (for failures) the full `error.cause` chain — which is what you need to tell a bare `TypeError: fetch failed` apart from an undici `UND_ERR_HEADERS_TIMEOUT`. The agent's own streaming output still goes to the per-iteration `iteration-<n>.jsonl` file next to it.
 
-```sh
-GNHF_DEBUG_LOG_PATH=/tmp/gnhf-debug.jsonl gnhf "ship it"
-```
+Including a snippet of `gnhf.log` is the single most useful thing you can attach when filing an issue.
 
 ## Agents
 

package/dist/cli.mjs

@@ -135,18 +135,111 @@ function loadConfig(overrides) {
 }
 //#endregion
 //#region src/core/debug-log.ts
-function appendDebugLog(event, details = {}) {
-	const logPath = process.env.GNHF_DEBUG_LOG_PATH;
-	if (!logPath) return;
+const PRE_INIT_BUFFER_CAPACITY = 1e3;
+const STACK_LINE_LIMIT = 12;
+const CAUSE_DEPTH_LIMIT = 6;
+let logPath = null;
+let preInitBuffer = [];
+let preInitDroppedCount = 0;
+function formatLine(event, details) {
+	const base = {
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		pid: process.pid,
+		event
+	};
 	try {
-		appendFileSync(logPath, `${JSON.stringify({
-			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-			pid: process.pid,
-			event,
+		return `${JSON.stringify({
+			...base,
 			...details
-		})}\n`, "utf-8");
+		})}\n`;
+	} catch (error) {
+		return `${JSON.stringify({
+			...base,
+			logError: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+			detailsKeys: Object.keys(details)
+		})}\n`;
+	}
+}
+function initDebugLog(path) {
+	logPath = path;
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+	} catch {}
+	if (preInitBuffer.length === 0 && preInitDroppedCount === 0) return;
+	const flushed = (preInitDroppedCount > 0 ? formatLine("debug-log:pre-init-overflow", {
+		droppedCount: preInitDroppedCount,
+		bufferCapacity: PRE_INIT_BUFFER_CAPACITY
+	}) : "") + preInitBuffer.join("");
+	preInitBuffer = [];
+	preInitDroppedCount = 0;
+	try {
+		appendFileSync(path, flushed, "utf-8");
+	} catch {}
+}
+function appendDebugLog(event, details = {}) {
+	const line = formatLine(event, details);
+	if (logPath === null) {
+		preInitBuffer.push(line);
+		if (preInitBuffer.length > PRE_INIT_BUFFER_CAPACITY) {
+			preInitBuffer.shift();
+			preInitDroppedCount += 1;
+		}
+		return;
+	}
+	try {
+		appendFileSync(logPath, line, "utf-8");
 	} catch {}
 }
+/**
+* Serialize an error (including its cause chain) to a plain object that's
+* safe to embed in a JSONL log line. This is critical for diagnosing
+* fetch failures, where the surface message is often just "fetch failed"
+* but `err.cause` holds the real undici error (e.g. UND_ERR_HEADERS_TIMEOUT).
+*
+* Contract: must never throw. Callers invoke this inside catch blocks and
+* timer/EventEmitter handlers, and a throw here would mask the original
+* error or crash the process.
+*/
+function serializeError(error, depth = 0) {
+	try {
+		return serializeErrorUnsafe(error, depth);
+	} catch (serializationError) {
+		return {
+			value: "[serialization failed]",
+			serializationError: serializationError instanceof Error ? `${serializationError.name}: ${serializationError.message}` : String(serializationError)
+		};
+	}
+}
+function tryRead(read) {
+	try {
+		return read();
+	} catch {
+		return;
+	}
+}
+function serializeErrorUnsafe(error, depth) {
+	if (depth > CAUSE_DEPTH_LIMIT) return { value: "[cause chain truncated]" };
+	if (error instanceof Error) {
+		const result = {
+			name: tryRead(() => error.name) ?? "Error",
+			message: tryRead(() => error.message) ?? ""
+		};
+		const code = tryRead(() => error.code);
+		if (typeof code === "string" || typeof code === "number") result.code = code;
+		const stack = tryRead(() => error.stack);
+		if (typeof stack === "string") result.stack = stack.split("\n").slice(0, STACK_LINE_LIMIT).join("\n");
+		const cause = tryRead(() => "cause" in error ? error.cause : void 0);
+		if (cause !== void 0) result.cause = serializeError(cause, depth + 1);
+		return result;
+	}
+	if (error === null || error === void 0) return { value: String(error) };
+	if (typeof error === "object") try {
+		return { value: JSON.parse(JSON.stringify(error)) };
+	} catch {
+		return { value: String(error) };
+	}
+	return { value: String(error) };
+}
 //#endregion
 //#region src/core/git.ts
 const NOT_GIT_REPOSITORY_MESSAGE = "This command must be run inside a Git repository. Change into a repo or run \"git init\" first.";
@@ -255,6 +348,7 @@ const AGENT_OUTPUT_SCHEMA = {
 };
 //#endregion
 //#region src/core/run.ts
+const LOG_FILENAME = "gnhf.log";
 function writeSchemaFile(schemaPath) {
 	writeFileSync(schemaPath, JSON.stringify(AGENT_OUTPUT_SCHEMA, null, 2), "utf-8");
 }
@@ -286,6 +380,7 @@ function setupRun(runId, prompt, baseCommit, cwd) {
 	writeFileSync(notesPath, `# gnhf run: ${runId}\n\nObjective: ${prompt}\n\n## Iteration Log\n`, "utf-8");
 	const schemaPath = join(runDir, "output-schema.json");
 	writeSchemaFile(schemaPath);
+	const logPath = join(runDir, LOG_FILENAME);
 	const baseCommitPath = join(runDir, "base-commit");
 	const hasStoredBaseCommit = existsSync(baseCommitPath);
 	const resolvedBaseCommit = hasStoredBaseCommit ? readFileSync(baseCommitPath, "utf-8").trim() : baseCommit;
@@ -296,6 +391,7 @@ function setupRun(runId, prompt, baseCommit, cwd) {
 		promptPath,
 		notesPath,
 		schemaPath,
+		logPath,
 		baseCommit: resolvedBaseCommit,
 		baseCommitPath
 	};
@@ -307,6 +403,7 @@ function resumeRun(runId, cwd) {
 	const notesPath = join(runDir, "notes.md");
 	const schemaPath = join(runDir, "output-schema.json");
 	writeSchemaFile(schemaPath);
+	const logPath = join(runDir, LOG_FILENAME);
 	const baseCommitPath = join(runDir, "base-commit");
 	return {
 		runId,
@@ -314,6 +411,7 @@ function resumeRun(runId, cwd) {
 		promptPath,
 		notesPath,
 		schemaPath,
+		logPath,
 		baseCommit: existsSync(baseCommitPath) ? readFileSync(baseCommitPath, "utf-8").trim() : backfillLegacyBaseCommit(runId, baseCommitPath, cwd),
 		baseCommitPath
 	};
@@ -1179,20 +1277,48 @@ var OpenCodeAgent = class {
 		const logStream = logPath ? createWriteStream(logPath) : null;
 		const runController = new AbortController();
 		let sessionId = null;
+		const runStartedAt = Date.now();
+		appendDebugLog("opencode:run:start", {
+			cwd,
+			promptLength: prompt.length,
+			hasLogPath: logPath !== void 0
+		});
 		const onAbort = () => {
 			runController.abort();
 		};
 		if (signal?.aborted) {
 			logStream?.end();
+			appendDebugLog("opencode:run:aborted-early", {});
 			throw createAbortError$1();
 		}
 		signal?.addEventListener("abort", onAbort, { once: true });
 		try {
 			const server = await this.ensureServer(cwd, runController.signal);
 			sessionId = await this.createSession(server, cwd, runController.signal);
-			return await this.streamMessage(server, sessionId, buildPrompt(prompt), runController.signal, logStream, onUsage, onMessage);
+			const result = await this.streamMessage(server, sessionId, buildPrompt(prompt), runController.signal, logStream, onUsage, onMessage);
+			appendDebugLog("opencode:run:end", {
+				sessionId,
+				elapsedMs: Date.now() - runStartedAt,
+				inputTokens: result.usage.inputTokens,
+				outputTokens: result.usage.outputTokens
+			});
+			return result;
 		} catch (error) {
-			if (runController.signal.aborted || isAbortError$1(error)) throw createAbortError$1();
+			if (runController.signal.aborted || isAbortError$1(error)) {
+				appendDebugLog("opencode:run:aborted", {
+					sessionId,
+					elapsedMs: Date.now() - runStartedAt
+				});
+				throw createAbortError$1();
+			}
+			appendDebugLog("opencode:run:error", {
+				sessionId,
+				elapsedMs: Date.now() - runStartedAt,
+				error: serializeError(error),
+				serverStderr: this.server?.stderr.slice(-2048),
+				serverStdout: this.server?.stdout.slice(-2048),
+				serverClosed: this.server?.closed ?? true
+			});
 			throw error;
 		} finally {
 			signal?.removeEventListener("abort", onAbort);
@@ -1249,25 +1375,82 @@ var OpenCodeAgent = class {
 			stdout: ""
 		};
 		const maxOutput = 64 * 1024;
+		const maxMirroredLineLength = 2048;
+		const maxMirroredLinesPerRun = 500;
+		let mirroredLineCount = 0;
+		let mirroredSuppressionLogged = false;
+		const stderrLineBuffer = { tail: "" };
+		const mirrorStderrChunk = (chunk) => {
+			stderrLineBuffer.tail += chunk;
+			let newlineIndex = stderrLineBuffer.tail.indexOf("\n");
+			while (newlineIndex !== -1) {
+				const rawLine = stderrLineBuffer.tail.slice(0, newlineIndex);
+				stderrLineBuffer.tail = stderrLineBuffer.tail.slice(newlineIndex + 1);
+				const line = rawLine.replace(/\r$/, "");
+				if (line.length > 0) if (mirroredLineCount >= maxMirroredLinesPerRun) {
+					if (!mirroredSuppressionLogged) {
+						appendDebugLog("opencode:server:stderr:suppressed", {
+							port: server.port,
+							cap: maxMirroredLinesPerRun
+						});
+						mirroredSuppressionLogged = true;
+					}
+				} else {
+					mirroredLineCount += 1;
+					appendDebugLog("opencode:server:stderr", {
+						port: server.port,
+						line: line.length > maxMirroredLineLength ? `${line.slice(0, maxMirroredLineLength)}…` : line,
+						truncated: line.length > maxMirroredLineLength
+					});
+				}
+				newlineIndex = stderrLineBuffer.tail.indexOf("\n");
+			}
+		};
 		child.stdout.on("data", (data) => {
 			server.stdout += data.toString();
 			if (server.stdout.length > maxOutput) server.stdout = server.stdout.slice(-maxOutput);
 		});
 		child.stderr.on("data", (data) => {
-			server.stderr += data.toString();
+			const text = data.toString();
+			server.stderr += text;
 			if (server.stderr.length > maxOutput) server.stderr = server.stderr.slice(-maxOutput);
+			mirrorStderrChunk(text);
 		});
-		child.on("close", () => {
+		child.on("close", (code, closeSignal) => {
 			server.closed = true;
+			if (stderrLineBuffer.tail.length > 0) mirrorStderrChunk("\n");
+			appendDebugLog("opencode:server:close", {
+				cwd: server.cwd,
+				port: server.port,
+				code,
+				signal: closeSignal,
+				stderr: server.stderr.slice(-2048),
+				stdout: server.stdout.slice(-2048)
+			});
 			if (this.server === server) this.server = null;
 		});
 		this.server = server;
+		const spawnedAt = Date.now();
 		appendDebugLog("opencode:spawn", {
 			cwd,
 			port,
-			detached
+			detached,
+			pid: child.pid,
+			bin: this.bin
 		});
-		server.readyPromise = this.waitForHealthy(server, signal).catch(async (error) => {
+		server.readyPromise = this.waitForHealthy(server, signal).then(() => {
+			appendDebugLog("opencode:server:ready", {
+				port,
+				elapsedMs: Date.now() - spawnedAt
+			});
+		}).catch(async (error) => {
+			appendDebugLog("opencode:server:ready-failed", {
+				port,
+				elapsedMs: Date.now() - spawnedAt,
+				error: serializeError(error),
+				stderr: server.stderr.slice(-2048),
+				stdout: server.stdout.slice(-2048)
+			});
 			await this.shutdownServer();
 			throw error;
 		});
@@ -1300,44 +1483,69 @@ var OpenCodeAgent = class {
 		throw new Error(`Timed out waiting for opencode serve to become ready on port ${server.port}`);
 	}
 	async createSession(server, cwd, signal) {
-		return (await this.requestJSON(server, "/session", {
+		const response = await this.requestJSON(server, "/session", {
 			method: "POST",
 			body: {
 				directory: cwd,
 				permission: BLANKET_PERMISSION_RULESET
 			},
 			signal
-		})).id;
+		});
+		appendDebugLog("opencode:session:create", { sessionId: response.id });
+		return response.id;
 	}
 	async streamMessage(server, sessionId, prompt, signal, logStream, onUsage, onMessage) {
 		const streamAbortController = new AbortController();
 		const streamSignal = AbortSignal.any([signal, streamAbortController.signal]);
+		const streamStartedAt = Date.now();
+		appendDebugLog("opencode:stream:start", { sessionId });
 		const eventResponse = await this.request(server, "/global/event", {
 			method: "GET",
 			headers: { accept: "text/event-stream" },
 			signal: streamSignal
 		});
-		if (!eventResponse.body) throw new Error("opencode returned no event stream body");
+		if (!eventResponse.body) {
+			appendDebugLog("opencode:stream:no-body", { sessionId });
+			throw new Error("opencode returned no event stream body");
+		}
+		const messagePostStartedAt = Date.now();
+		appendDebugLog("opencode:message-post:start", {
+			sessionId,
+			promptLength: prompt.length
+		});
 		let messageRequestError = null;
 		const messageRequest = (async () => {
 			try {
+				await this.request(server, `/session/${sessionId}/prompt_async`, {
+					method: "POST",
+					body: {
+						role: "user",
+						parts: [{
+							type: "text",
+							text: prompt
+						}],
+						format: STRUCTURED_OUTPUT_FORMAT
+					},
+					signal
+				});
+				appendDebugLog("opencode:message-post:end", {
+					sessionId,
+					elapsedMs: Date.now() - messagePostStartedAt
+				});
 				return {
 					ok: true,
-					body: await this.requestText(server, `/session/${sessionId}/message`, {
-						method: "POST",
-						body: {
-							role: "user",
-							parts: [{
-								type: "text",
-								text: prompt
-							}],
-							format: STRUCTURED_OUTPUT_FORMAT
-						},
-						signal
-					})
+					body: ""
 				};
 			} catch (error) {
 				messageRequestError = error;
+				appendDebugLog("opencode:message-post:error", {
+					sessionId,
+					elapsedMs: Date.now() - messagePostStartedAt,
+					error: serializeError(error),
+					serverClosed: server.closed,
+					serverStderr: server.stderr.slice(-2048),
+					streamTelemetry: buildTelemetry()
+				});
 				streamAbortController.abort();
 				return {
 					ok: false,
@@ -1356,6 +1564,67 @@ var OpenCodeAgent = class {
 		let lastText = null;
 		let lastFinalAnswerText = null;
 		let lastUsageSignature = "0:0:0:0";
+		let structuredOutputFromSSE = null;
+		const eventCounts = {};
+		let firstEventAtMs = null;
+		let lastEventAtMs = null;
+		let lastHeartbeatAtMs = null;
+		const phaseTransitions = [];
+		let currentPhase = null;
+		const noteEvent = (type) => {
+			const key = type ?? "unknown";
+			eventCounts[key] = (eventCounts[key] ?? 0) + 1;
+			const nowMs = Date.now() - streamStartedAt;
+			if (type === "server.heartbeat") {
+				lastHeartbeatAtMs = nowMs;
+				return;
+			}
+			if (firstEventAtMs === null) firstEventAtMs = nowMs;
+			lastEventAtMs = nowMs;
+		};
+		const notePhase = (phase) => {
+			if (!phase || phase === currentPhase) return;
+			currentPhase = phase;
+			phaseTransitions.push({
+				phase,
+				atMs: Date.now() - streamStartedAt
+			});
+		};
+		const buildTelemetry = () => ({
+			eventCounts: { ...eventCounts },
+			firstEventAtMs,
+			lastEventAtMs,
+			lastHeartbeatAtMs,
+			msSinceLastEvent: lastEventAtMs === null ? null : Date.now() - streamStartedAt - lastEventAtMs,
+			phaseTransitions: [...phaseTransitions],
+			currentPhase,
+			sawSessionIdle: (eventCounts["session.idle"] ?? 0) > 0
+		});
+		const STALL_THRESHOLDS_MS = [
+			6e4,
+			12e4,
+			24e4,
+			48e4
+		];
+		let nextStallThresholdIndex = 0;
+		const stallTimer = setInterval(() => {
+			if (nextStallThresholdIndex >= STALL_THRESHOLDS_MS.length) return;
+			const threshold = STALL_THRESHOLDS_MS[nextStallThresholdIndex];
+			const referencePointMs = lastEventAtMs ?? firstEventAtMs ?? 0;
+			const silenceMs = Date.now() - streamStartedAt - referencePointMs;
+			if (silenceMs < threshold) return;
+			nextStallThresholdIndex += 1;
+			appendDebugLog("opencode:stream:stall", {
+				sessionId,
+				thresholdMs: threshold,
+				silenceMs,
+				currentPhase,
+				lastEventAtMs,
+				lastHeartbeatAtMs,
+				eventCounts: { ...eventCounts }
+			});
+		}, 15e3);
+		stallTimer.unref?.();
 		const updateUsage = (messageId, tokens) => {
 			if (!messageId || !tokens) return;
 			usageByMessageId.set(messageId, toUsage(tokens));
@@ -1390,6 +1659,7 @@ var OpenCodeAgent = class {
 				text: nextText,
 				phase
 			});
+			notePhase(phase);
 			if (!trimmed) return;
 			lastText = nextText;
 			if (phase === "final_answer") lastFinalAnswerText = nextText;
@@ -1419,6 +1689,7 @@ var OpenCodeAgent = class {
 			}
 			if (payload?.type === "message.updated") {
 				if (properties.info?.role === "assistant") updateUsage(properties.info.id, properties.info.tokens);
+				if (properties.info?.structured) structuredOutputFromSSE = properties.info.structured;
 				return false;
 			}
 			return payload?.type === "session.idle";
@@ -1432,7 +1703,9 @@ var OpenCodeAgent = class {
 			const dataLines = rawEvent.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart());
 			if (dataLines.length === 0) return;
 			try {
-				if (handleEvent(JSON.parse(dataLines.join("\n")))) sawSessionIdle = true;
+				const event = JSON.parse(dataLines.join("\n"));
+				noteEvent(event.payload?.type);
+				if (handleEvent(event)) sawSessionIdle = true;
 			} catch {}
 		};
 		const processBufferedEvents = (flushRemainder = false) => {
@@ -1458,6 +1731,7 @@ var OpenCodeAgent = class {
 				buffer = "";
 			}
 		};
+		let bytesRead = 0;
 		try {
 			while (!sawSessionIdle) {
 				let readResult;
@@ -1465,9 +1739,27 @@ var OpenCodeAgent = class {
 					readResult = await reader.read();
 				} catch (error) {
 					if (messageRequestError) {
+						appendDebugLog("opencode:stream:error", {
+							sessionId,
+							elapsedMs: Date.now() - streamStartedAt,
+							bytesRead,
+							reason: "message-post-failed",
+							error: serializeError(messageRequestError),
+							telemetry: buildTelemetry()
+						});
 						if (isAbortError$1(messageRequestError) || isAgentAbortError(messageRequestError)) throw createAbortError$1();
 						throw messageRequestError;
 					}
+					appendDebugLog("opencode:stream:error", {
+						sessionId,
+						elapsedMs: Date.now() - streamStartedAt,
+						bytesRead,
+						reason: "reader-read-failed",
+						error: serializeError(error),
+						serverClosed: server.closed,
+						serverStderr: server.stderr.slice(-2048),
+						telemetry: buildTelemetry()
+					});
 					if (isAbortError$1(error)) throw createAbortError$1();
 					throw error;
 				}
@@ -1476,6 +1768,7 @@ var OpenCodeAgent = class {
 					if (tail) {
 						logStream?.write(tail);
 						buffer += tail;
+						bytesRead += tail.length;
 					}
 					processBufferedEvents(true);
 					break;
@@ -1483,43 +1776,73 @@ var OpenCodeAgent = class {
 				const chunk = decoder.decode(readResult.value, { stream: true });
 				logStream?.write(chunk);
 				buffer += chunk;
+				bytesRead += chunk.length;
 				processBufferedEvents();
 			}
 		} finally {
+			clearInterval(stallTimer);
 			streamAbortController.abort();
 			await reader.cancel().catch(() => void 0);
 		}
+		appendDebugLog("opencode:stream:end", {
+			sessionId,
+			elapsedMs: Date.now() - streamStartedAt,
+			bytesRead,
+			sawSessionIdle,
+			telemetry: buildTelemetry()
+		});
 		const messageResult = await messageRequest;
 		if (!messageResult.ok) {
 			if (isAbortError$1(messageResult.error) || isAgentAbortError(messageResult.error)) throw createAbortError$1();
 			throw messageResult.error;
 		}
 		const body = messageResult.body;
-		let response;
-		try {
-			response = JSON.parse(body);
+		if (body) try {
+			JSON.parse(body);
 		} catch (error) {
-			throw new Error(`Failed to parse opencode response: ${error instanceof Error ? error.message : String(error)}`);
-		}
-		if (response.info?.role === "assistant") updateUsage(response.info.id, response.info.tokens);
-		for (const part of response.parts ?? []) {
-			if (part.type !== "text" || typeof part.text !== "string") continue;
-			if (!part.text.trim()) continue;
-			lastText = part.text;
-			if (part.metadata?.openai?.phase === "final_answer") lastFinalAnswerText = part.text;
-		}
-		if (response.info?.structured) return {
-			output: response.info.structured,
-			usage
-		};
+			appendDebugLog("opencode:response:parse-error", {
+				sessionId,
+				bodyLength: body.length,
+				bodySample: body.slice(0, 512),
+				error: serializeError(error)
+			});
+		}
+		if (structuredOutputFromSSE) {
+			appendDebugLog("opencode:output:structured", {
+				sessionId,
+				source: "sse"
+			});
+			return {
+				output: structuredOutputFromSSE,
+				usage
+			};
+		}
 		const outputText = lastFinalAnswerText ?? lastText;
-		if (!outputText) throw new Error("opencode returned no text output");
+		if (!outputText) {
+			appendDebugLog("opencode:output:missing", {
+				sessionId,
+				hasStructuredOutput: structuredOutputFromSSE !== null
+			});
+			throw new Error("opencode returned no text output");
+		}
 		try {
+			const output = JSON.parse(outputText);
+			appendDebugLog("opencode:output:structured", {
+				sessionId,
+				source: lastFinalAnswerText ? "final_answer" : "last_text",
+				outputTextLength: outputText.length
+			});
 			return {
-				output: JSON.parse(outputText),
+				output,
 				usage
 			};
 		} catch (error) {
+			appendDebugLog("opencode:output:parse-error", {
+				sessionId,
+				outputTextLength: outputText.length,
+				outputTextSample: outputText.slice(0, 512),
+				error: serializeError(error)
+			});
 			throw new Error(`Failed to parse opencode output: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	}
@@ -1529,7 +1852,13 @@ var OpenCodeAgent = class {
 				method: "DELETE",
 				timeoutMs: 1e3
 			});
-		} catch {}
+			appendDebugLog("opencode:session:delete", { sessionId });
+		} catch (error) {
+			appendDebugLog("opencode:session:delete-failed", {
+				sessionId,
+				error: serializeError(error)
+			});
+		}
 	}
 	async abortSession(server, sessionId) {
 		try {
@@ -1537,7 +1866,13 @@ var OpenCodeAgent = class {
 				method: "POST",
 				timeoutMs: 1e3
 			});
-		} catch {}
+			appendDebugLog("opencode:session:abort", { sessionId });
+		} catch (error) {
+			appendDebugLog("opencode:session:abort-failed", {
+				sessionId,
+				error: serializeError(error)
+			});
+		}
 	}
 	async shutdownServer() {
 		if (!this.server || this.server.closed) {
@@ -1549,9 +1884,11 @@ var OpenCodeAgent = class {
 			return;
 		}
 		const server = this.server;
+		const shutdownStartedAt = Date.now();
 		appendDebugLog("opencode:shutdown", {
 			cwd: server.cwd,
-			port: server.port
+			port: server.port,
+			pid: server.child.pid
 		});
 		this.closingPromise = (this.platform === "win32" && server.child.pid ? killWindowsProcessTree(server.child.pid) : shutdownChildProcess(server.child, {
 			detached: server.detached,
@@ -1560,6 +1897,10 @@ var OpenCodeAgent = class {
 		})).finally(() => {
 			if (this.server === server) this.server = null;
 			this.closingPromise = null;
+			appendDebugLog("opencode:shutdown:done", {
+				port: server.port,
+				elapsedMs: Date.now() - shutdownStartedAt
+			});
 		});
 		await this.closingPromise;
 	}
@@ -1574,14 +1915,35 @@ var OpenCodeAgent = class {
 		const headers = new Headers(options.headers);
 		if (options.body !== void 0) headers.set("content-type", "application/json");
 		const signal = withTimeoutSignal$1(options.signal, options.timeoutMs);
-		const response = await this.fetchFn(`${server.baseUrl}${path}`, {
-			method: options.method,
-			headers,
-			body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
-			signal
-		});
+		const startedAt = Date.now();
+		let response;
+		try {
+			response = await this.fetchFn(`${server.baseUrl}${path}`, {
+				method: options.method,
+				headers,
+				body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+				signal
+			});
+		} catch (error) {
+			appendDebugLog("opencode:request:error", {
+				method: options.method,
+				path,
+				elapsedMs: Date.now() - startedAt,
+				timeoutMs: options.timeoutMs,
+				error: serializeError(error),
+				serverClosed: server.closed
+			});
+			throw error;
+		}
 		if (!response.ok) {
 			const body = await response.text();
+			appendDebugLog("opencode:request:non-ok", {
+				method: options.method,
+				path,
+				status: response.status,
+				elapsedMs: Date.now() - startedAt,
+				bodySample: body.slice(0, 1024)
+			});
 			throw new Error(`opencode ${options.method} ${path} failed with ${response.status}: ${body}`);
 		}
 		return response;
@@ -1706,11 +2068,18 @@ var RovoDevAgent = class {
 		const logStream = logPath ? createWriteStream(logPath) : null;
 		const runController = new AbortController();
 		let sessionId = null;
+		const runStartedAt = Date.now();
+		appendDebugLog("rovodev:run:start", {
+			cwd,
+			promptLength: prompt.length,
+			hasLogPath: logPath !== void 0
+		});
 		const onAbort = () => {
 			runController.abort();
 		};
 		if (signal?.aborted) {
 			logStream?.end();
+			appendDebugLog("rovodev:run:aborted-early", {});
 			throw createAbortError();
 		}
 		signal?.addEventListener("abort", onAbort, { once: true });
@@ -1719,9 +2088,30 @@ var RovoDevAgent = class {
 			sessionId = await this.createSession(server, runController.signal);
 			await this.setInlineSystemPrompt(server, sessionId, runController.signal);
 			await this.setChatMessage(server, sessionId, prompt, runController.signal);
-			return await this.streamChat(server, sessionId, runController.signal, logStream, onUsage, onMessage);
+			const result = await this.streamChat(server, sessionId, runController.signal, logStream, onUsage, onMessage);
+			appendDebugLog("rovodev:run:end", {
+				sessionId,
+				elapsedMs: Date.now() - runStartedAt,
+				inputTokens: result.usage.inputTokens,
+				outputTokens: result.usage.outputTokens
+			});
+			return result;
 		} catch (error) {
-			if (runController.signal.aborted || isAbortError(error)) throw createAbortError();
+			if (runController.signal.aborted || isAbortError(error)) {
+				appendDebugLog("rovodev:run:aborted", {
+					sessionId,
+					elapsedMs: Date.now() - runStartedAt
+				});
+				throw createAbortError();
+			}
+			appendDebugLog("rovodev:run:error", {
+				sessionId,
+				elapsedMs: Date.now() - runStartedAt,
+				error: serializeError(error),
+				serverStderr: this.server?.stderr.slice(-2048),
+				serverStdout: this.server?.stdout.slice(-2048),
+				serverClosed: this.server?.closed ?? true
+			});
 			throw error;
 		} finally {
 			signal?.removeEventListener("abort", onAbort);
@@ -1779,17 +2169,40 @@ var RovoDevAgent = class {
 			server.stderr += data.toString();
 			if (server.stderr.length > MAX_OUTPUT) server.stderr = server.stderr.slice(-MAX_OUTPUT);
 		});
-		child.on("close", () => {
+		child.on("close", (code, closeSignal) => {
 			server.closed = true;
+			appendDebugLog("rovodev:server:close", {
+				cwd: server.cwd,
+				port: server.port,
+				code,
+				signal: closeSignal,
+				stderr: server.stderr.slice(-2048),
+				stdout: server.stdout.slice(-2048)
+			});
 			if (this.server === server) this.server = null;
 		});
 		this.server = server;
+		const spawnedAt = Date.now();
 		appendDebugLog("rovodev:spawn", {
 			cwd,
 			port,
-			detached
+			detached,
+			pid: child.pid,
+			bin: this.bin
 		});
-		server.readyPromise = this.waitForHealthy(server, signal).catch(async (error) => {
+		server.readyPromise = this.waitForHealthy(server, signal).then(() => {
+			appendDebugLog("rovodev:server:ready", {
+				port,
+				elapsedMs: Date.now() - spawnedAt
+			});
+		}).catch(async (error) => {
+			appendDebugLog("rovodev:server:ready-failed", {
+				port,
+				elapsedMs: Date.now() - spawnedAt,
+				error: serializeError(error),
+				stderr: server.stderr.slice(-2048),
+				stdout: server.stdout.slice(-2048)
+			});
 			await this.shutdownServer();
 			throw error;
 		});
@@ -1822,11 +2235,13 @@ var RovoDevAgent = class {
 		throw new Error(`Timed out waiting for rovodev serve to become ready on port ${server.port}`);
 	}
 	async createSession(server, signal) {
-		return (await this.requestJSON(server, "/v3/sessions/create", {
+		const response = await this.requestJSON(server, "/v3/sessions/create", {
 			method: "POST",
 			body: { custom_title: "gnhf" },
 			signal
-		})).session_id;
+		});
+		appendDebugLog("rovodev:session:create", { sessionId: response.session_id });
+		return response.session_id;
 	}
 	async setInlineSystemPrompt(server, sessionId, signal) {
 		const schema = readFileSync(this.schemaPath, "utf-8").trim();
@@ -1852,7 +2267,13 @@ var RovoDevAgent = class {
 				sessionId,
 				timeoutMs: 1e3
 			});
-		} catch {}
+			appendDebugLog("rovodev:session:cancel", { sessionId });
+		} catch (error) {
+			appendDebugLog("rovodev:session:cancel-failed", {
+				sessionId,
+				error: serializeError(error)
+			});
+		}
 	}
 	async deleteSession(server, sessionId) {
 		try {
@@ -1861,16 +2282,27 @@ var RovoDevAgent = class {
 				sessionId,
 				timeoutMs: 1e3
 			});
-		} catch {}
+			appendDebugLog("rovodev:session:delete", { sessionId });
+		} catch (error) {
+			appendDebugLog("rovodev:session:delete-failed", {
+				sessionId,
+				error: serializeError(error)
+			});
+		}
 	}
 	async streamChat(server, sessionId, signal, logStream, onUsage, onMessage) {
+		const streamStartedAt = Date.now();
+		appendDebugLog("rovodev:stream:start", { sessionId });
 		const response = await this.request(server, "/v3/stream_chat", {
 			method: "GET",
 			sessionId,
 			headers: { accept: "text/event-stream" },
 			signal
 		});
-		if (!response.body) throw new Error("rovodev returned no response body");
+		if (!response.body) {
+			appendDebugLog("rovodev:stream:no-body", { sessionId });
+			throw new Error("rovodev returned no response body");
+		}
 		const usage = {
 			inputTokens: 0,
 			outputTokens: 0,
@@ -1959,11 +2391,20 @@ var RovoDevAgent = class {
 				}
 			}
 		};
+		let bytesRead = 0;
 		while (true) {
 			let readResult;
 			try {
 				readResult = await reader.read();
 			} catch (error) {
+				appendDebugLog("rovodev:stream:error", {
+					sessionId,
+					elapsedMs: Date.now() - streamStartedAt,
+					bytesRead,
+					error: serializeError(error),
+					serverClosed: server.closed,
+					serverStderr: server.stderr.slice(-2048)
+				});
 				if (isAbortError(error)) throw createAbortError();
 				throw error;
 			}
@@ -1971,6 +2412,7 @@ var RovoDevAgent = class {
 			const chunk = decoder.decode(readResult.value, { stream: true });
 			logStream?.write(chunk);
 			buffer += chunk;
+			bytesRead += chunk.length;
 			while (true) {
 				const lfBoundary = buffer.indexOf("\n\n");
 				const crlfBoundary = buffer.indexOf("\r\n\r\n");
@@ -1991,14 +2433,33 @@ var RovoDevAgent = class {
 		}
 		buffer += decoder.decode();
 		if (buffer.trim()) handleEvent(buffer);
+		appendDebugLog("rovodev:stream:end", {
+			sessionId,
+			elapsedMs: Date.now() - streamStartedAt,
+			bytesRead
+		});
 		const finalText = latestTextSegment.trim();
-		if (!finalText) throw new Error("rovodev returned no text output");
+		if (!finalText) {
+			appendDebugLog("rovodev:output:missing", { sessionId });
+			throw new Error("rovodev returned no text output");
+		}
 		try {
+			const output = JSON.parse(finalText);
+			appendDebugLog("rovodev:output:parsed", {
+				sessionId,
+				outputTextLength: finalText.length
+			});
 			return {
-				output: JSON.parse(finalText),
+				output,
 				usage
 			};
 		} catch (error) {
+			appendDebugLog("rovodev:output:parse-error", {
+				sessionId,
+				outputTextLength: finalText.length,
+				outputTextSample: finalText.slice(0, 512),
+				error: serializeError(error)
+			});
 			throw new Error(`Failed to parse rovodev output: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	}
@@ -2012,9 +2473,11 @@ var RovoDevAgent = class {
 			return;
 		}
 		const server = this.server;
+		const shutdownStartedAt = Date.now();
 		appendDebugLog("rovodev:shutdown", {
 			cwd: server.cwd,
-			port: server.port
+			port: server.port,
+			pid: server.child.pid
 		});
 		this.closingPromise = this.platform === "win32" ? new Promise((resolve) => {
 			const handleClose = () => {
@@ -2041,6 +2504,10 @@ var RovoDevAgent = class {
 		this.closingPromise = this.closingPromise.finally(() => {
 			if (this.server === server) this.server = null;
 			this.closingPromise = null;
+			appendDebugLog("rovodev:shutdown:done", {
+				port: server.port,
+				elapsedMs: Date.now() - shutdownStartedAt
+			});
 		});
 		await this.closingPromise;
 	}
@@ -2052,14 +2519,35 @@ var RovoDevAgent = class {
 		if (options.sessionId) headers.set("x-session-id", options.sessionId);
 		if (options.body !== void 0 && !headers.has("content-type")) headers.set("content-type", "application/json");
 		const signal = withTimeoutSignal(options.signal, options.timeoutMs);
-		const response = await this.fetchFn(`${server.baseUrl}${path}`, {
-			method: options.method,
-			headers,
-			body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
-			signal
-		});
+		const startedAt = Date.now();
+		let response;
+		try {
+			response = await this.fetchFn(`${server.baseUrl}${path}`, {
+				method: options.method,
+				headers,
+				body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+				signal
+			});
+		} catch (error) {
+			appendDebugLog("rovodev:request:error", {
+				method: options.method,
+				path,
+				elapsedMs: Date.now() - startedAt,
+				timeoutMs: options.timeoutMs,
+				error: serializeError(error),
+				serverClosed: server.closed
+			});
+			throw error;
+		}
 		if (!response.ok) {
 			const body = await response.text();
+			appendDebugLog("rovodev:request:non-ok", {
+				method: options.method,
+				path,
+				status: response.status,
+				elapsedMs: Date.now() - startedAt,
+				bodySample: body.slice(0, 1024)
+			});
 			throw new Error(`rovodev ${options.method} ${path} failed with ${response.status}: ${body}`);
 		}
 		return response;
@@ -2151,6 +2639,11 @@ var Orchestrator = class extends EventEmitter {
 	}
 	stop() {
 		this.stopRequested = true;
+		appendDebugLog("orchestrator:stop-requested", {
+			iteration: this.state.currentIteration,
+			hasActiveIteration: this.activeIterationPromise !== null,
+			loopDone: this.loopDone
+		});
 		this.activeAbortController?.abort();
 		if (this.loopDone) {
 			this.emit("stopped");
@@ -2185,6 +2678,16 @@ var Orchestrator = class extends EventEmitter {
 		this.state.startTime = /* @__PURE__ */ new Date();
 		this.state.status = "running";
 		this.emit("state", this.getState());
+		appendDebugLog("orchestrator:start", {
+			agent: this.agent.name,
+			runId: this.runInfo.runId,
+			startIteration: this.state.currentIteration,
+			maxIterations: this.limits.maxIterations,
+			maxTokens: this.limits.maxTokens,
+			maxConsecutiveFailures: this.config.maxConsecutiveFailures,
+			baseCommit: this.runInfo.baseCommit,
+			initialCommitCount: this.state.commitCount
+		});
 		try {
 			while (!this.stopRequested) {
 				const preIterationAbortReason = this.getPreIterationAbortReason();
@@ -2201,11 +2704,32 @@ var Orchestrator = class extends EventEmitter {
 					runId: this.runInfo.runId,
 					prompt: this.prompt
 				});
+				appendDebugLog("iteration:start", {
+					iteration: this.state.currentIteration,
+					promptLength: iterationPrompt.length,
+					consecutiveFailures: this.state.consecutiveFailures,
+					totalInputTokens: this.state.totalInputTokens,
+					totalOutputTokens: this.state.totalOutputTokens,
+					git: this.snapshotGitState()
+				});
+				const iterationStartedAt = Date.now();
 				this.activeIterationPromise = this.runIteration(iterationPrompt);
 				const result = await this.activeIterationPromise;
 				this.activeIterationPromise = null;
-				if (result.type === "stopped") break;
+				const iterationElapsedMs = Date.now() - iterationStartedAt;
+				if (result.type === "stopped") {
+					appendDebugLog("iteration:stopped", {
+						iteration: this.state.currentIteration,
+						elapsedMs: iterationElapsedMs
+					});
+					break;
+				}
 				if (result.type === "aborted") {
+					appendDebugLog("iteration:aborted", {
+						iteration: this.state.currentIteration,
+						elapsedMs: iterationElapsedMs,
+						reason: result.reason
+					});
 					this.abort(result.reason);
 					break;
 				}
@@ -2213,6 +2737,18 @@ var Orchestrator = class extends EventEmitter {
 				this.state.iterations.push(record);
 				this.emit("iteration:end", record);
 				this.emit("state", this.getState());
+				appendDebugLog("iteration:end", {
+					iteration: record.number,
+					elapsedMs: iterationElapsedMs,
+					success: record.success,
+					summary: record.summary,
+					keyChanges: record.keyChanges.length,
+					keyLearnings: record.keyLearnings.length,
+					consecutiveFailures: this.state.consecutiveFailures,
+					totalInputTokens: this.state.totalInputTokens,
+					totalOutputTokens: this.state.totalOutputTokens,
+					commitCount: this.state.commitCount
+				});
 				const postIterationAbortReason = this.getPostIterationAbortReason();
 				if (postIterationAbortReason) {
 					this.abort(postIterationAbortReason);
@@ -2227,7 +2763,16 @@ var Orchestrator = class extends EventEmitter {
 					this.state.status = "waiting";
 					this.state.waitingUntil = new Date(Date.now() + backoffMs);
 					this.emit("state", this.getState());
+					appendDebugLog("backoff:start", {
+						iteration: this.state.currentIteration,
+						consecutiveFailures: this.state.consecutiveFailures,
+						backoffMs
+					});
 					await this.interruptibleSleep(backoffMs);
+					appendDebugLog("backoff:end", {
+						iteration: this.state.currentIteration,
+						stopRequested: this.stopRequested
+					});
 					this.state.waitingUntil = null;
 					if (!this.stopRequested) {
 						this.state.status = "running";
@@ -2240,6 +2785,15 @@ var Orchestrator = class extends EventEmitter {
 			if (this.stopPromise) await this.stopPromise;
 			else await this.closeAgent();
 			this.loopDone = true;
+			appendDebugLog("orchestrator:end", {
+				status: this.state.status,
+				iterations: this.state.currentIteration,
+				successCount: this.state.successCount,
+				failCount: this.state.failCount,
+				totalInputTokens: this.state.totalInputTokens,
+				totalOutputTokens: this.state.totalOutputTokens,
+				commitCount: this.state.commitCount
+			});
 		}
 	}
 	async runIteration(prompt) {
@@ -2262,6 +2816,12 @@ var Orchestrator = class extends EventEmitter {
 			this.emit("state", this.getState());
 		};
 		const logPath = join(this.runInfo.runDir, `iteration-${this.state.currentIteration}.jsonl`);
+		const agentStartedAt = Date.now();
+		appendDebugLog("agent:run:start", {
+			iteration: this.state.currentIteration,
+			agent: this.agent.name,
+			logPath
+		});
 		try {
 			const result = await this.agent.run(prompt, this.cwd, {
 				onUsage,
@@ -2269,6 +2829,15 @@ var Orchestrator = class extends EventEmitter {
 				signal: this.activeAbortController.signal,
 				logPath
 			});
+			appendDebugLog("agent:run:end", {
+				iteration: this.state.currentIteration,
+				elapsedMs: Date.now() - agentStartedAt,
+				success: result.output.success,
+				inputTokens: result.usage.inputTokens,
+				outputTokens: result.usage.outputTokens,
+				cacheReadTokens: result.usage.cacheReadTokens,
+				cacheCreationTokens: result.usage.cacheCreationTokens
+			});
 			if (this.stopRequested) return { type: "stopped" };
 			if (result.output.success) return {
 				type: "completed",
@@ -2279,14 +2848,31 @@ var Orchestrator = class extends EventEmitter {
 				record: this.recordFailure(`[FAIL] ${result.output.summary}`, result.output.summary, result.output.key_learnings)
 			};
 		} catch (err) {
+			const elapsedMs = Date.now() - agentStartedAt;
 			if (this.pendingAbortReason && err instanceof Error && err.message === "Agent was aborted") {
+				appendDebugLog("agent:run:aborted", {
+					iteration: this.state.currentIteration,
+					elapsedMs,
+					reason: this.pendingAbortReason
+				});
 				resetHard(this.cwd);
 				return {
 					type: "aborted",
 					reason: this.pendingAbortReason
 				};
 			}
-			if (this.stopRequested) return { type: "stopped" };
+			if (this.stopRequested) {
+				appendDebugLog("agent:run:stopped", {
+					iteration: this.state.currentIteration,
+					elapsedMs
+				});
+				return { type: "stopped" };
+			}
+			appendDebugLog("agent:run:error", {
+				iteration: this.state.currentIteration,
+				elapsedMs,
+				error: serializeError(err)
+			});
 			const summary = err instanceof Error ? err.message : String(err);
 			return {
 				type: "completed",
@@ -2358,13 +2944,31 @@ var Orchestrator = class extends EventEmitter {
 		this.state.status = "aborted";
 		this.state.lastMessage = reason;
 		this.state.waitingUntil = null;
+		appendDebugLog("orchestrator:abort", {
+			reason,
+			iteration: this.state.currentIteration,
+			consecutiveFailures: this.state.consecutiveFailures
+		});
 		this.emit("abort", reason);
 		this.emit("state", this.getState());
 	}
 	async closeAgent() {
 		try {
 			await this.agent.close?.();
-		} catch {}
+		} catch (err) {
+			appendDebugLog("agent:close:error", { error: serializeError(err) });
+		}
+	}
+	snapshotGitState() {
+		try {
+			return {
+				head: getHeadCommit(this.cwd),
+				branch: getCurrentBranch(this.cwd),
+				commitCount: this.state.commitCount
+			};
+		} catch (err) {
+			return { error: serializeError(err) };
+		}
 	}
 };
 //#endregion
@@ -3285,7 +3889,22 @@ program.name("gnhf").description("Before I go to bed, I tell my agents: good nig
 			if (!reexeced) persistedPrompt?.cleanup();
 		}
 	}
-	appendDebugLog("run:start", { args: process$1.argv.slice(2) });
+	initDebugLog(runInfo.logPath);
+	appendDebugLog("run:start", {
+		args: process$1.argv.slice(2),
+		runId: runInfo.runId,
+		runDir: runInfo.runDir,
+		agent: config.agent,
+		promptLength: prompt.length,
+		promptFromStdin,
+		startIteration,
+		maxIterations: options.maxIterations,
+		maxTokens: options.maxTokens,
+		preventSleep: config.preventSleep,
+		platform: process$1.platform,
+		nodeVersion: process$1.version,
+		gnhfVersion: packageVersion
+	});
 	const orchestrator = new Orchestrator(config, createAgent(config.agent, runInfo, config.agentPathOverride[config.agent]), runInfo, prompt, cwd, startIteration, {
 		maxIterations: options.maxIterations,
 		maxTokens: options.maxTokens
@@ -3308,6 +3927,7 @@ program.name("gnhf").description("Before I go to bed, I tell my agents: good nig
 	const orchestratorPromise = orchestrator.start().finally(() => {
 		if (!(orchestrator.getState().status === "aborted" && process$1.stdin.isTTY)) renderer.stop();
 	}).catch((err) => {
+		appendDebugLog("orchestrator:fatal", { error: serializeError(err) });
 		exitAltScreen();
 		die(err instanceof Error ? err.message : String(err));
 	});
@@ -3329,7 +3949,19 @@ program.name("gnhf").description("Before I go to bed, I tell my agents: good nig
 		process$1.off("SIGTERM", handleSigTerm);
 		await sleepPreventionCleanup?.();
 	}
-	appendDebugLog("run:complete", { signal: shutdownSignal });
+	{
+		const finalState = orchestrator.getState();
+		appendDebugLog("run:complete", {
+			signal: shutdownSignal,
+			status: finalState.status,
+			iterations: finalState.currentIteration,
+			successCount: finalState.successCount,
+			failCount: finalState.failCount,
+			totalInputTokens: finalState.totalInputTokens,
+			totalOutputTokens: finalState.totalOutputTokens,
+			commitCount: finalState.commitCount
+		});
+	}
 	if (shutdownSignal) process$1.exit(getSignalExitCode(shutdownSignal));
 });
 function enterAltScreen() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnhf",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Before I go to bed, I tell my agents: good night, have fun",
   "type": "module",
   "bin": {