pi-crew 0.11.7 → 0.11.9

package/src/runtime/child-pi/pi-version.ts

@@ -0,0 +1,187 @@
+/**
+ * pi-version.ts — host `pi` binary version probe + hand-rolled comparison
+ * (U9, pi 1.0.4 adoption wave).
+ *
+ * WHY HAND-ROLLED (no `semver` dependency): pi-crew's package policy is ZERO
+ * new runtime dependencies (AGENTS.md / wave constraint). The comparison
+ * surface pi-crew actually needs is major.minor.patch + simple pre-release
+ * ordering + conservative null on malformed input — pulling in `semver` for
+ * that costs a dependency (plus its transitive tree) that every install pays
+ * for a decision made at most once per process. If a richer need appears
+ * (ranges, build-metadata ordering), REVISIT this decision explicitly — do
+ * not silently grow this file into a partial semver implementation.
+ *
+ * PROBE CONTRACT (probePiVersion):
+ *   - Execs the SAME binary the stdio transport spawns: getPiSpawnCommand
+ *     (PI_TEAMS_PI_BIN aware) with `--version` — probing a different install
+ *     than the one we spawn would gate flags on the wrong version.
+ *   - The exec is INJECTABLE (ExecPiVersionFn seam) so unit tests never spawn
+ *     a real child; the default seam wraps node:child_process execFile with a
+ *     5s timeout (utf8).
+ *   - Single-flight memoized per process: the FIRST call creates the promise;
+ *     every later call (any args) returns the same one. Failures memoize too
+ *     (null = unknown) — a missing/old pi binary does not re-probe per spawn.
+ *   - NEVER rejects: spawn error / nonzero exit / timeout / unparseable
+ *     stdout all resolve null. The result is a hint, never a failure channel.
+ *
+ * COMPARISON CONTRACT (comparePiVersion):
+ *   - Strict `major.minor.patch[-prerelease][+build]` (official semver shape;
+ *     leading zeros rejected). Build metadata is IGNORED per semver §10.
+ *   - Malformed input (either side, incl. null/undefined) → null — callers
+ *     treat null as "unknown" and conservatively emit NO version-gated flag.
+ *   - Pre-release ordering (semver §11, simplified): release > pre-release;
+ *     identifiers compared pairwise (numeric identifiers numerically and
+ *     LOWER than alphanumeric; alphanumeric lexically); a shorter identifier
+ *     list is lower when all preceding identifiers are equal.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getPiSpawnCommand } from "../pi-spawn.ts";
+
+/** Probe timeout (ms). `pi --version` is a fast print; 5s absorbs slow cold starts. */
+export const PI_VERSION_PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * Injectable exec seam for {@link probePiVersion}. Mirrors the
+ * promisify(execFile) shape: resolves {stdout, stderr} on exit 0, REJECTS on
+ * spawn error / nonzero exit / timeout. Tests pass a fake — the default
+ * seam would spawn a real child (forbidden in unit tests).
+ */
+export type ExecPiVersionFn = (
+	file: string,
+	args: string[],
+	options: { timeout: number; encoding: "utf8" },
+) => Promise<{ stdout?: string; stderr?: string }>;
+
+const execFileAsync = promisify(execFile);
+
+const defaultExec: ExecPiVersionFn = (file, args, options) => execFileAsync(file, args, options);
+
+/**
+ * ── Version-floor registry (U9) ─────────────────────────────────────────────
+ * Every argv flag pi-crew gates on the HOST pi binary's version is listed
+ * here so "which pi needs which flag" is greppable in ONE place. The emit
+ * sites live in src/runtime/model/pi-args.ts (parity non-hermetic block).
+ *
+ *   - `1.0.4` → `--no-mcp`: disconnects ambient MCP servers outright ("no
+ *     servers connect, no MCP tools or /mcp" — cli.md:198), strictly stronger
+ *     than the U2-lite `mcp__*` --exclude-tools tool-cut. Emitted ONLY on
+ *     parity (non-hermetic) spawns whose probed piVersion >= this floor.
+ *
+ * Future candidates: none yet. When adding one, append the floor constant
+ * here + the gate at the emit site — pre-floor hosts must NEVER see the flag
+ * (pi's strict parser rejects unknown options with a nonzero exit).
+ */
+export const PI_NO_MCP_FLOOR = "1.0.4";
+
+// Probe-side extraction is LENIENT (tolerates "pi 1.0.4" / banners); the
+// strict validation lives in parseVersion below. First version-shaped token
+// in stdout wins.
+const VERSION_TOKEN_RE = /\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\b/;
+
+// Strict semver shape (official regex, numeric identifiers without leading
+// zeros). Anything else is "unknown" — never a guess.
+const STRICT_SEMVER_RE =
+	/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+interface ParsedVersion {
+	major: number;
+	minor: number;
+	patch: number;
+	/** null = release (no pre-release). Build metadata is dropped at parse. */
+	prerelease: string[] | null;
+}
+
+function parseVersion(value: string | null | undefined): ParsedVersion | null {
+	if (typeof value !== "string") return null;
+	const match = STRICT_SEMVER_RE.exec(value.trim());
+	if (!match) return null;
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	const prerelease = match[4] === undefined ? null : match[4].split(".");
+	return { major, minor, patch, prerelease };
+}
+
+/** Semver §11 identifier compare: numeric < alphanumeric; numeric numeric-ly, alphanumeric lexically. */
+function comparePrereleaseIdentifiers(a: string, b: string): -1 | 0 | 1 {
+	const aNumeric = /^\d+$/.test(a);
+	const bNumeric = /^\d+$/.test(b);
+	if (aNumeric && bNumeric) {
+		const delta = Number(a) - Number(b);
+		return delta < 0 ? -1 : delta > 0 ? 1 : 0;
+	}
+	if (aNumeric) return -1; // numeric identifiers have LOWER precedence
+	if (bNumeric) return 1;
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Compare two pi version strings. Returns -1 | 0 | 1, or null when EITHER
+ * side is malformed/unknown (conservative — callers must treat null as
+ * "emit nothing version-gated"). Build metadata is ignored (semver §10).
+ */
+export function comparePiVersion(a: string | null | undefined, b: string | null | undefined): -1 | 0 | 1 | null {
+	const pa = parseVersion(a);
+	const pb = parseVersion(b);
+	if (!pa || !pb) return null;
+	for (const key of ["major", "minor", "patch"] as const) {
+		if (pa[key] !== pb[key]) return pa[key] < pb[key] ? -1 : 1;
+	}
+	if (pa.prerelease === null && pb.prerelease === null) return 0;
+	if (pa.prerelease === null) return 1; // release > pre-release
+	if (pb.prerelease === null) return -1;
+	const ids = pa.prerelease;
+	const other = pb.prerelease;
+	for (let i = 0; i < Math.min(ids.length, other.length); i++) {
+		const cmp = comparePrereleaseIdentifiers(ids[i] as string, other[i] as string);
+		if (cmp !== 0) return cmp;
+	}
+	if (ids.length !== other.length) return ids.length < other.length ? -1 : 1; // larger set wins
+	return 0;
+}
+
+/**
+ * Floor gate: true ONLY when `version` parses and is >= `floor`. Unknown
+ * (null/undefined) or malformed versions are BELOW every floor — the
+ * conservative "never emit a flag the host may reject" posture.
+ */
+export function piVersionAtLeast(version: string | null | undefined, floor: string): boolean {
+	const cmp = comparePiVersion(version, floor);
+	return cmp !== null && cmp >= 0;
+}
+
+/** Memoized single-flight probe promise (null = unknown, failures included). */
+let memoizedProbe: Promise<string | null> | null = null;
+
+async function runPiVersionProbe(exec: ExecPiVersionFn): Promise<string | null> {
+	const { command, args } = getPiSpawnCommand(["--version"]);
+	const { stdout } = await exec(command, args, { timeout: PI_VERSION_PROBE_TIMEOUT_MS, encoding: "utf8" });
+	const text = typeof stdout === "string" ? stdout : "";
+	const hit = VERSION_TOKEN_RE.exec(text);
+	return hit ? hit[0] : null;
+}
+
+/**
+ * Resolve the host pi binary's version (`pi --version`), single-flight
+ * memoized per process. The `exec` seam is consumed only by the call that
+ * actually creates the memo — later calls reuse the settled promise no
+ * matter what they pass. NEVER rejects; unknown resolves null.
+ */
+export function probePiVersion(exec: ExecPiVersionFn = defaultExec): Promise<string | null> {
+	if (!memoizedProbe) memoizedProbe = runPiVersionProbe(exec).catch(() => null);
+	return memoizedProbe;
+}
+
+/** @internal Test-only: drop the memoized probe so the next call re-probes with a fresh seam. */
+export function __test_resetPiVersionMemo(): void {
+	memoizedProbe = null;
+}
+
+/** @internal Test-only: is a probe memoized? (null = no probe has run yet —
+ *  lets tests prove a code path never TOUCHED the probe, which the call
+ *  counter alone cannot show once single-flight kicks in). */
+export function __test_peekPiVersionMemo(): Promise<string | null> | null {
+	return memoizedProbe;
+}

package/src/runtime/classifier/classifier-service.ts

@@ -0,0 +1,298 @@
+/**
+ * P2-1 (pi 1.0.4 adoption, 2026-10-07): host-process classifier seam.
+ *
+ * Thin never-rejects wrapper around the Pi extension-surface classifier API
+ * (`ctx.modelRegistry.classify()` — docs/models.md:137-138 of the 1.0.4
+ * release: "Extensions call classifiers through ctx.modelRegistry.classify(),
+ * without codemode"). HOST-PROCESS ONLY: the registry handle lives on the
+ * extension ctx in this process — child `pi -p` workers are separate
+ * processes with no ctx and must never import this path.
+ *
+ * Contract (adoption review §R2.3, R2-V probe p3b):
+ *   - classifier unavailable (`getAvailableOfType("classifier")` → [] — the
+ *     catalog lists models but no provider is credentialed) → caller fallback;
+ *   - classify() throws → caller fallback;
+ *   - result.stopReason !== "stop" (e.g. "error" + errorMessage
+ *     "Provider is not configured: opencode" on this host) → caller fallback;
+ *   - answer missing / not boolean-shaped → caller fallback;
+ *   - classify() must NEVER throw up to the orchestrator.
+ *
+ * Every fallback mode logs ONCE per (mode, model) per process (log-once set)
+ * and increments `crew.classifier.calls_total{outcome}` when a metric
+ * registry is threaded — mirrors the dispatch-batch retry-counter pattern
+ * (dispatch-batch.ts:812). Defaults are DORMANT: callers gate on
+ * resolveClassifierEnabled() (runtime.classifierEnabled, default false).
+ */
+import { getCrewEnvBool, getCrewEnvString } from "../../config/env-vars.ts";
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { modelStringFromUnknown } from "../model/model-fallback.ts";
+
+/** Default classifier model (runtime.classifierModel default). */
+export const DEFAULT_CLASSIFIER_MODEL = "opencode/jev-1.13-free";
+
+/** One typed yes/no question (codemode classify question shape, bool type). */
+export interface ClassifierBoolQuestion {
+	type: "bool";
+	instructions: string;
+	/** Label per answer — helps the classifier ground the decision. */
+	criteria?: { true: string; false: string };
+}
+
+/** Request body for modelRegistry.classify(model, request). */
+export interface ClassifyRequest {
+	state: Record<string, unknown>;
+	questions: Record<string, ClassifierBoolQuestion>;
+}
+
+/** Structured result shape returned by modelRegistry.classify (never throws
+ *  per model-registry.d.ts — but we still guard a throwing implementation). */
+export interface ClassifyCallResult {
+	answers?: Record<string, unknown>;
+	stopReason?: string;
+	errorMessage?: string;
+}
+
+/** Duck-typed host registry handle (mirrors ModelRegistryLike in
+ *  model-fallback.ts — the runtime threads the real ctx.modelRegistry as
+ *  `unknown`). NOTE: on the real 1.0.4 ModelRegistry, getAvailableOfType is
+ *  ASYNC (returns a Promise — model-registry.d.ts) while getModelsOfType is
+ *  sync; the duck type accepts both shapes and classifyBool awaits. */
+export interface ClassifierModelRegistryLike {
+	getAvailableOfType?: (type: string) => Promise<unknown[]> | unknown[];
+	classify?: (model: unknown, request: ClassifyRequest) => Promise<ClassifyCallResult> | ClassifyCallResult;
+}
+
+export type ClassifierOutcomeReason =
+	| "classified"
+	| "registry_missing"
+	| "no_classifier_available"
+	| "classify_threw"
+	| "stop_reason_error"
+	| "answer_missing";
+
+export interface ClassifyBoolInput {
+	/** Host-process model registry handle (ctx.modelRegistry, threaded unknown). */
+	modelRegistry: unknown;
+	/** Configured classifier model id ("provider/id"). */
+	classifierModel: string;
+	/** Key under `questions` carrying the bool question. */
+	questionKey: string;
+	question: ClassifierBoolQuestion;
+	/** JSON state the classifier reasons about (keep small + low-cardinality). */
+	state: Record<string, unknown>;
+	/** Caller-provided fallback decision — returned on EVERY failure mode. */
+	fallback: boolean;
+	/** Optional metric registry (counter created on demand, dispatch-batch style). */
+	metricRegistry?: MetricRegistry;
+	/** Extra low-cardinality labels for the calls_total counter. */
+	metricLabels?: Record<string, string>;
+}
+
+export interface ClassifyBoolResult {
+	/** Effective decision: the classifier answer, or the caller fallback. */
+	decision: boolean;
+	/** True ONLY when a real classifier answer informed the decision. */
+	fromClassifier: boolean;
+	/** Which branch produced the outcome (diagnostics + metric label). */
+	reason: ClassifierOutcomeReason;
+	/** Classifier model id actually used (undefined on every fallback path). */
+	usedModel: string | undefined;
+	/** Raw stopReason / errorMessage from the classify call, when one ran. */
+	stopReason: string | undefined;
+	errorMessage: string | undefined;
+}
+
+/**
+ * Log-once state: `${reason}|${classifierModel}`. Module-level on purpose —
+ * per-call-site instances would re-log on every consumer invocation; the
+ * process-wide set matches the "log-once per failure mode" contract.
+ * @internal — test introspection/reset.
+ */
+const loggedFailureModes = new Set<string>();
+
+/** @internal — test hook: reset the log-once set between test cases. */
+export function __test__resetClassifierLogOnce(): void {
+	loggedFailureModes.clear();
+}
+
+/** @internal — test hook: observe the log-once set (assert no re-log). */
+export function __test__classifierLoggedFailureModes(): string[] {
+	return [...loggedFailureModes];
+}
+
+function noteFailureMode(reason: ClassifierOutcomeReason, classifierModel: string, detail: string): void {
+	const key = `${reason}|${classifierModel}`;
+	if (loggedFailureModes.has(key)) return;
+	loggedFailureModes.add(key);
+	logInternalError("classifier-service", new Error(`classifier fallback: ${reason}`), detail, "warn");
+}
+
+function outcomeMetric(
+	metricRegistry: MetricRegistry | undefined,
+	reason: ClassifierOutcomeReason,
+	labels: Record<string, string> | undefined,
+): void {
+	try {
+		metricRegistry?.counter("crew.classifier.calls_total", "Classifier calls by outcome").inc({
+			outcome: reason,
+			...labels,
+		});
+	} catch (error) {
+		// Metric plumbing must never break the never-rejects contract.
+		logInternalError("classifier-service.metric", error, `outcome=${reason}`, "warn");
+	}
+}
+
+/** Normalize a registry handle into the duck-typed classifier surface. */
+function asClassifierRegistry(modelRegistry: unknown): ClassifierModelRegistryLike | undefined {
+	if (!modelRegistry || typeof modelRegistry !== "object" || Array.isArray(modelRegistry)) return undefined;
+	return modelRegistry as ClassifierModelRegistryLike;
+}
+
+/**
+ * Resolve classifier-enabled precedence: env PI_CREW_CLASSIFIER_ENABLED beats
+ * runtime.classifierEnabled beats default FALSE (dormant). Mirrors
+ * resolveHermeticWorkers (pi-args.ts) — env wins in either direction.
+ */
+export function resolveClassifierEnabled(explicit?: boolean): boolean {
+	const env = getCrewEnvBool("PI_CREW_CLASSIFIER_ENABLED");
+	if (env !== undefined) return env;
+	return explicit ?? false;
+}
+
+/**
+ * Resolve classifier-model precedence: env PI_CREW_CLASSIFIER_MODEL beats
+ * runtime.classifierModel beats DEFAULT_CLASSIFIER_MODEL. Blank env values
+ * are ignored (fall through to config/default) — conservative.
+ */
+export function resolveClassifierModel(explicit?: string): string {
+	const env = getCrewEnvString("PI_CREW_CLASSIFIER_MODEL");
+	if (env !== undefined && env.trim().length > 0) return env.trim();
+	return explicit && explicit.trim().length > 0 ? explicit.trim() : DEFAULT_CLASSIFIER_MODEL;
+}
+
+/**
+ * Ask ONE bool question of a host-process classifier. NEVER REJECTS — every
+ * failure mode (no registry, no credentialed classifier, thrown error,
+ * stopReason !== "stop", missing/non-boolean answer) returns the
+ * caller-provided fallback with {@link ClassifyBoolResult.fromClassifier}
+ * false, after a log-once note + metric counter increment.
+ */
+export async function classifyBool(input: ClassifyBoolInput): Promise<ClassifyBoolResult> {
+	const registry = asClassifierRegistry(input.modelRegistry);
+	if (!registry || typeof registry.getAvailableOfType !== "function" || typeof registry.classify !== "function") {
+		noteFailureMode("registry_missing", input.classifierModel, "model registry absent or lacks the classifier surface");
+		outcomeMetric(input.metricRegistry, "registry_missing", input.metricLabels);
+		return {
+			decision: input.fallback,
+			fromClassifier: false,
+			reason: "registry_missing",
+			usedModel: undefined,
+			stopReason: undefined,
+			errorMessage: undefined,
+		};
+	}
+	// Credentialed classifiers only — the catalog (getModelsOfType) can list
+	// models whose provider has no key on this host (R2.3: 6 catalog entries,
+	// 0 available). getAvailableOfType is the availability oracle (ASYNC on
+	// the real registry — model-registry.d.ts).
+	let available: unknown[];
+	try {
+		available = (await registry.getAvailableOfType("classifier")) ?? [];
+	} catch (error) {
+		noteFailureMode("classify_threw", input.classifierModel, `getAvailableOfType threw: ${String(error)}`);
+		outcomeMetric(input.metricRegistry, "classify_threw", input.metricLabels);
+		return {
+			decision: input.fallback,
+			fromClassifier: false,
+			reason: "classify_threw",
+			usedModel: undefined,
+			stopReason: undefined,
+			errorMessage: undefined,
+		};
+	}
+	if (!Array.isArray(available) || available.length === 0) {
+		noteFailureMode(
+			"no_classifier_available",
+			input.classifierModel,
+			"getAvailableOfType('classifier') is empty — no credentialed classifier",
+		);
+		outcomeMetric(input.metricRegistry, "no_classifier_available", input.metricLabels);
+		return {
+			decision: input.fallback,
+			fromClassifier: false,
+			reason: "no_classifier_available",
+			usedModel: undefined,
+			stopReason: undefined,
+			errorMessage: undefined,
+		};
+	}
+	// Prefer the configured model id; fall back to the first available
+	// candidate so a renamed catalog id still gets a usable classifier.
+	const requested = input.classifierModel.trim();
+	const normalized = available.map((entry) => modelStringFromUnknown(entry)).filter((id): id is string => id !== undefined);
+	const matchedIndex = normalized.indexOf(requested);
+	const chosenIndex = matchedIndex >= 0 ? matchedIndex : 0;
+	const chosen = available[chosenIndex];
+	const usedModel = normalized[chosenIndex] ?? requested;
+	try {
+		const result = await registry.classify(chosen, {
+			state: input.state,
+			questions: { [input.questionKey]: input.question },
+		});
+		const stopReason = typeof result?.stopReason === "string" ? result.stopReason : undefined;
+		const errorMessage = typeof result?.errorMessage === "string" ? result.errorMessage : undefined;
+		if (stopReason !== "stop") {
+			noteFailureMode(
+				"stop_reason_error",
+				input.classifierModel,
+				`classify stopReason=${stopReason ?? "undefined"}${errorMessage ? ` errorMessage=${errorMessage}` : ""}`,
+			);
+			outcomeMetric(input.metricRegistry, "stop_reason_error", input.metricLabels);
+			return {
+				decision: input.fallback,
+				fromClassifier: false,
+				reason: "stop_reason_error",
+				usedModel: undefined,
+				stopReason,
+				errorMessage,
+			};
+		}
+		const answer = result?.answers?.[input.questionKey];
+		if (typeof answer !== "boolean") {
+			noteFailureMode("answer_missing", input.classifierModel, `answers[${input.questionKey}] is ${typeof answer}, expected boolean`);
+			outcomeMetric(input.metricRegistry, "answer_missing", input.metricLabels);
+			return {
+				decision: input.fallback,
+				fromClassifier: false,
+				reason: "answer_missing",
+				usedModel: undefined,
+				stopReason,
+				errorMessage,
+			};
+		}
+		outcomeMetric(input.metricRegistry, "classified", input.metricLabels);
+		return {
+			decision: answer,
+			fromClassifier: true,
+			reason: "classified",
+			usedModel,
+			stopReason,
+			errorMessage,
+		};
+	} catch (error) {
+		// The registry contract says classify never rejects, but a misbehaving
+		// implementation must still not take the orchestrator down with it.
+		noteFailureMode("classify_threw", input.classifierModel, `classify threw: ${String(error)}`);
+		outcomeMetric(input.metricRegistry, "classify_threw", input.metricLabels);
+		return {
+			decision: input.fallback,
+			fromClassifier: false,
+			reason: "classify_threw",
+			usedModel: undefined,
+			stopReason: undefined,
+			errorMessage: undefined,
+		};
+	}
+}

package/src/runtime/dispatch-batch.ts

@@ -778,6 +778,10 @@ export async function dispatchBatch(ctx: SchedulerContext, decision: DispatchBat
 			parentContext: input.parentContext,
 			parentModel: input.parentModel,
 			modelRegistry: input.modelRegistry,
+			// P2-1: thread the host metric registry to the task-runner seam so the
+			// retry-triage classifier can count calls/decisions (same
+			// ExecuteTeamRunInput handle dispatch-batch itself uses at :812).
+			metricRegistry: input.metricRegistry,
 			modelOverride: input.modelOverride,
 			teamRoleModel: teamRole?.model,
 			teamRoleThinking: teamRole?.thinking,

package/src/runtime/live-session/live-session-runtime.ts

@@ -322,6 +322,29 @@ function modelFromRegistry(modelRegistry: unknown, modelId: string | undefined):
 	}
 }
 
+/**
+ * R3-12: resolve pi-crew's fallback chain into pi SDK `scopedModels` entries.
+ *
+ * SDK semantics (pi-coding-agent docs/sdk.md; dist/core/agent-session.js):
+ * `scopedModels` bounds the session's CYCLING scope and what extensions see
+ * through `getScopedModels` — it is NOT a hard access gate (`setModel` still
+ * accepts any credentialed model), so binding the fallback chain cannot break
+ * a legitimate user/model override. Candidates that don't resolve in the
+ * registry are skipped; an empty result means the caller passes NO option so
+ * pi keeps its default scope (all available models) — the "explicit
+ * non-empty" guard from the R3 spec.
+ */
+export function resolveScopedSessionModels(modelRegistry: unknown, candidates: readonly string[]): Array<{ model: unknown }> {
+	const scoped: Array<{ model: unknown }> = [];
+	for (const candidate of candidates) {
+		const model = modelFromRegistry(modelRegistry, candidate);
+		if (!model || typeof model !== "object") continue;
+		if (scoped.some((entry) => entry.model === model)) continue;
+		scoped.push({ model });
+	}
+	return scoped;
+}
+
 /**
  * Round 18: when agent declares `model: false`, the inherited `parentModel`
  * (= `ctx.model` from Pi runtime, set via `team-tool.ts:541/655`) is the
@@ -793,6 +816,12 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 		// H1.a: teamRole.thinking takes precedence over agent.thinking.
 		const effectiveThinking = input.teamRoleThinking ?? input.agent.thinking;
 
+		// R3-12: bind the live session's model scope to pi-crew's fallback chain
+		// so model cycling (and the extension-visible scope) cannot drift outside
+		// the candidates the routing gate approved. Only bound when the chain
+		// resolves to at least one registry model (explicit non-empty guard).
+		const scopedSessionModels = resolveScopedSessionModels(input.modelRegistry, modelRouting.candidates);
+
 		// G1: Build custom tools (submit_result + irc)
 		const submitResultTool = createSubmitResultTool((result) => {
 			customToolYieldResult = result;
@@ -819,6 +848,8 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 			...(input.modelRegistry ? { modelRegistry: input.modelRegistry } : {}),
 			...(resolvedModel ? { model: resolvedModel } : {}),
 			...(effectiveThinking ? { thinkingLevel: effectiveThinking } : {}),
+			// R3-12: cycling/visibility scope = the fallback chain (see helper).
+			...(scopedSessionModels.length > 0 ? { scopedModels: scopedSessionModels } : {}),
 			customTools,
 		});
 		session = created.session;

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

@@ -5,8 +5,12 @@ 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";
+import { PI_NO_MCP_FLOOR, piVersionAtLeast } from "../child-pi/pi-version.ts";
 
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+// U4 (pi 1.0.4 adoption): pi's CLI documents 7 thinking levels (docs/cli.md:70);
+// `max` completes the surface — frontmatter `thinking: max` previously fell
+// back to Pi's default via isValidThinkingLevel.
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 // FIX (2026-07-02): use packageRoot() instead of import.meta.url-relative path.
 // The previous path.resolve(path.dirname(fileURLToPath(import.meta.url)),
 // "..", "prompt", "prompt-runtime.ts") was correct in source but BROKEN
@@ -50,6 +54,15 @@ export interface BuildPiWorkerArgsInput {
 	 *  (`--session-dir`, SDK ≥ 0.30.0). Run-scoped per-worker dir, e.g.
 	 *  `<artifactsRoot>/sessions/<taskId>/` — lives and dies with run artifacts. */
 	sessionDir?: string;
+	/** R3-15 (Pi 1.0.0 deep-learn r3): worker task id for the human-facing
+	 *  session display name — emits `--name crew-<taskId>` (cli.md:100, `-n/--name`
+	 *  "Sets the session display name"). Cosmetic only: W2's deterministic
+	 *  --session-id stays the machine-readable correlation key. Emitted inside
+	 *  the sessionEnabled block (a name labels a persisted session; under
+	 *  --no-session nothing persists). NOT stripped for surface TUI panes — a
+	 *  display name is not headless-only, it labels the pane's session too
+	 *  (child-pi.ts stripHeadlessOnlyFlags stays untouched). */
+	taskId?: string;
 	maxDepth?: number;
 	skillPaths?: string[];
 	env?: NodeJS.ProcessEnv;
@@ -75,6 +88,16 @@ export interface BuildPiWorkerArgsInput {
 	 *  declarations, and `--skill` flags are unaffected (cli.md:186-191:
 	 *  explicit -e and --skill survive --no-extensions/--no-skills). */
 	hermeticWorkers?: boolean;
+	/** U9 (pi 1.0.4 version floor): the HOST pi binary's version as probed by
+	 *  `pi --version` (probePiVersion — single-flight memoized per process,
+	 *  injectable exec seam, never rejects), or null when unknown (probe
+	 *  failed/timed out/unparseable). PURE INPUT — the builder NEVER spawns:
+	 *  the async spawn path (runChildPi) awaits the memoized probe upstream and
+	 *  threads the resolved string|null down through here. Drives the
+	 *  version-gated flags registered in child-pi/pi-version.ts (`--no-mcp` at
+	 *  the 1.0.4 floor, parity spawns only); unknown/below-floor conservatively
+	 *  emits NOTHING — a pre-floor host's strict parser rejects unknown flags. */
+	piVersion?: string | null;
 }
 
 export interface BuildPiWorkerArgsResult {
@@ -315,6 +338,10 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 	if (input.sessionEnabled !== false) {
 		if (input.sessionId) args.push("--session-id", input.sessionId);
 		if (input.sessionDir) args.push("--session-dir", input.sessionDir);
+		// R3-15: human-facing display name — `crew-<taskId>` makes crew workers
+		// distinguishable in pi's session picker (flag predates nothing: -n/--name
+		// is a long-standing CLI flag, cli.md:100 — no capability gate needed).
+		if (input.taskId) args.push("--name", `crew-${input.taskId}`);
 	}
 
 	const resolvedModel = input.model ?? input.agent.model;
@@ -367,8 +394,40 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 		// B2 (fix round 1): `disallowedTools:` frontmatter is a
 		// declaration-driven denylist (opt-in like `tools:`) — NOT the
 		// role-based policy D5 removed.
-		const disallowed = (input.agent.disallowedTools ?? []).map((t) => t.trim()).filter(Boolean);
-		if (disallowed.length > 0) args.push("--exclude-tools", [...new Set(disallowed)].join(","));
+		// U2-lite (pi 1.0.4 `--tools` semantics drift): on 1.0.4, `--tools` no
+		// longer cuts MCP — ambient MCP servers stay connected on parity
+		// (NON-hermetic) spawns. Fold `mcp__*` into the exclude list to restore
+		// the pre-1.0.4 MCP cut. Kept OUT of hermetic spawns: --no-extensions
+		// already disables builtin:mcp (hermetic spawns are MCP-clean — the
+		// conflict verdict in docs/reviews/pi-1.0.4-upgrade-notes-2026-10-06.md),
+		// and the default loadout pins !--exclude-tools
+		// (test/unit/runtime/model/pi-args-loadout.test.ts). Cross-version-safe:
+		// on pre-1.0.4 hosts the `mcp__*` pattern matches no literal tool name
+		// → benign no-op. ONE flag value only — pi's strict parser rejects a
+		// duplicate --exclude-tools flag, so declared disallowedTools merge
+		// comma-sep ahead of the pattern. Stays inside the else of disableTools:
+		// `--no-tools` already locks the whole tool surface, an extra cut would
+		// be dead weight. Surface TUI panes strip argv flags after build
+		// (child-pi.ts stripHeadlessOnlyFlags), so this cut never reaches them.
+		const disallowed = new Set((input.agent.disallowedTools ?? []).map((t) => t.trim()).filter(Boolean));
+		const paritySpawn = !resolveHermeticWorkers(input.hermeticWorkers);
+		if (paritySpawn) disallowed.add("mcp__" + "*");
+		if (disallowed.size > 0) args.push("--exclude-tools", [...disallowed].join(","));
+		// U9 (version floor, registry PI_NO_MCP_FLOOR in child-pi/pi-version.ts;
+		// flag doc cli.md:198): parity spawn on a host pi >= 1.0.4 ALSO passes
+		// `--no-mcp` — "no servers connect, and there are no MCP tools or /mcp",
+		// strictly stronger than the mcp__* tool-cut above (servers never even
+		// handshake). Below the floor / unknown (null) / malformed piVersion →
+		// NO flag: pi's strict option parser rejects unknown flags with a
+		// nonzero exit, so guessing wrong would break every parity spawn. The
+		// mcp__* fold STAYS alongside — it is the cross-version-safe baseline
+		// (pre-1.0.4 hosts have no --no-mcp to lean on). Hermetic spawns never
+		// reach here (--no-extensions already makes them MCP-clean). Kept inside
+		// the else of disableTools like the fold (--no-tools already locks the
+		// whole surface). Surface TUI panes KEEP the flag — stripHeadlessOnlyFlags
+		// only strips --no-approve/--no-extensions, same treatment as
+		// --exclude-tools: parity semantics must not depend on spawn mode.
+		if (paritySpawn && piVersionAtLeast(input.piVersion, PI_NO_MCP_FLOOR)) args.push("--no-mcp");
 	}
 	// prompt-runtime extension luôn nạp (hạ tầng phối hợp — không phải cắt xén).
 	args.push("--extension", PROMPT_RUNTIME_EXTENSION_PATH);