pi-crew 0.11.5 → 0.11.7

package/src/runtime/model/model-scope.ts

@@ -11,11 +11,34 @@
  *   - defaultSubagentModel / parentModel-inherited out-of-scope
  *     → WARNING + runs anyway (soft warn, same as frontmatter).
  *
- * Pattern semantics match pi's `--models` CLI / `enabledModels` allowlist:
- *   - `"anthropic/claude-opus-4-5"` — exact match (case-insensitive).
- *   - `"claude-*"`, `"*sonnet*"`, `"github-copilot/*"` — glob (single `*`).
- *   - Any other string — case-insensitive substring fallback (pi's
- *     `tryMatchModel` behavior, model-resolver.ts).
+ * Pattern semantics mirror pi 1.0.0's canonical `resolveModelScopeFromModels()`
+ * (SDK `core/model-resolver.js:204-270`) and `parseModelPattern()` (:155-200) —
+ * R3-20 alignment (docs/reviews/pi-1.0.0-deep-learn-r3-2026-10-03.md §R3b.3):
+ *   - Optional `:<thinking>` suffix (`off|minimal|low|medium|high|xhigh|max`,
+ *     case-sensitive) is stripped from patterns AND resolved model ids before
+ *     matching, so `anthropic/claude-sonnet-5:high` in enabledModels no longer
+ *     falsely rejects the plain model id (hard-error bug).
+ *   - A pattern containing ANY of `*`, `?`, `[` is a glob, translated with
+ *     minimatch semantics (`*`/`?` do not cross `/`, `[...]`/`[!...]` classes,
+ *     whole-segment `**` crosses separators), anchored + case-insensitive.
+ *   - Globs are tried against BOTH the configured `provider/id` form and the
+ *     bare model id (after the first `/`), mirroring
+ *     `minimatch(fullId, p) || minimatch(id, p)` — so `gpt-5*` matches
+ *     `openai/gpt-5-mini`.
+ *   - Non-glob patterns fall back to case-insensitive substring, progressively
+ *     stripping trailing colon suffixes (mirrors parseModelPattern's
+ *     recursion: valid levels become thinking hints, invalid ones are
+ *     recursed through with a warning — membership still follows the prefix).
+ *
+ * Why reimplement instead of importing the canonical matcher: the SDK does
+ * NOT export `resolveModelScopeFromModels` from the package root (runtime-
+ * verified: only `resolveModelScopeWithDiagnostics` is exported, and it needs
+ * a live async `ModelRuntime` + catalog I/O). This gate is synchronous and
+ * this module is pure by design, so an exact-semantics reimplementation is
+ * the only import-compatible option. Residual divergence (documented, not
+ * fixable string-level): canonical fuzzy also matches model display `name`s
+ * (`model-resolver.js:114-115`), which requires the catalog — display-name-
+ * only patterns (e.g. `"Claude Opus 4.5"`) stay unmatched here.
  *
  * This module is pure (no I/O, no globals). Reading the actual
  * `enabledModels` from pi's settings is the caller's job (instantiate
@@ -41,37 +64,134 @@ export interface ModelScopeCheck {
 }
 
 /**
- * Convert a glob pattern with `*` wildcards into a RegExp.
- * Escape all regex meta-characters except `*`, which becomes `.*`.
- * Anchored (^...$) and case-insensitive.
+ * Valid `:<thinking>` level names — mirrors pi's `VALID_THINKING_LEVELS`
+ * (SDK `cli/args.js`). Matched case-sensitively, exactly like the canonical
+ * `isValidThinkingLevel()`, so OpenRouter-style ids (`foo:exacto`) and
+ * mistyped levels (`:HIGH`) are NOT treated as thinking suffixes.
+ */
+const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+function isValidThinkingLevel(level: string): boolean {
+	return (VALID_THINKING_LEVELS as readonly string[]).includes(level);
+}
+
+/**
+ * Strip one trailing VALID `:<thinking>` suffix — the canonical glob-branch
+ * rule (model-resolver.js:214-222). Invalid suffixes are left in place here;
+ * the fuzzy branch strips them progressively instead (parseModelPattern
+ * recursion) — see matchesModelPattern.
+ */
+function stripValidThinkingSuffix(value: string): string {
+	const colonIdx = value.lastIndexOf(":");
+	if (colonIdx === -1) return value;
+	return isValidThinkingLevel(value.substring(colonIdx + 1)) ? value.substring(0, colonIdx) : value;
+}
+
+/** Does the pattern contain glob characters? Canonical test: `*`, `?` or `[`. */
+function hasGlobChars(pattern: string): boolean {
+	return pattern.includes("*") || pattern.includes("?") || pattern.includes("[");
+}
+
+/** Escape a literal character for use in a RegExp body. */
+function escapeRegExpChar(ch: string): string {
+	return /[.+^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+
+/**
+ * Convert a glob pattern into an anchored, case-insensitive RegExp with
+ * minimatch semantics (canonical uses `minimatch(p, { nocase: true })`):
+ *   - `*`  → `[^/]*` (any run of non-separator chars; does NOT cross `/`)
+ *   - `?`  → `[^/]` (exactly one non-separator char)
+ *   - `[...]` / `[!...]` / `[^...]` → character class (both `!` and `^` negate)
+ *   - `[` without a closing `]` → literal `[`
+ *   - a whole-segment run of `**` → `.*` (crosses separators, but still
+ *     requires the preceding `/` — `anthropic/**` does not match `anthropic`)
+ *   - everything else → regex-escaped literal
  */
 export function patternToRegExp(pattern: string): RegExp {
-	const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
-	return new RegExp(`${escaped.replace(/\*/g, ".*")}`, "i");
+	let out = "^";
+	for (let i = 0; i < pattern.length; i++) {
+		const ch = pattern[i];
+		if (ch === "*") {
+			let end = i;
+			while (end < pattern.length && pattern[end] === "*") end++;
+			const wholeSegment = (i === 0 || pattern[i - 1] === "/") && (end === pattern.length || pattern[end] === "/");
+			out += end - i >= 2 && wholeSegment ? ".*" : "[^/]*";
+			i = end - 1;
+		} else if (ch === "?") {
+			out += "[^/]";
+		} else if (ch === "[") {
+			const closing = pattern.indexOf("]", i + 1);
+			let inner = closing === -1 ? "" : pattern.substring(i + 1, closing);
+			let negated = false;
+			if (inner.startsWith("!") || inner.startsWith("^")) {
+				negated = true;
+				inner = inner.substring(1);
+			}
+			if (closing === -1 || inner.length === 0) {
+				// Unmatched `[` (or empty class `[]`/`[!]`) → literal, like minimatch.
+				out += "\\[";
+			} else {
+				let cls = "";
+				for (const c of inner) {
+					if (c === "\\") cls += "\\\\";
+					else if (c === "]") cls += "\\]";
+					else cls += c;
+				}
+				out += `[${negated ? "^" : ""}${cls}]`;
+				i = closing;
+			}
+		} else {
+			out += escapeRegExpChar(ch);
+		}
+	}
+	return new RegExp(`${out}$`, "i");
 }
 
 /**
  * Does a model id match a single allowlist pattern?
- * Semantics (in order):
- *   1. Exact case-insensitive match.
- *   2. Glob match (pattern contains `*`).
- *   3. Case-insensitive substring match (pi's fallback).
+ * Mirrors the canonical `resolveModelScopeFromModels()` per-pattern flow:
+ *   - Glob branch (pattern contains `*`, `?` or `[`): strip one VALID
+ *     `:<thinking>` suffix, try the exact reference first, then match the
+ *     glob against BOTH the configured string and its bare-id form
+ *     (`minimatch(fullId, p) || minimatch(id, p)`, model-resolver.js:228-232).
+ *   - Fuzzy branch (parseModelPattern): substring match, progressively
+ *     stripping trailing colon suffixes until a hit or no colon remains.
  * Returns true on first hit; false otherwise.
  */
 export function matchesModelPattern(modelId: string, pattern: string): boolean {
 	if (!modelId || !pattern) return false;
-	const id = modelId.trim();
-	const pat = pattern.trim();
-	if (!id || !pat) return false;
-	if (id.toLowerCase() === pat.toLowerCase()) return true;
-	if (pat.includes("*")) {
+	const rawId = modelId.trim();
+	const rawPat = pattern.trim();
+	if (!rawId || !rawPat) return false;
+	// Canonical compares thinking-less base ids: pi-crew's resolved candidates
+	// keep their `:high` suffix (splitThinkingSuffix), and user patterns may
+	// carry one — strip valid suffixes from BOTH sides before matching.
+	const id = stripValidThinkingSuffix(rawId);
+	// Bare-id form = everything after the FIRST `/` (the provider segment);
+	// openrouter-style ids can themselves contain slashes.
+	const bareId = id.includes("/") ? id.substring(id.indexOf("/") + 1) : id;
+	if (hasGlobChars(rawPat)) {
+		const glob = stripValidThinkingSuffix(rawPat);
+		if (id.toLowerCase() === glob.toLowerCase() || bareId.toLowerCase() === glob.toLowerCase()) {
+			return true;
+		}
 		try {
-			return patternToRegExp(pat).test(id);
+			const re = patternToRegExp(glob);
+			return re.test(id) || re.test(bareId);
 		} catch {
 			return false;
 		}
 	}
-	return id.toLowerCase().includes(pat.toLowerCase());
+	let pat = rawPat;
+	for (;;) {
+		// Substring over the configured form is a superset of canonical's
+		// exact-then-substring over the same string, so verdicts agree.
+		if (id.toLowerCase().includes(pat.toLowerCase())) return true;
+		const colonIdx = pat.lastIndexOf(":");
+		if (colonIdx === -1) return false;
+		pat = pat.substring(0, colonIdx);
+	}
 }
 
 /**

package/src/runtime/model/pi-args.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentConfig } from "../../agents/agent-config.ts";
+import { getCrewEnvBool } from "../../config/env-vars.ts";
 import { atomicWriteFile } from "../../state/atomic-write.ts";
 import { hasRunStateLayout, packageRoot, userPiRoot } from "../../utils/paths.ts";
 
@@ -15,7 +16,6 @@ const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 // find pi-crew's package.json and works correctly from both src/ and
 // dist/ entry points.
 const PROMPT_RUNTIME_EXTENSION_PATH = path.join(packageRoot(), "src", "prompt", "prompt-runtime.ts");
-const TASK_ARG_LIMIT = 8000;
 // D8 spec v0.7 — nested mở (default 4 depth levels: child→child→child→child);
 // cap giữ để chống runaway recursion từ config lỗi hoặc intentional abuse.
 const DEFAULT_MAX_CREW_DEPTH = 4;
@@ -41,6 +41,15 @@ export interface BuildPiWorkerArgsInput {
 	agent: AgentConfig;
 	model?: string;
 	sessionEnabled?: boolean;
+	/** W2 (session-file recovery): deterministic pi session id for this worker
+	 *  (`--session-id`, SDK ≥ 0.76.0 — below pi-crew's tested host floor 0.99.2,
+	 *  so emitted unconditionally when set; no capability gate). Same id across
+	 *  retries appends to one session file (SDK §R2.2) — cross-attempt resume. */
+	sessionId?: string;
+	/** W2 (session-file recovery): directory for this worker's session JSONL
+	 *  (`--session-dir`, SDK ≥ 0.30.0). Run-scoped per-worker dir, e.g.
+	 *  `<artifactsRoot>/sessions/<taskId>/` — lives and dies with run artifacts. */
+	sessionDir?: string;
 	maxDepth?: number;
 	skillPaths?: string[];
 	env?: NodeJS.ProcessEnv;
@@ -48,6 +57,24 @@ export interface BuildPiWorkerArgsInput {
 	role?: string;
 	/** Per-role thinking override (teamRole.thinking). Takes precedence over agent.thinking. */
 	thinkingOverride?: string;
+	/** R3-1 (Pi 1.0.0 deep-learn round 3): run-static worker header (Protocol
+	 *  block, mailbox contract, workspace structure, runtime context) riding the
+	 *  `--append-system-prompt` channel instead of the user-message concatenation.
+	 *  Compaction summarizes the user-message span (compaction.md:150-160) but the
+	 *  system prompt survives intact — the parts that must NEVER be lost move here.
+	 *  Task text + dependency context stay in the user message (they SHOULD be
+	 *  summarizable). Final append order: builtin → agent.systemPrompt (if any,
+	 *  honoring its declared replace/append mode) → this header. Probe-verified
+	 *  2026-10-04 (/tmp/pi-r3impl): the append channel and AGENTS.md discovery
+	 *  (project_context section) coexist in one system message. */
+	systemPromptAppend?: string;
+	/** R3-19/D5 (hermetic worker spawns): pass `--no-extensions` on the worker
+	 *  argv. Resolved via resolveHermeticWorkers — env
+	 *  PI_CREW_HERMETIC_WORKERS beats this beats default TRUE. Explicit `-e
+	 *  prompt-runtime` (pushed unconditionally below), agent `extensions:`
+	 *  declarations, and `--skill` flags are unaffected (cli.md:186-191:
+	 *  explicit -e and --skill survive --no-extensions/--no-skills). */
+	hermeticWorkers?: boolean;
 }
 
 export interface BuildPiWorkerArgsResult {
@@ -91,6 +118,17 @@ export function resolveCrewMaxDepth(inputMaxDepth?: number, env: NodeJS.ProcessE
 	return DEFAULT_MAX_CREW_DEPTH;
 }
 
+/**
+ * R3-19/D5 (hermetic worker spawns): resolution order mirrors
+ * resolveSessionRecoveryEnabled — env PI_CREW_HERMETIC_WORKERS beats the
+ * explicit config/runtime value beats default TRUE.
+ */
+export function resolveHermeticWorkers(explicit?: boolean): boolean {
+	const env = getCrewEnvBool("PI_CREW_HERMETIC_WORKERS");
+	if (env !== undefined) return env;
+	return explicit ?? true;
+}
+
 export function checkCrewDepth(
 	inputMaxDepth?: number,
 	env: NodeJS.ProcessEnv = process.env,
@@ -266,6 +304,18 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 	// never sets it, so it can never be matched as a sub-agent.
 	const args = ["--mode", "json", "-p"];
 	if (input.sessionEnabled === false) args.push("--no-session");
+	// W2 (session-file recovery): deterministic session identity so a worker
+	// that dies without a final assistant event (exitCode null / killed) can
+	// have its last COMPLETE assistant turn tail-recovered from the session
+	// JSONL (child-pi.ts settle path → session-recovery.ts). Both flags are
+	// SDK-era flags older than the tested host floor (fact pack §1: session-id
+	// 0.76.0, session-dir 0.30.0 < 0.99.2) → unconditional add, same as the
+	// existing --no-session/--model emissions. Skipped when sessions are off —
+	// under --no-session pi persists nothing, the flags would be meaningless.
+	if (input.sessionEnabled !== false) {
+		if (input.sessionId) args.push("--session-id", input.sessionId);
+		if (input.sessionDir) args.push("--session-dir", input.sessionDir);
+	}
 
 	const resolvedModel = input.model ?? input.agent.model;
 	// H1.a: teamRole.thinking (passed as thinkingOverride) takes precedence over agent.thinking.
@@ -279,8 +329,13 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 		args.push("--thinking", effectiveThinking);
 	}
 
-	// D5 (spec v0.7 §6): default loadout = FULL session (như main session).
-	// --no-extensions/--no-skills/--tools CHỈ xuất hiện khi agent .md khai explicit.
+	// D5 (spec v0.7 §6): default loadout = FULL session (như main session) —
+	// --no-skills/--tools CHỈ xuất hiện khi agent .md khai explicit. R3-19/D5
+	// reversal (2026-10-04): extension discovery is now hermetic by default
+	// (--no-extensions below, off-switch runtime.hermeticWorkers / env
+	// PI_CREW_HERMETIC_WORKERS) — the ambient package stack cost ~1.37s/spawn
+	// and leaked 8 direct-exposure MCP tools + 5 host tools into every worker
+	// (probe C §R3b.6: 431ms vs 1806ms to first stdout record).
 	// "message" MUST stay in CONTROL_TOOLS: it is registered by prompt-runtime
 	// behind the PI_CREW_MSG_ENABLED dormant-env gate (child-pi-spawn.ts sets it
 	// unconditionally), but pi's --tools allowlist filters the tool SURFACE — a
@@ -333,7 +388,13 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 	const excluded = new Set((input.agent.excludeExtensions ?? []).map((name) => path.basename(name).toLowerCase()));
 	declaredExtensions = declaredExtensions.filter((ext) => !excluded.has(path.basename(ext).toLowerCase()));
 	for (const ext of declaredExtensions) args.push("--extension", ext);
-	// KHÔNG còn --no-extensions (extension discovery hoạt động như main session).
+	// R3-19/D5: hermetic spawns — disable discovered/configured/built-in
+	// extensions on worker argv. cli.md:186-187: "Explicit -e paths still
+	// load" — the unconditional prompt-runtime push above and the agent
+	// `extensions:` declarations below survive; --skill flags are a separate
+	// gate. Default ON (resolveHermeticWorkers); surface TUI panes strip the
+	// flag (child-pi.ts stripHeadlessOnlyFlags).
+	if (resolveHermeticWorkers(input.hermeticWorkers)) args.push("--no-extensions");
 	if (input.agent.inheritSkills === false) args.push("--no-skills");
 	for (const skillPath of input.skillPaths ?? []) args.push("--skill", skillPath);
 
@@ -347,18 +408,61 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 		atomicWriteFile(promptPath, input.agent.systemPrompt, { mode: 0o600 });
 		args.push(input.agent.systemPromptMode === "append" ? "--append-system-prompt" : "--system-prompt", promptPath);
 	}
-
-	if (input.task.length > TASK_ARG_LIMIT) {
+	// R3-1: run-static header rides its own --append-system-prompt file. pi
+	// parses --system-prompt and --append-system-prompt independently and the
+	// append flag is repeatable (cli/args.js:71-77; appends join with "\n\n" in
+	// argv order), so pushing it AFTER the agent flag yields the required final
+	// order builtin → agent.systemPrompt → run-static header in BOTH modes
+	// (replace mode: agent file replaces builtin, header appends after it;
+	// append mode: two append files in argv order).
+	if (input.systemPromptAppend?.trim()) {
 		if (!tempDir) {
 			const tmpBase = getPiTempBase();
 			tempDir = createSafeTempDir(tmpBase, `pi-crew-${process.pid}-`);
 		}
-		const taskPath = path.join(tempDir, "task.md");
-		atomicWriteFile(taskPath, input.task, { mode: 0o600 });
-		args.push(`@${taskPath}`);
-	} else {
-		args.push(`Task: ${input.task}`);
+		const headerPath = path.join(tempDir, "worker-header.md");
+		atomicWriteFile(headerPath, input.systemPromptAppend, { mode: 0o600 });
+		args.push("--append-system-prompt", headerPath);
+	}
+
+	// D1 (R3-3, pinned 2026-10-04): deterministic project-trust for worker
+	// spawns — `--no-approve` (cli alias -na). The command-line override applies
+	// FIRST in pi's trust resolution (security.md "How Pi chooses a trust
+	// decision"), before any extension, saved decision in ~/.pi/agent/trust.json,
+	// or defaultProjectTrust — so worker behavior no longer varies with the
+	// ambient trust store of the machine (P-C probe: /home/bom/source/my_pi and
+	// /tmp were pre-trusted there). Decision rationale vs the D1 criteria:
+	// (a) no ambient-trust dependency ✓ (CLI override wins);
+	// (b) write capability intact ✓ (security.md:33 — project trust does NOT
+	//     limit what tool calls can access; only startup resource loading is
+	//     gated, so workers still write files in the task cwd);
+	// (c) minimal scope ✓ (declines rather than grants; one command; not
+	//     persisted to trust.json).
+	// AGENTS.md/CLAUDE.md context files load REGARDLESS of project trust
+	// (security.md:57) — probe-verified 2026-10-04 (/tmp/pi-r3impl probe2: the
+	// project_context section is present with --no-approve), so the R3-18
+	// repo-instruction auto-load is preserved. `-a` was rejected: it grants
+	// maximal project trust (loads .pi/mcp.json, .pi/extensions… from untrusted
+	// task cwds) — the opposite of minimal scope, and redundant with the D5
+	// hermetic posture. Surface TUI spawns strip this flag (child-pi.ts
+	// trySurfaceBranch) to keep the interactive trust prompt available.
+	args.push("--no-approve");
+
+	// G3 (SDD-2 W-B, spill-always): task text NEVER rides argv — argv is
+	// world-readable via /proc/<pid>/cmdline, leaking task content (and any
+	// secrets embedded in prompts) to every local user/process scanner.
+	// EVERY task, regardless of length, is spilled to an owner-only (0600)
+	// task.md inside pi-crew's temp dir and passed as a `@<path>` inclusion
+	// arg. The pre-G3 short-argv branch (task <= 8000 → `Task: ...` positional)
+	// is removed; the file content is the RAW task text (same contract the
+	// long-task path always had — no `Task: ` prefix).
+	if (!tempDir) {
+		const tmpBase = getPiTempBase();
+		tempDir = createSafeTempDir(tmpBase, `pi-crew-${process.pid}-`);
 	}
+	const taskPath = path.join(tempDir, "task.md");
+	atomicWriteFile(taskPath, input.task, { mode: 0o600 });
+	args.push(`@${taskPath}`);
 
 	const env = input.env ?? process.env;
 	const parentDepth = currentCrewDepth(env);

package/src/runtime/model/provider-extensions.ts

@@ -62,6 +62,61 @@ function cachedResult(settingsPath: string): { mtimeMs: number; result: Discover
 	return undefined;
 }
 
+/**
+ * GH #61: normalize a DIRECTORY `pi.extensions` entry to the entry FILE that
+ * Pi's own package auto-load registers. Pi's chain (package-manager
+ * `collectAutoExtensionEntries` → `resolveExtensionEntries`) resolves a
+ * directory to its nested pi-manifest entries, else `index.ts`/`index.js`.
+ * If pi-crew injects the directory as-is, the child worker loads the same
+ * extension twice under two path identities (".../dist" via --extension vs
+ * ".../dist/index.js" via package auto-discovery) and pi's
+ * detectExtensionConflicts kills the worker at startup (exit 1, every tool
+ * reported as conflicting). Always inject the FILE identity.
+ */
+function resolveExtensionDirEntry(dir: string, depth = 0): string | undefined {
+	if (depth > 2) return undefined; // guard pathological nesting loops
+	const pkgJsonPath = path.join(dir, "package.json");
+	if (fs.existsSync(pkgJsonPath)) {
+		try {
+			const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")) as { pi?: { extensions?: string[] } };
+			const piExts = pkg.pi?.extensions;
+			if (Array.isArray(piExts) && piExts.length > 0) {
+				for (const rel of piExts) {
+					const abs = path.resolve(dir, rel);
+					if (!fs.existsSync(abs)) continue;
+					return fs.statSync(abs).isDirectory() ? resolveExtensionDirEntry(abs, depth + 1) : abs;
+				}
+			}
+		} catch {
+			/* malformed package.json — fall through to index probes */
+		}
+	}
+	// Order mirrors Pi's resolveExtensionEntries EXACTLY for the first two
+	// (index.ts → index.js): when Pi's auto-load registers the extension, the
+	// injected identity MUST match its pick. index.mjs and package.json `main`
+	// are fallbacks for packages Pi's auto-load would NOT register at all (it
+	// checks neither) — a single injected instance there cannot conflict, and
+	// `main` preserves the legacy jiti dir-loading behaviour (GH #61 follow-up).
+	for (const name of ["index.ts", "index.js"]) {
+		const abs = path.join(dir, name);
+		if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return abs;
+	}
+	const mjs = path.join(dir, "index.mjs");
+	if (fs.existsSync(mjs) && fs.statSync(mjs).isFile()) return mjs;
+	if (fs.existsSync(pkgJsonPath)) {
+		try {
+			const main = (JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")) as { main?: string }).main;
+			if (main) {
+				const abs = path.resolve(dir, main);
+				if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return abs;
+			}
+		} catch {
+			/* malformed package.json — skip */
+		}
+	}
+	return undefined;
+}
+
 /**
  * Resolve the extension entry point for an installed Pi package.
  * Order: package.json `pi.extensions` (array) → `index.ts` → `index.mjs` → `index.js` → `src/index.ts`.
@@ -80,7 +135,18 @@ function resolvePackageEntry(pkgDir: string): string | undefined {
 			if (Array.isArray(piExts) && piExts.length > 0) {
 				for (const rel of piExts) {
 					const abs = path.resolve(pkgDir, rel);
-					if (fs.existsSync(abs)) return abs;
+					if (!fs.existsSync(abs)) continue;
+					// GH #61: a DIRECTORY entry (e.g. pi-web-access "./dist") must be
+					// normalized to the file identity Pi's auto-load uses — injecting the
+					// raw dir double-loads the extension in child workers (tool conflicts,
+					// exit 1). An unresolvable dir is SKIPPED, matching Pi's own view of
+					// the package (its auto-load would not register it either).
+					if (fs.statSync(abs).isDirectory()) {
+						const entry = resolveExtensionDirEntry(abs);
+						if (entry) return entry;
+						continue;
+					}
+					return abs;
 				}
 			}
 			// Fall back to `main` when it points at a loadable entry (rare for extensions).

package/src/runtime/peer-dep.ts

@@ -69,6 +69,9 @@ let cachedResolve: ResolvedPeerDep | undefined | null = null;
 let cachedModule: PeerDepModule | undefined;
 let primingPromise: Promise<PeerDepModule> | undefined;
 
+/** Warn-once guard for the legacy-fork resolution notice (W6/P2-4, 2026-10-03). */
+let forkResolutionWarned = false;
+
 /**
  * Build the ordered list of "resolution bases" — paths to seed
  * `createRequire(...).resolve()` from. Node walks UP `node_modules` from each
@@ -212,6 +215,24 @@ function tryResolveFrom(base: string): ResolvedPeerDep | undefined {
 	}
 }
 
+/**
+ * W6/P2-4 (pi 1.0.0 adoption wave, 2026-10-03): the @mariozechner fork stopped
+ * publishing (npm latest 0.73.1, 2026-05-07) and sits outside the
+ * @earendil-works semver guarantees, but resolution code + tests still
+ * deliberately support it (Windows global installs, issue #33) and there is
+ * no install-base evidence it is unused — kept, not removed. Warn once per
+ * process so installs relying on it know to migrate to the canonical package.
+ */
+function warnIfForkResolved(name: string): void {
+	if (name !== "@mariozechner/pi-coding-agent" || forkResolutionWarned) return;
+	forkResolutionWarned = true;
+	console.warn(
+		`[pi-crew] notice: resolved the legacy peer dependency "${name}" (fork last published 0.73.1, 2026-05-07). ` +
+			`The canonical package is "@earendil-works/pi-coding-agent"; pi-crew keeps the fork for compatibility, ` +
+			`but support may be removed in a future release.`,
+	);
+}
+
 /** Resolve the peer dep install dir + ESM entry URL. Memoized (sync). */
 export function resolvePeerDep(): ResolvedPeerDep | undefined {
 	if (cachedResolve !== null) return cachedResolve ?? undefined;
@@ -225,6 +246,7 @@ export function resolvePeerDep(): ResolvedPeerDep | undefined {
 	for (const base of bases) {
 		const found = tryResolveFrom(base);
 		if (found) {
+			warnIfForkResolved(found.name);
 			cachedResolve = found;
 			return found;
 		}
@@ -234,6 +256,7 @@ export function resolvePeerDep(): ResolvedPeerDep | undefined {
 	for (const base of peerDepNpmGlobalBases()) {
 		const found = tryResolveFrom(base);
 		if (found) {
+			warnIfForkResolved(found.name);
 			cachedResolve = found;
 			return found;
 		}
@@ -317,4 +340,5 @@ export function __resetPeerDepCacheForTest(): void {
 	cachedResolve = null;
 	cachedModule = undefined;
 	primingPromise = undefined;
+	forkResolutionWarned = false;
 }

package/src/runtime/rpc/README.md

@@ -0,0 +1,100 @@
+# RPC worker transport — W7 (P2-3) EXPERIMENTAL PROTOTYPE
+
+Opt-in, **not wired into live dispatch**. The production stdio child-pi path
+(`child-pi.ts`) is untouched; `run-worker.ts` returns a structured
+**not-implemented** result when the RPC transport is requested (see below).
+
+## What this is
+
+A JSONL frame client that speaks the pi SDK's RPC mode protocol
+(`pi --mode rpc`) on stdin/stdout, implementing the two Round-2 design gates
+the adoption review (§R2.5) proved are mandatory for any RPC transport:
+
+1. **`extension_ui_request` drain policy** (`ui-request-policy.ts`) —
+   fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`,
+   `set_editor_text`) are counted per method and dropped. Round-2 live
+   evidence: 15 of the first 16 records a worker emits belong to this family.
+2. **Dialog auto-answer policy** (`cancel` | `block`) — dialog methods
+   (`select`/`confirm`/`input`/`editor`) park a server-side promise that NEVER
+   resolves if unanswered (ask-over-RPC deadlock, R2.5). `cancel` (default)
+   answers the universal safe answer `{type:"extension_ui_response", id,
+   cancelled:true}` (select/input → undefined, confirm → false). `block`
+   leaves it pending on purpose (debug). **There is no auto-confirm mode —
+   deliberate security decision.** An unattended transport must never say
+   "yes" for the user.
+
+Counters (fake-stream asserted): `uiRequestsDrained`, `drainedByMethod`,
+`dialogsCancelled`, `dialogsBlocked`, `malformedFrames`, `responsesMatched`,
+`responsesUnmatched`.
+
+## Deviation from "use SDK RpcClient" — recorded, evidence-based
+
+The task's original phrasing said "transport dùng SDK RpcClient/runRpcMode".
+The verified recon packet (adaptive-07) proved `RpcClient` unusable for this
+prototype and the leader routed the packet through; deviation accepted per
+packet §C:
+
+1. **No public API to answer `extension_ui_request`** — `send`/`process` are
+   private; non-response records go to event listeners only. Gate 2 would
+   require bracket-accessing private members.
+2. **Version skew** — `RpcClient.start()` spawns `node <cliPath ?? "dist/cli.js">`
+   cwd-relative, NOT the host pi binary the stdio transport resolves
+   (`getPiSpawnCommand` / `PI_TEAMS_PI_BIN`).
+3. **Not injectable** — the W7 test requirement ("fake RPC stream, no real
+   spawn") is impossible against `RpcClient`.
+
+`runRpcMode` is a server-side embed API — inapplicable (pi-crew is a spawner,
+not an embedder).
+
+So: **own strict-LF frame loop over the SDK's exported protocol TYPES**
+(`RpcCommand` / `RpcResponse` / `RpcExtensionUIRequest` /
+`RpcExtensionUIResponse` — all imported from `@earendil-works/pi-coding-agent`).
+The framing rule follows the SDK's own `modes/rpc/jsonl.d.ts` spec: split on
+`\n` ONLY. **Node readline is unsafe here** — it also splits on U+2028/U+2029,
+which are legal inside JSON strings. `serializeJsonLine` /
+`attachJsonlLineReader` are not exported top-level, hence the ~15-line
+hand-rolled splitter.
+
+## Config & env
+
+- `runtime.workerTransport: "stdio" (default) | "rpc"` — declared in
+  `src/schema/config-schema.ts` + `src/config/types.ts`. **Config→seam plumbing
+  is NOT wired yet** (needs a `parseRuntimeConfig` line in
+  `config-validation.ts`, which is outside this lane's file ownership);
+  the live gate is env `PI_CREW_WORKER_TRANSPORT` (`runWorker` has no config
+  access — packet §A).
+- `PI_CREW_WORKER_TRANSPORT=rpc` — selects the transport at the
+  `run-worker.ts` seam. Currently produces the structured not-implemented
+  result (honest prototype) rather than a live spawn.
+- `PI_CREW_RPC_DIALOG_ANSWER=cancel|block` — GATE 2 policy (default `cancel`,
+  invalid fails safe to `cancel`).
+
+## Why the seam returns not-implemented instead of calling `runRpcWorker`
+
+The task's honesty clause allowed exactly this: this lane may not live-spawn
+pi (Round 2 already spent the live probes), so a live-wired seam would ship an
+end-to-end path that NO test can validate — one env var away from silently
+degrading real runs. `runRpcWorker` is complete and fake-stream unit tested
+(prompt → `agent_settled` → orderly stop → `ChildPiRunResult` mapping, abort
+via RPC `abort` command); flipping the seam is a one-line integration change
+after a live-fire probe validates:
+
+- the exact `--mode rpc` argv/env parity with `prepareSpawnContext`
+  (print-mode argv assembly is stdio-specific),
+- session/event stream shape assumptions (`message_end` assistant text →
+  `rawFinalText`),
+- the Round-2 remaining unknowns (`--approve` probe anomaly, rpc3).
+
+## Files
+
+- `frame-client.ts` — strict-LF JSONL frame client, pending-command map with
+  per-command timeout, malformed-frame resilience (count + drop, never throw),
+  orderly stop (stdin end → exit → SIGKILL fallback, kill-once guard).
+- `ui-request-policy.ts` — the two design gates + counters.
+- `rpc-worker.ts` — env resolvers (`resolveWorkerTransport`,
+  `resolveDialogAnswerPolicy`) + `runRpcWorker` prototype runner.
+
+## Production-ready? Honestly: NO.
+
+Prototype-grade. Validated only against fake streams
+(`test/unit/runtime/rpc/`). No live spawn has been attempted from this code.