gnhf 0.1.24 → 0.1.26

package/README.md

@@ -45,7 +45,7 @@ gnhf is a [ralph](https://ghuntley.com/ralph/), [autoresearch](https://github.co
 You wake up to a branch full of clean work and a log of everything that happened.
 
 - **Dead simple** — one command starts an autonomous loop that runs until you Ctrl+C or a configured runtime cap is reached
-- **Long running** — each iteration is committed on success, rolled back on failure, with sensible retries and exponential backoff
+- **Long running** — each iteration is committed on success, rolled back on failure, with sensible retries; hard agent errors back off exponentially while agent-reported failures continue immediately
 - **Live terminal title** — interactive runs keep your terminal title updated with live status, token totals, and commit count, then restore the previous title on exit
 - **Agent-agnostic** — works with Claude Code, Codex, Rovo Dev, or OpenCode out of the box
 
@@ -122,7 +122,7 @@ npm link
               ┌──────────┐  ┌───────────┐                  │
               │  commit  │  │ git reset │                  │
               │  append  │  │  --hard   │                  │
-              │ notes.md │  │  backoff  │                  │
+              │ notes.md │  │ maybe wait│                  │
               └────┬─────┘  └─────┬─────┘                  │
                    │              │                        │
                    │   ┌──────────┘                        │
@@ -136,10 +136,12 @@ npm link
 ```
 
 - **Incremental commits** — each successful iteration is a separate git commit, so you can cherry-pick or revert individual changes
+- **Failure handling** - all failed iterations are rolled back with `git reset --hard`; agent-reported failures proceed to the next iteration immediately, while hard agent errors use exponential backoff
 - **Runtime caps** - `--max-iterations` stops before the next iteration begins, `--max-tokens` can abort mid-iteration once reported usage reaches the cap, and `--stop-when` ends the loop after an iteration whose agent output reports the natural-language condition is met; uncommitted work is rolled back in either case, and in the interactive TUI the final state remains visible until you press Ctrl+C to exit
+- **Iteration finalization** - agents are expected to finish validation, stop any background processes they started, and only then emit the final JSON result for the iteration
 - **Shared memory** — the agent reads `notes.md` (built up from prior iterations) to communicate across iterations
 - **Local run metadata** — gnhf stores prompt, notes, and resume metadata under `.gnhf/runs/` and ignores it locally, so your branch only contains intentional work
-- **Resume support** — run `gnhf` while on an existing `gnhf/` branch to pick up where a previous run left off; if you provide a different prompt, gnhf asks whether to overwrite the saved prompt, start a new branch, or quit
+- **Resume support** — run `gnhf` while on an existing `gnhf/` branch to pick up where a previous run left off; if you provide a different prompt, gnhf asks whether to update the saved prompt and continue with the existing history, start a new branch, or quit
 
 ### Worktree Mode
 
@@ -165,7 +167,7 @@ Pass `--worktree` to run each agent in an isolated [git worktree](https://git-sc
 | `echo "<prompt>" \| gnhf` | Pipe prompt via stdin                           |
 | `cat prd.md \| gnhf`      | Pipe a large spec or PRD via stdin              |
 
-If you run `gnhf` on an existing `gnhf/` branch with a different prompt, gnhf asks whether to overwrite the saved prompt, start a new branch, or quit. When the prompt came from stdin, that confirmation is read from the controlling terminal, so it must be available.
+If you run `gnhf` on an existing `gnhf/` branch with a different prompt, gnhf asks whether to update `prompt.md` and continue the existing run history, start a new branch, or quit. When the prompt came from stdin, that confirmation is read from the controlling terminal, so it must be available.
 
 ### Flags
 
@@ -242,12 +244,12 @@ Including a snippet of `gnhf.log` is the single most useful thing you can attach
 
 `gnhf` supports four agents:
 
-| Agent       | Flag               | Requirements                                                               | Notes                                                                                                                                                                                                            |
-| ----------- | ------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Claude Code | `--agent claude`   | Install Anthropic's `claude` CLI and sign in first.                        | `gnhf` invokes `claude` directly in non-interactive mode.                                                                                                                                                        |
-| Codex       | `--agent codex`    | Install OpenAI's `codex` CLI and sign in first.                            | `gnhf` invokes `codex exec` directly in non-interactive mode.                                                                                                                                                    |
-| Rovo Dev    | `--agent rovodev`  | Install Atlassian's `acli` and authenticate it with Rovo Dev first.        | `gnhf` starts a local `acli rovodev serve --disable-session-token <port>` process automatically in the repo workspace.                                                                                           |
-| OpenCode    | `--agent opencode` | Install `opencode` and configure at least one usable model provider first. | `gnhf` starts a local `opencode serve --hostname 127.0.0.1 --port <port> --print-logs` process automatically, creates a per-run session, and applies a blanket allow rule so tool calls do not block on prompts. |
+| Agent       | Flag               | Requirements                                                               | Notes                                                                                                                                                                                                                        |
+| ----------- | ------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code | `--agent claude`   | Install Anthropic's `claude` CLI and sign in first.                        | `gnhf` invokes `claude` directly in non-interactive mode. After Claude emits a successful structured result, `gnhf` treats that result as final and shuts down any lingering Claude process tree after a short grace period. |
+| Codex       | `--agent codex`    | Install OpenAI's `codex` CLI and sign in first.                            | `gnhf` invokes `codex exec` directly in non-interactive mode.                                                                                                                                                                |
+| Rovo Dev    | `--agent rovodev`  | Install Atlassian's `acli` and authenticate it with Rovo Dev first.        | `gnhf` starts a local `acli rovodev serve --disable-session-token <port>` process automatically in the repo workspace.                                                                                                       |
+| OpenCode    | `--agent opencode` | Install `opencode` and configure at least one usable model provider first. | `gnhf` starts a local `opencode serve --hostname 127.0.0.1 --port <port> --print-logs` process automatically, creates a per-run session, and applies a blanket allow rule so tool calls do not block on prompts.             |
 
 ## Development
 

package/dist/cli.mjs

@@ -488,7 +488,7 @@ function setupRun(runId, prompt, baseCommit, cwd, schemaOptions) {
 	const promptPath = join(runDir, "prompt.md");
 	writeFileSync(promptPath, prompt, "utf-8");
 	const notesPath = join(runDir, "notes.md");
-	writeFileSync(notesPath, `# gnhf run: ${runId}\n\nObjective: ${prompt}\n\n## Iteration Log\n`, "utf-8");
+	if (!existsSync(notesPath)) writeFileSync(notesPath, `# gnhf run: ${runId}\n\nObjective: see .gnhf/runs/${runId}/prompt.md\n\n## Iteration Log\n`, "utf-8");
 	const schemaPath = join(runDir, "output-schema.json");
 	writeSchemaFile(schemaPath, schemaOptions.includeStopField);
 	const logPath = join(runDir, LOG_FILENAME);
@@ -1043,6 +1043,7 @@ function setupAbortHandler(signal, child, reject, abortChild = () => {
 }
 //#endregion
 //#region src/core/agents/claude.ts
+const DEFAULT_FINAL_RESULT_EXIT_GRACE_MS = 15e3;
 function shouldUseWindowsShell$2(bin, platform) {
 	if (platform !== "win32") return false;
 	if (/\.(cmd|bat)$/i.test(bin)) return true;
@@ -1073,8 +1074,22 @@ function terminateClaudeProcess(child, platform) {
 		} catch {}
 		return;
 	}
+	if (child.pid) try {
+		process.kill(-child.pid, "SIGTERM");
+		return;
+	} catch {}
 	child.kill("SIGTERM");
 }
+async function shutdownClaudeProcess(child, platform) {
+	if (platform === "win32") {
+		terminateClaudeProcess(child, platform);
+		return;
+	}
+	await shutdownChildProcess(child, { detached: true });
+}
+function isFinalStructuredResult(event) {
+	return !event.is_error && event.subtype === "success" && !!event.structured_output;
+}
 function buildClaudeArgs(prompt, schema, extraArgs) {
 	const userArgs = extraArgs ?? [];
 	const userSpecifiedPermissionMode = userArgs.some((arg) => arg === "--dangerously-skip-permissions" || arg === "--permission-mode" || arg.startsWith("--permission-mode=") || arg === "--permission-prompt-tool" || arg.startsWith("--permission-prompt-tool="));
@@ -1108,12 +1123,14 @@ var ClaudeAgent = class {
 	name = "claude";
 	bin;
 	extraArgs;
+	finalResultGraceMs;
 	platform;
 	schema;
 	constructor(binOrDeps = {}) {
 		const deps = typeof binOrDeps === "string" ? { bin: binOrDeps } : binOrDeps;
 		this.bin = deps.bin ?? "claude";
 		this.extraArgs = deps.extraArgs;
+		this.finalResultGraceMs = deps.finalResultGraceMs ?? DEFAULT_FINAL_RESULT_EXIT_GRACE_MS;
 		this.platform = deps.platform ?? process.platform;
 		this.schema = deps.schema ?? buildAgentOutputSchema({ includeStopField: false });
 	}
@@ -1123,6 +1140,7 @@ var ClaudeAgent = class {
 			const logStream = logPath ? createWriteStream(logPath) : null;
 			const child = spawn(this.bin, buildClaudeArgs(prompt, this.schema, this.extraArgs), {
 				cwd,
+				detached: this.platform !== "win32",
 				shell: shouldUseWindowsShell$2(this.bin, this.platform),
 				stdio: [
 					"ignore",
@@ -1133,6 +1151,11 @@ var ClaudeAgent = class {
 			});
 			if (setupAbortHandler(signal, child, reject, () => terminateClaudeProcess(child, this.platform))) return;
 			let resultEvent = null;
+			let finalStructuredResultEvent = null;
+			let latestResultUsage = null;
+			let finalResultCleanupTimer = null;
+			let closedAfterFinalCleanup = false;
+			let stderr = "";
 			const cumulative = {
 				inputTokens: 0,
 				outputTokens: 0,
@@ -1144,6 +1167,12 @@ var ClaudeAgent = class {
 			let lastAnonymousAssistantId = null;
 			let lastAnonymousAssistantUsage = null;
 			let pendingAnonymousAssistantUsage = null;
+			child.stderr.on("data", (data) => {
+				stderr += data.toString();
+			});
+			child.on("error", (err) => {
+				reject(/* @__PURE__ */ new Error(`Failed to spawn claude: ${err.message}`));
+			});
 			parseJSONLStream(child.stdout, logStream, (event) => {
 				if (event.type === "assistant") {
 					const msg = event.message;
@@ -1201,23 +1230,41 @@ var ClaudeAgent = class {
 						}
 					}
 				}
-				if (event.type === "result") resultEvent = event;
+				if (event.type === "result") {
+					const next = event;
+					latestResultUsage = next.usage;
+					if (isFinalStructuredResult(next)) {
+						finalStructuredResultEvent = next;
+						if (finalResultCleanupTimer) clearTimeout(finalResultCleanupTimer);
+						finalResultCleanupTimer = setTimeout(() => {
+							closedAfterFinalCleanup = true;
+							shutdownClaudeProcess(child, this.platform);
+						}, this.finalResultGraceMs);
+					} else if (!finalStructuredResultEvent && (next.is_error || next.subtype !== "success" || next.structured_output || !resultEvent)) resultEvent = next;
+				}
 			});
-			setupChildProcessHandlers(child, "claude", logStream, reject, () => {
-				if (!resultEvent) {
+			child.on("close", (code) => {
+				if (finalResultCleanupTimer) clearTimeout(finalResultCleanupTimer);
+				logStream?.end();
+				if (code !== 0 && !closedAfterFinalCleanup) {
+					reject(/* @__PURE__ */ new Error(`claude exited with code ${code}: ${stderr}`));
+					return;
+				}
+				const terminalResultEvent = finalStructuredResultEvent ?? resultEvent;
+				if (!terminalResultEvent) {
 					reject(/* @__PURE__ */ new Error("claude returned no result event"));
 					return;
 				}
-				if (resultEvent.is_error || resultEvent.subtype !== "success") {
-					reject(/* @__PURE__ */ new Error(`claude reported error: ${JSON.stringify(resultEvent)}`));
+				if (terminalResultEvent.is_error || terminalResultEvent.subtype !== "success") {
+					reject(/* @__PURE__ */ new Error(`claude reported error: ${JSON.stringify(terminalResultEvent)}`));
 					return;
 				}
-				if (!resultEvent.structured_output) {
+				if (!terminalResultEvent.structured_output) {
 					reject(/* @__PURE__ */ new Error("claude returned no structured_output"));
 					return;
 				}
-				const output = resultEvent.structured_output;
-				const usage = toTokenUsage(resultEvent.usage);
+				const output = terminalResultEvent.structured_output;
+				const usage = toTokenUsage(latestResultUsage ?? terminalResultEvent.usage);
 				onUsage?.(usage);
 				resolve({
 					output,
@@ -2813,7 +2860,8 @@ This is iteration ${params.n}. Each iteration aims to make an incremental step f
 2. Identify the next smallest logical unit of work that's individually verifiable and would make incremental progress towards the objective, and treat that as the scope of this iteration
 3. If you attempted a solution and it didn't end up moving the needle on the objective, document learnings and record success=false, then conclude the iteration rather than continuously pivoting
 4. If you made code changes, run build/tests/linters/formatters if available to validate your work. Do NOT make any git commits - that will be handled automatically by the gnhf orchestrator
-6. Finally, respond with a JSON object according to the provided schema
+5. If you started any long-running background processes (dev servers, browsers, watchers, Electron, etc.), stop them before finishing the iteration
+6. Only submit the final JSON object after the result is final: your work is complete, validation is done, and you have stopped any background processes you started
 
 ## Output
 
@@ -2849,6 +2897,7 @@ var Orchestrator = class extends EventEmitter {
 		successCount: 0,
 		failCount: 0,
 		consecutiveFailures: 0,
+		consecutiveErrors: 0,
 		startTime: /* @__PURE__ */ new Date(),
 		waitingUntil: null,
 		lastMessage: null
@@ -2993,14 +3042,14 @@ var Orchestrator = class extends EventEmitter {
 					this.abort(`${this.config.maxConsecutiveFailures} consecutive failures`);
 					break;
 				}
-				if (this.state.consecutiveFailures > 0 && !this.stopRequested) {
-					const backoffMs = 6e4 * Math.pow(2, this.state.consecutiveFailures - 1);
+				if (this.state.consecutiveErrors > 0 && !this.stopRequested) {
+					const backoffMs = 6e4 * Math.pow(2, this.state.consecutiveErrors - 1);
 					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,
+						consecutiveErrors: this.state.consecutiveErrors,
 						backoffMs
 					});
 					await this.interruptibleSleep(backoffMs);
@@ -3088,7 +3137,7 @@ var Orchestrator = class extends EventEmitter {
 			};
 			return {
 				type: "completed",
-				record: this.recordFailure(`[FAIL] ${result.output.summary}`, result.output.summary, toStringArray(result.output.key_learnings)),
+				record: this.recordFailure(`[FAIL] ${result.output.summary}`, result.output.summary, toStringArray(result.output.key_learnings), "reported"),
 				shouldFullyStop
 			};
 		} catch (err) {
@@ -3120,7 +3169,7 @@ var Orchestrator = class extends EventEmitter {
 			const summary = err instanceof Error ? err.message : String(err);
 			return {
 				type: "completed",
-				record: this.recordFailure(`[ERROR] ${summary}`, summary, []),
+				record: this.recordFailure(`[ERROR] ${summary}`, summary, [], "error"),
 				shouldFullyStop: false
 			};
 		} finally {
@@ -3134,6 +3183,7 @@ var Orchestrator = class extends EventEmitter {
 		this.state.commitCount = getBranchCommitCount(this.runInfo.baseCommit, this.cwd);
 		this.state.successCount++;
 		this.state.consecutiveFailures = 0;
+		this.state.consecutiveErrors = 0;
 		return {
 			number: this.state.currentIteration,
 			success: true,
@@ -3143,11 +3193,13 @@ var Orchestrator = class extends EventEmitter {
 			timestamp: /* @__PURE__ */ new Date()
 		};
 	}
-	recordFailure(notesSummary, recordSummary, learnings) {
+	recordFailure(notesSummary, recordSummary, learnings, kind) {
 		appendNotes(this.runInfo.notesPath, this.state.currentIteration, notesSummary, [], toStringArray(learnings));
 		resetHard(this.cwd);
 		this.state.failCount++;
 		this.state.consecutiveFailures++;
+		if (kind === "error") this.state.consecutiveErrors++;
+		else this.state.consecutiveErrors = 0;
 		return {
 			number: this.state.currentIteration,
 			success: false,
@@ -3280,6 +3332,7 @@ var MockOrchestrator = class extends EventEmitter {
 		successCount: 11,
 		failCount: 2,
 		consecutiveFailures: 0,
+		consecutiveErrors: 0,
 		startTime: new Date(Date.now() - INITIAL_ELAPSED_MS),
 		waitingUntil: null,
 		lastMessage: AGENT_MESSAGES[0]
@@ -4252,10 +4305,11 @@ program.name("gnhf").description("Before I go to bed, I tell my agents: good nig
 			runInfo = existing;
 			startIteration = getLastIterationNumber(existing);
 		} else {
-			const answer = await ask(`You are on gnhf branch "${currentBranch}".\n  (o) Overwrite current run with new prompt\n  (n) Start a new branch on top of this one\n  (q) Quit\nChoose [o/n/q]: `, "The overwrite prompt closed before a choice was entered. Re-run gnhf from an interactive terminal and choose o, n, or q.", "Cannot show the overwrite prompt because stdin is not interactive. Re-run gnhf from an interactive terminal and choose o, n, or q.");
+			const answer = await ask(`You are on gnhf branch "${currentBranch}".\n  (o) Update prompt and continue current run\n  (n) Start a new branch on top of this one\n  (q) Quit\nChoose [o/n/q]: `, "The overwrite prompt closed before a choice was entered. Re-run gnhf from an interactive terminal and choose o, n, or q.", "Cannot show the overwrite prompt because stdin is not interactive. Re-run gnhf from an interactive terminal and choose o, n, or q.");
 			if (answer === "o") {
 				ensureCleanWorkingTree(cwd);
 				runInfo = setupRun(existingRunId, prompt, existing.baseCommit, cwd, schemaOptions);
+				startIteration = getLastIterationNumber(existing);
 			} else if (answer === "n") runInfo = initializeNewBranch(prompt, cwd, schemaOptions);
 			else process$1.exit(0);
 		}

package/package.json

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