pi-crew 0.11.23 → 0.11.25

package/src/config/env-vars.ts

@@ -78,7 +78,10 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_DEPTH",
 		mirror: "PI_TEAMS_DEPTH",
 		mirrorPrecedence: "crew",
-		default: "0",
+		// wave-2b: default was the STRING "0" on an int parser — getCrewEnvParsed
+		// returned the raw string from the fallback, so typed readers (getCrewEnvInt)
+		// saw undefined instead of 0. Numeric default routes through the parser.
+		default: 0,
 		parser: "int",
 		doc: "current crew depth (pi-args.ts:72 reads CREW ?? TEAMS ?? '0')",
 	},
@@ -86,7 +89,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_TEAMS_DEPTH",
 		mirror: "PI_CREW_DEPTH",
 		mirrorPrecedence: "crew",
-		default: "0",
+		default: 0, // wave-2b: numeric default on int parser (was string "0")
 		parser: "int",
 		doc: "crew depth mirror (fallback of PI_CREW_DEPTH)",
 	},
@@ -274,7 +277,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	},
 	PI_CREW_DEBUG: {
 		name: "PI_CREW_DEBUG",
-		doc: "truthiness enables background debug logging (background-runner.ts:63)",
+		doc: "truthiness enables background debug logging (background-runner.ts:63); RAW truthiness — '0'/'false' still ENABLE, unset to disable (R45-F4)",
 	},
 	PI_CREW_DEBUG_BUDGET: {
 		name: "PI_CREW_DEBUG_BUDGET",
@@ -368,7 +371,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	},
 	PI_CREW_TRUST_PROJECT_DWF: {
 		name: "PI_CREW_TRUST_PROJECT_DWF",
-		doc: "'1' allows project-sourced .dwf.ts workflows (dynamic-workflow-runner.ts:154)",
+		doc: "'1' allows project-sourced .dwf.ts workflows (dynamic-workflow-runner.ts:189)",
 	},
 	PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS: {
 		name: "PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS",
@@ -377,7 +380,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	},
 	PI_TEAMS_DEBUG: {
 		name: "PI_TEAMS_DEBUG",
-		doc: "truthiness gates debug-severity internal-error logging (internal-error.ts:4)",
+		doc: "truthiness gates debug-severity internal-error logging (internal-error.ts:10); RAW truthiness — '0'/'false' still ENABLE, unset to disable (R45-F4)",
 	},
 	PI_TEAMS_MOCK_CHILD_PI: {
 		name: "PI_TEAMS_MOCK_CHILD_PI",
@@ -508,7 +511,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	PI_CREW_VERIFY_GATE_TIMEOUT_MS: {
 		name: "PI_CREW_VERIFY_GATE_TIMEOUT_MS",
 		parser: "int",
-		default: "120000",
+		default: 120_000, // wave-2b: numeric default (was string "120000" — fallback bypassed the parser)
 		doc: "U13 per-check timeout in ms for the deterministic verify_gate pre-gate commands. Invalid/≤0 → 120000, mirroring runPhaseGates (runtime/verification/verify-gate.ts resolveVerifyGateTimeoutMs)",
 	},
 	PI_CREW_VERIFY_DETERMINISM: {
@@ -523,7 +526,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	PI_CREW_RPC_TURN_TIMEOUT_MS: {
 		name: "PI_CREW_RPC_TURN_TIMEOUT_MS",
 		parser: "int",
-		default: "600000",
+		default: 600_000, // wave-2b: numeric default (was string "600000" — fallback bypassed the parser)
 		doc: "W7/DR1 belt-and-suspenders turn timeout for the EXPERIMENTAL RPC worker transport: max ms a prompt-accepted turn may run without agent_settled before the transport fails with the early-failure shape (DR5 guard still blocks the stdio fallback once a session event was seen). Env-only while RPC stays experimental. Invalid/≤0 → 600000 (rpc-worker.ts resolveRpcTurnTimeoutMs)",
 	},
 	PI_CREW_AUTO_EXIT: {
@@ -533,13 +536,13 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	PI_CREW_AUTO_PRUNE_KEEP: {
 		name: "PI_CREW_AUTO_PRUNE_KEEP",
 		parser: "int",
-		default: "10",
+		default: 10, // wave-2b: numeric default (was string "10" — fallback bypassed the parser)
 		doc: "DP-01: number of most-recent finished runs the session-start auto-prune retains (was hard-coded 10). Invalid/negative → 10 with a warning (run-maintenance.ts:resolveAutoPruneKeep)",
 	},
 	PI_CREW_AUTO_PRUNE_AGE_FLOOR_HOURS: {
 		name: "PI_CREW_AUTO_PRUNE_AGE_FLOOR_HOURS",
 		parser: "int",
-		default: "24",
+		default: 24, // wave-2b: numeric default (was string "24" — fallback bypassed the parser)
 		doc: "DP-01: auto-prune never deletes a finished run younger than this many hours, even beyond top-keep — evidence/incident runs survive a session restart (0 disables; run-maintenance.ts:resolveAutoPruneAgeFloorMs)",
 	},
 	PI_CREW_SURFACE: {
@@ -763,18 +766,25 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
  * Raw crew-env lookup. Returns the raw string (undefined when unset) with
  * mirror-alias fallback applied per the entry's `mirrorPrecedence`. This is
  * the behavior-preserving replacement for `process.env.PI_CREW_X` reads.
+ *
+ * R26-F1 (deep-review round 26): `env` is an OPTIONAL source override. Reads
+ * that receive an env object as a parameter (`isRootSession(env)`,
+ * `currentCrewDepth(env)`, …) must still route through the registry — passing
+ * the object here keeps the registry invariant intact for those sites instead
+ * of leaving them as gate-blind `env.PI_CREW_X` dot reads. Defaults to
+ * `process.env`, so existing call sites are unchanged.
  */
-export function getCrewEnv(name: string): string | undefined {
+export function getCrewEnv(name: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
 	const spec = CREW_ENV_VARS[name];
 	if (!spec?.mirror || spec.mirrorPrecedence === "or") {
-		return process.env[name];
+		return env[name];
 	}
 	const crewName = name.startsWith("PI_TEAMS_") ? spec.mirror : name;
 	const teamsName = name.startsWith("PI_TEAMS_") ? name : spec.mirror;
 	if (spec.mirrorPrecedence === "teams") {
-		return process.env[teamsName] ?? process.env[crewName];
+		return env[teamsName] ?? env[crewName];
 	}
-	return process.env[crewName] ?? process.env[teamsName];
+	return env[crewName] ?? env[teamsName];
 }
 
 /**

package/src/config/role-tools.ts

@@ -17,18 +17,21 @@ export interface RoleToolConfig {
 }
 
 export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
-	// Explorer - Read-only exploration; bash is included for git log/show
-	// (decisions stream needs commit-history mining) but edit/write stay
-	// excluded. State-mutation safety is enforced separately by
-	// READ_ONLY_ROLES in role-permission.ts.
+	// Explorer - Read-only exploration. Wave-3 (Chain A cheapest cut, deep review
+	// 2026-10-16/17): bash REMOVED from the enforced allowlist — the advertised
+	// read-only contract is now the enforceable one (READ_ONLY_ROLES state-mutation
+	// gating cannot stop host-level persistence via arbitrary commands, e.g.
+	// `git config --global` or writes to ~/.pi/agent). Frontmatter mirrors this.
 	explorer: {
-		tools: ["read", "grep", "find", "ls", "glob", "bash", "ask"],
-		excludeTools: ["edit", "write", "web"],
+		tools: ["read", "grep", "find", "ls", "glob", "ask"],
+		excludeTools: ["edit", "write", "bash", "web"],
 	},
 
-	// Analyst - Read and analyze, limited execution
+	// Analyst - Read and analyze, limited execution. (ask_question removed
+	// 2026-10-18: the host tool is `ask` — excluding a nonexistent name was a
+	// dead entry; the live `ask` tool stays allowed for analyst.)
 	analyst: {
-		excludeTools: ["edit", "write", "ask_question"],
+		excludeTools: ["edit", "write"],
 	},
 
 	// Planner - Read-only planning; emits plans as TEXT (runner persists result).
@@ -40,7 +43,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// default/implementation workflows.
 	planner: {
 		tools: ["read", "grep", "find", "ls", "glob", "ask"],
-		excludeTools: ["edit", "write", "bash", "web", "ask_question"],
+		excludeTools: ["edit", "write", "bash", "web"],
 	},
 
 	// Critic - Read-only plan/design critique (F2: was missing from the map,
@@ -66,7 +69,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// Writer - Documentation focused
 	writer: {
 		tools: ["read", "edit", "write", "ls", "ask"],
-		excludeTools: ["bash", "web", "ask_question"],
+		excludeTools: ["bash", "web"],
 	},
 
 	// Security Reviewer - Strict restrictions
@@ -75,7 +78,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// resolved at runtime (returned {}), silently dropping enforcement.
 	"security-reviewer": {
 		tools: ["read", "grep", "find", "ask"],
-		excludeTools: ["edit", "write", "bash", "web", "ask_question"],
+		excludeTools: ["edit", "write", "bash", "web"],
 	},
 
 	// Verifier - Runs tests (needs bash) but must NOT edit source (F4: moved

package/src/config/types.ts

@@ -386,7 +386,10 @@ export interface CrewReliabilityConfig {
 	retryPolicy?: CrewRetryPolicyConfig;
 	autoRecover?: boolean;
 	deadletterThreshold?: number;
-	/** Interval (ms) for periodic stale-run auto-repair. Default 60_000 (60s). Set to 0 to disable. */
+	/** Interval (ms) for periodic stale-run auto-repair. Default 300_000 (5min) —
+	 *  the canonical value lives in the `?? 300_000` fallback at
+	 *  `src/extension/registration/observability.ts:256` (RT-F2 raised it from 60s;
+	 *  R45-F2). Set to 0 to disable. */
 	autoRepairIntervalMs?: number;
 	/** Remove /tmp/pi-crew-* directories after their orphaned runs are reconciled. Default: true. */
 	cleanupOrphanedTempDirs?: boolean;

package/src/extension/crew-cleanup.ts

@@ -79,6 +79,12 @@ export function registerCleanupHandler(pi: ExtensionAPI, opts?: { disposeTermina
 			// suppression; on REAL shutdowns (quit/reload) the flag is unset
 			// and this cleanup still drains the registry, as does the
 			// process-exit hook (tryRegisterSessionCleanup) when pi dies.
+			// R49-F6: this gate is a SWITCH FLAG (`isSessionSwitchInFlight()`), not the
+			// reason-aware gate used by lifecycle-handlers.ts:165-166. On a `reload` shutdown
+			// the flag can still read true (it is cleared on the next session_start), so
+			// this handler may skip a cleanup the reason-gate would have run — the
+			// process-exit hook (tryRegisterSessionCleanup) is the backstop. Divergence
+			// is deliberate (never kill workers on a navigational switch) but not obvious.
 			if (isSessionSwitchInFlight()) return;
 			// Kill all child-pi processes
 			await cleanupChildProcesses();

package/src/extension/management.ts

@@ -15,6 +15,7 @@ import { projectCrewRoot, userPiRoot } from "../utils/paths.ts";
 import { allWorkflows, discoverWorkflows, invalidateWorkflowDiscoveryCache } from "../workflows/discover-workflows.ts";
 import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
 import { serializeWorkflow } from "../workflows/workflow-serializer.ts";
+import { assertRootOnlyAction } from "./team-tool/destructive-gate.ts";
 import { enforceDestructiveIntent } from "./team-tool/intent-policy.ts";
 import type { TeamToolDetails } from "./team-tool-types.ts";
 import { type PiTeamsToolResult, toolResult } from "./tool-result.ts";
@@ -415,6 +416,12 @@ export function handleUpdate(params: TeamToolParamsValue, ctx: ManagementContext
 	if (parsed.error) return result(parsed.error, "error", true);
 	const cfg = parsed.value!;
 	const current = resolved.resource!;
+	// Wave-3 root-gate (R5-M-B2): the update path resolves its write scope from
+	// the MATCHED resource (params.scope may be undefined and match either
+	// tier), so the facade gate cannot decide — gate HERE on the resolved
+	// source. Non-root sessions may only rewrite project-tier resources.
+	const updateGate = assertRootOnlyAction("update", undefined, current.source === "project" ? "project" : "user");
+	if (updateGate) return result(updateGate.message, "error", true);
 	const nextName = hasOwn(cfg, "name") ? sanitizeName(String(cfg.name ?? "")) : current.name;
 	if (!nextName) return result("config.name is invalid after sanitization.", "error", true);
 	const source = current.source === "project" ? "project" : "user";

package/src/extension/project-init.ts

@@ -21,6 +21,13 @@ export interface ProjectInitResult {
 	configScope: "global" | "project" | "none";
 	configCreated: boolean;
 	configSkipped: boolean;
+	/**
+	 * F13-A: set when an EXPLICIT `overwrite: true` replaced an existing config
+	 * file. The previous content is preserved at this path — an overwrite of the
+	 * global (`~/.pi/agent/pi-crew.json`) or project config is destructive and may
+	 * discard user-customized settings, so it must never be silent.
+	 */
+	configBackupPath?: string;
 }
 
 function ensureDir(dir: string, createdDirs: string[]): void {
@@ -112,10 +119,20 @@ export function initializeProject(cwd: string, options: ProjectInitOptions = {})
 
 	let configCreated = false;
 	let configSkipped = false;
+	let configBackupPath: string | undefined;
 	if (configPath) {
 		if (configScope === "project") ensureDir(path.dirname(configPath), createdDirs);
 		else fs.mkdirSync(path.dirname(configPath), { recursive: true });
-		if (!fs.existsSync(configPath) || options.overwrite === true) {
+		const configExists = fs.existsSync(configPath);
+		if (!configExists) {
+			fs.writeFileSync(configPath, `${JSON.stringify(DEFAULT_PI_CREW_CONFIG, null, 2)}\n`, "utf-8");
+			configCreated = true;
+		} else if (options.overwrite === true) {
+			// F13-A: overwriting an existing config is destructive — it may hold the
+			// user's own settings (global scope writes ~/.pi/agent/pi-crew.json).
+			// Keep the previous content and report it instead of replacing silently.
+			configBackupPath = `${configPath}.bak-${Date.now()}`;
+			fs.copyFileSync(configPath, configBackupPath);
 			fs.writeFileSync(configPath, `${JSON.stringify(DEFAULT_PI_CREW_CONFIG, null, 2)}\n`, "utf-8");
 			configCreated = true;
 		} else {
@@ -166,5 +183,6 @@ export function initializeProject(cwd: string, options: ProjectInitOptions = {})
 		configScope,
 		configCreated,
 		configSkipped,
+		...(configBackupPath ? { configBackupPath } : {}),
 	};
 }

package/src/extension/register.ts

@@ -24,6 +24,7 @@ import { startRuntimeWarmup } from "../runtime/model/runtime-warmup.ts";
 import { primePeerDep } from "../runtime/peer-dep.ts";
 import { deployBundledThemes } from "../ui/deploy-bundled-themes.ts";
 import { installChildProcessAbortShield } from "../utils/child-process-shield.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 import { resetTimings, time } from "../utils/timings.ts";
 import { registerAutonomousPolicy } from "./autonomous-policy.ts";
 import { registerContextStatusInjection } from "./context-status-injection.ts";
@@ -75,6 +76,21 @@ export async function registerPiTeams(pi: ExtensionAPI): Promise<void> {
 		);
 	}
 
+	// Wave-3 (attack-chain A / R2-M-B1 hardening): hermeticWorkers is DEFAULT
+	// ON; runtime.hermeticWorkers=false is a deliberate trust downgrade (worker
+	// pi sessions load ambient extensions/skills — the parity state where a
+	// repo-planted worker can reach the `team` tool's user-tier persistence).
+	// Emit ONE prominent warning at extension init so the operator sees it.
+	try {
+		if (loadConfig(process.cwd()).config.runtime?.hermeticWorkers === false) {
+			console.warn(
+				"[pi-crew] ⚠ SECURITY: runtime.hermeticWorkers=false — workers will load ambient extensions/skills (non-default trust posture). Worker sessions can then persist user-tier config/agents (every future session). Re-enable hermetic spawns unless parity mode is specifically required.",
+			);
+		}
+	} catch {
+		/* config read failures surface through their own channel */
+	}
+
 	startRuntimeWarmup();
 	primePeerDep().catch(() => undefined);
 	deployBundledThemes();
@@ -82,56 +98,93 @@ export async function registerPiTeams(pi: ExtensionAPI): Promise<void> {
 	const ctx = buildRegistrationContext(pi);
 	ctx.importCrashRecovery = importCrashRecovery;
 	ctx.purgeStaleActiveRunIndexSyncIfLoaded = purgeStaleActiveRunIndexSyncIfLoaded;
-	installRuntimeCleanup(pi, ctx);
-	installForegroundRunController(pi, ctx);
-	installSubagentManager(pi, ctx);
-	installLazyConfigurers(pi, ctx);
-	installCrossExtensionWiring(pi, ctx);
+
+	// R49-F5 (wave-6 M4-R2) — registrar guard. The registrars below run in a
+	// flat sequence; before this guard ANY throw aborted the remaining
+	// registrars and left a PARTIAL extension with no diagnostic (Pi's loader
+	// discards the rejection). Guard each call: on throw, record the subsystem
+	// name, log it through the internal-error channel, and CONTINUE — extension
+	// load must never break the session, but a failed subsystem must be
+	// visible. ONE consolidated warning is surfaced before the skill check.
+	const registrarFailures: string[] = [];
+	const withRegistrar = <T>(name: string, fn: () => T): T | undefined => {
+		try {
+			return fn();
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			registrarFailures.push(`${name} (${detail})`);
+			logInternalError(`register.${name}`, err, "extension registration subsystem");
+			return undefined;
+		}
+	};
+
+	withRegistrar("runtimeCleanup", () => installRuntimeCleanup(pi, ctx));
+	withRegistrar("foregroundRunController", () => installForegroundRunController(pi, ctx));
+	withRegistrar("subagentManager", () => installSubagentManager(pi, ctx));
+	withRegistrar("lazyConfigurers", () => installLazyConfigurers(pi, ctx));
+	withRegistrar("crossExtensionWiring", () => installCrossExtensionWiring(pi, ctx));
 
 	time("register.policy");
-	registerAutonomousPolicy(pi);
-	registerKnowledgeInjection(pi);
+	withRegistrar("autonomousPolicy", () => registerAutonomousPolicy(pi));
+	withRegistrar("knowledgeInjection", () => registerKnowledgeInjection(pi));
 
-	registerPiTools(pi, ctx);
-	registerPiCommands(pi, ctx);
-	installPiHooks(pi, ctx);
-	installSessionLifecycleHandlers(pi, ctx);
+	withRegistrar("piTools", () => registerPiTools(pi, ctx));
+	withRegistrar("piCommands", () => registerPiCommands(pi, ctx));
+	withRegistrar("piHooks", () => installPiHooks(pi, ctx));
+	withRegistrar("sessionLifecycleHandlers", () => installSessionLifecycleHandlers(pi, ctx));
 	// Phase 0 inter-pi broker: install the lifecycle controller immediately
 	// after the session handlers. The controller's gate (broker.enabled AND
 	// root-session only) decides whether anything is actually done; for
 	// subagents or when the flag is off, it returns a no-op controller.
-	ctx.brokerController = installCrewBrokerLifecycleController(pi, ctx);
+	ctx.brokerController = withRegistrar("crewBrokerLifecycle", () => installCrewBrokerLifecycleController(pi, ctx));
 
 	// M3-1 (UI-AUDIT P0-2/P1-1): wire the tab-title + Ghostty progress
 	// controller to runEventBus. Before this the controller was never
 	// constructed (dead since v0.8.3). Registers the dispose hook that the
 	// SIGTERM/SIGHUP handler calls (crew-cleanup.ts).
-	installTerminalStatus(pi, ctx);
-	registerCompactionGuard(pi, {
-		foregroundControllers: ctx.foregroundControllers,
-		foregroundTeamRunControllers: ctx.foregroundTeamRunControllers,
-	});
+	withRegistrar("terminalStatus", () => installTerminalStatus(pi, ctx));
+	withRegistrar("compactionGuard", () =>
+		registerCompactionGuard(pi, {
+			foregroundControllers: ctx.foregroundControllers,
+			foregroundTeamRunControllers: ctx.foregroundTeamRunControllers,
+		}),
+	);
 
 	if (process.env.CREW_RESILIENT_EDIT === "1") {
+		// R49-F5: do NOT swallow the outcome. `wrapEditWithResilientReplace`
+		// returns false when the hook was NOT registered (pi-diff present or the
+		// host lacks the tool_result seam) and the dynamic import can reject;
+		// both were previously discarded, so an operator who set
+		// CREW_RESILIENT_EDIT=1 got a silent no-op.
 		// LAZY: resilient-edit only loads when the opt-in env var is set.
 		import("../runtime/resilient-edit.ts")
-			.then(({ wrapEditWithResilientReplace }) => wrapEditWithResilientReplace(pi))
-			.catch(() => {
-				/* non-critical */
+			.then(({ wrapEditWithResilientReplace }) => {
+				if (!wrapEditWithResilientReplace(pi)) {
+					console.warn(
+						"[pi-crew] CREW_RESILIENT_EDIT=1 but the resilient-edit wrapper did NOT register " +
+							"(pi-diff detected or the host lacks the tool_result seam) — the opt-in is a no-op this session.",
+					);
+				}
+			})
+			.catch((err: unknown) => {
+				logInternalError("register.resilientEdit", err, "CREW_RESILIENT_EDIT=1");
+				console.warn(`[pi-crew] resilient-edit failed to load: ${err instanceof Error ? err.message : String(err)}`);
 			});
 	}
 
-	registerCrewMessageRenderers(pi);
-	registerCrewInputRouter(pi);
-	registerCrewShortcuts(pi);
-	registerContextStatusInjection(pi, {
-		enabled: loadConfig(process.cwd()).config.reliability?.ambientStatusInjection !== false,
-	});
+	withRegistrar("crewMessageRenderers", () => registerCrewMessageRenderers(pi));
+	withRegistrar("crewInputRouter", () => registerCrewInputRouter(pi));
+	withRegistrar("crewShortcuts", () => registerCrewShortcuts(pi));
+	withRegistrar("contextStatusInjection", () =>
+		registerContextStatusInjection(pi, {
+			enabled: loadConfig(process.cwd()).config.reliability?.ambientStatusInjection !== false,
+		}),
+	);
 
-	try {
-		registerCrewVibes(pi);
-	} catch (err) {
-		console.warn("[pi-crew] crew-vibes initialization failed:", err instanceof Error ? err.message : err);
+	withRegistrar("crewVibes", () => registerCrewVibes(pi));
+
+	if (registrarFailures.length > 0) {
+		console.warn(`[pi-crew] ${registrarFailures.length} subsystem(s) failed to register: ${registrarFailures.join(", ")}`);
 	}
 
 	const skillCheck = await runPostInitSkillCheck(process.cwd());

package/src/extension/registration/artifact-cleanup.ts

@@ -5,33 +5,69 @@ import { CLEANUP_MARKER_FILE, cleanupOldArtifacts, pruneExpiredArtifacts } from
 import type { ArtifactDescriptor, TeamRunManifest } from "../../state/types.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
+import { resolveContainedRelativePath } from "../../utils/safe-paths.ts";
 
 /**
- * ST-10: Load artifact descriptors from all manifests in a runs directory.
- * Returns a flat list of every ArtifactDescriptor across all runs.
- * Best-effort: unreadable or corrupt manifests are silently skipped.
+ * ST-10 + R44-N1: artifact descriptors for ONE run, paired with the run's
+ * HOST-DERIVED artifacts root (containment anchor). The anchor is computed
+ * from the runs directory being scanned (`<crewRoot>/state/runs/<runId>` →
+ * `<crewRoot>/artifacts/<runId>` — the same convention `createRunPaths`
+ * derives), NEVER from the worker-writable manifest itself: a malicious
+ * manifest must not be able to nominate its own prune boundary.
  */
-function collectArtifactDescriptors(runsDir: string): ArtifactDescriptor[] {
-	const descriptors: ArtifactDescriptor[] = [];
+export interface RunArtifactGroup {
+	runId: string;
+	/** Host-derived per-run artifacts root (prune containment anchor). */
+	artifactsRoot: string;
+	descriptors: ArtifactDescriptor[];
+}
+
+/**
+ * ST-10: Load artifact descriptors from all manifests in a runs directory,
+ * grouped per run with the host-derived artifacts root for each run.
+ * Best-effort: unreadable or corrupt manifests are silently skipped. Runs
+ * whose DIRECTORY NAME cannot form a safe artifacts root (path-escape) are
+ * skipped with a warn (fail-closed — their descriptors are never pruned).
+ */
+export function collectArtifactDescriptors(runsDir: string): RunArtifactGroup[] {
+	const groups: RunArtifactGroup[] = [];
 	let dirs: fs.Dirent[];
 	try {
 		dirs = fs.readdirSync(runsDir, { withFileTypes: true });
 	} catch {
-		return descriptors;
+		return groups;
 	}
+	// runsDir = <crewRoot>/<state.runsSubdir> → the crew root sits two levels up
+	// (mirrors state-store.ts validateRunManifestPaths' baseRoot derivation).
+	const crewRoot = path.resolve(runsDir, "..", "..");
+	const artifactsParent = path.join(crewRoot, DEFAULT_PATHS.state.artifactsSubdir);
 	for (const dir of dirs) {
 		if (!dir.isDirectory()) continue;
+		let artifactsRoot: string;
+		try {
+			artifactsRoot = resolveContainedRelativePath(artifactsParent, dir.name, "runId");
+		} catch (error) {
+			// R44-N1 fail-closed: an unsafe run-dir name must not reach the prune
+			// path at all — its descriptors are dropped, not anchored elsewhere.
+			logInternalError(
+				"artifact-cleanup.run-anchor",
+				error instanceof Error ? error : new Error(String(error)),
+				`runsDir=${runsDir} runId=${dir.name}`,
+				"warn",
+			);
+			continue;
+		}
 		const manifestPath = path.join(runsDir, dir.name, DEFAULT_PATHS.state.manifestFile);
 		try {
 			const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as TeamRunManifest;
 			if (Array.isArray(manifest.artifacts)) {
-				descriptors.push(...manifest.artifacts);
+				groups.push({ runId: dir.name, artifactsRoot, descriptors: manifest.artifacts });
 			}
 		} catch {
 			// Skip unreadable/corrupt manifests — best-effort.
 		}
 	}
-	return descriptors;
+	return groups;
 }
 
 export function runArtifactCleanup(cwd: string): void {
@@ -49,9 +85,14 @@ export function runArtifactCleanup(cwd: string): void {
 			markerFile: CLEANUP_MARKER_FILE,
 		});
 
-		// ST-10: Enforce retention/expiresAt from manifest metadata.
-		pruneExpiredArtifacts(collectArtifactDescriptors(path.join(userCrewRoot(), DEFAULT_PATHS.state.runsSubdir)));
-		pruneExpiredArtifacts(collectArtifactDescriptors(path.join(projectCrewRoot(cwd), DEFAULT_PATHS.state.runsSubdir)));
+		// ST-10 + R44-N1: enforce retention/expiresAt from manifest metadata,
+		// per-run and containment-anchored — a run's descriptors can only prune
+		// files under that run's OWN host-derived artifacts root.
+		for (const scope of [userCrewRoot(), projectCrewRoot(cwd)]) {
+			for (const group of collectArtifactDescriptors(path.join(scope, DEFAULT_PATHS.state.runsSubdir))) {
+				pruneExpiredArtifacts(group.descriptors, { artifactsRoot: group.artifactsRoot });
+			}
+		}
 	} catch (error) {
 		logInternalError("register.artifact-cleanup", error, `cwd=${cwd}`);
 	}

package/src/extension/registration/commands/manage.ts

@@ -99,8 +99,10 @@ export function registerManageCommands(pi: ExtensionAPI, deps: RegisterTeamComma
 		description: "Open the pi-crew interactive menu (list/run/status/cleanup/manage resources/doctor)",
 		handler: handleTeamManagerCommand,
 	});
-	// Backward-compat alias: this command was originally registered as "team-cleanup"
-	// (the interactive menu predates the runId-targeted cleanup action). Keep both so
+	// Backward-compat alias: the interactive menu originally shipped under a
+	// runId-targeted name; `/team-cleanup` itself was NEVER registered (R27-D1) —
+	// the live names are `/team-manager` and this `/team-cleanup-menu` alias, so
+	// docs must not advertise `/team-cleanup <runId>`. Keep both.
 
 	pi.registerCommand("team-cleanup-menu", {
 		description: "Alias for /team-manager (pi-crew interactive menu)",
@@ -218,6 +220,11 @@ export function registerManageCommands(pi: ExtensionAPI, deps: RegisterTeamComma
 			// LAZY: load withSessionId only when needed for skill-create command
 			const { withSessionId } = await import("../../team-tool/context.ts");
 			const sessionId = withSessionId(ctx);
+			// R49-F7: `ctx.workspaceFolder` is a PHANTOM read — it is a VS-Code-era
+			// field that pi's ExtensionCommandContext does not define (absent in the
+			// resolved 0.77/1.0.4 api literal), so the optional chain always falls back
+			// to `process.cwd()`. Harmless (the fallback is correct) but do not treat
+			// this branch as a real cwd override.
 			const cwd =
 				(
 					ctx as unknown as {

package/src/extension/registration/hook-registration.ts

@@ -80,6 +80,9 @@ function installResourcesDiscoverHook(pi: ExtensionAPI, ctx: RegistrationContext
 			return paths.length > 0 ? { skillPaths: paths } : {};
 		});
 	} catch {
+		// R49-F4: `pi.on()` does NOT throw for an unknown event name in pi 0.77/1.0.4
+		// (verified against the resolved api literal + dist) — this catch is defensive
+		// only. The real degradation on an older host is that the hook NEVER FIRES.
 		/* older Pi without resources_discover */
 	}
 }

package/src/extension/registration/lazy-configurers.ts

@@ -76,6 +76,8 @@ function installTurnReconcileHook(pi: ExtensionAPI, ctx: RegistrationContext): v
 			}
 		});
 	} catch {
+		// R49-F4: `pi.on()` never throws on an unknown event (pi 0.77/1.0.4) — this
+		// catch is defensive; the real older-host degradation is a NEVER-FIRING hook.
 		/* older Pi without before_agent_start — rely on the interval alone */
 	}
 }