pi-crew 0.1.40 → 0.1.41

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.1.41
+
+### Added
+
+- Added strict-provider-friendly team tool schema shapes and config schema coverage for result delivery controls.
+- Added resilient result watcher fallback polling for resource-limit watch failures and partial JSON retry handling.
+- Added `runtime.completionMutationGuard` (`off`/`warn`/`fail`) with structured `task.attention` events when implementation-style workers complete without observed mutations.
+- Added group-join mailbox delivery metadata, request-id dedupe, ack observability, timeout events, and dashboard/status visibility.
+- Expanded `team doctor` and `team status` with schema, async/result delivery, worktree/readiness, attention, transcript, and group-join diagnostics.
+
+### Fixed
+
+- Recovered adaptive implementation planner output when compaction truncates the end marker but complete phase objects are still present.
+
 ## 0.1.40
 
 ### Added

package/README.md

@@ -60,6 +60,8 @@ Current highlights:
 - reliability hardening: heartbeat gradient watcher, opt-in retry executor with attempt trace, crash-recovery detection, deadletter queue
 - background `Agent`/`crew_agent` completion wake-up so parent sessions can automatically join completed subagent results
 - optional `runtime.requirePlanApproval` gate for planner-first approval before mutating adaptive implementation workers run
+- optional `runtime.completionMutationGuard` to warn or fail implementation-style workers that complete without observed mutation tool calls
+- grouped result delivery is correlated through mailbox metadata, deduped by request id, and acknowledged via existing `ack-message`
 - shared redaction for common secrets before durable event/log/mailbox/artifact/metric/diagnostic persistence
 - package polish: `schema.json`, TypeScript semantic check, strip-types import smoke, cross-platform CI workflow, dry-run package verification
 
@@ -176,7 +178,10 @@ Supported config:
   },
   "runtime": {
     "mode": "auto",
-    "requirePlanApproval": false
+    "groupJoin": "smart",
+    "groupJoinAckTimeoutMs": 300000,
+    "requirePlanApproval": false,
+    "completionMutationGuard": "warn"
   },
   "limits": {
     "maxConcurrentWorkers": 3,
@@ -237,6 +242,8 @@ Safety notes:
 - Background `Agent`/`crew_agent` runs notify the parent session when they reach a terminal state; the parent can then call `get_subagent_result`/`crew_agent_result` and continue the original task.
 - `tools.terminateOnForeground` is an opt-in power-user setting. When true, foreground `Agent`/`crew_agent` calls return with `terminate: true` after the child result is available, saving one follow-up LLM turn. Default is false so the assistant can still summarize raw worker output.
 - Runtime state paths are treated as untrusted data: run ids, import bundles, artifact/transcript paths, mailbox files, and agent control/log files are validated with containment checks before reads or writes.
+- `runtime.completionMutationGuard` defaults to `warn`; set `off` to disable or `fail` to fail implementation-style tasks that report success without observed mutation tool calls.
+- Group-join result messages use normal mailbox delivery and normal `ack-message`; missing acknowledgements never block run completion, and duplicate delivery attempts reuse the same request id/message instead of appending spam.
 - Common secret patterns (`token=`, `apiKey=`, `Authorization: Bearer ...`, private keys, etc.) are redacted before durable logs/events/mailbox/artifacts/metrics/diagnostics are written.
 - `observability.enabled` defaults to true for in-memory metrics and heartbeat watching. Metric JSONL snapshots are gated by `telemetry.enabled`; set `telemetry.enabled=false` to opt out of local telemetry files.
 - `reliability.autoRetry` and `reliability.autoRecover` default to false. Enabling retry may execute an idempotent task more than once; each attempt is recorded in `task.attempts`, and exhausted retries append a deadletter entry.
@@ -472,7 +479,7 @@ Manual slash commands are ops/debug controls. Autonomous tool use via policy/rec
 /team-api team_... send-message taskId=task_... direction=inbox to=worker body="task scoped message"
 /team-api team_... read-mailbox direction=outbox
 /team-api team_... read-mailbox taskId=task_... direction=inbox
-/team-api team_... ack-message messageId=msg_...
+/team-api team_... ack-message messageId=msg_...   # also acknowledges group-join result messages
 /team-api team_... read-delivery
 /team-api team_... validate-mailbox repair=true
 /team-api team_... approve-plan

package/docs/usage.md

@@ -29,6 +29,13 @@ Supported fields:
     "preferAsyncForLongTasks": false,
     "allowWorktreeSuggestion": true
   },
+  "runtime": {
+    "mode": "auto",
+    "groupJoin": "smart",
+    "groupJoinAckTimeoutMs": 300000,
+    "completionMutationGuard": "warn",
+    "requirePlanApproval": false
+  },
   "ui": {
     "widgetPlacement": "aboveEditor",
     "widgetMaxLines": 8,
@@ -113,6 +120,10 @@ Background `Agent`/`crew_agent` subagents wake the parent Pi session when they c
 
 State paths are validated before read/write operations. Run ids, imported bundles, artifact and transcript references, mailbox files, and agent control/log files must stay inside their expected `.crew` roots and symlink escapes are rejected. Read-only mailbox APIs return default state without creating mailbox files when no messages exist.
 
+Group-join result delivery uses the normal outbox mailbox and normal `/team-api ... ack-message`. `runtime.groupJoinAckTimeoutMs` only emits observability (`agent.group_join.ack_timeout`) and does not block run completion.
+
+`runtime.completionMutationGuard` defaults to `warn`. Use `off` to disable or `fail` to fail implementation-style workers that complete without observed mutation tool calls.
+
 ## Worktree mode
 
 ```json

package/package.json

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

package/schema.json

@@ -69,7 +69,9 @@
         "inheritContext": { "type": "boolean" },
         "promptMode": { "type": "string", "enum": ["replace", "append"] },
         "groupJoin": { "type": "string", "enum": ["off", "group", "smart"] },
-        "requirePlanApproval": { "type": "boolean" }
+        "groupJoinAckTimeoutMs": { "type": "integer", "minimum": 1 },
+        "requirePlanApproval": { "type": "boolean" },
+        "completionMutationGuard": { "type": "string", "enum": ["off", "warn", "fail"] }
       }
     },
     "control": {

package/src/config/config.ts

@@ -30,6 +30,8 @@ export interface CrewLimitsConfig {
 
 export type CrewRuntimeMode = "auto" | "scaffold" | "child-process" | "live-session";
 
+export type CompletionMutationGuardMode = "off" | "warn" | "fail";
+
 export interface CrewRuntimeConfig {
 	mode?: CrewRuntimeMode;
 	preferLiveSession?: boolean;
@@ -39,7 +41,9 @@ export interface CrewRuntimeConfig {
 	inheritContext?: boolean;
 	promptMode?: "replace" | "append";
 	groupJoin?: "off" | "group" | "smart";
+	groupJoinAckTimeoutMs?: number;
 	requirePlanApproval?: boolean;
+	completionMutationGuard?: CompletionMutationGuardMode;
 }
 
 export interface CrewControlConfig {
@@ -493,7 +497,9 @@ function parseRuntimeConfig(value: unknown): CrewRuntimeConfig | undefined {
 		inheritContext: parseWithSchema(Type.Boolean(), obj.inheritContext),
 		promptMode: parseWithSchema(Type.Union([Type.Literal("replace"), Type.Literal("append")]), obj.promptMode),
 		groupJoin: parseWithSchema(Type.Union([Type.Literal("off"), Type.Literal("group"), Type.Literal("smart")]), obj.groupJoin),
+		groupJoinAckTimeoutMs: parsePositiveInteger(obj.groupJoinAckTimeoutMs, 86_400_000),
 		requirePlanApproval: parseWithSchema(Type.Boolean(), obj.requirePlanApproval),
+		completionMutationGuard: parseWithSchema(Type.Union([Type.Literal("off"), Type.Literal("warn"), Type.Literal("fail")]), obj.completionMutationGuard),
 	};
 	return Object.values(runtime).some((entry) => entry !== undefined) ? runtime : undefined;
 }

package/src/extension/result-watcher.ts

@@ -26,6 +26,12 @@ export interface ResultWatcherOptions extends ResultWatcherDependencies {
 }
 
 const RESULT_WATCHER_RESTART_MS = 3000;
+const RESULT_WATCHER_POLL_MS = 1000;
+
+function shouldFallBackToPolling(error: unknown): boolean {
+	const code = error && typeof error === "object" ? (error as { code?: unknown }).code : undefined;
+	return code === "EMFILE" || code === "ENOSPC" || code === "EPERM";
+}
 
 function readJson(filePath: string): unknown | undefined {
 	try {
@@ -45,16 +51,19 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 	const seen = getGlobalSeenMap("pi-crew.result-watcher");
 	let watcher: fs.FSWatcher | null | undefined;
 	let restartTimer: ReturnType<typeof setTimeout> | undefined;
+	let pollTimer: ReturnType<typeof setInterval> | undefined;
 	const coalescer = createFileCoalescer((file) => {
 		if (!isCurrent()) return;
 		const filePath = path.join(resultsDir, file);
 		if (!file.endsWith(".json") || !fs.existsSync(filePath)) return;
 		const payload = readJson(filePath);
-		if (payload !== undefined) {
-			const key = buildCompletionKey(payload as Record<string, unknown>, `file:${file}`);
-			if (!markSeenWithTtl(seen, key, Date.now(), completionTtlMs)) {
-				events.emit(eventName, payload);
-			}
+		if (payload === undefined) {
+			coalescer.schedule(file, RESULT_WATCHER_POLL_MS);
+			return;
+		}
+		const key = buildCompletionKey(payload as Record<string, unknown>, `file:${file}`);
+		if (!markSeenWithTtl(seen, key, Date.now(), completionTtlMs)) {
+			events.emit(eventName, payload);
 		}
 		try {
 			fs.unlinkSync(filePath);
@@ -62,7 +71,22 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 			logInternalError("result-watcher.unlink", error, `filePath=${filePath}`);
 		}
 	}, 50);
-	const scheduleRestart = () => {
+	const poll = () => {
+		if (!isCurrent() || !fs.existsSync(resultsDir)) return;
+		for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
+	};
+	const startPolling = () => {
+		if (pollTimer) return;
+		pollTimer = setInterval(poll, RESULT_WATCHER_POLL_MS);
+		pollTimer.unref?.();
+		poll();
+	};
+	const stopPolling = () => {
+		if (pollTimer) clearInterval(pollTimer);
+		pollTimer = undefined;
+	};
+	const scheduleRestart = (error?: unknown) => {
+		if (shouldFallBackToPolling(error)) startPolling();
 		if (restartTimer) clearTimeout(restartTimer);
 		restartTimer = setTimeout(() => {
 			restartTimer = undefined;
@@ -85,17 +109,18 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 				if (event !== "rename" || !fileName) return;
 				coalescer.schedule(fileName.toString());
 			}, scheduleRestart);
+			if (watcher) stopPolling();
 			watcher?.unref?.();
 		},
 		prime() {
-			if (!isCurrent() || !fs.existsSync(resultsDir)) return;
-			for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
+			poll();
 		},
 		stop() {
 			if (restartTimer) clearTimeout(restartTimer);
 			restartTimer = undefined;
 			closeWatcher(watcher);
 			watcher = undefined;
+			stopPolling();
 			coalescer.clear();
 		},
 	};

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

@@ -5,7 +5,7 @@ import { loadRunManifestById, saveRunManifest, saveRunTasks, updateRunStatus } f
 import { withRunLockSync } from "../../state/locks.ts";
 import { canTransitionTaskStatus, isTeamTaskStatus } from "../../state/contracts.ts";
 import { claimTask, releaseTaskClaim, transitionClaimedTaskStatus } from "../../state/task-claims.ts";
-import { acknowledgeMailboxMessage, appendMailboxMessage, readDeliveryState, readMailbox, validateMailbox, type MailboxDirection } from "../../state/mailbox.ts";
+import { acknowledgeMailboxMessage, appendMailboxMessage, readDeliveryState, readMailbox, readMailboxMessage, validateMailbox, type MailboxDirection } from "../../state/mailbox.ts";
 import { appendEvent, readEvents, readEventsCursor } from "../../state/event-log.ts";
 import { resolveCrewRuntime } from "../../runtime/runtime-resolver.ts";
 import { probeLiveSessionRuntime } from "../../subagents/live/session-runtime.ts";
@@ -298,8 +298,18 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		if (!messageId) return result("API ack-message requires config.messageId.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		try {
 			return withRunLockSync(loaded.manifest, () => {
+				const message = readMailboxMessage(loaded.manifest, messageId);
 				const delivery = acknowledgeMailboxMessage(loaded.manifest, messageId);
 				appendEvent(loaded.manifest.eventsPath, { type: "mailbox.acknowledged", runId: loaded.manifest.runId, data: { messageId } });
+				if (message?.data?.kind === "group_join" && typeof message.data.requestId === "string") {
+					appendEvent(loaded.manifest.eventsPath, {
+						type: "agent.group_join.acknowledged",
+						runId: loaded.manifest.runId,
+						message: "Group join delivery acknowledged via mailbox ack.",
+						data: { requestId: message.data.requestId, messageId, batchId: message.data.batchId, partial: message.data.partial, acknowledgedAt: delivery.updatedAt, acknowledgedBy: "leader" },
+						metadata: { provenance: "api" },
+					});
+				}
 				ctx.events?.emit?.("crew.mailbox.acknowledged", { runId: loaded.manifest.runId, messageId, delivery });
 				return result(JSON.stringify(delivery, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 			});

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

@@ -10,6 +10,7 @@ import { DEFAULT_PATHS } from "../../config/defaults.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { getPiSpawnCommand } from "../../runtime/pi-spawn.ts";
 import { validateResources } from "../validate-resources.ts";
+import { TeamToolParams } from "../../schema/team-tool-schema.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
 
@@ -59,6 +60,24 @@ function checkWritableDir(dir: string): { ok: boolean; detail: string } {
 	}
 }
 
+function auditJsonSchema(schema: unknown): string[] {
+	const issues: string[] = [];
+	const walk = (node: unknown): void => {
+		if (!node || typeof node !== "object" || Array.isArray(node)) return;
+		const record = node as Record<string, unknown>;
+		if (Array.isArray(record.type)) issues.push("schema node uses array-valued type");
+		if (record.description && !record.type && !record.anyOf && !record.oneOf && !record.allOf && !record.properties) issues.push(`description-only schema node: ${record.description}`);
+		if (record.type === "array" && !record.items) issues.push("array schema missing items");
+		if (record.type && (record.anyOf || record.oneOf)) issues.push("schema node combines type with union keyword");
+		for (const value of Object.values(record)) {
+			if (Array.isArray(value)) for (const item of value) walk(item);
+			else walk(value);
+		}
+	};
+	walk(schema);
+	return issues;
+}
+
 function makeLine(check: DoctorCheck): string {
 	return `- ${check.ok ? "OK" : "FAIL"} ${check.label}: ${check.detail}`;
 }
@@ -130,6 +149,18 @@ export function buildTeamDoctorReport(input: TeamDoctorReportInput): TeamDoctorR
 			ok: input.validationErrors === 0,
 			detail: `${input.validationErrors} errors, ${input.validationWarnings} warnings`,
 		}]),
+		section("Schema", () => {
+			const schemaIssues = auditJsonSchema(TeamToolParams);
+			return [{ label: "strict-provider schema", ok: schemaIssues.length === 0, detail: schemaIssues.length ? schemaIssues.slice(0, 3).join("; ") : "team tool schema compatible" }];
+		}),
+		section("Async/result delivery", () => [
+			{ label: "result watcher", ok: true, detail: "fs.watch with polling fallback for EMFILE/ENOSPC/EPERM" },
+			{ label: "async notifier", ok: true, detail: "session-stale guarded completion notifications enabled" },
+		]),
+		section("Worktrees", () => [
+			{ label: "leader repository", ok: true, detail: input.cwd },
+			{ label: "cleanup policy", ok: true, detail: "dirty worktrees preserved unless force is set" },
+		]),
 	];
 	if (input.smokeChildPi) {
 		sections.push([`Child check`, `- ${input.smokeChildPi.ok ? "OK" : "FAIL"} child Pi smoke: ${input.smokeChildPi.detail}`]);

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

@@ -1,6 +1,7 @@
 import { loadConfig } from "../../config/config.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { appendEvent, readEvents } from "../../state/event-log.ts";
+import { readDeliveryState, readMailbox } from "../../state/mailbox.ts";
 import { loadRunManifestById, updateRunStatus } from "../../state/state-store.ts";
 import { aggregateUsage, formatUsage } from "../../state/usage.ts";
 import { applyAttentionState, formatActivityAge, resolveCrewControlConfig } from "../../runtime/agent-control.ts";
@@ -27,15 +28,32 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 	}
 	const counts = new Map<string, number>();
 	for (const task of tasks) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
-	const events = readEvents(manifest.eventsPath).slice(-8);
+	const allEvents = readEvents(manifest.eventsPath);
+	const events = allEvents.slice(-8);
+	const attentionByTask = new Map(allEvents.filter((event) => event.type === "task.attention" && event.taskId).map((event) => [event.taskId!, event]));
 	const controlConfig = resolveCrewControlConfig(loadConfig(ctx.cwd).config);
 	const crewAgents = readCrewAgents(manifest).map((agent) => applyAttentionState(manifest, agent, controlConfig));
 	const artifactLines = manifest.artifacts.slice(-10).map((artifact) => `- ${artifact.kind}: ${artifact.path}${artifact.sizeBytes !== undefined ? ` (${artifact.sizeBytes} bytes)` : ""}`);
+	const deliveryState = readDeliveryState(manifest);
+	const ackTimeoutMs = loadConfig(ctx.cwd).config.runtime?.groupJoinAckTimeoutMs;
+	const groupJoinLines = readMailbox(manifest, "outbox")
+		.filter((message) => message.data?.kind === "group_join")
+		.slice(-5)
+		.map((message) => {
+			const ack = deliveryState.messages[message.id] === "acknowledged" ? "acknowledged" : "pending";
+			const ageMs = Date.now() - new Date(message.createdAt).getTime();
+			const requestId = String(message.data?.requestId ?? "unknown");
+			const timedOut = ack === "pending" && ackTimeoutMs !== undefined && Number.isFinite(ageMs) && ageMs > ackTimeoutMs;
+			if (timedOut && !allEvents.some((event) => event.type === "agent.group_join.ack_timeout" && event.data?.requestId === requestId)) {
+				appendEvent(manifest.eventsPath, { type: "agent.group_join.ack_timeout", runId: manifest.runId, message: "Group join delivery ack timed out; mailbox delivery remains the fallback.", data: { requestId, messageId: message.id, batchId: message.data?.batchId, partial: message.data?.partial, ageMs, ackTimeoutMs } });
+			}
+			return `- ${String(message.data?.partial) === "true" ? "partial" : "completed"} request=${requestId} message=${message.id} ack=${timedOut ? "timeout" : ack}`;
+		});
 	const totalUsage = aggregateUsage(tasks);
 	const activeAgents = crewAgents.filter((agent) => agent.status === "running");
 	const completedAgents = crewAgents.filter((agent) => agent.status !== "running");
 	const waitingTasks = tasks.filter((task) => task.status === "queued");
-	const agentLine = (agent: typeof crewAgents[number]): string => `- ${agent.id} [${agent.status}] ${agent.role} -> ${agent.agent} runtime=${agent.runtime}${agent.model ? ` model=${agent.model}` : ""}${agent.usage ? ` usage=${formatUsage(agent.usage)}` : ""}${agent.progress?.activityState === "needs_attention" ? " needs_attention" : ""}${formatActivityAge(agent) ? ` activity=${formatActivityAge(agent)}` : ""}${agent.progress?.currentTool ? ` tool=${agent.progress.currentTool}` : ""}${agent.toolUses ? ` tools=${agent.toolUses}` : ""}${!agent.usage && agent.progress?.tokens ? ` tokens=${agent.progress.tokens}` : ""}${agent.progress?.turns ? ` turns=${agent.progress.turns}` : ""}${agent.jsonEvents !== undefined ? ` jsonEvents=${agent.jsonEvents}` : ""}${agent.statusPath ? ` status=${agent.statusPath}` : ""}${agent.error ? ` error=${agent.error}` : ""}`;
+	const agentLine = (agent: typeof crewAgents[number]): string => `- ${agent.id} [${agent.status}] ${agent.role} -> ${agent.agent} runtime=${agent.runtime}${agent.model ? ` model=${agent.model}` : ""}${agent.usage ? ` usage=${formatUsage(agent.usage)}` : ""}${agent.progress?.activityState ? ` activityState=${agent.progress.activityState}` : ""}${formatActivityAge(agent) ? ` activity=${formatActivityAge(agent)}` : ""}${agent.progress?.currentTool ? ` tool=${agent.progress.currentTool}` : ""}${agent.toolUses ? ` tools=${agent.toolUses}` : ""}${!agent.usage && agent.progress?.tokens ? ` tokens=${agent.progress.tokens}` : ""}${agent.progress?.turns ? ` turns=${agent.progress.turns}` : ""}${agent.jsonEvents !== undefined ? ` jsonEvents=${agent.jsonEvents}` : ""}${agent.outputPath ? ` output=${agent.outputPath}` : ""}${agent.transcriptPath ? ` transcript=${agent.transcriptPath}` : ""}${agent.statusPath ? ` status=${agent.statusPath}` : ""}${agent.error ? ` error=${agent.error}` : ""}`;
 	const lines = [
 		`Run: ${manifest.runId}`,
 		`Team: ${manifest.team}`,
@@ -51,7 +69,7 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		"Task graph:",
 		...formatTaskGraphLines(tasks),
 		"Tasks:",
-		...(tasks.length ? tasks.map((task) => `- ${task.id} [${task.status}] ${task.role} -> ${task.agent}${task.taskPacket ? ` scope=${task.taskPacket.scope}` : ""}${task.verification ? ` green=${task.verification.observedGreenLevel}/${task.verification.requiredGreenLevel}` : ""}${task.modelAttempts?.length ? ` attempts=${task.modelAttempts.length}` : ""}${task.modelRouting ? ` modelRouting=${task.modelRouting.requested ? `${task.modelRouting.requested}->` : ""}${task.modelRouting.resolved}${task.modelRouting.usedAttempt ? ` attempt=${task.modelRouting.usedAttempt + 1}` : ""}` : ""}${task.jsonEvents !== undefined ? ` jsonEvents=${task.jsonEvents}` : ""}${task.usage ? ` usage=${JSON.stringify(task.usage)}` : ""}${task.worktree ? ` worktree=${task.worktree.path}` : ""}${task.error ? ` error=${task.error}` : ""}`) : ["- (none)"]),
+		...(tasks.length ? tasks.map((task) => `- ${task.id} [${task.status}] ${task.role} -> ${task.agent}${task.taskPacket ? ` scope=${task.taskPacket.scope}` : ""}${task.verification ? ` green=${task.verification.observedGreenLevel}/${task.verification.requiredGreenLevel}` : ""}${task.modelAttempts?.length ? ` attempts=${task.modelAttempts.length}` : ""}${task.modelRouting ? ` modelRouting=${task.modelRouting.requested ? `${task.modelRouting.requested}->` : ""}${task.modelRouting.resolved}${task.modelRouting.usedAttempt ? ` attempt=${task.modelRouting.usedAttempt + 1}` : ""}` : ""}${task.agentProgress?.activityState ? ` activityState=${task.agentProgress.activityState}` : ""}${attentionByTask.get(task.id)?.data?.reason ? ` attention=${String(attentionByTask.get(task.id)?.data?.reason)}` : ""}${task.jsonEvents !== undefined ? ` jsonEvents=${task.jsonEvents}` : ""}${task.usage ? ` usage=${JSON.stringify(task.usage)}` : ""}${task.resultArtifact ? ` result=${task.resultArtifact.path}` : ""}${task.transcriptArtifact ? ` transcript=${task.transcriptArtifact.path}` : ""}${task.worktree ? ` worktree=${task.worktree.path}` : ""}${task.error ? ` error=${task.error}` : ""}`) : ["- (none)"]),
 		`Task counts: ${[...counts.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none"}`,
 		"Active agents:",
 		...(activeAgents.length ? activeAgents.map(agentLine) : ["- (none)"]),
@@ -62,6 +80,8 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		"Policy decisions:",
 		...(manifest.policyDecisions?.length ? manifest.policyDecisions.map((item) => `- ${item.action} (${item.reason})${item.taskId ? ` ${item.taskId}` : ""}: ${item.message}`) : ["- (none)"]),
 		`Total usage: ${formatUsage(totalUsage)}`,
+		"Group joins:",
+		...(groupJoinLines.length ? groupJoinLines : ["- (none)"]),
 		"",
 		"Recent artifacts:",
 		...(artifactLines.length ? artifactLines : ["- (none)"]),

package/src/runtime/agent-control.ts

@@ -1,6 +1,6 @@
 import type { PiTeamsConfig } from "../config/config.ts";
 import type { TeamRunManifest } from "../state/types.ts";
-import { appendEvent } from "../state/event-log.ts";
+import { appendTaskAttentionEvent } from "./attention-events.ts";
 import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
 import { upsertCrewAgent } from "./crew-agent-records.ts";
 
@@ -53,12 +53,11 @@ export function applyAttentionState(manifest: TeamRunManifest, agent: CrewAgentR
 		},
 	};
 	upsertCrewAgent(manifest, updated);
-	appendEvent(manifest.eventsPath, {
-		type: "agent.needs_attention",
-		runId: manifest.runId,
+	appendTaskAttentionEvent({
+		manifest,
 		taskId: agent.taskId,
 		message: `${agent.agent} needs attention (no observed activity for ${Math.floor(age / 1000)}s).`,
-		data: { agentId: agent.id, ageMs: age, needsAttentionAfterMs: config.needsAttentionAfterMs },
+		data: { activityState: "needs_attention", reason: "idle", elapsedMs: age, taskId: agent.taskId, agentName: agent.agent, suggestedAction: "Check worker status, wait, steer, or cancel if needed." },
 	});
 	return updated;
 }

package/src/runtime/attention-events.ts

@@ -0,0 +1,23 @@
+import { appendEvent, readEvents } from "../state/event-log.ts";
+import type { CrewAttentionEventData, TeamRunManifest } from "../state/types.ts";
+
+export interface AppendTaskAttentionInput {
+	manifest: TeamRunManifest;
+	taskId?: string;
+	message: string;
+	data: CrewAttentionEventData;
+}
+
+export function appendTaskAttentionEvent(input: AppendTaskAttentionInput): boolean {
+	const recent = readEvents(input.manifest.eventsPath).slice(-100);
+	const duplicate = recent.some((event) => event.type === "task.attention" && event.taskId === input.taskId && event.data?.reason === input.data.reason && event.data?.activityState === input.data.activityState);
+	if (duplicate) return false;
+	appendEvent(input.manifest.eventsPath, {
+		type: "task.attention",
+		runId: input.manifest.runId,
+		taskId: input.taskId,
+		message: input.message,
+		data: { ...input.data },
+	});
+	return true;
+}

package/src/runtime/completion-guard.ts

@@ -0,0 +1,99 @@
+import * as fs from "node:fs";
+
+export interface CompletionMutationGuardInput {
+	role: string;
+	taskText?: string;
+	transcriptPath?: string;
+	stdout?: string;
+}
+
+export interface CompletionMutationGuardResult {
+	expectedMutation: boolean;
+	observedMutation: boolean;
+	reason?: "no_mutation_observed";
+	observedTools: string[];
+}
+
+const MUTATING_ROLES = new Set(["executor", "test-engineer"]);
+const MUTATING_TOOLS = new Set(["edit", "write", "multi_edit", "apply_patch"]);
+const READ_ONLY_COMMANDS = /^(pwd|ls|dir|cat|type|sed|grep|rg|find|git\s+(status|diff|log|show|branch|remote|rev-parse|ls-files)|npm\s+(test|run\s+(typecheck|check|lint|test|ci))|node\s+--test)\b/i;
+const MUTATING_COMMANDS = /\b(rm\s+-|del\s+|erase\s+|mv\s+|move\s+|cp\s+|copy\s+|mkdir\b|touch\b|git\s+(add|commit|push|reset|clean|checkout|switch|merge|rebase|stash)|npm\s+(install|i|uninstall|publish|version)|pnpm\s+(add|install|remove)|yarn\s+(add|install|remove)|python\b.*>|node\b.*>|echo\b.*>|Set-Content|Out-File)\b/i;
+const READ_ONLY_HINTS = /\b(read-only|no edits?|do not edit|không sửa|khong sua|chỉ đọc|chi doc|plan only|chỉ lập plan|review only|audit only)\b/i;
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function commandText(value: unknown): string {
+	const record = asRecord(value);
+	if (!record) return typeof value === "string" ? value : "";
+	for (const key of ["command", "cmd", "script", "input"]) {
+		const raw = record[key];
+		if (typeof raw === "string") return raw;
+	}
+	return JSON.stringify(record);
+}
+
+function isMutatingTool(tool: string, args: unknown): boolean {
+	const normalized = tool.toLowerCase();
+	if (MUTATING_TOOLS.has(normalized)) return true;
+	if (normalized === "bash" || normalized === "shell" || normalized === "powershell") {
+		const command = commandText(args).trim();
+		if (!command || READ_ONLY_COMMANDS.test(command)) return false;
+		return MUTATING_COMMANDS.test(command);
+	}
+	return false;
+}
+
+function collectToolCallsFromEvent(event: unknown): Array<{ tool: string; args?: unknown }> {
+	const record = asRecord(event);
+	if (!record) return [];
+	const calls: Array<{ tool: string; args?: unknown }> = [];
+	const directTool = record.toolName ?? record.name ?? record.tool;
+	if (typeof directTool === "string" && (record.type === "tool_execution_start" || record.type === "toolCall" || record.type === "tool_call")) {
+		calls.push({ tool: directTool, args: record.args ?? record.input });
+	}
+	const content = Array.isArray(record.content) ? record.content : asRecord(record.message)?.content;
+	if (Array.isArray(content)) {
+		for (const part of content) {
+			const item = asRecord(part);
+			if (!item) continue;
+			const tool = item.name ?? item.toolName ?? item.tool;
+			if (typeof tool === "string" && (item.type === "toolCall" || item.type === "tool_call" || item.type === "tool_execution_start")) calls.push({ tool, args: item.input ?? item.args });
+		}
+	}
+	return calls;
+}
+
+function transcriptText(input: CompletionMutationGuardInput): string {
+	if (input.transcriptPath && fs.existsSync(input.transcriptPath)) return fs.readFileSync(input.transcriptPath, "utf-8");
+	return input.stdout ?? "";
+}
+
+export function expectsImplementationMutation(input: Pick<CompletionMutationGuardInput, "role" | "taskText">): boolean {
+	if (!MUTATING_ROLES.has(input.role)) return false;
+	return !READ_ONLY_HINTS.test(input.taskText ?? "");
+}
+
+export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
+	const expectedMutation = expectsImplementationMutation(input);
+	const observedTools: string[] = [];
+	let observedMutation = false;
+	const text = transcriptText(input);
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		let event: unknown;
+		try { event = JSON.parse(trimmed); } catch { continue; }
+		for (const call of collectToolCallsFromEvent(event)) {
+			observedTools.push(call.tool);
+			if (isMutatingTool(call.tool, call.args)) observedMutation = true;
+		}
+	}
+	return {
+		expectedMutation,
+		observedMutation,
+		observedTools,
+		...(expectedMutation && !observedMutation ? { reason: "no_mutation_observed" as const } : {}),
+	};
+}

package/src/runtime/crew-agent-runtime.ts

@@ -1,5 +1,5 @@
 import type { TeamTaskStatus } from "../state/contracts.ts";
-import type { ModelRoutingState, UsageState } from "../state/types.ts";
+import type { CrewActivityState, ModelRoutingState, UsageState } from "../state/types.ts";
 
 export type CrewRuntimeKind = "scaffold" | "child-process" | "live-session";
 export type CrewAgentStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "stopped";
@@ -21,7 +21,7 @@ export interface CrewAgentProgress {
 	turns?: number;
 	durationMs?: number;
 	lastActivityAt?: string;
-	activityState?: "active" | "needs_attention" | "stale";
+	activityState?: CrewActivityState;
 	failedTool?: string;
 }
 

package/src/runtime/group-join.ts

@@ -1,7 +1,7 @@
 import type { CrewRuntimeConfig } from "../config/config.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { appendEvent } from "../state/event-log.ts";
-import { appendMailboxMessage } from "../state/mailbox.ts";
+import { appendMailboxMessage, findMailboxMessageByRequestId, readDeliveryState } from "../state/mailbox.ts";
 import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { aggregateTaskOutputs } from "./task-output-context.ts";
 
@@ -18,6 +18,9 @@ export interface CrewGroupJoinDelivery {
 	remaining: string[];
 	artifact?: ArtifactDescriptor;
 	messageId?: string;
+	requestId?: string;
+	ackRequired?: boolean;
+	ackStatus?: "pending" | "acknowledged";
 }
 
 export function resolveGroupJoinMode(runtime?: CrewRuntimeConfig): CrewGroupJoinMode {
@@ -34,6 +37,10 @@ function batchIdFor(runId: string, taskIds: string[]): string {
 	return `${runId}_${taskIds.join("+").replace(/[^a-zA-Z0-9_+-]/g, "_")}`;
 }
 
+function requestIdFor(runId: string, batchId: string, partial: boolean): string {
+	return `${runId}:group-join:${partial ? "partial" : "completed"}:${batchId}`;
+}
+
 function statusList(tasks: TeamTaskState[], status: TeamTaskState["status"]): string[] {
 	return tasks.filter((task) => task.status === status).map((task) => task.id);
 }
@@ -55,7 +62,10 @@ export function deliverGroupJoin(input: {
 	const partial = input.partial ?? remaining.length > 0;
 	const batchId = batchIdFor(input.manifest.runId, taskIds);
 	const summary = aggregateTaskOutputs(latest, input.manifest);
-	const delivery: CrewGroupJoinDelivery = { batchId, mode: input.mode, partial, taskIds, completed, failed, skipped, remaining };
+	const requestId = requestIdFor(input.manifest.runId, batchId, partial);
+	const existingMailbox = findMailboxMessageByRequestId(input.manifest, requestId);
+	const existingStatus = existingMailbox ? readDeliveryState(input.manifest).messages[existingMailbox.id] ?? existingMailbox.status : undefined;
+	const delivery: CrewGroupJoinDelivery = { batchId, mode: input.mode, partial, taskIds, completed, failed, skipped, remaining, requestId, ackRequired: true, ackStatus: existingStatus === "acknowledged" ? "acknowledged" : "pending" };
 	const content = `${JSON.stringify({ ...delivery, createdAt: new Date().toISOString() }, null, 2)}\n`;
 	const artifact = writeArtifact(input.manifest.artifactsRoot, {
 		kind: "metadata",
@@ -63,12 +73,13 @@ export function deliverGroupJoin(input: {
 		producer: "group-join",
 		content,
 	});
-	const mailbox = appendMailboxMessage(input.manifest, {
+	const mailbox = existingMailbox ?? appendMailboxMessage(input.manifest, {
 		direction: "outbox",
 		from: "group-join",
 		to: "leader",
 		body: [
 			`Group join ${partial ? "partial" : "completed"}: ${taskIds.join(", ")}`,
+			`Request: ${requestId}`,
 			`Completed: ${completed.join(", ") || "none"}`,
 			`Failed: ${failed.join(", ") || "none"}`,
 			`Skipped: ${skipped.join(", ") || "none"}`,
@@ -77,12 +88,19 @@ export function deliverGroupJoin(input: {
 			summary,
 		].join("\n"),
 		status: "delivered",
+		data: { kind: "group_join", requestId, batchId, partial, ackRequired: true, taskIds, completed, failed, skipped, remaining },
 	});
 	appendEvent(input.manifest.eventsPath, {
 		type: partial ? "agent.group_join.partial" : "agent.group_join.completed",
 		runId: input.manifest.runId,
 		message: `Group join ${partial ? "partial" : "completed"} for ${taskIds.length} task(s).`,
-		data: { ...delivery, artifactPath: artifact.path, messageId: mailbox.id },
+		data: { ...delivery, artifactPath: artifact.path, messageId: mailbox.id, fallback: "mailbox-delivered", reused: Boolean(existingMailbox) },
+	});
+	if (existingMailbox) appendEvent(input.manifest.eventsPath, {
+		type: "agent.group_join.delivery_reused",
+		runId: input.manifest.runId,
+		message: `Reused group join mailbox delivery for ${taskIds.length} task(s).`,
+		data: { requestId, messageId: mailbox.id, batchId, partial },
 	});
 	return { ...delivery, artifact, messageId: mailbox.id };
 }

package/src/runtime/task-runner.ts

@@ -25,6 +25,8 @@ import { coordinationBridgeInstructions, renderTaskPrompt } from "./task-runner/
 import { applyAgentProgressEvent, applyUsageToProgress, progressEventSummary, shouldFlushProgressEvent } from "./task-runner/progress.ts";
 import { checkpointTask, persistSingleTaskUpdate, updateTask } from "./task-runner/state-helpers.ts";
 import { cleanResultText, isFinalChildEvent } from "./task-runner/result-utils.ts";
+import { evaluateCompletionMutationGuard } from "./completion-guard.ts";
+import { appendTaskAttentionEvent } from "./attention-events.ts";
 
 export interface TaskRunnerInput {
 	manifest: TeamRunManifest;
@@ -86,6 +88,8 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 	let error: string | undefined;
 	let modelAttempts: ModelAttemptSummary[] | undefined;
 	let parsedOutput: ParsedPiJsonOutput | undefined;
+	let finalStdout = "";
+	let transcriptPath: string | undefined;
 
 	let startupEvidence = createStartupEvidence({ command: runtimeKind === "child-process" ? "pi" : runtimeKind === "live-session" ? "live-session" : "safe-scaffold", startedAt: new Date(task.startedAt ?? new Date().toISOString()), finishedAt: new Date(), promptSentAt: new Date(task.startedAt ?? new Date().toISOString()), promptAccepted: true, exitCode: 0 });
 	const inputsArtifact = writeTaskInputsArtifact(manifest, task, dependencyContext);
@@ -100,10 +104,9 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		const candidates = modelRoutingPlan.candidates;
 		const attemptModels = candidates.length > 0 ? candidates : [undefined];
 		const logs: string[] = [];
-		let finalStdout = "";
 		let finalStderr = "";
 		modelAttempts = [];
-		const transcriptPath = `${manifest.artifactsRoot}/transcripts/${task.id}.jsonl`;
+		transcriptPath = `${manifest.artifactsRoot}/transcripts/${task.id}.jsonl`;
 		let finalCheckpointWritten = false;
 		let lastAgentRecordPersistedAt = 0;
 		let lastHeartbeatPersistedAt = 0;
@@ -258,6 +261,26 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		producer: task.id,
 	}) : undefined;
 
+	const mutationGuardMode = input.runtimeConfig?.completionMutationGuard ?? "warn";
+	const mutationGuard = !error && mutationGuardMode !== "off" ? evaluateCompletionMutationGuard({ role: task.role, taskText: `${task.title}\n${input.step.task}`, transcriptPath: runtimeKind === "child-process" ? transcriptPath : transcriptArtifact?.path, stdout: finalStdout }) : undefined;
+	if (mutationGuard?.reason === "no_mutation_observed") {
+		appendTaskAttentionEvent({
+			manifest,
+			taskId: task.id,
+			message: "Implementation-style task completed without an observed mutation tool call.",
+			data: { activityState: "needs_attention", reason: "completion_guard", taskId: task.id, agentName: task.agent, observedTools: mutationGuard.observedTools, suggestedAction: mutationGuardMode === "fail" ? "Review the worker output and rerun with a concrete implementation task." : "Review the worker output; set runtime.completionMutationGuard='fail' to enforce this." },
+		});
+		task = { ...task, agentProgress: { ...(task.agentProgress ?? emptyCrewAgentProgress()), activityState: "needs_attention" } };
+		if (mutationGuardMode === "fail") {
+			error = "Completion mutation guard failed: implementation-style task completed without an observed mutation tool call.";
+			exitCode = exitCode === 0 ? 1 : exitCode;
+			if (modelAttempts?.length) {
+				modelAttempts = modelAttempts.map((attempt, index) => index === modelAttempts!.length - 1 ? { ...attempt, success: false, exitCode, error } : attempt);
+			}
+		}
+		tasks = updateTask(tasks, task);
+	}
+
 	task = {
 		...task,
 		status: error ? "failed" : "completed",

package/src/runtime/team-runner.ts

@@ -118,8 +118,11 @@ function slug(value: string): string {
 
 function extractAdaptivePlanJson(text: string): string | undefined {
 	const markerMatch = text.match(/ADAPTIVE_PLAN_JSON_START\s*([\s\S]*?)\s*ADAPTIVE_PLAN_JSON_END/);
-	const fencedMatch = markerMatch ? undefined : text.match(/```(?:json)?\s*([\s\S]*?)```/i);
-	return markerMatch?.[1] ?? fencedMatch?.[1];
+	if (markerMatch?.[1]) return markerMatch[1];
+	const startIndex = text.indexOf("ADAPTIVE_PLAN_JSON_START");
+	if (startIndex >= 0) return text.slice(startIndex + "ADAPTIVE_PLAN_JSON_START".length).trim();
+	const fencedMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+	return fencedMatch?.[1];
 }
 
 export function __test__parseAdaptivePlan(text: string, allowedRoles: string[]): AdaptivePlan | undefined {
@@ -179,6 +182,52 @@ function closeUnbalancedJson(raw: string): string {
 	return result;
 }
 
+function salvageCompletePhaseObjects(raw: string): unknown | undefined {
+	const phasesIndex = raw.indexOf('"phases"');
+	if (phasesIndex < 0) return undefined;
+	const arrayStart = raw.indexOf("[", phasesIndex);
+	if (arrayStart < 0) return undefined;
+	const phases: unknown[] = [];
+	let objectStart = -1;
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let index = arrayStart + 1; index < raw.length; index++) {
+		const char = raw[index];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (char === "\\" && inString) {
+			escaped = true;
+			continue;
+		}
+		if (char === '"') {
+			inString = !inString;
+			continue;
+		}
+		if (inString) continue;
+		if (char === "{") {
+			if (depth === 0) objectStart = index;
+			depth++;
+			continue;
+		}
+		if (char === "}") {
+			if (depth <= 0) continue;
+			depth--;
+			if (depth === 0 && objectStart >= 0) {
+				try {
+					phases.push(JSON.parse(raw.slice(objectStart, index + 1)));
+				} catch {
+					// Ignore malformed trailing phase objects and keep earlier complete phases.
+				}
+				objectStart = -1;
+			}
+		}
+	}
+	return phases.length ? { phases } : undefined;
+}
+
 function adaptiveRoleAlias(role: string, allowed: Set<string>): string | undefined {
 	if (allowed.has(role)) return role;
 	const normalized = slug(role);
@@ -199,6 +248,7 @@ export function __test__repairAdaptivePlan(text: string, allowedRoles: string[])
 	if (!raw) return { repaired: false, reason: "missing-json" };
 	const candidates = [raw, closeUnbalancedJson(raw)];
 	let parsed: unknown;
+	let salvageUsed = false;
 	for (const candidate of candidates) {
 		try {
 			parsed = JSON.parse(candidate);
@@ -207,13 +257,17 @@ export function __test__repairAdaptivePlan(text: string, allowedRoles: string[])
 			// Try the next repair candidate.
 		}
 	}
+	if (!parsed) {
+		parsed = salvageCompletePhaseObjects(raw);
+		salvageUsed = parsed !== undefined;
+	}
 	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { repaired: false, reason: "invalid-json" };
 	const phasesRaw = Array.isArray((parsed as { phases?: unknown }).phases) ? (parsed as { phases: unknown[] }).phases : Array.isArray((parsed as { tasks?: unknown }).tasks) ? [{ name: "adaptive", tasks: (parsed as { tasks: unknown[] }).tasks }] : undefined;
 	if (!phasesRaw) return { repaired: false, reason: "missing-phases" };
 	const allowed = new Set(allowedRoles);
 	const phases: AdaptivePlanPhase[] = [];
 	let total = 0;
-	let repaired = raw !== closeUnbalancedJson(raw);
+	let repaired = salvageUsed || raw !== closeUnbalancedJson(raw);
 	for (const [phaseIndex, phaseRaw] of phasesRaw.entries()) {
 		if (!phaseRaw || typeof phaseRaw !== "object" || Array.isArray(phaseRaw)) continue;
 		const phaseObj = phaseRaw as { name?: unknown; tasks?: unknown };

package/src/schema/config-schema.ts

@@ -36,7 +36,9 @@ export const PiTeamsRuntimeConfigSchema = Type.Object({
 	inheritContext: Type.Optional(Type.Boolean()),
 	promptMode: Type.Optional(Type.Union([Type.Literal("replace"), Type.Literal("append")])),
 	groupJoin: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("group"), Type.Literal("smart")])),
+	groupJoinAckTimeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
 	requirePlanApproval: Type.Optional(Type.Boolean()),
+	completionMutationGuard: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("warn"), Type.Literal("fail")])),
 }, { additionalProperties: false });
 
 export const PiTeamsControlConfigSchema = Type.Object({

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

@@ -1,9 +1,18 @@
 import { Type } from "typebox";
 
 const SkillOverride = Type.Unsafe({
-	type: ["string", "array", "boolean"],
-	items: { type: "string" },
 	description: "Skill name(s) to inject, array of skill names, or false to disable role defaults.",
+	anyOf: [
+		{ type: "string" },
+		{ type: "array", items: { type: "string" } },
+		{ type: "boolean" },
+	],
+});
+
+const FreeformConfig = Type.Unsafe({
+	description: "Resource config for management actions.",
+	type: "object",
+	additionalProperties: true,
 });
 
 export const TeamToolParams = Type.Object({
@@ -66,7 +75,7 @@ export const TeamToolParams = Type.Object({
 		Type.Literal("project"),
 		Type.Literal("both"),
 	], { description: "Resource scope for discovery or management." })),
-	config: Type.Optional(Type.Unsafe({ description: "Resource config for management actions." })),
+	config: Type.Optional(FreeformConfig),
 	dryRun: Type.Optional(Type.Boolean({ description: "Preview a management mutation without writing files." })),
 	confirm: Type.Optional(Type.Boolean({ description: "Required for destructive management actions." })),
 	force: Type.Optional(Type.Boolean({ description: "Override reference checks for destructive management actions." })),

package/src/state/mailbox.ts

@@ -18,6 +18,7 @@ export interface MailboxMessage {
 	status: MailboxMessageStatus;
 	taskId?: string;
 	acknowledgedAt?: string;
+	data?: Record<string, unknown>;
 }
 
 export interface MailboxDeliveryState {
@@ -134,7 +135,7 @@ function parseMailboxMessage(raw: unknown, expectedDirection: MailboxDirection):
 	const obj = raw as Record<string, unknown>;
 	if (typeof obj.id !== "string" || typeof obj.runId !== "string" || !isDirection(obj.direction) || typeof obj.from !== "string" || typeof obj.to !== "string" || typeof obj.body !== "string" || typeof obj.createdAt !== "string" || !isStatus(obj.status)) return undefined;
 	if (obj.direction !== expectedDirection) return undefined;
-	return { id: obj.id, runId: obj.runId, direction: obj.direction, from: obj.from, to: obj.to, body: obj.body, createdAt: obj.createdAt, status: obj.status, taskId: typeof obj.taskId === "string" ? obj.taskId : undefined, acknowledgedAt: typeof obj.acknowledgedAt === "string" ? obj.acknowledgedAt : undefined };
+	return { id: obj.id, runId: obj.runId, direction: obj.direction, from: obj.from, to: obj.to, body: obj.body, createdAt: obj.createdAt, status: obj.status, taskId: typeof obj.taskId === "string" ? obj.taskId : undefined, acknowledgedAt: typeof obj.acknowledgedAt === "string" ? obj.acknowledgedAt : undefined, data: obj.data && typeof obj.data === "object" && !Array.isArray(obj.data) ? obj.data as Record<string, unknown> : undefined };
 }
 
 function readMailboxFile(filePath: string, direction: MailboxDirection): MailboxMessage[] {
@@ -208,6 +209,7 @@ export function appendMailboxMessage(manifest: TeamRunManifest, message: Omit<Ma
 		createdAt,
 		status: message.status ?? "queued",
 		taskId: message.taskId,
+		data: message.data,
 	};
 	fs.appendFileSync(mailboxFile(manifest, complete.direction, complete.taskId), `${JSON.stringify(redactSecrets(complete))}\n`, "utf-8");
 	const delivery = readDeliveryState(manifest);
@@ -217,6 +219,14 @@ export function appendMailboxMessage(manifest: TeamRunManifest, message: Omit<Ma
 	return complete;
 }
 
+export function findMailboxMessageByRequestId(manifest: TeamRunManifest, requestId: string): MailboxMessage | undefined {
+	return readMailbox(manifest).find((message) => message.data?.requestId === requestId);
+}
+
+export function readMailboxMessage(manifest: TeamRunManifest, messageId: string): MailboxMessage | undefined {
+	return readMailbox(manifest).find((message) => message.id === messageId);
+}
+
 export function acknowledgeMailboxMessage(manifest: TeamRunManifest, messageId: string): MailboxDeliveryState {
 	const delivery = readDeliveryState(manifest);
 	if (!delivery.messages[messageId]) throw new Error(`Mailbox message '${messageId}' not found.`);

package/src/state/types.ts

@@ -92,6 +92,19 @@ export interface PlanApprovalState {
 	planArtifactPath?: string;
 }
 
+export type CrewActivityState = "active" | "active_long_running" | "needs_attention" | "stale";
+export type CrewAttentionReason = "idle" | "tool_failures" | "completion_guard" | "heartbeat_stale" | "plan_approval_pending";
+
+export interface CrewAttentionEventData {
+	activityState: CrewActivityState;
+	reason: CrewAttentionReason;
+	elapsedMs?: number;
+	taskId?: string;
+	agentName?: string;
+	suggestedAction?: string;
+	observedTools?: string[];
+}
+
 export interface TeamRunManifest {
 	schemaVersion: 1;
 	runId: string;

package/src/ui/dashboard-panes/progress-pane.ts

@@ -3,8 +3,11 @@ import type { RunUiSnapshot } from "../snapshot-types.ts";
 export function renderProgressPane(snapshot: RunUiSnapshot | undefined): string[] {
 	if (!snapshot) return ["Progress pane: snapshot unavailable"];
 	const progress = snapshot.progress;
+	const groupJoins = snapshot.groupJoins ?? [];
+	const groupJoinLines = groupJoins.length ? groupJoins.map((item) => `group join ${item.partial ? "partial" : "completed"}: ${item.requestId} ack=${item.ack}`) : ["group joins: none"];
 	return [
 		`Progress pane: ${progress.completed}/${progress.total} completed · running=${progress.running} queued=${progress.queued} failed=${progress.failed}`,
+		...groupJoinLines,
 		...snapshot.recentEvents.slice(-10).map((event) => {
 			const seq = event.metadata?.seq !== undefined ? `#${event.metadata.seq}` : "#?";
 			return `${seq} ${event.time} ${event.type}${event.taskId ? ` ${event.taskId}` : ""}${event.message ? ` · ${event.message}` : ""}`;

package/src/ui/run-snapshot-cache.ts

@@ -8,7 +8,7 @@ import { readEvents, type TeamEvent } from "../state/event-log.ts";
 import type { MailboxMessageStatus } from "../state/mailbox.ts";
 import { loadRunManifestById } from "../state/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import type { RunSnapshotCache, RunUiMailbox, RunUiProgress, RunUiSnapshot, RunUiUsage } from "./snapshot-types.ts";
+import type { RunSnapshotCache, RunUiGroupJoin, RunUiMailbox, RunUiProgress, RunUiSnapshot, RunUiUsage } from "./snapshot-types.ts";
 
 const DEFAULT_TTL_MS = 250;
 const DEFAULT_MAX_ENTRIES = 24;
@@ -195,6 +195,25 @@ function readDeliveryMessages(filePath: string): Record<string, MailboxMessageSt
 	}
 }
 
+function readGroupJoinMailbox(filePath: string, delivery: Record<string, MailboxMessageStatus>): RunUiGroupJoin[] {
+	try {
+		return fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean).flatMap((line) => {
+			try {
+				const parsed = JSON.parse(line) as unknown;
+				if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return [];
+				const message = parsed as { id?: unknown; data?: unknown };
+				const data = message.data && typeof message.data === "object" && !Array.isArray(message.data) ? message.data as Record<string, unknown> : undefined;
+				if (typeof message.id !== "string" || data?.kind !== "group_join" || typeof data.requestId !== "string") return [];
+				return [{ requestId: data.requestId, messageId: message.id, partial: data.partial === true, ack: delivery[message.id] === "acknowledged" ? "acknowledged" as const : "pending" as const }];
+			} catch {
+				return [];
+			}
+		});
+	} catch {
+		return [];
+	}
+}
+
 function readMailboxCounts(filePath: string, delivery: Record<string, MailboxMessageStatus>): number {
 	try {
 		return fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean).reduce((count, line) => {
@@ -213,6 +232,12 @@ function readMailboxCounts(filePath: string, delivery: Record<string, MailboxMes
 	}
 }
 
+function groupJoinsFrom(manifest: TeamRunManifest): RunUiGroupJoin[] {
+	const root = path.join(manifest.stateRoot, "mailbox");
+	const delivery = readDeliveryMessages(path.join(root, "delivery.json"));
+	return readGroupJoinMailbox(path.join(root, "outbox.jsonl"), delivery).slice(-5);
+}
+
 function mailboxFrom(manifest: TeamRunManifest, agents: CrewAgentRecord[]): RunUiMailbox {
 	const root = path.join(manifest.stateRoot, "mailbox");
 	const delivery = readDeliveryMessages(path.join(root, "delivery.json"));
@@ -241,6 +266,7 @@ function signatureFor(input: Omit<RunUiSnapshot, "signature" | "fetchedAt">, sta
 		progress: input.progress,
 		usage: input.usage,
 		mailbox: input.mailbox,
+		groupJoins: input.groupJoins,
 		events: input.recentEvents.map((event) => [event.metadata?.seq, event.time, event.type, event.taskId, event.message]),
 		output: input.recentOutputLines,
 		stamps,
@@ -306,6 +332,7 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 			throw new Error(`Run '${runId}' could not be parsed.`);
 		}
 		const mailbox = mailboxFrom(loaded.manifest, agents);
+		const groupJoins = groupJoinsFrom(loaded.manifest);
 		const base = {
 			runId: loaded.manifest.runId,
 			cwd: loaded.manifest.cwd,
@@ -315,6 +342,7 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 			progress: progressFromTasks(tasks),
 			usage: usageFrom(tasks, agents),
 			mailbox,
+			groupJoins,
 			recentEvents: safeRecentEvents(loaded.manifest.eventsPath, recentEventsLimit),
 			recentOutputLines: recentOutputLines(loaded.manifest, agents, recentOutputLimit),
 		};

package/src/ui/snapshot-types.ts

@@ -22,6 +22,13 @@ export interface RunUiMailbox {
 	needsAttention: number;
 }
 
+export interface RunUiGroupJoin {
+	requestId: string;
+	messageId: string;
+	partial: boolean;
+	ack: "pending" | "acknowledged";
+}
+
 export interface RunUiSnapshot {
 	runId: string;
 	cwd: string;
@@ -33,6 +40,7 @@ export interface RunUiSnapshot {
 	progress: RunUiProgress;
 	usage: RunUiUsage;
 	mailbox: RunUiMailbox;
+	groupJoins?: RunUiGroupJoin[];
 	recentEvents: TeamEvent[];
 	recentOutputLines: string[];
 }

package/src/utils/fs-watch.ts

@@ -18,14 +18,14 @@ export function closeWatcher(watcher: FSWatcher | null | undefined): void {
 export function watchWithErrorHandler(
 	path: string,
 	listener: WatchListener<string>,
-	onError: () => void,
+	onError: (error?: unknown) => void,
 ): FSWatcher | null {
 	try {
 		const watcher = fs.watch(path, listener);
 		watcher.on("error", onError);
 		return watcher;
-	} catch {
-		onError();
+	} catch (error) {
+		onError(error);
 		return null;
 	}
 }