gnhf 0.1.25 → 0.1.26

package/README.md

@@ -138,6 +138,7 @@ 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 update the saved prompt and continue with the existing history, start a new branch, or quit
@@ -243,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

@@ -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,7 +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,
@@ -1145,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;
@@ -1205,24 +1233,38 @@ var ClaudeAgent = class {
 				if (event.type === "result") {
 					const next = event;
 					latestResultUsage = next.usage;
-					if (next.is_error || next.subtype !== "success" || next.structured_output || !resultEvent) resultEvent = next;
+					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(latestResultUsage ?? resultEvent.usage);
+				const output = terminalResultEvent.structured_output;
+				const usage = toTokenUsage(latestResultUsage ?? terminalResultEvent.usage);
 				onUsage?.(usage);
 				resolve({
 					output,
@@ -2818,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
 

package/package.json

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