@junghanacs/entwurf 0.12.0

package/scripts/check-model-lock.ts

@@ -0,0 +1,408 @@
+/**
+ * check-model-lock — deterministic unit test for `pi-extensions/model-lock.ts`.
+ *
+ * Mocks `ExtensionAPI` + `ExtensionContext` and drives the
+ * `session_start` / `agent_start` / `model_select` handlers through every
+ * case in the policy matrix. No pi process, no network, no API cost. The
+ * harness shape mirrors pi-core's actual behavior (setModel mutates +
+ * emits synthetic model_select with source="set") so reentry-guard
+ * validation is realistic.
+ *
+ * Coverage (every assertion must pass):
+ *   1.  native → native: no-op
+ *   2.  native → entwurf: revert (warning notify)
+ *   3.  entwurf → native: revert (warning notify)
+ *   4.  entwurf/X → entwurf/Y (id differs): revert (warning notify)
+ *   5.  entwurf → entwurf (same id): skip (changed=false)
+ *   6.  undefined → any: skip (!from)
+ *   7.  source="restore": skip
+ *   8.  Reentry guard: revert's synthetic emit MUST NOT re-trigger revert
+ *   9.  setModel returns false: notify level "error" instead of "warning"
+ *   10. session_start "startup" + entries=0: lock NOT engaged, model_select no-op
+ *   11. session_start "startup" + entries already have a message: lock engaged
+ *   12. session_start "startup" empty → agent_start → lock engaged
+ *   13. session_start "resume": lock engaged immediately
+ *   14. session_start "new" + entries=0: lock NOT engaged
+ *   15. session_start "reload" + entries have a message: lock engaged
+ *   16. session_start "fork": lock engaged immediately
+ *   17. session_start "reload" + entries=0 BUT prior sessionLocked=true: lock preserved
+ *   18. getEntries() throws: defensive `catch { return true }` engages the lock
+ *
+ * Scope (B-side, the extension hook):
+ *   this drives the model-lock extension hook directly. Its former A-side
+ *   companion `smoke-model-switch` exercised the ACP bridge guard
+ *   (`ensureBridgeSession`) and was removed with the ACP purge (v2-only),
+ *   so this B-side gate now stands alone as the policy verification surface.
+ *
+ * Module-level state note: model-lock.ts uses two module-level flags
+ * (`reverting`, `sessionLocked`) that persist across tests in the same
+ * Node process. Each `makeHarness` call explicitly establishes the
+ * starting state via `initial:` so tests do not implicitly depend on
+ * order.
+ *
+ * See AGENTS.md § session model lock, NEXT.md § Session model lock.
+ */
+
+import assert from "node:assert/strict";
+
+import modelLockExtension from "../pi-extensions/model-lock.ts";
+
+type Provider = string;
+type ModelLike = { provider: Provider; id: string };
+type Source = "set" | "cycle" | "restore";
+type SessionStartReason = "startup" | "reload" | "new" | "resume" | "fork";
+
+interface ModelSelectEventLike {
+	type: "model_select";
+	model: ModelLike;
+	previousModel: ModelLike | undefined;
+	source: Source;
+}
+
+interface SessionStartEventLike {
+	type: "session_start";
+	reason: SessionStartReason;
+	previousSessionFile?: string;
+}
+
+interface AgentStartEventLike {
+	type: "agent_start";
+}
+
+interface EntryLike {
+	type: string;
+}
+
+interface NotifyCall {
+	message: string;
+	level: "info" | "warning" | "error";
+}
+
+interface Harness {
+	dispatchSessionStart(reason: SessionStartReason): Promise<void>;
+	dispatchAgentStart(): Promise<void>;
+	dispatch(event: ModelSelectEventLike): Promise<void>;
+	setEntries(entries: EntryLike[]): void;
+	setEntriesThrowing(throwing: boolean): void;
+	setModelCalls: ModelLike[];
+	notifyCalls: NotifyCall[];
+	emitsDuringSetModel(): number;
+}
+
+/**
+ * `initial` controls the starting state of module-level `sessionLocked`:
+ *
+ *   "locked"   — emit session_start "resume" (immediate lock). Default for
+ *                tests 1-9 which predate the sessionLocked gate.
+ *   "unlocked" — emit session_start "startup" with empty entries (no lock).
+ *                For tests verifying pre-turn freedom.
+ *   "manual"   — emit nothing. Test code drives session_start /
+ *                agent_start explicitly. For tests with multi-step
+ *                state setup (e.g., test 17 reload-preserve).
+ */
+type InitialState = "locked" | "unlocked" | "manual";
+
+interface MakeHarnessOpts {
+	setModelReturns?: boolean;
+	initial?: InitialState;
+	entries?: EntryLike[];
+}
+
+async function makeHarness(opts: MakeHarnessOpts = {}): Promise<Harness> {
+	const setModelReturns = opts.setModelReturns ?? true;
+	const initial: InitialState = opts.initial ?? "locked";
+	let entries: EntryLike[] = opts.entries ?? [];
+	let entriesThrowing = false;
+
+	const modelSelectHandlers: Array<(event: ModelSelectEventLike, ctx: unknown) => Promise<void> | void> = [];
+	const sessionStartHandlers: Array<(event: SessionStartEventLike, ctx: unknown) => Promise<void> | void> = [];
+	const agentStartHandlers: Array<(event: AgentStartEventLike, ctx: unknown) => Promise<void> | void> = [];
+
+	const setModelCalls: ModelLike[] = [];
+	const notifyCalls: NotifyCall[] = [];
+	let emitsDuringSetModel = 0;
+
+	const ctx = {
+		ui: {
+			notify(message: string, level: "info" | "warning" | "error" = "info"): void {
+				notifyCalls.push({ message, level });
+			},
+		},
+		sessionManager: {
+			getEntries(): EntryLike[] {
+				if (entriesThrowing) throw new Error("simulated session-manager teardown");
+				return entries;
+			},
+		},
+	};
+
+	const pi = {
+		on(event: string, handler: any): void {
+			if (event === "model_select") modelSelectHandlers.push(handler);
+			else if (event === "session_start") sessionStartHandlers.push(handler);
+			else if (event === "agent_start") agentStartHandlers.push(handler);
+		},
+		async setModel(model: ModelLike): Promise<boolean> {
+			setModelCalls.push(model);
+			// Simulate pi-core: AgentSession.setModel emits a synthetic
+			// model_select with source "set" AFTER mutating state. The
+			// reentry guard must catch this and skip.
+			const syntheticEvent: ModelSelectEventLike = {
+				type: "model_select",
+				model,
+				previousModel: { provider: "fake-prev", id: "synthetic" },
+				source: "set",
+			};
+			emitsDuringSetModel += 1;
+			for (const handler of modelSelectHandlers) {
+				await handler(syntheticEvent, ctx);
+			}
+			return setModelReturns;
+		},
+	};
+
+	// Register the extension. After this, handlers[] arrays hold the listeners.
+	modelLockExtension(pi as any);
+
+	const harness: Harness = {
+		async dispatchSessionStart(reason: SessionStartReason) {
+			for (const handler of sessionStartHandlers) {
+				await handler({ type: "session_start", reason }, ctx);
+			}
+		},
+		async dispatchAgentStart() {
+			for (const handler of agentStartHandlers) {
+				await handler({ type: "agent_start" }, ctx);
+			}
+		},
+		async dispatch(event: ModelSelectEventLike) {
+			for (const handler of modelSelectHandlers) {
+				await handler(event, ctx);
+			}
+		},
+		setEntries(next: EntryLike[]) {
+			entries = next;
+		},
+		setEntriesThrowing(throwing: boolean) {
+			entriesThrowing = throwing;
+		},
+		setModelCalls,
+		notifyCalls,
+		emitsDuringSetModel: () => emitsDuringSetModel,
+	};
+
+	// Establish the requested initial state via real handler dispatch so
+	// module-level `sessionLocked` reflects the choice deterministically,
+	// overriding whatever the previous test left behind.
+	if (initial === "locked") {
+		await harness.dispatchSessionStart("resume");
+	} else if (initial === "unlocked") {
+		// startup with empty entries → sessionLocked = false
+		entries = [];
+		await harness.dispatchSessionStart("startup");
+	}
+	// "manual": leave whatever module state is. Test must drive session_start
+	// explicitly before any model_select assertion.
+
+	return harness;
+}
+
+// Test models.
+const NATIVE_A: ModelLike = { provider: "openai-codex", id: "gpt-5.4" };
+const NATIVE_B: ModelLike = { provider: "openai-codex", id: "gpt-5.5" };
+const PSA_SONNET: ModelLike = { provider: "entwurf", id: "claude-sonnet-4-6" };
+const PSA_OPUS: ModelLike = { provider: "entwurf", id: "claude-opus-4-8" };
+
+let passed = 0;
+let failed = 0;
+
+async function run(name: string, body: () => Promise<void>): Promise<void> {
+	try {
+		await body();
+		console.log(`  ok   ${name}`);
+		passed += 1;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		console.error(`  FAIL ${name}`);
+		console.error(`       ${msg}`);
+		failed += 1;
+	}
+}
+
+console.log("[check-model-lock] policy unit tests");
+
+// =============================================================================
+// Tests 1-9 — original policy matrix (sessionLocked=true via default "locked")
+// =============================================================================
+
+await run("1. native → native: no-op (touchesEntwurf=false)", async () => {
+	const h = await makeHarness();
+	await h.dispatch({ type: "model_select", model: NATIVE_B, previousModel: NATIVE_A, source: "set" });
+	assert.equal(h.setModelCalls.length, 0);
+	assert.equal(h.notifyCalls.length, 0);
+});
+
+await run("2. native → entwurf: revert + warning notify", async () => {
+	const h = await makeHarness();
+	await h.dispatch({ type: "model_select", model: PSA_SONNET, previousModel: NATIVE_A, source: "set" });
+	assert.equal(h.setModelCalls.length, 1);
+	assert.deepEqual(h.setModelCalls[0], NATIVE_A);
+	assert.equal(h.notifyCalls.length, 1);
+	assert.equal(h.notifyCalls[0].level, "warning");
+	assert.match(h.notifyCalls[0].message, /locked to openai-codex\/gpt-5\.4/);
+	assert.match(h.notifyCalls[0].message, /entwurf\/claude-sonnet-4-6/);
+});
+
+await run("3. entwurf → native: revert + warning notify", async () => {
+	const h = await makeHarness();
+	await h.dispatch({ type: "model_select", model: NATIVE_A, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 1);
+	assert.deepEqual(h.setModelCalls[0], PSA_SONNET);
+	assert.equal(h.notifyCalls.length, 1);
+	assert.equal(h.notifyCalls[0].level, "warning");
+});
+
+await run("4. entwurf/X → entwurf/Y (id differs): revert + warning notify", async () => {
+	const h = await makeHarness();
+	await h.dispatch({ type: "model_select", model: PSA_OPUS, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 1, "B reverts same-provider mismatch BEFORE next prompt");
+	assert.deepEqual(h.setModelCalls[0], PSA_SONNET);
+	assert.equal(h.notifyCalls.length, 1);
+	assert.equal(h.notifyCalls[0].level, "warning");
+});
+
+await run("5. entwurf → entwurf (same id): no-op (changed=false)", async () => {
+	const h = await makeHarness();
+	await h.dispatch({ type: "model_select", model: PSA_SONNET, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 0);
+	assert.equal(h.notifyCalls.length, 0);
+});
+
+await run("6. undefined → entwurf (first selection): no-op (!from)", async () => {
+	const h = await makeHarness();
+	await h.dispatch({ type: "model_select", model: PSA_SONNET, previousModel: undefined, source: "set" });
+	assert.equal(h.setModelCalls.length, 0);
+	assert.equal(h.notifyCalls.length, 0);
+});
+
+await run('7. source="restore": no-op (skip restore)', async () => {
+	const h = await makeHarness();
+	await h.dispatch({ type: "model_select", model: PSA_SONNET, previousModel: NATIVE_A, source: "restore" });
+	assert.equal(h.setModelCalls.length, 0);
+	assert.equal(h.notifyCalls.length, 0);
+});
+
+await run("8. Reentry guard: synthetic model_select inside setModel must NOT re-trigger revert", async () => {
+	const h = await makeHarness();
+	await h.dispatch({ type: "model_select", model: PSA_SONNET, previousModel: NATIVE_A, source: "set" });
+	assert.equal(h.setModelCalls.length, 1, "setModel must be called exactly once (no reentry)");
+	assert.equal(h.emitsDuringSetModel(), 1, "exactly one synthetic emit happened (sanity check)");
+	assert.equal(h.notifyCalls.length, 1, "notify must be called exactly once (no reentry)");
+});
+
+await run("9. setModel returns false (auth missing): notify level error", async () => {
+	const h = await makeHarness({ setModelReturns: false });
+	await h.dispatch({ type: "model_select", model: NATIVE_A, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 1);
+	assert.equal(h.notifyCalls.length, 1);
+	assert.equal(h.notifyCalls[0].level, "error");
+	assert.match(h.notifyCalls[0].message, /failed to revert/);
+});
+
+// =============================================================================
+// Tests 10-18 — session lifecycle gate (sessionLocked)
+// =============================================================================
+
+await run('10. session_start "startup" + entries=0: lock NOT engaged, model_select no-op', async () => {
+	const h = await makeHarness({ initial: "unlocked" });
+	// Pre-turn model change (CLI --model, settings.json default, etc.) — must be free.
+	await h.dispatch({ type: "model_select", model: PSA_SONNET, previousModel: NATIVE_A, source: "set" });
+	assert.equal(h.setModelCalls.length, 0, "lock must NOT fire before first agent_start");
+	assert.equal(h.notifyCalls.length, 0);
+});
+
+await run('11. session_start "startup" + entries have a message: lock engaged', async () => {
+	// Future-proof guard: pi-mono currently distinguishes resume from
+	// startup, but if a future pi version loads a saved session under
+	// "startup" the entries-based check engages the lock.
+	const h = await makeHarness({ initial: "manual", entries: [{ type: "message" }] });
+	await h.dispatchSessionStart("startup");
+	await h.dispatch({ type: "model_select", model: NATIVE_A, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 1, "saved-session-on-startup engages the lock");
+	assert.equal(h.notifyCalls[0].level, "warning");
+});
+
+await run('12. session_start "startup" empty → agent_start → lock engaged', async () => {
+	const h = await makeHarness({ initial: "unlocked" });
+	// Pre-turn: still unlocked, change allowed.
+	await h.dispatch({ type: "model_select", model: PSA_OPUS, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 0, "pre-turn no-op");
+
+	// First prompt arrives → agent_start fires → lock engaged.
+	await h.dispatchAgentStart();
+	await h.dispatch({ type: "model_select", model: NATIVE_A, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 1, "post agent_start lock engaged");
+	assert.equal(h.notifyCalls[0].level, "warning");
+});
+
+await run('13. session_start "resume": lock engaged immediately', async () => {
+	const h = await makeHarness({ initial: "manual" });
+	await h.dispatchSessionStart("resume");
+	await h.dispatch({ type: "model_select", model: NATIVE_A, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 1, "resume engages lock without needing agent_start");
+	assert.equal(h.notifyCalls[0].level, "warning");
+});
+
+await run('14. session_start "new" + entries=0: lock NOT engaged', async () => {
+	const h = await makeHarness({ initial: "manual" });
+	await h.dispatchSessionStart("new");
+	await h.dispatch({ type: "model_select", model: PSA_SONNET, previousModel: NATIVE_A, source: "set" });
+	assert.equal(h.setModelCalls.length, 0, "new session pre-turn must be free");
+});
+
+await run('15. session_start "reload" + entries have a message: lock engaged', async () => {
+	const h = await makeHarness({ initial: "manual", entries: [{ type: "message" }] });
+	await h.dispatchSessionStart("reload");
+	await h.dispatch({ type: "model_select", model: NATIVE_A, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 1, "reload of an active session engages lock");
+});
+
+await run('16. session_start "fork": lock engaged immediately', async () => {
+	const h = await makeHarness({ initial: "manual" });
+	await h.dispatchSessionStart("fork");
+	await h.dispatch({ type: "model_select", model: NATIVE_A, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 1, "fork engages lock immediately");
+});
+
+await run('17. session_start "reload" + entries=0 BUT prior sessionLocked=true: lock preserved', async () => {
+	// This is the GPT-flagged edge case: a session that already locked
+	// (via earlier agent_start or resume) must survive a reload even
+	// if message entries are not visible at the reload instant. The
+	// guard `sessionLocked = sessionLocked || hasStartedConversation(ctx)`
+	// keeps the prior `true` instead of resetting to `false`.
+	const h = await makeHarness({ initial: "manual" });
+	await h.dispatchSessionStart("resume"); // sessionLocked = true
+	h.setEntries([]); // simulate entries momentarily empty at reload boundary
+	await h.dispatchSessionStart("reload"); // sessionLocked = true || false = true (preserved)
+	await h.dispatch({ type: "model_select", model: NATIVE_A, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 1, "reload must NOT release a prior lock");
+	assert.equal(h.notifyCalls[0].level, "warning");
+});
+
+await run("18. getEntries() throws: defensive catch engages the lock", async () => {
+	const h = await makeHarness({ initial: "manual" });
+	h.setEntriesThrowing(true);
+	// Without the try/catch fallback, this dispatch would propagate the
+	// throw and the module would be in an indeterminate state. With the
+	// `catch { return true }` defensive probe, the lock engages.
+	await h.dispatchSessionStart("startup");
+	await h.dispatch({ type: "model_select", model: NATIVE_A, previousModel: PSA_SONNET, source: "set" });
+	assert.equal(h.setModelCalls.length, 1, "throwing probe must conservatively engage lock");
+});
+
+console.log("");
+console.log(`[check-model-lock] ${passed} passed, ${failed} failed`);
+
+if (failed > 0) {
+	process.exit(1);
+}

package/scripts/check-package-source-routing.ts

@@ -0,0 +1,253 @@
+/**
+ * check-package-source-routing — deterministic gate for #29 (package-installed
+ * Entwurf ACP routing). No backend, no spawn, no API cost.
+ *
+ * Pins resolveExplicitExtensionSpec()'s package-source → install-root mapping and
+ * the fail-fast routing contract, exercised through the two public routing
+ * surfaces the spawn/resume paths actually call:
+ *
+ *   - getRegistryRouting(target, isRemote)            — spawn path
+ *   - getEntwurfExplicitExtensions(model, isRemote, recordedProvider) — resume path
+ *
+ * The original bug: a `git:` / `npm:` Pi settings package source returned null,
+ * so `provider=entwurf` spawned a `--no-extensions` child that died with
+ * `Unknown provider "entwurf"`. This gate covers the install matrix:
+ *
+ *   local path / git user / npm user (+ version spec) / install-missing /
+ *   project-scope (unseen → unresolved) / no-source, across local + remote,
+ *   plus the self-root fallback property and the resume fail-fast signal.
+ *
+ * Self-root note: for LOCAL entwurf resolution the parent module's own path
+ * is a valid bridge root, so local resolution always succeeds even when settings
+ * has no source — that IS the desired "local always works" property. Fail-fast is
+ * therefore asserted on the REMOTE path, where a local self-root cannot cross SSH.
+ *
+ * Env-isolation: PI_CODING_AGENT_DIR / PI_SETTINGS_PATH are set to temp paths
+ * before the resolver is imported (directly or in the subprocess env-check), so
+ * the module-level AGENT_DIR / PI_SETTINGS_PATH consts capture them. The real
+ * ~/.pi/agent is never read or written; os.homedir() is only used to build the
+ * EXPECTED remote path string (proving the local override does not leak remote).
+ */
+
+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";
+import { fileURLToPath } from "node:url";
+import type { ResolvedTarget } from "../pi-extensions/lib/entwurf-core.ts";
+
+// --- Isolated agent dir (must be set BEFORE importing entwurf-core) ----------
+const tmpAgent = fs.mkdtempSync(path.join(os.tmpdir(), "psa-route-"));
+process.env.PI_CODING_AGENT_DIR = tmpAgent;
+delete process.env.ENTWURF_ACP_FOR_CODEX; // control wantsCodexBridge per-case
+
+// Dynamic import so the resolver's AGENT_DIR / PI_SETTINGS_PATH consts capture
+// the env above. A static import would evaluate them against the real ~/.pi.
+const core = await import("../pi-extensions/lib/entwurf-core.ts");
+const { getRegistryRouting, getEntwurfExplicitExtensions, EntwurfRoutingError } = core;
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SETTINGS_PATH = path.join(tmpAgent, "settings.json");
+const REMOTE_AGENT = path.posix.join(os.homedir(), ".pi", "agent");
+
+let passed = 0;
+function check(label: string, fn: () => void): void {
+	fn();
+	passed += 1;
+	console.log(`[check-package-source-routing] ${label}: ok`);
+}
+
+// --- Fixture helpers ---------------------------------------------------------
+function setSource(source: string | null): void {
+	const packages = source ? [source] : [];
+	fs.writeFileSync(SETTINGS_PATH, JSON.stringify({ packages }, null, 2));
+}
+
+function makeInstallDir(...segs: string[]): string {
+	const dir = path.join(tmpAgent, ...segs);
+	fs.mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+function rmInstall(...segs: string[]): void {
+	fs.rmSync(path.join(tmpAgent, ...segs), { recursive: true, force: true });
+}
+
+const ACP: ResolvedTarget = { provider: "entwurf", model: "claude-sonnet-4-6", explicitOnly: false };
+const eArg = (r: { args: string[] }): string | undefined => {
+	const i = r.args.indexOf("-e");
+	return i >= 0 ? r.args[i + 1] : undefined;
+};
+
+// =============================================================================
+// LOCAL spawn (getRegistryRouting, isRemote=false)
+// =============================================================================
+
+// 1. Local path package source resolves to <agentDir>/<source>.
+check("local-path source resolves to agentDir-relative root", () => {
+	const root = makeInstallDir("local-pkgs", "entwurf");
+	setSource("local-pkgs/entwurf");
+	const r = getRegistryRouting(ACP, false);
+	assert.equal(r.provider, "entwurf");
+	assert.equal(eArg(r), root);
+});
+
+// 2. git: user source → <agentDir>/git/<host>/<path>.
+check("git: source resolves to agentDir/git/<host>/<path>", () => {
+	const root = makeInstallDir("git", "github.com", "junghan0611", "entwurf");
+	setSource("git:github.com/junghan0611/entwurf");
+	const r = getRegistryRouting(ACP, false);
+	assert.equal(eArg(r), root);
+});
+
+// 3. npm: user source → <agentDir>/npm/node_modules/<name>.
+check("npm: source resolves to agentDir/npm/node_modules/<name>", () => {
+	const root = makeInstallDir("npm", "node_modules", "@junghanacs", "entwurf");
+	setSource("npm:@junghanacs/entwurf");
+	const r = getRegistryRouting(ACP, false);
+	assert.equal(eArg(r), root);
+});
+
+// 4. npm: source WITH a version spec — root keys on the bare name, version stripped.
+check("npm: source with @version strips the version from the install root", () => {
+	const root = makeInstallDir("npm", "node_modules", "@junghanacs", "entwurf");
+	setSource("npm:@junghanacs/entwurf@0.8.0");
+	const r = getRegistryRouting(ACP, false);
+	assert.equal(eArg(r), root);
+});
+
+// 5. Self-root fallback — settings source absent, but LOCAL resolution still
+//    succeeds via the loaded module's own root (the "local always works" property).
+check("local self-root fallback resolves when settings has no source", () => {
+	rmInstall("git");
+	rmInstall("npm");
+	rmInstall("local-pkgs");
+	setSource(null);
+	const r = getRegistryRouting(ACP, false);
+	assert.equal(eArg(r), REPO_ROOT, "self-root should be the entwurf-core package root");
+});
+
+// 6. Native provider passes through untouched — no bridge, no throw.
+check("native provider target passes through with no -e and no throw", () => {
+	setSource(null);
+	const r = getRegistryRouting({ provider: "openai-codex", model: "gpt-5.4", explicitOnly: false }, false);
+	assert.equal(r.provider, "openai-codex");
+	assert.equal(eArg(r), undefined);
+});
+
+// =============================================================================
+// REMOTE spawn (getRegistryRouting, isRemote=true) — self-root excluded
+// =============================================================================
+
+// 7. git: remote → remotePath uses the plain ~/.pi/agent layout, NOT the local
+//    PI_CODING_AGENT_DIR override (no local-env leak into the SSH path).
+check("git: remote resolves to ~/.pi/agent/git/... (no local-env leak)", () => {
+	makeInstallDir("git", "github.com", "junghan0611", "entwurf"); // local mirror gates existence
+	setSource("git:github.com/junghan0611/entwurf");
+	const r = getRegistryRouting(ACP, true);
+	assert.equal(eArg(r), path.posix.join(REMOTE_AGENT, "git", "github.com", "junghan0611", "entwurf"));
+});
+
+// 8. npm: remote with version → ~/.pi/agent/npm/node_modules/<name>.
+check("npm: remote with @version resolves to ~/.pi/agent/npm/node_modules/<name>", () => {
+	makeInstallDir("npm", "node_modules", "@junghanacs", "entwurf");
+	setSource("npm:@junghanacs/entwurf@0.8.0");
+	const r = getRegistryRouting(ACP, true);
+	assert.equal(eArg(r), path.posix.join(REMOTE_AGENT, "npm", "node_modules", "@junghanacs", "entwurf"));
+});
+
+// 9. Install dir missing, remote → fail-fast (EntwurfRoutingError), NOT warn-and-spawn.
+check("remote git: with missing install dir throws EntwurfRoutingError", () => {
+	rmInstall("git");
+	setSource("git:github.com/junghan0611/entwurf");
+	assert.throws(() => getRegistryRouting(ACP, true), EntwurfRoutingError);
+});
+
+// 10. No source in settings, remote → fail-fast.
+check("remote with no settings source throws EntwurfRoutingError", () => {
+	setSource(null);
+	assert.throws(() => getRegistryRouting(ACP, true), EntwurfRoutingError);
+});
+
+// 10b. PI_SETTINGS_PATH override must be honored independently from
+//      PI_CODING_AGENT_DIR/settings.json. This is run in a subprocess because
+//      entwurf-core captures the env at module import time.
+check("PI_SETTINGS_PATH env override is honored", () => {
+	const agent = fs.mkdtempSync(path.join(os.tmpdir(), "psa-route-settings-"));
+	try {
+		const root = path.join(agent, "git", "github.com", "junghan0611", "entwurf");
+		fs.mkdirSync(root, { recursive: true });
+		const settingsPath = path.join(agent, "custom-settings.json");
+		fs.writeFileSync(settingsPath, JSON.stringify({ packages: ["git:github.com/junghan0611/entwurf"] }));
+		const out = execFileSync(
+			process.execPath,
+			["--experimental-strip-types", path.join(REPO_ROOT, "scripts", "resolve-acp-bridge.ts"), "remote"],
+			{
+				env: { ...process.env, PI_CODING_AGENT_DIR: agent, PI_SETTINGS_PATH: settingsPath },
+				encoding: "utf8",
+			},
+		);
+		assert.equal(out, path.posix.join(REMOTE_AGENT, "git", "github.com", "junghan0611", "entwurf"));
+	} finally {
+		fs.rmSync(agent, { recursive: true, force: true });
+	}
+});
+
+// 11. Project-scope (-l) sources live in cwd/.pi, never user settings.json, so the
+//     resolver never sees them — they resolve to nothing and fail-fast on remote
+//     rather than silently emitting Unknown provider.
+check("project-scope source (unseen in user settings) fails fast on remote", () => {
+	// A project install would record under ./.pi; user settings stays empty.
+	setSource(null);
+	assert.throws(() => getRegistryRouting(ACP, true), EntwurfRoutingError);
+});
+
+// =============================================================================
+// RESUME path (getEntwurfExplicitExtensions) — unresolvedAcpIntent signal
+// =============================================================================
+
+// 12. recorded provider=entwurf + remote + no source → unresolvedAcpIntent
+//     (resume callers fail-fast; no -e injected).
+check("resume recorded entwurf + remote + no source → unresolvedAcpIntent", () => {
+	setSource(null);
+	const r = getEntwurfExplicitExtensions("claude-sonnet-4-6", true, "entwurf");
+	assert.equal(r.unresolvedAcpIntent, true);
+	assert.equal(eArg(r), undefined);
+	assert.ok(r.warnings.length > 0, "should warn about the unresolved bridge");
+});
+
+// 13. recorded provider=entwurf + LOCAL → self-root resolves, no fail-fast.
+check("resume recorded entwurf + local resolves via self-root", () => {
+	setSource(null);
+	const r = getEntwurfExplicitExtensions("claude-sonnet-4-6", false, "entwurf");
+	assert.ok(!r.unresolvedAcpIntent, "local self-root should resolve");
+	assert.equal(eArg(r), REPO_ROOT);
+	assert.equal(r.provider, "entwurf");
+});
+
+// 14. opt-in Codex-via-ACP + remote + no source → unresolvedAcpIntent (fail-fast).
+check("resume Codex-via-ACP opt-in + remote + no source → unresolvedAcpIntent", () => {
+	setSource(null);
+	process.env.ENTWURF_ACP_FOR_CODEX = "1";
+	try {
+		const r = getEntwurfExplicitExtensions("gpt-5.4", true, undefined);
+		assert.equal(r.unresolvedAcpIntent, true);
+	} finally {
+		delete process.env.ENTWURF_ACP_FOR_CODEX;
+	}
+});
+
+// 15. Claude-only heuristic (no recorded ACP signal) stays warning-only — NOT
+//     fail-fast — because the legacy pi-claude-code-use bridge may exist.
+check("resume Claude-only heuristic + remote + no source stays warning-only", () => {
+	setSource(null);
+	const r = getEntwurfExplicitExtensions("claude-sonnet-4-6", true, undefined);
+	assert.ok(!r.unresolvedAcpIntent, "Claude heuristic must not fail-fast");
+	assert.ok(r.warnings.length > 0, "should warn");
+	assert.equal(eArg(r), undefined);
+});
+
+// --- Cleanup + summary -------------------------------------------------------
+fs.rmSync(tmpAgent, { recursive: true, force: true });
+console.log(`[check-package-source-routing] ${passed} assertions ok`);