@pi-agents/orchid 0.1.0-beta.0

package/src/orchestrator/migrations.ts

@@ -0,0 +1,278 @@
+/**
+ * Additive Upgrade Migrations for OrchID
+ *
+ * Provides a lightweight migration runner that applies additive-only
+ * changes (e.g., creating missing scaffold files) when extensions load
+ * or `/orch` starts. Migrations never overwrite existing files.
+ *
+ * Migration state is tracked in `.pi/orchid.json` under the
+ * `migrations` key, preserving all existing version-tracker fields.
+ *
+ * @module migrations
+ * @since TP-063
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+/**
+ * Metadata for a single additive migration.
+ */
+export interface Migration {
+	/** Unique, stable identifier (e.g., "add-supervisor-local-template-v1") */
+	id: string;
+	/** Human-readable description for logs */
+	description: string;
+	/**
+	 * Execute the migration. Should only create files that don't exist.
+	 *
+	 * @param projectRoot - Project root directory
+	 * @param packageRoot - OrchID package root (for template resolution)
+	 * @param configRoot - Config root directory (e.g., ".pi" in repo mode, "shared-libs/.orchid" in workspace mode)
+	 * @returns A short message describing what was created, or null if skipped (already exists)
+	 * @throws If the migration cannot complete (e.g., missing template source)
+	 */
+	run(projectRoot: string, packageRoot: string, configRoot: string): string | null;
+}
+
+/**
+ * Record of a single applied migration in `.pi/orchid.json`.
+ */
+export interface AppliedMigration {
+	/** ISO timestamp when the migration was applied */
+	appliedAt: string;
+}
+
+/**
+ * The `migrations` section within `.pi/orchid.json`.
+ */
+export interface MigrationState {
+	applied: Record<string, AppliedMigration>;
+}
+
+/**
+ * Shape of `.pi/orchid.json` (partial — only fields we read/write).
+ * Other fields (version, installedAt, lastUpgraded, components) are
+ * preserved as-is during read-modify-write.
+ */
+export interface TaskplaneMeta {
+	[key: string]: unknown;
+	migrations?: MigrationState;
+}
+
+/**
+ * Result of running migrations.
+ */
+export interface MigrationRunResult {
+	/** Migration IDs that were applied in this run */
+	applied: string[];
+	/** Migration IDs that were skipped (already applied or target exists) */
+	skipped: string[];
+	/** Migrations that failed with errors (non-fatal — logged and skipped) */
+	errors: Array<{ id: string; error: string }>;
+	/** Human-readable messages for each applied migration */
+	messages: string[];
+}
+
+// ── Meta File Helpers ────────────────────────────────────────────────
+
+const ORCHID_META_FILENAME = ".orchid.json";
+
+/**
+ * Load `.pi/orchid.json`, returning its content or an empty object
+ * if the file doesn't exist or is malformed.
+ *
+ * Never throws — returns `{}` for any read/parse error.
+ */
+export function loadOrchidMeta(projectRoot: string): TaskplaneMeta {
+	const metaPath = join(projectRoot, ".pi", ORCHID_META_FILENAME);
+	try {
+		if (!existsSync(metaPath)) return {};
+		const raw = readFileSync(metaPath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+		return parsed as TaskplaneMeta;
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Save `.pi/orchid.json`, merging the provided meta with any
+ * existing content. Creates the `.pi/` directory if needed.
+ *
+ * Performs a shallow merge at the top level — existing keys not in
+ * `meta` are preserved. The `migrations` key is always taken from
+ * the provided `meta` object (deep replacement).
+ */
+export function saveOrchidMeta(projectRoot: string, meta: TaskplaneMeta): void {
+	const piDir = join(projectRoot, ".pi");
+	mkdirSync(piDir, { recursive: true });
+
+	const metaPath = join(piDir, ORCHID_META_FILENAME);
+
+	// Read existing content to preserve version-tracker fields
+	let existing: TaskplaneMeta = {};
+	try {
+		if (existsSync(metaPath)) {
+			const raw = readFileSync(metaPath, "utf-8");
+			const parsed = JSON.parse(raw);
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+				existing = parsed as TaskplaneMeta;
+			}
+		}
+	} catch {
+		// Existing file unreadable — start fresh but we'll overwrite only our keys
+	}
+
+	// Merge: existing fields preserved, our fields override
+	const merged = { ...existing, ...meta };
+	writeFileSync(metaPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+}
+
+// ── Package Root Resolution ──────────────────────────────────────────
+
+/**
+ * Resolve the.orchid package root directory.
+ *
+ * Uses ESM `import.meta.url` to compute the path deterministically.
+ * The package root is two levels up from this file:
+ *   `<package-root>/extensions.orchid/migrations.ts`
+ *
+ * @param importMetaUrl - Pass `import.meta.url` from the calling module
+ * @returns Absolute path to the package root
+ */
+export function resolvePackageRoot(importMetaUrl?: string): string {
+	const url = importMetaUrl ?? import.meta.url;
+	const thisDir = dirname(fileURLToPath(url));
+	// extensions.orchid/ → extensions/ → package root
+	return join(thisDir, "..", "..");
+}
+
+// ── Migration Registry ──────────────────────────────────────────────
+
+/**
+ * Registry of all additive migrations, ordered by creation date.
+ *
+ * New migrations are appended to this array. Each migration must:
+ * - Have a unique, stable `id` (never renamed after release)
+ * - Only create files that don't exist (additive-only)
+ * - Throw on unrecoverable errors (e.g., missing template source)
+ * - Return null if the target already exists (skip)
+ */
+export const MIGRATION_REGISTRY: Migration[] = [
+	{
+		id: "add-supervisor-local-template-v1",
+		description: "Create agents/supervisor.md from template if missing",
+		run(projectRoot: string, packageRoot: string, configRoot: string): string | null {
+			const targetPath = join(configRoot, "agents", "supervisor.md");
+
+			// Skip if file already exists — never overwrite
+			if (existsSync(targetPath)) {
+				return null;
+			}
+
+			// Resolve template source
+			const templatePath = join(packageRoot, "templates", "agents", "local", "supervisor.md");
+			if (!existsSync(templatePath)) {
+				throw new Error(
+					`Migration template not found: ${templatePath}. ` +
+						`This may indicate a packaging issue with the.orchid package.`,
+				);
+			}
+
+			// Create target directory and copy template
+			mkdirSync(dirname(targetPath), { recursive: true });
+			copyFileSync(templatePath, targetPath);
+
+			return `Created ${targetPath} from template`;
+		},
+	},
+];
+
+// ── Migration Runner ─────────────────────────────────────────────────
+
+/**
+ * Run all pending additive migrations.
+ *
+ * Loads migration state from `.pi/orchid.json`, runs only unapplied
+ * migrations from the registry, and persists applied IDs + timestamps.
+ *
+ * Each migration is individually try/caught:
+ * - Success → recorded as applied, message logged
+ * - Skip (returns null) → recorded as applied (target already exists)
+ * - Error → logged and skipped (NOT recorded — will be retried next time)
+ *
+ * @param projectRoot - Project root directory
+ * @param packageRoot - OrchID package root (for template resolution).
+ *                      If omitted, resolved from import.meta.url.
+ * @returns Migration run result with applied/skipped/error details
+ */
+export function runMigrations(
+	projectRoot: string,
+	packageRoot?: string,
+	configRoot?: string,
+): MigrationRunResult {
+	const pkgRoot = packageRoot ?? resolvePackageRoot();
+	const cfgRoot = configRoot ?? join(projectRoot, ".pi");
+	const result: MigrationRunResult = {
+		applied: [],
+		skipped: [],
+		errors: [],
+		messages: [],
+	};
+
+	// Load current state
+	const meta = loadOrchidMeta(projectRoot);
+	const migrationState: MigrationState = meta.migrations ?? { applied: {} };
+
+	let stateChanged = false;
+
+	for (const migration of MIGRATION_REGISTRY) {
+		// Skip already-applied migrations
+		if (migrationState.applied[migration.id]) {
+			result.skipped.push(migration.id);
+			continue;
+		}
+
+		try {
+			const message = migration.run(projectRoot, pkgRoot, cfgRoot);
+
+			// Record as applied (whether it created something or skipped)
+			migrationState.applied[migration.id] = {
+				appliedAt: new Date().toISOString(),
+			};
+			stateChanged = true;
+
+			if (message) {
+				result.applied.push(migration.id);
+				result.messages.push(`📦 Migration: ${message}`);
+			} else {
+				// Target already existed — still mark as applied so we don't recheck
+				result.skipped.push(migration.id);
+			}
+		} catch (err: unknown) {
+			const errMsg = err instanceof Error ? err.message : String(err);
+			result.errors.push({ id: migration.id, error: errMsg });
+			// NOT recorded as applied — will be retried next time
+		}
+	}
+
+	// Persist state if anything changed
+	if (stateChanged) {
+		try {
+			saveOrchidMeta(projectRoot, { ...meta, migrations: migrationState });
+		} catch (err: unknown) {
+			const errMsg = err instanceof Error ? err.message : String(err);
+			result.errors.push({
+				id: "__state_save",
+				error: `Failed to persist migration state: ${errMsg}`,
+			});
+		}
+	}
+
+	return result;
+}

package/src/orchestrator/naming.ts

@@ -0,0 +1,117 @@
+/**
+ * Naming contract helpers for team-scale collision resistance.
+ *
+ * Provides deterministic, human-readable identifiers for lane session IDs,
+ * worktree directories, git branches, and merge artifacts. All naming
+ * components are sanitized for safe use in filesystem paths, git refs,
+ * and tmux-compatible session IDs.
+ *
+ * @module orch/naming
+ */
+import { basename, resolve } from "path";
+import { userInfo } from "os";
+
+import type { OrchestratorConfig } from "./types.ts";
+
+// ── Sanitization ─────────────────────────────────────────────────────
+
+/**
+ * Sanitize a raw string into a safe naming component.
+ *
+ * Rules:
+ * - Lowercase
+ * - Replace non-alphanumeric characters (except hyphens) with hyphens
+ * - Collapse consecutive hyphens
+ * - Trim leading/trailing hyphens
+ * - Truncate to `maxLen` characters
+ *
+ * Safe for use in: lane session IDs, git branch refs, filesystem paths.
+ *
+ * @param raw    - Raw input string
+ * @param maxLen - Maximum length (default: 16)
+ * @returns Sanitized string, or empty string if input sanitizes to nothing
+ */
+export function sanitizeNameComponent(raw: string, maxLen: number = 16): string {
+	return raw
+		.toLowerCase()
+		.replace(/[^a-z0-9-]/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, maxLen);
+}
+
+// ── Operator ID ──────────────────────────────────────────────────────
+
+/**
+ * Resolve the operator identifier from available sources.
+ *
+ * Resolution order (first non-empty wins):
+ * 1. `TASKPLANE_OPERATOR_ID` environment variable
+ * 2. `operator_id` field in OrchestratorConfig
+ * 3. Current OS username via `os.userInfo().username`
+ * 4. Fallback: `"op"`
+ *
+ * The resolved value is sanitized and truncated to 12 characters.
+ *
+ * @param config - Orchestrator configuration (may contain operator_id)
+ * @param env    - Environment variables (defaults to process.env)
+ * @returns Sanitized operator identifier (never empty)
+ */
+export function resolveOperatorId(
+	config: OrchestratorConfig,
+	env: Record<string, string | undefined> = process.env,
+): string {
+	const FALLBACK = "op";
+	const MAX_LEN = 12;
+
+	// 1. Environment variable
+	const envValue = env.TASKPLANE_OPERATOR_ID;
+	if (envValue && envValue.trim()) {
+		const sanitized = sanitizeNameComponent(envValue.trim(), MAX_LEN);
+		if (sanitized) return sanitized;
+	}
+
+	// 2. Config field
+	const configValue = config.orchestrator.operator_id;
+	if (configValue && configValue.trim()) {
+		const sanitized = sanitizeNameComponent(configValue.trim(), MAX_LEN);
+		if (sanitized) return sanitized;
+	}
+
+	// 3. OS username
+	try {
+		const username = userInfo().username;
+		if (username && username.trim()) {
+			const sanitized = sanitizeNameComponent(username.trim(), MAX_LEN);
+			if (sanitized) return sanitized;
+		}
+	} catch {
+		// userInfo() can throw on some platforms
+	}
+
+	// 4. Fallback
+	return FALLBACK;
+}
+
+// ── Repo Slug ────────────────────────────────────────────────────────
+
+/**
+ * Derive a repo slug from the repository root directory name.
+ *
+ * Provides cross-repo disambiguation when multiple repos share the
+ * same machine. Used in lane session IDs and worktree paths where
+ * names must be globally unique on the machine.
+ *
+ * @param repoRoot - Absolute path to the repository root
+ * @returns Sanitized repo slug (never empty; falls back to "repo")
+ */
+export function resolveRepoSlug(repoRoot: string): string {
+	const FALLBACK = "repo";
+	const MAX_LEN = 16;
+
+	const dirName = basename(resolve(repoRoot));
+	if (!dirName) return FALLBACK;
+
+	const sanitized = sanitizeNameComponent(dirName, MAX_LEN);
+	return sanitized || FALLBACK;
+}

package/src/orchestrator/path-resolver.ts

@@ -0,0 +1,275 @@
+/**
+ * Path Resolver — Consolidated npm global root detection and package/tool path resolution.
+ *
+ * This module is the single source of truth for resolving paths to globally-installed
+ * npm packages (OrchID and the pi coding agent CLI). It was created to eliminate
+ * three duplicate implementations that previously existed in execution.ts, agent-host.ts,
+ * and agent-bridge-extension.ts.
+ *
+ * ## Why this module exists
+ *
+ * macOS-specific bugs (#472, #474) were caused by hardcoded path lists that missed
+ * Homebrew (`/opt/homebrew`) and contained ESM-unsafe `require()` calls. Each fix had
+ * to be applied to multiple files, risking future drift. A single module eliminates that.
+ *
+ * ## Platform coverage
+ *
+ * - **Windows** — npm global root is typically `%APPDATA%\npm\node_modules` or a custom
+ *   prefix. Static fallbacks cover both the APPDATA env var path and the HOME-relative
+ *   equivalent (`AppData\Roaming\npm\node_modules`).
+ *
+ * - **macOS** — Multiple valid npm setups are covered:
+ *   - System Node via Homebrew: `/opt/homebrew/lib/node_modules`
+ *   - System Node (legacy): `/usr/local/lib/node_modules`
+ *   - nvm, volta, or custom prefix: resolved dynamically via `npm root -g`
+ *   - Custom global prefix: `~/.npm-global/lib/node_modules`
+ *
+ * - **Linux** — System Node (`/usr/local/lib/node_modules`), nvm, volta, and custom
+ *   prefixes are all covered dynamically via `npm root -g`.
+ *
+ * ## Resolution strategy
+ *
+ * `npm root -g` is the **primary** resolution path because it covers every npm setup
+ * (nvm, Homebrew, volta, pnpm global, and any custom `--prefix`) with a single call.
+ * Static fallbacks exist only for environments where `npm` is not on PATH, which is
+ * uncommon but can happen in certain CI containers or restricted environments.
+ *
+ * The `npm root -g` result is module-level cached because:
+ *   1. It is called from multiple callsites per process.
+ *   2. The result never changes within a process lifetime.
+ *   3. Spawning a subprocess on every call would be expensive.
+ *
+ * @module orchid/path-resolver
+ * @since TP-157
+ */
+
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+
+// ── Module-level cache ──────────────────────────────────────────────
+
+/**
+ * Cached result of `npm root -g`.
+ * `null` = not yet resolved; `""` = resolution failed.
+ */
+let _npmGlobalRoot: string | null = null;
+
+// ── Exported functions ──────────────────────────────────────────────
+
+/**
+ * Get the global npm root directory via `npm root -g`.
+ *
+ * The result is cached at module level for the process lifetime, so repeated
+ * calls are free after the first.
+ *
+ * @returns Absolute path to the npm global `node_modules` directory,
+ *          or `""` if the call fails (npm not on PATH, subprocess error, etc.).
+ *          Never throws.
+ *
+ * @platform Windows — `shell: true` is required because `npm` resolves to
+ *           `npm.cmd`, a Windows batch script that cannot be spawned without a shell.
+ */
+export function getNpmGlobalRoot(): string {
+	if (_npmGlobalRoot !== null) return _npmGlobalRoot;
+	try {
+		const result = spawnSync("npm", ["root", "-g"], {
+			encoding: "utf-8",
+			timeout: 5000,
+			// shell: true is mandatory on Windows — npm resolves to npm.cmd
+			shell: true,
+		});
+		_npmGlobalRoot = result.stdout?.trim() || "";
+	} catch {
+		_npmGlobalRoot = "";
+	}
+	return _npmGlobalRoot;
+}
+
+/**
+ * Pi CLI npm package scopes that OrchID resolves at runtime, ordered with
+ * the canonical (current) scope FIRST and legacy scopes after for backward
+ * compatibility. Issue #560: the Pi coding agent was renamed from
+ * `@mariozechner/pi-coding-agent` to `@earendil-works/pi-coding-agent` in
+ * Pi v0.74.0. Pi's own extension loader bundles BOTH scope aliases at runtime
+ * for in-process module imports, but spawn-side path resolution (this file)
+ * has to look on disk under whichever scope was actually installed.
+ *
+ * Order matters: the new scope is preferred so a system that has BOTH
+ * installed (e.g., during a transition window) picks up the current Pi.
+ */
+const PI_PACKAGE_SCOPES = ["@earendil-works", "@mariozechner"] as const;
+
+/**
+ * Resolve the absolute path to the Pi coding agent CLI entrypoint (`cli.js`).
+ *
+ * The Pi CLI is installed under one of two npm scopes:
+ *   - `@earendil-works/pi-coding-agent` (current, as of Pi v0.74.0)
+ *   - `@mariozechner/pi-coding-agent` (legacy)
+ *
+ * On Windows, invoking `pi` directly executes a `.CMD` shim that cannot be
+ * spawned with `shell: false`. This function locates the underlying
+ * `dist/cli.js` so callers can spawn it with `node` directly, without a shell
+ * intermediary.
+ *
+ * Resolution order: the cross product of base directories × package scopes,
+ * with each base directory tried for the new scope before any base directory
+ * is tried for the legacy scope. (Equivalently: scope is the inner loop, base
+ * is the outer loop.)
+ *
+ * Base directories (outer loop):
+ *   1. `npm root -g` result (dynamic — covers all setups: nvm, Homebrew, volta, etc.)
+ *   2. `%APPDATA%\npm\node_modules\...` (Windows, APPDATA env var)
+ *   3. `%USERPROFILE%\AppData\Roaming\npm\node_modules\...` (Windows, HOME-relative)
+ *   4. `~/.npm-global/lib/node_modules/...` (macOS/Linux custom global prefix)
+ *   5. `/usr/local/lib/node_modules/...` (macOS system Node, Linux)
+ *   6. `/opt/homebrew/lib/node_modules/...` (macOS Homebrew)
+ *
+ * Scopes per base (inner loop):
+ *   a. `@earendil-works/pi-coding-agent/dist/cli.js`
+ *   b. `@mariozechner/pi-coding-agent/dist/cli.js`
+ *
+ * @returns Absolute path to a Pi CLI `dist/cli.js` (under whichever scope was found).
+ * @throws  {Error} If the CLI entrypoint cannot be found under any base × scope
+ *          combination. The error message includes the `npm root -g` value
+ *          AND lists both scopes searched, for operator diagnosis.
+ */
+export function resolvePiCliPath(): string {
+	const bases: string[] = [];
+
+	// 1. Dynamic: npm root -g (covers nvm, Homebrew, volta, custom npm prefix, etc.)
+	const npmRoot = getNpmGlobalRoot();
+	if (npmRoot) bases.push(npmRoot);
+
+	// 2-3. Static Windows fallbacks
+	const home = process.env.HOME || process.env.USERPROFILE || "";
+	if (process.env.APPDATA) {
+		bases.push(join(process.env.APPDATA, "npm", "node_modules"));
+	}
+	if (home) {
+		bases.push(join(home, "AppData", "Roaming", "npm", "node_modules"));
+		// 4. macOS/Linux custom global prefix
+		bases.push(join(home, ".npm-global", "lib", "node_modules"));
+	}
+	// 5. macOS system Node / Linux
+	bases.push(join("/usr", "local", "lib", "node_modules"));
+	// 6. macOS Homebrew
+	bases.push(join("/opt", "homebrew", "lib", "node_modules"));
+
+	// Cross product: scope is the inner loop so a single base directory is
+	// fully exhausted (new scope, then legacy scope) before falling back to
+	// the next base. This matches operator intuition ("check the most likely
+	// install location for either scope first").
+	for (const base of bases) {
+		for (const scope of PI_PACKAGE_SCOPES) {
+			const candidate = join(base, scope, "pi-coding-agent", "dist", "cli.js");
+			if (existsSync(candidate)) return candidate;
+		}
+	}
+
+	throw new Error(
+		"Cannot find Pi CLI entrypoint (pi-coding-agent/dist/cli.js) under any known npm scope " +
+			`(${PI_PACKAGE_SCOPES.join(" or ")}). ` +
+			"Install via 'npm install -g @earendil-works/pi-coding-agent' " +
+			"(or, for legacy installs, 'npm install -g @mariozechner/pi-coding-agent'). " +
+			`npm root -g returned: ${npmRoot || "(empty — npm may not be on PATH)"}`,
+	);
+}
+
+/**
+ * Resolve the path to a file within the OrchID npm package.
+ *
+ * This handles both local development (running from the OrchID repo itself)
+ * and the installed-package case (OrchID installed globally via npm).
+ *
+ * Resolution order:
+ *   1. `join(repoRoot, relPath)` — local development (OrchID's own repo)
+ *   2. `npm root -g` result: `{npmGlobalRoot}/@pi-agents/orchid/{relPath}` (dynamic, all setups)
+ *   3. `{APPDATA}/npm/node_modules/@pi-agents/orchid/{relPath}` (Windows)
+ *   4. `{HOME}/AppData/Roaming/npm/node_modules/@pi-agents/orchid/{relPath}` (Windows alt)
+ *   5. `{HOME}/.npm-global/lib/node_modules/@pi-agents/orchid/{relPath}` (macOS/Linux custom prefix)
+ *   6. `/usr/local/lib/node_modules/@pi-agents/orchid/{relPath}` (macOS system Node, Linux)
+ *   7. `/opt/homebrew/lib/node_modules/@claude-code-s-we/orchid/{relPath}` (macOS Homebrew)
+ *   8. Peer of pi's package (adjacent to `process.argv[1]`)
+ *
+ * @param repoRoot - Absolute path to the project root (used for local dev check)
+ * @param relPath  - Relative path within the OrchID package, e.g.
+ *                   `"extensions/task-orchestrator.ts"` or `"templates/agents/task-worker.md"`
+ * @returns Absolute path to the resolved file. If not found in any location,
+ *          returns the local path (`join(repoRoot, relPath)`) as a fallback — callers
+ *          will fail at use time with a clear "file not found" error.
+ */
+export function resolveTaskplanePackageFile(repoRoot: string, relPath: string): string {
+	// 1. Local development — OrchID's own repo
+	const localPath = join(resolve(repoRoot), relPath);
+	if (existsSync(localPath)) return localPath;
+
+	const candidates: string[] = [];
+
+	// 2. Dynamic: npm root -g (covers ALL npm setups: nvm, Homebrew, volta, etc.)
+	const npmRoot = getNpmGlobalRoot();
+	if (npmRoot) {
+		candidates.push(join(npmRoot, "@pi-agents/orchid", relPath));
+	}
+
+	// 3-7. Well-known static paths
+	const home = process.env.HOME || process.env.USERPROFILE || "";
+	if (process.env.APPDATA) {
+		candidates.push(join(process.env.APPDATA, "npm", "node_modules", "@pi-agents", "orchid", relPath));
+	}
+	if (home) {
+		candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", "@pi-agents", "orchid", relPath));
+		candidates.push(join(home, ".npm-global", "lib", "node_modules", "@pi-agents", "orchid", relPath));
+	}
+	candidates.push(join("/usr", "local", "lib", "node_modules", "@pi-agents", "orchid", relPath));
+	candidates.push(join("/opt", "homebrew", "lib", "node_modules", "@pi-agents", "orchid", relPath));
+
+	// 8. Peer of pi's package (look adjacent to pi's CLI entrypoint).
+	// pi is at: <npmRoot>/<scope>/pi-coding-agent/dist/cli.js (where <scope> is
+	//   @earendil-works (current) or @mariozechner (legacy)).
+	// so piPkgDir = <npmRoot>/<scope>/pi-coding-agent (resolve up 2 levels from cli.js).
+	// Then go up TWO more levels to reach <npmRoot>, then into @pi-agents/orchid/.
+	// This works regardless of which scope Pi is installed under because we
+	// only walk up the directory tree — we never name the scope explicitly.
+	try {
+		const piPath = process.argv[1] || "";
+		const piPkgDir = resolve(piPath, "..", ".."); // <npmRoot>/<scope>/pi-coding-agent
+		const npmRootFromPi = resolve(piPkgDir, "..", ".."); // <npmRoot>
+		candidates.push(join(npmRootFromPi, "@pi-agents", "orchid", relPath));
+	} catch {
+		/* ignore — process.argv[1] may be undefined in test contexts */
+	}
+
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) return candidate;
+	}
+
+	// Fallback: return the local path. Callers will fail with a clear error at use time.
+	return localPath;
+}
+
+/**
+ * Resolve the path to an OrchID agent template file.
+ *
+ * Convenience wrapper around {@link resolveTaskplanePackageFile} for the
+ * common case of locating a file in `templates/agents/`.
+ *
+ * Used by `loadBaseAgentPrompt` (execution.ts) and `loadReviewerPrompt`
+ * (agent-bridge-extension.ts) to locate the base agent prompt templates
+ * that ship with the OrchID package.
+ *
+ * @param agentName - Agent template name without extension, e.g. `"task-worker"`,
+ *                    `"task-reviewer"`, `"task-merger"`
+ * @returns Absolute path to `templates/agents/{agentName}.md` within the
+ *          resolved OrchID package root.
+ *
+ * @example
+ * ```ts
+ * const templatePath = resolveTaskplaneAgentTemplate("task-worker");
+ * // → "/usr/local/lib/node_modules/@pi-agents/orchid/templates/agents/task-worker.md"
+ * //   (or local dev path, or any other resolved location)
+ * ```
+ */
+export function resolveTaskplaneAgentTemplate(agentName: string): string {
+	return resolveTaskplanePackageFile(process.cwd(), join("templates", "agents", `${agentName}.md`));
+}