@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/gjc-runtime/team-runtime.ts

@@ -3,11 +3,34 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import { buildTeamHudSummary as buildWorkflowTeamHudSummary } from "../skill-state/workflow-hud";
+import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
+
 import { applyGjcTmuxProfile } from "./launch-tmux";
+import {
+	AlreadyExistsError,
+	appendJsonl as appendJsonlAudited,
+	appendText,
+	createJsonNoClobber,
+	deleteIfOwned,
+	removeFileAudited,
+	writeJsonAtomic,
+	writeReport,
+	writeWorkflowEnvelopeAtomic,
+} from "./state-writer";
+import { GJC_TMUX_PROFILE_OPTION, GJC_TMUX_PROFILE_VALUE } from "./tmux-common";
 
 export type GjcTeamPhase = "starting" | "running" | "awaiting_integration" | "complete" | "failed" | "cancelled";
 export type GjcTeamTaskStatus = "pending" | "blocked" | "in_progress" | "completed" | "failed";
 export type GjcWorkerStatusState = "idle" | "working" | "blocked" | "done" | "failed" | "draining" | "unknown";
+export type GjcTeamWorkerLifecycleState =
+	| "starting"
+	| "ready"
+	| "working"
+	| "draining"
+	| "stopped"
+	| "failed"
+	| "unknown";
+export type GjcTeamShutdownMode = "graceful" | "force" | "abort";
 
 export const GJC_TEAM_DEFAULT_WORKERS = 3;
 export const GJC_TEAM_MAX_WORKERS = 20;
@@ -47,6 +70,27 @@ export interface GjcTeamTaskClaim {
 	token: string;
 	leased_until: string;
 }
+export type GjcTeamTaskCompletionEvidenceKind = "command" | "inspection" | "artifact";
+export type GjcTeamTaskCompletionEvidenceStatus = "passed" | "failed" | "not_run" | "verified" | "rejected";
+
+export interface GjcTeamTaskCompletionEvidenceItem {
+	kind: GjcTeamTaskCompletionEvidenceKind;
+	status: GjcTeamTaskCompletionEvidenceStatus;
+	summary: string;
+	command?: string;
+	artifact?: string;
+	location?: string;
+	output?: string;
+}
+
+export interface GjcTeamTaskCompletionEvidence {
+	summary: string;
+	items: GjcTeamTaskCompletionEvidenceItem[];
+	files?: string[];
+	notes?: string;
+	recorded_by: string;
+	recorded_at: string;
+}
 
 export interface GjcTeamTask {
 	id: string;
@@ -58,9 +102,13 @@ export interface GjcTeamTask {
 	assignee?: string;
 	owner?: string;
 	result?: string;
+	completion_evidence?: GjcTeamTaskCompletionEvidence;
 	error?: string;
 	blocked_by?: string[];
 	depends_on?: string[];
+	lane?: string;
+	required_role?: string;
+	allowed_roles?: string[];
 	version: number;
 	claim?: GjcTeamTaskClaim;
 	created_at: string;
@@ -121,6 +169,22 @@ export interface GjcTeamMonitorSnapshot {
 	integration_by_worker: Record<string, GjcTeamWorkerIntegrationState>;
 	updated_at: string;
 }
+export interface GjcTeamWorkerLifecycle {
+	worker: string;
+	lifecycle_state: GjcTeamWorkerLifecycleState;
+	worker_status_state: GjcWorkerStatusState;
+	pane_id?: string;
+	pid?: number;
+	started_at?: string;
+	updated_at: string;
+	stopped_at?: string;
+	stop_reason?: string;
+	shutdown_request_id?: string;
+	shutdown_requested_at?: string;
+	shutdown_acknowledged_at?: string;
+	shutdown_ack_status?: string;
+	shutdown_mode?: GjcTeamShutdownMode;
+}
 
 export type GjcTeamNotificationDeliveryState =
 	| "pending"
@@ -167,9 +231,13 @@ export interface GjcTeamSnapshot {
 	task_counts: Record<GjcTeamTaskStatus, number>;
 	workers: GjcTeamWorker[];
 	integration_by_worker?: Record<string, GjcTeamWorkerIntegrationState>;
+	worker_lifecycle_by_id: Record<string, GjcTeamWorkerLifecycle>;
 	notification_summary: GjcTeamNotificationSummary;
 	updated_at: string;
 }
+export interface GjcTeamSnapshotOptions {
+	reconcileNotifications?: boolean;
+}
 
 export interface GjcTeamStartOptions {
 	workerCount: number;
@@ -189,6 +257,23 @@ export interface GjcTeamApiClaimResult {
 	claim_token?: string;
 	reason?: string;
 }
+export type GjcTeamLivenessRecoveryReason =
+	| "claim_expired"
+	| "stale_heartbeat"
+	| "missing_pane"
+	| "worker_lifecycle_failed"
+	| "worker_lifecycle_stopped";
+
+export interface GjcTeamRecoveredClaim {
+	task_id: string;
+	worker: string;
+	reasons: GjcTeamLivenessRecoveryReason[];
+}
+
+export interface GjcTeamLivenessRecoveryResult {
+	recovered_claims: GjcTeamRecoveredClaim[];
+	stale_workers: Record<string, GjcTeamLivenessRecoveryReason[]>;
+}
 
 export interface GjcTeamMailboxMessage {
 	message_id: string;
@@ -201,6 +286,55 @@ export interface GjcTeamMailboxMessage {
 	idempotency_key?: string;
 }
 
+function taskReceiptFields(teamName: string, task: GjcTeamTask): Record<string, unknown> {
+	return {
+		team_name: teamName,
+		task_id: task.id,
+		status: task.status,
+		owner: task.owner,
+		worker_id: task.claim?.owner ?? task.owner ?? task.assignee,
+	};
+}
+
+function mailboxMessageReceiptFields(teamName: string, message: GjcTeamMailboxMessage): Record<string, unknown> {
+	return {
+		team_name: teamName,
+		message_id: message.message_id,
+		from_worker: message.from_worker,
+		to_worker: message.to_worker,
+		delivered: Boolean(message.delivered_at),
+		notified: Boolean(message.notified_at),
+		delivered_at: message.delivered_at,
+		notified_at: message.notified_at,
+	};
+}
+
+function notificationReceiptFields(notification: GjcTeamNotification): Record<string, unknown> {
+	return {
+		team_name: notification.team_name,
+		notification_id: notification.id,
+		recipient: notification.recipient,
+		source_type: notification.source.type,
+		source_id: notification.source.id,
+		delivery_state: notification.delivery_state,
+		pane_attempt_result: notification.pane_attempt_result,
+		pane_attempt_reason: notification.pane_attempt_reason,
+		replay_count: notification.replay_count,
+	};
+}
+
+function notificationSummaryReceipt(
+	teamName: string,
+	result: { notifications: GjcTeamNotification[]; summary: GjcTeamNotificationSummary },
+): Record<string, unknown> {
+	return {
+		team_name: teamName,
+		notification_ids: result.notifications.map(notification => notification.id),
+		delivery_states: result.notifications.map(notification => notification.delivery_state),
+		summary: result.summary,
+	};
+}
+
 interface FsError {
 	code?: string;
 }
@@ -283,6 +417,19 @@ export interface GjcTeamEvent {
 	message?: string;
 	data?: Record<string, unknown>;
 }
+export interface GjcTeamTraceEvent {
+	schema_version: 1;
+	trace_id: string;
+	span_id: string;
+	source_event_id: string;
+	event_type: string;
+	ts: string;
+	worker?: string;
+	task_id?: string;
+	message?: string;
+	evidence_refs?: string[];
+	data?: Record<string, unknown>;
+}
 interface WorkerStatusFile {
 	state: GjcWorkerStatusState;
 	current_task_id?: string;
@@ -371,12 +518,15 @@ export const GJC_TEAM_API_OPERATIONS = [
 	"read-config",
 	"read-manifest",
 	"read-worker-status",
+	"update-worker-status",
 	"read-worker-heartbeat",
+	"recover-stale-claims",
 	"update-worker-heartbeat",
 	"write-worker-inbox",
 	"write-worker-identity",
 	"append-event",
 	"read-events",
+	"read-traces",
 	"await-event",
 	"write-shutdown-request",
 	"read-shutdown-ack",
@@ -392,9 +542,14 @@ function now(): string {
 function isEnoent(error: unknown): error is FsError {
 	return typeof error === "object" && error !== null && "code" in error && (error as FsError).code === "ENOENT";
 }
-function isEexist(error: unknown): error is FsError {
-	return typeof error === "object" && error !== null && "code" in error && (error as FsError).code === "EEXIST";
+function stateWriterOptions(filePath: string, category: "state" | "ledger" | "report" | "prune", verb: string) {
+	const resolved = path.resolve(filePath);
+	const marker = `${path.sep}.gjc${path.sep}`;
+	const markerIndex = resolved.indexOf(marker);
+	const cwd = markerIndex >= 0 ? resolved.slice(0, markerIndex) : process.cwd();
+	return { cwd, audit: { category, verb, owner: "gjc-runtime" as const } };
 }
+
 function sanitizeName(value: string): string {
 	const sanitized = value
 		.toLowerCase()
@@ -432,9 +587,6 @@ function safePathSegment(kind: string, value: string): string {
 function taskPath(dir: string, taskId: string): string {
 	return path.join(dir, "tasks", `${safePathSegment("task_id", taskId)}.json`);
 }
-function taskEvidencePath(dir: string, taskId: string): string {
-	return path.join(dir, "evidence", "tasks", `${safePathSegment("task_id", taskId)}.json`);
-}
 function mailboxPath(dir: string, worker: string): string {
 	return path.join(dir, "mailbox", `${safePathSegment("worker_id", worker)}.json`);
 }
@@ -450,6 +602,17 @@ function notificationPath(dir: string, notificationId: string): string {
 function workerDir(dir: string, worker: string): string {
 	return path.join(dir, "workers", safePathSegment("worker_id", worker));
 }
+function workerLifecyclePath(dir: string, worker: string): string {
+	return path.join(workerDir(dir, worker), "lifecycle.json");
+}
+
+function tracePath(dir: string): string {
+	return path.join(dir, "trace.jsonl");
+}
+
+function traceErrorPath(dir: string): string {
+	return path.join(dir, "trace-errors.jsonl");
+}
 function isSafeId(value: string): boolean {
 	return (
 		/^[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/.test(value) &&
@@ -469,6 +632,12 @@ function assertKnownWorker(config: GjcTeamConfig, worker: string, allowLeader =
 	if (allowLeader && isLeaderRecipient(worker)) return;
 	if (!config.workers.some(candidate => candidate.id === worker)) throw new Error(`unknown_worker:${worker}`);
 }
+function findKnownWorker(config: GjcTeamConfig, worker: string): GjcTeamWorker {
+	assertKnownWorker(config, worker);
+	const found = config.workers.find(candidate => candidate.id === worker);
+	if (!found) throw new Error(`unknown_worker:${worker}`);
+	return found;
+}
 function assertKnownParticipant(config: GjcTeamConfig, worker: string): void {
 	assertKnownWorker(config, worker, true);
 }
@@ -503,33 +672,171 @@ async function readJsonFile<T>(filePath: string): Promise<T | null> {
 		throw error;
 	}
 }
+function stateCategoryForJsonPath(filePath: string): "state" | "ledger" {
+	return filePath.endsWith(".jsonl") || filePath.includes(`${path.sep}telemetry${path.sep}`) ? "ledger" : "state";
+}
+
 async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
-	await fs.mkdir(path.dirname(filePath), { recursive: true });
-	const tmpPath = `${filePath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
-	await Bun.write(tmpPath, `${JSON.stringify(value, null, 2)}\n`);
-	await fs.rename(tmpPath, filePath);
+	await writeJsonAtomic(filePath, value, stateWriterOptions(filePath, stateCategoryForJsonPath(filePath), "write"));
 }
 async function writeJsonFileNoClobber(filePath: string, value: unknown): Promise<boolean> {
-	await fs.mkdir(path.dirname(filePath), { recursive: true });
-	let handle: fs.FileHandle | undefined;
 	try {
-		handle = await fs.open(filePath, "wx");
-		await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf-8");
+		await createJsonNoClobber(
+			filePath,
+			value,
+			stateWriterOptions(filePath, stateCategoryForJsonPath(filePath), "create"),
+		);
 		return true;
 	} catch (error) {
-		if (isEexist(error)) return false;
+		if (error instanceof AlreadyExistsError) return false;
 		throw error;
-	} finally {
-		await handle?.close();
 	}
 }
 async function appendJsonl(filePath: string, value: unknown): Promise<void> {
-	await fs.mkdir(path.dirname(filePath), { recursive: true });
-	await fs.appendFile(filePath, `${JSON.stringify(value)}\n`, "utf-8");
+	await appendJsonlAudited(filePath, value, stateWriterOptions(filePath, "ledger", "append"));
+}
+function traceIdForTeam(dir: string): string {
+	return `trace-${stableHash(path.basename(dir))}`;
+}
+
+function evidenceRefsForEvent(event: GjcTeamEvent): string[] | undefined {
+	const refs: string[] = [];
+	if (event.task_id && event.type === "task_transitioned" && event.data && "completion_evidence" in event.data)
+		refs.push(`task:${event.task_id}:completion_evidence`);
+	if (event.task_id && event.type === "task_claim_recovered") refs.push(`task:${event.task_id}:claim_recovery`);
+	if (event.worker && event.type.startsWith("worker_")) refs.push(`worker:${event.worker}`);
+	return refs.length > 0 ? refs : undefined;
+}
+function pickString(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+function pickNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function pickBoolean(value: unknown): boolean | undefined {
+	return typeof value === "boolean" ? value : undefined;
+}
+function pickStringArray(value: unknown): string[] | undefined {
+	return Array.isArray(value) && value.every(item => typeof item === "string") ? value : undefined;
+}
+function setIfDefined(record: Record<string, unknown>, key: string, value: unknown): void {
+	if (value !== undefined) record[key] = value;
+}
+function messageBodyTraceProjection(body: string | undefined): Record<string, unknown> {
+	if (body === undefined) return {};
+	return {
+		body_byte_length: Buffer.byteLength(body, "utf8"),
+		body_sha256: createHash("sha256").update(body).digest("hex"),
+	};
+}
+function traceDataForEvent(event: GjcTeamEvent): Record<string, unknown> | undefined {
+	const source = event.data ?? {};
+	const data: Record<string, unknown> = {};
+	switch (event.type) {
+		case "message_sent": {
+			setIfDefined(data, "to_worker", pickString(source.to_worker));
+			setIfDefined(data, "message_id", pickString(source.message_id));
+			Object.assign(data, messageBodyTraceProjection(pickString(event.message)));
+			break;
+		}
+		case "message_acknowledged":
+		case "message_notified": {
+			setIfDefined(data, "message_id", pickString(event.message));
+			break;
+		}
+		case "team_started": {
+			setIfDefined(data, "worker_count", pickNumber(source.worker_count));
+			setIfDefined(data, "agent_type", pickString(source.agent_type));
+			setIfDefined(data, "workspace_mode", pickString(source.workspace_mode));
+			setIfDefined(data, "dry_run", pickBoolean(source.dry_run));
+			break;
+		}
+		case "task_claim_recovered": {
+			setIfDefined(data, "reasons", pickStringArray(source.reasons));
+			break;
+		}
+		case "task_transitioned": {
+			setIfDefined(data, "status", pickString(source.status));
+			const evidence = source.completion_evidence;
+			if (typeof evidence === "object" && evidence !== null) {
+				const evidenceRecord = evidence as Record<string, unknown>;
+				data.completion_evidence = {
+					recorded_by: pickString(evidenceRecord.recorded_by),
+					item_count: pickNumber(evidenceRecord.item_count),
+					verified_item_count: pickNumber(evidenceRecord.verified_item_count),
+				};
+			}
+			break;
+		}
+		case "worker_integration_attempt_requested": {
+			setIfDefined(data, "worker_name", pickString(source.worker_name));
+			setIfDefined(data, "worker_head", pickString(source.worker_head));
+			setIfDefined(data, "status", pickString(source.status));
+			if (Array.isArray(source.files)) data.file_count = source.files.length;
+			break;
+		}
+		case "worker_lifecycle_nudge": {
+			setIfDefined(data, "condition", pickString(source.condition));
+			setIfDefined(data, "severity", pickString(source.severity));
+			setIfDefined(data, "fingerprint", pickString(source.fingerprint));
+			setIfDefined(data, "auto_action_taken", pickBoolean(source.auto_action_taken));
+			break;
+		}
+		case "team_shutdown": {
+			setIfDefined(data, "phase", pickString(source.phase));
+			setIfDefined(data, "shutdown_request_id", pickString(source.shutdown_request_id));
+			setIfDefined(data, "graceful_shutdown_complete", pickBoolean(source.graceful_shutdown_complete));
+			if (Array.isArray(source.evidence_failures)) data.evidence_failure_count = source.evidence_failures.length;
+			break;
+		}
+		case "worker_status_updated": {
+			setIfDefined(data, "status", pickString(source.status));
+			setIfDefined(data, "current_task_id", pickString(source.current_task_id));
+			break;
+		}
+		case "worker_shutdown_requested": {
+			setIfDefined(data, "requested_by", pickString(source.requested_by));
+			setIfDefined(data, "request_id", pickString(source.request_id));
+			setIfDefined(data, "mode", pickString(source.mode));
+			break;
+		}
+	}
+	return Object.keys(data).length > 0 ? data : undefined;
+}
+
+async function appendTraceForEvent(dir: string, event: GjcTeamEvent): Promise<void> {
+	const evidenceRefs = evidenceRefsForEvent(event);
+	const traceData = traceDataForEvent(event);
+	const trace: GjcTeamTraceEvent = {
+		schema_version: 1,
+		trace_id: traceIdForTeam(dir),
+		span_id: `span-${stableHash(event.event_id)}`,
+		source_event_id: event.event_id,
+		event_type: event.type,
+		ts: event.ts,
+		...(event.worker ? { worker: event.worker } : {}),
+		...(event.task_id ? { task_id: event.task_id } : {}),
+		...(traceData ? { data: traceData } : {}),
+		...(evidenceRefs ? { evidence_refs: evidenceRefs } : {}),
+	};
+	try {
+		await appendJsonl(tracePath(dir), trace);
+	} catch (error) {
+		try {
+			await appendJsonl(traceErrorPath(dir), {
+				ts: now(),
+				source_event_id: event.event_id,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		} catch {
+			// Trace append failure must not break legacy events.jsonl compatibility.
+		}
+	}
 }
 async function appendEvent(dir: string, event: Omit<GjcTeamEvent, "ts" | "event_id">): Promise<GjcTeamEvent> {
 	const full = { event_id: `evt-${Date.now()}-${Math.random().toString(16).slice(2)}`, ts: now(), ...event };
 	await appendJsonl(path.join(dir, "events.jsonl"), full);
+	await appendTraceForEvent(dir, full);
 	return full;
 }
 async function appendTelemetry(
@@ -562,6 +869,325 @@ async function readPhase(dir: string): Promise<GjcTeamPhase> {
 async function writePhase(dir: string, phase: GjcTeamPhase): Promise<void> {
 	await writeJsonFile(path.join(dir, "phase.json"), { current_phase: phase, updated_at: now() });
 }
+function isGjcWorkerStatusState(value: string): value is GjcWorkerStatusState {
+	return ["idle", "working", "blocked", "done", "failed", "draining", "unknown"].includes(value);
+}
+
+function parseGjcWorkerStatusState(value: unknown): GjcWorkerStatusState {
+	return typeof value === "string" && isGjcWorkerStatusState(value) ? value : "unknown";
+}
+function parseRequiredGjcWorkerStatusState(value: unknown): GjcWorkerStatusState {
+	const raw = typeof value === "string" ? value.trim() : "";
+	if (isGjcWorkerStatusState(raw)) return raw;
+	throw new Error(`invalid_worker_status:${raw}`);
+}
+
+function lifecycleStateForWorkerStatus(status: GjcWorkerStatusState): GjcTeamWorkerLifecycleState {
+	switch (status) {
+		case "working":
+			return "working";
+		case "draining":
+			return "draining";
+		case "failed":
+			return "failed";
+		case "unknown":
+			return "unknown";
+		case "idle":
+		case "blocked":
+		case "done":
+			return "ready";
+	}
+}
+
+function parseGjcTeamShutdownMode(value: unknown): GjcTeamShutdownMode {
+	const raw = typeof value === "string" ? value.trim() : "graceful";
+	if (raw === "graceful" || raw === "force" || raw === "abort") return raw;
+	throw new Error(`invalid_shutdown_mode:${raw}`);
+}
+
+function isGjcTeamWorkerLifecycleState(value: string): value is GjcTeamWorkerLifecycleState {
+	return ["starting", "ready", "working", "draining", "stopped", "failed", "unknown"].includes(value);
+}
+
+function parseGjcTeamWorkerLifecycleState(value: unknown): GjcTeamWorkerLifecycleState {
+	return typeof value === "string" && isGjcTeamWorkerLifecycleState(value) ? value : "unknown";
+}
+
+async function readWorkerStatusFile(dir: string, worker: string): Promise<WorkerStatusFile> {
+	return (
+		(await readJsonFile<WorkerStatusFile>(path.join(workerDir(dir, worker), "status.json"))) ?? {
+			state: "unknown",
+			updated_at: now(),
+		}
+	);
+}
+
+async function readWorkerLifecycleRecord(dir: string, worker: GjcTeamWorker): Promise<GjcTeamWorkerLifecycle> {
+	const workerStatus = await readWorkerStatusFile(dir, worker.id);
+	const heartbeat = await readJsonFile<WorkerHeartbeatFile>(path.join(workerDir(dir, worker.id), "heartbeat.json"));
+	const rawLifecycle = await readJsonFile<Partial<GjcTeamWorkerLifecycle>>(workerLifecyclePath(dir, worker.id));
+	const shutdownAck = await readJsonFile<Record<string, unknown>>(
+		path.join(workerDir(dir, worker.id), "shutdown-ack.json"),
+	);
+	const lifecycle: GjcTeamWorkerLifecycle = {
+		worker: worker.id,
+		lifecycle_state: parseGjcTeamWorkerLifecycleState(rawLifecycle?.lifecycle_state),
+		worker_status_state: parseGjcWorkerStatusState(workerStatus.state),
+		pane_id: worker.pane_id ?? rawLifecycle?.pane_id,
+		updated_at: rawLifecycle?.updated_at ?? workerStatus.updated_at ?? now(),
+	};
+	if (typeof rawLifecycle?.pid === "number") lifecycle.pid = rawLifecycle.pid;
+	else if (typeof heartbeat?.pid === "number") lifecycle.pid = heartbeat.pid;
+	if (rawLifecycle?.started_at) lifecycle.started_at = rawLifecycle.started_at;
+	if (rawLifecycle?.stopped_at) lifecycle.stopped_at = rawLifecycle.stopped_at;
+	if (rawLifecycle?.stop_reason) lifecycle.stop_reason = rawLifecycle.stop_reason;
+	if (rawLifecycle?.shutdown_request_id) lifecycle.shutdown_request_id = rawLifecycle.shutdown_request_id;
+	if (rawLifecycle?.shutdown_requested_at) lifecycle.shutdown_requested_at = rawLifecycle.shutdown_requested_at;
+	if (
+		rawLifecycle?.shutdown_mode === "graceful" ||
+		rawLifecycle?.shutdown_mode === "force" ||
+		rawLifecycle?.shutdown_mode === "abort"
+	)
+		lifecycle.shutdown_mode = rawLifecycle.shutdown_mode;
+	if (typeof shutdownAck?.acknowledged_at === "string")
+		lifecycle.shutdown_acknowledged_at = shutdownAck.acknowledged_at;
+	if (typeof shutdownAck?.status === "string") lifecycle.shutdown_ack_status = shutdownAck.status;
+	return lifecycle;
+}
+
+async function readWorkerLifecycleById(
+	dir: string,
+	config: GjcTeamConfig,
+): Promise<Record<string, GjcTeamWorkerLifecycle>> {
+	const entries = await Promise.all(config.workers.map(worker => readWorkerLifecycleRecord(dir, worker)));
+	return Object.fromEntries(entries.map(entry => [entry.worker, entry]));
+}
+
+async function writeWorkerLifecycleRecord(
+	dir: string,
+	worker: GjcTeamWorker,
+	lifecycleState: GjcTeamWorkerLifecycleState,
+	updates: Partial<GjcTeamWorkerLifecycle> = {},
+): Promise<GjcTeamWorkerLifecycle> {
+	const current = await readWorkerLifecycleRecord(dir, worker);
+	const next: GjcTeamWorkerLifecycle = {
+		...current,
+		...updates,
+		worker: worker.id,
+		lifecycle_state: lifecycleState,
+		worker_status_state: current.worker_status_state,
+		pane_id: updates.pane_id ?? worker.pane_id ?? current.pane_id,
+		updated_at: now(),
+	};
+	await writeJsonFile(workerLifecyclePath(dir, worker.id), next);
+	return next;
+}
+
+async function writeWorkerLifecycleForConfig(
+	dir: string,
+	config: GjcTeamConfig,
+	lifecycleState: GjcTeamWorkerLifecycleState,
+	updatesFor: (worker: GjcTeamWorker) => Partial<GjcTeamWorkerLifecycle> = () => ({}),
+): Promise<Record<string, GjcTeamWorkerLifecycle>> {
+	const entries = await Promise.all(
+		config.workers.map(worker => writeWorkerLifecycleRecord(dir, worker, lifecycleState, updatesFor(worker))),
+	);
+	return Object.fromEntries(entries.map(entry => [entry.worker, entry]));
+}
+
+function teamModeStatePath(): string {
+	return path.join(".gjc", "state", "team-state.json");
+}
+
+export async function persistGjcTeamModeStateSummary(snapshot: GjcTeamSnapshot, cwd = process.cwd()): Promise<void> {
+	const active = snapshot.phase !== "complete" && snapshot.phase !== "cancelled";
+	const updatedAt = now();
+	await writeWorkflowEnvelopeAtomic(
+		teamModeStatePath(),
+		{
+			skill: "team",
+			version: WORKFLOW_STATE_VERSION,
+			active,
+			current_phase: snapshot.phase,
+			team_name: snapshot.team_name,
+			task_counts: snapshot.task_counts,
+			updated_at: updatedAt,
+		},
+		{
+			cwd,
+			receipt: {
+				cwd,
+				skill: "team",
+				owner: "gjc-runtime",
+				command: "gjc team sync-team-summary",
+				nowIso: updatedAt,
+			},
+			audit: { category: "state", verb: "sync-team-summary", owner: "gjc-runtime", skill: "team" },
+		},
+	);
+}
+
+function appendLivenessRecoveryReason(
+	reasons: GjcTeamLivenessRecoveryReason[],
+	reason: GjcTeamLivenessRecoveryReason,
+): void {
+	if (!reasons.includes(reason)) reasons.push(reason);
+}
+
+function isPastTimestamp(value: string | undefined): boolean {
+	if (!value) return false;
+	const timestamp = Date.parse(value);
+	return Number.isFinite(timestamp) && timestamp <= Date.now();
+}
+
+function readClaimRecord(value: unknown): GjcTeamTaskClaim | undefined {
+	if (!isRecord(value)) return undefined;
+	const owner = typeof value.owner === "string" ? value.owner : "";
+	const token = typeof value.token === "string" ? value.token : "";
+	const leasedUntil = typeof value.leased_until === "string" ? value.leased_until : "";
+	if (!owner || !token || !leasedUntil) return undefined;
+	return { owner, token, leased_until: leasedUntil };
+}
+
+function isWorkerHeartbeatStale(
+	worker: GjcTeamWorker,
+	heartbeat: WorkerHeartbeatFile | null,
+	env: NodeJS.ProcessEnv,
+): boolean {
+	const thresholdMs = parseDurationEnv(env, "GJC_TEAM_HEARTBEAT_STALE_MS", 120_000);
+	if (thresholdMs <= 0) return false;
+	const heartbeatAt = Date.parse(heartbeat?.last_turn_at ?? worker.last_heartbeat);
+	return Number.isFinite(heartbeatAt) && Date.now() - heartbeatAt >= thresholdMs;
+}
+
+async function detectGjcTeamWorkerLivenessReasons(
+	dir: string,
+	config: GjcTeamConfig,
+	worker: GjcTeamWorker,
+	env: NodeJS.ProcessEnv,
+): Promise<GjcTeamLivenessRecoveryReason[]> {
+	const reasons: GjcTeamLivenessRecoveryReason[] = [];
+	const lifecycle = await readWorkerLifecycleRecord(dir, worker);
+	const heartbeat = await readJsonFile<WorkerHeartbeatFile>(path.join(workerDir(dir, worker.id), "heartbeat.json"));
+	if (lifecycle.lifecycle_state === "failed") appendLivenessRecoveryReason(reasons, "worker_lifecycle_failed");
+	if (lifecycle.lifecycle_state === "stopped") appendLivenessRecoveryReason(reasons, "worker_lifecycle_stopped");
+	if (isWorkerHeartbeatStale(worker, heartbeat, env)) appendLivenessRecoveryReason(reasons, "stale_heartbeat");
+	if (!config.dry_run && (!worker.pane_id?.startsWith("%") || !paneBelongsToTeamTarget(config, worker.pane_id)))
+		appendLivenessRecoveryReason(reasons, "missing_pane");
+	return reasons;
+}
+
+async function reconcileGjcTeamStaleClaims(
+	teamName: string,
+	dir: string,
+	config: GjcTeamConfig,
+	env: NodeJS.ProcessEnv,
+): Promise<GjcTeamLivenessRecoveryResult> {
+	const staleWorkers: Record<string, GjcTeamLivenessRecoveryReason[]> = {};
+	for (const worker of config.workers) {
+		const reasons = await detectGjcTeamWorkerLivenessReasons(dir, config, worker, env);
+		if (reasons.length === 0) continue;
+		staleWorkers[worker.id] = reasons;
+		if (reasons.includes("missing_pane") && reasons.includes("worker_lifecycle_stopped") === false) {
+			await writeWorkerLifecycleRecord(dir, worker, "failed", { stop_reason: "pane_missing" });
+		}
+	}
+
+	const recoveredClaims: GjcTeamRecoveredClaim[] = [];
+	for (const task of await readTasks(dir)) {
+		if (task.status === "completed" || task.status === "failed") continue;
+		const claimPath = path.join(dir, "claims", `${task.id}.json`);
+		const diskClaim = readClaimRecord(await readJsonFile<unknown>(claimPath));
+		const claim = task.claim ?? diskClaim;
+		if (!claim) continue;
+
+		const reasons = [...(staleWorkers[claim.owner] ?? [])];
+		if (isPastTimestamp(claim.leased_until)) appendLivenessRecoveryReason(reasons, "claim_expired");
+		if (reasons.length === 0) continue;
+
+		await fs.rm(claimPath, { force: true });
+		recoveredClaims.push({ task_id: task.id, worker: claim.owner, reasons });
+		if (task.status !== "in_progress") {
+			await appendEvent(dir, {
+				type: "task_claim_recovered",
+				task_id: task.id,
+				worker: claim.owner,
+				message: "Removed stale task claim file",
+				data: { reasons },
+			});
+			continue;
+		}
+
+		const recoveredTask = normalizeTask({
+			...task,
+			status: "pending",
+			assignee: undefined,
+			claim: undefined,
+			version: task.version + 1,
+			updated_at: now(),
+		});
+		await writeTask(dir, recoveredTask);
+		await appendEvent(dir, {
+			type: "task_claim_recovered",
+			task_id: task.id,
+			worker: claim.owner,
+			message: "Recovered task from stale worker claim",
+			data: { reasons },
+		});
+	}
+
+	if (recoveredClaims.length > 0)
+		await appendTelemetry(dir, {
+			type: "team_liveness_recovery",
+			message: `Recovered ${recoveredClaims.length} stale team task claim(s)`,
+			data: { team_name: teamName, recovered_claims: recoveredClaims },
+		});
+
+	return { recovered_claims: recoveredClaims, stale_workers: staleWorkers };
+}
+
+export async function recoverGjcTeamStaleClaims(
+	teamName: string,
+	cwd = process.cwd(),
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<GjcTeamLivenessRecoveryResult> {
+	const dir = await findTeamDir(teamName, cwd, env);
+	const config = await readConfig(dir);
+	return reconcileGjcTeamStaleClaims(teamName, dir, config, env);
+}
+function normalizeOptionalTaskString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed || undefined;
+}
+
+function normalizeOptionalTaskStringArray(value: unknown): string[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const items = Array.from(
+		new Set(value.map(item => (typeof item === "string" ? item.trim() : "")).filter(item => item.length > 0)),
+	).sort();
+	return items.length > 0 ? items : undefined;
+}
+type GjcTeamTaskMetadataInput = Partial<
+	Pick<GjcTeamTask, "owner" | "lane" | "required_role" | "allowed_roles" | "depends_on" | "blocked_by">
+>;
+
+function taskMetadataFromInput(input: Record<string, unknown>, includeOwner = false): GjcTeamTaskMetadataInput {
+	const metadata: GjcTeamTaskMetadataInput = {};
+	const owner = normalizeOptionalTaskString(input.owner);
+	const lane = normalizeOptionalTaskString(input.lane);
+	const requiredRole = normalizeOptionalTaskString(input.required_role ?? input.requiredRole);
+	const allowedRoles = normalizeOptionalTaskStringArray(input.allowed_roles ?? input.allowedRoles);
+	const dependsOn = normalizeOptionalTaskStringArray(input.depends_on ?? input.dependsOn);
+	const blockedBy = normalizeOptionalTaskStringArray(input.blocked_by ?? input.blockedBy);
+	if (includeOwner && owner) metadata.owner = owner;
+	if (lane) metadata.lane = lane;
+	if (requiredRole) metadata.required_role = requiredRole;
+	if (allowedRoles) metadata.allowed_roles = allowedRoles;
+	if (dependsOn) metadata.depends_on = dependsOn;
+	if (blockedBy) metadata.blocked_by = blockedBy;
+	return metadata;
+}
 
 function normalizeTask(raw: GjcTeamTask): GjcTeamTask {
 	const status = raw.status === ("complete" as GjcTeamTaskStatus) ? "completed" : raw.status;
@@ -573,6 +1199,9 @@ function normalizeTask(raw: GjcTeamTask): GjcTeamTask {
 		title: raw.title ?? raw.subject,
 		objective: raw.objective ?? raw.description,
 		version: raw.version ?? 1,
+		lane: normalizeOptionalTaskString(raw.lane),
+		required_role: normalizeOptionalTaskString(raw.required_role),
+		allowed_roles: normalizeOptionalTaskStringArray(raw.allowed_roles),
 	};
 }
 
@@ -616,13 +1245,189 @@ async function resolveGjcTeamSnapshotPhase(
 	monitor: GjcTeamMonitorSnapshot | null,
 ): Promise<GjcTeamPhase> {
 	if (storedPhase !== "running") return storedPhase;
-	if (tasks.length === 0 || !tasks.every(task => task.status === "completed")) return storedPhase;
+	if (tasks.length === 0 || !tasks.every(isGjcTeamTaskCompletionVerified)) return storedPhase;
 	return (await hasPendingGjcTeamIntegration(dir, config, monitor)) ? "awaiting_integration" : storedPhase;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value != null;
 }
+const GJC_TEAM_COMPLETION_EVIDENCE_SUMMARY_MAX = 4_000;
+const GJC_TEAM_COMPLETION_EVIDENCE_OUTPUT_MAX = 8_000;
+const GJC_TEAM_COMMAND_EVIDENCE_STATUSES = new Set<GjcTeamTaskCompletionEvidenceStatus>([
+	"passed",
+	"failed",
+	"not_run",
+]);
+const GJC_TEAM_VERIFICATION_EVIDENCE_STATUSES = new Set<GjcTeamTaskCompletionEvidenceStatus>(["verified", "rejected"]);
+
+function completionEvidenceError(taskId: string, field: string): Error {
+	return new Error(`invalid_completion_evidence:${taskId}:${field}`);
+}
+
+function trimRequiredCompletionEvidenceString(
+	taskId: string,
+	field: string,
+	value: unknown,
+	maxLength = GJC_TEAM_COMPLETION_EVIDENCE_SUMMARY_MAX,
+): string {
+	if (typeof value !== "string") throw completionEvidenceError(taskId, field);
+	const trimmed = value.trim();
+	if (!trimmed || trimmed.length > maxLength) throw completionEvidenceError(taskId, field);
+	return trimmed;
+}
+
+function trimOptionalCompletionEvidenceString(
+	taskId: string,
+	field: string,
+	value: unknown,
+	maxLength = GJC_TEAM_COMPLETION_EVIDENCE_OUTPUT_MAX,
+): string | undefined {
+	if (value == null) return undefined;
+	if (typeof value !== "string") throw completionEvidenceError(taskId, field);
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+	if (trimmed.length > maxLength) throw completionEvidenceError(taskId, field);
+	return trimmed;
+}
+
+function normalizeGjcTeamCompletionEvidenceStatus(
+	taskId: string,
+	kind: GjcTeamTaskCompletionEvidenceKind,
+	value: unknown,
+): GjcTeamTaskCompletionEvidenceStatus {
+	const status = trimRequiredCompletionEvidenceString(taskId, "items.status", value);
+	const allowed = kind === "command" ? GJC_TEAM_COMMAND_EVIDENCE_STATUSES : GJC_TEAM_VERIFICATION_EVIDENCE_STATUSES;
+	if (!allowed.has(status as GjcTeamTaskCompletionEvidenceStatus))
+		throw completionEvidenceError(taskId, "items.status");
+	return status as GjcTeamTaskCompletionEvidenceStatus;
+}
+
+function normalizeGjcTeamCompletionEvidenceItem(taskId: string, value: unknown): GjcTeamTaskCompletionEvidenceItem {
+	if (!isRecord(value) || Array.isArray(value)) throw completionEvidenceError(taskId, "items");
+	const kind = trimRequiredCompletionEvidenceString(taskId, "items.kind", value.kind);
+	if (kind !== "command" && kind !== "inspection" && kind !== "artifact")
+		throw completionEvidenceError(taskId, "items.kind");
+	const status = normalizeGjcTeamCompletionEvidenceStatus(taskId, kind, value.status);
+	const item: GjcTeamTaskCompletionEvidenceItem = {
+		kind,
+		status,
+		summary: trimRequiredCompletionEvidenceString(taskId, "items.summary", value.summary),
+	};
+	const command = trimOptionalCompletionEvidenceString(taskId, "items.command", value.command);
+	const artifact = trimOptionalCompletionEvidenceString(taskId, "items.artifact", value.artifact);
+	const location = trimOptionalCompletionEvidenceString(taskId, "items.location", value.location);
+	const output = trimOptionalCompletionEvidenceString(taskId, "items.output", value.output);
+	if (kind === "command" && !command) throw completionEvidenceError(taskId, "items.command");
+	if (command) item.command = command;
+	if (artifact) item.artifact = artifact;
+	if (location) item.location = location;
+	if (output) item.output = output;
+	return item;
+}
+
+function normalizeGjcTeamCompletionEvidenceFiles(taskId: string, value: unknown): string[] | undefined {
+	if (value == null) return undefined;
+	if (!Array.isArray(value)) throw completionEvidenceError(taskId, "files");
+	const files = new Set<string>();
+	for (const entry of value) {
+		if (typeof entry !== "string") throw completionEvidenceError(taskId, "files");
+		const filePath = entry.trim().replace(/\\/g, "/");
+		if (!filePath || filePath.includes("\0") || path.isAbsolute(filePath) || filePath.split("/").includes("..")) {
+			throw completionEvidenceError(taskId, "files");
+		}
+		files.add(filePath);
+	}
+	return files.size > 0 ? [...files].sort() : undefined;
+}
+
+function isGjcTeamCompletionEvidenceItemVerified(item: GjcTeamTaskCompletionEvidenceItem): boolean {
+	return (
+		(item.kind === "command" && item.status === "passed") ||
+		((item.kind === "inspection" || item.kind === "artifact") && item.status === "verified")
+	);
+}
+
+function normalizeGjcTeamTaskCompletionEvidence(
+	taskId: string,
+	owner: string,
+	input: unknown,
+	recordedAt = now(),
+): GjcTeamTaskCompletionEvidence {
+	if (!isRecord(input) || Array.isArray(input)) throw new Error(`completion_evidence_required:${taskId}`);
+	const itemsValue = input.items;
+	if (!Array.isArray(itemsValue) || itemsValue.length === 0) throw completionEvidenceError(taskId, "items");
+	const items = itemsValue.map(item => normalizeGjcTeamCompletionEvidenceItem(taskId, item));
+	if (!items.some(isGjcTeamCompletionEvidenceItemVerified))
+		throw new Error(`completion_evidence_no_verified_item:${taskId}`);
+	const evidence: GjcTeamTaskCompletionEvidence = {
+		summary: trimRequiredCompletionEvidenceString(taskId, "summary", input.summary),
+		items,
+		recorded_by: owner,
+		recorded_at: recordedAt,
+	};
+	const files = normalizeGjcTeamCompletionEvidenceFiles(taskId, input.files);
+	const notes = trimOptionalCompletionEvidenceString(taskId, "notes", input.notes);
+	if (files) evidence.files = files;
+	if (notes) evidence.notes = notes;
+	return evidence;
+}
+
+function getGjcTeamTaskCompletionEvidenceFailure(task: GjcTeamTask): string | null {
+	if (task.status !== "completed") return `task_not_completed:${task.id}`;
+	const evidence = task.completion_evidence;
+	if (!isRecord(evidence) || Array.isArray(evidence)) return `completion_evidence_required:${task.id}`;
+	if (typeof evidence.recorded_by !== "string" || evidence.recorded_by.trim().length === 0)
+		return `invalid_completion_evidence:${task.id}:recorded_by`;
+	if (typeof evidence.recorded_at !== "string" || evidence.recorded_at.trim().length === 0)
+		return `invalid_completion_evidence:${task.id}:recorded_at`;
+	try {
+		normalizeGjcTeamTaskCompletionEvidence(task.id, evidence.recorded_by.trim(), evidence, evidence.recorded_at);
+		return null;
+	} catch (error) {
+		return error instanceof Error ? error.message : `invalid_completion_evidence:${task.id}:unknown`;
+	}
+}
+
+function isGjcTeamTaskCompletionVerified(task: GjcTeamTask): boolean {
+	return getGjcTeamTaskCompletionEvidenceFailure(task) == null;
+}
+function roleValuesForWorker(worker: GjcTeamWorker): Set<string> {
+	return new Set([worker.role, worker.agent_type].map(value => value.trim()).filter(value => value.length > 0));
+}
+
+function getGjcTeamTaskClaimEligibilityReason(
+	task: GjcTeamTask,
+	worker: GjcTeamWorker,
+	tasks: GjcTeamTask[],
+): string | null {
+	if (task.status !== "pending") return `task_not_pending:${task.id}`;
+	if (task.owner && task.owner !== worker.id) return `task_owner_mismatch:${task.id}:${task.owner}`;
+	if (task.assignee && task.assignee !== worker.id) return `task_assignee_mismatch:${task.id}:${task.assignee}`;
+
+	const workerRoles = roleValuesForWorker(worker);
+	if (task.required_role && !workerRoles.has(task.required_role))
+		return `task_role_mismatch:${task.id}:${task.required_role}`;
+	if (task.allowed_roles?.length && !task.allowed_roles.some(role => workerRoles.has(role)))
+		return `task_role_mismatch:${task.id}:${task.allowed_roles.join(",")}`;
+
+	if (task.blocked_by?.length) return `task_blocked:${task.id}:${task.blocked_by.join(",")}`;
+	for (const dependencyId of task.depends_on ?? []) {
+		const dependency = tasks.find(candidate => candidate.id === dependencyId);
+		if (!dependency || !isGjcTeamTaskCompletionVerified(dependency))
+			return `task_dependency_incomplete:${task.id}:${dependencyId}`;
+	}
+
+	return null;
+}
+
+async function getActiveClaimReason(dir: string, task: GjcTeamTask): Promise<string | null> {
+	const claimPath = path.join(dir, "claims", `${task.id}.json`);
+	const diskClaim = readClaimRecord(await readJsonFile<unknown>(claimPath));
+	const claim = task.claim ?? diskClaim;
+	if (!claim || isPastTimestamp(claim.leased_until)) return null;
+	return `task_already_claimed:${task.id}`;
+}
 function isGjcTeamTaskRecord(value: unknown): value is GjcTeamTask {
 	return (
 		isRecord(value) &&
@@ -820,17 +1625,35 @@ async function ensureWorkerWorktree(
 export function resolveGjcTmuxCommand(env: NodeJS.ProcessEnv = process.env): string {
 	return env.GJC_TEAM_TMUX_COMMAND?.trim() || "tmux";
 }
+function buildTeamTmuxLeaderRequirementMessage(detail?: string): string {
+	const suffix = detail?.trim() ? `:${detail.trim()}` : "";
+	return `gjc_team_requires_tmux_leader: run \`gjc --tmux\` first, then run \`gjc team ...\` inside that tmux-backed leader session, or use \`gjc team --dry-run\` for state-only smoke tests${suffix}`;
+}
+function readGjcTmuxProfileValue(tmuxCommand: string, sessionName: string): string {
+	const result = Bun.spawnSync(
+		[tmuxCommand, "show-options", "-qv", "-t", `=${sessionName}`, GJC_TMUX_PROFILE_OPTION],
+		{
+			stdout: "pipe",
+			stderr: "pipe",
+		},
+	);
+	if (result.exitCode !== 0) return "";
+	return result.stdout.toString().trim();
+}
+
 function readCurrentTmuxLeaderContext(tmuxCommand: string, env: NodeJS.ProcessEnv): GjcTmuxLeaderContext {
 	const paneTarget = env.TMUX_PANE?.trim();
 	const args = paneTarget
 		? ["display-message", "-p", "-t", paneTarget, "#S:#I #{pane_id}"]
 		: ["display-message", "-p", "#S:#I #{pane_id}"];
 	const result = Bun.spawnSync([tmuxCommand, ...args], { stdout: "pipe", stderr: "pipe" });
-	if (result.exitCode !== 0) throw new Error(result.stderr.toString().trim() || "team_requires_current_tmux_context");
+	if (result.exitCode !== 0) throw new Error(buildTeamTmuxLeaderRequirementMessage(result.stderr.toString()));
 	const [sessionAndWindow = "", leaderPaneId = ""] = result.stdout.toString().trim().split(/\s+/);
 	const [sessionName = "", windowIndex = ""] = sessionAndWindow.split(":");
 	if (!sessionName || !windowIndex || !leaderPaneId.startsWith("%"))
-		throw new Error(`invalid_tmux_context:${result.stdout.toString().trim()}`);
+		throw new Error(buildTeamTmuxLeaderRequirementMessage(`invalid_tmux_context:${result.stdout.toString().trim()}`));
+	if (readGjcTmuxProfileValue(tmuxCommand, sessionName) !== GJC_TMUX_PROFILE_VALUE)
+		throw new Error(buildTeamTmuxLeaderRequirementMessage(`unmanaged_tmux_session:${sessionName}`));
 	return { sessionName, windowIndex, leaderPaneId, target: `${sessionName}:${windowIndex}` };
 }
 export function resolveGjcWorkerCommand(cwd = process.cwd(), env: NodeJS.ProcessEnv = process.env): string {
@@ -852,7 +1675,7 @@ function buildWorkerCommand(config: GjcTeamConfig, worker: GjcTeamWorker): strin
 		workspace,
 		`Task: ${config.task}`,
 		`Before claiming work, send startup ACK: gjc team api worker-startup-ack --input '{"team_name":"${config.team_name}","worker_id":"${worker.id}","protocol_version":"1"}' --json.`,
-		`Use gjc team api claim-task/transition-task-status with this worker id, record evidence, and do not mutate leader-owned goal state.`,
+		`Use gjc team api update-worker-status to report task-local activity, then claim-task/transition-task-status with this worker id; record completion_evidence (summary plus a passed command or verified inspection/artifact item) before completed, and do not mutate leader-owned goal state.`,
 	].join("\n");
 	const env = [
 		`GJC_TEAM_WORKER=${shellQuote(`${config.team_name}/${worker.id}`)}`,
@@ -1032,9 +1855,18 @@ async function appendIntegrationReport(
 	entry: { worker: string; operation: "merge" | "cherry-pick" | "rebase"; files: string[]; detail: string },
 ): Promise<void> {
 	const line = `- [${now()}] ${entry.worker}: ${entry.operation}; files=${entry.files.join(",") || "unknown"}; ${entry.detail}\n`;
-	await fs.mkdir(path.dirname(integrationReportPath(dir)), { recursive: true });
-	if (await pathExists(integrationReportPath(dir))) await fs.appendFile(integrationReportPath(dir), line, "utf-8");
-	else await Bun.write(integrationReportPath(dir), `# Integration Report\n\n${line}`);
+	if (await pathExists(integrationReportPath(dir)))
+		await appendText(
+			integrationReportPath(dir),
+			line,
+			stateWriterOptions(integrationReportPath(dir), "report", "append"),
+		);
+	else
+		await writeReport(
+			integrationReportPath(dir),
+			`# Integration Report\n\n${line}`,
+			stateWriterOptions(integrationReportPath(dir), "report", "write"),
+		);
 }
 async function appendCommitHygieneEntries(config: GjcTeamConfig, entries: GjcTeamCommitHygieneEntry[]): Promise<void> {
 	if (entries.length === 0) return;
@@ -1583,13 +2415,18 @@ async function integrateGjcWorkerCommits(
 }
 
 async function initializeStateDirs(dir: string, workers: GjcTeamWorker[]): Promise<void> {
-	for (const folder of ["tasks", "claims", "mailbox", "notifications", "dispatch", "approvals", "workers"])
-		await fs.mkdir(path.join(dir, folder), { recursive: true });
+	// Empty mailbox directories are runtime state, so they must exist before messages arrive.
+	await fs.mkdir(path.join(dir, "mailbox"), { recursive: true });
 	for (const worker of workers) {
-		await fs.mkdir(workerDir(dir, worker.id), { recursive: true });
 		await fs.mkdir(mailboxDirPath(dir, worker.id), { recursive: true });
 		await writeJsonFile(mailboxPath(dir, worker.id), { messages: [] });
 		await writeJsonFile(path.join(workerDir(dir, worker.id), "status.json"), { state: "idle", updated_at: now() });
+		await writeJsonFile(workerLifecyclePath(dir, worker.id), {
+			worker: worker.id,
+			lifecycle_state: "starting",
+			worker_status_state: "idle",
+			updated_at: now(),
+		} satisfies GjcTeamWorkerLifecycle);
 		await writeJsonFile(path.join(workerDir(dir, worker.id), "heartbeat.json"), {
 			pid: 0,
 			last_turn_at: now(),
@@ -1597,6 +2434,7 @@ async function initializeStateDirs(dir: string, workers: GjcTeamWorker[]): Promi
 			alive: true,
 		});
 	}
+	// Empty leader mailbox directory is runtime state, so it must exist before messages arrive.
 	await fs.mkdir(mailboxDirPath(dir, "leader-fixed"), { recursive: true });
 	await writeJsonFile(mailboxPath(dir, "leader-fixed"), { messages: [] });
 }
@@ -1714,6 +2552,10 @@ export async function startGjcTeam(options: GjcTeamStartOptions): Promise<GjcTea
 		updated_at: now(),
 	};
 	await writeJsonFile(path.join(dir, "config.json"), runningConfig);
+	await writeWorkerLifecycleForConfig(dir, runningConfig, "starting", worker => ({
+		pane_id: worker.pane_id,
+		started_at: runningConfig.created_at,
+	}));
 	await writePhase(dir, "running");
 	return readGjcTeamSnapshot(teamName, cwd, env);
 }
@@ -1722,6 +2564,7 @@ export async function readGjcTeamSnapshot(
 	teamName: string,
 	cwd = process.cwd(),
 	env: NodeJS.ProcessEnv = process.env,
+	options: GjcTeamSnapshotOptions = {},
 ): Promise<GjcTeamSnapshot> {
 	const dir = await findTeamDir(teamName, cwd, env);
 	const config = await readConfig(dir);
@@ -1736,7 +2579,11 @@ export async function readGjcTeamSnapshot(
 	};
 	for (const task of tasks) taskCounts[task.status] += 1;
 	const monitor = await readJsonFile<GjcTeamMonitorSnapshot>(monitorSnapshotPath(dir));
-	const notificationSummary = await reconcileTeamNotifications(dir, config);
+	const workerLifecycleById = await readWorkerLifecycleById(dir, config);
+	const notificationSummary =
+		options.reconcileNotifications === true
+			? await reconcileTeamNotifications(dir, config)
+			: summarizeNotifications(await listNotificationRecords(dir));
 	const phase = await resolveGjcTeamSnapshotPhase(dir, config, storedPhase, tasks, monitor);
 	return {
 		team_name: config.team_name,
@@ -1750,10 +2597,19 @@ export async function readGjcTeamSnapshot(
 		task_counts: taskCounts,
 		workers: config.workers,
 		integration_by_worker: monitor?.integration_by_worker,
+		worker_lifecycle_by_id: workerLifecycleById,
 		notification_summary: notificationSummary,
 		updated_at: config.updated_at,
 	};
 }
+export async function monitorGjcTeamSnapshot(
+	teamName: string,
+	cwd = process.cwd(),
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<GjcTeamSnapshot> {
+	const snapshot = await monitorGjcTeam(teamName, cwd, env);
+	return snapshot;
+}
 function workerIntegrationFingerprint(head: string | null, classification: GjcWorkerCheckpointClassification): string {
 	return `${head ?? "no-head"}:${classification.kind}:${classification.files.join("\0")}`;
 }
@@ -1864,6 +2720,7 @@ export async function monitorGjcTeam(
 	const dir = await findTeamDir(teamName, cwd, env);
 	const config = await readConfig(dir);
 	const previous = await readJsonFile<GjcTeamMonitorSnapshot>(monitorSnapshotPath(dir));
+	await reconcileGjcTeamStaleClaims(teamName, dir, config, env);
 	const integrationByWorker = await integrateGjcWorkerCommits(config, dir, previous, cwd, env);
 	await writeJsonFile(monitorSnapshotPath(dir), { integration_by_worker: integrationByWorker, updated_at: now() });
 	await replayGjcTeamNotifications(teamName, cwd, env);
@@ -1902,7 +2759,7 @@ async function writeGjcWorkerStartupAck(
 ): Promise<Record<string, unknown>> {
 	const dir = await findTeamDir(teamName, cwd, env);
 	const config = await readConfig(dir);
-	assertKnownWorker(config, worker);
+	const teamWorker = findKnownWorker(config, worker);
 	const ack = {
 		worker,
 		pid: typeof input.pid === "number" ? input.pid : undefined,
@@ -1911,6 +2768,11 @@ async function writeGjcWorkerStartupAck(
 		ack_at: now(),
 	};
 	await writeJsonFile(path.join(workerDir(dir, worker), "startup-ack.json"), ack);
+	await writeWorkerLifecycleRecord(dir, teamWorker, "ready", {
+		pane_id: teamWorker.pane_id,
+		pid: typeof input.pid === "number" ? input.pid : undefined,
+		started_at: ack.ack_at,
+	});
 	await appendEvent(dir, { type: "worker_startup_ack", worker, message: `Worker ${worker} acknowledged startup` });
 	return ack;
 }
@@ -2026,12 +2888,31 @@ export async function shutdownGjcTeam(
 	const dir = await findTeamDir(teamName, cwd, env);
 	const config = await readConfig(dir);
 	const tasks = await readTasks(dir);
-	const shutdownPhase: GjcTeamPhase =
-		tasks.length === 0 || tasks.every(task => task.status === "completed")
-			? "complete"
-			: tasks.some(task => task.status === "failed" || task.status === "blocked")
-				? "failed"
-				: "cancelled";
+	const evidenceFailures = tasks
+		.map(task => {
+			const reason = task.status === "completed" ? getGjcTeamTaskCompletionEvidenceFailure(task) : null;
+			return reason ? { task_id: task.id, reason } : null;
+		})
+		.filter((failure): failure is { task_id: string; reason: string } => failure != null);
+	const shutdownRequestId = `shutdown-${stableHash([config.team_name, now(), randomUUID()].join(":"))}`;
+	const shutdownRequestedAt = now();
+	await Promise.all(
+		config.workers.map(worker =>
+			writeGjcShutdownRequest(
+				teamName,
+				worker.id,
+				"leader-fixed",
+				cwd,
+				env,
+				shutdownRequestId,
+				"graceful",
+				shutdownRequestedAt,
+			),
+		),
+	);
+	const monitor = await readJsonFile<GjcTeamMonitorSnapshot>(monitorSnapshotPath(dir));
+	const completionVerified = tasks.length === 0 || tasks.every(isGjcTeamTaskCompletionVerified);
+	const pendingIntegration = completionVerified ? await hasPendingGjcTeamIntegration(dir, config, monitor) : false;
 	killWorkerPanes(config);
 	await removeCleanCreatedWorktrees(config.workers);
 	const stopped = {
@@ -2040,18 +2921,50 @@ export async function shutdownGjcTeam(
 		updated_at: now(),
 	};
 	await writeJsonFile(path.join(dir, "config.json"), stopped);
+	await writeWorkerLifecycleForConfig(dir, stopped, "stopped", worker => ({
+		pane_id: worker.pane_id,
+		stopped_at: stopped.updated_at,
+		stop_reason: "graceful_shutdown",
+		shutdown_request_id: shutdownRequestId,
+		shutdown_requested_at: shutdownRequestedAt,
+		shutdown_mode: "graceful",
+	}));
+	const workerLifecycleById = await readWorkerLifecycleById(dir, stopped);
+	const gracefulShutdownComplete = stopped.workers.every(worker => {
+		const lifecycle = workerLifecycleById[worker.id];
+		return (
+			lifecycle?.lifecycle_state === "stopped" &&
+			lifecycle.shutdown_request_id === shutdownRequestId &&
+			lifecycle.shutdown_mode === "graceful"
+		);
+	});
+	const shutdownPhase: GjcTeamPhase =
+		completionVerified && gracefulShutdownComplete
+			? pendingIntegration
+				? "awaiting_integration"
+				: "complete"
+			: evidenceFailures.length > 0 || tasks.some(task => task.status === "failed" || task.status === "blocked")
+				? "failed"
+				: "cancelled";
 	await writePhase(dir, shutdownPhase);
+	const shutdownData: Record<string, unknown> = {
+		phase: shutdownPhase,
+		shutdown_request_id: shutdownRequestId,
+		graceful_shutdown_complete: gracefulShutdownComplete,
+	};
+	if (evidenceFailures.length > 0) shutdownData.evidence_failures = evidenceFailures;
 	await appendEvent(dir, {
 		type: "team_shutdown",
 		message:
 			shutdownPhase === "complete"
 				? "Shut down native gjc team runtime after completed tasks"
 				: "Shut down native gjc team runtime with incomplete tasks",
-		data: { phase: shutdownPhase },
+		data: shutdownData,
 	});
 	await appendTelemetry(dir, {
 		type: "team_shutdown",
 		message: `Native gjc team runtime stopped with phase ${shutdownPhase}`,
+		data: { shutdown_request_id: shutdownRequestId, graceful_shutdown_complete: gracefulShutdownComplete },
 	});
 	return readGjcTeamSnapshot(config.team_name, cwd, env);
 }
@@ -2079,9 +2992,11 @@ export async function createGjcTeamTask(
 	description: string,
 	cwd = process.cwd(),
 	env: NodeJS.ProcessEnv = process.env,
+	taskOptions: GjcTeamTaskMetadataInput = {},
 ): Promise<GjcTeamTask> {
 	const dir = await findTeamDir(teamName, cwd, env);
 	const config = await readConfig(dir);
+	if (taskOptions.owner) assertKnownWorker(config, taskOptions.owner);
 	const tasks = await readTasks(dir);
 	const next = tasks.length + 1;
 	const task: GjcTeamTask = {
@@ -2091,6 +3006,12 @@ export async function createGjcTeamTask(
 		title: subject,
 		objective: description,
 		status: "pending",
+		...(taskOptions.owner ? { owner: taskOptions.owner } : {}),
+		...(taskOptions.lane ? { lane: taskOptions.lane } : {}),
+		...(taskOptions.required_role ? { required_role: taskOptions.required_role } : {}),
+		...(taskOptions.allowed_roles ? { allowed_roles: taskOptions.allowed_roles } : {}),
+		...(taskOptions.depends_on ? { depends_on: taskOptions.depends_on } : {}),
+		...(taskOptions.blocked_by ? { blocked_by: taskOptions.blocked_by } : {}),
 		version: 1,
 		created_at: now(),
 		updated_at: now(),
@@ -2104,7 +3025,12 @@ export async function createGjcTeamTask(
 export async function updateGjcTeamTask(
 	teamName: string,
 	taskId: string,
-	updates: Partial<Pick<GjcTeamTask, "subject" | "description" | "blocked_by" | "depends_on">>,
+	updates: Partial<
+		Pick<
+			GjcTeamTask,
+			"subject" | "description" | "blocked_by" | "depends_on" | "lane" | "required_role" | "allowed_roles"
+		>
+	>,
 	cwd = process.cwd(),
 	env: NodeJS.ProcessEnv = process.env,
 ): Promise<GjcTeamTask> {
@@ -2131,13 +3057,20 @@ export async function claimGjcTeamTask(
 ): Promise<GjcTeamApiClaimResult> {
 	const dir = await findTeamDir(teamName, cwd, env);
 	const config = await readConfig(dir);
-	assertKnownWorker(config, workerId);
+	const teamWorker = findKnownWorker(config, workerId);
+	const livenessRecovery = await reconcileGjcTeamStaleClaims(teamName, dir, config, env);
+	const staleWorkerReasons = livenessRecovery.stale_workers[workerId];
+	if (staleWorkerReasons?.length)
+		return { ok: false, reason: `worker_not_live:${workerId}:${staleWorkerReasons.join(",")}` };
 	const tasks = await readTasks(dir);
 	const task = taskId
 		? tasks.find(candidate => candidate.id === taskId)
-		: tasks.find(candidate => candidate.status === "pending" && (!candidate.owner || candidate.owner === workerId));
-	if (!task) return { ok: false, reason: "no_pending_task" };
-	if (task.status !== "pending") return { ok: false, reason: `task_not_pending:${task.id}` };
+		: tasks.find(candidate => getGjcTeamTaskClaimEligibilityReason(candidate, teamWorker, tasks) == null);
+	if (!task) return { ok: false, reason: taskId ? `task_not_found:${taskId}` : "no_pending_task" };
+	const eligibilityReason = getGjcTeamTaskClaimEligibilityReason(task, teamWorker, tasks);
+	if (eligibilityReason) return { ok: false, reason: eligibilityReason };
+	const activeClaimReason = await getActiveClaimReason(dir, task);
+	if (activeClaimReason) return { ok: false, reason: activeClaimReason };
 	const token = randomUUID();
 	const claim: GjcTeamTaskClaim = {
 		owner: workerId,
@@ -2145,20 +3078,19 @@ export async function claimGjcTeamTask(
 		leased_until: new Date(Date.now() + 30 * 60_000).toISOString(),
 	};
 	const claimPath = path.join(dir, "claims", `${task.id}.json`);
-	await fs.mkdir(path.dirname(claimPath), { recursive: true });
-	let claimFile: fs.FileHandle | undefined;
-	try {
-		claimFile = await fs.open(claimPath, "wx");
-		await claimFile.writeFile(`${JSON.stringify(claim, null, 2)}\n`, "utf-8");
-	} catch (error) {
-		if (isEexist(error)) return { ok: false, reason: `task_already_claimed:${task.id}` };
-		throw error;
-	} finally {
-		await claimFile?.close();
-	}
+	const created = await writeJsonFileNoClobber(claimPath, claim);
+	if (!created) return { ok: false, reason: `task_already_claimed:${task.id}` };
 	const current = await readGjcTeamTask(teamName, task.id, cwd, env);
-	if (current.status !== "pending") {
+	const currentEligibilityReason = getGjcTeamTaskClaimEligibilityReason(current, teamWorker, await readTasks(dir));
+	if (currentEligibilityReason) {
 		await fs.rm(claimPath, { force: true });
+		return { ok: false, reason: currentEligibilityReason };
+	}
+	if (current.status !== "pending") {
+		await deleteIfOwned(claimPath, {
+			...stateWriterOptions(claimPath, "prune", "rollback"),
+			predicate: current => (current as GjcTeamTaskClaim).token === token,
+		});
 		return { ok: false, reason: `task_not_pending:${task.id}` };
 	}
 	const updated: GjcTeamTask = {
@@ -2173,7 +3105,10 @@ export async function claimGjcTeamTask(
 	try {
 		await writeTask(dir, updated);
 	} catch (error) {
-		await fs.rm(claimPath, { force: true });
+		await deleteIfOwned(claimPath, {
+			...stateWriterOptions(claimPath, "prune", "rollback"),
+			predicate: current => (current as GjcTeamTaskClaim).token === token,
+		});
 		throw error;
 	}
 	await appendEvent(dir, {
@@ -2192,7 +3127,7 @@ export async function transitionGjcTeamTaskStatus(
 	env: NodeJS.ProcessEnv = process.env,
 	claimToken?: string,
 	workerId?: string,
-	evidence?: string,
+	completionEvidenceInput?: unknown,
 ): Promise<GjcTeamTask> {
 	const dir = await findTeamDir(teamName, cwd, env);
 	const config = await readConfig(dir);
@@ -2205,30 +3140,39 @@ export async function transitionGjcTeamTaskStatus(
 	if (task.claim.token !== claimToken) throw new Error(`claim_token_mismatch:${taskId}`);
 	if (workerId && task.claim.owner !== workerId) throw new Error(`claim_owner_mismatch:${taskId}`);
 	const terminal = status === "completed" || status === "failed";
-	if (status === "completed" && evidence !== undefined && evidence.trim().length === 0)
-		throw new Error(`task_evidence_required:${taskId}`);
+	const transitionedAt = now();
+	const completionEvidence =
+		status === "completed"
+			? normalizeGjcTeamTaskCompletionEvidence(taskId, task.claim.owner, completionEvidenceInput, transitionedAt)
+			: undefined;
 	const updated: GjcTeamTask = {
 		...task,
 		status,
 		claim: terminal ? undefined : task.claim,
 		version: task.version + 1,
-		updated_at: now(),
-		...(terminal ? { completed_at: now() } : {}),
+		updated_at: transitionedAt,
+		...(terminal ? { completed_at: transitionedAt } : {}),
+		...(completionEvidence ? { completion_evidence: completionEvidence } : {}),
 	};
 	await writeTask(dir, updated);
-	if (terminal && evidence)
-		await writeJsonFile(taskEvidencePath(dir, taskId), {
-			task_id: taskId,
-			worker: workerId ?? task.claim.owner,
-			evidence,
-			recorded_at: now(),
-		});
-	if (terminal) await fs.rm(path.join(dir, "claims", `${taskId}.json`), { force: true });
+	if (terminal) {
+		const claimPath = path.join(dir, "claims", `${taskId}.json`);
+		await removeFileAudited(claimPath, stateWriterOptions(claimPath, "prune", "terminal"));
+	}
+	const eventData: Record<string, unknown> = { status };
+	if (completionEvidence) {
+		eventData.completion_evidence = {
+			recorded_by: completionEvidence.recorded_by,
+			item_count: completionEvidence.items.length,
+			verified_item_count: completionEvidence.items.filter(isGjcTeamCompletionEvidenceItemVerified).length,
+			files_count: completionEvidence.files?.length ?? 0,
+		};
+	}
 	await appendEvent(dir, {
 		type: "task_transitioned",
 		task_id: taskId,
 		message: "Task status changed",
-		data: { status },
+		data: eventData,
 	});
 	return updated;
 }
@@ -2239,8 +3183,18 @@ export async function transitionGjcTeamTask(
 	cwd = process.cwd(),
 	env: NodeJS.ProcessEnv = process.env,
 	claimToken?: string,
+	completionEvidenceInput?: unknown,
 ): Promise<GjcTeamTask> {
-	return transitionGjcTeamTaskStatus(teamName, taskId, parseGjcTeamTaskStatus(status, true), cwd, env, claimToken);
+	return transitionGjcTeamTaskStatus(
+		teamName,
+		taskId,
+		parseGjcTeamTaskStatus(status, true),
+		cwd,
+		env,
+		claimToken,
+		undefined,
+		completionEvidenceInput,
+	);
 }
 export async function releaseGjcTeamTaskClaim(
 	teamName: string,
@@ -2263,7 +3217,11 @@ export async function releaseGjcTeamTaskClaim(
 		updated_at: now(),
 	};
 	await writeTask(dir, updated);
-	await fs.rm(path.join(dir, "claims", `${taskId}.json`), { force: true });
+	const claimPath = path.join(dir, "claims", `${taskId}.json`);
+	await deleteIfOwned(claimPath, {
+		...stateWriterOptions(claimPath, "prune", "release"),
+		predicate: current => (current as GjcTeamTaskClaim).token === claimToken,
+	});
 	await appendEvent(dir, {
 		type: "task_claim_released",
 		task_id: taskId,
@@ -2603,12 +3561,43 @@ export async function readGjcWorkerStatus(
 	const dir = await findTeamDir(teamName, cwd, env);
 	const config = await readConfig(dir);
 	assertKnownWorker(config, worker);
-	return (
-		(await readJsonFile<WorkerStatusFile>(path.join(workerDir(dir, worker), "status.json"))) ?? {
-			state: "unknown",
-			updated_at: now(),
-		}
-	);
+	return readWorkerStatusFile(dir, worker);
+}
+export async function updateGjcWorkerStatus(
+	teamName: string,
+	worker: string,
+	status: GjcWorkerStatusState,
+	cwd = process.cwd(),
+	env: NodeJS.ProcessEnv = process.env,
+	currentTaskId?: string,
+	reason?: string,
+): Promise<WorkerStatusFile> {
+	const dir = await findTeamDir(teamName, cwd, env);
+	const config = await readConfig(dir);
+	const teamWorker = findKnownWorker(config, worker);
+	if (currentTaskId) assertSafeId("task_id", currentTaskId);
+	const trimmedReason = reason?.trim();
+	const value: WorkerStatusFile = {
+		state: status,
+		...(currentTaskId ? { current_task_id: currentTaskId } : {}),
+		...(trimmedReason ? { reason: trimmedReason } : {}),
+		updated_at: now(),
+	};
+	await writeJsonFile(path.join(workerDir(dir, worker), "status.json"), value);
+	const currentLifecycle = await readWorkerLifecycleRecord(dir, teamWorker);
+	const lifecycleState =
+		currentLifecycle.lifecycle_state === "stopped" ? "stopped" : lifecycleStateForWorkerStatus(status);
+	await writeWorkerLifecycleRecord(dir, teamWorker, lifecycleState);
+	await appendEvent(dir, {
+		type: "worker_status_updated",
+		worker,
+		message: `Worker ${worker} reported ${status}`,
+		data: {
+			status,
+			current_task_id: currentTaskId,
+		},
+	});
+	return value;
 }
 export async function readGjcWorkerHeartbeat(
 	teamName: string,
@@ -2646,7 +3635,7 @@ export async function writeGjcWorkerInbox(
 	const config = await readConfig(dir);
 	assertKnownWorker(config, worker);
 	const filePath = path.join(workerDir(dir, worker), "inbox.md");
-	await Bun.write(filePath, content);
+	await writeReport(filePath, content, stateWriterOptions(filePath, "report", "write"));
 	return { path: filePath };
 }
 export async function writeGjcWorkerIdentity(
@@ -2678,6 +3667,23 @@ export async function readGjcTeamEvents(
 		throw error;
 	}
 }
+export async function readGjcTeamTraces(
+	teamName: string,
+	cwd = process.cwd(),
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<GjcTeamTraceEvent[]> {
+	const dir = await findTeamDir(teamName, cwd, env);
+	try {
+		const text = await Bun.file(tracePath(dir)).text();
+		return text
+			.split(/\r?\n/)
+			.filter(Boolean)
+			.map(line => JSON.parse(line) as GjcTeamTraceEvent);
+	} catch (error) {
+		if (isEnoent(error)) return [];
+		throw error;
+	}
+}
 export async function appendGjcTeamEvent(
 	teamName: string,
 	type: string,
@@ -2741,13 +3747,27 @@ export async function writeGjcShutdownRequest(
 	requestedBy: string,
 	cwd = process.cwd(),
 	env: NodeJS.ProcessEnv = process.env,
+	requestId = `shutdown-${stableHash([teamName, worker, now(), randomUUID()].join(":"))}`,
+	mode: GjcTeamShutdownMode = "graceful",
+	requestedAt = now(),
 ): Promise<Record<string, unknown>> {
 	const dir = await findTeamDir(teamName, cwd, env);
 	const config = await readConfig(dir);
-	assertKnownWorker(config, worker);
+	const teamWorker = findKnownWorker(config, worker);
 	assertKnownParticipant(config, requestedBy);
-	const value = { worker, requested_by: requestedBy, requested_at: now() };
+	const value = { worker, requested_by: requestedBy, request_id: requestId, mode, requested_at: requestedAt };
 	await writeJsonFile(path.join(workerDir(dir, worker), "shutdown-request.json"), value);
+	await writeWorkerLifecycleRecord(dir, teamWorker, "draining", {
+		shutdown_request_id: requestId,
+		shutdown_requested_at: requestedAt,
+		shutdown_mode: mode,
+	});
+	await appendEvent(dir, {
+		type: "worker_shutdown_requested",
+		worker,
+		message: `Worker ${worker} shutdown requested`,
+		data: { requested_by: requestedBy, request_id: requestId, mode },
+	});
 	return value;
 }
 export async function readGjcShutdownAck(
@@ -2778,121 +3798,142 @@ export async function executeGjcTeamApiOperation(
 			return { tasks: await listGjcTeamTasks(teamName, cwd, env) };
 		case "read-task":
 			return { task: await readGjcTeamTask(teamName, String(input.task_id ?? input.taskId), cwd, env) };
-		case "create-task":
-			return {
-				task: await createGjcTeamTask(
-					teamName,
-					String(input.subject ?? "Task"),
-					String(input.description ?? ""),
-					cwd,
-					env,
-				),
-			};
-		case "update-task":
-			return {
-				task: await updateGjcTeamTask(
-					teamName,
-					String(input.task_id ?? input.taskId),
-					{
-						subject: typeof input.subject === "string" ? input.subject : undefined,
-						description: typeof input.description === "string" ? input.description : undefined,
-					},
-					cwd,
-					env,
-				),
-			};
-		case "claim-task":
-			return claimGjcTeamTask(
+		case "create-task": {
+			const task = await createGjcTeamTask(
+				teamName,
+				String(input.subject ?? "Task"),
+				String(input.description ?? ""),
+				cwd,
+				env,
+				taskMetadataFromInput(input, true),
+			);
+			return { ok: true, ...taskReceiptFields(teamName, task) };
+		}
+		case "update-task": {
+			const task = await updateGjcTeamTask(
+				teamName,
+				String(input.task_id ?? input.taskId),
+				{
+					subject: typeof input.subject === "string" ? input.subject : undefined,
+					description: typeof input.description === "string" ? input.description : undefined,
+					...taskMetadataFromInput(input),
+				},
+				cwd,
+				env,
+			);
+			return { ok: true, ...taskReceiptFields(teamName, task) };
+		}
+		case "claim-task": {
+			const requestedTaskId = input.task_id ?? input.taskId;
+			const result = await claimGjcTeamTask(
 				teamName,
 				worker,
 				cwd,
 				env,
-				typeof input.task_id === "string" ? input.task_id : undefined,
+				typeof requestedTaskId === "string" ? requestedTaskId : undefined,
 			);
-		case "transition-task":
-		case "transition-task-status":
 			return {
-				ok: true,
-				task: await transitionGjcTeamTaskStatus(
-					teamName,
-					String(input.task_id ?? input.taskId),
-					parseGjcTeamTaskStatus(input.to ?? input.status),
-					cwd,
-					env,
-					typeof input.claim_token === "string" ? input.claim_token : undefined,
-					explicitWorker,
-					typeof input.evidence === "string"
-						? input.evidence
-						: typeof input.result === "string"
-							? input.result
-							: undefined,
-				),
+				ok: result.ok,
+				reason: result.reason,
+				team_name: teamName,
+				worker_id: result.worker_id ?? worker,
+				...(result.task ? taskReceiptFields(teamName, result.task) : {}),
+				claim_token: result.claim_token,
 			};
-		case "release-task-claim":
+		}
+		case "transition-task":
+		case "transition-task-status": {
+			const task = await transitionGjcTeamTaskStatus(
+				teamName,
+				String(input.task_id ?? input.taskId),
+				parseGjcTeamTaskStatus(input.to ?? input.status),
+				cwd,
+				env,
+				typeof input.claim_token === "string" ? input.claim_token : undefined,
+				explicitWorker,
+				input.completion_evidence ?? input.completionEvidence,
+			);
 			return {
 				ok: true,
-				task: await releaseGjcTeamTaskClaim(
-					teamName,
-					String(input.task_id),
-					String(input.claim_token),
-					worker,
-					cwd,
-					env,
-				),
-			};
-		case "send-message":
-			return {
-				message: await sendGjcTeamMessage(
-					teamName,
-					String(input.from_worker),
-					String(input.to_worker),
-					String(input.body),
-					cwd,
-					env,
-					typeof input.idempotency_key === "string" ? input.idempotency_key : undefined,
-				),
+				...taskReceiptFields(teamName, task),
+				worker_id: explicitWorker ?? task.owner ?? task.assignee,
 			};
-		case "broadcast":
+		}
+		case "release-task-claim": {
+			const task = await releaseGjcTeamTaskClaim(
+				teamName,
+				String(input.task_id),
+				String(input.claim_token),
+				worker,
+				cwd,
+				env,
+			);
+			return { ok: true, ...taskReceiptFields(teamName, task), worker_id: worker };
+		}
+		case "send-message": {
+			const message = await sendGjcTeamMessage(
+				teamName,
+				String(input.from_worker),
+				String(input.to_worker),
+				String(input.body),
+				cwd,
+				env,
+				typeof input.idempotency_key === "string" ? input.idempotency_key : undefined,
+			);
+			return { ok: true, ...mailboxMessageReceiptFields(teamName, message) };
+		}
+		case "broadcast": {
+			const messages = await broadcastGjcTeamMessage(
+				teamName,
+				String(input.from_worker),
+				String(input.body),
+				cwd,
+				env,
+				typeof input.idempotency_key === "string" ? input.idempotency_key : undefined,
+			);
 			return {
-				messages: await broadcastGjcTeamMessage(
-					teamName,
-					String(input.from_worker),
-					String(input.body),
-					cwd,
-					env,
-					typeof input.idempotency_key === "string" ? input.idempotency_key : undefined,
-				),
+				ok: true,
+				team_name: teamName,
+				message_ids: messages.map(message => message.message_id),
+				delivery_states: messages.map(message => ({
+					message_id: message.message_id,
+					to_worker: message.to_worker,
+					delivered: Boolean(message.delivered_at),
+					notified: Boolean(message.notified_at),
+				})),
 			};
+		}
 		case "mailbox-list":
 			return { messages: await listGjcTeamMailbox(teamName, worker, cwd, env) };
-		case "mailbox-mark-delivered":
-			return {
-				message: await markGjcTeamMailboxMessage(
-					teamName,
-					worker,
-					String(input.message_id),
-					"delivered_at",
-					cwd,
-					env,
-				),
-			};
-		case "mailbox-mark-notified":
-			return {
-				message: await markGjcTeamMailboxMessage(
-					teamName,
-					worker,
-					String(input.message_id),
-					"notified_at",
-					cwd,
-					env,
-				),
-			};
+		case "mailbox-mark-delivered": {
+			const message = await markGjcTeamMailboxMessage(
+				teamName,
+				worker,
+				String(input.message_id),
+				"delivered_at",
+				cwd,
+				env,
+			);
+			return { ok: true, ...mailboxMessageReceiptFields(teamName, message) };
+		}
+		case "mailbox-mark-notified": {
+			const message = await markGjcTeamMailboxMessage(
+				teamName,
+				worker,
+				String(input.message_id),
+				"notified_at",
+				cwd,
+				env,
+			);
+			return { ok: true, ...mailboxMessageReceiptFields(teamName, message) };
+		}
 		case "notification-list": {
 			const dir = await findTeamDir(teamName, cwd, env);
 			const config = await readConfig(dir);
 			await reconcileTeamNotifications(dir, config);
 			const notifications = await listNotificationRecords(dir);
-			return { notifications, summary: summarizeNotifications(notifications) };
+			const result = { notifications, summary: summarizeNotifications(notifications) };
+			return notificationSummaryReceipt(teamName, result);
 		}
 		case "notification-read":
 			return {
@@ -2902,20 +3943,19 @@ export async function executeGjcTeamApiOperation(
 				),
 			};
 		case "notification-replay":
-			return replayGjcTeamNotifications(teamName, cwd, env);
+			return notificationSummaryReceipt(teamName, await replayGjcTeamNotifications(teamName, cwd, env));
 		case "notification-mark-pane-attempt": {
 			const dir = await findTeamDir(teamName, cwd, env);
 			const notification = await readNotificationRecord(dir, String(input.notification_id));
-			return {
-				notification: await writeNotificationRecord(dir, {
-					...notification,
-					delivery_state: parsePaneAttemptResult(String(input.result ?? "failed")),
-					pane_attempt_result: parsePaneAttemptResult(String(input.result ?? "failed")),
-					pane_attempt_reason: String(input.reason ?? "manual_api"),
-					pane_attempt_at: now(),
-					updated_at: now(),
-				}),
-			};
+			const updated = await writeNotificationRecord(dir, {
+				...notification,
+				delivery_state: parsePaneAttemptResult(String(input.result ?? "failed")),
+				pane_attempt_result: parsePaneAttemptResult(String(input.result ?? "failed")),
+				pane_attempt_reason: String(input.reason ?? "manual_api"),
+				pane_attempt_at: now(),
+				updated_at: now(),
+			});
+			return { ok: true, ...notificationReceiptFields(updated) };
 		}
 		case "worker-startup-ack":
 			return writeGjcWorkerStartupAck(teamName, worker, cwd, env, input);
@@ -2925,8 +3965,22 @@ export async function executeGjcTeamApiOperation(
 			return readJsonFile(path.join(await findTeamDir(teamName, cwd, env), "manifest.v2.json"));
 		case "read-worker-status":
 			return readGjcWorkerStatus(teamName, worker, cwd, env);
+		case "update-worker-status": {
+			const currentTaskIdInput = input.current_task_id ?? input.currentTaskId;
+			return updateGjcWorkerStatus(
+				teamName,
+				worker,
+				parseRequiredGjcWorkerStatusState(input.status ?? input.state),
+				cwd,
+				env,
+				typeof currentTaskIdInput === "string" ? currentTaskIdInput : undefined,
+				typeof input.reason === "string" ? input.reason : undefined,
+			);
+		}
 		case "read-worker-heartbeat":
 			return readGjcWorkerHeartbeat(teamName, worker, cwd, env);
+		case "recover-stale-claims":
+			return recoverGjcTeamStaleClaims(teamName, cwd, env);
 		case "update-worker-heartbeat":
 			return updateGjcWorkerHeartbeat(
 				teamName,
@@ -2962,6 +4016,8 @@ export async function executeGjcTeamApiOperation(
 			return appendGjcTeamEvent(teamName, String(input.type ?? "event"), worker, cwd, env);
 		case "read-events":
 			return { events: await readGjcTeamEvents(teamName, cwd, env) };
+		case "read-traces":
+			return { traces: await readGjcTeamTraces(teamName, cwd, env) };
 		case "await-event":
 			return awaitGjcTeamEvent(teamName, Number(input.timeout_ms ?? 0), cwd, env);
 		case "write-monitor-snapshot":
@@ -2972,8 +4028,18 @@ export async function executeGjcTeamApiOperation(
 			return writeGjcTaskApproval(teamName, String(input.task_id), input, cwd, env);
 		case "read-task-approval":
 			return readGjcTaskApproval(teamName, String(input.task_id), cwd, env);
-		case "write-shutdown-request":
-			return writeGjcShutdownRequest(teamName, worker, String(input.requested_by ?? "leader-fixed"), cwd, env);
+		case "write-shutdown-request": {
+			const shutdownRequestIdInput = input.request_id ?? input.requestId;
+			return writeGjcShutdownRequest(
+				teamName,
+				worker,
+				String(input.requested_by ?? input.requestedBy ?? "leader-fixed"),
+				cwd,
+				env,
+				typeof shutdownRequestIdInput === "string" ? shutdownRequestIdInput : undefined,
+				parseGjcTeamShutdownMode(input.mode),
+			);
+		}
 		case "read-shutdown-ack":
 			return readGjcShutdownAck(teamName, worker, cwd, env);
 		default: