@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/deep-interview/render-middleware.ts

@@ -0,0 +1,372 @@
+import { type Component, Container, Markdown, Spacer, Text } from "@gajae-code/tui";
+import { getMarkdownTheme, type Theme } from "../modes/theme/theme";
+
+interface RoundQuestionModel {
+	kind: "round-question";
+	round: string;
+	component?: string;
+	targeting?: string;
+	mode?: string;
+	whyNow?: string;
+	ambiguity?: string;
+	question: string;
+}
+
+interface TopologyQuestionModel {
+	kind: "topology-question";
+	context?: string;
+	components: Array<{ name: string; description: string }>;
+	question: string;
+}
+
+interface ProgressDimension {
+	name: string;
+	score: string;
+	weight: string;
+	weighted: string;
+	gap: string;
+}
+
+interface ProgressModel {
+	kind: "progress";
+	round: string;
+	dimensions: ProgressDimension[];
+	ambiguity?: string;
+	topology?: string;
+	ontology?: string;
+	nextTarget?: string;
+	status?: string;
+	extra?: string;
+}
+
+interface ThresholdModel {
+	kind: "threshold";
+	threshold: string;
+	source: string;
+	rest: string;
+}
+
+type DeepInterviewModel = RoundQuestionModel | TopologyQuestionModel | ProgressModel | ThresholdModel;
+
+function normalizeText(text: string): string {
+	return text.trim().replaceAll("\r\n", "\n");
+}
+
+function stripMarkdownEmphasis(value: string): string {
+	return value.replace(/\*\*/g, "").replace(/^"|"$/g, "").trim();
+}
+
+function parseRoundQuestion(text: string): RoundQuestionModel | null {
+	const normalized = normalizeText(text);
+	const lines = normalized.split("\n");
+	const headerIndex = lines.findIndex(line => /^Round\s+\d+\s+\|/i.test(line.trim()));
+	if (headerIndex < 0) return null;
+	const headerLine = lines[headerIndex]?.trim() ?? "";
+	const body = lines
+		.slice(headerIndex + 1)
+		.join("\n")
+		.trim();
+	if (!body) return null;
+
+	const componentMatch =
+		/^Round\s+(\d+)\s+\|\s+Component:\s*(.*?)\s+\|\s+Targeting:\s*(.*?)\s+\|\s+Why now:\s*(.*?)\s+\|\s+Ambiguity:\s*(.+?)%?\s*$/i.exec(
+			headerLine,
+		);
+	if (componentMatch) {
+		return {
+			kind: "round-question",
+			round: componentMatch[1] ?? "?",
+			component: componentMatch[2]?.trim(),
+			targeting: componentMatch[3]?.trim(),
+			whyNow: componentMatch[4]?.trim(),
+			ambiguity: componentMatch[5]?.trim(),
+			question: body,
+		};
+	}
+
+	const targetingMatch =
+		/^Round\s+(\d+)\s+\|\s+Targeting:\s*(.*?)\s+\|\s+Why now:\s*(.*?)\s+\|\s+Ambiguity:\s*(.+?)%?\s*$/i.exec(
+			headerLine,
+		);
+	if (targetingMatch) {
+		return {
+			kind: "round-question",
+			round: targetingMatch[1] ?? "?",
+			targeting: targetingMatch[2]?.trim(),
+			whyNow: targetingMatch[3]?.trim(),
+			ambiguity: targetingMatch[4]?.trim(),
+			question: body,
+		};
+	}
+
+	const modeMatch = /^Round\s+(\d+)\s+\|\s+(.*?)\s+\|\s+Ambiguity:\s*(.+?)%?\s*$/i.exec(headerLine);
+	if (modeMatch) {
+		return {
+			kind: "round-question",
+			round: modeMatch[1] ?? "?",
+			mode: modeMatch[2]?.trim(),
+			ambiguity: modeMatch[3]?.trim(),
+			question: body,
+		};
+	}
+
+	return null;
+}
+
+function parseTopologyQuestion(text: string): TopologyQuestionModel | null {
+	const normalized = normalizeText(text);
+	const lines = normalized.split("\n");
+	const headerIndex = lines.findIndex(line =>
+		/^Round\s+0\s+\|\s+Topology confirmation\s+\|\s+Ambiguity:\s+not scored yet/i.test(line.trim()),
+	);
+	if (headerIndex < 0) {
+		return null;
+	}
+	const components: TopologyQuestionModel["components"] = [];
+	const contextLines: string[] = [];
+	const questionLines: string[] = [];
+	let inQuestion = false;
+	for (const line of lines.slice(headerIndex + 1)) {
+		const trimmed = line.trim();
+		const component = /^\s*\d+\.\s+([^:]+):\s+(.+)$/.exec(line);
+		if (component) {
+			components.push({ name: component[1]?.trim() ?? "", description: component[2]?.trim() ?? "" });
+			continue;
+		}
+		if (/\?$/.test(trimmed)) inQuestion = true;
+		if (!trimmed) continue;
+		if (inQuestion) questionLines.push(trimmed);
+		else contextLines.push(trimmed);
+	}
+	return {
+		kind: "topology-question",
+		context: contextLines.join("\n") || undefined,
+		components,
+		question: questionLines.join("\n"),
+	};
+}
+
+function splitMarkdownTableRow(line: string): string[] {
+	const trimmed = line.trim();
+	if (!trimmed.startsWith("|") || !trimmed.endsWith("|")) return [];
+	return trimmed
+		.slice(1, -1)
+		.split("|")
+		.map(cell => stripMarkdownEmphasis(cell));
+}
+
+function parseProgress(text: string): ProgressModel | null {
+	const normalized = normalizeText(text);
+	const roundMatch = /^Round\s+(\d+)\s+complete\./i.exec(normalized);
+	if (!roundMatch) return null;
+
+	const lines = normalized.split("\n");
+	const dimensions: ProgressDimension[] = [];
+	const extraLines: string[] = [];
+	let ambiguity: string | undefined;
+	let topology: string | undefined;
+	let ontology: string | undefined;
+	let nextTarget: string | undefined;
+	let status: string | undefined;
+
+	for (const [index, line] of lines.entries()) {
+		if (index === 0) continue;
+		const trimmed = line.trim();
+		const cells = splitMarkdownTableRow(line);
+		if (cells.length >= 5) {
+			const [name = "", score = "", weight = "", weighted = "", gap = ""] = cells;
+			if (/^-+$/.test(name) || /^Dimension$/i.test(name)) continue;
+			if (/^Ambiguity$/i.test(name)) {
+				ambiguity = weighted || score || gap;
+				continue;
+			}
+			dimensions.push({ name, score, weight, weighted, gap });
+			continue;
+		}
+		const topologyMatch = /^\*\*Topology:\*\*\s*(.+)$/.exec(trimmed);
+		if (topologyMatch) {
+			topology = topologyMatch[1]?.trim();
+			continue;
+		}
+		const ontologyMatch = /^\*\*Ontology:\*\*\s*(.+)$/.exec(trimmed);
+		if (ontologyMatch) {
+			ontology = ontologyMatch[1]?.trim();
+			continue;
+		}
+		const nextTargetMatch = /^\*\*Next target:\*\*\s*(.+)$/.exec(trimmed);
+		if (nextTargetMatch) {
+			nextTarget = nextTargetMatch[1]?.trim();
+			continue;
+		}
+		if (/^(Clarity threshold met!|Focusing next question on:)/i.test(trimmed)) {
+			status = trimmed;
+			continue;
+		}
+		if (trimmed) extraLines.push(trimmed);
+	}
+
+	if (dimensions.length === 0 && !ambiguity && !topology && !ontology && !nextTarget) return null;
+	return {
+		kind: "progress",
+		round: roundMatch[1] ?? "?",
+		dimensions,
+		ambiguity,
+		topology,
+		ontology,
+		nextTarget,
+		status,
+		extra: extraLines.join("\n") || undefined,
+	};
+}
+
+function parseThreshold(text: string): ThresholdModel | null {
+	const normalized = normalizeText(text);
+	const match = /^Deep Interview threshold:\s*(.*?)\s*\(source:\s*(.*?)\)\s*$/im.exec(normalized.split("\n")[0] ?? "");
+	if (!match) return null;
+	return {
+		kind: "threshold",
+		threshold: match[1]?.trim() ?? "",
+		source: match[2]?.trim() ?? "",
+		rest: normalized.split("\n").slice(1).join("\n").trim(),
+	};
+}
+
+function parseDeepInterview(text: string): DeepInterviewModel | null {
+	return parseProgress(text) ?? parseTopologyQuestion(text) ?? parseRoundQuestion(text) ?? parseThreshold(text);
+}
+
+function addLabel(container: Container, label: string, value: string | undefined, uiTheme: Theme): void {
+	if (!value) return;
+	container.addChild(new Spacer(1));
+	container.addChild(new Text(uiTheme.fg("accent", uiTheme.bold(label)), 0, 0));
+	container.addChild(
+		new Markdown(value, 2, 0, getMarkdownTheme(), { color: (text: string) => uiTheme.fg("toolOutput", text) }),
+	);
+}
+
+function renderPipeSummary(title: string, value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	return (
+		value
+			.split("|")
+			.map(part => part.trim())
+			.filter(Boolean)
+			.map(part => `- ${part}`)
+			.join("\n") || title
+	);
+}
+
+function renderModel(model: DeepInterviewModel, uiTheme: Theme): Component {
+	const container = new Container();
+	if (model.kind === "round-question") {
+		const meta = [
+			`Round ${model.round}`,
+			model.ambiguity ? `Ambiguity ${model.ambiguity.replace(/%$/, "")}%` : undefined,
+		]
+			.filter(Boolean)
+			.join(" · ");
+		container.addChild(new Text(uiTheme.fg("toolTitle", uiTheme.bold(`Deep Interview · ${meta}`)), 0, 0));
+		addLabel(container, "Component", model.component, uiTheme);
+		addLabel(container, "Mode", model.mode, uiTheme);
+		addLabel(container, "Target", model.targeting, uiTheme);
+		addLabel(container, "Why now", model.whyNow, uiTheme);
+		addLabel(container, "Question", model.question, uiTheme);
+		return container;
+	}
+
+	if (model.kind === "topology-question") {
+		container.addChild(
+			new Text(uiTheme.fg("toolTitle", uiTheme.bold("Deep Interview · Round 0 · Topology confirmation")), 0, 0),
+		);
+		addLabel(container, "Ambiguity", "Not scored yet", uiTheme);
+		addLabel(container, "Reading", model.context, uiTheme);
+		if (model.components.length > 0) {
+			const components = model.components
+				.map((component, index) => `${index + 1}. **${component.name}**\n   ${component.description}`)
+				.join("\n\n");
+			addLabel(container, "Components", components, uiTheme);
+		}
+		addLabel(container, "Question", model.question, uiTheme);
+		return container;
+	}
+
+	if (model.kind === "progress") {
+		container.addChild(
+			new Text(uiTheme.fg("toolTitle", uiTheme.bold(`Deep Interview · Round ${model.round} complete`)), 0, 0),
+		);
+		addLabel(container, "Ambiguity", model.ambiguity, uiTheme);
+		if (model.dimensions.length > 0) {
+			container.addChild(new Spacer(1));
+			container.addChild(new Text(uiTheme.fg("accent", uiTheme.bold("Clarity")), 0, 0));
+			for (const dimension of model.dimensions) {
+				const body = [`Score ${dimension.score} · weight ${dimension.weight} · weighted ${dimension.weighted}`];
+				if (dimension.gap) body.push(/^clear$/i.test(dimension.gap) ? "Clear" : `Gap: ${dimension.gap}`);
+				addLabel(container, dimension.name, body.join("\n"), uiTheme);
+			}
+		}
+		addLabel(container, "Topology", renderPipeSummary("Topology", model.topology), uiTheme);
+		addLabel(container, "Ontology", renderPipeSummary("Ontology", model.ontology), uiTheme);
+		addLabel(container, "Next target", model.nextTarget, uiTheme);
+		addLabel(container, "Status", model.status, uiTheme);
+		addLabel(container, "Additional details", model.extra, uiTheme);
+		return container;
+	}
+
+	container.addChild(new Text(uiTheme.fg("toolTitle", uiTheme.bold("Deep Interview · Started")), 0, 0));
+	addLabel(container, "Threshold", `${model.threshold} · source: ${model.source}`, uiTheme);
+	addLabel(container, "Details", model.rest, uiTheme);
+	return container;
+}
+
+export function renderDeepInterviewAssistantText(text: string, uiTheme: Theme): Component | null {
+	const model = parseDeepInterview(text);
+	if (!model || model.kind === "round-question" || model.kind === "topology-question") return null;
+	return renderModel(model, uiTheme);
+}
+
+export function renderDeepInterviewAskQuestion(question: string, uiTheme: Theme): Component | null {
+	const model = parseTopologyQuestion(question) ?? parseRoundQuestion(question);
+	if (!model) return null;
+	return renderModel(model, uiTheme);
+}
+
+export function isDeepInterviewAskQuestion(question: string): boolean {
+	if (parseTopologyQuestion(question) ?? parseRoundQuestion(question)) return true;
+	const normalized = normalizeText(question);
+	return /(?:^|\n)\s*Round\s+\d+\s*\|.*?\bAmbiguity\b/i.test(normalized);
+}
+
+export function formatDeepInterviewSelectorPrompt(question: string): string | null {
+	const model = parseTopologyQuestion(question) ?? parseRoundQuestion(question);
+	if (!model) return null;
+	if (model.kind === "topology-question") {
+		const componentLines =
+			model.components.length > 0
+				? [
+						"Components:",
+						...model.components.map(
+							(component, index) => `${index + 1}. ${component.name} — ${component.description}`,
+						),
+					]
+				: [];
+		return [
+			"Deep Interview · Round 0 · Topology confirmation",
+			"Ambiguity: not scored yet",
+			model.context ? `Reading:\n${model.context}` : undefined,
+			...componentLines,
+			model.question ? `Question:\n${model.question}` : undefined,
+		]
+			.filter((line): line is string => Boolean(line))
+			.join("\n\n");
+	}
+	return [
+		`Deep Interview · Round ${model.round}${model.ambiguity ? ` · Ambiguity ${model.ambiguity.replace(/%$/, "")}%` : ""}`,
+		model.component ? `Component: ${model.component}` : undefined,
+		model.mode ? `Mode: ${model.mode}` : undefined,
+		model.targeting ? `Target: ${model.targeting}` : undefined,
+		model.whyNow ? `Why now: ${model.whyNow}` : undefined,
+		model.question,
+	]
+		.filter((line): line is string => Boolean(line))
+		.join("\n");
+}

package/src/defaults/gjc/skills/deep-interview/SKILL.md

@@ -125,7 +125,7 @@ Deep Interview threshold: <resolvedThresholdPercent> (source: <resolvedThreshold
 ```json
 {
   "active": true,
-  "current_phase": "deep-interview",
+  "current_phase": "interviewing",
   "state": {
     "interview_id": "<uuid>",
     "type": "greenfield|brownfield",

package/src/defaults/gjc/skills/ralplan/SKILL.md

@@ -49,10 +49,12 @@ Restricted read-only role agents (`planner`, `architect`, and `critic`) must pas
 
 After a role agent persists a stage artifact, its model-facing response to the caller SHOULD be receipt-only: return the `gjc ralplan --write --json` receipt (`run_id`, `path`, `stage`, `stage_n`, `sha256`, `created_at`) plus the minimal verdict/status fields the caller needs for routing, and do **not** paste the full persisted markdown back into the parent conversation. Downstream reviewers should receive the artifact path/receipt and read the persisted file themselves when they actually need the body. This preserves the audit trail while preventing Planner/Architect/Critic verdict bodies from being duplicated into the main-agent context.
 
+RECEIPT-ONLY guideline: role agents (`planner`, `architect`, and `critic`) persist durable outputs via `gjc ralplan --write` and return ONLY the receipt fields (`run_id`, `path`, `sha256`) plus verdict/status routing fields; include `stage` and `stage_n` when available, and never return the full persisted body.
+
 This skill runs GJC planning in consensus mode for the provided arguments.
 
 The consensus workflow:
-1. **Planner** creates initial plan and a compact **RALPLAN-DR summary** before review, then persists the stage with `gjc ralplan --write --stage planner --stage_n 1 --artifact "..."`:
+1. **Planner** creates the initial plan and a compact **RALPLAN-DR summary** before review. Launch the Planner ONCE per run as a detached, resumable subagent (await it before the Architect) and record its returned subagent id as the run's persisted Planner id; persist the stage with `gjc ralplan --write --stage planner --stage_n 1 --artifact "..." --planner-id <id> --planner-resumable <true|false>` (see **Persisted Planner** below):
    - After persistence, return only the receipt/path plus compact planning status; do not paste the full plan markdown back to the caller unless explicitly requested.
    - Principles (3-5)
    - Decision Drivers (top 3)
@@ -66,7 +68,7 @@ The consensus workflow:
    - The Critic agent/subagent must persist its evaluation with `gjc ralplan --write --stage critic --stage_n <N> --artifact "..." --json`, then return the receipt/path plus compact verdict/status (`OKAY`/`ITERATE`/`REJECT`) instead of pasting the full evaluation body.
 5. **Re-review loop** (max 5 iterations): Any non-`APPROVE` Critic verdict (`ITERATE` or `REJECT`) MUST run the same full closed loop:
    a. Collect Architect + Critic feedback
-   b. Revise the plan with Planner
+   b. Revise the plan by resuming the SAME persisted Planner subagent with consolidated Architect + Critic feedback (see **Persisted Planner** below); fall back to a fresh Planner spawn only per the fallback routing table
    c. Return to Architect review
       - Persist each Planner revision with `gjc ralplan --write --stage revision --stage_n <N> --artifact "..." --json` before re-review, then pass the receipt/path forward instead of duplicating the full revision markdown in the parent conversation.
    d. Return to Critic evaluation
@@ -88,6 +90,33 @@ The consensus workflow:
 
 Follow the Plan skill's full documentation for consensus mode details.
 
+### Persisted Planner (consensus loop)
+
+The Planner is a **same-session persisted subagent**: launched detached once, awaited before the Architect, then **resumed** with consolidated Architect + Critic feedback on every re-review pass instead of being re-spawned. The Architect and Critic stay **fresh, independent spawns each pass** so their verdicts remain reproducible from their pass artifacts alone. Do NOT modify the subagent control surface; this orchestration uses the existing `subagent` resume/steer controls only.
+
+**Persistence boundary:** this is same-parent, active-session continuity only. Resumability depends on the in-memory subagent record (and a persistent parent session — an in-memory parent yields `resumable:false`), not just a session file. The `.gjc` run-state record is an audit/routing hint, NOT a durable cross-process subagent registry. After a process restart, a missing record, or any unavailable/failed resume, use the fresh Planner fallback.
+
+**Resume routing table** (per re-review pass, when resuming the persisted Planner id):
+
+| Resume outcome | Action |
+|---|---|
+| `running` | `steer`/inject the consolidated feedback to the same id, then await — do NOT fresh-spawn |
+| `queued` | retain/update the queued message or await the same id — do NOT fresh-spawn just because it is queued |
+| `context_unavailable`, `not_found`, `no_runner`, `resume_failed` | fresh Planner spawn for that pass; record the fallback metadata |
+| terminal (`completed`/`failed`/`cancelled`) + revision message | resume the same id when context is available; otherwise use the fresh fallback above |
+
+**Recording persisted-Planner metadata** (audit/routing only — never claim `subagent list` proves resumability, since the snapshot does not expose `resumable`). Ride these optional flags on the normal `--write` for the planner/revision stage of the pass:
+
+```
+gjc ralplan --write --stage revision --stage_n <N> --artifact "..." \
+  --planner-id <id> --planner-resumable <true|false> \
+  --fallback-reason <context_unavailable|not_found|no_runner|resume_failed|process_restart|missing_record> \
+  --fallback-attempted-id <id> --fallback-stage-n <N> \
+  --fallback-receipt-path <fresh-planner-stage-artifact-path> --json
+```
+
+Set `--planner-resumable true` only when the parent session is provably persistent; set/record `false` after an observed `context_unavailable`; otherwise omit it (unknown). Fallback flags are recorded only when a fresh-spawn fallback actually occurs: a fallback record requires `--fallback-reason` **together with** `--fallback-attempted-id` and `--fallback-stage-n` (the failed id and the pass it failed on), while `--fallback-receipt-path` (the fresh Planner's stage artifact) is optional.
+
 ## Pre-Execution Gate
 
 ### Why the Gate Exists

package/src/defaults/gjc/skills/team/SKILL.md

@@ -56,6 +56,7 @@ requiring a separate linked execution loop up front. GJC team supports current-w
 
 - **Canonical launch:** use plain `gjc team ...` / `$team ...` for the coordinated worker.
 - **Verification ownership:** keep one lane focused on tests, regression coverage, and evidence before shutdown.
+- **Typed lanes:** model delivery, verification, architecture, or specialist work as task `lane` metadata plus `required_role` / `allowed_roles`; claiming enforces owner, role, dependency, and lease order.
 - **Escalation:** use a new explicit follow-up task only when later manual work still needs a persistent single-owner fix/verification loop.
 - **Deprecation:** nested team execution commands have been removed. Use plain `gjc team ...` for coordinated execution.
 
@@ -135,6 +136,9 @@ When `$team` is used as a follow-up mode from ralplan, carry forward the approve
    - `.gjc/state/team/<team>/manifest.v2.json`
    - `.gjc/state/team/<team>/tasks/task-1.json`
    - `.gjc/state/team/<team>/mailbox/worker-1.json`
+   - `.gjc/state/team/<team>/workers/<worker>/status.json`
+   - `.gjc/state/team/<team>/workers/<worker>/lifecycle.json`
+   - `.gjc/state/team/<team>/workers/<worker>/heartbeat.json`
 4. Resolve the worker command from `GJC_TEAM_WORKER_COMMAND` or the active `gjc` entrypoint.
 5. Split the current tmux window like GJC team: worker 1 is split horizontally to the right of the leader, workers 2..N are vertically stacked in the right column, then `select-layout main-vertical` and `main-pane-width` keep leader-left/worker-right at roughly 50/50.
 6. Launch the worker with:
@@ -148,7 +152,7 @@ When `$team` is used as a follow-up mode from ralplan, carry forward the approve
    - diverged worker history is cherry-picked into the leader
    - idle/done/failed worker worktrees are cross-rebased onto the updated leader after integration; working workers are skipped
    - conflicts are aborted, recorded, and reported to the leader mailbox without falsely advancing `last_integrated_head`
-8. Store pane/target/integration evidence in config/manifest/snapshot: `tmux_session`, `tmux_session_name`, `tmux_target`, leader pane id, worker pane ids, and `integration_by_worker`.
+8. Store pane/target/integration/lifecycle evidence in config/manifest/snapshot: `tmux_session`, `tmux_session_name`, `tmux_target`, leader pane id, worker pane ids, `worker_lifecycle_by_id`, and `integration_by_worker`.
 9. Return control to the leader; follow-up uses `status`, `resume`, `shutdown`, and `gjc team api`.
 
 Important:
@@ -163,14 +167,15 @@ Important:
 
 Follow this exact lifecycle when running `$team`:
 
-1. Start team and verify startup evidence (team line, tmux target, worker pane id, state dir).
+1. Start team and verify startup evidence (team line, tmux target, worker pane id, state dir, `worker_lifecycle_by_id.<worker>.lifecycle_state=ready` after startup ACK).
 2. Monitor task progress with runtime/state tools first (`gjc team status <team>`, `gjc team resume <team>`, task files).
-3. Wait for terminal task state before shutdown:
+3. Wait for terminal task state and integration settlement before shutdown:
    - `pending=0`
    - `in_progress=0`
    - `failed=0` (or explicitly acknowledged failure path)
+   - no pending integration request/conflict (`status` / `resume` must not report `phase=awaiting_integration`)
 4. Only then run `gjc team shutdown <team>`.
-5. Verify shutdown evidence and preserved state (`phase=complete`, worker status `stopped`). If shutdown is forced before task completion, expect `phase=cancelled` or `phase=failed`, not `complete`.
+5. Verify shutdown evidence and preserved state (`phase=complete`, worker runtime status `stopped`, lifecycle `stopped` with a matching graceful shutdown request id). If shutdown is forced before evidence-backed task completion, expect `phase=cancelled` or `phase=failed`; if tasks are complete but integration is still pending or conflicted, expect `phase=awaiting_integration`, not `complete`.
 
 Do not run `shutdown` while the worker is actively writing updates unless user explicitly requested abort/cancel. Do not treat ad-hoc pane typing as primary control flow when runtime/state evidence is available.
 
@@ -181,24 +186,28 @@ While a team is running, keep checking live team state until terminal completion
 Minimum acceptable loop:
 
 ```bash
-sleep 30 && gjc team status <team-name>
+sleep 30 && gjc team monitor <team-name>
 ```
+The mutating monitor path also performs bounded liveness recovery: expired task claims, stale heartbeat claims, and missing recorded worker panes are requeued instead of leaving work permanently `in_progress`.
 
 ## Operational Commands
 
 ```bash
 gjc team status <team-name>
+gjc team monitor <team-name>
 gjc team resume <team-name>
 gjc team shutdown <team-name>
 ```
 
 Semantics:
 
-- `status`: mutating monitor path; reads team snapshot and applies pending worker worktree integration before returning task counts, worker state, tmux target/pane evidence, and `integration_by_worker`.
-- `resume`: mutating monitor path; performs the same integration-aware live snapshot for reconnect/inspection flows.
+- `status`: read-only snapshot path; it does not recover claims, replay notifications, integrate worker commits, or sync HUD state.
+- `monitor`: mutating monitor path; reads team snapshot, recovers expired/stale worker claims, applies pending worker worktree integration, replays notifications, syncs HUD state, and returns task counts, worker state, tmux target/pane evidence, `worker_lifecycle_by_id`, and `integration_by_worker`.
+- `resume`: mutating monitor path; performs the same liveness-recovery and integration-aware live snapshot for reconnect/inspection flows.
 - `list`: pure read path; lists known teams without integrating worker commits.
-- API/read-only snapshot operations are pure unless explicitly documented as a monitor/status path.
-- `shutdown`: kills the recorded worker pane when it still belongs to the stored tmux target, removes clean created worktrees, marks worker stopped, and sets phase from task state: `complete` only when all tasks completed, `failed` when tasks failed/blocked, and `cancelled` when work remains pending or in progress. It preserves `.gjc/state/team/<team>` as evidence.
+- API/read-only snapshot operations are pure unless explicitly documented as a monitor path.
+- `claim-task`: mutating task path; before granting a new claim, it recovers expired claims and rejects claims from workers already classified as not live.
+- `shutdown`: writes per-worker graceful `shutdown-request.json`, moves lifecycle through `draining` to `stopped`, kills the recorded worker pane when it still belongs to the stored tmux target, removes clean created worktrees, marks worker runtime status stopped, and sets phase from task, lifecycle, and integration state: `complete` only when all tasks have verified `completion_evidence`, every worker has matching graceful shutdown lifecycle evidence, and no integration request/conflict is pending; `awaiting_integration` when tasks and lifecycle are complete but leader integration still requires action; `failed` when tasks failed/blocked or completed tasks lack valid evidence; and `cancelled` when work remains pending or in progress. It preserves `.gjc/state/team/<team>` as evidence.
 
 ## Data Plane and Control Plane
 
@@ -214,15 +223,20 @@ Semantics:
 - `.gjc/state/team/<team>/manifest.v2.json`
 - `.gjc/state/team/<team>/phase.json`
 - `.gjc/state/team/<team>/events.jsonl`
+- `.gjc/state/team/<team>/trace.jsonl`
+- `.gjc/state/team/<team>/trace-errors.jsonl`
 - `.gjc/state/team/<team>/telemetry.jsonl`
 - `.gjc/state/team/<team>/monitor-snapshot.json`
 - `.gjc/state/team/<team>/integration-report.md`
-- `.gjc/state/team/<team>/tasks/task-1.json`
-- `.gjc/state/team/<team>/evidence/tasks/task-1.json`
+- `.gjc/state/team/<team>/tasks/task-1.json` (includes structured `completion_evidence` after completed transitions)
 - `.gjc/state/team/<team>/mailbox/worker-1/<message-id>.json`
 - `.gjc/state/team/<team>/mailbox/worker-1.json` (legacy compatibility view)
 - `.gjc/state/team/<team>/notifications/<notification-id>.json`
 - `.gjc/state/team/<team>/workers/<worker>/startup-ack.json`
+- `.gjc/state/team/<team>/workers/<worker>/status.json`
+- `.gjc/state/team/<team>/workers/<worker>/lifecycle.json`
+- `.gjc/state/team/<team>/workers/<worker>/heartbeat.json`
+- `.gjc/state/team/<team>/workers/<worker>/shutdown-request.json`
 - `.gjc/state/team/<team>/workers/<worker>/nudges/<fingerprint>.json`
 - `.gjc/reports/team-commit-hygiene/<team>.ledger.json`
 
@@ -233,17 +247,28 @@ Use `gjc team api` for machine-readable task lifecycle operations.
 ```bash
 gjc team api worker-startup-ack --input '{"team_name":"my-team","worker_id":"worker-1","protocol_version":"1"}' --json
 gjc team api claim-task --input '{"team_name":"my-team","worker_id":"worker-1"}' --json
-gjc team api transition-task-status --input '{"team_name":"my-team","task_id":"task-1","to":"completed","worker_id":"worker-1","claim_token":"<claim-token>","evidence":"summary of completed work and validation"}' --json
+gjc team api transition-task-status --input '{"team_name":"my-team","task_id":"task-1","to":"completed","worker_id":"worker-1","claim_token":"<claim-token>","completion_evidence":{"summary":"Completed requested work and verified it locally.","items":[{"kind":"command","status":"passed","summary":"Focused test passed","command":"bun test packages/coding-agent/test/gjc-runtime/team-runtime.test.ts"}],"files":["packages/coding-agent/test/gjc-runtime/team-runtime.test.ts"],"notes":"Include at least one passed command or verified inspection/artifact item."}}' --json
+gjc team api update-worker-status --input '{"team_name":"my-team","worker_id":"worker-1","status":"working","current_task_id":"task-1"}' --json
+gjc team api recover-stale-claims --input '{"team_name":"my-team"}' --json
+gjc team api read-traces --input '{"team_name":"my-team"}' --json
+gjc team api create-task --input '{"team_name":"my-team","subject":"Verify delivery","description":"Run verification","owner":"worker-1","lane":"verification","required_role":"executor","depends_on":["task-1"]}' --json
 ```
 
 Canonical worker lifecycle operations:
 
-- `worker-startup-ack` before task work
+- `worker-startup-ack` before task work; this records startup ACK and moves `workers/<worker>/lifecycle.json` to `ready`
 - `claim-task`
-- `transition-task-status` with the claim token, worker id, and completion evidence
+- `update-worker-status` when the worker starts/stops a task-local activity; this updates worker-reported `status.json` without replacing the runtime lifecycle source of truth
+- `recover-stale-claims` is leader/runtime-owned; it clears expired claim files, requeues in-progress tasks claimed by stale workers, and records `task_claim_recovered` events without modifying terminal task records or completion evidence
+- `transition-task-status` with the claim token, worker id, and structured `completion_evidence` object
 - `release-task-claim`
+Claim eligibility is ordered and must not be bypassed: explicit task id selection, task status/terminal checks, owner/assignee checks, lane/role checks, dependency/blocked checks, then active lease creation. `lane` is descriptive metadata; `required_role` and `allowed_roles` are the enforced worker role gates.
 
-GJC-team interop operations are also available for mailbox, native notification, worker heartbeat/status, startup ACK, events, monitor snapshots, approvals, and shutdown request/ack flows; run `gjc team api --help` for the full operation list.
+Completion evidence is stored inline on the task record as `completion_evidence`. It must include a non-empty `summary`, an `items` array, and at least one item with `status: "passed"` or `status: "verified"`. Valid item kinds are `command`, `inspection`, and `artifact`; command items require `command`. The camel-case alias `completionEvidence` is accepted by the API input, but legacy string `evidence` and separate evidence files are not part of the public completion contract.
+
+GJC-team interop operations are also available for mailbox, native notification, worker heartbeat/status, stale-claim recovery, startup ACK, events, monitor snapshots, approvals, and shutdown request/ack flows; run `gjc team api --help` for the full operation list.
+
+Structured trace records in `trace.jsonl` are append-only schema version 1 entries. Each trace references the legacy `events.jsonl` source via `source_event_id`, keeps `event_type`, worker/task ids, and includes `evidence_refs` for completion evidence or claim recovery when available. Trace append failures are isolated in `trace-errors.jsonl` and do not break `events.jsonl` compatibility.
 
 ## GJC-native concept parity
 
@@ -262,9 +287,10 @@ Forbidden assumptions: do not copy OMX paths, Codex notify payload formats, OMX
 Worker protocol:
 
 - Send startup ACK with `worker-startup-ack` before task work.
+- Report worker activity with `update-worker-status`; this is the worker-reported status plane, not the runtime lifecycle state.
 - Claim pending work with `claim-task`.
 - Transition the task to `completed`, `failed`, or `blocked` with `transition-task-status`, including claim token and evidence for completion.
-- Commit or leave worktree changes in the worker worktree; the leader `status`/`resume` monitor path will auto-checkpoint dirty worktrees and integrate committed history where possible.
+- Commit or leave worktree changes in the worker worktree; the leader `monitor`/`resume` path will auto-checkpoint dirty worktrees and integrate committed history where possible.
 - Record implementation/verification evidence in normal task output and state files; leader integration/conflict notifications are delivered through `.gjc/state/team/<team>/mailbox/leader-fixed.json`.
 
 ## Environment Knobs
@@ -291,7 +317,7 @@ Operator note (important for GJC panes):
 - **Split failure:** startup records a failed phase if state was already initialized, rolls back created worktrees, and never kills the leader tmux session.
 - **Worker API ENOENT:** team state is missing or `GJC_TEAM_STATE_ROOT` points somewhere else. Check `.gjc/state/team/<team>/` before assuming worker failure.
 - **Stale pane on shutdown:** shutdown only kills a recorded worker pane when it still belongs to the stored `tmux_target` and is not the leader pane. Stale panes outside that target require manual inspection.
-- **Integration conflict:** `gjc team status <team>` / `resume` aborts the failing merge, cherry-pick, or worker rebase; inspect `.gjc/state/team/<team>/integration-report.md`, `.gjc/state/team/<team>/events.jsonl`, `.gjc/state/team/<team>/mailbox/leader-fixed.json`, and `.gjc/reports/team-commit-hygiene/<team>.ledger.json`.
+- **Integration conflict:** `gjc team monitor <team>` / `resume` aborts the failing merge, cherry-pick, or worker rebase; `gjc team status <team>` is read-only inspection. Inspect `.gjc/state/team/<team>/integration-report.md`, `.gjc/state/team/<team>/events.jsonl`, `.gjc/state/team/<team>/mailbox/leader-fixed.json`, and `.gjc/reports/team-commit-hygiene/<team>.ledger.json`.
 
 ### Safe Manual Intervention (last resort)
 
@@ -330,8 +356,8 @@ tmux list-panes -F '#{pane_id}	#{pane_current_command}	#{pane_start_command}'
 tmux kill-pane -t %450
 tmux kill-pane -t %451
 
-# 3) Remove stale team state only after preserving needed evidence (example)
-rm -rf .gjc/state/team/<team-name>
+# 3) Remove stale team state only after preserving needed evidence, using the state runtime
+# cleanup verb documented by the current manifest
 
 # 4) Retry
 gjc team executor "fresh retry"
@@ -349,8 +375,8 @@ When operating this skill, provide concrete progress evidence:
 
 1. Team started line (`Team started: <name>`)
 2. tmux target and worker pane id
-3. task state from `gjc team status <team>` or `.gjc/state/team/<team>/tasks/task-1.json`
-4. shutdown outcome (`phase=complete`, worker status `stopped`) when the run is terminal; incomplete shutdowns must report `phase=cancelled`/`failed`
+3. task state from read-only `gjc team status <team>`, mutating `gjc team monitor <team>`, or `.gjc/state/team/<team>/tasks/task-1.json`
+4. shutdown outcome (`phase=complete`, worker status `stopped`) when the run is terminal; incomplete shutdowns must report `phase=cancelled`/`failed`, and integration-blocked shutdowns must report `phase=awaiting_integration`
 
 Do not claim success without file/pane evidence.
 Do not claim clean completion if shutdown occurred with `in_progress>0`.