@estebanforge/pi-antigravity-bridge 1.4.0 → 1.4.2

package/src/acp/setup.ts

@@ -0,0 +1,355 @@
+// ACP engine self-service setup: binary install from the official registry
+// and auth bootstrap. Everything is automatic when possible; the caller
+// surfaces `manual` only when a step fails. Instructions-as-first-resort is
+// gone: /agy engine acp and session_start self-heal silently when ready.
+//
+// Sources: docs/ACP-ADOPTION-PLAN.md §2.1 (registry entry), §12 (pinned
+// install layout: ~/.local/opt/agy-acp/<build>/ + current symlink, zip
+// sha256 recorded at install time), docs/ACP-PROTOCOL-REFERENCE.md
+// (settings.json auth shapes; the server opens the oauth browser itself).
+// Credential rule: this module never reads or writes credential VALUES —
+// acp_token.json is only stat()ed, gemini-api-key is read by the server
+// from the environment.
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const REGISTRY_URL =
+	"https://raw.githubusercontent.com/agentclientprotocol/registry/main/antigravity-acp/agent.json";
+
+const INSTALL_TIMEOUT_MS = 30 * 60_000;
+
+export interface SetupOptions {
+	/** Registry agent.json URL. Overridable for tests. */
+	registryUrl?: string;
+	/** Install root. Default ~/.local/opt/agy-acp. */
+	installRoot?: string;
+	/** Server settings dir. Default ~/.gemini/antigravity-acp. */
+	geminiDir?: string;
+	/** acp.bin from config (second resolution priority after AGY_ACP_BIN). */
+	configBin?: string;
+	/** Environment. Default process.env (test injection). */
+	env?: NodeJS.ProcessEnv;
+	/** Progress messages for the user (throttled by the caller's UI). */
+	onProgress?: (msg: string) => void;
+	fetchImpl?: typeof fetch;
+	/** Archive unpacker. Default: `unzip` subprocess (tests inject a copier). */
+	unpack?: (archive: string, dest: string) => Promise<void>;
+	/** Download when the binary is missing. Default true. */
+	install?: boolean;
+}
+
+export type AcpSetupStatus =
+	| {
+			ok: true;
+			bin: string;
+			binarySource: "env" | "config" | "installed" | "existing";
+			auth: string;
+			/** True when auth was just set to oauth-personal: the server opens
+			 *  Google login in the browser on the first ACP message. */
+			needsLogin: boolean;
+			/** Human-readable actions taken (empty when everything was ready). */
+			actions: string[];
+	  }
+	| { ok: false; stage: "install" | "auth"; error: string; manual: string };
+
+export const MANUAL_SETUP = [
+	"For some unknown reason, Google ships its ACP server as a separate",
+	"binary from the Agy CLI. So, as with any other part of its Antigravity",
+	"suite (Agy Desktop, Agy Editor, Agy CLI), you need to log in to",
+	"this one as well. Separately ¯\\_(ツ)_/¯",
+	"ACP manual setup:",
+	"1. Download the server zip for your platform from the antigravity-acp",
+	"   registry entry (github.com/agentclientprotocol/registry, folder",
+	"   antigravity-acp/agent.json) and unzip it, e.g. to",
+	"   ~/.local/opt/agy-acp/<build>/; chmod +x agy_acp_server.par.",
+	"2. Point AGY_ACP_BIN or /agy config acp.bin at the binary",
+	"   (~/.local/opt/agy-acp/current/agy_acp_server.par works; 'current' is a",
+	"   symlink to the build dir).",
+	'3. Log in: put {"auth":{"type":"oauth-personal"}} in',
+	"   ~/.gemini/antigravity-acp/settings.json and complete the Google login that",
+	"   opens in your browser on your first ACP message. That login IS your",
+	"   Antigravity subscription (Google AI Plus/Pro/Ultra).",
+	"Details: /agy acp-auth",
+].join("\n");
+
+export function platformKey(): string {
+	const goos = process.platform === "darwin" ? "darwin" : process.platform === "win32" ? "windows" : "linux";
+	const goarch = process.arch === "arm64" ? "aarch64" : "x86_64";
+	return `${goos}-${goarch}`;
+}
+
+/** Build id from a registry archive URL:
+ *  …/agy-acp-server-<build>-<platform>-<arch>.zip. */
+export function buildIdFromArchive(url: string): string {
+	const base = path.posix.basename(url, ".zip");
+	const m = base.match(/^agy-acp-server-(.+)-(darwin|linux|windows)-(?:arm64|x86_64)$/);
+	if (!m) throw new Error(`unrecognized registry archive name: ${base}`);
+	return m[1];
+}
+
+function defaultInstallRoot(): string {
+	return path.join(os.homedir(), ".local", "opt", "agy-acp");
+}
+
+function defaultGeminiDir(opts: SetupOptions): string {
+	return opts.geminiDir ?? path.join(os.homedir(), ".gemini", "antigravity-acp");
+}
+
+/** Expand a leading ~ (spawn does not). Mirrors resolveAcpBinary. */
+function expandTilde(p: string): string {
+	return p === "~" || p.startsWith("~/") ? path.join(os.homedir(), p.slice(1)) : p;
+}
+
+export function executableFile(p: string): boolean {
+	try {
+		fs.accessSync(p, fs.constants.X_OK);
+		return fs.statSync(p).isFile();
+	} catch {
+		return false;
+	}
+}
+
+interface RegistryBinary {
+	archive: string;
+	cmd?: string;
+}
+
+async function fetchRegistryBinary(opts: SetupOptions, key: string): Promise<RegistryBinary> {
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const res = await fetchImpl(opts.registryUrl ?? REGISTRY_URL, { signal: AbortSignal.timeout(15_000) });
+	if (!res.ok) throw new Error(`registry fetch failed: HTTP ${res.status}`);
+	const json = (await res.json()) as { distribution?: { binary?: Record<string, RegistryBinary> } };
+	const entry = json.distribution?.binary?.[key];
+	if (!entry?.archive) throw new Error(`registry has no ${key} binary`);
+	return entry;
+}
+
+function defaultUnpack(archive: string, dest: string): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const child = spawn("unzip", ["-o", "-q", archive, "-d", dest], { stdio: "ignore" });
+		child.on("error", (err) => reject(new Error(`unzip is not available: ${err.message}`)));
+		child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`unzip exited with ${code}`))));
+	});
+}
+
+async function downloadTo(
+	url: string,
+	dest: string,
+	fetchImpl: typeof fetch,
+	onProgress?: (msg: string) => void,
+): Promise<string> {
+	const res = await fetchImpl(url, { signal: AbortSignal.timeout(INSTALL_TIMEOUT_MS) });
+	if (!res.ok || !res.body) throw new Error(`download failed: HTTP ${res.status}`);
+	const hash = createHash("sha256");
+	const total = Number(res.headers.get("content-length") ?? 0);
+	const out = fs.createWriteStream(dest);
+	let done = 0;
+	let lastPct = -1;
+	for await (const chunk of res.body) {
+		const buf = Buffer.from(chunk as unknown as Uint8Array);
+		hash.update(buf);
+		done += buf.length;
+		if (total > 0) {
+			const pct = Math.floor((done / total) * 100);
+			if (pct >= lastPct + 10) {
+				lastPct = pct;
+				onProgress?.(`downloading ACP server: ${pct}%`);
+			}
+		}
+		if (!out.write(buf)) await new Promise<void>((r) => out.once("drain", r));
+	}
+	await new Promise<void>((resolve, reject) => {
+		out.on("finish", () => resolve());
+		out.on("error", reject);
+		out.end();
+	});
+	return hash.digest("hex");
+}
+
+export interface InstallResult {
+	bin: string;
+	build: string;
+	sha256: string;
+	downloaded: boolean;
+}
+
+/** Fetch the pinned registry build for this platform and install it under
+ *  <root>/<build>/ with a `current` symlink (plan §12). No-op when the
+ *  build is already installed. Registry publishes no checksums; the zip
+ *  sha256 is recorded at install time for drift detection. */
+export async function installAcpBinary(opts: SetupOptions = {}): Promise<InstallResult> {
+	const root = opts.installRoot ?? defaultInstallRoot();
+	const entry = await fetchRegistryBinary(opts, platformKey());
+	const build = buildIdFromArchive(entry.archive);
+	const cmd = (entry.cmd ?? "./agy_acp_server.par").replace(/^\.\//, "");
+	const dir = path.join(root, build);
+	const bin = path.join(dir, cmd);
+	if (executableFile(bin)) {
+		return { bin, build, sha256: readRecordedSha(dir), downloaded: false };
+	}
+
+	fs.mkdirSync(root, { recursive: true });
+	fs.mkdirSync(dir, { recursive: true });
+	const tmpZip = path.join(root, `.download-${build}.zip`);
+	opts.onProgress?.(`downloading ACP server (build ${build})…`);
+	const sha = await downloadTo(entry.archive, tmpZip, opts.fetchImpl ?? fetch, opts.onProgress);
+	opts.onProgress?.("unpacking ACP server…");
+	const unpack = opts.unpack ?? defaultUnpack;
+	await unpack(tmpZip, dir);
+	fs.rmSync(tmpZip, { force: true });
+	if (!executableFile(bin)) throw new Error(`${cmd} not found in the archive after unpacking`);
+	fs.chmodSync(bin, 0o755);
+	fs.writeFileSync(path.join(dir, "zip.sha256"), `${sha}  ${path.basename(entry.archive)}\n`);
+
+	// Re-point `current` at the new build. The link is ours (managed layout).
+	const link = path.join(root, "current");
+	fs.rmSync(link, { force: true });
+	fs.symlinkSync(build, link);
+	opts.onProgress?.("ACP server installed.");
+	return { bin, build, sha256: sha, downloaded: true };
+}
+
+function readRecordedSha(dir: string): string {
+	try {
+		return fs.readFileSync(path.join(dir, "zip.sha256"), "utf8").split(/\s+/)[0] ?? "";
+	} catch {
+		return "";
+	}
+}
+
+export interface AuthState {
+	configured: boolean;
+	/** settings.json auth.type, "token" (acp_token.json present), or undefined. */
+	type?: string;
+}
+
+/** Auth state WITHOUT reading any credential value: settings.json carries
+ *  only auth.type (+ non-secret gcp placement), acp_token.json is stat()ed. */
+export function readAuthState(dir?: string): AuthState {
+	const target = dir ?? path.join(os.homedir(), ".gemini", "antigravity-acp");
+	try {
+		const raw = JSON.parse(fs.readFileSync(path.join(target, "settings.json"), "utf8")) as {
+			auth?: { type?: unknown };
+		};
+		const type = typeof raw.auth?.type === "string" ? raw.auth.type : undefined;
+		if (type) return { configured: true, type };
+	} catch {
+		/* absent or garbage = unconfigured */
+	}
+	try {
+		fs.statSync(path.join(target, "acp_token.json"));
+		return { configured: true, type: "token" };
+	} catch {
+		return { configured: false };
+	}
+}
+
+/** Write a minimal auth block into settings.json. The server reads this file
+ *  at STARTUP, so this must happen before the first server spawn. */
+export function writeAuthType(type: "gemini-api-key" | "oauth-personal", dir?: string): void {
+	const target = dir ?? path.join(os.homedir(), ".gemini", "antigravity-acp");
+	fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+	const file = path.join(target, "settings.json");
+	let settings: Record<string, unknown> = {};
+	try {
+		settings = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+	} catch {
+		/* fresh file */
+	}
+	const prevAuth = (typeof settings.auth === "object" && settings.auth !== null ? settings.auth : {}) as Record<string, unknown>;
+	fs.writeFileSync(file, `${JSON.stringify({ ...settings, auth: { ...prevAuth, type } }, null, 2)}\n`, { mode: 0o600 });
+}
+
+export interface BinaryResolution {
+	bin: string | null;
+	source: "env" | "config" | "existing" | "installed" | null;
+}
+
+/** Read-only binary resolution: AGY_ACP_BIN > acp.bin > installed `current`
+ *  layout. Does NOT install and does NOT fall back to the bare PATH name. */
+export function resolveInstalledBinary(opts: SetupOptions = {}): BinaryResolution {
+	const env = opts.env ?? process.env;
+	const root = opts.installRoot ?? defaultInstallRoot();
+	const candidates: Array<[string, BinaryResolution["source"]]> = [
+		[env.AGY_ACP_BIN?.trim() ?? "", "env"],
+		[opts.configBin?.trim() ?? "", "config"],
+		[path.join(root, "current", "agy_acp_server.par"), "existing"],
+	];
+	for (const [raw, source] of candidates) {
+		if (!raw) continue;
+		const bin = expandTilde(raw);
+		if (executableFile(bin)) return { bin, source };
+	}
+	return { bin: null, source: null };
+}
+
+/** Read-only setup state (for /agy doctor): no installs, no writes. */
+export function inspectAcpSetup(opts: SetupOptions = {}): { bin: string | null; source: string | null; auth: string | null } {
+	const binary = resolveInstalledBinary(opts);
+	const auth = readAuthState(defaultGeminiDir(opts));
+	return { bin: binary.bin, source: binary.source, auth: auth.configured ? (auth.type ?? "token") : null };
+}
+
+/** Orchestrate everything the ACP engine needs, in order: binary (install
+ *  from the registry when missing), then auth (oauth-personal: the user's
+ *  own Antigravity subscription - the same Google account and plan as the
+ *  agy CLI login; the server opens the browser itself on the first message).
+ *  Every step is skipped when already satisfied; failures return `manual`
+ *  text for the caller to surface. */
+export async function ensureAcpReady(opts: SetupOptions = {}): Promise<AcpSetupStatus> {
+	const actions: string[] = [];
+
+	// 1. Binary.
+	let binary = resolveInstalledBinary(opts);
+	if (!binary.bin) {
+		if (opts.install === false) {
+			return { ok: false, stage: "install", error: "no ACP server binary found", manual: MANUAL_SETUP };
+		}
+		try {
+			const installed = await installAcpBinary(opts);
+			binary = { bin: installed.bin, source: "installed" };
+			actions.push(installed.downloaded ? `installed ACP server build ${installed.build}` : `found installed ACP server build ${installed.build}`);
+		} catch (err) {
+			return {
+				ok: false,
+				stage: "install",
+				error: err instanceof Error ? err.message : String(err),
+				manual: MANUAL_SETUP,
+			};
+		}
+	}
+
+	// 2. Auth. settings.json is read at server STARTUP; setup always runs
+	// before the first spawn, so a fresh write takes effect. oauth-personal is
+	// THE default: it is the Antigravity subscription (same Google account and
+	// plan as the agy CLI login). gemini-api-key (metered paid API) stays a
+	// manual option for headless boxes (/agy acp-auth); never the default.
+	const gdir = defaultGeminiDir(opts);
+	const auth = readAuthState(gdir);
+	if (!auth.configured) {
+		try {
+			writeAuthType("oauth-personal", gdir);
+			actions.push("configured oauth-personal auth (your Antigravity subscription login)");
+			return { ok: true, bin: binary.bin!, binarySource: binary.source!, auth: "oauth-personal", needsLogin: true, actions };
+		} catch (err) {
+			return {
+				ok: false,
+				stage: "auth",
+				error: err instanceof Error ? err.message : String(err),
+				manual: MANUAL_SETUP,
+			};
+		}
+	}
+	return {
+		ok: true,
+		bin: binary.bin!,
+		binarySource: binary.source!,
+		auth: auth.type ?? "token",
+		needsLogin: false,
+		actions,
+	};
+}

package/src/config.ts

@@ -59,8 +59,10 @@ export interface AgyConfig {
 	 *  always available. */
 	patchCleanupNotified?: boolean;
 	/** Which pi tools the MCP bridge exposes to agy: "none" (bridge off),
-	 *  "mcp" (pi-mcp-adapter tools + skills bridge; default), "all" (every
-	 *  registered non-builtin tool incl. other Ask* delegations). */
+	 *  "all" (every registered non-builtin tool incl. other Ask* delegations;
+	 *  default - users expect the bridge working out of the box, and the
+	 *  "mcp" surface serves an empty catalog on installs without
+	 *  pi-mcp-adapter), "mcp" (pi-mcp-adapter tools + skills bridge only). */
 	bridgeTools: BridgeTools;
 	/** Inject a delta digest of pi-side context (compaction summaries, turns
 	 *  handled by other providers or pi's own tools) into each agy prompt.
@@ -94,7 +96,7 @@ const DEFAULTS: AgyConfig = {
 	skipPermissions: true,
 	defaultModel: "flash",
 	defaultThinking: "medium",
-	bridgeTools: "mcp",
+	bridgeTools: "all",
 	digest: false,
 	systemPrompt: true,
 	acp: { bin: "", permissions: "auto" },
@@ -149,7 +151,9 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 
 	const bridgeRaw = (process.env.AGY_BRIDGE_TOOLS ?? file.bridgeTools ?? DEFAULTS.bridgeTools).toLowerCase();
 	const bridgeTools: BridgeTools =
-		bridgeRaw === "none" || bridgeRaw === "all" ? bridgeRaw : "mcp";
+		bridgeRaw === "none" || bridgeRaw === "all" || bridgeRaw === "mcp"
+			? bridgeRaw
+			: DEFAULTS.bridgeTools;
 
 	const digest = process.env.AGY_DIGEST !== undefined
 		? ["1", "true", "on"].includes(process.env.AGY_DIGEST.toLowerCase())

package/src/driver.ts

@@ -132,6 +132,10 @@ export class AgyDriver implements TurnDriver {
 	#queueTail: Promise<void> = Promise.resolve();
 	#shutdown = false;
 	#stderrTail = "";
+	// Frames can split across pipe chunks; the trailing partial line lives here
+	// until its newline arrives (same scheme as JsonRpcSession.feed). Dropping
+	// it ate large tool frames and could hide the result frame of a turn.
+	#stdoutBuf = "";
 	#lifecycle: string[] = [];
 	#onTurnEnd: ((outcome: TurnOutcome) => void) | undefined;
 	#stats = {
@@ -332,7 +336,16 @@ export class AgyDriver implements TurnDriver {
 			windowsHide: true,
 		});
 		this.#child = child;
+		this.#stdoutBuf = "";
 		this.#stats.spawns += 1;
+		// Pipe write failures surface asynchronously as stream 'error' events;
+		// the sync try/catch around stdin.write cannot see them. Without this
+		// listener an EPIPE (agy died mid-write) is uncaught and kills pi.
+		child.stdin!.on("error", (err) => {
+			if (generation !== this.#generation) return;
+			const turn = this.#active;
+			if (turn && !turn.closed) this.#failTurn(turn, `agy stdin write failed: ${err.message}`);
+		});
 		this.#log(`spawn:${child.pid ?? "?"}:${request.conversationId ? "resume" : "fresh"}`);
 		this.#state = "ready";
 
@@ -379,10 +392,15 @@ export class AgyDriver implements TurnDriver {
 	}
 
 	#onStdout(chunk: string): void {
+		// Buffer the trailing partial line: a frame split across pipe chunks is
+		// reassembled when its newline arrives (mirrors JsonRpcSession.feed).
+		this.#stdoutBuf += chunk;
+		const lines = this.#stdoutBuf.split("\n");
+		this.#stdoutBuf = lines.pop() ?? "";
 		const turn = this.#active;
 		if (!turn || turn.closed) return;
 		if (turn.idleTimer) turn.idleTimer.refresh();
-		for (const line of chunk.split("\n")) {
+		for (const line of lines) {
 			if (!line.trim()) continue;
 			this.#applyParsed(turn, parseAgyLine(line));
 			if (turn.closed) return;
@@ -585,6 +603,7 @@ export class AgyDriver implements TurnDriver {
 		if (!child) return;
 		this.#child = undefined;
 		this.#generation += 1;
+		this.#stdoutBuf = "";
 		try {
 			child.stdout?.removeAllListeners();
 			child.stderr?.removeAllListeners();

package/src/provider.ts

@@ -846,6 +846,14 @@ export function createStreamSimple(
 		const config = loadConfig();
 		const engine = deps.engine ?? config.engine;
 		const selected = engine === "acp" && deps.acpDriver ? deps.acpDriver : deps.driver;
+		// RC01: ACP modes are permission modes, there is no review-only plan.
+		// A plan turn on ACP would silently run non-plan; fail visibly instead.
+		if (selected === deps.acpDriver && config.mode === "plan") {
+			const partial = newAssistant(model);
+			const blocks: BlockState = { partial, textIdx: null, thinkingIdx: null, started: false };
+			finalize(stream, blocks, "error", "ACP engine has no plan mode. /agy mode accept-edits, or /agy engine stream-json.");
+			return stream;
+		}
 		if (selected && roundTrips) {
 			void runTurnDriver(stream, model, context, options, entries, store, {
 				driver: selected,

package/src/skills.ts

@@ -22,7 +22,9 @@ export interface SkillLite {
 	dir: string;
 }
 
-/** Parse `name:` / `description:` out of SKILL.md frontmatter. */
+/** Parse `name:` / `description:` out of SKILL.md frontmatter. Deliberately
+ *  line-based, not YAML: multi-line block scalars (`description: >-`) keep
+ *  only their first line. */
 function parseFrontmatter(raw: string): { name?: string; description?: string } {
 	const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
 	if (!m) return {};
@@ -36,48 +38,123 @@ function parseFrontmatter(raw: string): { name?: string; description?: string }
 	return out;
 }
 
-function scanDir(dir: string): SkillLite[] {
-	let entries: string[];
+// The rest of this module mirrors pi's own skill discovery (pi docs
+// "docs/skills.md - Locations") so the bridge's activate_skill catalog
+// matches the [Skills] list pi shows in its system prompt:
+//
+// - Global: ~/.pi/agent/skills (pi style) and ~/.agents/skills (agents style,
+//   the cross-harness standard).
+// - Project: .pi/skills (pi style) and .agents/skills in cwd + ancestors up
+//   to the git repo root (agents style).
+// - Both styles discover every directory holding a SKILL.md, recursively;
+//   grouping folders (no SKILL.md) are descended into and a skill's contents
+//   are freeform (no descent past its SKILL.md).
+// - pi style also treats root .md files as individual skills; agents style
+//   ignores root .md but picks up frontmatter .md files inside grouping
+//   folders.
+// - Skills without a description are not loaded (same as pi).
+// - Name collisions keep the first skill found, pi global dirs before
+//   project dirs.
+
+export type SkillStyle = "pi" | "agents";
+
+export interface SkillLocation {
+	dir: string;
+	style: SkillStyle;
+}
+
+const MAX_DEPTH = 16; // symlink-loop insurance; real catalogs nest 1-2 levels
+
+/** Ordered skill locations for a session: pi global dirs, then project dirs
+ *  (project `.agents/skills` walks cwd ancestors up to the git root). */
+export function skillLocations(projectDir?: string, home: string = os.homedir()): SkillLocation[] {
+	const out: SkillLocation[] = [
+		{ dir: path.join(home, ".pi", "agent", "skills"), style: "pi" },
+		{ dir: path.join(home, ".agents", "skills"), style: "agents" },
+	];
+	if (!projectDir) return out;
+	out.push({ dir: path.join(projectDir, ".pi", "skills"), style: "pi" });
+	let dir = path.resolve(projectDir);
+	for (;;) {
+		out.push({ dir: path.join(dir, ".agents", "skills"), style: "agents" });
+		if (path.dirname(dir) === dir || fs.existsSync(path.join(dir, ".git"))) break;
+		dir = path.dirname(dir);
+	}
+	return out;
+}
+
+function readSkillFile(file: string, fallbackName: string): SkillLite | null {
+	let raw = "";
 	try {
-		entries = fs.readdirSync(dir, { withFileTypes: true }).map((e) => e.name);
+		// Strip a UTF-8 BOM so editors that add one do not break the `---` anchor.
+		raw = fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "");
 	} catch {
-		return [];
+		return null;
 	}
-	const found: SkillLite[] = [];
-	for (const entry of entries) {
-		const skillDir = path.join(dir, entry);
-		const skillFile = path.join(skillDir, "SKILL.md");
+	const fm = parseFrontmatter(raw);
+	const description = (fm.description ?? "").trim();
+	// pi does not load skills without a description.
+	if (!description) return null;
+	return {
+		name: fm.name?.trim() || fallbackName,
+		description: description.replace(/\s+/g, " ").slice(0, 160),
+		filePath: file,
+		dir: path.dirname(file),
+	};
+}
+
+function scanLocation(loc: SkillLocation): SkillLite[] {
+	const walk = (dir: string, depth: number): SkillLite[] => {
+		if (depth > MAX_DEPTH) return [];
+		let entries: fs.Dirent[];
 		try {
-			if (!fs.statSync(skillFile).isFile()) continue;
+			entries = fs.readdirSync(dir, { withFileTypes: true });
 		} catch {
-			continue;
+			return [];
 		}
-		let raw = "";
-		try {
-			raw = fs.readFileSync(skillFile, "utf8");
-		} catch {
-			continue;
+		const found: SkillLite[] = [];
+		for (const entry of entries) {
+			// Hidden entries are harness internals (e.g. ~/.agents/skills/.system);
+			// pi's own [Skills] list never includes them.
+			if (entry.name.startsWith(".")) continue;
+			const full = path.join(dir, entry.name);
+			let isDir: boolean;
+			try {
+				isDir = entry.isDirectory() || (entry.isSymbolicLink() && fs.statSync(full).isDirectory());
+			} catch {
+				continue;
+			}
+			if (isDir) {
+				if (fs.existsSync(path.join(full, "SKILL.md"))) {
+					const skill = readSkillFile(path.join(full, "SKILL.md"), entry.name);
+					if (skill) found.push(skill);
+				} else {
+					found.push(...walk(full, depth + 1));
+				}
+				continue;
+			}
+			if (!entry.name.endsWith(".md") || entry.name === "SKILL.md") continue;
+			const standalone = loc.style === "pi" ? depth === 0 : depth > 0;
+			if (!standalone) continue;
+			const skill = readSkillFile(full, entry.name.replace(/\.md$/, ""));
+			if (skill) found.push(skill);
 		}
-		const fm = parseFrontmatter(raw);
-		found.push({
-			name: fm.name?.trim() || entry,
-			description: (fm.description ?? "").replace(/\s+/g, " ").slice(0, 160),
-			filePath: skillFile,
-			dir: skillDir,
-		});
-	}
-	return found;
+		return found;
+	};
+	return walk(loc.dir, 0);
 }
 
-/** Unique skills with a file path; first name wins (same as pi collisions). */
-export function scanSkills(projectDir?: string): SkillLite[] {
-	const globalDir = path.join(os.homedir(), ".pi", "agent", "skills");
+/** pi-faithful skill catalog: every skill pi itself would load, deduped by
+ *  name (first wins). `home` is injectable for tests. */
+export function scanSkills(projectDir?: string, home: string = os.homedir()): SkillLite[] {
 	const seen = new Set<string>();
 	const out: SkillLite[] = [];
-	for (const skill of [...scanDir(globalDir), ...(projectDir ? scanDir(path.join(projectDir, ".pi", "skills")) : [])]) {
-		if (!skill.filePath || seen.has(skill.name)) continue;
-		seen.add(skill.name);
-		out.push(skill);
+	for (const loc of skillLocations(projectDir, home)) {
+		for (const skill of scanLocation(loc)) {
+			if (seen.has(skill.name)) continue;
+			seen.add(skill.name);
+			out.push(skill);
+		}
 	}
 	return out;
 }