pi-crew 0.9.64 → 0.9.66

package/src/runtime/scratchpad/snapshot-hmac.ts

@@ -0,0 +1,161 @@
+/**
+ * Snapshot HMAC helper — opt-in integrity for scratchpad snapshots.
+ *
+ * Closes the E.2 gap declared in docs/improvement-plan-2026-08-09.md and
+ * docs/runtime/scratchpad/README.md:120 ("v8.deserialize of restore content
+ * is unauthenticated (no HMAC)"). The threat model — a same-uid attacker
+ * plants a crafted V8 blob at the snapshot path to run deserialize gadgets
+ * in the guest — does not cross the existing same-uid boundary, but HMAC
+ * hardening is required before snapshots ever land in a shared/networked
+ * store.
+ *
+ * Migration window (see docs/decisions/2026-08-10-scratchpad-snapshot-hmac.md):
+ *
+ *   Phase 1 (this module): HMAC sign-on-write + verify-on-read are OPT-IN
+ *     via PI_CREW_SNAPSHOT_HMAC_KEY. When the key is unset, behaviour is
+ *     unchanged (snapshots remain unsigned). When the key is set, writes
+ *     attach a signature and reads verify it; an unsigned/failed snapshot
+ *     is ACCEPTED with a warning so existing snapshots remain readable.
+ *   Phase 2 (after one release): unsigned snapshots are REJECTED when the
+ *     key is set (configurable via PI_CREW_SNAPSHOT_HMAC_STRICT=1).
+ *   Phase 3 (after snapshots move to a shared store): the key becomes
+ *     required and unsigned snapshots are always rejected.
+ *
+ * Wire-up into the actual write/read paths is intentionally deferred to a
+ * follow-up that audits the snapshot envelope format (V8 base64 vs raw
+ * bytes) and the writeArtifact redaction interaction. See ADR for the plan.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Env var holding the HMAC secret. When unset, HMAC is disabled (Phase 0
+ * behaviour — snapshots unsigned). When set, sign-on-write and
+ * verify-on-read are enabled.
+ */
+export const SNAPSHOT_HMAC_KEY_ENV = "PI_CREW_SNAPSHOT_HMAC_KEY";
+
+/**
+ * Opt-in strict mode (Phase 2): when the key is set AND this is "1",
+ * unsigned or signature-mismatched snapshots are REJECTED on read instead
+ * of accepted with a warning.
+ */
+export const SNAPSHOT_HMAC_STRICT_ENV = "PI_CREW_SNAPSHOT_HMAC_STRICT";
+
+/**
+ * Header prefix for an inline signature. When snapshots are signed, the
+ * signature is prepended to the blob as `PI_CREW_SIG=<hex>\n` so a single
+ * read yields both the signature and the payload. (Sidecar files would
+ * require writeArtifact coordination that the envelope format does not
+ * currently support.)
+ */
+export const SNAPSHOT_SIG_PREFIX = "PI_CREW_SIG=";
+
+export function getSnapshotHmacKey(env: NodeJS.ProcessEnv = process.env): Buffer | undefined {
+	const raw = env[SNAPSHOT_HMAC_KEY_ENV];
+	if (!raw) return undefined;
+	// Accept hex-encoded keys directly; otherwise encode the string as utf8.
+	// A key shorter than 32 bytes is rejected to prevent trivial brute-force.
+	const buf = /^[0-9a-fA-F]+$/.test(raw) && raw.length % 2 === 0 ? Buffer.from(raw, "hex") : Buffer.from(raw, "utf8");
+	if (buf.length < 32) {
+		throw new Error(
+			`${SNAPSHOT_HMAC_KEY_ENV} must be at least 32 bytes (got ${buf.length}); use a longer key or generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`,
+		);
+	}
+	return buf;
+}
+
+export function isSnapshotHmacStrict(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env[SNAPSHOT_HMAC_STRICT_ENV] === "1" || env[SNAPSHOT_HMAC_STRICT_ENV] === "true";
+}
+
+/**
+ * Compute the HMAC-SHA256 signature of `content` under `key`. Returns a
+ * lowercase hex string.
+ */
+export function signSnapshot(content: Buffer | string, key: Buffer): string {
+	return createHmac("sha256", key).update(content).digest("hex");
+}
+
+/**
+ * Constant-time signature comparison. Both signatures must be lowercase
+ * hex of the same length; anything else returns false without throwing.
+ */
+export function snapshotSignatureMatches(content: Buffer | string, signature: string, key: Buffer): boolean {
+	const expected = signSnapshot(content, key);
+	const a = Buffer.from(expected);
+	const b = Buffer.from(signature);
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(a, b);
+}
+
+/**
+ * Outcome of {@link verifySnapshotPayload}. Callers decide how to react
+ * based on the strict-mode flag.
+ */
+export type SnapshotVerifyOutcome =
+	| { kind: "unsigned"; strict: boolean }
+	| { kind: "verified" }
+	| { kind: "mismatch"; strict: boolean }
+	| { kind: "hmac-disabled" };
+
+/**
+ * Verify a snapshot payload that may or may not carry an inline signature.
+ *
+ * @param payload The raw bytes read from disk (possibly including the
+ *   `PI_CREW_SIG=<hex>\n` prefix).
+ * @param key The HMAC key, or `undefined` when HMAC is disabled.
+ * @param strict When true, unsigned/mismatched payloads are reported as
+ *   rejectable. When false (the Phase 1 default), the caller is expected
+ *   to accept the payload with a warning.
+ */
+export function verifySnapshotPayload(payload: Buffer, key: Buffer | undefined, strict: boolean): SnapshotVerifyOutcome {
+	if (!key) return { kind: "hmac-disabled" };
+	const prefixStr = SNAPSHOT_SIG_PREFIX;
+	if (payload.length < prefixStr.length + 1 || payload.subarray(0, prefixStr.length).toString("utf8") !== prefixStr) {
+		return { kind: "unsigned", strict };
+	}
+	const newlineIdx = payload.indexOf(0x0a, prefixStr.length);
+	if (newlineIdx < 0) return { kind: "unsigned", strict };
+	const sigHex = payload.subarray(prefixStr.length, newlineIdx).toString("utf8");
+	const body = payload.subarray(newlineIdx + 1);
+	return snapshotSignatureMatches(body, sigHex, key) ? { kind: "verified" } : { kind: "mismatch", strict };
+}
+
+/**
+ * Strip the inline signature prefix and return the bare payload. Returns
+ * the original buffer when no prefix is present. Used by read paths that
+ * have already called {@link verifySnapshotPayload} and decided to accept.
+ */
+export function stripSnapshotSignature(payload: Buffer): Buffer {
+	if (payload.length < SNAPSHOT_SIG_PREFIX.length) return payload;
+	if (payload.subarray(0, SNAPSHOT_SIG_PREFIX.length).toString("utf8") !== SNAPSHOT_SIG_PREFIX) return payload;
+	const newlineIdx = payload.indexOf(0x0a, SNAPSHOT_SIG_PREFIX.length);
+	if (newlineIdx < 0) return payload;
+	return payload.subarray(newlineIdx + 1);
+}
+
+/**
+ * Attach an inline signature to a payload. Returns a new buffer shaped as
+ * `PI_CREW_SIG=<hex>\n<payload>`. Used by write paths that have HMAC
+ * enabled.
+ */
+export function attachSnapshotSignature(payload: Buffer, key: Buffer): Buffer {
+	const sig = signSnapshot(payload, key);
+	return Buffer.concat([Buffer.from(`${SNAPSHOT_SIG_PREFIX}${sig}\n`, "utf8"), payload]);
+}
+
+/**
+ * Should the caller reject the snapshot based on the verify outcome?
+ * Centralises the strict-vs-migration decision so callers stay simple.
+ */
+export function shouldRejectSnapshot(outcome: SnapshotVerifyOutcome): boolean {
+	switch (outcome.kind) {
+		case "hmac-disabled":
+			return false;
+		case "verified":
+			return false;
+		case "unsigned":
+		case "mismatch":
+			return outcome.strict;
+	}
+}

package/src/runtime/team-runner.ts

@@ -1,15 +1,15 @@
+import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { AgentConfig } from "../agents/agent-config.ts";
 import type { CrewLimitsConfig, CrewReliabilityConfig, CrewRuntimeConfig } from "../config/config.ts";
 import { CrewError, ErrorCode } from "../errors.ts";
 import { appendHookEvent, executeHook } from "../hooks/registry.ts";
 import { childCorrelation, withCorrelation } from "../observability/correlation.ts";
 import type { MetricRegistry } from "../observability/metric-registry.ts";
-import { PluginRegistry } from "../plugins/plugin-registry.ts";
-import { NextJsPlugin, VitePlugin, VitestPlugin } from "../plugins/plugins/index.ts";
 import { atomicWriteFile, flushPendingAtomicWrites } from "../state/atomic-write.ts";
-import { canTransitionRunStatus, TEAM_TASK_STATUSES, TEAM_TERMINAL_TASK_STATUSES, type TeamTaskStatus } from "../state/contracts.ts";
+import { canTransitionRunStatus } from "../state/contracts.ts";
 import { withRunLock } from "../state/coordination/locks.ts";
 import {
 	appendEvent,
@@ -35,6 +35,7 @@ import { effectivenessPolicyDecision, evaluateRunEffectiveness, formatRunEffecti
 import { applyGoalAchievement, assessGoalAchievement } from "./goal-workflow/goal-achievement.ts";
 import { deliverGroupJoin, resolveGroupJoinMode } from "./group-join.ts";
 import { terminateLiveAgentsForRun } from "./live-session/live-agent-manager.ts";
+import { isNonTerminalTaskStatus, mergeTaskUpdatesPreservingTerminal } from "./merge-gate.ts";
 import { resolveTaskRuntimeKind } from "./model/runtime-policy.ts";
 import type { CrewRuntimeCapabilities } from "./model/runtime-resolver.ts";
 import { filterReadyByWriteOverlap } from "./path-overlap.ts";
@@ -70,16 +71,6 @@ import {
 	type WorkflowStateMachine,
 } from "./workflow-state.ts";
 
-// Built-in plugin registry for framework awareness.
-// NOTE: This registry is registered here for future use. The integration
-// point (reading package.json deps, computing active plugin context, and
-// passing it into RunConfig / task-runner) is not yet implemented; see
-// `getPluginContext` in src/plugins/plugin-context.ts (planned).
-const builtInRegistry = new PluginRegistry();
-builtInRegistry.register(NextJsPlugin);
-builtInRegistry.register(VitestPlugin);
-builtInRegistry.register(VitePlugin);
-
 /**
  * Start a periodic heartbeat for the team-level run.
  *
@@ -128,6 +119,113 @@ function startTeamRunHeartbeat(stateRoot: string, runId: string): () => void {
 	return () => clearInterval(interval);
 }
 
+// ─── Perf observability (auto-attach, toggle per team) ─────────────────────
+// "Bộ đo luôn hoạt động khi pi-crew chạy": unless the team frontmatter says
+// `observability: false`, every run spawns the external resource sampler
+// (scripts/resource-sampler.mjs --watch-run — auto-resolves the runner PID
+// from state and auto-stops when the runner dies) and, after completion,
+// runs analyze-run to emit the perf report. Both are detached child
+// processes so a failure in the tooling never affects the run itself.
+const OBSERVABILITY_INTERVAL_MS = 2000;
+const OBSERVABILITY_ANALYZE_DELAY_MS = 3000;
+
+function perfScriptPath(scriptName: string): string | undefined {
+	try {
+		// Two layouts: dev (src/runtime/team-runner.ts → ../../scripts) and
+		// bundled (dist/index.mjs → ../scripts). Try both, use whichever exists.
+		const candidates = [
+			fileURLToPath(new URL(`../../scripts/${scriptName}`, import.meta.url)),
+			fileURLToPath(new URL(`../scripts/${scriptName}`, import.meta.url)),
+		];
+		return candidates.find((p) => fs.existsSync(p));
+	} catch {
+		return undefined;
+	}
+}
+
+function startPerfSampler(manifest: TeamRunManifest, team: TeamConfig): void {
+	// DIRECT fs marker (console may be swallowed by the host) — every branch
+	// writes artifacts/<runId>/perf-obs.log with the exact reason.
+	const marker = (msg: string): void => {
+		try {
+			fs.appendFileSync(path.join(manifest.artifactsRoot, "perf-obs.log"), `[${new Date().toISOString()}] ${msg}\n`);
+		} catch {
+			/* best-effort */
+		}
+	};
+	marker(`startPerfSampler entered (team=${team.name} observability=${String(team.observability)} importMetaUrl=${import.meta.url})`);
+	// Strict true: parsed team files default observability to true (parseTeamFile),
+	// while direct-object TeamConfig fixtures (unit tests) stay undefined and
+	// therefore do NOT spawn the sampler — keeps test isolation.
+	if (team.observability !== true) {
+		marker(`SKIP: observability=${String(team.observability)} !== true`);
+		return;
+	}
+	const samplerPath = perfScriptPath("resource-sampler.mjs");
+	if (!samplerPath) {
+		marker(`SKIP: resource-sampler.mjs not found (importMetaUrl=${import.meta.url})`);
+		return;
+	}
+	marker(`spawning sampler from ${samplerPath}`);
+	const crewRoot = path.dirname(path.dirname(path.dirname(manifest.stateRoot)));
+	const outPath = path.join(manifest.artifactsRoot, "resources.jsonl");
+	const logPath = path.join(manifest.artifactsRoot, "perf-obs.log");
+	try {
+		const child = spawn(
+			process.execPath,
+			[
+				"--experimental-strip-types",
+				samplerPath,
+				"--watch-run",
+				manifest.runId,
+				"--crew-root",
+				crewRoot,
+				"--interval",
+				String(OBSERVABILITY_INTERVAL_MS),
+				"--out",
+				outPath,
+			],
+			{ detached: true, stdio: ["ignore", "ignore", "pipe"] },
+		);
+		// diagnostics: sampler stderr → perf-obs.log (best-effort; never affects the run)
+		child.stderr?.on("data", (d: Buffer) => {
+			try {
+				fs.appendFileSync(logPath, String(d));
+			} catch {
+				/* best-effort */
+			}
+		});
+		child.unref();
+	} catch (err) {
+		console.warn(`[perf-obs] sampler spawn failed for ${manifest.runId}: ${String(err)}`);
+	}
+}
+
+function schedulePerfAnalyze(manifest: TeamRunManifest, team: TeamConfig): void {
+	// Strict true — same test-isolation rationale as startPerfSampler.
+	if (team.observability !== true) return;
+	const analyzePath = perfScriptPath("analyze-run.mjs");
+	const resourcesPath = path.join(manifest.artifactsRoot, "resources.jsonl");
+	// Only analyze when the sampler actually produced data (sampler may have
+	// been skipped/failed to spawn) AND the scripts exist.
+	if (!analyzePath || !fs.existsSync(resourcesPath)) return;
+	const crewRoot = path.dirname(path.dirname(path.dirname(manifest.stateRoot)));
+	// Delay so child-worker transcripts are fully flushed before analyze reads them.
+	const timer = setTimeout(() => {
+		try {
+			const child = spawn(
+				process.execPath,
+				["--experimental-strip-types", analyzePath, manifest.runId, "--crew-root", crewRoot, "--resources", resourcesPath],
+				{ detached: true, stdio: "ignore" },
+			);
+			child.unref();
+		} catch (err) {
+			console.warn(`[perf-obs] analyze spawn failed for ${manifest.runId}: ${String(err)}`);
+		}
+	}, OBSERVABILITY_ANALYZE_DELAY_MS);
+	timer.unref();
+}
+
 export interface ExecuteTeamRunInput {
 	manifest: TeamRunManifest;
 	tasks: TeamTaskState[];
@@ -241,9 +339,12 @@ function markBlocked(tasks: TeamTaskState[], reason: string): TeamTaskState[] {
 	);
 }
 
-function isNonTerminalTaskStatus(status: TeamTaskState["status"]): boolean {
-	return status === "queued" || status === "running" || status === "waiting";
-}
+// isNonTerminalTaskStatus, safeFinishedAt, isMalformedFinishedAtReplacement,
+// statusMergeKey, REJECTED_STATUS_MERGE_TRANSITIONS, shouldMergeTaskUpdate,
+// __test__shouldMergeTaskUpdate, mergeTaskUpdatesPreservingTerminal,
+// __test__mergeTaskUpdates — moved to ./merge-gate.ts (2026-08-10
+// improvement-plan Tier 2 team-runner split, self-contained portion).
+// Re-imported below to preserve all in-file callers.
 
 /**
  * CORE-6: Unified cancel/fail of non-terminal tasks. Replaces hand-rolled
@@ -281,193 +382,6 @@ export function cancelNonTerminalTasks(
 	});
 }
 
-/**
- * Returns the finishedAt timestamp as a number, or Infinity for invalid/malformed dates.
- * This makes comparison logic in shouldMergeTaskUpdate more readable by abstracting
- * the NaN handling into a single well-named function.
- */
-function safeFinishedAt(task: TeamTaskState): number {
-	if (!task.finishedAt) return -Infinity;
-	const ms = new Date(task.finishedAt).getTime();
-	return Number.isNaN(ms) ? Infinity : ms;
-}
-
-/**
- * Returns true when the current task has a malformed finishedAt (NaN/Infinity)
- * and the updated task has a valid finite finishedAt. Malformed finishedAt
- * should be replaced rather than persisting corruption.
- */
-function isMalformedFinishedAtReplacement(currentTime: number, updatedTime: number): boolean {
-	return !Number.isFinite(currentTime) && Number.isFinite(updatedTime);
-}
-
-/**
- * RT-16: status-level gate for shouldMergeTaskUpdate. Returns the stable
- * "from->to" key used by REJECTED_STATUS_MERGE_TRANSITIONS.
- */
-function statusMergeKey(from: TeamTaskStatus, to: TeamTaskStatus): string {
-	return `${from}->${to}`;
-}
-
-/**
- * RT-16 — derived merge-gate transition table.
- *
- * The set of old->new status pairs that shouldMergeTaskUpdate must REJECT based
- * solely on the status transition (before any field-level comparison). It
- * replaces the former 13 hand-written status guards that hand-duplicated the
- * lifecycle table. Built once from the single source-of-truth table
- * (TEAM_TASK_STATUSES + TEAM_TERMINAL_TASK_STATUSES — the terminal half of
- * TEAM_TASK_STATUS_TRANSITIONS) plus two merge-specific policies that are
- * STRICTER than the lifecycle table on the parallel-merge path:
- *
- *  P1 Terminal preservation — every terminal->non-terminal pair is rejected.
- *    The lifecycle table permits retries (e.g. completed->queued), but a stale
- *    worker snapshot must never resurrect a settled task.
- *  P2 Completed integrity — five terminal->terminal flips that touch the
- *    "completed" success terminal are rejected: completed->failed,
- *    completed->needs_attention, failed->completed, cancelled->completed,
- *    needs_attention->completed. (completed may still move to
- *    cancelled/skipped; that is intentionally allowed, so these are NOT simply
- *    "every illegal terminal->terminal flip".)
- *  P3 waiting->running regression — the single stale-snapshot case.
- *
- * The decision for every old->new pair is byte-for-byte identical to the former
- * 7 status guards (verified exhaustively in
- * test/unit/team-runner-should-merge-table.test.ts).
- */
-const REJECTED_STATUS_MERGE_TRANSITIONS: ReadonlySet<string> = (() => {
-	const rejected = new Set<string>();
-	// P1 — terminal preservation: reject every terminal->non-terminal pair.
-	for (const from of TEAM_TASK_STATUSES) {
-		if (!TEAM_TERMINAL_TASK_STATUSES.has(from)) continue;
-		for (const to of TEAM_TASK_STATUSES) {
-			if (!TEAM_TERMINAL_TASK_STATUSES.has(to)) rejected.add(statusMergeKey(from, to));
-		}
-	}
-	// P3 — waiting->running stale-snapshot regression.
-	rejected.add(statusMergeKey("waiting", "running"));
-	// P2 — completed integrity flips (bespoke terminal->terminal policy).
-	const completedIntegrityFlips: ReadonlyArray<[TeamTaskStatus, TeamTaskStatus]> = [
-		["completed", "failed"],
-		["completed", "needs_attention"],
-		["failed", "completed"],
-		["cancelled", "completed"],
-		["needs_attention", "completed"],
-	];
-	for (const [from, to] of completedIntegrityFlips) rejected.add(statusMergeKey(from, to));
-	return rejected;
-})();
-
-function shouldMergeTaskUpdate(current: TeamTaskState, updated: TeamTaskState): boolean {
-	// RT-16: status-level gate — reject stale/dangerous transitions via the
-	// derived transition table (REJECTED_STATUS_MERGE_TRANSITIONS) instead of
-	// hand-written guards. Parallel workers receive the same input snapshot; a
-	// later result may still carry stale copies. The table encodes three
-	// merge-specific policies stricter than the lifecycle table: terminal
-	// preservation (no terminal->non-terminal resurrection), completed integrity
-	// (no flipping the "completed" success terminal to/from failed or
-	// needs_attention), and the waiting->running stale-snapshot regression.
-	if (REJECTED_STATUS_MERGE_TRANSITIONS.has(statusMergeKey(current.status, updated.status))) return false;
-	// Guard: when current is "running" but has resultArtifact (another worker already
-	// completed it), a stale updated with status="running" and no resultArtifact
-	// must not overwrite the actual completed state.
-	if (current.status === updated.status && updated.status === "running" && current.resultArtifact && !updated.resultArtifact)
-		return false;
-	// Guard: when current is "completed" and has resultArtifact but updated is also
-	// "completed" without resultArtifact, block the stale update from overwriting
-	// a task that successfully produced output.
-	if (current.status === updated.status && current.status === "completed" && current.resultArtifact && !updated.resultArtifact)
-		return false;
-	// Prevent a stale completed task from overwriting a fresher one.
-	// Restructure to handle undefined current.finishedAt as a special case:
-	// - undefined current + valid updated: allow the update
-	// - valid current + undefined updated: block the update (don't lose completion time)
-	// - both undefined: finishedAt guard does not apply, fall through to heartbeat check
-	// - both valid: compare timestamps as before
-	if (current.finishedAt !== undefined && updated.finishedAt !== undefined) {
-		const currentTime = safeFinishedAt(current);
-		const updatedTime = safeFinishedAt(updated);
-		// Malformed finishedAt (NaN) is treated as Infinity — invalid state should be
-		// replaced rather than persisting corruption. Log warning for visibility.
-		if (!Number.isFinite(currentTime)) {
-			console.warn(`[team-runner] Task ${current.id} has malformed finishedAt: ${current.finishedAt}`);
-		}
-		if (isMalformedFinishedAtReplacement(currentTime, updatedTime)) {
-			return true;
-		}
-		if (updatedTime < currentTime) return false;
-	}
-	// Block if updated is trying to establish a terminal status without a finishedAt
-	// timestamp. Heartbeat-only updates (status='running', no finishedAt) are
-	// allowed if heartbeat has changed (checked separately in hasMeaningfulUpdate).
-	if (!updated.finishedAt && !isNonTerminalTaskStatus(updated.status)) return false;
-	// Explicitly enumerate all fields that constitute a meaningful update so that
-	// adding a new important field requires updating this list (rather than silently
-	// losing data if a field is forgotten in the boolean OR chain below).
-	const hasMeaningfulUpdate =
-		updated.status !== current.status ||
-		updated.finishedAt !== current.finishedAt ||
-		updated.startedAt !== current.startedAt ||
-		Boolean(updated.resultArtifact) !== Boolean(current.resultArtifact) ||
-		(Boolean(updated.resultArtifact) && updated.resultArtifact !== current.resultArtifact) ||
-		Boolean(updated.error) ||
-		Boolean(updated.modelAttempts?.length) ||
-		Boolean(updated.usage) ||
-		Boolean(updated.attempts?.length) ||
-		updated.heartbeat?.lastSeenAt !== current.heartbeat?.lastSeenAt ||
-		updated.jsonEvents !== current.jsonEvents ||
-		updated.agentProgress?.lastActivityAt !== current.agentProgress?.lastActivityAt;
-	return hasMeaningfulUpdate;
-}
-/** Exposed for the exhaustive status-merge table test (RT-16). */
-export const __test__shouldMergeTaskUpdate = shouldMergeTaskUpdate;
-
-// H4 fix: rename to descriptive name. Kept __test__ as alias for backward
-// compat test imports.
-// FIX (perf P10): replace O(N×M) .find() + .map() inside nested loops with a
-// single-pass Map-based merge. Build an index of `merged` once, then for each
-// incoming updated task do O(1) lookup; the final pass reassembles `merged`
-// preserving original order. For a 20-task run × 5-batch merger with
-// ~10 updates per result, this reduces from O(50×20) = 1000 ops to O(120).
-// Behavior is unchanged: skipped updates (shouldMergeTaskUpdate=false) still
-// leave the existing task in place.
-export function mergeTaskUpdatesPreservingTerminal(base: TeamTaskState[], results: Array<{ tasks: TeamTaskState[] }>): TeamTaskState[] {
-	// Index current merged state by id for O(1) lookup during the merge pass.
-	const indexById = new Map<string, TeamTaskState>();
-	for (const task of base) indexById.set(task.id, task);
-
-	let skipped = 0;
-	for (const result of results) {
-		for (const updated of result.tasks) {
-			const current = indexById.get(updated.id);
-			if (!current) continue;
-			if (!shouldMergeTaskUpdate(current, updated)) {
-				// Log skipped merges for visibility into rejected parallel updates.
-				// In distributed systems with parallel workers, rejected merges may
-				// indicate bugs (wrong status, timestamp corruption) if they accumulate.
-				console.debug("[team-runner] Skipping stale merge for task", updated.id, {
-					currentStatus: current.status,
-					updatedStatus: updated.status,
-					currentFinishedAt: current.finishedAt,
-					updatedFinishedAt: updated.finishedAt,
-				});
-				skipped += 1;
-				continue;
-			}
-			indexById.set(updated.id, updated);
-		}
-	}
-	// Reassemble in original `base` order so downstream snapshots stay stable.
-	const merged = base.map((task) => indexById.get(task.id) ?? task);
-	// `skipped` is intentional visibility — currently no caller reads it but
-	// we'd rather leave the count available for future instrumentation than
-	// remove the cumulative silent-rejection signal it provides.
-	void skipped;
-	return refreshTaskGraphQueues(merged);
-}
-/** @deprecated Use mergeTaskUpdatesPreservingTerminal. Kept for backward test import compat. */
-export const __test__mergeTaskUpdates = mergeTaskUpdatesPreservingTerminal;
-
 // 2.8: adaptive-plan parsing/repair/injection moved to src/runtime/goal-workflow/adaptive-plan.ts.
 // Re-export the test-only helpers so existing test imports still resolve.
 export {
@@ -475,6 +389,10 @@ export {
 	__test__repairAdaptivePlan,
 } from "./goal-workflow/adaptive-plan.ts";
 
+// Merge-gate extracted to ./merge-gate.ts (2026-08-10 improvement-plan Tier 2).
+// Re-export the test-only helpers so existing test imports still resolve.
+export { __test__mergeTaskUpdates, __test__shouldMergeTaskUpdate } from "./merge-gate.ts";
+
 import { injectAdaptivePlanIfReady } from "./goal-workflow/adaptive-plan.ts";
 
 function formatTaskProgress(task: TeamTaskState): string {
@@ -912,6 +830,10 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 	// heartbeats; the team-level run had no heartbeat, so any multi-phase
 	// workflow lasting >5min was marked stale and cancelled.
 	const stopTeamHeartbeat = startTeamRunHeartbeat(manifest.stateRoot, manifest.runId);
+	// Perf observability: auto-attach the resource sampler for this run (toggle:
+	// team frontmatter `observability: false`). Detached + unref'd — the sampler
+	// auto-stops when the runner dies, so no explicit cleanup needed.
+	startPerfSampler(manifest, input.team);
 
 	const cleanupUsage = (): void => {
 		for (const task of input.tasks) clearTrackedTaskUsage(task.id);
@@ -994,6 +916,9 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		// this single flush at run-end coalesces any pending progress bursts
 		// before manifest updates are observed by readers.
 		await flushEventLogBuffer();
+		// Perf observability: emit the post-run perf report (detached, delayed so
+		// child transcripts are flushed). Never affects run outcome.
+		schedulePerfAnalyze(manifest, input.team);
 		return result;
 	} catch (error) {
 		// Round 27 (BUG 1): the success path calls stopTeamHeartbeat() but this

package/src/schema/team-tool-schema.ts

@@ -268,10 +268,12 @@ const sharedFields = {
 		}),
 	),
 	budgetTotal: Type.Optional(
+		// Empty-string unset marker accepted (Tier-9: models emit "" when unset).
 		// 0 accepted as "unset/disabled" (models emit 0 for off); still rejects 1-999
 		// as the MISCONFIGURATION GUARD against typo'd silent-abort configs.
 		Type.Union(
 			[
+				Type.Literal(""),
 				Type.Literal(0),
 				Type.Number({
 					minimum: 1000,

package/src/teams/discover-teams.ts

@@ -111,6 +111,8 @@ function parseTeamFile(filePath: string, source: ResourceSource): TeamConfig | u
 			defaultWorkflow: frontmatter.defaultWorkflow || frontmatter.workflow || undefined,
 			workspaceMode: frontmatter.workspaceMode?.trim() === "worktree" ? "worktree" : "single",
 			maxConcurrency: frontmatter.maxConcurrency ? Number.parseInt(frontmatter.maxConcurrency, 10) : undefined,
+			// observability defaults ON ("luôn hoạt động"); explicit `observability: false` disables.
+			observability: frontmatter.observability === undefined ? true : frontmatter.observability !== "false",
 			routing: triggers || useWhen || avoidWhen || cost || category ? { triggers, useWhen, avoidWhen, cost, category } : undefined,
 		};
 	} catch {

package/src/teams/team-config.ts

@@ -23,6 +23,13 @@ export interface TeamConfig {
 	defaultWorkflow?: string;
 	workspaceMode?: "single" | "worktree";
 	maxConcurrency?: number;
+	/**
+	 * Perf observability: when true (default), the run auto-attaches the
+	 * resource sampler (scripts/resource-sampler.mjs --watch-run) and runs
+	 * analyze-run after completion. Set `observability: false` in the team
+	 * frontmatter to disable.
+	 */
+	observability?: boolean;
 	routing?: RoutingMetadata;
 	/**
 	 * Optional git-based source URL when this team config is sourced from a remote URL.

package/src/teams/team-serializer.ts

@@ -24,6 +24,7 @@ export function serializeTeam(team: TeamConfig): string {
 		team.defaultWorkflow ? `defaultWorkflow: ${team.defaultWorkflow}` : undefined,
 		team.workspaceMode ? `workspaceMode: ${team.workspaceMode}` : undefined,
 		team.maxConcurrency !== undefined ? `maxConcurrency: ${team.maxConcurrency}` : undefined,
+		team.observability !== undefined ? `observability: ${team.observability}` : undefined,
 		line("triggers", team.routing?.triggers),
 		line("useWhen", team.routing?.useWhen),
 		line("avoidWhen", team.routing?.avoidWhen),

package/src/ui/mascot.ts

@@ -99,7 +99,6 @@ export class AnimatedMascot {
 	private currentArminGrid: string[][];
 	private effectState: EffectState = {};
 	private effectDone = false;
-	private visible = true;
 	private frame = 0;
 	private effectPhase = 0;
 	private gridVersion = 0;
@@ -200,10 +199,7 @@ export class AnimatedMascot {
 			this.gridVersion++;
 		}
 		this.invalidate();
-		// Only request a re-render when the mascot is visible (not obscured by
-		// another overlay such as the dashboard or live sidebar).  This avoids
-		// pointless repaints on every animation frame while hidden.
-		if (this.visible) this.requestRender?.();
+		this.requestRender?.();
 	}
 
 	private tickArminEffect(): boolean {
@@ -432,15 +428,6 @@ export class AnimatedMascot {
 		}
 	}
 
-	/**
-	 * Set whether the mascot is currently visible (not obscured by another
-	 * overlay).  When invisible, tick() skips requestRender so the animation
-	 * does not trigger needless repaints while hidden.
-	 */
-	setVisible(visible: boolean): void {
-		this.visible = visible;
-	}
-
 	dispose(): void {
 		this.doneGuard.called = true;
 		if (this.interval) clearInterval(this.interval);

package/teams/default.team.md

@@ -1,5 +1,6 @@
 ---
 name: default
+observability: true
 description: Balanced team for ordinary implementation tasks
 defaultWorkflow: default
 workspaceMode: single

package/teams/fast-fix.team.md

@@ -1,5 +1,6 @@
 ---
 name: fast-fix
+observability: true
 description: Small team for quick bug fixes
 defaultWorkflow: fast-fix
 workspaceMode: single