pi-crew 0.11.57 → 0.11.59

package/docs/architecture.md

@@ -102,6 +102,7 @@ lives there. The ones most likely to be set by hand:
 | `PI_CREW_ASYNC_EARLY_EXIT_GUARD=0` | Disable the async-run early-exit guard. |
 | `PI_TEAMS_MOCK_CHILD_PI` / `PI_CREW_MOCK_LIVE_SESSION` | Test hooks for mocked worker execution. |
 | `PI_CREW_MAX_WORKERS` | Cap concurrent workers (default `max(2, cpus−2)`). |
+| `PI_CREW_KNOWLEDGE_MAX_BYTES` | Cap knowledge.md injection (bytes) across every path — worker prompts and the main session alike; `0`/negative disables knowledge injection entirely (unset keeps per-path defaults 5000/2048/2000). |
 | `PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS` | Child Pi response timeout. |
 
 ### Debugging a run

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.57",
+	"version": "0.11.59",
 	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
 	"author": "baphuongna",
 	"license": "MIT",

package/src/config/config-validation.ts

@@ -79,8 +79,9 @@ export const LIMIT_CEILINGS = {
 	// (10_000 turns), which capped the effective timeout at 10s and silently disabled
 	// any larger value (e.g. 300_000 = 5min) via parsePositiveInteger returning undefined.
 	runtimeTaskTimeoutMs: 24 * 60 * 60 * 1000,
-	// Handoff budget (est tokens, chars/4) for the dynamic.dependencyContext
-	// prompt layer. Above the ceiling the budget is treated as the OFF-switch
+	// Handoff budget (effective tokens — CJK-aware countTokens,
+	// utils/token-counter.ts) for the dynamic.dependencyContext prompt layer.
+	// Above the ceiling the budget is treated as the OFF-switch
 	// (untrimmed render), mirroring the render-site semantics in
 	// task-output-context.ts.
 	runtimeHandoffBudgetTokens: 1_000_000,
@@ -413,8 +414,10 @@ function parseModelFallbackConfig(value: unknown): CrewRuntimeConfig["modelFallb
 }
 
 /**
- * Handoff budget for the dynamic.dependencyContext prompt layer (est tokens,
- * chars/4). Deliberately NOT parsePositiveInteger: out-of-range values are
+ * Handoff budget for the dynamic.dependencyContext prompt layer (effective
+ * tokens — CJK-aware countTokens from utils/token-counter.ts, floored by the
+ * measured-output anchor at the render site; the old chars/4 wording was
+ * drift). Deliberately NOT parsePositiveInteger: out-of-range values are
  * dropped silently (undefined → render site falls back to default 1800)
  * rather than rejecting the whole runtime block. The ≤0 / >1_000_000
  * OFF-switch is expressible only via env PI_CREW_HANDOFF_BUDGET_TOKENS

package/src/config/env-allowlist-registry.ts

@@ -279,12 +279,17 @@ const CREW_ENV_FORWARDING_DECL: Record<string, CrewEnvForwardDecision> = {
 	PI_CREW_KEYBINDINGS: { kind: "host-only", reason: "host keybinding map" },
 	PI_CREW_AUTO_PRUNE_KEEP: { kind: "host-only", reason: "session-start auto-prune (run-maintenance, host)" },
 	PI_CREW_AUTO_PRUNE_AGE_FLOOR_HOURS: { kind: "host-only", reason: "session-start auto-prune (host)" },
+	PI_CREW_SUBAGENT_RECORD_TTL_DAYS: { kind: "host-only", reason: "session-start subagent-record TTL prune (subagent-manager, host)" },
 	PI_CREW_USE_BUNDLE: { kind: "host-only", reason: "root index.ts loader choice (outside src/ gate scope)" },
 
 	// — gap: read by code that ALSO runs in the detached runner, deliberately
 	//   NOT forwarded (behavior preservation 0.11.17) — follow-up candidates.
 	PI_CREW_PROMPT_BREAKDOWN: { kind: "gap", reason: "prompt-builder runs in the runner for async runs" },
 	PI_CREW_PROMPT_SKILLS: { kind: "gap", reason: "prompt-builder runs in the runner for async runs" },
+	PI_CREW_KNOWLEDGE_MAX_BYTES: {
+		kind: "gap",
+		reason: "knowledge-injection read (prompt-builder stable prefix) runs in the runner for async runs; deliberately not forwarded — workers receive knowledge via prompt text, not env (same class as PI_CREW_PROMPT_SKILLS)",
+	},
 	PI_CREW_BACKGROUND_MODE: { kind: "gap", reason: "child-executor read inside the runner" },
 	PI_CREW_DEBUG: { kind: "gap", reason: "background-runner debug logging" },
 	PI_TEAMS_DEBUG: { kind: "gap", reason: "internal-error severity gate — every process incl. the runner" },

package/src/config/env-vars.ts

@@ -263,6 +263,11 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_PROMPT_SKILLS",
 		doc: "'full' inlines complete skill bodies in worker prompts (SR-02 escape hatch); default injects compact index entries (name+description+path, read-on-demand)",
 	},
+	PI_CREW_KNOWLEDGE_MAX_BYTES: {
+		name: "PI_CREW_KNOWLEDGE_MAX_BYTES",
+		parser: "int",
+		doc: "R1 (adaptive context diet): byte cap for knowledge.md injection — overrides EVERY knowledge-injection cap at once (worker/query path MAX_SESSION_LOG_BYTES 5000 + MAX_CONVENTIONS_BYTES 2048, no-query main-session path MAX_KNOWLEDGE_HEAD_BYTES 2000; knowledge-injection.ts readKnowledge). Unset/non-integer → per-path defaults (byte-identical to pre-R1 behavior, pinned by unit test); ≥1 → each cap becomes N; ≤0 → off-switch, injects NO knowledge",
+	},
 	PI_CREW_ASYNC_EARLY_EXIT_GUARD: {
 		name: "PI_CREW_ASYNC_EARLY_EXIT_GUARD",
 		doc: "'0' skips the async-run early-exit guard (team-tool/run.ts:103)",
@@ -345,7 +350,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	PI_CREW_HANDOFF_BUDGET_TOKENS: {
 		name: "PI_CREW_HANDOFF_BUDGET_TOKENS",
 		parser: "int",
-		doc: "est-token (chars/4) budget for the dynamic.dependencyContext prompt layer; beats runtime.handoffBudgetTokens, default 1800; resolved ≤0 or >1_000_000 disables the trim (task-output-context.ts renderDependencyOutputContext)",
+		doc: "effective-token budget for the dynamic.dependencyContext prompt layer (CJK-aware countTokens, utils/token-counter.ts — NOT chars/4, that wording was drift); beats runtime.handoffBudgetTokens, default 1800; resolved ≤0 or >1_000_000 disables the trim (task-output-context.ts renderDependencyOutputContext)",
 	},
 	PI_CREW_MOCK_LIVE_SESSION: {
 		name: "PI_CREW_MOCK_LIVE_SESSION",
@@ -606,6 +611,12 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		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_SUBAGENT_RECORD_TTL_DAYS: {
+		name: "PI_CREW_SUBAGENT_RECORD_TTL_DAYS",
+		parser: "int",
+		default: 7,
+		doc: "FIX 3: days a TERMINAL subagent record (<crewRoot>/state/subagents/*.json) survives before the session-start prune deletes it (0 disables; running/blocked/queued records are NEVER deleted — blocked drives blockedSignalFromSubagentDir; subagent-manager.ts prunePersistedSubagentRecords)",
+	},
 	PI_CREW_SURFACE: {
 		name: "PI_CREW_SURFACE",
 		doc: "surface provider kind for this worker ('tmux'|'herdr') — arms the worker-side recorder/parent-guard (written by prepareSurfaceSpawn.ts:214, read by surface-worker.ts)",

package/src/config/role-tools.ts

@@ -60,9 +60,10 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 		scratchpad: true,
 	},
 
-	// Reviewer - Read and review, no write
+	// Reviewer - Read and review, no write (bash dropped 2026-11-05: read_only
+	// tier strips it at runtime anyway — R6 drift fix, agents/reviewer.md)
 	reviewer: {
-		tools: ["read", "grep", "find", "ls", "glob", "bash", "ask"],
+		tools: ["read", "grep", "find", "ls", "glob", "ask"],
 		excludeTools: ["edit", "write"],
 	},
 

package/src/config/types.ts

@@ -180,10 +180,12 @@ export interface CrewRuntimeConfig {
 	/** Mark certain bash commands as excludeFromContext to reduce context tokens. Default: false */
 	excludeContextBash?: boolean;
 	/**
-	 * Est-token budget for the dynamic.dependencyContext prompt layer
+	 * Effective-token budget for the dynamic.dependencyContext prompt layer
 	 * (handoff budget). When the rendered dependency output exceeds this many
-	 * estimated tokens (chars/4 — the same heuristic the prompt breakdown
-	 * uses), dependencies are trimmed IN DECLARATION ORDER: earlier deps keep
+	 * effective tokens (countTokens — the CJK-aware estimator in
+	 * utils/token-counter.ts, floored by the measured-output anchor; the old
+	 * chars/4 wording was drift), dependencies are trimmed IN DECLARATION
+	 * ORDER: earlier deps keep
 	 * their full output, later ones are downgraded to taskId/role/status + a
 	 * ≤240-char summary head + an artifact pointer
 	 * (`artifacts/<runId>/results/<taskId>.txt`) the worker can `read` back.

package/src/extension/knowledge-injection.ts

@@ -52,6 +52,64 @@ const MAX_SESSION_LOG_BYTES = 5_000;
  */
 export const MAX_CONVENTIONS_BYTES = 2_048;
 
+/**
+ * R1 (adaptive context diet, 2026-11-04): single env knob capping how much
+ * knowledge.md content is injected, read via getCrewEnv so the registry +
+ * env gate stay the single read path. PI_CREW_KNOWLEDGE_MAX_BYTES overrides
+ * EVERY injection cap in this file — the worker/query-path caps
+ * (MAX_SESSION_LOG_BYTES + MAX_CONVENTIONS_BYTES) AND the no-query
+ * main-session head cap (MAX_KNOWLEDGE_HEAD_BYTES).
+ *
+ * WHY one knob over all three caps (decision recorded per task packet):
+ * the three caps are per-path bounds of the SAME injection surface — one
+ * dial means one mental model ("max bytes of knowledge per agent") for
+ * both the host session and worker prompts; a per-path split would need
+ * three env names to move one budget, and the worker path (the context-diet
+ * target) spans TWO caps that must move together anyway.
+ *
+ * Semantics (mirrors PI_CREW_HANDOFF_BUDGET_TOKENS):
+ *   - unset / non-integer / empty → per-path defaults above — output is
+ *     BYTE-IDENTICAL to pre-R1 behavior (HARD RULE, pinned by unit test);
+ *   - N ≥ 1 → every cap becomes N (raising above a default is allowed);
+ *   - N ≤ 0 → off-switch: NO knowledge injected (readKnowledge → "").
+ */
+const KNOWLEDGE_MAX_BYTES_ENV_RE = /^[+-]?\d+$/;
+
+/**
+ * R1.1 (adaptive context diet, 2026-11-05): bound on the session-log
+ * section INDEX rendered into every worker prompt. The index used to list
+ * EVERY session-log header — a recovery safety net that grew linearly with
+ * knowledge.md history (measured 2026-11-05 on this repo: 130 entries ≈
+ * 10.4K chars = 82% of the whole injected block, dwarfing the ~2K of matched
+ * content the knob actually caps). The index is now bounded to the most
+ * recent MAX_INDEX_ENTRIES entries (file order — the session-log is
+ * chronological, newest appended last) plus a one-line counter pointing
+ * `read` at the full file for the omitted earlier ones. Unlike the byte caps
+ * this bound applies BY DEFAULT (knob unset) — the unbounded index was the
+ * real growth bug. Unset output changes ONLY inside this index comment, and
+ * only when a project has more than MAX_INDEX_ENTRIES session-log sections;
+ * injected CONTENT (conventions + matched session-log bodies + their
+ * truncation notices) is byte-identical when unset.
+ */
+const MAX_INDEX_ENTRIES = 15;
+
+/** Resolve the R1 knob: undefined = unset/invalid (keep per-path defaults),
+ *  otherwise the parsed integer (≤0 = off-switch). Never throws. */
+function resolveKnowledgeMaxBytes(): number | undefined {
+	const raw = getCrewEnv("PI_CREW_KNOWLEDGE_MAX_BYTES");
+	if (raw === undefined) return undefined;
+	const trimmed = raw.trim();
+	if (!KNOWLEDGE_MAX_BYTES_ENV_RE.test(trimmed)) return undefined;
+	const parsed = Number.parseInt(trimmed, 10);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/** Effective cap for one path: knob override (guaranteed ≥1 — the ≤0
+ *  off-switch returns early in readKnowledge), else the path default. */
+function knowledgeCap(defaultBytes: number, knob: number | undefined): number {
+	return knob === undefined ? defaultBytes : knob;
+}
+
 /**
  * Relevance context for section-aware injection. When omitted (or when goal/
  * taskText are both absent), injection falls back to conventions-only — no
@@ -268,6 +326,10 @@ function selectSessionLog(query: string, sessionLog: KnowledgeSection[], budgetB
 /** Read knowledge content. "" if absent/empty. */
 export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 	try {
+		// R1 knob: resolved once per call; ≤0 short-circuits BOTH paths to ""
+		// (off-switch) BEFORE any file I/O or cache interaction.
+		const maxBytes = resolveKnowledgeMaxBytes();
+		if (maxBytes !== undefined && maxBytes <= 0) return "";
 		const p = knowledgePath(cwd);
 		const stat = tryStat(p);
 		if (!stat) {
@@ -286,7 +348,15 @@ export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 		// start (main session + every worker), re-reading the file each time.
 		// For a run with N workers this is N redundant readFileSync of the same
 		// file. Cache by (mtimeMs, size) and only re-read when the file changes.
-		const cacheKey = `${stat.mtimeMs}:${stat.size}`;
+		// R1: the no-query CONTENT depends on the effective head cap, so the cap
+		// rides the content-cache key (a same-process env change between reads
+		// must not serve a stale truncation). Parsed sections stay cap-independent.
+		const headCap = knowledgeCap(MAX_KNOWLEDGE_HEAD_BYTES, maxBytes);
+		const cacheKey = `${stat.mtimeMs}:${stat.size}:${headCap}`;
+		// NIT-3 (review follow-up): parsed sections are cap-INDEPENDENT — key
+		// them by file identity only, so a mid-process knob change re-truncates
+		// (knowledgeCache above) but never re-parses the file.
+		const sectionKey = `${stat.mtimeMs}:${stat.size}`;
 
 		// B2: when no query context is provided (main-session hook, legacy
 		// callers, tests), keep the simple head-only path. This preserves the
@@ -298,8 +368,8 @@ export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 			// markers are added, so system-generated HTML comments (truncation
 			// notices) survive — sanitizeAgentSystemPrompt strips ALL HTML comments.
 			let content = sanitizeAgentSystemPrompt(fs.readFileSync(p, "utf8").trim(), "project");
-			if (content.length > MAX_KNOWLEDGE_HEAD_BYTES) {
-				content = `${content.slice(0, MAX_KNOWLEDGE_HEAD_BYTES)}\n\n<!-- knowledge.md truncated at ${MAX_KNOWLEDGE_HEAD_BYTES} bytes (head shown). Full file: ${p} — use the \`read\` tool if you need sections beyond the head. -->`;
+			if (content.length > headCap) {
+				content = `${content.slice(0, headCap)}\n\n<!-- knowledge.md truncated at ${headCap} bytes (head shown). Full file: ${p} — use the \`read\` tool if you need sections beyond the head. -->`;
 			}
 			knowledgeCache.set(p, { key: cacheKey, content });
 			enforceKnowledgeCacheCap(knowledgeCache);
@@ -312,7 +382,7 @@ export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 			conventions: KnowledgeSection[];
 			sessionLog: KnowledgeSection[];
 		};
-		if (cachedSections && cachedSections.key === cacheKey) {
+		if (cachedSections && cachedSections.key === sectionKey) {
 			parsed = {
 				conventions: cachedSections.conventions,
 				sessionLog: cachedSections.sessionLog,
@@ -323,7 +393,7 @@ export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 			const content = sanitizeAgentSystemPrompt(fs.readFileSync(p, "utf8").trim(), "project");
 			parsed = parseKnowledgeSections(content);
 			sectionCache.set(p, {
-				key: cacheKey,
+				key: sectionKey,
 				conventions: parsed.conventions,
 				sessionLog: parsed.sessionLog,
 			});
@@ -331,31 +401,60 @@ export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 		}
 
 		const queryText = [query.goal, query.taskText].filter(Boolean).join(" \n ");
-		const matchedSessionLog = selectSessionLog(queryText, parsed.sessionLog, MAX_SESSION_LOG_BYTES);
+		const sessionLogCap = knowledgeCap(MAX_SESSION_LOG_BYTES, maxBytes);
+		const matchedSessionLog = selectSessionLog(queryText, parsed.sessionLog, sessionLogCap);
 
 		const parts: string[] = [];
 		// Conventions: always injected, but capped at MAX_CONVENTIONS_BYTES
 		// (SEC-2 LOW defense-in-depth — the no-query path already bounds raw
 		// content at MAX_KNOWLEDGE_HEAD_BYTES; this mirrors that bound on the
 		// worker/query path where convention sections were previously uncapped).
+		// R1: the effective cap is the R1 knob when set (byte-identical defaults
+		// when unset).
+		const conventionsCap = knowledgeCap(MAX_CONVENTIONS_BYTES, maxBytes);
 		const conventionsBody = parsed.conventions.map((s) => s.body).join("\n");
-		if (conventionsBody.length > MAX_CONVENTIONS_BYTES) {
+		if (conventionsBody.length > conventionsCap) {
 			parts.push(
-				`${conventionsBody.slice(0, MAX_CONVENTIONS_BYTES)}\n\n<!-- ...[truncated] conventions section capped at ${MAX_CONVENTIONS_BYTES} bytes. Full file: ${p} — use \`read\`. -->`,
+				`${conventionsBody.slice(0, conventionsCap)}\n\n<!-- ...[truncated] conventions section capped at ${conventionsCap} bytes. Full file: ${p} — use \`read\`. -->`,
 			);
 		} else if (conventionsBody) {
 			parts.push(conventionsBody);
 		}
 		// Matched session-log (drop-whole, budget-capped).
 		for (const sec of matchedSessionLog) parts.push(sec.body);
-		// Always: section-index of ALL session-log headers (recovery safety net).
+		// Always: section-index of session-log headers (recovery safety net).
+		// R1.1: bounded to the last MAX_INDEX_ENTRIES headers plus a counter —
+		// see MAX_INDEX_ENTRIES doc for the growth-bug rationale. The counter
+		// line sits ABOVE the kept entries because the omitted ones are the
+		// earlier sections (keep-tail policy).
 		if (parsed.sessionLog.length > 0) {
-			const indexLines = parsed.sessionLog.map((s) => `  - ${s.header}`);
+			const omitted = parsed.sessionLog.length - MAX_INDEX_ENTRIES;
+			const indexLines = (omitted > 0 ? parsed.sessionLog.slice(-MAX_INDEX_ENTRIES) : parsed.sessionLog).map(
+				(s) => `  - ${s.header}`,
+			);
+			if (omitted > 0) {
+				indexLines.unshift(
+					`… ${omitted} earlier session-log sections omitted (index capped at ${MAX_INDEX_ENTRIES} most recent) — use \`read\` on the full file to browse them.`,
+				);
+			}
 			parts.push(
 				`<!-- Session-log sections in knowledge.md (not injected unless matched above — use \`read\` for detail):\n${indexLines.join("\n")}\nFull file: ${p} -->`,
 			);
 		}
-		return parts.join("\n").trim();
+		const joined = parts.join("\n").trim();
+		// R1.1 whole-block backstop (knob set ONLY): the knobbled query-path
+		// budgets (conventions N + session-log N) plus the no-query head budget
+		// (N) justify up to 3N of knowledge — but truncation notices and the
+		// section-index ride on top. When the FINAL joined block would exceed
+		// 3N bytes, cut the tail and point `read` at the file so the knob stays
+		// a true upper bound ("max bytes of knowledge per agent" × 3 paths).
+		// Unset = no whole-block cap (pre-R1.1 behavior; the per-path defaults
+		// already bound each part).
+		if (maxBytes !== undefined && joined.length > maxBytes * 3) {
+			const wholeBlockCap = maxBytes * 3;
+			return `${joined.slice(0, wholeBlockCap)}\n\n<!-- knowledge block truncated at ${wholeBlockCap} bytes (whole-block cap). Full file: ${p} — use the \`read\` tool. -->`;
+		}
+		return joined;
 	} catch {
 		return "";
 	}

package/src/extension/registration/lifecycle-handlers.ts

@@ -44,7 +44,9 @@ import { createSessionSnapshot } from "../../runtime/session-snapshot.ts";
 import { applyCrewSettingsTiersToConfig, loadCrewSettingsTiers, scheduledJobsHiddenCountOf } from "../../runtime/settings-store.ts";
 import type { ReconcileResult } from "../../runtime/stale-reconciler.ts";
 import { flushReapEscalationsSync } from "../../runtime/stale-reconciler.ts";
+import { prunePersistedSubagentRecords, resolveSubagentRecordTtlDays } from "../../runtime/subagent-manager.ts";
 import { ensureCoordinationPublicVerifyKey, getMailboxVerifyKeyPublic } from "../../state/coordination/mailbox.ts";
+import { sweepOrphanHealthSnapshots } from "../../state/stores/health-store.ts";
 import { loadRunManifestById, saveRunManifest } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest } from "../../state/types.ts";
 import { installInlinePanel } from "../../ui/inline-panel/index.ts";
@@ -52,6 +54,7 @@ import { clearSessionSwitchInFlight, markSessionSwitchInFlight } from "../../ui/
 import { registerPiCrewPowerbarSegments, resetPowerbarDedupState, updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
 import { updateCrewWidget } from "../../ui/widget/index.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
+import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
 import { extractBrokerSessionId } from "../../utils/session-utils.ts";
 import { getBrokerSocketPath } from "../../utils/socket-path.ts";
 import { startAsyncRunNotifier, stopAsyncRunNotifier } from "../async-notifier.ts";
@@ -508,6 +511,14 @@ async function runDeferredSessionCleanup(
 		logInternalError("register.sessionStart.reconcileStale", error);
 	}
 
+	// FIX 2 phase-2: wait for the observability init (kicked off synchronously
+	// in session_start) so the prunes below release metric labels on the LIVE
+	// registry — releasing on a fresh registry would be an empty no-op lie.
+	// Best-effort: an init failure (already logged by configureObservability)
+	// leaves metricRegistry undefined → prune simply skips label release.
+	await ctx.observabilityState.initPromise?.catch(() => {});
+	if (ctx.cleanedUp || ctx.sessionGeneration !== ownerGeneration) return; // session switched while we waited
+
 	// Auto-prune finished project-level run directories
 	try {
 		// DP-01: keep + age-floor are env-driven; the age floor means a run
@@ -515,6 +526,7 @@ async function runDeferredSessionCleanup(
 		const { removed } = pruneFinishedRuns(extensionCtx.cwd, resolveAutoPruneKeep(), {
 			ageFloorMs: resolveAutoPruneAgeFloorMs(),
 			intent: "session-start-auto",
+			metricRegistry: ctx.observabilityState.metricRegistry,
 		});
 		if (removed.length > 0) {
 			ctx.notifyOperator({
@@ -534,6 +546,7 @@ async function runDeferredSessionCleanup(
 		const { removed } = pruneUserLevelRuns(resolveAutoPruneKeep(), {
 			ageFloorMs: resolveAutoPruneAgeFloorMs(),
 			intent: "session-start-auto",
+			metricRegistry: ctx.observabilityState.metricRegistry,
 		});
 		if (removed.length > 0) {
 			ctx.notifyOperator({
@@ -547,6 +560,47 @@ async function runDeferredSessionCleanup(
 	} catch (error) {
 		logInternalError("register.sessionStart.autoPruneUser", error);
 	}
+
+	// FIX 1: sweep orphaned health snapshots — files under
+	// <crewRoot>/state/health/ whose run dir is already gone (left behind by
+	// pre-fix prunes; 2,322 files / 9.3 MB on the dev box at discovery).
+	// Conservative (exists-but-unreadable run dir → KEEP), bounded, never throws.
+	try {
+		for (const crewRoot of new Set([projectCrewRoot(extensionCtx.cwd), userCrewRoot()])) {
+			const { removed } = sweepOrphanHealthSnapshots(crewRoot);
+			if (removed.length > 0) {
+				ctx.notifyOperator({
+					id: `orphan_health_sweep`,
+					severity: "info",
+					source: "run-maintenance",
+					title: `Removed ${removed.length} orphaned health snapshot(s)`,
+					body: `Health snapshots whose runs were already pruned (under ${crewRoot}): ${removed
+						.slice(0, 10)
+						.join(", ")}${removed.length > 10 ? ", …" : ""}`,
+				});
+			}
+		}
+	} catch (error) {
+		logInternalError("register.sessionStart.sweepOrphanHealth", error);
+	}
+
+	// FIX 3: TTL-prune old TERMINAL subagent records (running/blocked/queued
+	// never touched — blocked drives blockedSignalFromSubagentDir; keep-50
+	// shield preserves recent history).
+	try {
+		const { removed } = prunePersistedSubagentRecords(extensionCtx.cwd);
+		if (removed.length > 0) {
+			ctx.notifyOperator({
+				id: `subagent_record_ttl_prune`,
+				severity: "info",
+				source: "run-maintenance",
+				title: `Pruned ${removed.length} old subagent record(s)`,
+				body: `Terminal subagent records past the ${resolveSubagentRecordTtlDays()}-day TTL (PI_CREW_SUBAGENT_RECORD_TTL_DAYS=0 disables).`,
+			});
+		}
+	} catch (error) {
+		logInternalError("register.sessionStart.pruneSubagentRecords", error);
+	}
 }
 
 /** Manifest keys the scheduler stamps for traceability. They are NOT declared

package/src/extension/run-maintenance.ts

@@ -2,7 +2,9 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_PATHS } from "../config/defaults.ts";
 import { getCrewEnv } from "../config/env-vars.ts";
+import type { MetricRegistry } from "../observability/metric-registry.ts";
 import { createCancellationToken } from "../runtime/process/cancellation-token.ts";
+import { removeHealthSnapshot } from "../state/stores/health-store.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
@@ -29,6 +31,12 @@ export interface PruneRunsOptions {
 	 *  0 disables the floor. Defaults to the PI_CREW_AUTO_PRUNE_AGE_FLOOR_HOURS
 	 *  value (24h) for auto-prune callers; manual prune passes 0 explicitly. */
 	ageFloorMs?: number;
+	/** FIX 2 phase-2: the LIVE MetricRegistry to release pruned runs' label
+	 *  series from. Callers pass the shared session registry (TeamContext /
+	 *  observabilityState.metricRegistry) — a second, fresh registry would hold
+	 * no labels and its release would be a silent no-op lie. Optional: callers
+	 * without a registry handle (tests) simply skip label release. */
+	metricRegistry?: MetricRegistry;
 }
 
 /**
@@ -270,6 +278,15 @@ export function pruneFinishedRuns(cwd: string, keep: number, options: PruneRunsO
 		}
 		fs.rmSync(run.stateRoot, { recursive: true, force: true });
 		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
+		// FIX 1: the run's health snapshot lives OUTSIDE stateRoot/artifactsRoot
+		// (<crewRoot>/state/health/<runId>.json) and was left orphaned forever.
+		// crewRoot derivation mirrors isSafeToPrune above.
+		const healthCrewRoot = run.stateRoot.startsWith(userCrewRoot() + path.sep) ? userCrewRoot() : projectCrewRoot(cwd);
+		removeHealthSnapshot(healthCrewRoot, run.runId);
+		// FIX 2 phase-2: a pruned run must stop pinning metric label series
+		// (cardinality) in the live registry. Missing registry = skip (see
+		// PruneRunsOptions.metricRegistry).
+		options.metricRegistry?.releaseLabels((l) => l.runId === run.runId);
 		// DP-01: preserve the reason of a pruned failed/blocked run in a durable
 		// index (the run dir that held it is gone now).
 		if (run.status === "failed" || run.status === "blocked") appendPrunedFailureIndex(cwd, run);
@@ -348,6 +365,9 @@ export function pruneUserLevelRuns(keep: number, options: PruneRunsOptions = {})
 				recursive: true,
 				force: true,
 			});
+			// FIX 1: ghost-run removal also orphans the health snapshot — remove it
+			// in the same breath (crewRoot here is always the user root).
+			removeHealthSnapshot(crewRoot, manifest.runId);
 			ghostRemoved.push(manifest.runId);
 			continue;
 		}
@@ -390,6 +410,11 @@ export function pruneUserLevelRuns(keep: number, options: PruneRunsOptions = {})
 		}
 		fs.rmSync(run.stateRoot, { recursive: true, force: true });
 		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
+		// FIX 1: user-level runs snapshot to <userCrewRoot>/state/health/ — remove
+		// it alongside the state/artifacts dirs (crewRoot is userCrewRoot() here).
+		removeHealthSnapshot(crewRoot, run.runId);
+		// FIX 2 phase-2: same label release as the project-level prune.
+		options.metricRegistry?.releaseLabels((l) => l.runId === run.runId);
 		// DP-01: preserve a pruned failed/blocked run's reason (the user-level
 		// index lives under the user crew root).
 		if (run.status === "failed" || run.status === "blocked") {

package/src/extension/team-tool/lifecycle-actions.ts

@@ -7,6 +7,7 @@ import { killProcessPid } from "../../runtime/child-pi/child-pi.ts";
 import { terminateLiveAgentsForRun } from "../../runtime/live-session/live-agent-manager.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { appendEvent, appendEventAsync } from "../../state/event-log/event-log.ts";
+import { removeHealthSnapshot } from "../../state/stores/health-store.ts";
 import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { projectCrewRoot, userCrewRoot, userPiRoot } from "../../utils/paths.ts";
@@ -220,6 +221,9 @@ export async function handlePrune(params: TeamToolParamsValue, ctx: TeamContext)
 		intent,
 		signal: ctx.signal,
 		dryRun,
+		// FIX 2 phase-2: release pruned runs' metric labels on the LIVE session
+		// registry (undefined in synthesized contexts → prune skips the release).
+		metricRegistry: ctx.metricRegistry,
 	});
 	// Fire hook once with all removed run IDs for batch visibility
 	if (pruned.removed.length > 0) {
@@ -352,6 +356,10 @@ export async function handleForget(params: TeamToolParamsValue, ctx: TeamContext
 	const resolvedArtifactsRoot = resolveRealContainedPath(crewRoot, loaded.manifest.artifactsRoot);
 	fs.rmSync(resolvedStateRoot, { recursive: true, force: true });
 	fs.rmSync(resolvedArtifactsRoot, { recursive: true, force: true });
+	// FIX 1: forget removes the run dir, so its health snapshot (which lives at
+	// <crewRoot>/state/health/<runId>.json, outside stateRoot) must go too or it
+	// orphans forever (2,322 orphans / 9.3 MB accumulated before this call).
+	removeHealthSnapshot(crewRoot, loaded.manifest.runId);
 	// FORGET-RESURRECT (observed 2026-08-04): the SIGTERM above is fire-and-forget
 	// (killProcessPid returns void; no await on process-group exit). A still-alive
 	// background runner/worker can land one final heartbeat write (15s interval)

package/src/observability/metric-registry.ts

@@ -1,5 +1,5 @@
 import { logInternalError } from "../utils/internal-error.ts";
-import { Counter, Gauge, Histogram, type Metric, type MetricSnapshot } from "./metrics-primitives.ts";
+import { Counter, Gauge, Histogram, type Metric, type MetricLabels, type MetricSnapshot } from "./metrics-primitives.ts";
 
 const METRIC_NAME_PATTERN = /^crew\.[a-z]+\.[a-z][a-z_]*$/;
 
@@ -90,6 +90,19 @@ export class MetricRegistry {
 		return [...this.metrics.values()].map((metric) => metric.snapshot());
 	}
 
+	/**
+	 * LABEL-GC: release stored label values matching `predicate` across every
+	 * registered metric; returns the total number of series dropped. Dispatches
+	 * polymorphically to {@link Metric.releaseLabelValues}, so Histograms (not
+	 * run-scoped) are untouched and no private Map is reached into from here.
+	 * A release is not an eviction — `cardinalityEvictions` is unaffected.
+	 */
+	releaseLabels(predicate: (labels: MetricLabels) => boolean): number {
+		let released = 0;
+		for (const metric of this.metrics.values()) released += metric.releaseLabelValues(predicate);
+		return released;
+	}
+
 	dispose(): void {
 		this.metrics.clear();
 	}

package/src/observability/metrics-primitives.ts

@@ -108,6 +108,18 @@ export abstract class Metric {
 	}
 
 	abstract snapshot(): MetricSnapshot;
+
+	/**
+	 * LABEL-GC: drop every stored label value whose labels match `predicate`;
+	 * returns the number of series dropped. Default is a no-op — only the
+	 * run-scoped value metrics (Counter/Gauge) override it. A deliberate
+	 * release is NOT a cardinality eviction ({@link cardinalityEvictions} is
+	 * reserved for MAX_LABEL_COMBINATIONS overflow) — the series is dropped
+	 * because it can no longer occur, not because the cap was hit.
+	 */
+	releaseLabelValues(_predicate: (labels: MetricLabels) => boolean): number {
+		return 0;
+	}
 }
 
 export class Counter extends Metric {
@@ -134,6 +146,22 @@ export class Counter extends Metric {
 		return this.values.get(labelKey(labels))?.value ?? 0;
 	}
 
+	/**
+	 * LABEL-GC: delete stored series whose labels match `predicate`.
+	 * `cardinalityEvictions` is deliberately NOT touched — a run-scoped series
+	 * is released because its run stopped being active, not because the
+	 * MAX_LABEL_COMBINATIONS FIFO cap evicted it.
+	 */
+	releaseLabelValues(predicate: (labels: MetricLabels) => boolean): number {
+		let dropped = 0;
+		for (const [key, entry] of this.values) {
+			if (!predicate(entry.labels)) continue;
+			this.values.delete(key);
+			dropped += 1;
+		}
+		return dropped;
+	}
+
 	snapshot(): MetricSnapshot {
 		return {
 			type: "counter",
@@ -168,6 +196,18 @@ export class Gauge extends Metric {
 		return this.values.get(labelKey(labels))?.value ?? 0;
 	}
 
+	/** LABEL-GC: see {@link Counter.releaseLabelValues} — Gauge shares the same
+	 *  semantics (series released by predicate, eviction counter untouched). */
+	releaseLabelValues(predicate: (labels: MetricLabels) => boolean): number {
+		let dropped = 0;
+		for (const [key, entry] of this.values) {
+			if (!predicate(entry.labels)) continue;
+			this.values.delete(key);
+			dropped += 1;
+		}
+		return dropped;
+	}
+
 	snapshot(): MetricSnapshot {
 		return {
 			type: "gauge",