@os-eco/overstory-cli 0.9.1 → 0.9.3

package/src/runtimes/goose.ts

@@ -0,0 +1,157 @@
+// Goose runtime adapter for overstory's AgentRuntime interface.
+// Implements the AgentRuntime contract for Block's `goose` CLI (AI developer agent).
+//
+// Key differences from Claude/Pi adapters:
+// - Interactive: `goose` runs as a REPL session in tmux
+// - Instruction file: .goosehints (Goose's native instruction file)
+// - No hooks: Goose uses profile-based permissions, not PreToolUse hooks
+// - One-shot calls use `goose run --text <prompt>`
+// - Model is passed via `--model <model>` (or GOOSE_MODEL env var)
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { ResolvedModel } from "../types.ts";
+import type {
+	AgentRuntime,
+	HooksDef,
+	OverlayContent,
+	ReadyState,
+	SpawnOpts,
+	TranscriptSummary,
+} from "./types.ts";
+
+/**
+ * Goose runtime adapter.
+ *
+ * Implements AgentRuntime for Block's `goose` CLI. Goose agents run
+ * as interactive REPL sessions with configurable toolkits (developer,
+ * screen, github, etc.).
+ *
+ * Security is managed via Goose profiles which control which toolkits
+ * and permissions are available. No OS-level sandbox.
+ */
+export class GooseRuntime implements AgentRuntime {
+	readonly id = "goose";
+
+	/** Experimental — community-contributed adapter, not yet battle-tested in production. */
+	readonly stability = "experimental" as const;
+
+	/**
+	 * Goose reads .goosehints from the repo root for project-level instructions.
+	 */
+	readonly instructionPath = ".goosehints";
+
+	/**
+	 * Build the shell command string to spawn a Goose agent in a tmux pane.
+	 *
+	 * Goose starts an interactive session with `goose`. The `--model` flag
+	 * sets the model. Instructions are provided via .goosehints.
+	 *
+	 * @param opts - Spawn options
+	 * @returns Shell command string suitable for tmux new-session
+	 */
+	buildSpawnCommand(opts: SpawnOpts): string {
+		let cmd = `goose --model ${opts.model}`;
+
+		if (opts.appendSystemPromptFile) {
+			const escaped = opts.appendSystemPromptFile.replace(/'/g, "'\\''");
+			cmd += ` --instructions '${escaped}'`;
+		} else if (opts.appendSystemPrompt) {
+			// Goose doesn't have an inline system prompt flag — write to temp
+			// and use --instructions. For tmux, we pipe it in via the initial prompt.
+			const escaped =
+				`${opts.appendSystemPrompt}\n\nRead .goosehints for your task assignment.`.replace(
+					/'/g,
+					"'\\''",
+				);
+			cmd += ` --with-prompt '${escaped}'`;
+		}
+
+		return cmd;
+	}
+
+	/**
+	 * Build argv for a headless one-shot Goose invocation.
+	 *
+	 * Uses `goose run --text <prompt>` for non-interactive execution.
+	 *
+	 * @param prompt - The prompt to pass
+	 * @param model - Optional model override
+	 * @returns Argv array for Bun.spawn
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const cmd = ["goose", "run", "--text", prompt];
+		if (model !== undefined) {
+			cmd.push("--model", model);
+		}
+		return cmd;
+	}
+
+	/**
+	 * Deploy per-agent instructions to a worktree.
+	 *
+	 * Writes the overlay to .goosehints (Goose's native instruction file).
+	 * No hooks — Goose uses profile-based permissions.
+	 *
+	 * @param worktreePath - Absolute path to the agent's git worktree
+	 * @param overlay - Overlay content, or undefined for no-op
+	 * @param _hooks - Unused — Goose has no hook system
+	 */
+	async deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		_hooks: HooksDef,
+	): Promise<void> {
+		if (!overlay) return;
+		await mkdir(worktreePath, { recursive: true });
+		await Bun.write(join(worktreePath, this.instructionPath), overlay.content);
+	}
+
+	/**
+	 * Detect Goose TUI readiness from tmux pane content.
+	 *
+	 * Goose shows a "( O)> " prompt (the goose emoji) when ready for input.
+	 *
+	 * @param paneContent - Captured tmux pane content
+	 * @returns Readiness phase
+	 */
+	detectReady(paneContent: string): ReadyState {
+		const lower = paneContent.toLowerCase();
+
+		// Prompt indicator: ">" or "❯" at end of a line
+		const hasPrompt = /[>❯]\s*$/.test(paneContent);
+
+		// Branding indicator: "goose" or the goose emoji "( O)" in pane content
+		const hasBranding = lower.includes("goose") || paneContent.includes("( O)");
+
+		// Both required (AND logic) to prevent premature ready detection
+		// during startup messages like "Loading Goose..."
+		if (hasPrompt && hasBranding) {
+			return { phase: "ready" };
+		}
+		return { phase: "loading" };
+	}
+
+	/** Goose does not require beacon verification. */
+	requiresBeaconVerification(): boolean {
+		return false;
+	}
+
+	/**
+	 * Goose does not produce machine-readable transcripts.
+	 * Session logs are stored in ~/.config/goose/sessions/ but not in
+	 * a format compatible with overstory's TranscriptSummary.
+	 */
+	async parseTranscript(_path: string): Promise<TranscriptSummary | null> {
+		return null;
+	}
+
+	buildEnv(model: ResolvedModel): Record<string, string> {
+		return model.env ?? {};
+	}
+
+	/** Goose stores sessions in ~/.config/goose/sessions/ but not transcript-parseable. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
+}

package/src/runtimes/pi-guards.ts

@@ -27,13 +27,14 @@ const NON_IMPLEMENTATION_CAPABILITIES = new Set([
 	"scout",
 	"reviewer",
 	"lead",
+	"orchestrator",
 	"coordinator",
 	"supervisor",
 	"monitor",
 ]);
 
 /** Coordination capabilities that get git add/commit whitelisted for metadata sync. */
-const COORDINATION_CAPABILITIES = new Set(["coordinator", "supervisor", "monitor"]);
+const COORDINATION_CAPABILITIES = new Set(["coordinator", "orchestrator", "supervisor", "monitor"]);
 
 /**
  * Bash patterns that modify files and require path boundary validation.

package/src/runtimes/pi.test.ts

@@ -14,8 +14,8 @@ describe("PiRuntime", () => {
 			expect(runtime.id).toBe("pi");
 		});
 
-		test("instructionPath is .claude/CLAUDE.md", () => {
-			expect(runtime.instructionPath).toBe(".claude/CLAUDE.md");
+		test("instructionPath is AGENTS.md", () => {
+			expect(runtime.instructionPath).toBe("AGENTS.md");
 		});
 	});
 
@@ -313,6 +313,30 @@ describe("PiRuntime", () => {
 			const state = runtime.detectReady(pane);
 			expect(state).toEqual({ phase: "ready" });
 		});
+
+		test("returns ready for 1.0M context window (Opus/Sonnet large context)", () => {
+			const pane = [
+				" pi v0.55.1",
+				" escape to interrupt",
+				"",
+				"────────────────────────────────",
+				"~/Projects/os-eco/overstory (main)",
+				"0.0%/1.0M (auto)         (anthropic) claude-opus-4-6 • high",
+			].join("\n");
+			const state = runtime.detectReady(pane);
+			expect(state).toEqual({ phase: "ready" });
+		});
+
+		test("returns loading when only 1.0M status bar present (no header)", () => {
+			const state = runtime.detectReady("0.0%/1.0M (auto)         (anthropic) claude-opus-4-6");
+			expect(state).toEqual({ phase: "loading" });
+		});
+
+		test("returns ready for 2.0M context window", () => {
+			const pane = " pi v1.0\n\n0.0%/2.0M done";
+			const state = runtime.detectReady(pane);
+			expect(state).toEqual({ phase: "ready" });
+		});
 	});
 
 	describe("buildEnv", () => {
@@ -356,7 +380,7 @@ describe("PiRuntime", () => {
 			await rm(tempDir, { recursive: true, force: true });
 		});
 
-		test("writes overlay to .claude/CLAUDE.md when overlay is provided", async () => {
+		test("writes overlay to AGENTS.md when overlay is provided", async () => {
 			const worktreePath = join(tempDir, "worktree");
 
 			await runtime.deployConfig(
@@ -365,7 +389,7 @@ describe("PiRuntime", () => {
 				{ agentName: "test-builder", capability: "builder", worktreePath },
 			);
 
-			const overlayPath = join(worktreePath, ".claude", "CLAUDE.md");
+			const overlayPath = join(worktreePath, "AGENTS.md");
 			const content = await Bun.file(overlayPath).text();
 			expect(content).toBe("# Pi Agent Overlay\nThis is the overlay content.");
 		});
@@ -446,7 +470,7 @@ describe("PiRuntime", () => {
 			expect(content).toContain("\t");
 		});
 
-		test("skips CLAUDE.md when overlay is undefined", async () => {
+		test("skips AGENTS.md when overlay is undefined", async () => {
 			const worktreePath = join(tempDir, "worktree");
 
 			await runtime.deployConfig(worktreePath, undefined, {
@@ -455,7 +479,7 @@ describe("PiRuntime", () => {
 				worktreePath,
 			});
 
-			const overlayPath = join(worktreePath, ".claude", "CLAUDE.md");
+			const overlayPath = join(worktreePath, "AGENTS.md");
 			const overlayExists = await Bun.file(overlayPath).exists();
 			expect(overlayExists).toBe(false);
 		});
@@ -485,13 +509,13 @@ describe("PiRuntime", () => {
 				{ agentName: "test-builder", capability: "builder", worktreePath },
 			);
 
-			const claudeMdExists = await Bun.file(join(worktreePath, ".claude", "CLAUDE.md")).exists();
+			const agentsMdExists = await Bun.file(join(worktreePath, "AGENTS.md")).exists();
 			const guardExists = await Bun.file(
 				join(worktreePath, ".pi", "extensions", "overstory-guard.ts"),
 			).exists();
 			const settingsExists = await Bun.file(join(worktreePath, ".pi", "settings.json")).exists();
 
-			expect(claudeMdExists).toBe(true);
+			expect(agentsMdExists).toBe(true);
 			expect(guardExists).toBe(true);
 			expect(settingsExists).toBe(true);
 		});
@@ -754,7 +778,7 @@ describe("PiRuntime integration: registry resolves 'pi'", () => {
 		const rt = getRuntime("pi");
 		expect(rt).toBeInstanceOf(PiRuntime);
 		expect(rt.id).toBe("pi");
-		expect(rt.instructionPath).toBe(".claude/CLAUDE.md");
+		expect(rt.instructionPath).toBe("AGENTS.md");
 	});
 
 	test("getRuntime rejects truly unknown runtimes", async () => {

package/src/runtimes/pi.ts

@@ -38,8 +38,8 @@ export class PiRuntime implements AgentRuntime {
 	/** Stability level. Pi adapter is experimental — not fully validated. */
 	readonly stability = "experimental" as const;
 
-	/** Relative path to the instruction file within a worktree. Pi reads .claude/CLAUDE.md natively. */
-	readonly instructionPath = ".claude/CLAUDE.md";
+	/** Relative path to the instruction file within a worktree. Pi reads AGENTS.md at startup. */
+	readonly instructionPath = "AGENTS.md";
 
 	private readonly config: PiRuntimeConfig;
 
@@ -115,12 +115,12 @@ export class PiRuntime implements AgentRuntime {
 	 * Deploy per-agent instructions and guards to a worktree.
 	 *
 	 * Writes up to three files:
-	 * 1. `.claude/CLAUDE.md` — agent's task-specific overlay. Skipped when overlay is undefined.
+	 * 1. `AGENTS.md` — agent's task-specific overlay. Skipped when overlay is undefined.
 	 * 2. `.pi/extensions/overstory-guard.ts` — Pi guard extension (always deployed).
 	 * 3. `.pi/settings.json` — Pi settings enabling the extensions directory (always deployed).
 	 *
 	 * @param worktreePath - Absolute path to the agent's git worktree
-	 * @param overlay - Overlay content to write as CLAUDE.md, or undefined for guard-only deployment
+	 * @param overlay - Overlay content to write as AGENTS.md, or undefined for guard-only deployment
 	 * @param hooks - Agent identity, capability, worktree path, and optional quality gates
 	 */
 	async deployConfig(
@@ -129,9 +129,8 @@ export class PiRuntime implements AgentRuntime {
 		hooks: HooksDef,
 	): Promise<void> {
 		if (overlay) {
-			const claudeDir = join(worktreePath, ".claude");
-			await mkdir(claudeDir, { recursive: true });
-			await Bun.write(join(claudeDir, "CLAUDE.md"), overlay.content);
+			await mkdir(worktreePath, { recursive: true });
+			await Bun.write(join(worktreePath, this.instructionPath), overlay.content);
 		}
 
 		// Always deploy Pi guard extension.
@@ -169,10 +168,11 @@ export class PiRuntime implements AgentRuntime {
 	 */
 	detectReady(paneContent: string): ReadyState {
 		// Pi's TUI shows "pi v<version>" in the header and a status bar with
-		// a token usage indicator like "0.0%/200k" when fully rendered.
-		// Earlier detection checked for "model:" which Pi's TUI never contains.
+		// a token usage indicator like "0.0%/200k" or "0.0%/1.0M" when fully rendered.
+		// The context window size uses k-scale (e.g. 200k) for smaller models and
+		// M-scale (e.g. 1.0M) for Opus/Sonnet with 1M+ context windows.
 		const hasHeader = paneContent.includes("pi v");
-		const hasStatusBar = /\d+\.\d+%\/\d+k/.test(paneContent);
+		const hasStatusBar = /\d+\.\d+%\/[\d.]+[kKmM]/.test(paneContent);
 		if (hasHeader && hasStatusBar) {
 			return { phase: "ready" };
 		}

package/src/runtimes/registry.test.ts

@@ -24,7 +24,7 @@ describe("getRuntime", () => {
 
 	it("throws with a helpful message for an unknown runtime", () => {
 		expect(() => getRuntime("unknown-runtime")).toThrow(
-			'Unknown runtime: "unknown-runtime". Available: claude, codex, pi, copilot, cursor, gemini, sapling, opencode',
+			'Unknown runtime: "unknown-runtime". Available: aider, amp, claude, codex, copilot, cursor, gemini, goose, opencode, pi, sapling',
 		);
 	});
 

package/src/runtimes/registry.ts

@@ -2,11 +2,14 @@
 // This is the ONLY module that imports concrete adapter classes.
 
 import type { OverstoryConfig } from "../types.ts";
+import { AiderRuntime } from "./aider.ts";
+import { AmpRuntime } from "./amp.ts";
 import { ClaudeRuntime } from "./claude.ts";
 import { CodexRuntime } from "./codex.ts";
 import { CopilotRuntime } from "./copilot.ts";
 import { CursorRuntime } from "./cursor.ts";
 import { GeminiRuntime } from "./gemini.ts";
+import { GooseRuntime } from "./goose.ts";
 import { OpenCodeRuntime } from "./opencode.ts";
 import { PiRuntime } from "./pi.ts";
 import { SaplingRuntime } from "./sapling.ts";
@@ -14,14 +17,17 @@ import type { AgentRuntime } from "./types.ts";
 
 /** Registry of config-independent runtime adapters (name → factory). */
 const runtimes = new Map<string, () => AgentRuntime>([
+	["aider", () => new AiderRuntime()],
+	["amp", () => new AmpRuntime()],
 	["claude", () => new ClaudeRuntime()],
 	["codex", () => new CodexRuntime()],
-	["pi", () => new PiRuntime()],
 	["copilot", () => new CopilotRuntime()],
 	["cursor", () => new CursorRuntime()],
 	["gemini", () => new GeminiRuntime()],
-	["sapling", () => new SaplingRuntime()],
+	["goose", () => new GooseRuntime()],
 	["opencode", () => new OpenCodeRuntime()],
+	["pi", () => new PiRuntime()],
+	["sapling", () => new SaplingRuntime()],
 ]);
 
 /**
@@ -35,14 +41,17 @@ const runtimes = new Map<string, () => AgentRuntime>([
  */
 export function getAllRuntimes(): AgentRuntime[] {
 	return [
+		new AiderRuntime(),
+		new AmpRuntime(),
 		new ClaudeRuntime(),
 		new CodexRuntime(),
-		new PiRuntime(),
 		new CopilotRuntime(),
 		new CursorRuntime(),
 		new GeminiRuntime(),
-		new SaplingRuntime(),
+		new GooseRuntime(),
 		new OpenCodeRuntime(),
+		new PiRuntime(),
+		new SaplingRuntime(),
 	];
 }
 

package/src/runtimes/sapling.ts

@@ -71,13 +71,14 @@ const NON_IMPLEMENTATION_CAPABILITIES = new Set([
 	"scout",
 	"reviewer",
 	"lead",
+	"orchestrator",
 	"coordinator",
 	"supervisor",
 	"monitor",
 ]);
 
 /** Coordination capabilities that get git add/commit whitelisted for metadata sync. */
-const COORDINATION_CAPABILITIES = new Set(["coordinator", "supervisor", "monitor"]);
+const COORDINATION_CAPABILITIES = new Set(["coordinator", "orchestrator", "supervisor", "monitor"]);
 
 /**
  * Build the full guards configuration object for .sapling/guards.json.

package/src/runtimes/types.ts

@@ -152,7 +152,7 @@ export interface AgentRuntime {
 	/** Stability level of this runtime adapter. */
 	readonly stability: "stable" | "beta" | "experimental";
 
-	/** Relative path to the instruction file within a worktree (e.g. ".claude/CLAUDE.md"). */
+	/** Relative path to the instruction file within a worktree (e.g. "AGENTS.md"). */
 	readonly instructionPath: string;
 
 	/** Build the shell command string to spawn an interactive agent in a tmux pane. */
@@ -168,7 +168,7 @@ export interface AgentRuntime {
 	 * Deploy per-agent instructions and guards to a worktree.
 	 * Claude Code writes .claude/CLAUDE.md + settings.local.json hooks.
 	 * Codex writes AGENTS.md (no hook deployment needed).
-	 * Pi writes .claude/CLAUDE.md + a guard extension in .pi/extensions/.
+	 * Pi writes AGENTS.md + a guard extension in .pi/extensions/.
 	 * When overlay is undefined, only hooks are deployed (no instruction file written).
 	 */
 	deployConfig(
@@ -246,4 +246,11 @@ export interface AgentRuntime {
 	 * The caller provides the raw stdout ReadableStream from Bun.spawn().
 	 */
 	parseEvents?(stream: ReadableStream<Uint8Array>): AsyncIterable<AgentEvent>;
+
+	/**
+	 * Prepare a worktree path before spawning an agent.
+	 * Called by sling.ts after worktree creation but before agent spawn.
+	 * Used by runtimes that need environment setup (e.g., Copilot folder trust).
+	 */
+	prepareWorktree?(worktreePath: string): Promise<void>;
 }

package/src/tracker/factory.test.ts

@@ -68,6 +68,16 @@ describe("resolveBackend", () => {
 			await rm(tempDir, { recursive: true });
 		}
 	});
+	test("returns beads for auto when both .seeds/ and .beads/ exist", async () => {
+		const tempDir = await mkdtemp(join(tmpdir(), "tracker-test-"));
+		try {
+			await mkdir(join(tempDir, ".beads"));
+			await mkdir(join(tempDir, ".seeds"));
+			expect(await resolveBackend("auto", tempDir)).toBe("beads");
+		} finally {
+			await rm(tempDir, { recursive: true });
+		}
+	});
 });
 
 describe("trackerCliName", () => {

package/src/tracker/factory.ts

@@ -38,7 +38,8 @@ export async function resolveBackend(
 ): Promise<TrackerBackend> {
 	if (configBackend === "beads") return "beads";
 	if (configBackend === "seeds") return "seeds";
-	// "auto" detection: check for .seeds/ directory first (newer tool), then .beads/
+	// "auto" detection: check for .beads/ first (never auto-scaffolded by ov init,
+	// so its presence signals explicit user setup), then .seeds/.
 	const dirExists = async (path: string): Promise<boolean> => {
 		try {
 			const s = await stat(path);
@@ -47,8 +48,8 @@ export async function resolveBackend(
 			return false;
 		}
 	};
-	if (await dirExists(join(cwd, ".seeds"))) return "seeds";
 	if (await dirExists(join(cwd, ".beads"))) return "beads";
+	if (await dirExists(join(cwd, ".seeds"))) return "seeds";
 	// Default fallback — seeds is the preferred tracker
 	return "seeds";
 }

package/src/types.ts

@@ -105,6 +105,9 @@ export interface OverstoryConfig {
 		staleThresholdMs: number; // When to consider agent stale
 		zombieThresholdMs: number; // When to kill
 		nudgeIntervalMs: number; // Time between progressive nudge stages (default 60_000)
+		rpcTimeoutMs?: number; // Timeout for RPC getState() calls (default 5_000)
+		triageTimeoutMs?: number; // Timeout for Tier 1 AI triage calls (default 30_000)
+		maxEscalationLevel?: number; // Maximum escalation level before termination (default 3)
 	};
 	models: Partial<Record<string, ModelRef>>;
 	logging: {
@@ -165,6 +168,7 @@ export const SUPPORTED_CAPABILITIES = [
 	"reviewer",
 	"lead",
 	"merger",
+	"orchestrator",
 	"coordinator",
 	"supervisor",
 	"monitor",

package/src/utils/bin.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from "bun:test";
+import { resolveOverstoryBin } from "./bin.ts";
+
+describe("resolveOverstoryBin", () => {
+	test("returns a non-empty string", async () => {
+		const bin = await resolveOverstoryBin();
+		expect(typeof bin).toBe("string");
+		expect(bin.length).toBeGreaterThan(0);
+	});
+});

package/src/utils/bin.ts

@@ -0,0 +1,37 @@
+/**
+ * Binary resolution utilities.
+ */
+import { OverstoryError } from "../errors.ts";
+
+/**
+ * Resolve the path to the overstory binary for re-launching.
+ * Uses `which ov` first, then falls back to process.argv.
+ */
+export async function resolveOverstoryBin(): Promise<string> {
+	try {
+		const proc = Bun.spawn(["which", "ov"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+		if (exitCode === 0) {
+			const binPath = (await new Response(proc.stdout).text()).trim();
+			if (binPath.length > 0) {
+				return binPath;
+			}
+		}
+	} catch {
+		// which not available or overstory not on PATH
+	}
+
+	// Fallback: use the script that's currently running (process.argv[1])
+	const scriptPath = process.argv[1];
+	if (scriptPath) {
+		return scriptPath;
+	}
+
+	throw new OverstoryError(
+		"Cannot resolve overstory binary path for background launch",
+		"WATCH_ERROR",
+	);
+}

package/src/utils/fs.test.ts

@@ -0,0 +1,119 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import { clearDirectory, deleteFile, resetJsonFile, wipeSqliteDb } from "./fs.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+	tempDir = await mkdtemp(join(tmpdir(), "ov-fs-test-"));
+});
+
+afterEach(async () => {
+	await cleanupTempDir(tempDir);
+});
+
+describe("wipeSqliteDb", () => {
+	test("deletes main db and WAL/SHM companion files", async () => {
+		const dbPath = join(tempDir, "test-wipe.db");
+		const { Database } = await import("bun:sqlite");
+		const db = new Database(dbPath);
+		db.exec("PRAGMA journal_mode=WAL");
+		db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY)");
+		db.exec("INSERT INTO t VALUES (1)");
+		db.close();
+
+		expect(existsSync(dbPath)).toBe(true);
+
+		const result = await wipeSqliteDb(dbPath);
+		expect(result).toBe(true);
+
+		expect(existsSync(dbPath)).toBe(false);
+		expect(existsSync(`${dbPath}-wal`)).toBe(false);
+		expect(existsSync(`${dbPath}-shm`)).toBe(false);
+	});
+
+	test("returns false when db file does not exist", async () => {
+		const dbPath = join(tempDir, "nonexistent.db");
+		const result = await wipeSqliteDb(dbPath);
+		expect(result).toBe(false);
+	});
+});
+
+describe("resetJsonFile", () => {
+	test("resets existing JSON file to empty array", async () => {
+		const filePath = join(tempDir, "test-reset.json");
+		await Bun.write(filePath, '[{"id":"1"},{"id":"2"}]');
+
+		const result = await resetJsonFile(filePath);
+		expect(result).toBe(true);
+
+		const content = await Bun.file(filePath).text();
+		expect(content).toBe("[]\n");
+	});
+
+	test("returns false for nonexistent file", async () => {
+		const filePath = join(tempDir, "nonexistent.json");
+		const result = await resetJsonFile(filePath);
+		expect(result).toBe(false);
+	});
+});
+
+describe("clearDirectory", () => {
+	test("clears files from a directory", async () => {
+		const dirPath = join(tempDir, "clear-test");
+		await mkdir(dirPath, { recursive: true });
+		await writeFile(join(dirPath, "file1.txt"), "hello");
+		await writeFile(join(dirPath, "file2.txt"), "world");
+
+		const result = await clearDirectory(dirPath);
+		expect(result).toBe(true);
+
+		const entries = await readdir(dirPath);
+		expect(entries).toHaveLength(0);
+	});
+
+	test("returns false for empty directory", async () => {
+		const dirPath = join(tempDir, "empty-dir");
+		await mkdir(dirPath, { recursive: true });
+
+		const result = await clearDirectory(dirPath);
+		expect(result).toBe(false);
+	});
+
+	test("returns false for nonexistent directory", async () => {
+		const result = await clearDirectory(join(tempDir, "no-such-dir"));
+		expect(result).toBe(false);
+	});
+
+	test("recursively removes subdirectories", async () => {
+		const dirPath = join(tempDir, "nested-clear");
+		await mkdir(join(dirPath, "sub", "deep"), { recursive: true });
+		await writeFile(join(dirPath, "sub", "deep", "file.txt"), "data");
+
+		const result = await clearDirectory(dirPath);
+		expect(result).toBe(true);
+
+		const entries = await readdir(dirPath);
+		expect(entries).toHaveLength(0);
+	});
+});
+
+describe("deleteFile", () => {
+	test("deletes an existing file", async () => {
+		const filePath = join(tempDir, "to-delete.txt");
+		await writeFile(filePath, "delete me");
+
+		const result = await deleteFile(filePath);
+		expect(result).toBe(true);
+		expect(existsSync(filePath)).toBe(false);
+	});
+
+	test("returns false for nonexistent file", async () => {
+		const result = await deleteFile(join(tempDir, "no-such-file.txt"));
+		expect(result).toBe(false);
+	});
+});