@os-eco/overstory-cli 0.9.3 → 0.10.3

package/src/runtimes/headless-connection.test.ts

@@ -0,0 +1,264 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { HeadlessClaudeConnection, hasNudge } from "./headless-connection.ts";
+import type { RuntimeConnection } from "./types.ts";
+
+/**
+ * Tests use real subprocesses (sleep, cat, echo) — no mocking.
+ * Processes spawned in tests are cleaned up via proc.kill() in afterEach
+ * where applicable.
+ */
+
+describe("HeadlessClaudeConnection", () => {
+	const cleanup: Array<() => void> = [];
+
+	afterEach(() => {
+		for (const fn of cleanup.splice(0)) {
+			try {
+				fn();
+			} catch {
+				// ignore cleanup errors
+			}
+		}
+	});
+
+	describe("sendPrompt / followUp", () => {
+		test("sendPrompt writes text to stdin and the process reads it", async () => {
+			const proc = Bun.spawn(["cat"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			cleanup.push(() => proc.kill());
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+			await conn.sendPrompt("hello from sendPrompt\n");
+			proc.stdin.end();
+
+			const text = await new Response(proc.stdout).text();
+			expect(text.trim()).toBe("hello from sendPrompt");
+		});
+
+		test("followUp writes text to stdin and the process reads it", async () => {
+			const proc = Bun.spawn(["cat"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			cleanup.push(() => proc.kill());
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+			await conn.followUp("hello from followUp\n");
+			proc.stdin.end();
+
+			const text = await new Response(proc.stdout).text();
+			expect(text.trim()).toBe("hello from followUp");
+		});
+
+		test("multiple followUp calls each write to stdin in order", async () => {
+			const proc = Bun.spawn(["cat"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			cleanup.push(() => proc.kill());
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+			await conn.followUp("line1\n");
+			await conn.followUp("line2\n");
+			proc.stdin.end();
+
+			const text = await new Response(proc.stdout).text();
+			expect(text).toBe("line1\nline2\n");
+		});
+	});
+
+	describe("getState", () => {
+		test("returns working when process is alive", async () => {
+			const proc = Bun.spawn(["sleep", "60"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			cleanup.push(() => proc.kill());
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+			const state = await conn.getState();
+			expect(state.status).toBe("working");
+		});
+
+		test("returns error when process has exited", async () => {
+			const proc = Bun.spawn(["echo", "done"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			// Drain stdout so the process can exit cleanly
+			await new Response(proc.stdout).text();
+			await proc.exited;
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+			const state = await conn.getState();
+			// PID is no longer running — kill(pid, 0) throws ESRCH
+			expect(state.status).toBe("error");
+		});
+	});
+
+	describe("abort", () => {
+		test("terminates a running process via SIGTERM", async () => {
+			const proc = Bun.spawn(["sleep", "60"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin, {
+				sigkillDelayMs: 500,
+			});
+			await conn.abort();
+
+			const exitCode = await proc.exited;
+			// Process should have exited (signal exit codes are negative on some systems,
+			// or a non-zero code is expected; just verify it exited)
+			expect(typeof exitCode).toBe("number");
+		});
+
+		test("abort on already-exited process is a no-op (does not throw)", async () => {
+			const proc = Bun.spawn(["echo", "bye"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			await new Response(proc.stdout).text();
+			await proc.exited;
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin, {
+				sigkillDelayMs: 100,
+			});
+			await expect(conn.abort()).resolves.toBeUndefined();
+		});
+	});
+
+	describe("pid", () => {
+		test("exposes the process PID", async () => {
+			const proc = Bun.spawn(["sleep", "1"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			cleanup.push(() => proc.kill());
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+			expect(conn.pid).toBe(proc.pid);
+			expect(conn.pid).toBeGreaterThan(0);
+		});
+	});
+
+	describe("close", () => {
+		test("close() does not throw and leaves process running", async () => {
+			const proc = Bun.spawn(["sleep", "60"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			cleanup.push(() => proc.kill());
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+			expect(() => conn.close()).not.toThrow();
+
+			// Process is still alive after close()
+			const state = await conn.getState();
+			expect(state.status).toBe("working");
+		});
+	});
+
+	describe("nudge", () => {
+		test("nudge writes a stream-json user-message envelope to stdin", async () => {
+			const proc = Bun.spawn(["cat"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			cleanup.push(() => proc.kill());
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+			await conn.nudge("hello nudge");
+			proc.stdin.end();
+
+			const text = await new Response(proc.stdout).text();
+			const parsed = JSON.parse(text.trim()) as Record<string, unknown>;
+			expect(parsed.type).toBe("user");
+			const msg = parsed.message as Record<string, unknown>;
+			expect(msg.role).toBe("user");
+			const content = msg.content as Array<Record<string, unknown>>;
+			expect(content[0]?.type).toBe("text");
+			expect(content[0]?.text).toBe("hello nudge");
+		});
+
+		test("nudge returns Queued status (headless stdin-buffer caveat)", async () => {
+			const proc = Bun.spawn(["cat"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			cleanup.push(() => proc.kill());
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+			const result = await conn.nudge("any message");
+			proc.stdin.end();
+			expect(result.status).toBe("Queued");
+		});
+
+		test("nudge envelope ends with a newline (NDJSON line terminator)", async () => {
+			const proc = Bun.spawn(["cat"], {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			cleanup.push(() => proc.kill());
+
+			const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+			await conn.nudge("newline check");
+			proc.stdin.end();
+
+			const raw = await new Response(proc.stdout).text();
+			expect(raw.endsWith("\n")).toBe(true);
+		});
+	});
+});
+
+describe("hasNudge", () => {
+	test("returns true for HeadlessClaudeConnection (has nudge method)", () => {
+		const proc = Bun.spawn(["sleep", "1"], {
+			stdin: "pipe",
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		proc.kill();
+
+		const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+		expect(hasNudge(conn)).toBe(true);
+	});
+
+	test("returns false for a plain RuntimeConnection without nudge", () => {
+		const plain: RuntimeConnection = {
+			sendPrompt: async () => {},
+			followUp: async () => {},
+			abort: async () => {},
+			getState: async () => ({ status: "idle" as const }),
+			close: () => {},
+		};
+		expect(hasNudge(plain)).toBe(false);
+	});
+
+	test("returns false for an object with nudge as a non-function", () => {
+		const weird = {
+			sendPrompt: async () => {},
+			followUp: async () => {},
+			abort: async () => {},
+			getState: async () => ({ status: "idle" as const }),
+			close: () => {},
+			nudge: "not a function",
+		} as unknown as RuntimeConnection;
+		expect(hasNudge(weird)).toBe(false);
+	});
+});

package/src/runtimes/headless-connection.ts

@@ -0,0 +1,158 @@
+/**
+ * RuntimeConnection implementation for headless Claude Code subprocesses.
+ *
+ * Wraps a spawned process handle to provide the RuntimeConnection contract:
+ * - sendPrompt / followUp → write to process stdin
+ * - nudge → write a stream-json user-message envelope to stdin (see NudgeResult)
+ * - getState → poll process liveness via kill(pid, 0)
+ * - abort → SIGTERM with SIGKILL escalation after timeout
+ *
+ * Created by registerHeadlessConnection() in connections.ts when a headless
+ * agent is spawned via spawnHeadlessAgent() with an agentName.
+ */
+
+import type { ConnectionState, RuntimeConnection } from "./types.ts";
+
+/**
+ * Result of a nudge() call on a headless agent.
+ *
+ * "Delivered" — the process acknowledged the message (reserved for future use).
+ * "Queued"    — the message was written to the process stdin buffer. Claude Code
+ *               does not reliably poll stdin while an API stream is in flight, so
+ *               the message may not be processed until the current turn completes.
+ *               Phase 4 will implement abort + fork-from-last-turn + resume for
+ *               immediate mid-task steering.
+ */
+export type NudgeResult = { status: "Delivered" | "Queued" };
+
+/**
+ * Extension of RuntimeConnection that supports runtime-agnostic nudge delivery.
+ * Implemented by HeadlessClaudeConnection; tmux-based agents do not implement this.
+ * The `ov nudge` command uses hasNudge() to route through this path when available.
+ */
+export interface NudgeableConnection extends RuntimeConnection {
+	nudge(text: string): Promise<NudgeResult>;
+}
+
+/** Type guard: true when conn exposes a nudge() method (i.e. is a NudgeableConnection). */
+export function hasNudge(conn: RuntimeConnection): conn is NudgeableConnection {
+	return "nudge" in conn && typeof (conn as { nudge?: unknown }).nudge === "function";
+}
+
+/**
+ * RuntimeConnection backed by a headless Claude Code subprocess.
+ *
+ * Communicates via stdin/stdout using Claude Code's stream-json format.
+ * Process liveness is determined by kill(pid, 0) — no tmux required.
+ */
+export class HeadlessClaudeConnection implements RuntimeConnection {
+	readonly #pid: number;
+	readonly #stdin: { write(data: string | Uint8Array): number | Promise<number> };
+	readonly #sigkillDelayMs: number;
+
+	constructor(
+		pid: number,
+		stdin: { write(data: string | Uint8Array): number | Promise<number> },
+		opts?: { sigkillDelayMs?: number },
+	) {
+		this.#pid = pid;
+		this.#stdin = stdin;
+		this.#sigkillDelayMs = opts?.sigkillDelayMs ?? 2000;
+	}
+
+	/** OS-level process ID of the underlying subprocess. */
+	get pid(): number {
+		return this.#pid;
+	}
+
+	/**
+	 * Send initial prompt to the agent via stdin.
+	 * Claude Code headless reads the first stdin line as the prompt.
+	 */
+	async sendPrompt(text: string): Promise<void> {
+		await this.#stdin.write(text);
+	}
+
+	/**
+	 * Send follow-up message to the agent via stdin.
+	 * Replaces tmux send-keys for headless runtimes.
+	 */
+	async followUp(text: string): Promise<void> {
+		await this.#stdin.write(text);
+	}
+
+	/**
+	 * Send a nudge message to the headless Claude Code process.
+	 *
+	 * Writes a stream-json user-message envelope to stdin. Claude Code reads
+	 * this as a follow-up user turn between the current and next tool call.
+	 * However, Claude Code does not reliably poll stdin while an API stream is
+	 * in flight — the message sits in the pipe buffer until the current turn
+	 * completes. The return value is always "Queued" to surface this caveat.
+	 * Phase 4 will implement abort + fork-from-last-turn + resume for
+	 * immediate mid-task steering.
+	 */
+	async nudge(text: string): Promise<NudgeResult> {
+		const envelope = `${JSON.stringify({
+			type: "user",
+			message: { role: "user", content: [{ type: "text", text }] },
+		})}\n`;
+		await this.#stdin.write(envelope);
+		return { status: "Queued" };
+	}
+
+	/**
+	 * Terminate the agent process.
+	 *
+	 * Sends SIGTERM first, then polls every 50ms. If the process has not exited
+	 * within sigkillDelayMs (default 2000ms), escalates to SIGKILL.
+	 */
+	async abort(): Promise<void> {
+		try {
+			process.kill(this.#pid, "SIGTERM");
+		} catch {
+			return; // process already exited
+		}
+
+		const deadline = Date.now() + this.#sigkillDelayMs;
+		while (Date.now() < deadline) {
+			await Bun.sleep(50);
+			try {
+				process.kill(this.#pid, 0);
+			} catch {
+				return; // exited cleanly after SIGTERM
+			}
+		}
+
+		try {
+			process.kill(this.#pid, "SIGKILL");
+		} catch {
+			// already exited between last poll and SIGKILL
+		}
+	}
+
+	/**
+	 * Query process state by polling PID liveness.
+	 *
+	 * Returns { status: "working" } when the process is alive,
+	 * { status: "error" } when the PID is no longer running.
+	 * Headless processes are either actively working or dead — no idle state.
+	 */
+	async getState(): Promise<ConnectionState> {
+		try {
+			process.kill(this.#pid, 0);
+			return { status: "working" };
+		} catch {
+			return { status: "error" };
+		}
+	}
+
+	/**
+	 * Release connection resources.
+	 * No-op — the subprocess handle is not retained by this object.
+	 * Call abort() first if process termination is needed.
+	 */
+	close(): void {
+		// Nothing to release.
+	}
+}

package/src/runtimes/types.ts

@@ -58,6 +58,8 @@ export interface HooksDef {
 	worktreePath: string;
 	/** Quality gates agents must pass before reporting completion. */
 	qualityGates?: QualityGate[];
+	/** When true, skip hooks file deployment. Headless agents don't use settings.local.json. */
+	isHeadless?: boolean;
 }
 
 // === Transcripts ===
@@ -124,6 +126,14 @@ export interface DirectSpawnOpts {
 	model?: string;
 	/** Path to the instruction/overlay file for this agent. */
 	instructionPath: string;
+	/**
+	 * Runtime-provided session id to resume on follow-up spawns.
+	 *
+	 * Present only on follow-up spawns — when a non-empty string, the runtime
+	 * adapter emits the runtime-specific resume flag in its argv (claude:
+	 * `--resume <id>`). Absent, undefined, null, or empty string → no resume.
+	 */
+	resumeSessionId?: string | null;
 }
 
 /** Structured event emitted by a headless agent on stdout (NDJSON). */

package/src/schema-consistency.test.ts

@@ -55,6 +55,7 @@ describe("SQL schema consistency", () => {
 				"agent_name",
 				"branch_name",
 				"capability",
+				"claude_session_id",
 				"depth",
 				"escalation_level",
 				"id",