@gajae-code/coding-agent 0.18.7 → 0.18.8

package/src/progress/project-progress.ts

@@ -0,0 +1,446 @@
+/**
+ * Read-only project progress projection. One report is re-shaped into the
+ * machine-facing `session.progress` SDK snapshot (`progress-snapshot.ts`), and
+ * the human-facing `/progress` view renders that same snapshot
+ * (`render-progress.ts`) in the TUI, text mode, and ACP.
+ *
+ * The completion indicator is derived exclusively from countable units that
+ * carry a durable completion status. It never weights units by size, never
+ * credits partial work on an open unit, and never infers progress from
+ * conversation text, elapsed time, or token spend. When no countable basis
+ * exists the indicator is reported as unknown instead of guessed.
+ */
+import type { SubagentLifecycle } from "../async/job-manager";
+import { selectNextSchedulableGoal, type UltragoalGoalStatus } from "../gjc-runtime/ultragoal-runtime";
+import type { GoalStatus } from "../goals/state";
+import type { WorkflowHudSeverity } from "../skill-state/active-state";
+import type { TodoStatus } from "../tools/todo-write";
+import type {
+	ProgressAgentCounts,
+	ProgressBasisKind,
+	ProgressDurableSource,
+	ProgressHeadline,
+	ProgressReviewVerdict,
+	ProgressSignalKind,
+	ProgressSignalSource,
+} from "./progress-contract";
+
+export interface ProgressGoalInput {
+	objective: string;
+	status: GoalStatus;
+	timeUsedSeconds: number;
+}
+
+export interface ProgressTodoInput {
+	content: string;
+	status: TodoStatus;
+}
+
+export interface ProgressWorkflowChip {
+	label: string;
+	value?: string;
+	severity?: WorkflowHudSeverity;
+}
+
+export interface ProgressWorkflowInput {
+	skill: string;
+	phase: string;
+	summary?: string;
+	chips: ProgressWorkflowChip[];
+}
+
+export interface ProgressStoryInput {
+	id: string;
+	title: string;
+	status: UltragoalGoalStatus;
+	/** A completion-verification (quality-gate) receipt is recorded on the story. */
+	hasVerificationReceipt: boolean;
+}
+
+export interface ProgressUltragoalInput {
+	objective: string;
+	stories: ProgressStoryInput[];
+}
+
+export const PROGRESS_SOURCE_LABELS: Record<ProgressDurableSource, string> = {
+	"workflow-state": "Workflow state",
+	"ultragoal-plan": "Ultragoal plan",
+};
+
+export interface ProjectProgressInput {
+	goal?: ProgressGoalInput;
+	todos: ProgressTodoInput[];
+	workflows: ProgressWorkflowInput[];
+	ultragoal?: ProgressUltragoalInput;
+	subagents: SubagentLifecycle[];
+	/** Whether session-scoped `.gjc` state (workflows, ultragoal plan) was consulted at all. */
+	sessionStateRead: boolean;
+	/** Durable sources that exist but could not be read; excluded from the estimate. */
+	unreadable: ProgressDurableSource[];
+	/** Durable sources whose primary record was unreadable but whose contents were recovered from authoritative per-entry records. */
+	recovered: ProgressDurableSource[];
+	/** Durable sources whose readable derived snapshot listed entries the authoritative per-entry records do not; those stale entries were discarded. */
+	discarded: ProgressDurableSource[];
+	/** Durable sources listing entries whose authority could not be established; those entries are excluded and their absence is unconfirmed. */
+	unresolved: ProgressDurableSource[];
+}
+
+export interface ProgressSignal {
+	kind: ProgressSignalKind;
+	/** Which durable state produced the signal. */
+	source: ProgressSignalSource;
+	/** Stable identifier inside the source: story id, workflow skill, or durable source key. */
+	ref?: string;
+	text: string;
+}
+
+export interface ProgressCompletion {
+	basis: ProgressBasisKind;
+	done: number;
+	total: number;
+	/**
+	 * Displayed whole percent, or undefined when no countable basis exists.
+	 * Never rounds up to 100 while a unit is open, nor down to 0 once a unit is done.
+	 */
+	percent: number | undefined;
+}
+
+export interface ProgressStoryCounts {
+	total: number;
+	complete: number;
+	active: number;
+	pending: number;
+	blocked: number;
+	superseded: number;
+	verified: number;
+	/** Active story, else the next pending one; blocked, review-blocked, and failed stories are never selected. */
+	current?: { id: string; title: string };
+}
+
+export interface ProgressTodoCounts {
+	total: number;
+	completed: number;
+	inProgress: number;
+	pending: number;
+	abandoned: number;
+	current?: string;
+}
+
+/** Verification evidence that durable state actually records; nothing is inferred. */
+export interface ProgressVerification {
+	/** Complete stories that carry a quality-gate completion receipt (only when stories are complete). */
+	storyReceipts?: { complete: number; withReceipt: number };
+	/** Latest review verdict chips published by active workflows. */
+	reviewVerdicts: ProgressReviewVerdict[];
+}
+
+export interface ProjectProgressReport {
+	headline: ProgressHeadline;
+	completion: ProgressCompletion;
+	/** How the completion indicator was derived, in plain words. */
+	basisExplanation: string;
+	goal?: ProgressGoalInput;
+	/** The ultragoal plan the story counts were derived from. */
+	ultragoal?: ProgressUltragoalInput;
+	stories?: ProgressStoryCounts;
+	todoItems: ProgressTodoInput[];
+	todos?: ProgressTodoCounts;
+	workflows: ProgressWorkflowInput[];
+	agents: ProgressAgentCounts;
+	verification: ProgressVerification;
+	signals: ProgressSignal[];
+	sessionStateRead: boolean;
+	unreadable: ProgressDurableSource[];
+	recovered: ProgressDurableSource[];
+	discarded: ProgressDurableSource[];
+	unresolved: ProgressDurableSource[];
+}
+
+const BLOCKING_STORY_STATUSES: ReadonlySet<UltragoalGoalStatus> = new Set(["failed", "blocked", "review_blocked"]);
+
+function plural(count: number, singular: string, pluralForm = `${singular}s`): string {
+	return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+
+function countStories(ultragoal: ProgressUltragoalInput): ProgressStoryCounts {
+	const counts: ProgressStoryCounts = {
+		total: 0,
+		complete: 0,
+		active: 0,
+		pending: 0,
+		blocked: 0,
+		superseded: 0,
+		verified: 0,
+	};
+	for (const story of ultragoal.stories) {
+		if (story.status === "superseded") {
+			counts.superseded++;
+			continue;
+		}
+		counts.total++;
+		if (story.status === "complete") {
+			counts.complete++;
+			if (story.hasVerificationReceipt) counts.verified++;
+		} else if (story.status === "active") counts.active++;
+		else if (story.status === "pending") counts.pending++;
+		else if (BLOCKING_STORY_STATUSES.has(story.status)) counts.blocked++;
+	}
+	// Mirror the Ultragoal scheduler. A read-only projection never opts into
+	// `--retry-failed`, so failed stories are not presented as next work.
+	const current = selectNextSchedulableGoal(ultragoal.stories, false);
+	if (current) counts.current = { id: current.id, title: current.title };
+	return counts;
+}
+
+function countTodos(todos: readonly ProgressTodoInput[]): ProgressTodoCounts {
+	const counts: ProgressTodoCounts = { total: 0, completed: 0, inProgress: 0, pending: 0, abandoned: 0 };
+	for (const todo of todos) {
+		if (todo.status === "abandoned") {
+			counts.abandoned++;
+			continue;
+		}
+		counts.total++;
+		if (todo.status === "completed") counts.completed++;
+		else if (todo.status === "in_progress") counts.inProgress++;
+		else counts.pending++;
+	}
+	const current = todos.find(todo => todo.status === "in_progress") ?? todos.find(todo => todo.status === "pending");
+	if (current) counts.current = current.content;
+	return counts;
+}
+
+function countAgents(statuses: readonly SubagentLifecycle[]): ProgressAgentCounts {
+	const counts: ProgressAgentCounts = {
+		total: statuses.length,
+		running: 0,
+		waiting: 0,
+		completed: 0,
+		failed: 0,
+		cancelled: 0,
+	};
+	for (const status of statuses) {
+		if (status === "running") counts.running++;
+		else if (status === "queued" || status === "paused") counts.waiting++;
+		else if (status === "completed") counts.completed++;
+		else if (status === "failed") counts.failed++;
+		else counts.cancelled++;
+	}
+	return counts;
+}
+
+/** Whole percent that never overstates (no 100 while open) nor erases (no 0 once started) progress. */
+export function displayPercent(done: number, total: number): number | undefined {
+	if (total <= 0) return undefined;
+	if (done >= total) return 100;
+	if (done <= 0) return 0;
+	return Math.min(99, Math.max(1, Math.round((done / total) * 100)));
+}
+
+function selectCompletion(
+	stories: ProgressStoryCounts | undefined,
+	todos: ProgressTodoCounts | undefined,
+	goal: ProgressGoalInput | undefined,
+): { completion: ProgressCompletion; explanation: string } {
+	if (stories && stories.total > 0) {
+		return {
+			completion: {
+				basis: "ultragoal-stories",
+				done: stories.complete,
+				total: stories.total,
+				percent: displayPercent(stories.complete, stories.total),
+			},
+			explanation:
+				"Ultragoal stories marked complete in the durable plan (goals.json). Every story counts equally regardless of size; superseded stories are excluded; open stories earn no partial credit.",
+		};
+	}
+	if (todos && todos.total > 0) {
+		return {
+			completion: {
+				basis: "todos",
+				done: todos.completed,
+				total: todos.total,
+				percent: displayPercent(todos.completed, todos.total),
+			},
+			explanation:
+				"Session todo items marked completed. Every item counts equally regardless of size; abandoned items are excluded; in-progress items earn no partial credit.",
+		};
+	}
+	if (goal?.status === "complete") {
+		return {
+			completion: { basis: "goal-status", done: 1, total: 1, percent: 100 },
+			explanation: "The session goal is marked complete; no finer-grained plan or todo list was recorded.",
+		};
+	}
+	return {
+		completion: { basis: "none", done: 0, total: 0, percent: undefined },
+		explanation:
+			"No ultragoal plan or todo list is recorded, so there is nothing countable to measure. Create a plan (/skill:ultragoal) or a todo list to get a completion estimate.",
+	};
+}
+
+function workflowSignals(workflows: readonly ProgressWorkflowInput[]): ProgressSignal[] {
+	const signals: ProgressSignal[] = [];
+	for (const workflow of workflows) {
+		for (const chip of workflow.chips) {
+			const text = `${workflow.skill}: ${chip.label}${chip.value ? ` ${chip.value}` : ""}`;
+			const base = { source: "workflow" as const, ref: workflow.skill, text };
+			if (chip.severity === "blocked" || chip.severity === "error") signals.push({ kind: "blocker", ...base });
+			else if (chip.severity === "warning") signals.push({ kind: "pending", ...base });
+		}
+	}
+	return signals;
+}
+
+function collectVerification(
+	stories: ProgressStoryCounts | undefined,
+	workflows: readonly ProgressWorkflowInput[],
+): ProgressVerification {
+	const reviewVerdicts: ProgressReviewVerdict[] = [];
+	for (const workflow of workflows) {
+		const verdict = workflow.chips.find(chip => chip.label === "verdict" && chip.value);
+		if (verdict?.value) reviewVerdicts.push({ skill: workflow.skill, verdict: verdict.value });
+	}
+	return {
+		...(stories && stories.complete > 0
+			? { storyReceipts: { complete: stories.complete, withReceipt: stories.verified } }
+			: {}),
+		reviewVerdicts,
+	};
+}
+
+export function computeProjectProgress(input: ProjectProgressInput): ProjectProgressReport {
+	const stories = input.ultragoal ? countStories(input.ultragoal) : undefined;
+	const todos = input.todos.length > 0 ? countTodos(input.todos) : undefined;
+	const agents = countAgents(input.subagents);
+	const { completion, explanation } = selectCompletion(stories, todos, input.goal);
+
+	const signals: ProgressSignal[] = [];
+	if (input.ultragoal) {
+		for (const story of input.ultragoal.stories) {
+			if (BLOCKING_STORY_STATUSES.has(story.status)) {
+				signals.push({
+					kind: "blocker",
+					source: "ultragoal",
+					ref: story.id,
+					text: `Story ${story.id} is ${story.status.replace("_", " ")}: ${story.title}`,
+				});
+			}
+		}
+	}
+	// The ultragoal HUD chips summarize the same goals.json stories reported above;
+	// repeating them would list every blocked story twice.
+	signals.push(
+		...workflowSignals(
+			input.ultragoal ? input.workflows.filter(workflow => workflow.skill !== "ultragoal") : input.workflows,
+		),
+	);
+	if (agents.running + agents.waiting > 0) {
+		signals.push({
+			kind: "pending",
+			source: "subagents",
+			text: `${plural(agents.running + agents.waiting, "subagent")} still running, queued, or paused; their work counts only once it is recorded in the plan or todos.`,
+		});
+	}
+	if (agents.failed > 0)
+		signals.push({
+			kind: "note",
+			source: "subagents",
+			text: `${plural(agents.failed, "subagent")} failed this session.`,
+		});
+	if (completion.basis === "ultragoal-stories" && todos && todos.inProgress + todos.pending > 0) {
+		signals.push({
+			kind: "note",
+			source: "todos",
+			text: `Open todos (${todos.inProgress + todos.pending}) are tracked separately; the estimate follows the ultragoal plan.`,
+		});
+	}
+	for (const source of input.unreadable) {
+		signals.push({
+			kind: "note",
+			source: "state",
+			ref: source,
+			text: `${PROGRESS_SOURCE_LABELS[source]} could not be read and is excluded from the estimate.`,
+		});
+	}
+	for (const source of input.recovered) {
+		signals.push({
+			kind: "note",
+			source: "state",
+			ref: source,
+			text: `${PROGRESS_SOURCE_LABELS[source]} snapshot could not be read; its contents were recovered from authoritative per-entry records.`,
+		});
+	}
+	for (const source of input.discarded) {
+		signals.push({
+			kind: "note",
+			source: "state",
+			ref: source,
+			text: `${PROGRESS_SOURCE_LABELS[source]} snapshot is stale; workflows it lists without an authoritative per-entry record were discarded, not reported as active.`,
+		});
+	}
+	for (const source of input.unresolved) {
+		signals.push({
+			kind: "note",
+			source: "state",
+			ref: source,
+			text: `${PROGRESS_SOURCE_LABELS[source]} lists workflows whose authority cannot be established; they are not reported as active, and their absence is unconfirmed.`,
+		});
+	}
+
+	const headline = selectHeadline(input, completion, stories, todos, agents, signals);
+	if (headline === "awaiting-completion" && input.goal && input.goal.status !== "complete") {
+		signals.push({
+			kind: "pending",
+			source: "goal",
+			text: "All tracked units are done, but the session goal is not marked complete yet.",
+		});
+	}
+
+	return {
+		headline,
+		completion,
+		basisExplanation: explanation,
+		...(input.goal ? { goal: input.goal } : {}),
+		...(input.ultragoal ? { ultragoal: input.ultragoal } : {}),
+		...(stories ? { stories } : {}),
+		todoItems: input.todos,
+		...(todos ? { todos } : {}),
+		workflows: input.workflows,
+		agents,
+		verification: collectVerification(stories, input.workflows),
+		signals,
+		sessionStateRead: input.sessionStateRead,
+		unreadable: input.unreadable,
+		recovered: input.recovered,
+		discarded: input.discarded,
+		unresolved: input.unresolved,
+	};
+}
+
+function selectHeadline(
+	input: ProjectProgressInput,
+	completion: ProgressCompletion,
+	stories: ProgressStoryCounts | undefined,
+	todos: ProgressTodoCounts | undefined,
+	agents: ProgressAgentCounts,
+	signals: readonly ProgressSignal[],
+): ProgressHeadline {
+	const goalStatus = input.goal?.status;
+	if (goalStatus === "dropped") return "dropped";
+	if (signals.some(signal => signal.kind === "blocker")) return "blocked";
+	const allDone = completion.total > 0 && completion.done >= completion.total;
+	if (allDone) {
+		const goalOpen = goalStatus !== undefined && goalStatus !== "complete";
+		return goalOpen || agents.running + agents.waiting > 0 ? "awaiting-completion" : "complete";
+	}
+	if (goalStatus === "paused") return "paused";
+	const somethingMoving =
+		completion.done > 0 ||
+		(stories?.active ?? 0) > 0 ||
+		(todos?.inProgress ?? 0) > 0 ||
+		agents.running > 0 ||
+		goalStatus === "active";
+	if (somethingMoving) return "in-progress";
+	if (completion.total > 0) return "not-started";
+	return input.workflows.length > 0 ? "in-progress" : "no-tracked-work";
+}

package/src/progress/render-progress.ts

@@ -0,0 +1,209 @@
+/**
+ * Human-readable `/progress` view. It renders the machine-facing
+ * `session.progress` snapshot, so the TUI, text mode, and ACP (which reads the
+ * snapshot over the SDK) show exactly what an orchestrator receives.
+ *
+ * Like `progress-contract.ts`, this module must stay a dependency leaf: the ACP
+ * agent imports it, and the ACP entrypoint may not reach the session graph.
+ */
+import {
+	boundSnapshotText,
+	type ProgressBasisKind,
+	type ProgressHeadline,
+	type ProjectProgressSnapshot,
+} from "./progress-contract";
+
+/** ACP palette copy for `/progress`, shared by the builtin registry and the production ACP agent. */
+export const PROGRESS_COMMAND_ACP_DESCRIPTION = "Show read-only project progress overview";
+
+export const PROGRESS_HEADLINE_LABELS: Record<ProgressHeadline, string> = {
+	complete: "Complete",
+	"awaiting-completion": "Tracked work done, awaiting completion",
+	blocked: "Blocked",
+	"in-progress": "In progress",
+	"not-started": "Not started",
+	paused: "Paused",
+	dropped: "Dropped",
+	"no-tracked-work": "No tracked work",
+};
+
+const BASIS_UNIT_LABELS: Record<Exclude<ProgressBasisKind, "none">, string> = {
+	"ultragoal-stories": "ultragoal stories complete",
+	todos: "todo items completed",
+	"goal-status": "session goal complete",
+};
+
+/** Styling hooks so the TUI can colour output while ACP/text mode stays plain. */
+export interface ProgressRenderStyle {
+	bold(text: string): string;
+	fg(color: "accent" | "success" | "warning" | "error" | "dim" | "muted", text: string): string;
+}
+
+export interface ProgressRenderOptions {
+	style?: ProgressRenderStyle;
+	/**
+	 * Sanitizes and bounds durable text to one display line of at most `max` columns.
+	 * Defaults to a character-bounded plain-text clip for ACP and text mode.
+	 */
+	clip?: (text: string, max: number) => string;
+	barWidth?: number;
+}
+
+const PLAIN_STYLE: ProgressRenderStyle = { bold: text => text, fg: (_color, text) => text };
+
+function plural(count: number, singular: string, pluralForm = `${singular}s`): string {
+	return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+
+function headlineColor(headline: ProgressHeadline): "success" | "warning" | "error" | "accent" | "muted" {
+	switch (headline) {
+		case "complete":
+			return "success";
+		case "blocked":
+			return "error";
+		case "awaiting-completion":
+		case "paused":
+			return "warning";
+		case "dropped":
+		case "no-tracked-work":
+			return "muted";
+		default:
+			return "accent";
+	}
+}
+
+function formatElapsed(seconds: number): string {
+	const minutes = Math.floor(Math.max(0, seconds) / 60);
+	if (minutes < 1) return "<1m";
+	const hours = Math.floor(minutes / 60);
+	return hours > 0 ? `${hours}h ${minutes % 60}m` : `${minutes}m`;
+}
+
+/** Human-readable verification lines; the structured form is `snapshot.verification`. */
+function verificationLines(verification: ProjectProgressSnapshot["verification"]): string[] {
+	const lines: string[] = [];
+	const receipts = verification.storyReceipts;
+	if (receipts) {
+		lines.push(
+			`${receipts.withReceipt} of ${plural(receipts.complete, "complete story", "complete stories")} carry a recorded quality-gate receipt`,
+		);
+	}
+	for (const { skill, verdict } of verification.reviewVerdicts) lines.push(`${skill} review verdict: ${verdict}`);
+	return lines;
+}
+
+/** Render the overview as display lines (no trailing newline). */
+export function renderProgressSnapshot(
+	snapshot: ProjectProgressSnapshot,
+	options: ProgressRenderOptions = {},
+): string[] {
+	const style = options.style ?? PLAIN_STYLE;
+	const clip = options.clip ?? boundSnapshotText;
+	const width = options.barWidth ?? 24;
+	const label = (text: string) => style.fg("dim", text.padEnd(14));
+	const lines: string[] = [];
+	const color = headlineColor(snapshot.state);
+
+	lines.push(`${style.bold("Project progress")}  ${style.fg(color, PROGRESS_HEADLINE_LABELS[snapshot.state])}`);
+	const { completion } = snapshot;
+	if (completion.percent === null || completion.basis === "none") {
+		lines.push(`${style.fg("dim", `[${"·".repeat(width)}]`)} unknown`);
+	} else {
+		const filled = Math.round((completion.percent / 100) * width);
+		const bar = `${style.fg(color, "█".repeat(filled))}${style.fg("dim", "░".repeat(width - filled))}`;
+		const unit = BASIS_UNIT_LABELS[completion.basis];
+		lines.push(
+			`[${bar}] ~${completion.percent}%  ${style.fg("muted", `${completion.done} of ${completion.total} ${unit}`)}`,
+		);
+	}
+	lines.push(style.fg("dim", `Basis: ${completion.explanation}`));
+	lines.push("");
+
+	const { goal, ultragoal, todos } = snapshot.execution;
+	const activeWork = snapshot.activeWork;
+	if (goal) {
+		lines.push(
+			`${label("Goal")}${goal.status} · ${formatElapsed(goal.timeUsedSeconds)} · ${clip(goal.objective, 100)}`,
+		);
+	}
+	if (ultragoal) {
+		const s = ultragoal.counts;
+		const parts = [`${s.complete}/${s.total} complete`];
+		if (s.active > 0) parts.push(`${s.active} active`);
+		if (s.pending > 0) parts.push(`${s.pending} pending`);
+		if (s.blocked > 0) parts.push(style.fg("error", `${s.blocked} blocked`));
+		if (s.superseded > 0) parts.push(`${s.superseded} superseded`);
+		lines.push(`${label("Ultragoal")}${parts.join(" · ")}`);
+		if (activeWork.story) {
+			lines.push(`${label("")}next: ${clip(activeWork.story.id, 24)} ${clip(activeWork.story.title, 90)}`);
+		}
+	}
+	if (todos) {
+		const t = todos.counts;
+		const parts = [`${t.completed}/${t.total} completed`];
+		if (t.inProgress > 0) parts.push(`${t.inProgress} in progress`);
+		if (t.pending > 0) parts.push(`${t.pending} pending`);
+		if (t.abandoned > 0) parts.push(`${t.abandoned} abandoned`);
+		lines.push(`${label("Todos")}${parts.join(" · ")}`);
+		if (activeWork.todo) lines.push(`${label("")}now: ${clip(activeWork.todo, 90)}`);
+	}
+	if (activeWork.workflows.length === 0 && snapshot.sources.unreadable.includes("workflow-state")) {
+		lines.push(`${label("Workflows")}${style.fg("warning", "unknown: workflow state could not be read")}`);
+	} else if (activeWork.workflows.length === 0 && snapshot.sources.unresolved.includes("workflow-state")) {
+		lines.push(`${label("Workflows")}${style.fg("warning", "unknown: workflow state could not be reconciled")}`);
+	} else if (activeWork.workflows.length === 0 && activeWork.omittedWorkflows === 0) {
+		lines.push(`${label("Workflows")}${style.fg("dim", "none active")}`);
+	} else {
+		activeWork.workflows.forEach((workflow, index) => {
+			const chips = workflow.chips
+				.filter(chip => chip.value)
+				.slice(0, 4)
+				.map(chip => `${chip.label} ${clip(chip.value ?? "", 40)}`);
+			const detail = [workflow.phase, ...chips].join(" · ");
+			lines.push(`${label(index === 0 ? "Workflows" : "")}${clip(workflow.skill, 24)}: ${clip(detail, 110)}`);
+			if (workflow.summary) lines.push(`${label("")}${style.fg("muted", clip(workflow.summary, 100))}`);
+		});
+		if (activeWork.omittedWorkflows > 0) {
+			lines.push(
+				`${label(activeWork.workflows.length === 0 ? "Workflows" : "")}${style.fg("dim", `… ${plural(activeWork.omittedWorkflows, "more active workflow")} not shown`)}`,
+			);
+		}
+	}
+	const a = activeWork.agents;
+	if (a.total === 0) {
+		lines.push(`${label("Agents")}${style.fg("dim", "no subagents this session")}`);
+	} else {
+		const parts: string[] = [];
+		if (a.running > 0) parts.push(`${a.running} running`);
+		if (a.waiting > 0) parts.push(`${a.waiting} queued/paused`);
+		if (a.completed > 0) parts.push(`${a.completed} completed`);
+		if (a.failed > 0) parts.push(style.fg("error", `${a.failed} failed`));
+		if (a.cancelled > 0) parts.push(`${a.cancelled} cancelled`);
+		lines.push(`${label("Agents")}${parts.join(" · ")}`);
+	}
+	const verification = verificationLines(snapshot.verification);
+	if (verification.length === 0) {
+		lines.push(`${label("Verification")}${style.fg("dim", "no durable verification evidence recorded")}`);
+	} else {
+		verification.forEach((line, index) => {
+			lines.push(`${label(index === 0 ? "Verification" : "")}${clip(line, 110)}`);
+		});
+	}
+
+	if (snapshot.attention.length > 0 || snapshot.omittedAttention > 0) {
+		lines.push("", style.bold("Attention"));
+		for (const item of snapshot.attention) {
+			const marker =
+				item.kind === "blocker"
+					? style.fg("error", "✖")
+					: item.kind === "pending"
+						? style.fg("warning", "…")
+						: style.fg("dim", "·");
+			lines.push(`  ${marker} ${clip(item.text, 140)}`);
+		}
+		if (snapshot.omittedAttention > 0) {
+			lines.push(`  ${style.fg("dim", `… ${plural(snapshot.omittedAttention, "more attention item")} not shown`)}`);
+		}
+	}
+	return lines;
+}

package/src/prompts/system/master-mode.md

@@ -25,4 +25,5 @@ You are running as a GJC master session. You coordinate peer GJC sessions throug
 ## Delegation discipline
 
 - Give each spawned child one bounded task with explicit acceptance criteria in the seed prompt; monitor via broker-routed status/tail and aggregate results yourself.
+- `gjc sdk session send` only starts a new turn; on a child that is mid-turn it fails with `busy` and was not applied. Correct a running child you spawned with `gjc sdk session raw control <id> --op turn.steer --json-input '{"text":"<instruction>"}' --idempotency-key <key>`, and stop its active turn with `--op turn.abort --json-input '{}'`. There are no `session.steer` or `session.abort` operations.
 - Clean up children you created with `gjc sdk session raw global --op session.close --json-input '{"sessionId":"<id>"}' --idempotency-key <key>` when their work is integrated. Orphaned children are reaped automatically after the configured grace period, but explicit close is the polite default.

package/src/prompts/tools/skill-discovery.md

@@ -3,7 +3,7 @@ Discover bundled GJC workflow, project, and user runtime skills without loading
 <instruction>
 - Includes the four bundled GJC workflow skills (`autoresearch`, `deep-interview`, `ralplan`, `ultragoal`) as `source: "bundled"` candidates from the generated bundled catalog; they are always available, cannot be replaced by filesystem copies, and are included for `source: "all"` but excluded by explicit `source: "project"`/`"user"` requests.
 - Returns thin metadata only: name, description, source scope, path, and use conditions when present. Bundled paths are stable catalog identifiers, not filesystem paths.
-- In trusted Git projects, `.gjc/skills` may be a symlink to a directory inside the same repository (for example `../.agents/skills`). Link and target identities remain checked through body loading; external targets and symlinked user/profile roots are refused. Do not replace a safe project link with copied files to make discovery work.
+- In trusted Git projects, `.gjc/skills` may be a symlink to a directory inside the same repository (for example `../.agents/skills`). Project link and target identities remain checked through body loading; external project targets are refused. An individual user-scope skill symlink inside `~/.gjc/agent/skills` or a configured custom directory may resolve outside its scan root when user/global `skills.trustUserSkills` is enabled; project settings cannot grant this permission. Its link and target identities remain checked through body loading. Symlinked user/profile authority roots remain refused. Do not replace a safe project link with copied files to make discovery work.
 - Claude Code (`.claude/skills`) and Codex (`.codex/skills`) layouts are explicit import sources into `.gjc`, never invokable candidates. They are not returned as candidates; instead, each convention skill found in a trusted scope is reported in `diagnostics` with the exact copy command that enables it (copy into `.gjc/skills`), so a skill placed in a documented convention location is discoverable in a normal session without being silently loaded.
 - Discovery is on by default in a normal session. `query` matching is conjunctive substring: every whitespace-separated term must appear in a skill's name, description, source, or use conditions, unless a term equals the exact skill name — one keyword that appears nowhere in the candidate's metadata drops every candidate, so query with exact names or few terms known to appear literally, not topic keyword lists. When zero candidates are returned, the result carries a `notice` if discovery config disabled a requested scope, a non-empty query filtered out scanned skills, or diagnostics explain observed skills that were skipped or filtered. Only an empty result without a `notice` means no skills were scanned and no diagnostics were produced; never report a zero-candidate result as proof no skill exists.
 - When skills were scanned but not advertised (protected-name collision with a bundled workflow skill, include/ignore/disable policy filters, invalid frontmatter, shadowing), the result carries a bounded `diagnostics` list explaining why.