pi-crew 0.11.57 → 0.11.59

package/src/runtime/heartbeat/heartbeat-watcher.ts

@@ -46,6 +46,14 @@ export class HeartbeatWatcher {
 	private consecutiveDead = new Map<string, number>();
 	private lastSeen = new Map<string, number>(); // key → last time it was active
 	private lastDeadletterTriggerAt = new Map<string, number>(); // 3.6 cooldown gate
+	/**
+	 * Run-scoped metric label GC (FIX 2, 2026-11): runIds whose label values are
+	 * still live — observed running in a previous tick and not yet released.
+	 * Per-run label values are live only while the run is active; durable
+	 * per-run detail lives in the run's own events.jsonl + health snapshot.
+	 * See the release loop at the end of tickUnsafe().
+	 */
+	private activeRunIds = new Set<string>();
 	/** Max age (ms) to retain a stale key before garbage-collecting it. */
 	private readonly maxKeyAgeMs = 600_000; // 10 minutes
 	private readonly opts: HeartbeatWatcherOptions;
@@ -83,6 +91,8 @@ export class HeartbeatWatcher {
 		const thresholds = this.opts.thresholds ?? DEFAULT_GRADIENT_THRESHOLDS;
 		const tickThreshold = this.opts.deadletterTickThreshold ?? 3;
 		const activeKeys = new Set<string>();
+		// runIds confirmed running on disk this tick (see activeRunIds above).
+		const runningRunIds = new Set<string>();
 
 		for (const run of this.opts.manifestCache.list(50)) {
 			if (run.status !== "running") continue;
@@ -96,6 +106,8 @@ export class HeartbeatWatcher {
 			// This closes the false-positive alert loop when a run completes but the
 			// manifestCache.list(50) still serves a pre-completion snapshot.
 			if (loaded.manifest.status !== "running") continue;
+			// Confirmed running on disk → its run-scoped label values stay live.
+			runningRunIds.add(run.runId);
 			for (const task of loaded.tasks) {
 				if (task.status !== "running") continue;
 				// Guest-child tasks (delegate subagents, agent === "delegate") have NO
@@ -244,6 +256,42 @@ export class HeartbeatWatcher {
 			}
 		}
 
+		// Run-scoped metric label GC. `crew.heartbeat.staleness_ms`
+		// ({runId,taskId}) and `crew.heartbeat.level_total` ({runId,level}) are the
+		// only run-scoped series; without this the registry's label Maps grow
+		// unbounded (the MAX_LABEL_COMBINATIONS=10_000 FIFO cap is never reached at
+		// realistic volumes — measured: 101 label values/day across 33 runs, the
+		// heartbeat pair = 58% of a 26.9 KB metrics snapshot). Release a run's
+		// label values once it stops being active: durable per-run detail lives in
+		// the run's own events.jsonl + health snapshot — the same tradeoff OBS-1
+		// already applied to event metrics (src/observability/event-to-metric.ts:
+		// "Using runId/taskId as METRIC labels would blow up cardinality").
+		// Re-check the manifest cache first: a run may have fallen out of the
+		// top-50 scan window while still active, and a BLOCKED run (parked on
+		// `ask`, resumable — blocked is terminal-for-UI but never released) must
+		// keep its labels. Only a run that is neither running nor blocked, or that
+		// has vanished from the cache entirely, is released. Still-active runs stay
+		// in the tracking set so their release fires once they truly stop.
+		//
+		// Robustness: this pass must NEVER abort the tick — the stale-key cleanup
+		// below is load-bearing (it drops the deadletter cooldown marker, M-8) — so
+		// it is guarded and tolerates caches/registries that omit the reader
+		// (partial test seams).
+		try {
+			const nextActiveRunIds = new Set(runningRunIds);
+			for (const runId of this.activeRunIds) {
+				if (runningRunIds.has(runId)) continue;
+				if (this.isRunStillActive(runId)) {
+					nextActiveRunIds.add(runId);
+					continue;
+				}
+				this.opts.registry.releaseLabels?.((labels) => labels.runId === runId);
+			}
+			this.activeRunIds = nextActiveRunIds;
+		} catch (error) {
+			logInternalError("heartbeat-watcher.label-gc", error);
+		}
+
 		// Cleanup: drop keys that were NOT in this tick's active set AND
 		// haven't been seen for > maxKeyAgeMs.  This covers runs that
 		// completed or fell out of the manifest cache's top-50 window.
@@ -262,6 +310,31 @@ export class HeartbeatWatcher {
 		}
 	}
 
+	/**
+	 * Is the run still active per the manifest cache?
+	 *
+	 * `true` for "running" (it may simply have fallen out of the top-50 scan
+	 * window) and for "blocked" (parked on `ask`, resumable — blocked is
+	 * terminal-for-UI but must keep its labels). `false` when the run is gone or
+	 * carries a non-active status — that is the release case.
+	 *
+	 * A cache that cannot answer (missing `get`, or a throw) resolves to `true`
+	 * (keep): a wrongly released series belonging to a still-active run is
+	 * re-added on the next tick, but a series kept for a vanished run is only a
+	 * bounded leak — and the definitive release happens on the run-prune path.
+	 */
+	private isRunStillActive(runId: string): boolean {
+		const getStatus = this.opts.manifestCache.get;
+		if (typeof getStatus !== "function") return true;
+		try {
+			const manifest = getStatus.call(this.opts.manifestCache, runId);
+			return manifest?.status === "running" || manifest?.status === "blocked";
+		} catch (error) {
+			logInternalError("heartbeat-watcher.label-gc.status", error, `runId=${runId}`);
+			return true;
+		}
+	}
+
 	dispose(): void {
 		if (this.timer) clearTimeout(this.timer);
 		this.timer = undefined;
@@ -270,5 +343,8 @@ export class HeartbeatWatcher {
 		this.lastSeen.clear();
 		// M-8: clear the deadletter cooldown map too (was leaked before).
 		this.lastDeadletterTriggerAt.clear();
+		// Label-GC bookkeeping only (the registry outlives the watcher; labels
+		// are released on run inactivity, not on watcher teardown).
+		this.activeRunIds.clear();
 	}
 }

package/src/runtime/subagent-manager.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_PATHS, DEFAULT_SUBAGENT } from "../config/defaults.ts";
+import { getCrewEnv } from "../config/env-vars.ts";
 import type { PiTeamsToolResult } from "../extension/tool-result.ts";
 import { atomicWriteFile } from "../state/atomic-write.ts";
 import { loadRunManifestById } from "../state/stores/state-store.ts";
@@ -139,6 +140,128 @@ export function removePersistedSubagentRecord(cwd: string, id: string): boolean
  */
 export const MAX_TERMINAL_SUBAGENT_RECORDS = 50;
 
+/** FIX 3: statuses whose persisted record may be TTL-pruned. Anything else
+ * (queued | running | blocked) is NEVER deleted — `blocked` especially, since
+ * blockedSignalFromSubagentDir (terminal-status-wiring.ts) derives terminal
+ * blocked-state from blocked records on disk; deleting one breaks detection. */
+const TTL_PRUNABLE_STATUSES = new Set<SubagentStatus>(["completed", "failed", "cancelled", "error", "stopped"]);
+
+/** Default bound for the TTL prune scan: files examined per call (1,229 files
+ *  had accumulated on the dev box at discovery; 2,000 leaves headroom while
+ *  keeping session-start I/O bounded). */
+export const PRUNE_SUBAGENT_RECORDS_MAX_FILES = 2000;
+
+/**
+ * FIX 3: resolve the subagent record TTL (days) from
+ * PI_CREW_SUBAGENT_RECORD_TTL_DAYS (default 7; 0 disables). Invalid/negative
+ * values fall back to 7 with a logged warning — mirrors resolveAutoPruneKeep.
+ */
+export function resolveSubagentRecordTtlDays(env: (name: string) => string | undefined = getCrewEnv): number {
+	const raw = env("PI_CREW_SUBAGENT_RECORD_TTL_DAYS")?.trim();
+	if (raw === undefined || raw === "") return 7;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed < 0) {
+		logInternalError(
+			"subagent-manager.ttl-invalid",
+			new Error(`PI_CREW_SUBAGENT_RECORD_TTL_DAYS=${JSON.stringify(raw)} is not a non-negative integer; using 7`),
+		);
+		return 7;
+	}
+	return parsed;
+}
+
+export interface PrunePersistedSubagentRecordsOptions {
+	/** TTL in days. Defaults to resolveSubagentRecordTtlDays() (env-driven, 7).
+	 *  0 disables the prune entirely. */
+	ttlDays?: number;
+	/** Always keep this many most-recent records regardless of age/status.
+	 *  Default 50 (matches MAX_TERMINAL_SUBAGENT_RECORDS). */
+	keepRecent?: number;
+	/** Bound on files scanned per call. Default PRUNE_SUBAGENT_RECORDS_MAX_FILES. */
+	maxFiles?: number;
+	/** Clock injection for tests. */
+	now?: number;
+}
+
+/**
+ * FIX 3: TTL-prune persisted TERMINAL subagent records under
+ * `<projectCrewRoot(cwd)>/state/subagents/*.json`. removePersistedSubagentRecord
+ * only fires on explicit cancel/stop, so terminal records accumulated
+ * indefinitely (1,229 files / 6.7 MB over Jun–Oct).
+ *
+ * Safety contract:
+ *  - ONLY terminal statuses (see TTL_PRUNABLE_STATUSES) are eligible.
+ *    queued/running/blocked are never deleted (blocked drives
+ *    blockedSignalFromSubagentDir terminal-status derivation).
+ *  - The `keepRecent` most-recent records (by completedAt ?? startedAt) are
+ *    retained regardless of age or status (recent history stays inspectable).
+ *  - Malformed JSON is skipped (kept) — a corrupt file is never a prune target.
+ *  - Bounded scan + best-effort: never throws; per-file failures are kept.
+ */
+export function prunePersistedSubagentRecords(
+	cwd: string,
+	opts: PrunePersistedSubagentRecordsOptions = {},
+): { removed: string[]; kept: number } {
+	const ttlDays = opts.ttlDays ?? resolveSubagentRecordTtlDays();
+	if (ttlDays === 0) return { removed: [], kept: 0 }; // disabled — no scan, no delete
+	const removed: string[] = [];
+	let kept = 0;
+	try {
+		const dir = path.join(projectCrewRoot(cwd), DEFAULT_PATHS.state.subagentsSubdir);
+		let files: string[];
+		try {
+			files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+		} catch {
+			return { removed, kept }; // no dir / unreadable → nothing to do
+		}
+		const maxFiles = opts.maxFiles ?? PRUNE_SUBAGENT_RECORDS_MAX_FILES;
+		const now = opts.now ?? Date.now();
+		const ttlMs = ttlDays * 24 * 60 * 60 * 1000;
+		// Parse every (bounded) file; malformed → keep, tracked as kept so the
+		// caller can see the sweep saw it.
+		const parsed: Array<{ id: string; ageMs: number; terminal: boolean }> = [];
+		for (const file of files.slice(0, maxFiles)) {
+			try {
+				const raw = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8")) as unknown;
+				const record = sanitizePersistedRecord(raw);
+				if (!record) {
+					kept++;
+					continue;
+				}
+				const ageMs = now - (record.completedAt ?? record.startedAt);
+				parsed.push({ id: record.id, ageMs, terminal: TTL_PRUNABLE_STATUSES.has(record.status) });
+			} catch {
+				kept++; // unreadable/parse error → skip (keep)
+			}
+		}
+		// Keep-N shield: the keepRecent most-recent records survive regardless
+		// of age or status.
+		const keepRecent = opts.keepRecent ?? MAX_TERMINAL_SUBAGENT_RECORDS;
+		const shielded = new Set(
+			parsed
+				.slice()
+				.sort((a, b) => a.ageMs - b.ageMs) // smallest age = most recent first
+				.slice(0, Math.max(0, keepRecent))
+				.map((entry) => entry.id),
+		);
+		for (const entry of parsed) {
+			if (!entry.terminal || entry.ageMs <= ttlMs || shielded.has(entry.id)) {
+				kept++;
+				continue;
+			}
+			try {
+				fs.unlinkSync(path.join(dir, `${entry.id}.json`));
+				removed.push(entry.id);
+			} catch {
+				kept++; // unlink failed → still on disk
+			}
+		}
+	} catch (error) {
+		logInternalError("subagent-manager.prune-persisted", error, `cwd=${cwd}`);
+	}
+	return { removed, kept };
+}
+
 /**
  * Predicate: should this record's persisted file be deleted on terminal status?
  * Only abnormal terminations (cancelled / stopped / terminated-flag) are wiped.

package/src/runtime/task-packet.ts

@@ -384,6 +384,22 @@ export function parseHandoffFromOutput(output: string): ParsedHandoff {
 	};
 }
 
-export function renderTaskPacket(packet: TaskPacket): string {
-	return ["# Task Packet", "", "```json", JSON.stringify(packet, null, 2), "```", ""].join("\n");
+/** R3 (adaptive-04, 2026-11-04): render options for the prompt seam.
+ * `omitObjective` swaps the packet's `objective` field for a POINTER line —
+ * the worker prompt already carries the task body as the canonical `Task:`
+ * narrative (prompt-builder.ts taskAndHandoff), and the JSON re-embed
+ * duplicated it verbatim (measured ~0.5-1K est-tok/worker, the "task body
+ * ×3" finding). Default (no options) keeps the full objective so non-prompt
+ * consumers and the direct unit contract (task-handoff-template.test.ts)
+ * are unchanged. The substitution is render-only: `TaskPacket` state and
+ * `validateTaskPacket` still see the real objective. */
+export interface RenderTaskPacketOptions {
+	omitObjective?: boolean;
+}
+
+const OMITTED_OBJECTIVE_POINTER = "(see the 'Task:' section below — task body rendered once, not re-embedded here)";
+
+export function renderTaskPacket(packet: TaskPacket, options?: RenderTaskPacketOptions): string {
+	const body = options?.omitObjective ? { ...packet, objective: OMITTED_OBJECTIVE_POINTER } : packet;
+	return ["# Task Packet", "", "```json", JSON.stringify(body, null, 2), "```", ""].join("\n");
 }

package/src/runtime/task-runner/pre-execution.ts

@@ -152,9 +152,10 @@ export async function prepareTaskExecutionContext(
 	// caller provided one) into the dep-context collection — cache hits reuse
 	// the closeout's reads byte-identically; undefined keeps uncached behavior.
 	const dependencyContext = collectDependencyOutputContext(manifest, input.tasks, input.task, input.step, input.resultReadCache);
-	// Handoff budget: caps the dynamic.dependencyContext layer at an est-token
-	// (chars/4) budget (env PI_CREW_HANDOFF_BUDGET_TOKENS > runtime config >
-	// default 1800). IMPORTANT: only the RENDER path is budgeted — an explicit
+	// Handoff budget: caps the dynamic.dependencyContext layer at an
+	// effective-token budget (CJK-aware countTokens, utils/token-counter.ts)
+	// (env PI_CREW_HANDOFF_BUDGET_TOKENS > runtime config > default 1800).
+	// IMPORTANT: only the RENDER path is budgeted — an explicit
 	// input.dependencyContextText override (leader-provided text) passes through
 	// UNCHANGED.
 	const dependencyContextText =

package/src/runtime/task-runner/prompt-builder.ts

@@ -8,7 +8,7 @@ import { buildMemoryBlock } from "../agent-memory.ts";
 import { permissionForRole } from "../role-permission.ts";
 import { scrubDependencyContextBody } from "../task-output-context.ts";
 import { HANDOFF_TEMPLATE, renderTaskPacket, sanitizeTaskText } from "../task-packet.ts";
-import { buildWorkspaceTree } from "../workspace-tree.ts";
+import { buildTaskWorkspaceTree } from "../workspace-tree.ts";
 import { renderSuggestedFilesSection, runRetrievalCycle } from "./retrieval-orchestrator.ts";
 
 /**
@@ -159,23 +159,40 @@ export function renderOutputSchemaBlock(outputSchema: TaskOutputSchema): string
  * Expensive async sub-results that compose the stable prefix.
  * These are cached per (cwd, step.task, runId) so parallel siblings
  * in the same batch reuse them instead of recomputing.
+ *
+ * R2 (adaptive-04): the workspace tree is NO LONGER part of these
+ * components — it is now per-task (subtree around the task's working
+ * files), so caching it under the shared keys below would leak one task's
+ * subtree into its siblings. renderTaskPrompt builds the tree itself via
+ * buildTaskWorkspaceTree, which has its own per-root TTL cache.
  */
 export interface StableComponents {
-	treeBlock: string;
 	suggestedFilesBlock: string;
+	/**
+	 * R2.2 (adaptive-03): the retrieval-suggested file paths (relative to
+	 * the task cwd) behind `suggestedFilesBlock`. Carried alongside the
+	 * rendered block so the per-task workspace-tree scoping in
+	 * renderTaskPrompt can fall back to them when a step declares no
+	 * `reads` — no second retrieval pass. Both cache read sites must return
+	 * the SAME array the fresh compute produced: the keys already cover the
+	 * retrieval inputs (per-run key = cwd+step+runId with a run-fixed goal;
+	 * the cross-run io key includes the goal), so no key change is needed.
+	 */
+	suggestedFiles: string[];
 	knowledgeFragment: string;
 }
 
 const stableComponentCache = new Map<string, StableComponents>();
 
-// P9 (perf): cross-run cache for the I/O-heavy sub-results (workspace tree +
-// retrieval + knowledge). The tree and retrieval don't depend on runId, but
-// they DO depend on the run GOAL: `runRetrievalCycle(step.task, goal, cwd)`
-// and `buildKnowledgeFragment(cwd, { goal, taskText, role })` both take the
-// goal as a query signal. A short-lived (TTL-bounded) cross-run cache lets
-// sequential runs in the same session amortize the cost: run #2 in cwd X with
-// the same step text AND the same goal gets a cache hit instead of redoing
-// `buildWorkspaceTree` (which walks the FS) and `runRetrievalCycle`. The TTL
+// P9 (perf): cross-run cache for the I/O-heavy sub-results (retrieval +
+// knowledge; R2 moved the workspace tree out to a per-task scope, so it no
+// longer rides these goal-scoped caches). Retrieval and knowledge don't
+// depend on runId, but they DO depend on the run GOAL:
+// `runRetrievalCycle(step.task, goal, cwd)` and `buildKnowledgeFragment(cwd,
+// { goal, taskText, role })` both take the goal as a query signal. A
+// short-lived (TTL-bounded) cross-run cache lets sequential runs in the same
+// session amortize the cost: run #2 in cwd X with the same step text AND the
+// same goal gets a cache hit instead of redoing `runRetrievalCycle`. The TTL
 // bounds staleness in long-lived sessions (e.g., the workspace may have
 // changed between runs); a mtime check on the .git/HEAD or workspace marker
 // would be overkill for an already-bounded perf win. The full per-run cache
@@ -195,8 +212,9 @@ const stableComponentCache = new Map<string, StableComponents>();
 // (src/extension/knowledge-injection.ts:61-68); if it ever starts scoring, the
 // key must gain it too.
 interface CachedStableIO {
-	treeBlock: string;
 	suggestedFilesBlock: string;
+	/** R2.2: retrieval file paths ride the cross-run cache with the block. */
+	suggestedFiles: string[];
 	knowledgeFragment: string;
 	at: number;
 }
@@ -229,7 +247,8 @@ export function clearStablePrefixCache(): void {
 
 /**
  * Compute (or return cached) expensive async sub-results that compose
- * the stable prefix: workspace tree, file retrieval, knowledge fragment.
+ * the stable prefix: file retrieval, knowledge fragment. (R2: the workspace
+ * tree left this cache — it is per-task now; see StableComponents.)
  * Parallel siblings with the same cwd/step/run reuse the cached result.
  */
 export async function computeStablePrefixComponents(
@@ -255,19 +274,22 @@ export async function computeStablePrefixComponents(
 	const ioFresh = ioCached && now - ioCached.at < STABLE_IO_TTL_MS;
 	if (ioFresh) {
 		const components: StableComponents = {
-			treeBlock: ioCached!.treeBlock,
 			suggestedFilesBlock: ioCached!.suggestedFilesBlock,
+			// R2.2: reconstruct the retrieval paths too — a cross-run hit that
+			// dropped them would silently de-scope the caller's task tree back
+			// to the whole workspace.
+			suggestedFiles: ioCached!.suggestedFiles,
 			knowledgeFragment: ioCached!.knowledgeFragment,
 		};
 		stableComponentCache.set(cacheKey, components);
 		return components;
 	}
 
-	const tree = await buildWorkspaceTree(task.cwd);
-	const treeBlock = tree.rendered ? `# Workspace Structure\n${tree.rendered}` : "";
-
 	const retrieval = await runRetrievalCycle(step.task, manifest.goal, task.cwd);
 	const suggestedFilesBlock = renderSuggestedFilesSection(retrieval);
+	// R2.2: keep the raw paths (relative to task.cwd) next to the rendered
+	// block so the tree scoping below can reuse the retrieval result.
+	const suggestedFiles = retrieval.files.map((file) => file.path);
 
 	const knowledgeFragment = buildKnowledgeFragment(task.cwd, {
 		goal: manifest.goal,
@@ -275,7 +297,7 @@ export async function computeStablePrefixComponents(
 		role: step.role,
 	});
 
-	const components: StableComponents = { treeBlock, suggestedFilesBlock, knowledgeFragment };
+	const components: StableComponents = { suggestedFilesBlock, suggestedFiles, knowledgeFragment };
 	stableComponentCache.set(cacheKey, components);
 	// RR-021 WI-4.3f: same insertion-order eviction cap as the stableIOCache
 	// sibling below — stableComponentCache had NO cap (unbounded across a
@@ -321,6 +343,28 @@ export function promptBreakdownEnabled(): boolean {
 	return getCrewEnv("PI_CREW_PROMPT_BREAKDOWN") === "1";
 }
 
+/**
+ * R2.2 (adaptive-03): pick the focus paths for the task-scoped workspace
+ * tree. `step.reads` (declared inputs) is the strongest signal and wins
+ * whenever it yields at least one non-empty string (`reads: false` means
+ * "no declared reads" — the same normalization used by task-packet.ts and
+ * task-output-context.ts — so it falls through, it does not opt out). When
+ * the step declares none, fall back to the retrieval-suggested files that
+ * already ride the (cached) StableComponents — zero extra I/O. Anything
+ * else (no reads AND no suggestions, junk-only entries) yields `undefined`
+ * so buildTaskWorkspaceTree keeps the whole-workspace fallback, the
+ * pre-R2.2 fail-safe. Out-of-workspace/nonexistent paths keep their
+ * existing NIT-2/dir-refinement semantics inside the resolver.
+ */
+function treeFocusPaths(reads: WorkflowStep["reads"], suggestedFiles: readonly string[] | undefined): string[] | undefined {
+	const declared = Array.isArray(reads) ? reads.filter((entry): entry is string => typeof entry === "string" && entry.trim() !== "") : [];
+	if (declared.length > 0) return declared;
+	const retrieved = Array.isArray(suggestedFiles)
+		? suggestedFiles.filter((entry): entry is string => typeof entry === "string" && entry.trim() !== "")
+		: [];
+	return retrieved.length > 0 ? retrieved : undefined;
+}
+
 /**
  * SR-02 phase 2: worker-prompt skill injection mode. Default "index" injects
  * compact per-skill entries (name + description + Path pointer) and the worker
@@ -413,7 +457,13 @@ export async function renderTaskPrompt(
 		`Step: ${step.id}`,
 		`Role: ${step.role}`,
 	].join("\n");
-	const taskPacketBlock = task.taskPacket ? renderTaskPacket(task.taskPacket) : "";
+	// R3 (adaptive-04): single-canonical task body. The packet JSON used to
+	// re-embed the full objective — the SAME text as the `Task:` narrative
+	// below — a second time ("task body ×3" finding; the third copy is the
+	// parent-context embed in child-pi.ts, outside this seam). The JSON block
+	// now carries a pointer; renderTaskPacket's default still embeds the
+	// objective for non-prompt consumers and the direct unit contract.
+	const taskPacketBlock = task.taskPacket ? renderTaskPacket(task.taskPacket, { omitObjective: true }) : "";
 	const specContractBlock = task.taskPacket?.specSnapshots?.length
 		? renderSpecContractBlock(task.taskPacket, { verifier: step.role === "verifier" })
 		: "";
@@ -427,16 +477,35 @@ export async function renderTaskPrompt(
 		HANDOFF_TEMPLATE,
 	].join("\n");
 
-	// Stable prefix: role instructions, coordination, workspace tree — rarely changes.
+	// R2 (adaptive-04): the workspace tree is scoped to a subtree AROUND this
+	// task's working files instead of the identical whole-workspace walk that
+	// every sibling worker used to carry. Per-task content must NOT ride the
+	// byte-stable shared prefix (ARCH-3), so the block lives at the END of the
+	// dynamic suffix; buildWorkspaceTree's per-root TTL cache keeps parallel
+	// siblings sharing a scope on one walk.
+	// R2.2 (adaptive-03): the focus signal is reads-first — step.reads when the
+	// step declares inputs, else the retrieval-suggested files from the stable
+	// components (the smoke-run steps declare no reads, so pre-R2.2 they always
+	// carried the whole tree). No signal / out-of-workspace / non-existent
+	// scope ⇒ legacy full tree (fail-safe unchanged).
+	const { tree: taskTree, scope: treeScope } = await buildTaskWorkspaceTree(
+		task.cwd,
+		treeFocusPaths(step.reads, stableComponents.suggestedFiles),
+	);
+	const treeBlock = taskTree.rendered
+		? `# Workspace Structure${treeScope.relativePath === "." ? "" : ` (subtree: ${treeScope.relativePath})`}\n${taskTree.rendered}`
+		: "";
+
+	// Stable prefix: role instructions, coordination — rarely changes.
 	// ARCH-3 (byte-stable worker prefix): per-task values (Task ID, Task cwd, mailbox
-	// target) live in dynamicSuffix so siblings sharing a run+role produce a
-	// byte-identical prefix and hit provider KV-cache across the batch.
+	// target, the R2 task-scoped workspace tree) live in dynamicSuffix so siblings
+	// sharing a run+role produce a byte-identical prefix and hit provider KV-cache
+	// across the batch.
 	const stablePrefix = [
 		headerBlock,
 		protocolBlock,
 		roleInstructions,
 		coordination,
-		stableComponents.treeBlock,
 		stableComponents.suggestedFilesBlock,
 		toolGuidance,
 		// O4 (ARCH-2 corrected): project knowledge (.crew/knowledge.md). Builtin
@@ -451,8 +520,10 @@ export async function renderTaskPrompt(
 		.filter(Boolean)
 		.join("\n");
 
-	// Dynamic suffix: goal, step, skills, task packet, dependency context, memory — changes per task
-	const dynamicSuffix = [
+	// Dynamic suffix: goal, step, skills, task packet, dependency context, memory — changes per task.
+	// R2: the task-scoped workspace tree is pinned LAST (the most task-variable
+	// block) so everything before it keeps the per-task layout stable.
+	const dynamicParts = [
 		taskHeader,
 		"",
 		skillBlock,
@@ -465,7 +536,9 @@ export async function renderTaskPrompt(
 		memoryBlock,
 		outputSchemaBlock,
 		taskAndHandoff,
-	].join("\n");
+	];
+	if (treeBlock) dynamicParts.push("", treeBlock);
+	const dynamicSuffix = dynamicParts.join("\n");
 
 	const full = [stablePrefix, "", dynamicSuffix].join("\n");
 	const sections: Record<string, number> | undefined = promptBreakdownEnabled()
@@ -476,7 +549,11 @@ export async function renderTaskPrompt(
 				"stable.protocol": protocolBlock.length,
 				"stable.roleInstructions": roleInstructions.length,
 				"stable.coordination": coordination.length,
-				"stable.workspaceTree": stableComponents.treeBlock.length,
+				// R2 mapping for before/after comparison: pre-R2 key was
+				// "stable.workspaceTree" (identical whole-workspace walk ×N,
+				// riding the system-append channel); post-R2 the tree is a
+				// per-task subtree in the user message → "dynamic.workspaceTree".
+				"dynamic.workspaceTree": treeBlock.length,
 				"stable.suggestedFiles": stableComponents.suggestedFilesBlock.length,
 				"stable.toolGuidance": toolGuidance.length,
 				"stable.knowledge": stableComponents.knowledgeFragment.length,

package/src/runtime/workspace-tree.ts

@@ -245,6 +245,138 @@ function applyLineCap(lines: RenderLine[], cap: number): { lines: RenderLine[];
 	return { lines: kept, elided: removable.length };
 }
 
+// ── Task-scoped subtree (R2, adaptive-04 2026-11-04) ───────────────────
+
+export interface TaskTreeScope {
+	/** Absolute directory the walk roots at. */
+	rootPath: string;
+	/** Scope relative to the workspace root; "." when the walk covers the whole workspace. */
+	relativePath: string;
+}
+
+/** Normalize a native-separator relative path to forward slashes (no-op on POSIX). */
+function toPosixRel(p: string): string {
+	return path.sep === "/" ? p : p.split(path.sep).join("/");
+}
+
+/** Longest shared directory prefix across relative dir paths ("." when none). */
+function commonDirPrefix(dirs: string[]): string {
+	const split = dirs.map((d) => d.split(path.sep).filter((p) => p !== "" && p !== "."));
+	let prefix = split[0] ?? [];
+	for (let i = 1; i < split.length && prefix.length > 0; i++) {
+		const other = split[i]!;
+		const keep: string[] = [];
+		for (let j = 0; j < Math.min(prefix.length, other.length); j++) {
+			if (prefix[j] === other[j]) keep.push(prefix[j]!);
+			else break;
+		}
+		prefix = keep;
+	}
+	return prefix.length > 0 ? prefix.join(path.sep) : ".";
+}
+
+/**
+ * R2 (adaptive-04): resolve the walk root for a task-scoped workspace tree.
+ *
+ * The legacy prompt seam walked the ENTIRE workspace from `task.cwd` — in
+ * shared-workspace mode that is the same root for every sibling worker, so
+ * each prompt carried an identical whole-workspace tree (measured 26% of the
+ * 01_discover artifact, ~0.9K est-tok/worker). This resolves a subtree
+ * AROUND the task's working files instead: the deepest directory that is an
+ * ancestor of every in-workspace focus path (focus paths are the step's
+ * `reads`, which follow file-path semantics — a directory-valued read
+ * contributes its parent and therefore narrows nothing).
+ *
+ * Deterministic and pure (no FS access) so unit tests pin the scoping rule
+ * directly. Falls back to "." (whole workspace, legacy behavior) when there
+ * are no focus paths, when they all live outside the workspace, or when they
+ * share no directory below the root.
+ */
+export function resolveTaskTreeScope(workspaceCwd: string, focusPaths?: readonly string[] | false | null): TaskTreeScope {
+	const rootPath = path.resolve(workspaceCwd);
+	if (!focusPaths || focusPaths.length === 0) return { rootPath, relativePath: "." };
+
+	const insideDirs: string[] = [];
+	for (const entry of focusPaths) {
+		if (typeof entry !== "string" || entry.trim() === "") continue;
+		const rel = path.relative(rootPath, path.resolve(rootPath, entry));
+		// Outside the workspace ("../x", absolute elsewhere) cannot scope it.
+		// Exact `..` or `..`+sep only — a literal "..foo" sibling stays inside.
+		if (!rel || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) continue;
+		insideDirs.push(path.dirname(rel));
+	}
+	if (insideDirs.length === 0) return { rootPath, relativePath: "." };
+
+	const common = commonDirPrefix(insideDirs);
+	if (common === ".") return { rootPath, relativePath: "." };
+	// relativePath is a POSIX-style contract (prompt header, breakdown, tests) —
+	// normalize Windows separators at the boundary; rootPath stays native for FS.
+	return { rootPath: path.join(rootPath, common), relativePath: toPosixRel(common) };
+}
+
+export interface TaskWorkspaceTree {
+	tree: WorkspaceTree;
+	scope: TaskTreeScope;
+}
+
+/**
+ * R2 (adaptive-04): build the workspace tree scoped to a subtree around the
+ * task's working files. Options/defaults are the legacy `buildWorkspaceTree`
+ * ones (depth 3 / dirLimit 12 / lineCap 120) — only the walk ROOT narrows.
+ *
+ * Fail-safe: a focus path pointing at a directory that does not exist (typo,
+ * glob pattern, stale path) must not strip the worker's tree — the walk falls back to the whole workspace, byte-identical to pre-R2.
+ * Per-root walks reuse `buildWorkspaceTree`'s TTL cache, so parallel
+ * siblings that share a scope do one FS walk.
+ */
+export async function buildTaskWorkspaceTree(
+	workspaceCwd: string,
+	focusPaths?: readonly string[] | false | null,
+	options?: WorkspaceTreeOptions,
+): Promise<TaskWorkspaceTree> {
+	const scope = resolveTaskTreeScope(workspaceCwd, focusPaths);
+	// NIT-2 (review follow-up): a top-level directory-valued focus path
+	// (e.g. reads: ["pi-crew"]) contributes dirname "." in the PURE resolver —
+	// file-path semantics — and de-scopes to the whole workspace even though
+	// the task plainly scopes to that directory. Refine HERE (the FS layer;
+	// resolveTaskTreeScope stays FS-free): on the fallback path only, stat each
+	// inside-workspace focus path and treat an EXISTING directory as its own
+	// scope root. Nonexistent paths keep file-path semantics (dirname), so a
+	// typo/glob still falls back fail-safe; a directory mixed with a root-level
+	// file still resolves to the whole workspace (conservative, no narrowing).
+	let effective = scope;
+	if (scope.relativePath === "." && Array.isArray(focusPaths) && focusPaths.length > 0) {
+		const rootPath = path.resolve(workspaceCwd);
+		const candidates: string[] = [];
+		for (const entry of focusPaths) {
+			if (typeof entry !== "string" || entry.trim() === "") continue;
+			const abs = path.resolve(rootPath, entry);
+			const rel = path.relative(rootPath, abs);
+			if (!rel || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) continue;
+			let isDir = false;
+			try {
+				isDir = (await fs.stat(abs)).isDirectory();
+			} catch {
+				isDir = false;
+			}
+			candidates.push(isDir ? rel : path.dirname(rel));
+		}
+		if (candidates.length > 0) {
+			const common = commonDirPrefix(candidates);
+			if (common !== ".") effective = { rootPath: path.join(rootPath, common), relativePath: toPosixRel(common) };
+		}
+	}
+	if (effective.relativePath !== ".") {
+		try {
+			await fs.stat(effective.rootPath);
+		} catch {
+			const rootPath = path.resolve(workspaceCwd);
+			return { tree: await buildWorkspaceTree(rootPath, options), scope: { rootPath, relativePath: "." } };
+		}
+	}
+	return { tree: await buildWorkspaceTree(effective.rootPath, options), scope: effective };
+}
+
 // ── Public API ────────────────────────────────────────────────────────
 
 const emptyResult = (rootPath: string): WorkspaceTree => ({