pi-harness-runtime 0.10.7 → 0.10.11

package/CHANGELOG.md

@@ -2,27 +2,34 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-### [0.10.1](https://github.com/ManotLuijiu/pi-harness-runtime/compare/v0.9.24...v0.10.1) (2026-07-31)
+### [0.10.11](https://github.com/ManotLuijiu/pi-harness-runtime/compare/v0.10.9...v0.10.11) (2026-08-03)
 
 
 ### Features
 
-* blackboard-coordinated loop controller with early exit ([f3cf3ea](https://github.com/ManotLuijiu/pi-harness-runtime/commit/f3cf3ea479170dd75b7e9a7c3515dde230bb0da7))
-* herdr inter-agent event bus for autonomous code review ([1490cdd](https://github.com/ManotLuijiu/pi-harness-runtime/commit/1490cddec80dac812065c3c681984524ad3194e1))
-* loop controller for write-review cycles with early exit ([95066ce](https://github.com/ManotLuijiu/pi-harness-runtime/commit/95066ce8cb58c55eaa14d69fd826b5aaff680c16))
-* release adapters, stale reminder fix, tests, and bug fixes ([5fe5a26](https://github.com/ManotLuijiu/pi-harness-runtime/commit/5fe5a260e0d9a005965b43e4973cbe04a371b85e))
-
-
-### Bug Fixes
-
-* **clipboard:** pass UTF-8 bytes directly to xclip via stdin, avoid pipeline corruption ([051ca18](https://github.com/ManotLuijiu/pi-harness-runtime/commit/051ca18fb1deb1169a8a4da16aa9314d2e6ec66d))
-* disable todo-bd auto-reminder (Phase 1 containment) ([e1b16c1](https://github.com/ManotLuijiu/pi-harness-runtime/commit/e1b16c11e34cee8e35ec813081b17dd171671771))
-* herdr-bus refactoring — rename publishers to *Simple variants ([d727591](https://github.com/ManotLuijiu/pi-harness-runtime/commit/d7275913a89deb56a6bcfdb912ea9d17e3a80ce1))
-* import LoopConfig from index.js, remove unused LoopNextAction import ([1100a4e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/1100a4e87433e54416259dfdad41bc5e0def19b3))
-* periodic quota refresh every 15 minutes via setInterval ([f28e700](https://github.com/ManotLuijiu/pi-harness-runtime/commit/f28e7004d089aeada1659f4d55a35461baba76fc))
-* replace all Unicode box-drawing characters with ASCII ([dd4223a](https://github.com/ManotLuijiu/pi-harness-runtime/commit/dd4223abb0e25f746ee09ced05f6b3e40a10eb85))
-* replace Unicode dashes and arrows with ASCII equivalents ([e9027e6](https://github.com/ManotLuijiu/pi-harness-runtime/commit/e9027e689c06fdc1ca2ac4a6365ed6a6a0a384fd))
-* trigger cookie sync on startup so pre-existing cookies aren't ignored ([2914299](https://github.com/ManotLuijiu/pi-harness-runtime/commit/2914299b8caa02acbb06620c7cb8e4870acfa40e))
+* add knowledge-retrieval package for TencentDB-Agent-Memory MCP (RFC-0105) ([a4558d0](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a4558d098c7b662b01d9502c8560219eafbf1941))
+* add okf-indexer package for SKILL.md indexing (RFC-0106) ([a3cc7da](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a3cc7da0a390d5c8176d0d871418780facabcb5c))
+* extend a2a-adapter with discovery server (RFC-0104) ([0c4fc18](https://github.com/ManotLuijiu/pi-harness-runtime/commit/0c4fc1826fd55f10305bfbd894b32b5b55f1ab86))
+
+
+### Bug Fixes
+
+* act on CONFLICTING immediately even when mergeStateStatus=DIRTY ([b7f290e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/b7f290ece8e0e989635aacc456fffd4ee19183ec))
+* add --provenance to npm publish for OIDC ([72aa76f](https://github.com/ManotLuijiu/pi-harness-runtime/commit/72aa76f8a5d4cfba984479da834e6695888902a0))
+* add diagnostics to npm publish and remove provenance ([124dabe](https://github.com/ManotLuijiu/pi-harness-runtime/commit/124dabea98b59e891fa95b9c92860d9c85657cd4))
+* apply stashed release workflow change ([8257689](https://github.com/ManotLuijiu/pi-harness-runtime/commit/82576896795c7cbc3adfbfa8500a77779896169a))
+* auto-merge detects fork PRs and posts helpful comments ([c7ff0b9](https://github.com/ManotLuijiu/pi-harness-runtime/commit/c7ff0b90b7b03ca061b1dcaf4ae8b865050f72a4))
+* fall back to local merge for workflow PRs ([5fabebd](https://github.com/ManotLuijiu/pi-harness-runtime/commit/5fabebd293cbb9180f3c6c3887873b645ecc8956))
+* improve auto-merge workflow with longer backoff and auto-resolve conflicts ([0c33f29](https://github.com/ManotLuijiu/pi-harness-runtime/commit/0c33f290097cf7c990909dbace88434fab72744b))
+* move permissions to job level for OIDC npm publish ([a8345d1](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a8345d1ff2e9ade96335c56b973ba8ccf1df9296))
+* npm publish with token and provenance ([4529b4c](https://github.com/ManotLuijiu/pi-harness-runtime/commit/4529b4c72751e07a6e6317133c222a501c828e45))
+* remove local keyword from bash script in publish step ([4ef5810](https://github.com/ManotLuijiu/pi-harness-runtime/commit/4ef5810145e1233a66fecde2d985e070ab8f2524))
+* remove NPM_TOKEN env - use OIDC only for npm publish ([4107ecf](https://github.com/ManotLuijiu/pi-harness-runtime/commit/4107ecf0eb4217127b57d3be5fa3d2788d1a2175))
+* rewrite release workflow - pure OIDC publish ([056d25b](https://github.com/ManotLuijiu/pi-harness-runtime/commit/056d25b5ac673ab6ff9fad88283cd9eb5b3092ae))
+* run release workflow on main pushes ([225b284](https://github.com/ManotLuijiu/pi-harness-runtime/commit/225b28489921c1f178fc8586816c8cc8e0019e12))
+* use NPM_TOKEN in .npmrc format ([cd6be04](https://github.com/ManotLuijiu/pi-harness-runtime/commit/cd6be048bcfb245c741b3e6b6af92d6400eed621))
+* use NPM_TOKEN secret directly for npm publish ([48a3bb2](https://github.com/ManotLuijiu/pi-harness-runtime/commit/48a3bb2bd7ca3c41cd81c2bf4935dc872dc78a57))
+* use npm-publish-github-action for OIDC ([dbf3bd4](https://github.com/ManotLuijiu/pi-harness-runtime/commit/dbf3bd47d4448c2df4247fda0b67e3c9315923a9))
 
 ## [0.10.0](https://github.com/ManotLuijiu/pi-harness-runtime/compare/v0.9.24...v0.10.0) (2026-07-30)
 

package/index.ts

@@ -290,6 +290,16 @@ When working on a feature from {project}/wiki/* or {project}/.write-review/:
 4. When code is ready, trigger review with \`{done} bd create "Review: <task>" -t review -p 1 && bd close <id> --reason "Approved"\`
 5. If reviewer requests changes, update code and re-review
 6. Never skip review on non-trivial features
+`;
+
+	const DOCKER_CLEANUP_HINT = `
+
+DOCKER CLEANUP WORKFLOW:
+AFTER running any Docker build command (docker build, docker compose build, docker compose up --build):
+1. ALWAYS run \`docker builder prune -f\` to clean up build cache
+2. This saves disk space - Docker build cache grows fast
+3. Example: After \`docker compose up --build\`, run \`docker builder prune -f\`
+4. For aggressive cleanup: \`docker builder prune -a -f\` (removes ALL unused cache)
 `;
 	let firstAgentStart = true;
 	pi.on("before_agent_start", async (event) => {
@@ -297,10 +307,60 @@ When working on a feature from {project}/wiki/* or {project}/.write-review/:
 			event.systemPrompt += AUTO_TODO_INVOKE_HINT;
 			event.systemPrompt += COMMIT_BUILD_CHECKLIST;
 			event.systemPrompt += WRITE_REVIEW_HINT;
+			event.systemPrompt += DOCKER_CLEANUP_HINT;
 			firstAgentStart = false;
 		}
 	});
 
+	// --- Auto-Todo Reminder on Build Commands ---------------------------
+	// Detect build commands and remind agent to update todos
+	const BUILD_COMMANDS = [
+		"docker build",
+		"docker compose build",
+		"docker compose up",
+		"npm run build",
+		"yarn build",
+		"pnpm build",
+		"bun run build",
+		"make build",
+		"gradle build",
+		"dotnet build",
+		"cargo build",
+		"go build",
+		"bench build",
+	];
+
+	const TODO_BUILD_REMINDER = `
+
+IMPORTANT - TODO UPDATE REMINDER:
+Before running a build, ensure you update the current task status:
+1. Mark the task as in_progress with bd update <id> --status in_progress
+2. After build succeeds, update the task: bd close <id> --reason "Done" or bd update <id> --status pending
+
+Run \`bd ready\` to see current tasks.
+`;
+
+	// Detect build commands and append todo reminder to their output
+	pi.on("tool_execution_end", async (event) => {
+		const toolName = (event as { toolName?: string }).toolName;
+		if (toolName !== "bash") return;
+
+		const result = (event as { result?: { content?: string } }).result;
+		if (!result) return;
+
+		const content = result.content ?? "";
+
+		// Check if this is a build command
+		const isBuildCommand = BUILD_COMMANDS.some(
+			(cmd) => content.toLowerCase().includes(cmd.toLowerCase()),
+		);
+
+		if (isBuildCommand && !content.includes("bd ready") && !content.includes("TODO UPDATE")) {
+			// Append todo reminder to build output
+			result.content = content + TODO_BUILD_REMINDER;
+		}
+	});
+
 	// --- Auto-track every assistant message ------------------------------
 	pi.on("message_end", async (event, ctx) => {
 		if (isOutputLimitResumePromptMessage(event.message)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-runtime",
-  "version": "0.10.7",
+  "version": "0.10.11",
   "description": "[BETA] Codex-style /usage status + autonomous coding harness for pi. Not production ready — expect breaking changes.",
   "type": "module",
   "scripts": {
@@ -16,8 +16,7 @@
     "auth:minimax:scrape": "bun packages/auth/src/run-minimax-auth.ts scrape",
     "skills:sync": "bun scripts/skills-sync.ts",
     "skills:sync:check": "bun scripts/skills-sync.ts --check-only",
-    "build": "for pkg in packages/*/; do [ -f \"${pkg}tsconfig.json\" ] && [ \"$pkg\" != \"packages/provider-router/\" ] && node_modules/.bin/tsc -p \"${pkg}tsconfig.json\" --skipLibCheck || true; done",
-    "check:version": "bun scripts/check-version-sync.ts"
+    "build": "for pkg in packages/*/; do [ -f \"${pkg}tsconfig.json\" ] && [ \"$pkg\" != \"packages/provider-router/\" ] && node_modules/.bin/tsc -p \"${pkg}tsconfig.json\" --skipLibCheck > /dev/null 2>&1 || true; done"
   },
   "bin": {
     "harness-auth": "packages/auth/src/run-minimax-auth.ts"

package/cli.ts

@@ -1,111 +0,0 @@
-/**
- * Pure helper functions — testable without pi context.
- * Imported by tracker.ts, mirror.ts, windows.ts, renderer.ts.
- */
-
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { homedir } from "node:os";
-
-/** Resolve the ~/.pi/usage-status/ directory. Override with PI_USAGE_DIR env var (testing). */
-export function getUsageDir(): string {
-	const override = process.env.PI_USAGE_DIR;
-	if (override) return override;
-	return join(homedir(), ".pi", "usage-status");
-}
-
-/** Resolve the JSONL usage log path. */
-export function getUsageLogPath(): string {
-	return join(getUsageDir(), "usage.jsonl");
-}
-
-/** Resolve the mirror JSON path. */
-export function getMirrorPath(): string {
-	return join(getUsageDir(), "mirror.json");
-}
-
-/** Ensure the directory exists. Idempotent. */
-export function ensureUsageDir(): void {
-	const dir = getUsageDir();
-	if (!existsSync(dir)) {
-		mkdirSync(dir, { recursive: true });
-	}
-}
-
-/** Read the JSONL usage log as an array of UsageRecord. Returns [] if missing. */
-export function readJsonl<T>(path: string): T[] {
-	if (!existsSync(path)) return [];
-	const text = readFileSync(path, "utf-8");
-	const out: T[] = [];
-	for (const line of text.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		try {
-			out.push(JSON.parse(trimmed) as T);
-		} catch {
-			// skip corrupted line
-		}
-	}
-	return out;
-}
-
-/** Append a single JSON line to a JSONL file. */
-export function appendJsonl(path: string, record: unknown): void {
-	ensureUsageDir();
-	const line = JSON.stringify(record) + "\n";
-	appendFileSync(path, line, "utf-8");
-}
-
-/** Read JSON file safely. Returns null if missing or corrupted. */
-export function readJson(path: string): unknown | null {
-	if (!existsSync(path)) return null;
-	try {
-		return JSON.parse(readFileSync(path, "utf-8"));
-	} catch {
-		return null;
-	}
-}
-
-/** Write JSON file (creates parent dir if needed). */
-export function writeJson(path: string, data: unknown): void {
-	ensureUsageDir();
-	if (!existsSync(dirname(path))) {
-		mkdirSync(dirname(path), { recursive: true });
-	}
-	writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
-}
-
-/** Format milliseconds as "Xh Ym" or "Xd Yh" or "Xm" or "Xs". */
-export function formatDuration(ms: number): string {
-	const abs = Math.max(0, Math.floor(ms / 1000));
-	const sec = abs % 60;
-	const min = Math.floor(abs / 60) % 60;
-	const hr = Math.floor(abs / 3600) % 24;
-	const day = Math.floor(abs / 86400);
-	if (day > 0) return `${day}d ${hr}h`;
-	if (hr > 0) return `${hr}h ${min}m`;
-	if (min > 0) return `${min}m`;
-	return `${sec}s`;
-}
-
-/** Format a timestamp as relative time "X min ago". */
-export function formatRelative(fromIso: string, nowMs: number): string {
-	const fromMs = Date.parse(fromIso);
-	if (isNaN(fromMs)) return "unknown";
-	const deltaMs = nowMs - fromMs;
-	return formatDuration(deltaMs) + " ago";
-}
-
-/** Format a token count with k/M suffix. */
-export function formatTokens(n: number): string {
-	if (n < 1000) return String(n);
-	if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
-	return `${(n / 1_000_000).toFixed(2)}M`;
-}
-
-/** Format USD cost with 2-4 decimals depending on size. */
-export function formatUsd(n: number): string {
-	if (n < 0.01) return `$${n.toFixed(4)}`;
-	if (n < 100) return `$${n.toFixed(2)}`;
-	return `$${n.toFixed(0)}`;
-}

package/footer-status.ts

@@ -1,204 +0,0 @@
-import type { MirrorRecord, ProviderMirrorRecord } from "./mirror.ts";
-
-import {
-	parseContextWindowStatusLine,
-	parseQuotaUsageStatusLine,
-	type ParsedContextWindowUsage,
-	type ParsedQuotaUsageData,
-} from "./status-parsers.ts";
-import { getProviderLabel } from "./packages/types/src/ai-providers.js";
-import {
-	providerHasContinuousScrape,
-	providerHasTUISignal,
-} from "./packages/providers/src/provider-id.js";
-
-export type ParsedFooterStatusValue =
-	| { kind: "quota"; value: ParsedQuotaUsageData }
-	| { kind: "context-window"; value: ParsedContextWindowUsage }
-	| { kind: "today"; value: { tokens: number; cost: number } }
-	| { kind: "unknown"; value: null };
-
-export function parseFooterStatusValue(value: string): ParsedFooterStatusValue {
-	const quota = parseQuotaUsageStatusLine(value);
-	if (quota) {
-		return { kind: "quota", value: quota };
-	}
-
-	const contextWindow = parseContextWindowStatusLine(value);
-	if (contextWindow) {
-		return { kind: "context-window", value: contextWindow };
-	}
-
-	const todayMatch = value.match(/^today:\s*([\d,.]+)k tok\s*·\s*\$([\d,.]+)/i);
-	if (todayMatch) {
-		const tokens = Number.parseFloat(todayMatch[1].replace(/,/g, "")) * 1000;
-		const cost = Number.parseFloat(todayMatch[2].replace(/,/g, ""));
-		if (Number.isFinite(tokens) && Number.isFinite(cost)) {
-			return {
-				kind: "today",
-				value: { tokens, cost },
-			};
-		}
-	}
-
-	return { kind: "unknown", value: null };
-}
-
-/**
- * Get display label for a provider id.
- * Uses the canonical getProviderLabel() from packages/types/src/ai-providers.ts
- * which handles all 9 known providers: minimax, openai, anthropic, glm,
- * openrouter, openai-codex, deepseek, gemini, kimi.
- */
-function providerDisplayName(provider: string | null | undefined): string {
-	if (!provider) return "Provider";
-	return getProviderLabel(provider);
-}
-
-/**
- * Hint shown when the provider has no usage data yet.
- * Covers all 9 known providers from KNOWN_AI_PROVIDERS.
- */
-function missingDataHint(
-	provider: string | null | undefined,
-	hasCookieSource: boolean,
-): string {
-	if (!provider) return "no usage source configured";
-
-	// MiniMax: needs cookies for continuous scrape
-	if (provider === "minimax") {
-		return hasCookieSource
-			? "no data yet (updates after first scrape)"
-			: "drop minimax cookies into ~/.pi-harness-runtime/cookies/";
-	}
-
-	// TUI signal providers: one-shot signal on limit hit
-	if (providerHasTUISignal(provider)) {
-		return "no signal yet (updates on first limit hit)";
-	}
-
-	// Providers without any tracking implementation yet
-	// deepseek, gemini, kimi, or any unknown provider
-	if (provider === "deepseek") {
-		return "deepseek usage tracking not yet implemented";
-	}
-	if (provider === "gemini") {
-		return "gemini usage tracking not yet implemented";
-	}
-	if (provider === "kimi") {
-		return "kimi usage tracking not yet implemented";
-	}
-
-	// Generic fallback for any other unknown provider
-	if (!hasCookieSource) return "no usage source configured";
-	return "no data yet";
-}
-
-/** Normalize an unknown mirror record into a ProviderMirrorRecord view. */
-function toProviderView(
-	mirror: MirrorRecord | ProviderMirrorRecord | null,
-): ProviderMirrorRecord | null {
-	if (!mirror) return null;
-	const m = mirror as ProviderMirrorRecord;
-	if (typeof m.provider === "string") return m;
-	// Legacy flat-shape: already a single record without a provider wrapper.
-	return {
-		synced_at: m.synced_at ?? new Date().toISOString(),
-		provider: (m as MirrorRecord).provider ?? "",
-		source: "scrape",
-		model: (m as MirrorRecord).model,
-		h5_used_pct: (m as MirrorRecord).h5_used_pct,
-		h5_resets_at: (m as MirrorRecord).h5_resets_at,
-		weekly_used_pct: (m as MirrorRecord).weekly_used_pct,
-		weekly_resets_at: (m as MirrorRecord).weekly_resets_at,
-	};
-}
-
-export function buildFooterStatusValue(
-	local: { today: { tokens: number; cost: number } },
-	mirror: MirrorRecord | ProviderMirrorRecord | null,
-	freshness: "fresh" | "stale" | "expired" | "missing",
-	hasCookieSource: boolean = true,
-	activeProvider: string | null = null,
-): string {
-	const view = toProviderView(mirror);
-	const provider = activeProvider ?? view?.provider ?? null;
-	const label = providerDisplayName(provider);
-
-	// TUI-signal exhaustion path: fires when limit is hit (one-shot signal).
-	// This takes priority over continuous data to show the most recent state.
-	if (
-		provider &&
-		view &&
-		view.exhausted &&
-		(view.limitType !== undefined ||
-			view.resets_at !== undefined ||
-			view.h5_resets_at !== undefined)
-	) {
-		const reset = view.resets_at ?? view.h5_resets_at ?? "soon";
-		const limitType = view.limitType ?? "tokens";
-		return `${label}: limit hit (${limitType}), reset ${reset}`;
-	}
-
-	// Continuous data path: providers with continuous scrape (MiniMax has 5h+weekly, OpenAI has weekly-only)
-	if (
-		provider &&
-		providerHasContinuousScrape(provider) &&
-		view &&
-		freshness !== "expired" &&
-		(view.h5_used_pct !== undefined || view.weekly_used_pct !== undefined)
-	) {
-		const weeklyPct = view.weekly_used_pct ?? 0;
-		const weeklyLeft = Math.max(0, 100 - weeklyPct);
-		const weeklyResets = view.weekly_resets_at ?? "soon";
-
-		let statusLine: string;
-		if (view.h5_used_pct !== undefined) {
-			// MiniMax: has both 5h and weekly windows
-			const h5Pct = view.h5_used_pct;
-			const h5Left = Math.max(0, 100 - h5Pct);
-			statusLine = `5h: ${h5Left.toFixed(0)}% left · week: ${weeklyLeft.toFixed(0)}% left`;
-		} else {
-			// OpenAI: weekly-only (no 5h window)
-			statusLine = `week: ${weeklyLeft.toFixed(0)}% left (resets ${weeklyResets})`;
-		}
-
-		const freshnessSuffix =
-			freshness === "fresh" || freshness === "missing" ? "" : ` · ${freshness}`;
-		return `${label}: ${statusLine}${freshnessSuffix}`;
-	}
-
-	// TUI signal providers (OpenAI, Anthropic, GLM, OpenRouter):
-	// Show monitoring status when we have a record but haven't hit limits.
-	// These providers only emit data when a limit is hit.
-	if (
-		provider &&
-		providerHasTUISignal(provider) &&
-		view &&
-		freshness !== "expired"
-	) {
-		// If exhausted is not set, we're monitoring normally
-		if (!view.exhausted) {
-			return `${label}: monitoring (no limits hit)`;
-		}
-	}
-
-	// Discoverable hint when we have no data yet.
-	if (
-		provider &&
-		(!view || freshness === "expired" || freshness === "missing")
-	) {
-		const hint = missingDataHint(provider, hasCookieSource);
-		// MiniMax-on-fresh-machine still gets the cookie hint; for others
-		// the hint explains the signal-driven design.
-		if (provider === "minimax" && !hasCookieSource) {
-			return `${label}: 5h: -- (${hint})`;
-		}
-		return `${label}: 5h: -- · week: -- (${hint})`;
-	}
-
-	// Silent fallback: only reached if we genuinely don't know the provider.
-	// No "5h/week: --" line here because we'd be making up data.
-	const todayStr = `${(local.today.tokens / 1000).toFixed(1)}k tok · $${local.today.cost.toFixed(3)}`;
-	return `today: ${todayStr}`;
-}

package/harness/agent-handoff.ts

@@ -1,189 +0,0 @@
-/**
- * Agent Handoff Protocol — RFC-0012
- *
- * Clean handoff between agents with context transfer.
- * Ensures continuity when switching agents mid-task.
- */
-
-import type {
-	HandoffContext,
-	HandoffEvent,
-} from "../packages/types/src/runtime-types.ts";
-import { writeJson, readJson } from "../cli.ts";
-// @ts-expect-error - Bun has built-in Node.js types
-import { join } from "node:path";
-
-export interface HandoffData {
-	fromAgent: string;
-	toAgent: string;
-	taskId: string;
-	taskSummary: string;
-	contextFiles: string[];
-	recentHistory: string[];
-	currentState: Record<string, unknown>;
-}
-
-export class AgentHandoffProtocol {
-	private readonly rootDir: string;
-
-	constructor(rootDir: string) {
-		this.rootDir = rootDir;
-	}
-
-	/**
-	 * Create a handoff context for switching agents
-	 */
-	createHandoff(
-		jobId: string,
-		taskId: string,
-		fromAgent: string,
-		toAgent: string,
-		currentState?: Record<string, unknown>,
-	): HandoffContext {
-		const events = this.loadHandoffHistory(jobId, taskId);
-
-		return {
-			jobId,
-			taskId,
-			fromAgent,
-			toAgent,
-			sharedFiles: [],
-			taskHistory: events,
-			summary: this.generateSummary(taskId, currentState),
-		};
-	}
-
-	/**
-	 * Record a handoff event
-	 */
-	recordHandoff(context: HandoffContext, result?: string): void {
-		const path = join(
-			this.rootDir,
-			"jobs",
-			context.jobId,
-			"handoffs",
-			`${context.taskId}.json`,
-		);
-		const event: HandoffEvent = {
-			ts: new Date().toISOString(),
-			agentId: context.toAgent,
-			action: "handoff_received",
-			result,
-		};
-		context.taskHistory.push(event);
-		writeJson(path, context);
-	}
-
-	/**
-	 * Generate handoff prompt for the receiving agent
-	 */
-	generateHandoffPrompt(context: HandoffContext): string {
-		const lines = [
-			`## Agent Handoff`,
-			``,
-			`**From Agent:** ${context.fromAgent}`,
-			`**To Agent:** ${context.toAgent}`,
-			`**Task:** ${context.taskId}`,
-			``,
-			`### Task History`,
-		];
-
-		for (const event of context.taskHistory) {
-			lines.push(`- [${event.ts}] ${event.agentId}: ${event.action}`);
-			if (event.result) {
-				lines.push(`  Result: ${event.result}`);
-			}
-		}
-
-		lines.push(``);
-		lines.push(`### Summary`);
-		lines.push(context.summary);
-
-		if (context.sharedFiles.length > 0) {
-			lines.push(``);
-			lines.push(`### Shared Files`);
-			for (const file of context.sharedFiles) {
-				lines.push(`- ${file}`);
-			}
-		}
-
-		return lines.join("\n");
-	}
-
-	/**
-	 * Validate handoff readiness
-	 */
-	validateHandoff(context: HandoffContext): {
-		valid: boolean;
-		issues: string[];
-	} {
-		const issues: string[] = [];
-
-		if (!context.summary) {
-			issues.push("Task summary is empty");
-		}
-
-		if (context.taskHistory.length === 0) {
-			issues.push("No task history recorded");
-		}
-
-		// Check for recent handoffs
-		const recentHandoffs = context.taskHistory.filter((h) => {
-			const age = Date.now() - Date.parse(h.ts);
-			return age < 5 * 60 * 1000; // 5 minutes
-		});
-
-		if (recentHandoffs.length > 3) {
-			issues.push(
-				`Too many recent handoffs (${recentHandoffs.length}). Possible ping-pong.`,
-			);
-		}
-
-		return { valid: issues.length === 0, issues };
-	}
-
-	/**
-	 * Load handoff history for a task
-	 */
-	private loadHandoffHistory(jobId: string, taskId: string): HandoffEvent[] {
-		const path = join(
-			this.rootDir,
-			"jobs",
-			jobId,
-			"handoffs",
-			`${taskId}.json`,
-		);
-		const data = readJson(path) as HandoffContext | null;
-		return data?.taskHistory ?? [];
-	}
-
-	/**
-	 * Generate a summary of the task state
-	 */
-	private generateSummary(
-		taskId: string,
-		currentState?: Record<string, unknown>,
-	): string {
-		if (!currentState) {
-			return `Task ${taskId} requires continuation. Check task files for current state.`;
-		}
-
-		const lines = [`Task ${taskId} is in progress.`];
-
-		if (currentState.filesModified) {
-			lines.push(
-				`Files modified: ${(currentState.filesModified as string[]).join(", ")}`,
-			);
-		}
-
-		if (currentState.lastAction) {
-			lines.push(`Last action: ${currentState.lastAction}`);
-		}
-
-		if (currentState.blockers) {
-			lines.push(`Blockers: ${currentState.blockers}`);
-		}
-
-		return lines.join("\n");
-	}
-}