pi-crew 0.11.20 → 0.11.22

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.20",
+	"version": "0.11.22",
 	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
 	"author": "baphuongna",
 	"license": "MIT",
@@ -88,6 +88,7 @@
 		"test": "npm run test:unit && npm run test:integration",
 		"test:full": "npm run test:unit && npm run test:integration && npm run test:integration:slow",
 		"test:unit": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=180000 --test-force-exit 'test/unit/**/*.test.ts'",
+		"test:coverage": "node --import tsx/esm --test --experimental-test-coverage --test-concurrency=4 --test-timeout=180000 --test-force-exit 'test/unit/**/*.test.ts'",
 		"test:critical": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/runtime/broker/crew-broker-handshake.test.ts test/unit/runtime/broker/crew-broker-stale-socket.test.ts test/unit/runtime/broker/crew-broker-feature-flag.test.ts test/unit/runtime/broker/crew-broker-server-gate.test.ts test/unit/runtime/broker/crew-broker-client-fallback.test.ts test/unit/runtime/broker/crew-broker-mailbox-observer.test.ts test/unit/runtime/broker/crew-broker-close-during-reconnect.test.ts test/unit/runtime/broker/crew-broker-steer-dedup.test.ts test/unit/runtime/broker/crew-broker-symlink-steering.test.ts test/unit/ui/keybinding-map.parity.test.ts test/unit/ui/pi-tui-dispatch-probe.test.ts test/unit/utils/session-utils-extract.test.ts test/unit/config/config-schema-sync.test.ts test/unit/runtime/child-pi/child-pi-env-spread.test.ts test/unit/runtime/task-runner/child-executor-heartbeat-pulse.test.ts",
 		"test:watch": "node scripts/test-runner.mjs --watch --test-concurrency=4 --test-timeout=30000 'test/unit/**/*.test.ts'",
 		"test:integration": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=300000 test/integration/*.test.ts",

package/skills/real-test-pi-crew/SKILL.md

@@ -1256,6 +1256,27 @@ When a tier fails, the recovery is usually quick. Match the symptom to the cause
 | `team action='schedule' interval=<ms>` always says `Invalid schedule "<N>ms". Use "5m", …` | handle-schedule builds `${interval}ms`; both interval parsers lacked an `ms` unit — every numeric interval died. Fixed 2026-09-21 | The suggested "5m" formats only work via `cron`/`once` params, not `interval` (interval is schema-typed as a plain ms number) |
 | Runs keep appearing under one scheduled job; children of YOUR pi process; machine thrashing | **Interval ≥ 2^31-1 ms (≥24.8 days) overflowed the Node timer to a 1ms hot loop** (fixed 2026-09-22 — clamped hops). Check `.crew/audit/prune.jsonl` for interleaved auto-prunes. Contain: remove job, then `pkill -f '[b]ackground-runner.ts --cwd <root>'` | Any new timer scheduling must clamp below MAX_TIMER_DELAY_MS — grep for `setInterval(`/`setTimeout(` with computed delays |
 
+## Release gate — battery → push → GitHub Actions GREEN → publish (canonical, 2026-10-14)
+
+Local `npm run ci` là LINUX-ONLY — không thay được matrix 3-OS của GitHub Actions.
+Live-proven 2026-10-14: **0.11.19 và 0.11.20 đều publish khi CI GitHub ĐỎ** (local ci + pre-push
+hook xanh hết) — windows fail do child-env thiếu `SYSTEMROOT` (node con không khởi tạo Winsock được,
+stdout rỗng); macOS fail do transient ECONNREFUSED khiến accepting-probe 1 lần coi holder SỐNG là
+corpse → xóa file socket + rebind (STEAL lock) — fix bằng 3-strike takeover (`process-lock.ts`).
+
+**Quy trình BẮT BUỘC cho mọi release (theo thứ tự, không bỏ bước):**
+
+1. Cập nhật skill (wave entry) + CHANGELOG heading cho version sắp release — commit.
+2. Chạy battery theo decision table (đủ tier cho paths đổi) — xanh hết.
+3. `npm version patch` (tạo release commit + tag).
+4. `git push origin main --follow-tags` — pre-push hook tự chạy full unit local.
+5. **`gh run watch <runId> --exit-status` (hoặc poll `gh run list`) — CHỜ matrix 3-OS XANH TOÀN BỘ.**
+   CI đỏ ⇒ KHÔNG publish — fix, push lại, chờ lại. (Check nhanh fail: `gh run view <id>` +
+   `gh api repos/<o>/<r>/actions/jobs/<jobId>//logs` — KHÔNG grep "not ok" mù: tên test có thể
+   chứa literal "not ok" ("malformed JSON is not ok with a message") — grep kèm assertion block.)
+6. CHỈ KHI xanh: `npm publish` → poll `npm view <pkg> dist-tags.latest` → `gh release create`.
+7. Post-release: knowledge.md entry SHIPPED + dọn branch/scratch.
+
 ## Performance budget (per-tier soft limits)
 
 | Tier | Soft limit | Hard limit | What happens over hard limit |

package/src/errors.ts

@@ -147,9 +147,22 @@ export const errors = {
 		);
 	},
 
-	modelExhausted(chain: string[], lastFailure?: string): CrewError {
+	modelExhausted(chain: string[], lastFailure?: string, plannedChainLength?: number): CrewError {
 		const tried = chain.join(" → ");
 		const last = lastFailure ? ` Last failure: ${lastFailure}` : "";
+		// J4 (DR-03 round-6): a chain that broke EARLY (non-retryable failure,
+		// classifier veto, or spawn-budget stop while queued fallbacks remained)
+		// is not exhaustion — the old "All N candidates exhausted" wording
+		// overstated what happened and hid that fallbacks were never tried.
+		// plannedChainLength (the full candidate chain length) lets the message
+		// distinguish the two shapes; omit it for the legacy exhaustion wording.
+		if (plannedChainLength !== undefined && chain.length < plannedChainLength) {
+			const untried = plannedChainLength - chain.length;
+			return new CrewError(
+				ErrorCode.ModelExhausted,
+				`Model chain failed early (tried ${tried} — ${chain.length} of ${plannedChainLength} candidates; ${untried} queued fallback${untried === 1 ? "" : "s"} not tried).${last}`,
+			).withContext("model fallback chain");
+		}
 		return new CrewError(
 			ErrorCode.ModelExhausted,
 			`All ${chain.length} model candidates exhausted (tried: ${tried}).${last}`,

package/src/extension/async-notifier.ts

@@ -1,7 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { readCrewAgents, saveCrewAgents } from "../runtime/crew-agent-records.ts";
 import { checkProcessLiveness, isActiveRunStatus } from "../runtime/process-status.ts";
-import { withRunLock } from "../state/coordination/locks.ts";
+import { withRunLock, withRunLockSync } from "../state/coordination/locks.ts";
 import { appendEventAsync, readEventsCursor, type TeamEvent } from "../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
@@ -70,24 +70,49 @@ function isTaskActive(task: TeamTaskState): boolean {
 	return task.status === "running" || task.status === "queued" || task.status === "waiting";
 }
 
+/**
+ * R4-7 (DR-02 Wave 2 Cluster C): pure RMW core of the async-died sweep —
+ * flip ONLY still-active tasks to failed. Exported so the locked sweep body
+ * stays unit-testable without the notifier interval harness (repo seam
+ * pattern). Predicate is byte-identical to the previous inline map.
+ */
+export function failStillActiveTasks(tasks: readonly TeamTaskState[], failedAt: string, message: string): TeamTaskState[] {
+	return tasks.map((task) =>
+		isTaskActive(task)
+			? {
+					...task,
+					status: "failed",
+					finishedAt: failedAt,
+					error: message,
+				}
+			: task,
+	);
+}
+
 function markActiveTasksAndAgentsFailed(run: TeamRunManifest, message: string): void {
-	const loaded = loadRunManifestById(run.cwd, run.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency;
-	const tasks = loaded?.tasks ?? [];
 	const failedAt = new Date().toISOString();
-	if (tasks.some(isTaskActive)) {
-		saveRunTasks(
-			run,
-			tasks.map((task) =>
-				isTaskActive(task)
-					? {
-							...task,
-							status: "failed",
-							finishedAt: failedAt,
-							error: message,
-						}
-					: task,
-			),
-		);
+	// R4-7 (DR-02 Wave 2 Cluster C): the task flip used to be an UNLOCKED
+	// load→map→save on tasks.json (":74 no withRunLock - best-effort"). It is
+	// now a run-locked RMW with the fresh re-read INSIDE the lock (R13-S1
+	// canonical pattern): only tasks that are STILL active in the fresh read
+	// are flipped, so a task that completed (or was cancelled) by a concurrent
+	// writer is never overwritten with failed. Lock re-entrance: the sole
+	// caller (markDeadAsyncRunIfNeeded) already holds the ASYNC run lock for
+	// this run in the same async context, so this sync acquisition bypasses
+	// via lockCtx — no self-deadlock, no double file acquire; an unlocked
+	// future caller gets real mutual exclusion.
+	try {
+		withRunLockSync(run, () => {
+			const fresh = loadRunManifestById(run.cwd, run.runId);
+			if (!fresh) return;
+			if (!fresh.tasks.some(isTaskActive)) return;
+			saveRunTasks(fresh.manifest, failStillActiveTasks(fresh.tasks, failedAt, message));
+		});
+	} catch (error) {
+		// Best-effort sweep: lock contention or a store failure must not break
+		// the notifier tick (the run-status flip above already happened) — warn
+		// and keep going; whatever remains active is retried by the next pass.
+		logInternalError("async-notifier.markActiveTasksFailed", error, `runId=${run.runId}`, "warn");
 	}
 	const agents = readCrewAgents(run);
 	if (agents.some((agent) => agent.status === "running" || agent.status === "queued" || agent.status === "waiting")) {

package/src/extension/cross-extension-rpc.ts

@@ -1,7 +1,8 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { withHmacVerification } from "./rpc-hmac.ts";
+import { isHmacEnabled, withHmacVerification } from "./rpc-hmac.ts";
 // Lazy-loaded to avoid pulling team-tool.ts (and its entire runtime chain) into module load.
 import type { handleTeamTool as HandleTeamToolFn } from "./team-tool.ts";
 
@@ -75,6 +76,19 @@ function isAllowedRpcOperation(operation: string): boolean {
 	return RPC_ALLOWED_OPERATIONS.has(operation);
 }
 
+// R7-9 (DR-04 round 7): operations a publisher WITHOUT a valid HMAC signature
+// may issue on the realtime `pi-crew:live-control` channel. Mirrors the
+// RPC_ALLOWED_OPERATIONS semantics (unauthenticated = read-only). The
+// live-control protocol currently defines NO read-only operations — every
+// parseable operation (steer/stop/resume/follow-up) mutates a live agent
+// session — so the set is empty and unauthenticated publishers are rejected
+// outright. Add future read-only live-control ops here when introduced.
+const LIVE_CONTROL_UNAUTHENTICATED_OPERATIONS: ReadonlySet<string> = new Set([]);
+
+function isUnauthenticatedLiveControlOperationAllowed(operation: string): boolean {
+	return LIVE_CONTROL_UNAUTHENTICATED_OPERATIONS.has(operation);
+}
+
 // SECURITY (HIGH #4 fix): In-memory rate limiter for RPC run requests.
 // Prevents any extension from spawning unlimited child processes.
 const RPC_RATE_LIMIT_MAX = 5; // Max 5 RPC run requests...
@@ -148,9 +162,15 @@ function on(events: EventBusLike, channel: string, handler: (raw: unknown) => un
 }
 
 // SECURITY TRUST BOUNDARY: RPC channels (pi-crew:rpc:run, pi-crew:rpc:status,
-// pi-crew:rpc:live-control) are accessible to any extension on the shared event
-// bus. Mitigations: rate limiting, explicit intent, operation allowlist, cwd
-// containment validation, and HMAC origin signing (see rpc-hmac.ts).
+// pi-crew:rpc:live-control, and the realtime pi-crew:live-control channel) are
+// accessible to any extension on the shared event bus. Mitigations: rate
+// limiting, explicit intent, operation allowlist, cwd containment validation,
+// and HMAC origin signing (see rpc-hmac.ts). Trust model (R7-9): without a
+// valid HMAC signature every RPC surface is read-only — the request/response
+// channels enforce this via RPC_ALLOWED_OPERATIONS, and the realtime
+// pi-crew:live-control channel rejects any operation outside
+// LIVE_CONTROL_UNAUTHENTICATED_OPERATIONS (currently ALL of them, since
+// steer/stop/resume/follow-up are mutating) with a warn log and no publish.
 
 export function registerPiCrewRpc(
 	events: EventBusLike | undefined,
@@ -283,7 +303,24 @@ export function registerPiCrewRpc(
 			"pi-crew:live-control",
 			withHmacVerification((raw) => {
 				const request = parseLiveControlRealtimeMessage(raw);
-				if (request) publishLiveControlRealtime(request);
+				if (!request) return;
+				// R7-9 (DR-04 round 7): gate mutating live-control operations. This
+				// handler is only reachable WITHOUT a valid HMAC signature when
+				// PI_CREW_RPC_SECRET is unset — when the secret IS set the wrapper
+				// rejects missing/invalid signatures outright (throw, no publish).
+				// With no secret the publisher is unauthenticated, so only the
+				// (currently empty) read-only allowlist may pass; steer/stop/
+				// resume/follow-up are rejected with a warn log and no publish.
+				if (!isHmacEnabled() && !isUnauthenticatedLiveControlOperationAllowed(request.operation)) {
+					logInternalError(
+						"rpc.live-control",
+						new Error(`rejected unauthenticated live-control operation '${request.operation}'`),
+						`runId=${request.runId},taskId=${request.taskId}`,
+						"warn",
+					);
+					return;
+				}
+				publishLiveControlRealtime(request);
 			}, "pi-crew:live-control"),
 		),
 		on(

package/src/extension/notification-router.ts

@@ -154,11 +154,15 @@ export class NotificationRouter {
 		if (this.batch.length === 0) return;
 		const items = this.batch;
 		this.batch = [];
+		// R7-4 (2026-10-16): flush() also runs inside the setTimeout callback —
+		// a throwing `deliver` used to escape into the timer as an uncaught
+		// exception. Wrap every delivery; log via logInternalError and keep the
+		// lossy batch semantics (the batch is NOT re-queued on error).
 		if (items.length === 1) {
-			this.deliver(items[0]!);
+			this.deliverSafely(items[0]!);
 			return;
 		}
-		this.deliver({
+		this.deliverSafely({
 			id: `batch:${items.map((item) => notificationKey(item)).join(",")}`,
 			severity: batchSeverity(items),
 			source: "batch",
@@ -168,6 +172,15 @@ export class NotificationRouter {
 		});
 	}
 
+	/** R7-4: never let a throwing deliver callback escape flush() (timer context). */
+	private deliverSafely(notification: NotificationDescriptor): void {
+		try {
+			this.deliver(notification);
+		} catch (error) {
+			logInternalError("notification.flush", error);
+		}
+	}
+
 	dispose(): void {
 		if (this.timer) clearTimeout(this.timer);
 		this.timer = undefined;

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

@@ -536,8 +536,11 @@ async function runDeferredSessionCleanup(
  * Build a CrewScheduler wired to the current session. The scheduler's
  * executor closure invokes handleTeamTool lazily — the heavy team-tool
  * import only fires when a scheduled job actually runs.
+ *
+ * @internal — exported for the R6-2 persistence-wiring unit tests
+ * (test/unit/runtime/scheduling/scheduler-persist-reload.test.ts).
  */
-function setupCrewScheduler(
+export function setupCrewScheduler(
 	pi: ExtensionAPI,
 	ctx: RegistrationContext,
 	extensionCtx: ExtensionContext,
@@ -556,6 +559,15 @@ function setupCrewScheduler(
 			if (ctx.cleanedUp) return;
 			notifyScheduleEvent(event);
 			pi.events?.emit?.("crew-scheduler", event);
+			// R6-2(a) (round-6 audit): `updated` scheduler events persist the job —
+			// the persist flow armCron's docstring always claimed existed. fire()'s
+			// lastStatus flips and advanceCronNextRun's nextRun writes now land on
+			// disk; before this only the executor persisted, and it persisted the
+			// pre-completion snapshot (lastStatus:"running") while the terminal flip
+			// stayed memory-only — a restart in that window reloaded "running" and
+			// fire()'s in-flight guard skipped the job forever (jobs died after
+			// restart). persistScheduledJobUpdate is best-effort (internal catch).
+			if (event.type === "updated") persistScheduledJobUpdate(extensionCtx.cwd, event.job);
 		},
 		executor: (job) => {
 			let runParams: { action: string; team: string; goal: string };
@@ -601,17 +613,26 @@ function setupCrewScheduler(
 							/* best-effort provenance tracking */
 						}
 					}
-					try {
-						const updatedJob = crewScheduler?.list().find((j) => j.id === job.id);
-						if (updatedJob) persistScheduledJobUpdate(extensionCtx.cwd, updatedJob);
-					} catch {
-						/* best-effort */
-					}
-					crewScheduler?.update(job.id, {
-						runCount: job.runCount + 1,
-						lastRun: new Date().toISOString(),
-						lastStatus: "success",
-					});
+					// R6-2(b) + I6 (round-6 audit): update state FIRST, then persist the
+					// UPDATED job. The old order persisted the fire-time snapshot (still
+					// lastStatus:"running") and then flipped memory only — a restart in
+					// that window reloaded "running" and fire()'s in-flight guard skipped
+					// the job forever. runCount comes from a FRESH list() read: the
+					// closure-captured `job` is the dispatch-time snapshot, so any update
+					// that landed between dispatch and completion (run-now, another
+					// completion) would otherwise be clobbered with a stale count. The
+					// update() call also persists via the emit wiring above; the explicit
+					// persist keeps the executor authoritative when the emit guard exited
+					// early (cleanedUp).
+					const freshJob = crewScheduler?.list().find((j) => j.id === job.id);
+					const completedJob = freshJob
+						? crewScheduler?.update(job.id, {
+								runCount: freshJob.runCount + 1,
+								lastRun: new Date().toISOString(),
+								lastStatus: "success",
+							})
+						: undefined;
+					if (completedJob) persistScheduledJobUpdate(extensionCtx.cwd, completedJob);
 				} catch (err) {
 					logInternalError("scheduler.execute", err);
 					crewScheduler?.update(job.id, { lastStatus: "error" });
@@ -651,7 +672,9 @@ function setupCrewScheduler(
 //  - retains the broker across session switches when the session_id is
 //    unchanged; on a session_id change, stops the old broker and binds a new
 //    one on the next acquire.
-//  - stops the broker during session_shutdown BEFORE the runtime cleanup path.
+//  - stops the broker during session_shutdown: cleanupRuntime
+//    (registration/runtime-cleanup.ts) calls ctx.brokerController?.stop()
+//    first, before the rest of the runtime teardown (R7-11 wiring).
 //
 // The gate is re-evaluated on every `issueForChild` call (cheap env+depth
 // check) so the kill switch (PI_CREW_BROKER=0) takes effect immediately.

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

@@ -129,6 +129,23 @@ function buildCleanupRuntime(ctx: RegistrationContext): () => void {
 	return (): void => {
 		if (ctx.cleanedUp) return;
 		ctx.cleanedUp = true;
+		// R7-11 (DR-04 round 7): stop the inter-pi broker FIRST, before the rest
+		// of the runtime teardown — this call is what makes the
+		// CrewBrokerLifecycleController docblock's "stops the broker during
+		// session_shutdown" promise true (see lifecycle-handlers.ts). The
+		// controller's stop() is idempotent and swallows its own errors; clearing
+		// the field makes a re-entry a no-op even if the cleanedUp gate were
+		// bypassed. Fire-and-forget: cleanupRuntime is synchronous and shutdown
+		// must not block on the broker socket teardown.
+		try {
+			const stopping = ctx.brokerController?.stop();
+			ctx.brokerController = undefined;
+			stopping?.catch((error) => {
+				logInternalError("cleanup-runtime.broker-stop", error);
+			});
+		} catch (error) {
+			logInternalError("cleanup-runtime.broker-stop", error);
+		}
 		const sid = extractSessionId(ctx.currentCtx);
 		if (ctx.preloadTimer) {
 			clearTimeout(ctx.preloadTimer);

package/src/extension/registration/wire-cross-extension.ts

@@ -10,9 +10,31 @@
  *     (EXT-9: no longer on globalThis[Symbol.for(...)]).
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { logInternalError } from "../../utils/internal-error.ts";
 import { registerPiCrewRpc } from "../cross-extension-rpc.ts";
 import type { RegistrationContext } from "./registration-types.ts";
 
+/**
+ * N-6 (DR-04 round 7): shared generation/ownership guard for the late lazy
+ * team-tool import. The dynamic import resolves on a LATER tick — a
+ * session_shutdown (or session-switch cleanup) may already have torn the
+ * runtime down by then, and installing the crew registry after teardown would
+ * resurrect extension state for a disposed registration. Skip the install
+ * when the registration generation moved on or the context is marked
+ * cleaned-up; session_start rebinds the registry via
+ * refreshCrossExtensionWiringForSession anyway.
+ */
+function registryInstallSkipped(ctx: RegistrationContext, installGeneration: number, where: string): boolean {
+	if (!ctx.cleanedUp && ctx.sessionGeneration === installGeneration) return false;
+	logInternalError(
+		"register.wire-cross-extension",
+		new Error(`skipped crew registry install (${where}): runtime cleanup already ran before the lazy import resolved`),
+		`installGeneration=${installGeneration},currentGeneration=${ctx.sessionGeneration},cleanedUp=${ctx.cleanedUp}`,
+		"debug",
+	);
+	return true;
+}
+
 /** Install both wires on the registration context. */
 export function installCrossExtensionWiring(pi: ExtensionAPI, ctx: RegistrationContext): void {
 	// Wire the in-process RPC handle.
@@ -27,8 +49,10 @@ export function installCrossExtensionWiring(pi: ExtensionAPI, ctx: RegistrationC
 	// Install the crew registry. Lazy import keeps team-tool.ts (which pulls
 	// in the entire runtime chain) out of the cold-start module graph. EXT-9:
 	// the registry now lives in module-scoped state, not globalThis.
+	const installGeneration = ctx.sessionGeneration;
 	void import("../team-tool.ts").then(({ installCrewGlobalRegistry }) => {
 		// LAZY: defer team-tool until cross-extension wiring fires
+		if (registryInstallSkipped(ctx, installGeneration, "install")) return;
 		const manifestCacheForRegistry = ctx.getManifestCache(ctx.currentCtx?.cwd ?? process.cwd());
 		installCrewGlobalRegistry({
 			manifestCache: manifestCacheForRegistry,
@@ -57,8 +81,10 @@ export function refreshCrossExtensionWiringForSession(pi: ExtensionAPI, ctx: Reg
 		installCrossExtensionWiring(pi, ctx);
 		return;
 	}
+	const installGeneration = ctx.sessionGeneration;
 	void import("../team-tool.ts").then(({ installCrewGlobalRegistry }) => {
 		// LAZY: defer team-tool until cross-extension wiring fires
+		if (registryInstallSkipped(ctx, installGeneration, "session-refresh")) return;
 		installCrewGlobalRegistry({
 			manifestCache: ctx.getManifestCache(ctx.currentCtx?.cwd ?? process.cwd()),
 			cwdProvider: () => ctx.currentCtx?.cwd ?? process.cwd(),

package/src/extension/rpc-hmac.ts

@@ -96,6 +96,32 @@ export function createRpcSignature(origin: string, channel: string, body: unknow
 
 // --- Verification ------------------------------------------------------------
 
+/**
+ * Bounded insertion-ordered (FIFO) cache of nonces from VERIFIED signatures
+ * (R7-10, DR-04 round 7). A captured request replayed inside the signature
+ * validity window is rejected with reason "replayed nonce".
+ *
+ * Nonces are recorded ONLY after the HMAC itself validates, so an attacker
+ * cannot flood the cache with junk nonces to evict recorded ones (that would
+ * re-enable replay). Entries expire with the signature validity window and
+ * are pruned on every verification; size is FIFO-capped to bound memory.
+ */
+const NONCE_CACHE_MAX_ENTRIES = 512;
+const seenNonces = new Map<string, number>();
+
+function pruneSeenNonces(now: number): void {
+	const expiredBefore = now - SIGNATURE_VALIDITY_MS;
+	for (const [nonce, seenAt] of seenNonces) {
+		if (seenAt >= expiredBefore) break; // insertion order ⇒ every later entry is newer
+		seenNonces.delete(nonce);
+	}
+	while (seenNonces.size > NONCE_CACHE_MAX_ENTRIES) {
+		const oldestNonce = seenNonces.keys().next().value;
+		if (oldestNonce === undefined) break;
+		seenNonces.delete(oldestNonce);
+	}
+}
+
 /**
  * Verify an HMAC signature.
  *
@@ -121,7 +147,21 @@ export function verifyRpcSignature(payload: RpcSignedPayload, body: unknown): {
 	}
 
 	const expected = computeHmac(secret, payload, body);
-	return timingSafeCompare(payload.signature, expected) ? { valid: true } : { valid: false, reason: "HMAC signature mismatch" };
+	if (!timingSafeCompare(payload.signature, expected)) {
+		return { valid: false, reason: "HMAC signature mismatch" };
+	}
+
+	// R7-10: replay protection — reject a nonce that was already verified within
+	// the validity window; record this one only after the HMAC validated.
+	pruneSeenNonces(now);
+	if (seenNonces.has(payload.nonce)) {
+		return {
+			valid: false,
+			reason: `replayed nonce (nonce already verified within the ${Math.round(SIGNATURE_VALIDITY_MS / 60000)}-minute validity window)`,
+		};
+	}
+	seenNonces.set(payload.nonce, now);
+	return { valid: true };
 }
 
 // --- Middleware --------------------------------------------------------------
@@ -135,7 +175,7 @@ export function verifyRpcSignature(payload: RpcSignedPayload, body: unknown): {
  */
 export function withHmacVerification<P extends { requestId: string }>(
 	handler: (params: P) => unknown | Promise<unknown>,
-	_channel: string,
+	channel: string,
 ): (raw: unknown) => unknown | Promise<unknown> {
 	return (raw: unknown) => {
 		const params = raw as P;
@@ -155,6 +195,17 @@ export function withHmacVerification<P extends { requestId: string }>(
 			throw new Error("[pi-crew HMAC] Missing HMAC signature in RPC request.");
 		}
 
+		// N-3 (DR-04 round 7): bind the arrival channel. The MAC covers the
+		// CLAIMED channel (payload.channel is mixed into computeHmac), so without
+		// this check a signature issued for channel A also validates on channel B
+		// — a cross-channel replay. The signature must have been issued for the
+		// exact channel this wrapper guards.
+		if (sigPayload.channel !== channel) {
+			throw new Error(
+				`[pi-crew HMAC] Signature channel mismatch: signature was issued for '${sigPayload.channel}', request arrived on '${channel}'.`,
+			);
+		}
+
 		// Strip HMAC fields from body before verification (HMAC was signed over original params)
 		const originalBody = stripHmacFields(params);
 		const verification = verifyRpcSignature(sigPayload, originalBody);

package/src/extension/team-tool/cancel.ts

@@ -293,27 +293,11 @@ export async function handleCancel(params: TeamToolParamsValue, ctx: TeamContext
 			true,
 		);
 	}
-	await terminateLiveAgentsForRun(loaded.manifest.runId, "cancelled", appendEvent, loaded.manifest.eventsPath);
-
-	// Best-effort: kill the async background runner process so it doesn't
-	// overwrite the cancelled state while we hold the run lock.
-	const asyncPid = loaded.manifest.async?.pid;
-	if (asyncPid !== undefined && asyncPid > 0) {
-		try {
-			killProcessPid(asyncPid);
-			// H1 (2026-08-10): informational event in async context — await the
-			// async lock path (non-blocking event loop, ~1ms vs ~14ms sync).
-			await appendEventAsync(loaded.manifest.eventsPath, {
-				type: "async.kill_requested",
-				runId: loaded.manifest.runId,
-				message: "Sent SIGTERM to background runner process.",
-				data: { pid: asyncPid },
-			});
-		} catch (error) {
-			logInternalError("team-tool.handleCancel.killAsync", error, `runId=${loaded.manifest.runId},pid=${asyncPid}`);
-		}
-	}
-
+	// N-5 (DR-04 round 7): the live-agent termination + async-runner kill used
+	// to run HERE on the stale pre-lock `loaded` snapshot — a run that reached a
+	// terminal state during the before_cancel hook gap was still torn down and
+	// its background runner SIGTERMed. The signal decision now derives from the
+	// FRESH in-lock read below (see the gated block inside the lock).
 	return withRunLockSync(loaded.manifest, () => {
 		// R13-2 (2026-08-14): fresh re-read INSIDE the lock. `loaded` was captured
 		// lock-free BEFORE the before_cancel hook + live-agent termination gap; a
@@ -349,6 +333,35 @@ export async function handleCancel(params: TeamToolParamsValue, ctx: TeamContext
 				true,
 			);
 		}
+		// N-5 (DR-04 round 7): signal ONLY when the FRESH in-lock status is still
+		// "running". Best-effort semantics are kept, but this is a synchronous
+		// run-lock callback (cannot await — H1 2026-08-10 pattern), so the
+		// async operations are fire-and-forget with errors logged. killProcessPid
+		// still signals synchronously here — while we hold the lock — so the async
+		// background runner cannot overwrite the cancelled state we write below.
+		if (fresh.manifest.status === "running") {
+			void terminateLiveAgentsForRun(fresh.manifest.runId, "cancelled", appendEvent, fresh.manifest.eventsPath).catch((error) =>
+				logInternalError("team-tool.handleCancel.terminateLiveAgents", error, `runId=${fresh.manifest.runId}`),
+			);
+			const asyncPid = fresh.manifest.async?.pid;
+			if (asyncPid !== undefined && asyncPid > 0) {
+				try {
+					killProcessPid(asyncPid);
+					// H1 (2026-08-10): informational event in async context — fire-and-forget
+					// on the async lock path (non-blocking event loop, ~1ms vs ~14ms sync).
+					void appendEventAsync(fresh.manifest.eventsPath, {
+						type: "async.kill_requested",
+						runId: fresh.manifest.runId,
+						message: "Sent SIGTERM to background runner process.",
+						data: { pid: asyncPid },
+					}).catch((error) =>
+						logInternalError("team-tool.handleCancel.killAsyncEvent", error, `runId=${fresh.manifest.runId},pid=${asyncPid}`),
+					);
+				} catch (error) {
+					logInternalError("team-tool.handleCancel.killAsync", error, `runId=${fresh.manifest.runId},pid=${asyncPid}`);
+				}
+			}
+		}
 		const cancellableIds = new Set(abortResult.abortedIds);
 		const cancelReason = cancelReasonFromParams(params);
 		const cancelIntent = intentFromConfig(params.config);

package/src/extension/team-tool/dispatch/index.ts

@@ -1,12 +1,13 @@
 /**
  * API-5 facade dispatch — domain router registry.
  *
- * `domainForAction(action)` maps each of the 54 action strings to one of 5
+ * `domainForAction(action)` maps each of the 57 action strings to one of 5
  * domains. `handleTeamTool` (in team-tool.ts) calls this to pick the right
  * domain router, preserving the exact same public API and zero caller changes.
  *
- * 54→5 mapping:
- *   run     (9):  run, parallel, plan, orchestrate, resume, retry, wait, steer, goal
+ * 57→5 mapping (kept in sync by test/unit/schema/team-tool-docs-sync.test.ts —
+ * DR-01: this header drifted to 54/9/16 while the schema had 57/10/17):
+ *   run     (10): run, parallel, plan, plans, orchestrate, resume, retry, wait, steer, goal
  *   status  (17): status, list, get, events, artifacts, breakdown, summary, graph,
  *                 search, health, worktrees, checkpoint, cache, explain, onboard, recommend, help
  *   control (7):  cancel, invalidate, respond, cleanup, prune, forget, doctor
@@ -24,7 +25,7 @@ import { handleStatusDomain } from "./status.ts";
 export { handleAutomateDomain, handleControlDomain, handleManageDomain, handleRunDomain, handleStatusDomain };
 
 const ACTION_TO_DOMAIN: Record<string, TeamDomain> = {
-	// run domain (9)
+	// run domain (10)
 	run: "run",
 	plans: "run",
 	parallel: "run",
@@ -64,7 +65,7 @@ const ACTION_TO_DOMAIN: Record<string, TeamDomain> = {
 	forget: "control",
 	doctor: "control",
 
-	// manage domain (16)
+	// manage domain (17)
 	create: "manage",
 	update: "manage",
 	delete: "manage",