@selesai/code 0.5.20 → 0.5.21

package/dist/extensions/pi-subagents/test/unit/selector.test.ts

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { initTheme } from "@selesai/code";
+import { SelectorComponent } from "../../src/slash/selector.ts";
+
+initTheme("dark");
+
+function createHarness(items: Array<{ value: string; label: string; current?: boolean }>) {
+	const results: Array<{ confirmed: boolean; value?: string }> = [];
+	const component = new SelectorComponent(
+		{ requestRender() {} } as never,
+		{
+			fg(_color: string, text: string) { return text; },
+			bold(text: string) { return text; },
+		} as never,
+		{
+			matches(key: string, binding: string) { return key === binding; },
+		} as never,
+		{ title: "Select item", items, done: (result) => results.push(result) },
+	);
+	return { component, results };
+}
+
+describe("SelectorComponent", () => {
+	it("keeps the current selection visible in a bounded list and confirms it", () => {
+		const items = Array.from({ length: 12 }, (_, index) => ({
+			value: `value-${index}`,
+			label: `Item ${index}`,
+			current: index === 10,
+		}));
+		const { component, results } = createHarness(items);
+
+		const rendered = component.render(80).join("\n");
+		assert.match(rendered, /Item 10/);
+		assert.match(rendered, /\(11\/12\)/);
+
+		component.handleInput("tui.select.confirm");
+		assert.deepEqual(results, [{ confirmed: true, value: "value-10" }]);
+	});
+
+	it("filters searchable values and reports cancellation", () => {
+		const { component, results } = createHarness([
+			{ value: "anthropic/opus", label: "opus" },
+			{ value: "openai/gpt", label: "gpt" },
+		]);
+
+		component.handleInput("gpt");
+		component.handleInput("tui.select.confirm");
+		component.handleInput("tui.select.cancel");
+
+		assert.deepEqual(results, [
+			{ confirmed: true, value: "openai/gpt" },
+			{ confirmed: false },
+		]);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/session-lease.test.ts

@@ -0,0 +1,326 @@
+import assert from "node:assert/strict";
+import { spawn, type ChildProcess } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, it } from "node:test";
+import { acquireSessionLease, canonicalSessionFilePath, SessionLeaseConflictError, sessionLeaseDir } from "../../src/runs/shared/session-lease.ts";
+
+function fixture(prefix: string): { root: string; leases: string; sessionFile: string } {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+	const sessionFile = path.join(root, "session.jsonl");
+	fs.writeFileSync(sessionFile, "", "utf-8");
+	return { root, leases: path.join(root, "leases"), sessionFile };
+}
+
+function request(sessionFile: string, runId: string) {
+	return { sessionFile, runId, sourceRunId: "source-run", parentSessionId: "parent-session" };
+}
+
+function waitForLine(child: ChildProcess, timeoutMs = 10_000): Promise<string> {
+	return new Promise((resolve, reject) => {
+		let stdout = "";
+		const timer = setTimeout(() => reject(new Error(`Timed out waiting for child output. stderr: ${String(child.stderr?.read() ?? "")}`)), timeoutMs);
+		child.stdout?.setEncoding("utf-8");
+		child.stdout?.on("data", (chunk: string) => {
+			stdout += chunk;
+			const newline = stdout.indexOf("\n");
+			if (newline === -1) return;
+			clearTimeout(timer);
+			resolve(stdout.slice(0, newline));
+		});
+		child.once("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		child.once("exit", (code) => {
+			if (stdout.includes("\n")) return;
+			clearTimeout(timer);
+			reject(new Error(`Lease child exited with ${code} before reporting acquisition.`));
+		});
+	});
+}
+
+function waitForExit(child: ChildProcess, timeoutMs = 10_000): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (child.exitCode !== null) {
+			resolve();
+			return;
+		}
+		const timer = setTimeout(() => reject(new Error("Timed out waiting for lease child exit.")), timeoutMs);
+		child.once("exit", () => {
+			clearTimeout(timer);
+			resolve();
+		});
+		child.once("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+	});
+}
+
+function pidIsAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+async function waitForPidExit(pid: number, timeoutMs = 10_000): Promise<void> {
+	const deadline = Date.now() + timeoutMs;
+	while (pidIsAlive(pid)) {
+		if (Date.now() > deadline) throw new Error(`Timed out waiting for pid ${pid} to exit.`);
+		await new Promise((resolve) => setTimeout(resolve, 20));
+	}
+}
+
+describe("session revival leases", () => {
+	it("allows one owner and reports its run metadata on contention", () => {
+		const { root, leases, sessionFile } = fixture("pi-session-lease-owner-");
+		try {
+			const first = acquireSessionLease(request(sessionFile, "revive-a"), {
+				rootDir: leases,
+				pid: 101,
+				hostname: "host-a",
+				processStartIdentity: "start-a",
+				isProcessAlive: () => true,
+				getProcessStartIdentity: () => "start-a",
+				token: () => "token-a",
+				now: () => 1000,
+			});
+			assert.throws(
+				() => acquireSessionLease(request(sessionFile, "revive-b"), {
+					rootDir: leases,
+					pid: 202,
+					hostname: "host-a",
+					processStartIdentity: "start-b",
+					isProcessAlive: () => true,
+					getProcessStartIdentity: () => "start-a",
+					token: () => "token-b",
+				}),
+				(error: unknown) => error instanceof SessionLeaseConflictError
+					&& error.owner?.runId === "revive-a"
+					&& /already owned by run 'revive-a'/.test(error.message),
+			);
+			assert.equal(first.release(), true);
+			const second = acquireSessionLease(request(sessionFile, "revive-b"), { rootDir: leases, token: () => "token-b" });
+			assert.equal(second.release(), true);
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("keys aliases by the canonical session path", { skip: process.platform === "win32" ? "symlink creation is not portable on Windows CI" : undefined }, () => {
+		const { root, leases, sessionFile } = fixture("pi-session-lease-canonical-");
+		try {
+			const alias = path.join(root, "alias.jsonl");
+			fs.symlinkSync(sessionFile, alias);
+			assert.equal(canonicalSessionFilePath(alias), canonicalSessionFilePath(sessionFile));
+			assert.equal(sessionLeaseDir(alias, leases), sessionLeaseDir(sessionFile, leases));
+			const lease = acquireSessionLease(request(alias, "alias-owner"), { rootDir: leases });
+			assert.throws(() => acquireSessionLease(request(sessionFile, "direct-owner"), { rootDir: leases }), /already owned by run 'alias-owner'/);
+			lease.release();
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("allows different canonical session files concurrently", () => {
+		const { root, leases, sessionFile } = fixture("pi-session-lease-distinct-");
+		try {
+			const otherSession = path.join(root, "other.jsonl");
+			fs.writeFileSync(otherSession, "", "utf-8");
+			const first = acquireSessionLease(request(sessionFile, "revive-a"), { rootDir: leases });
+			const second = acquireSessionLease(request(otherSession, "revive-b"), { rootDir: leases });
+			first.release();
+			second.release();
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("reclaims only demonstrably dead or PID-reused owners", () => {
+		const { root, leases, sessionFile } = fixture("pi-session-lease-stale-");
+		try {
+			const dead = acquireSessionLease(request(sessionFile, "dead-owner"), {
+				rootDir: leases,
+				pid: 101,
+				hostname: "host-a",
+				processStartIdentity: "start-dead",
+				token: () => "dead-token",
+			});
+			const recovered = acquireSessionLease(request(sessionFile, "recovered"), {
+				rootDir: leases,
+				pid: 202,
+				hostname: "host-a",
+				processStartIdentity: "start-recovered",
+				isProcessAlive: (pid) => pid === 101 ? false : true,
+				token: () => "recovered-token",
+			});
+			assert.equal(recovered.owner.runId, "recovered");
+			assert.ok(fs.existsSync(`${dead.leaseDir}.stale-dead-token`));
+			recovered.release();
+
+			const reused = acquireSessionLease(request(sessionFile, "reused-owner"), {
+				rootDir: leases,
+				pid: 303,
+				hostname: "host-a",
+				processStartIdentity: "old-start",
+				token: () => "reused-token",
+			});
+			const afterReuse = acquireSessionLease(request(sessionFile, "after-reuse"), {
+				rootDir: leases,
+				pid: 404,
+				hostname: "host-a",
+				processStartIdentity: "new-owner-start",
+				isProcessAlive: () => true,
+				getProcessStartIdentity: (pid) => pid === 303 ? "new-start" : "new-owner-start",
+				token: () => "after-reuse-token",
+			});
+			assert.equal(afterReuse.owner.runId, "after-reuse");
+			assert.ok(fs.existsSync(`${reused.leaseDir}.stale-reused-token`));
+			afterReuse.release();
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("does not reclaim a dead runner while its writer is live or still spawning", () => {
+		const { root, leases, sessionFile } = fixture("pi-session-lease-writer-state-");
+		try {
+			const lease = acquireSessionLease(request(sessionFile, "runner-owner"), {
+				rootDir: leases,
+				pid: 101,
+				hostname: "host-a",
+				processStartIdentity: "runner-start",
+				getProcessStartIdentity: (pid) => pid === 202 ? "writer-start" : undefined,
+			});
+			lease.updateWriter({ state: "spawning" });
+			assert.throws(
+				() => acquireSessionLease(request(sessionFile, "spawning-contender"), {
+					rootDir: leases,
+					pid: 303,
+					hostname: "host-a",
+					processStartIdentity: "contender-start",
+					isProcessAlive: () => false,
+				}),
+				/already owned by run 'runner-owner'/,
+			);
+
+			lease.updateWriter({ state: "running", pid: 202 });
+			assert.throws(
+				() => acquireSessionLease(request(sessionFile, "writer-contender"), {
+					rootDir: leases,
+					pid: 303,
+					hostname: "host-a",
+					processStartIdentity: "contender-start",
+					isProcessAlive: (pid) => pid === 202,
+					getProcessStartIdentity: (pid) => pid === 202 ? "writer-start" : undefined,
+				}),
+				/already owned by run 'runner-owner'/,
+			);
+			lease.release();
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("does not reclaim unverifiable owners on another host", () => {
+		const { root, leases, sessionFile } = fixture("pi-session-lease-host-");
+		try {
+			const lease = acquireSessionLease(request(sessionFile, "remote-owner"), {
+				rootDir: leases,
+				pid: 101,
+				hostname: "host-a",
+				processStartIdentity: "start-a",
+			});
+			assert.throws(
+				() => acquireSessionLease(request(sessionFile, "local-owner"), {
+					rootDir: leases,
+					pid: 202,
+					hostname: "host-b",
+					processStartIdentity: "start-b",
+					isProcessAlive: () => false,
+				}),
+				/already owned by run 'remote-owner'/,
+			);
+			lease.release();
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("keeps an orphaned writer exclusive after its runner exits", async () => {
+		const { root, leases, sessionFile } = fixture("pi-session-lease-orphan-writer-");
+		const helper = fileURLToPath(new URL("../support/session-lease-child.mjs", import.meta.url));
+		const releaseSignal = path.join(root, "unused-release");
+		let writerPid: number | undefined;
+		try {
+			const owner = spawn(process.execPath, ["--experimental-strip-types", helper, sessionFile, leases, releaseSignal, "abandon-with-writer"], {
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			const started = JSON.parse(await waitForLine(owner)) as { acquired?: boolean; writerPid?: number };
+			assert.equal(started.acquired, true);
+			assert.equal(typeof started.writerPid, "number");
+			writerPid = started.writerPid;
+			await waitForExit(owner);
+			assert.ok(writerPid && pidIsAlive(writerPid));
+			assert.throws(() => acquireSessionLease(request(sessionFile, "blocked-by-writer"), { rootDir: leases }), /already owned by run 'child-/);
+
+			process.kill(writerPid, "SIGTERM");
+			await waitForPidExit(writerPid);
+			const recovered = acquireSessionLease(request(sessionFile, "after-writer-exit"), { rootDir: leases });
+			assert.equal(recovered.owner.runId, "after-writer-exit");
+			recovered.release();
+		} finally {
+			if (writerPid && pidIsAlive(writerPid)) process.kill(writerPid, "SIGKILL");
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("enforces ownership across independent Node processes and elects one stale successor", async () => {
+		const { root, leases, sessionFile } = fixture("pi-session-lease-process-");
+		const helper = fileURLToPath(new URL("../support/session-lease-child.mjs", import.meta.url));
+		const releaseSignal = path.join(root, "release");
+		let child: ChildProcess | undefined;
+		try {
+			child = spawn(process.execPath, ["--experimental-strip-types", helper, sessionFile, leases, releaseSignal, "hold"], {
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			const line = await waitForLine(child);
+			const started = JSON.parse(line) as { owner?: { pid?: number; runId?: string } };
+			assert.equal(started.owner?.pid, child.pid);
+			assert.throws(() => acquireSessionLease(request(sessionFile, "parent-contender"), { rootDir: leases }), /already owned by run 'child-/);
+			fs.writeFileSync(releaseSignal, "release", "utf-8");
+			await waitForExit(child);
+			const afterRelease = acquireSessionLease(request(sessionFile, "parent-after-release"), { rootDir: leases });
+			afterRelease.release();
+
+			fs.rmSync(releaseSignal, { force: true });
+			const abandoned = spawn(process.execPath, ["--experimental-strip-types", helper, sessionFile, leases, releaseSignal, "abandon"], {
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			await waitForLine(abandoned);
+			await waitForExit(abandoned);
+
+			const releaseA = path.join(root, "release-a");
+			const releaseB = path.join(root, "release-b");
+			const contenderA = spawn(process.execPath, ["--experimental-strip-types", helper, sessionFile, leases, releaseA, "hold"], { stdio: ["ignore", "pipe", "pipe"] });
+			const contenderB = spawn(process.execPath, ["--experimental-strip-types", helper, sessionFile, leases, releaseB, "hold"], { stdio: ["ignore", "pipe", "pipe"] });
+			const [lineA, lineB] = await Promise.all([waitForLine(contenderA), waitForLine(contenderB)]);
+			const stateA = JSON.parse(lineA) as { acquired?: boolean };
+			const stateB = JSON.parse(lineB) as { acquired?: boolean };
+			assert.equal(Number(stateA.acquired === true) + Number(stateB.acquired === true), 1);
+			fs.writeFileSync(stateA.acquired ? releaseA : releaseB, "release", "utf-8");
+			await Promise.all([waitForExit(contenderA), waitForExit(contenderB)]);
+			const recovered = acquireSessionLease(request(sessionFile, "parent-after-contenders"), { rootDir: leases });
+			recovered.release();
+		} finally {
+			if (child && child.exitCode === null) child.kill();
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+});

package/dist/extensions/pi-subagents/test/unit/single-output.test.ts

@@ -3,8 +3,10 @@ import { afterEach, describe, it } from "node:test";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { Message, Usage } from "@earendil-works/pi-ai";
 import {
 	captureSingleOutputSnapshot,
+	extractChildWrittenOutput,
 	finalizeSingleOutput,
 	formatSavedOutputReference,
 	injectOutputPathSystemPrompt,
@@ -80,12 +82,20 @@ describe("resolveSingleOutputPath", () => {
 });
 
 describe("injectSingleOutputInstruction", () => {
-	it("appends output instruction with resolved path", () => {
-		const output = injectSingleOutputInstruction("Analyze this", "/tmp/report.md");
+	it("appends direct-write instructions for mutation-capable agents", () => {
+		const output = injectSingleOutputInstruction("Analyze this", "/tmp/report.md", { tools: ["read", "write"] });
 		assert.match(output, /Write your findings to exactly this path: \/tmp\/report.md/);
 		assert.match(output, /This path is authoritative for this run\./);
 		assert.match(output, /Ignore any other output filename or output path mentioned elsewhere/);
 	});
+
+	it("tells read-only agents to return the artifact for runtime persistence", () => {
+		const output = injectSingleOutputInstruction("Analyze this", "/tmp/report.md", { tools: ["read", "grep", "find", "ls"] });
+		assert.match(output, /Return the complete artifact in your final response\./);
+		assert.match(output, /runtime will persist it to exactly this path: \/tmp\/report\.md/);
+		assert.match(output, /Do not call contact_supervisor merely because no write-capable tool is available\./);
+		assert.doesNotMatch(output, /Write your findings to exactly this path/);
+	});
 });
 
 describe("injectOutputPathSystemPrompt", () => {
@@ -97,6 +107,13 @@ describe("injectOutputPathSystemPrompt", () => {
 		assert.match(output, /Ignore any other output filename or output path mentioned elsewhere/);
 	});
 
+	it("uses runtime-persistence instructions in read-only system prompts", () => {
+		const output = injectOutputPathSystemPrompt("Analyze only", "/tmp/new.md", { tools: ["read"] });
+		assert.match(output, /Return the complete artifact in your final response\./);
+		assert.match(output, /runtime will persist it to exactly this path: \/tmp\/new\.md/);
+		assert.doesNotMatch(output, /Write your findings to exactly this path/);
+	});
+
 	it("leaves prompts unchanged when no output path is active", () => {
 		assert.equal(injectOutputPathSystemPrompt("Base prompt", undefined), "Base prompt");
 	});
@@ -146,6 +163,88 @@ describe("resolveSingleOutput", () => {
 	});
 });
 
+describe("extractChildWrittenOutput", () => {
+	const usage: Usage = { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+	const toolCall = (id: string, name: string, args: Record<string, unknown>): Message => ({
+		role: "assistant",
+		content: [{ type: "toolCall", id, name, arguments: args }],
+		api: "test",
+		provider: "test",
+		model: "mock/test-model",
+		usage,
+		stopReason: "toolUse",
+		timestamp: 0,
+	});
+	const toolResult = (id: string, isError = false): Message => ({
+		role: "toolResult",
+		toolCallId: id,
+		toolName: "write",
+		content: [{ type: "text", text: isError ? "write failed" : "ok" }],
+		isError,
+		timestamp: 0,
+	});
+	const completedWrite = (id: string, writePath: string, content: string): Message[] => [
+		toolCall(id, "write", { path: writePath, content }),
+		toolResult(id),
+	];
+
+	it("returns the last successfully written content for the configured path", () => {
+		const messages = [
+			...completedWrite("w1", "/tmp/out.md", "draft"),
+			...completedWrite("w2", "/tmp/other.md", "unrelated"),
+			...completedWrite("w3", "/tmp/out.md", "final report"),
+		];
+		assert.equal(extractChildWrittenOutput(messages, "/tmp/out.md", "/repo"), "final report");
+	});
+
+	it("ignores write calls whose tool result failed", () => {
+		const failedOnly = [toolCall("w1", "write", { path: "/tmp/out.md", content: "never landed" }), toolResult("w1", true)];
+		assert.equal(extractChildWrittenOutput(failedOnly, "/tmp/out.md", "/repo"), undefined);
+
+		const failedAfterSuccess = [
+			...completedWrite("w1", "/tmp/out.md", "landed"),
+			toolCall("w2", "write", { path: "/tmp/out.md", content: "never landed" }),
+			toolResult("w2", true),
+		];
+		assert.equal(extractChildWrittenOutput(failedAfterSuccess, "/tmp/out.md", "/repo"), "landed");
+	});
+
+	it("ignores write calls with no confirmed successful tool result", () => {
+		const missingResult = [toolCall("w1", "write", { path: "/tmp/out.md", content: "unconfirmed" })];
+		assert.equal(extractChildWrittenOutput(missingResult, "/tmp/out.md", "/repo"), undefined);
+
+		const missingStatus = [
+			toolCall("w1", "write", { path: "/tmp/out.md", content: "unconfirmed" }),
+			{ role: "toolResult", toolCallId: "w1", toolName: "write", content: [{ type: "text", text: "unknown" }], timestamp: 0 } as Message,
+		];
+		assert.equal(extractChildWrittenOutput(missingStatus, "/tmp/out.md", "/repo"), undefined);
+	});
+
+	it("resolves relative write paths against the child cwd", () => {
+		const messages = completedWrite("w1", "reports/out.md", "relative content");
+		assert.equal(extractChildWrittenOutput(messages, "/repo/reports/out.md", "/repo"), "relative content");
+		assert.equal(extractChildWrittenOutput(messages, "/elsewhere/reports/out.md", "/repo"), undefined);
+	});
+
+	it("matches configured output paths case-insensitively on Windows", { skip: process.platform !== "win32" ? "Windows path comparison" : undefined }, () => {
+		const writePath = path.join("C:\\Repo", "Reports", "Output.md");
+		const configuredPath = writePath.toLowerCase();
+		assert.equal(extractChildWrittenOutput(completedWrite("w1", writePath, "Windows report"), configuredPath, "C:\\Repo"), "Windows report");
+	});
+
+	it("ignores non-write tools and missing arguments", () => {
+		const messages = [
+			toolCall("e1", "edit", { path: "/tmp/out.md", oldText: "a", newText: "b" }),
+			toolResult("e1"),
+			toolCall("w1", "write", { path: "/tmp/out.md" }),
+			toolResult("w1"),
+		];
+		assert.equal(extractChildWrittenOutput(messages, "/tmp/out.md", "/repo"), undefined);
+		assert.equal(extractChildWrittenOutput(undefined, "/tmp/out.md", "/repo"), undefined);
+		assert.equal(extractChildWrittenOutput(messages, undefined, "/repo"), undefined);
+	});
+});
+
 describe("formatSavedOutputReference", () => {
 	it("includes absolute path, human-readable size, and line count", () => {
 		const reportPath = path.join(os.tmpdir(), "report.md");

package/dist/extensions/pi-subagents/test/unit/skills-fallback.test.ts

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -229,6 +230,12 @@ describe("skills filesystem fallback", () => {
 		const { resolved, missing } = resolveSkills(["pi-subagents", "safe-bash"], tempDir);
 		assert.deepEqual(missing, ["pi-subagents"]);
 		assert.deepEqual(resolved.map((skill) => skill.name), ["safe-bash"]);
+
+		const agentDir = path.join(tempDir, "agent");
+		writeSkillFile(path.join(agentDir, "skills", "pi-subagents"), "Still parent-only.");
+		const local = resolveSkills(["pi-subagents"], tempDir, ["./skills"], agentDir);
+		assert.deepEqual(local.resolved, []);
+		assert.deepEqual(local.missing, ["pi-subagents"]);
 	});
 
 	it("classifies package-provided skills as project-package", () => {
@@ -297,6 +304,59 @@ describe("skills filesystem fallback", () => {
 		assert.equal(resolved[0]?.source, "project-package");
 	});
 
+	it("skips optional global npm discovery in offline mode", () => {
+		const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+		const binDir = path.join(tempDir, "bin");
+		const fakeHome = path.join(tempDir, "home");
+		const marker = path.join(tempDir, "npm-calls.txt");
+		fs.mkdirSync(binDir, { recursive: true });
+		fs.mkdirSync(fakeHome, { recursive: true });
+		fs.writeFileSync(
+			path.join(binDir, "npm"),
+			"#!/bin/sh\nprintf 'npm-root-called\\n' >> \"$PI_DISCOVERY_MARKER\"\nexit 1\n",
+			{ encoding: "utf-8", mode: 0o755 },
+		);
+		fs.writeFileSync(
+			path.join(binDir, "npm.cmd"),
+			"@echo off\r\n>>\"%PI_DISCOVERY_MARKER%\" echo npm-root-called\r\nexit /b 1\r\n",
+			"utf-8",
+		);
+
+		const script = `
+			import fs from "node:fs";
+			const [{ clearSkillCache, discoverAvailableSkills }, { discoverAgents }] = await Promise.all([
+				import("./src/agents/skills.ts"),
+				import("./src/agents/agents.ts"),
+			]);
+			discoverAvailableSkills(process.cwd());
+			discoverAgents(process.cwd(), "both");
+			if (fs.existsSync(process.env.PI_DISCOVERY_MARKER)) {
+				throw new Error("npm was invoked while PI_OFFLINE was enabled");
+			}
+			delete process.env.PI_OFFLINE;
+			clearSkillCache();
+			discoverAvailableSkills(process.cwd());
+			discoverAgents(process.cwd(), "both");
+		`;
+		execFileSync(
+			process.execPath,
+			["--experimental-transform-types", "--import", "./test/support/register-loader.mjs", "--input-type=module", "--eval", script],
+			{
+				cwd: projectRoot,
+				env: {
+					...process.env,
+					HOME: fakeHome,
+					USERPROFILE: fakeHome,
+					PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ""}`,
+					PI_DISCOVERY_MARKER: marker,
+					PI_OFFLINE: "1",
+				},
+				stdio: "pipe",
+			},
+		);
+		assert.deepEqual(fs.readFileSync(marker, "utf-8").trim().split(/\r?\n/), ["npm-root-called", "npm-root-called"]);
+	});
+
 	it("falls back to the runtime cwd when the execution cwd lacks the skill", () => {
 		const nestedDir = path.join(tempDir, "nested");
 		fs.mkdirSync(nestedDir, { recursive: true });
@@ -409,13 +469,63 @@ describe("skills filesystem fallback", () => {
 		}
 	});
 
+	it("resolves agent-local files and directories before global skills without publishing them", () => {
+		makeProjectSkill(tempDir, "shared", "global body");
+		const agentDir = path.join(tempDir, "agents", "nested");
+		writeSkillFile(path.join(agentDir, "skills", "shared"), "local shared body");
+		writeSkillFile(path.join(agentDir, "direct"), "local direct body");
+
+		const local = resolveSkills(["shared", "direct", "missing"], tempDir, ["./skills", "./direct/SKILL.md"], agentDir);
+		assert.deepEqual(local.resolved.map((skill) => [skill.name, skill.content]), [
+			["shared", "local shared body"],
+			["direct", "local direct body"],
+		]);
+		assert.deepEqual(local.missing, ["missing"]);
+		assert.equal(resolveSkills(["shared"], tempDir).resolved[0]?.content, "global body");
+		assert.equal(discoverAvailableSkills(tempDir).some((skill) => skill.name === "direct"), false);
+	});
+
+	it("does not read malformed global settings when every selected local skill resolves", () => {
+		const agentDir = path.join(tempDir, "agents", "nested");
+		writeSkillFile(path.join(agentDir, "skills", "local"), "local body");
+		fs.mkdirSync(path.join(tempDir, ".selesai"), { recursive: true });
+		fs.writeFileSync(path.join(tempDir, ".selesai", "settings.json"), "{bad-json", "utf-8");
+
+		const result = resolveSkills(["local"], tempDir, ["./skills"], agentDir);
+		assert.deepEqual(result.missing, []);
+		assert.equal(result.resolved[0]?.content, "local body");
+	});
+
+	it("falls back globally when an agent-local skill candidate cannot be read", () => {
+		makeProjectSkill(tempDir, "shared", "global body");
+		const agentDir = path.join(tempDir, "agents", "nested");
+		const invalidLocalFile = path.join(agentDir, "skills", "shared", "SKILL.md");
+		fs.mkdirSync(invalidLocalFile, { recursive: true });
+
+		const result = resolveSkills(["shared"], tempDir, ["./skills"], agentDir);
+		assert.deepEqual(result.missing, []);
+		assert.equal(result.resolved[0]?.content, "global body");
+	});
+
+	it("keeps same-named agent-local skills isolated between invocations", () => {
+		makeProjectSkill(tempDir, "global-only", "global fallback");
+		const one = path.join(tempDir, "one");
+		const two = path.join(tempDir, "two");
+		writeSkillFile(path.join(one, "skills", "private"), "one private");
+		writeSkillFile(path.join(two, "skills", "private"), "two private");
+
+		assert.equal(resolveSkills(["private", "global-only"], tempDir, ["./skills"], one).resolved[0]?.content, "one private");
+		assert.equal(resolveSkills(["private", "global-only"], tempDir, ["./skills"], two).resolved[0]?.content, "two private");
+		assert.equal(resolveSkills(["global-only"], tempDir, ["./skills"], one).resolved[0]?.content, "global fallback");
+	});
+
 	it("surfaces malformed project settings files instead of silently ignoring them", () => {
 		fs.mkdirSync(path.join(tempDir, ".selesai"), { recursive: true });
 		fs.writeFileSync(path.join(tempDir, ".selesai", "settings.json"), "{bad-json", "utf-8");
 
 		assert.throws(
 			() => resolveSkills(["missing-skill"], tempDir),
-			/Failed to read skills settings file .+\.pi[\\/]settings\.json/,
+			/Failed to read skills settings file .+\.selesai[\\/]settings\.json/,
 		);
 	});