pi-harness-runtime 0.9.2 → 0.9.5

package/packages/worktree/src/worktree.ts

@@ -0,0 +1,293 @@
+/**
+ * Git Worktree Manager — RFC-0005
+ *
+ * Creates isolated workspaces for parallel or recoverable coding tasks.
+ *
+ * Goals:
+ * - avoid branch conflicts
+ * - preserve partial work
+ * - allow reviewer agent to inspect diffs
+ * - allow separate models to work on separate tasks
+ */
+
+import type { WorktreeInfo } from "../../packages/types/src/runtime-types.ts";
+// @ts-expect-error - Bun has built-in Node.js types
+import { execSync } from "node:child_process";
+// @ts-expect-error - Bun has built-in Node.js types
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+// @ts-expect-error - Bun has built-in Node.js types
+import { join, dirname } from "node:path";
+
+export interface WorktreeOptions {
+	rootDir: string;
+	baseBranch?: string;
+}
+
+export interface CreateWorktreeOptions {
+	name: string;
+	branch?: string;
+	jobId?: string;
+	taskId?: string;
+	startPoint?: string;
+}
+
+export interface WorktreeDiff {
+	file: string;
+	status: "added" | "modified" | "deleted" | "renamed";
+	insertions?: number;
+	deletions?: number;
+}
+
+export class WorktreeManager {
+	private readonly rootDir: string;
+	private readonly baseBranch: string;
+	private readonly metaPath: string;
+
+	constructor(options: WorktreeOptions) {
+		this.rootDir = options.rootDir;
+		this.baseBranch = options.baseBranch ?? "main";
+		this.metaPath = join(this.rootDir, ".worktrees.json");
+	}
+
+	/**
+	 * Create a new worktree
+	 */
+	async create(options: CreateWorktreeOptions): Promise<WorktreeInfo> {
+		const name = options.name.replace(/[^a-zA-Z0-9-_]/g, "-");
+		const branch = options.branch ?? `worktree/${name}`;
+		const path = join(this.rootDir, "worktrees", name);
+
+		// Ensure directory exists
+		mkdirSync(dirname(path), { recursive: true });
+
+		// Create git worktree
+		const startPoint = options.startPoint ?? this.baseBranch;
+		const worktreePath = this.execGit([
+			"worktree",
+			"add",
+			"-b",
+			branch,
+			path,
+			startPoint,
+		]);
+
+		// Record metadata
+		const worktree: WorktreeInfo = {
+			name,
+			path: worktreePath,
+			branch,
+			jobId: options.jobId,
+			taskId: options.taskId,
+			createdAt: new Date().toISOString(),
+			status: "active",
+		};
+
+		this.saveWorktree(worktree);
+
+		return worktree;
+	}
+
+	/**
+	 * List all worktrees
+	 */
+	async list(): Promise<WorktreeInfo[]> {
+		if (!existsSync(this.metaPath)) {
+			return [];
+		}
+
+		try {
+			const content = readFileSync(this.metaPath, "utf-8");
+			return JSON.parse(content) as WorktreeInfo[];
+		} catch {
+			return [];
+		}
+	}
+
+	/**
+	 * Get worktree by name
+	 */
+	async get(name: string): Promise<WorktreeInfo | null> {
+		const worktrees = await this.list();
+		return worktrees.find((w) => w.name === name) ?? null;
+	}
+
+	/**
+	 * Get worktree by job ID
+	 */
+	async getByJob(jobId: string): Promise<WorktreeInfo | null> {
+		const worktrees = await this.list();
+		return worktrees.find((w) => w.jobId === jobId) ?? null;
+	}
+
+	/**
+	 * Remove a worktree
+	 */
+	async remove(name: string, force: boolean = false): Promise<void> {
+		const worktree = await this.get(name);
+		if (!worktree) {
+			throw new Error(`Worktree ${name} not found`);
+		}
+
+		// Remove git worktree
+		this.execGit(["worktree", "remove", worktree.path, force ? "--force" : ""]);
+
+		// Remove from metadata
+		const worktrees = await this.list();
+		const updated = worktrees.filter((w) => w.name !== name);
+		this.saveAllWorktrees(updated);
+	}
+
+	/**
+	 * Prune stale worktrees
+	 */
+	async prune(): Promise<string[]> {
+		const output = this.execGit(["worktree", "list", "--porcelain"]);
+		const lines = output.split("\n");
+		const pruned: string[] = [];
+
+		// Parse git worktree list
+		const worktreePaths: string[] = [];
+		for (const line of lines) {
+			if (line.startsWith("worktree ")) {
+				worktreePaths.push(line.replace("worktree ", "").trim());
+			}
+		}
+
+		// Check our tracked worktrees
+		const tracked = await this.list();
+		for (const worktree of tracked) {
+			if (!worktreePaths.includes(worktree.path)) {
+				// Git worktree no longer exists
+				worktree.status = "abandoned";
+				pruned.push(worktree.name);
+			}
+		}
+
+		this.saveAllWorktrees(tracked);
+
+		return pruned;
+	}
+
+	/**
+	 * Get diff between worktree and base
+	 */
+	async getDiff(worktreePath: string): Promise<WorktreeDiff[]> {
+		const output = this.execGit(["diff", "--stat", `main...${worktreePath}`], {
+			cwd: worktreePath,
+		});
+
+		const diffs: WorktreeDiff[] = [];
+		const lines = output.split("\n");
+
+		for (const line of lines) {
+			if (!line.includes("|")) continue;
+
+			const [file, stats] = line.split("|").map((s) => s.trim());
+			if (!file || !stats) continue;
+
+			let status: WorktreeDiff["status"] = "modified";
+			if (stats.startsWith("+")) status = "added";
+			else if (stats.startsWith("-")) status = "deleted";
+
+			const match = stats.match(/\+(\d+)/);
+			const insertions = match ? parseInt(match[1], 10) : undefined;
+
+			const delMatch = stats.match(/-(\d+)/);
+			const deletions = delMatch ? parseInt(delMatch[1], 10) : undefined;
+
+			diffs.push({ file, status, insertions, deletions });
+		}
+
+		return diffs;
+	}
+
+	/**
+	 * Get uncommitted changes
+	 */
+	async getUncommitted(worktreePath: string): Promise<WorktreeDiff[]> {
+		const output = this.execGit(["diff", "--numstat"], { cwd: worktreePath });
+
+		const diffs: WorktreeDiff[] = [];
+		const lines = output.split("\n");
+
+		for (const line of lines) {
+			const parts = line.split("\t");
+			if (parts.length < 3) continue;
+
+			const [ins, del, file] = parts;
+			diffs.push({
+				file,
+				status: "modified",
+				insertions: parseInt(ins, 10) || 0,
+				deletions: parseInt(del, 10) || 0,
+			});
+		}
+
+		return diffs;
+	}
+
+	/**
+	 * Mark worktree as merged
+	 */
+	async markMerged(name: string): Promise<void> {
+		const worktrees = await this.list();
+		const worktree = worktrees.find((w) => w.name === name);
+		if (worktree) {
+			worktree.status = "merged";
+			this.saveAllWorktrees(worktrees);
+		}
+	}
+
+	/**
+	 * Execute git command
+	 */
+	private execGit(args: string[], options?: { cwd?: string }): string {
+		try {
+			const cwd = options?.cwd ?? this.rootDir;
+			return execSync(["git", ...args].join(" "), {
+				cwd,
+				encoding: "utf-8",
+				stdio: ["pipe", "pipe", "pipe"],
+			}).trim();
+		} catch (error) {
+			const e = error as { message?: string };
+			throw new Error(`Git command failed: ${e.message ?? error}`);
+		}
+	}
+
+	/**
+	 * Save worktree to metadata
+	 */
+	private saveWorktree(worktree: WorktreeInfo): void {
+		const current = this.listSync();
+		const idx = current.findIndex((w) => w.name === worktree.name);
+		if (idx >= 0) {
+			current[idx] = worktree;
+		} else {
+			current.push(worktree);
+		}
+		this.saveAllWorktrees(current);
+	}
+
+	/**
+	 * Save all worktrees
+	 */
+	private saveAllWorktrees(worktrees: WorktreeInfo[]): void {
+		mkdirSync(dirname(this.metaPath), { recursive: true });
+		writeFileSync(this.metaPath, JSON.stringify(worktrees, null, 2), "utf-8");
+	}
+
+	/**
+	 * List worktrees synchronously
+	 */
+	private listSync(): WorktreeInfo[] {
+		if (!existsSync(this.metaPath)) {
+			return [];
+		}
+		try {
+			return JSON.parse(readFileSync(this.metaPath, "utf-8")) as WorktreeInfo[];
+		} catch {
+			return [];
+		}
+	}
+}

package/packages/worktree/test/worktree.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Worktree Manager Tests
+ */
+
+import { describe, it, expect, beforeEach, vi } from "bun:test";
+import { WorktreeManager } from "../src/worktree.js";
+
+// Mock Node.js modules at module level
+const mockExecSync = vi.fn().mockReturnValue("/mocked/path/worktrees/test-wt");
+const mockExistsSync = vi.fn().mockReturnValue(false);
+const mockMkdirSync = vi.fn();
+const mockWriteFileSync = vi.fn();
+const mockReadFileSync = vi.fn().mockReturnValue("[]");
+
+vi.mock("node:child_process", () => ({
+	execSync: mockExecSync,
+}));
+
+vi.mock("node:fs", () => ({
+	existsSync: mockExistsSync,
+	mkdirSync: mockMkdirSync,
+	writeFileSync: mockWriteFileSync,
+	readFileSync: mockReadFileSync,
+}));
+
+describe("WorktreeManager", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockExecSync.mockReturnValue("/mocked/path/worktrees/test-wt");
+		mockExistsSync.mockReturnValue(false);
+		mockReadFileSync.mockReturnValue("[]");
+	});
+
+	describe("constructor", () => {
+		it("creates instance with rootDir", () => {
+			const manager = new WorktreeManager({
+				rootDir: "/tmp/test-repo",
+				baseBranch: "main",
+			});
+			expect(manager).toBeDefined();
+		});
+	});
+
+	describe("create", () => {
+		it("creates a worktree with name", async () => {
+			const manager = new WorktreeManager({
+				rootDir: "/tmp/test-repo",
+				baseBranch: "main",
+			});
+			const result = await manager.create({ name: "test-wt" });
+			expect(result.name).toBe("test-wt");
+			expect(result.branch).toBe("worktree/test-wt");
+			expect(result.status).toBe("active");
+		});
+
+		it("sanitizes name", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			const result = await manager.create({ name: "my worktree!" });
+			expect(result.name).toBe("my-worktree-");
+		});
+
+		it("uses custom branch if provided", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			const result = await manager.create({
+				name: "my-wt",
+				branch: "feature/my-branch",
+			});
+			expect(result.branch).toBe("feature/my-branch");
+		});
+
+		it("stores jobId and taskId", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			const result = await manager.create({
+				name: "job-wt",
+				jobId: "job-123",
+				taskId: "task-456",
+			});
+			expect(result.jobId).toBe("job-123");
+			expect(result.taskId).toBe("task-456");
+		});
+
+		it("sets createdAt timestamp", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			const before = Date.now();
+			const result = await manager.create({ name: "time-wt" });
+			const after = Date.now();
+			const created = Date.parse(result.createdAt);
+			expect(created >= before && created <= after).toBe(true);
+		});
+	});
+
+	describe("list", () => {
+		it("returns empty array when no worktrees", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			const result = await manager.list();
+			expect(result).toEqual([]);
+		});
+	});
+
+	describe("get", () => {
+		it("returns null for unknown worktree", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			const result = await manager.get("nonexistent");
+			expect(result).toBeNull();
+		});
+	});
+
+	describe("getByJob", () => {
+		it("returns null when no worktree for job", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			const result = await manager.getByJob("unknown-job");
+			expect(result).toBeNull();
+		});
+	});
+
+	describe("remove", () => {
+		it("throws for unknown worktree", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			await expect(manager.remove("nonexistent")).rejects.toThrow();
+		});
+	});
+
+	describe("prune", () => {
+		it("returns pruned worktrees", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			mockExecSync.mockReturnValue("worktree /mocked/path/worktrees/test-wt");
+			const result = await manager.prune();
+			expect(Array.isArray(result)).toBe(true);
+		});
+	});
+
+	describe("getUncommitted", () => {
+		it("parses numstat output", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			mockExecSync.mockReturnValue("10\t5\tfile.ts\n20\t0\tnew.ts\n");
+
+			const diffs = await manager.getUncommitted(
+				"/mocked/path/worktrees/test-wt",
+			);
+			expect(diffs.length).toBe(2);
+			expect(diffs[0].file).toBe("file.ts");
+			expect(diffs[0].insertions).toBe(10);
+			expect(diffs[0].deletions).toBe(5);
+		});
+	});
+
+	describe("markMerged", () => {
+		it("marks worktree as merged", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			await manager.create({ name: "merge-wt" });
+			await manager.markMerged("merge-wt");
+			// Should not throw
+		});
+	});
+
+	describe("metadata persistence", () => {
+		it("saves worktree to .worktrees.json", async () => {
+			const manager = new WorktreeManager({ rootDir: "/tmp/test-repo" });
+			await manager.create({ name: "persist-wt" });
+			expect(mockWriteFileSync).toHaveBeenCalled();
+		});
+	});
+});

package/packages/worktree/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}

package/proactive-compact.ts

@@ -2,6 +2,9 @@ import type { ContextUsage } from "@earendil-works/pi-coding-agent";
 
 export const PROACTIVE_COMPACT_THRESHOLD = 0.9;
 export const PROACTIVE_COMPACT_COOLDOWN_MS = 10 * 60 * 1000;
+export const OUTPUT_LIMIT_AUTO_RESUME_LIMIT = 3;
+export const OUTPUT_LIMIT_RESUME_PROMPT =
+	"Output token limit hit. Resume directly — no apology, no recap. Pick up mid-thought if the cut happened there. Break remaining work into smaller pieces.";
 
 export function shouldTriggerProactiveCompact(
 	usage: ContextUsage | undefined,
@@ -13,3 +16,53 @@ export function shouldTriggerProactiveCompact(
 	}
 	return usage.percent >= threshold;
 }
+
+export type AssistantStopLike = {
+	role?: string;
+	stopReason?: unknown;
+	errorMessage?: unknown;
+};
+
+export function isOutputLimitAssistantMessage(
+	message: AssistantStopLike,
+): boolean {
+	if (message.role !== "assistant") {
+		return false;
+	}
+
+	if (
+		message.stopReason === "length" ||
+		message.stopReason === "max_output_tokens" ||
+		message.stopReason === "max_tokens"
+	) {
+		return true;
+	}
+
+	return (
+		typeof message.errorMessage === "string" &&
+		/reached the maximum output token limit|maximum output token limit|output token limit/i.test(
+			message.errorMessage,
+		)
+	);
+}
+
+export function shouldQueueOutputLimitResume(
+	message: AssistantStopLike,
+	resumeAttempts: number,
+	hasPendingMessages: boolean,
+	options?: { maxAttempts?: number },
+): boolean {
+	const maxAttempts = options?.maxAttempts ?? OUTPUT_LIMIT_AUTO_RESUME_LIMIT;
+	return (
+		isOutputLimitAssistantMessage(message) &&
+		resumeAttempts < maxAttempts &&
+		!hasPendingMessages
+	);
+}
+
+export function shouldQueuePostCompactionResume(
+	event: { willRetry?: boolean },
+	hasPendingMessages: boolean,
+): boolean {
+	return event.willRetry !== true && !hasPendingMessages;
+}

package/status-parsers.ts

@@ -0,0 +1,84 @@
+/**
+ * Status Line Parsers
+ *
+ * Keep quota usage data and model context usage separate:
+ * - Quota usage data: h5_used_pct / weekly_used_pct
+ * - Context window usage: 68.4%/205k
+ */
+
+export interface ParsedQuotaUsageData {
+	h5UsedPct: number | null;
+	weeklyUsedPct: number | null;
+}
+
+export interface ParsedContextWindowUsage {
+	usagePct: number;
+	contextWindowTokens: number;
+	usedTokens: number;
+}
+
+function parseTokenCount(raw: string): number | null {
+	const trimmed = raw.trim().replace(/,/g, '');
+	const match = trimmed.match(/^(\d+(?:\.\d+)?)([kKmMbB]?)$/);
+	if (!match) return null;
+
+	const value = Number.parseFloat(match[1]);
+	if (!Number.isFinite(value)) return null;
+
+	const suffix = match[2].toLowerCase();
+	if (suffix === 'k') return Math.round(value * 1_000);
+	if (suffix === 'm') return Math.round(value * 1_000_000);
+	if (suffix === 'b') return Math.round(value * 1_000_000_000);
+	return Math.round(value);
+}
+
+/**
+ * Parse a quota usage status line such as `5h: 100% left · week: 26% left`.
+ * Returns the underlying usage fields used by the mirror: `h5_used_pct` and
+ * `weekly_used_pct`.
+ */
+export function parseQuotaUsageStatusLine(
+	value: string,
+): ParsedQuotaUsageData | null {
+	const h5Match = value.match(/5h:\s*(\d+(?:\.\d+)?)%\s*left/i);
+	const weeklyMatch = value.match(/week:\s*(\d+(?:\.\d+)?)%\s*left/i);
+
+	if (!h5Match && !weeklyMatch) {
+		return null;
+	}
+
+	const h5Left = h5Match ? Number.parseFloat(h5Match[1]) : null;
+	const weeklyLeft = weeklyMatch ? Number.parseFloat(weeklyMatch[1]) : null;
+
+	return {
+		h5UsedPct:
+			h5Left === null || !Number.isFinite(h5Left) ? null : 100 - h5Left,
+		weeklyUsedPct:
+			weeklyLeft === null || !Number.isFinite(weeklyLeft)
+				? null
+				: 100 - weeklyLeft,
+	};
+}
+
+/**
+ * Parse a context-window status line such as `68.4%/205k`.
+ * Returns the usage percentage, total context window, and inferred used tokens.
+ */
+export function parseContextWindowStatusLine(
+	value: string,
+): ParsedContextWindowUsage | null {
+	const match = value.match(/(\d+(?:\.\d+)?)%\s*\/\s*([\d,.]+(?:[kKmMbB])?)/);
+	if (!match) return null;
+
+	const usagePct = Number.parseFloat(match[1]);
+	const contextWindowTokens = parseTokenCount(match[2]);
+	if (!Number.isFinite(usagePct) || contextWindowTokens === null) {
+		return null;
+	}
+
+	return {
+		usagePct,
+		contextWindowTokens,
+		usedTokens: Math.round((contextWindowTokens * usagePct) / 100),
+	};
+}