gnhf 0.1.4 → 0.1.6

package/README.md

@@ -42,7 +42,7 @@
 gnhf is a [ralph](https://ghuntley.com/ralph/), [autoresearch](https://github.com/karpathy/autoresearch)-style orchestrator that keeps your agents running while you sleep — each iteration makes one small, committed, documented change towards an objective.
 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
+- **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
 - **Agent-agnostic** — works with Claude Code or Codex out of the box
 
@@ -50,9 +50,18 @@ You wake up to a branch full of clean work and a log of everything that happened
 
 ```sh
 $ gnhf "reduce complexity of the codebase without changing functionality"
-# go to sleep
+# have a good sleep
 ```
 
+```sh
+$ gnhf "reduce complexity of the codebase without changing functionality" \
+    --max-iterations 10 \
+    --max-tokens 5000000
+# have a good nap
+```
+
+Run `gnhf` from inside a Git repository with a clean working tree. If you are starting from a plain directory, run `git init` first.
+
 ## Install
 
 **npm**
@@ -116,6 +125,7 @@ npm link
 ```
 
 - **Incremental commits** — each successful iteration is a separate git commit, so you can cherry-pick or revert individual changes
+- **Runtime caps** — `--max-iterations` stops before the next iteration begins, while `--max-tokens` can abort mid-iteration once reported usage reaches the cap; uncommitted work is rolled back in either case
 - **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
@@ -131,10 +141,12 @@ npm link
 
 ### Flags
 
-| Flag              | Description                        | Default                |
-| ----------------- | ---------------------------------- | ---------------------- |
-| `--agent <agent>` | Agent to use (`claude` or `codex`) | config file (`claude`) |
-| `--version`       | Show version                       |                        |
+| Flag                   | Description                               | Default                |
+| ---------------------- | ----------------------------------------- | ---------------------- |
+| `--agent <agent>`      | Agent to use (`claude` or `codex`)        | config file (`claude`) |
+| `--max-iterations <n>` | Abort after `n` total iterations          | unlimited              |
+| `--max-tokens <n>`     | Abort after `n` total input+output tokens | unlimited              |
+| `--version`            | Show version                              |                        |
 
 ## Configuration
 
@@ -150,7 +162,7 @@ maxConsecutiveFailures: 3
 
 If the file does not exist yet, `gnhf` creates it on first run using the resolved defaults.
 
-CLI flags override config file values.
+CLI flags override config file values. The iteration and token caps are runtime-only flags and are not persisted in `config.yml`.
 
 ## Development
 

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import { appendFileSync, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import process$1 from "node:process";
 import { createInterface } from "node:readline";
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
 import { dirname, isAbsolute, join } from "node:path";
 import { homedir } from "node:os";
 import yaml from "js-yaml";
@@ -50,15 +50,47 @@ function loadConfig(overrides) {
 }
 //#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.";
+function translateGitError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
 function git(args, cwd) {
-	return execSync(`git ${args}`, {
-		cwd,
-		encoding: "utf-8",
-		stdio: "pipe"
-	}).trim();
+	try {
+		return execSync(`git ${args}`, {
+			cwd,
+			encoding: "utf-8",
+			stdio: "pipe"
+		}).trim();
+	} catch (error) {
+		throw translateGitError(error);
+	}
+}
+function isGitRepository(cwd) {
+	try {
+		execSync("git rev-parse --git-dir", {
+			cwd,
+			encoding: "utf-8",
+			stdio: "pipe",
+			env: {
+				...process.env,
+				LC_ALL: "C"
+			}
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+function ensureGitRepository(cwd) {
+	if (!isGitRepository(cwd)) throw new Error(NOT_GIT_REPOSITORY_MESSAGE);
 }
 function getCurrentBranch(cwd) {
-	return git("rev-parse --abbrev-ref HEAD", cwd);
+	ensureGitRepository(cwd);
+	try {
+		return git("symbolic-ref --short HEAD", cwd);
+	} catch {
+		return git("rev-parse --abbrev-ref HEAD", cwd);
+	}
 }
 function ensureCleanWorkingTree(cwd) {
 	if (git("status --porcelain", cwd)) throw new Error("Working tree is not clean. Commit or stash changes first.");
@@ -461,8 +493,10 @@ var Orchestrator = class extends EventEmitter {
 	runInfo;
 	cwd;
 	prompt;
+	limits;
 	stopRequested = false;
 	activeAbortController = null;
+	pendingAbortReason = null;
 	state = {
 		status: "running",
 		currentIteration: 0,
@@ -477,13 +511,14 @@ var Orchestrator = class extends EventEmitter {
 		waitingUntil: null,
 		lastMessage: null
 	};
-	constructor(config, agent, runInfo, prompt, cwd, startIteration = 0) {
+	constructor(config, agent, runInfo, prompt, cwd, startIteration = 0, limits = {}) {
 		super();
 		this.config = config;
 		this.agent = agent;
 		this.runInfo = runInfo;
 		this.prompt = prompt;
 		this.cwd = cwd;
+		this.limits = limits;
 		this.state.currentIteration = startIteration;
 		this.state.commitCount = getBranchCommitCount(this.runInfo.baseCommit, this.cwd);
 	}
@@ -503,6 +538,11 @@ var Orchestrator = class extends EventEmitter {
 		this.state.status = "running";
 		this.emit("state", this.getState());
 		while (!this.stopRequested) {
+			const preIterationAbortReason = this.getPreIterationAbortReason();
+			if (preIterationAbortReason) {
+				this.abort(preIterationAbortReason);
+				break;
+			}
 			this.state.currentIteration++;
 			this.state.status = "running";
 			this.emit("iteration:start", this.state.currentIteration);
@@ -512,15 +552,22 @@ var Orchestrator = class extends EventEmitter {
 				runId: this.runInfo.runId,
 				prompt: this.prompt
 			});
-			const record = await this.runIteration(iterationPrompt);
+			const result = await this.runIteration(iterationPrompt);
+			if (result.type === "aborted") {
+				this.abort(result.reason);
+				break;
+			}
+			const { record } = result;
 			this.state.iterations.push(record);
 			this.emit("iteration:end", record);
 			this.emit("state", this.getState());
+			const postIterationAbortReason = this.getPostIterationAbortReason();
+			if (postIterationAbortReason) {
+				this.abort(postIterationAbortReason);
+				break;
+			}
 			if (this.state.consecutiveFailures >= this.config.maxConsecutiveFailures) {
-				this.state.status = "aborted";
-				const reason = `${this.config.maxConsecutiveFailures} consecutive failures`;
-				this.emit("abort", reason);
-				this.emit("state", this.getState());
+				this.abort(`${this.config.maxConsecutiveFailures} consecutive failures`);
 				break;
 			}
 			if (this.state.consecutiveFailures > 0 && !this.stopRequested) {
@@ -541,10 +588,16 @@ var Orchestrator = class extends EventEmitter {
 		const baseInputTokens = this.state.totalInputTokens;
 		const baseOutputTokens = this.state.totalOutputTokens;
 		this.activeAbortController = new AbortController();
+		this.pendingAbortReason = null;
 		const onUsage = (usage) => {
 			this.state.totalInputTokens = baseInputTokens + usage.inputTokens;
 			this.state.totalOutputTokens = baseOutputTokens + usage.outputTokens;
 			this.emit("state", this.getState());
+			const reason = this.getTokenAbortReason();
+			if (reason && this.activeAbortController && !this.activeAbortController.signal.aborted) {
+				this.pendingAbortReason = reason;
+				this.activeAbortController.abort();
+			}
 		};
 		const onMessage = (text) => {
 			this.state.lastMessage = text;
@@ -558,11 +611,30 @@ var Orchestrator = class extends EventEmitter {
 				signal: this.activeAbortController.signal,
 				logPath
 			});
-			if (result.output.success) return this.recordSuccess(result.output);
-			return this.recordFailure(`[FAIL] ${result.output.summary}`, result.output.summary, result.output.key_learnings);
+			if (result.output.success) return {
+				type: "completed",
+				record: this.recordSuccess(result.output)
+			};
+			return {
+				type: "completed",
+				record: this.recordFailure(`[FAIL] ${result.output.summary}`, result.output.summary, result.output.key_learnings)
+			};
 		} catch (err) {
+			if (this.pendingAbortReason && err instanceof Error && err.message === "Agent was aborted") {
+				resetHard(this.cwd);
+				return {
+					type: "aborted",
+					reason: this.pendingAbortReason
+				};
+			}
 			const summary = err instanceof Error ? err.message : String(err);
-			return this.recordFailure(`[ERROR] ${summary}`, summary, []);
+			return {
+				type: "completed",
+				record: this.recordFailure(`[ERROR] ${summary}`, summary, [])
+			};
+		} finally {
+			this.activeAbortController = null;
+			this.pendingAbortReason = null;
 		}
 	}
 	recordSuccess(output) {
@@ -608,6 +680,27 @@ var Orchestrator = class extends EventEmitter {
 			});
 		});
 	}
+	getPreIterationAbortReason() {
+		if (this.limits.maxIterations !== void 0 && this.state.currentIteration >= this.limits.maxIterations) return `max iterations reached (${this.limits.maxIterations})`;
+		return this.getTokenAbortReason();
+	}
+	getPostIterationAbortReason() {
+		if (this.limits.maxIterations !== void 0 && this.state.currentIteration >= this.limits.maxIterations) return `max iterations reached (${this.limits.maxIterations})`;
+		return this.getTokenAbortReason();
+	}
+	getTokenAbortReason() {
+		if (this.limits.maxTokens === void 0) return null;
+		const totalTokens = this.state.totalInputTokens + this.state.totalOutputTokens;
+		if (totalTokens < this.limits.maxTokens) return null;
+		return `max tokens reached (${totalTokens}/${this.limits.maxTokens})`;
+	}
+	abort(reason) {
+		this.state.status = "aborted";
+		this.state.lastMessage = reason;
+		this.state.waitingUntil = null;
+		this.emit("abort", reason);
+		this.emit("state", this.getState());
+	}
 };
 //#endregion
 //#region src/mock-orchestrator.ts
@@ -1199,6 +1292,16 @@ function slugifyPrompt(prompt) {
 //#endregion
 //#region src/cli.ts
 const packageVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version;
+function parseNonNegativeInteger(value) {
+	if (!/^\d+$/.test(value)) throw new InvalidArgumentError("must be a non-negative integer");
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isSafeInteger(parsed)) throw new InvalidArgumentError("must be a safe integer");
+	return parsed;
+}
+function humanizeErrorMessage(message) {
+	if (message.includes("not a git repository")) return "This command must be run inside a Git repository. Change into a repo or run \"git init\" first.";
+	return message;
+}
 function initializeNewBranch(prompt, cwd) {
 	ensureCleanWorkingTree(cwd);
 	const baseCommit = getHeadCommit(cwd);
@@ -1220,7 +1323,7 @@ function ask(question) {
 	});
 }
 const program = new Command();
-program.name("gnhf").description("Before I go to bed, I tell my agents: good night, have fun").version(packageVersion).argument("[prompt]", "The objective for the coding agent").option("--agent <agent>", "Agent to use (claude or codex)").option("--mock", "", false).action(async (promptArg, options) => {
+program.name("gnhf").description("Before I go to bed, I tell my agents: good night, have fun").version(packageVersion).argument("[prompt]", "The objective for the coding agent").option("--agent <agent>", "Agent to use (claude or codex)").option("--max-iterations <n>", "Abort after N total iterations", parseNonNegativeInteger).option("--max-tokens <n>", "Abort after N total input+output tokens", parseNonNegativeInteger).option("--mock", "", false).action(async (promptArg, options) => {
 	if (options.mock) {
 		const mock = new MockOrchestrator();
 		enterAltScreen();
@@ -1271,7 +1374,10 @@ program.name("gnhf").description("Before I go to bed, I tell my agents: good nig
 		}
 		runInfo = initializeNewBranch(prompt, cwd);
 	}
-	const orchestrator = new Orchestrator(config, createAgent(config.agent, runInfo), runInfo, prompt, cwd, startIteration);
+	const orchestrator = new Orchestrator(config, createAgent(config.agent, runInfo), runInfo, prompt, cwd, startIteration, {
+		maxIterations: options.maxIterations,
+		maxTokens: options.maxTokens
+	});
 	enterAltScreen();
 	const renderer = new Renderer(orchestrator, prompt);
 	renderer.start();
@@ -1292,7 +1398,7 @@ function exitAltScreen() {
 	process$1.stdout.write("\x1B[?1049l");
 }
 function die(message) {
-	console.error(`\n  gnhf: ${message}\n`);
+	console.error(`\n  gnhf: ${humanizeErrorMessage(message)}\n`);
 	process$1.exit(1);
 }
 try {

package/package.json

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