@gajae-code/coding-agent 0.18.6 → 0.18.8

package/src/modes/controllers/input-controller.ts

@@ -40,7 +40,9 @@ import { CommandPalette, type CommandPaletteAction, type CommandPaletteEntry } f
 import type { PasteTextContext } from "../components/custom-editor";
 import { QueuePaneComponent } from "../components/queue-pane";
 import { type QueuedMessageMoveDirection, QueuedMessageSelectorComponent } from "../components/queued-message-selector";
+import { focusedUiOwnsInterrupt } from "../utils/interrupt-ownership";
 import { matchesAppInterrupt } from "../utils/keybinding-matchers";
+import { createUnforwardedOptionChordWarner } from "../utils/macos-option-forwarding";
 
 const QUEUE_SELECTOR_NAVIGATION_ACTIONS = [
 	"tui.select.up",
@@ -95,6 +97,8 @@ function isExpandable(obj: unknown): obj is Expandable {
 export class InputController {
 	readonly actionRegistry: ActionRegistry<void>;
 	readonly #loadPastedImageBatch: typeof loadPastedImageBatch;
+	/** Session id with an automatic-title request pending, if any. */
+	#autoTitleInFlightSessionId: string | undefined;
 	#deferredSubmission?: {
 		text: string;
 		images?: InteractiveModeContext["pendingImages"];
@@ -546,15 +550,23 @@ export class InputController {
 			if (!isInterruptKey && !isClearKey) {
 				return undefined;
 			}
-			if (isClearKey && !isInterruptKey && this.ctx.hasActiveBtw() && this.ctx.handleBtwEscape()) {
+			// Listeners run before focused handleInput. Yield interrupt/back to the
+			// focused UI before touching BTW, maintenance, retries or workflow state.
+			// Clear (Ctrl+C by default) remains a global abort, even if the same
+			// key is also configured as interrupt.
+			if (isInterruptKey && !isClearKey && focusedUiOwnsInterrupt(this.ctx)) {
+				this.#resetEscapeGestures();
+				return undefined;
+			}
+			if (isClearKey && this.ctx.hasActiveBtw() && this.ctx.handleBtwEscape()) {
 				this.#resetEscapeGestures();
 				return { consume: true };
 			}
-			if (isClearKey && !isInterruptKey && this.ctx.hookSelector?.hasActiveInlineInput?.() === true) {
+			if (isClearKey && this.ctx.hookSelector?.hasActiveInlineInput?.() === true) {
 				this.#resetEscapeGestures();
 				return undefined;
 			}
-			if (isClearKey && !isInterruptKey) {
+			if (isClearKey) {
 				if (this.#handlePendingSteerInterrupt()) return { consume: true };
 				if (
 					this.#handleCancellableWorkEscape({
@@ -807,6 +819,12 @@ export class InputController {
 		this.ctx.editor.setActionKeys("app.message.queue", this.ctx.keybindings.getKeys("app.message.queue"));
 		this.ctx.editor.onQueue = () => this.#executeAction("app.message.queue");
 		this.#registerCommandPaletteAction("app.message.queue", queue, true);
+		this.ctx.editor.onUnforwardedOptionChord ??= createUnforwardedOptionChordWarner({
+			platform: process.platform,
+			terminalProgram: Bun.env.TERM_PROGRAM,
+			formatKeyHint: key => this.ctx.keybindings.formatKeyHint(key),
+			showWarning: message => this.ctx.showWarning(message),
+		});
 
 		this.ctx.editor.onViewportPageScroll = direction => this.ctx.ui.scrollViewportPages(direction);
 		this.ctx.editor.onViewportFollowLive = () => {
@@ -1163,6 +1181,7 @@ export class InputController {
 				return;
 			}
 			this.ctx.queueCompactionMessage(text, "steer", composer);
+			this.#titleQueuedCompactionText(text);
 			return;
 		}
 
@@ -1172,6 +1191,9 @@ export class InputController {
 		// This handles extension commands (execute immediately), prompt template expansion, and queueing
 		if (this.ctx.session.isStreaming) {
 			invalidateSessionTitleGeneration(this.ctx.sessionManager);
+			// A turn started by a skill command has no user message yet, so the
+			// first typed message can arrive here instead of the idle path.
+			this.maybeGenerateSessionTitle(text);
 			if (this.#canModifyComposer(composer)) {
 				this.ctx.editor.addToHistory(text);
 				this.ctx.editor.setText("");
@@ -1200,32 +1222,7 @@ export class InputController {
 		// First, move any pending bash components to chat
 		this.ctx.flushPendingBashComponents();
 
-		// Generate session title on first message
-		const hasUserMessages = this.ctx.session.messages.some((m: AgentMessage) => m.role === "user");
-		if (!hasUserMessages && !this.ctx.sessionManager.getSessionName() && !$pickenv("GJC_NO_TITLE", "PI_NO_TITLE")) {
-			const registry = this.ctx.session.modelRegistry;
-			generateSessionTitle(
-				text,
-				registry,
-				this.ctx.settings,
-				this.ctx.session.credentialSessionId,
-				this.ctx.session.model,
-				provider => this.ctx.session.agent.metadataForProvider(provider),
-			)
-				.then(async title => {
-					if (title) {
-						const applied = await this.ctx.sessionManager.setSessionName(title, "auto");
-						if (applied) {
-							setSessionTerminalTitle(
-								this.ctx.sessionManager.getSessionName()!,
-								this.ctx.sessionManager.getCwd(),
-							);
-							this.ctx.updateEditorBorderColor();
-						}
-					}
-				})
-				.catch(() => {});
-		}
+		this.maybeGenerateSessionTitle(text);
 
 		if (this.ctx.onInputCallback) {
 			// Include any pending images from clipboard paste
@@ -1628,6 +1625,51 @@ export class InputController {
 		return this.ctx.settings.get("busyPromptMode") === "steer" ? "steer" : "followUp";
 	}
 
+	/**
+	 * Generate the automatic session title from the first user message. Called
+	 * from the editor submit and queue-shortcut paths (idle and streaming) and
+	 * from interactive startup messages; it is a no-op once the session has a
+	 * user message, a name, or a title request already in flight. The result is
+	 * bound to the session that requested it: a completion that lands after the
+	 * session was replaced (New Session, switch, resume) is discarded.
+	 */
+	maybeGenerateSessionTitle(text: string): void {
+		if (this.ctx.sessionManager.getSessionName()) return;
+		const sessionId = this.ctx.sessionManager.getSessionId();
+		if (this.#autoTitleInFlightSessionId === sessionId) return;
+		if ($pickenv("GJC_NO_TITLE", "PI_NO_TITLE")) return;
+		if (this.ctx.session.messages.some((m: AgentMessage) => m.role === "user")) return;
+		// Keep locally intercepted command arguments away from the title model.
+		if (this.ctx.session.isLocallyHandledSlashCommand(text)) return;
+		this.#autoTitleInFlightSessionId = sessionId;
+		generateSessionTitle(
+			text,
+			this.ctx.session.modelRegistry,
+			this.ctx.settings,
+			this.ctx.session.credentialSessionId,
+			this.ctx.session.model,
+			provider => this.ctx.session.agent.metadataForProvider(provider),
+		)
+			.then(async title => {
+				if (!title || this.ctx.sessionManager.getSessionId() !== sessionId) return;
+				const applied = await this.ctx.sessionManager.setSessionName(title, "auto");
+				if (applied) {
+					setSessionTerminalTitle(this.ctx.sessionManager.getSessionName()!, this.ctx.sessionManager.getCwd());
+					this.ctx.updateEditorBorderColor();
+				}
+			})
+			.catch(() => {})
+			.finally(() => {
+				if (this.#autoTitleInFlightSessionId === sessionId) this.#autoTitleInFlightSessionId = undefined;
+			});
+	}
+
+	/** Title text accepted into the compaction queue; skill commands replay through the skill path and are not titled. */
+	#titleQueuedCompactionText(text: string): void {
+		if (parseSkillInvocations(text, this.ctx.skillCommands ?? new Map()).length > 0) return;
+		this.maybeGenerateSessionTitle(text);
+	}
+
 	/**
 	 * Dispatch skill slash invocation(s) (`/skill:<name>`) through custom messages
 	 * using the supplied `streamingBehavior`. Returns true if the text contains a
@@ -1736,6 +1778,7 @@ export class InputController {
 				return;
 			}
 			this.ctx.queueCompactionMessage(text, "followUp");
+			this.#titleQueuedCompactionText(text);
 			return;
 		}
 
@@ -1750,6 +1793,7 @@ export class InputController {
 					followUpQueuePolicy: "sequential",
 				}),
 			);
+			this.maybeGenerateSessionTitle(text);
 			this.ctx.updatePendingMessagesDisplay();
 			this.ctx.ui.requestRender();
 			return;
@@ -1761,6 +1805,7 @@ export class InputController {
 			return;
 		}
 
+		this.maybeGenerateSessionTitle(text);
 		if (this.ctx.session.isStreaming) {
 			this.ctx.editor.addToHistory(text);
 			this.ctx.editor.setText("");

package/src/modes/controllers/runtime-mcp-command-controller.ts

@@ -44,7 +44,8 @@ import { parseCommandArgs } from "../shared";
 import { buildOAuthLoginAnchor, createOAuthUrlCopyLease } from "../shared/oauth-url-copy";
 import { theme } from "../theme/theme";
 import type { InteractiveModeContext } from "../types";
-import { matchesAppInterrupt } from "../utils/keybinding-matchers";
+import { focusedUiOwnsInterrupt } from "../utils/interrupt-ownership";
+import { matchesAppClear, matchesAppInterrupt } from "../utils/keybinding-matchers";
 import { groupBySource, parseRemoveArgs, readScopeFlag, showCommandMessage } from "./command-controller-shared";
 
 function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
@@ -645,7 +646,9 @@ export class MCPCommandController {
 		const cancellationUnsubscribe =
 			signal === undefined && typeof this.ctx.ui.addInputListener === "function"
 				? this.ctx.ui.addInputListener(data => {
-						if (data !== "\x03" && !matchesAppInterrupt(data)) return;
+						const isClearKey = data === "\x03" || matchesAppClear(data);
+						if (!isClearKey && !matchesAppInterrupt(data)) return;
+						if (!isClearKey && focusedUiOwnsInterrupt(this.ctx)) return;
 						userController.abort(new Error("OAuth flow cancelled"));
 						return { consume: true };
 					})
@@ -1839,7 +1842,9 @@ export class MCPCommandController {
 		const oauthUrlCopyLease = createOAuthUrlCopyLease(this.ctx);
 		const abortController = new AbortController();
 		const interruptUnsubscribe = this.ctx.ui.addInputListener?.(data => {
-			if (data !== "\x03" && !matchesAppInterrupt(data)) return;
+			const isClearKey = data === "\x03" || matchesAppClear(data);
+			if (!isClearKey && !matchesAppInterrupt(data)) return;
+			if (!isClearKey && focusedUiOwnsInterrupt(this.ctx)) return;
 			abortController.abort(new Error("Smithery authorization cancelled."));
 			return { consume: true };
 		});

package/src/modes/controllers/selector-controller.ts

@@ -1612,7 +1612,7 @@ export class SelectorController {
 	}
 
 	async #handleCredentialImport(): Promise<void> {
-		this.ctx.showStatus("Scanning for existing Claude Code / Codex CLI credentials…");
+		this.ctx.showStatus("Scanning for existing Claude Code / Codex CLI / Kiro CLI credentials…");
 		const preview = await runExternalCredentialAutoImport({
 			authStorage: {
 				importCredentialIfAbsent: async () => ({
@@ -2494,17 +2494,20 @@ export class SelectorController {
 	 * default) then refresh the status surfaces. Rethrows so callers surface errors.
 	 */
 	async #applyModelProfile(profileName: string, persistDefault: boolean): Promise<void> {
+		this.ctx.session.markUserModelSelection();
 		const profileLabel = formatModelProfileDisplayLabel(
 			this.ctx.session.modelRegistry.getModelProfile(profileName) ?? { name: profileName },
 		);
-		await activateModelProfile(
-			{
-				session: this.ctx.session,
-				modelRegistry: this.ctx.session.modelRegistry,
-				settings: this.ctx.settings,
-				profileName,
-			},
-			{ persistDefault },
+		await this.ctx.session.withSdkControlMutation(() =>
+			activateModelProfile(
+				{
+					session: this.ctx.session,
+					modelRegistry: this.ctx.session.modelRegistry,
+					settings: this.ctx.settings,
+					profileName,
+				},
+				{ persistDefault },
+			),
 		);
 		this.ctx.statusLine.invalidate();
 		this.ctx.updateEditorBorderColor();
@@ -2774,8 +2777,15 @@ export class SelectorController {
 							return;
 						}
 						const { model, role, thinkingLevel, selector: selectedSelector } = selection;
+						if (
+							(role !== null && role !== "default") ||
+							selection.roles?.some(targetRole => targetRole !== "default")
+						) {
+							this.ctx.session.markUserModelSelection();
+						}
 						if (role === null) {
 							// Temporary: update agent state but don't persist to settings
+							this.ctx.session.markUserModelSelection();
 							await this.ctx.session.setModelTemporary(model, thinkingLevel, {
 								cause: "temporary-operation",
 								reason: "other",
@@ -3677,12 +3687,15 @@ export class SelectorController {
 			return;
 		}
 
-		await activateModelProfile({
-			session: this.ctx.session,
-			modelRegistry: this.ctx.session.modelRegistry,
-			settings: this.ctx.settings,
-			profileName: recommendedProfile.name,
-		});
+		this.ctx.session.markUserModelSelection();
+		await this.ctx.session.withSdkControlMutation(() =>
+			activateModelProfile({
+				session: this.ctx.session,
+				modelRegistry: this.ctx.session.modelRegistry,
+				settings: this.ctx.settings,
+				profileName: recommendedProfile.name,
+			}),
+		);
 	}
 
 	async #handleOAuthLogin(providerId: string, options?: OAuthSelectorOptions): Promise<void> {

package/src/modes/interactive-mode.ts

@@ -2642,6 +2642,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#inputController.handleBackgroundCommand();
 	}
 
+	maybeGenerateSessionTitle(text: string): void {
+		this.#inputController.maybeGenerateSessionTitle(text);
+	}
+
 	handleImagePaste(): Promise<boolean> {
 		return this.#inputController.handleImagePaste();
 	}

package/src/modes/runtime-init.ts

@@ -11,6 +11,8 @@ import { ThinkingLevel } from "@gajae-code/agent-core";
 import { runExtensionCompact, runExtensionSetModel } from "../extensibility/extensions/compact-handler";
 import { getSessionSlashCommands } from "../extensibility/extensions/get-commands-handler";
 import type { ExtensionError, ExtensionUIContext } from "../extensibility/extensions/types";
+import { buildSessionProjectProgress } from "../progress/collect-project-progress";
+import { toProjectProgressSnapshot } from "../progress/progress-snapshot";
 import {
 	parseSyntheticModelId,
 	resolveSyntheticModelSelection,
@@ -201,6 +203,8 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 				return { bytes: new Uint8Array(await file.slice(start, end).arrayBuffer()), totalBytes: file.size };
 			},
 			getJobs: () => session.getAsyncJobSnapshot(),
+			getProjectProgress: async () =>
+				toProjectProgressSnapshot(await buildSessionProjectProgress(session, session.sessionManager)),
 			onJobFold: listener => session.onJobFold(listener),
 			onSessionEvent: listener => session.subscribe(listener),
 			setSdkPermissionProvider: provider => session.setSdkPermissionProvider(provider),

package/src/modes/utils/abort-message.ts

@@ -1,3 +1,5 @@
+import { getStreamIdleTimeoutRemediationMs } from "@gajae-code/ai/utils/idle-iterator";
+
 const STREAM_IDLE_TIMEOUT_PATTERN = /\bstream stalled while waiting for the next event\b/i;
 const GENERIC_ABORT_PATTERN = /^Request was aborted\.?$/i;
 const ABORT_DISPLAY_LABEL_PATTERN = /^(?:Operation aborted|Aborted after \d+ retry attempts?)(?::|$)/;
@@ -37,5 +39,5 @@ function normalizeAbortCause(errorMessage: string | undefined): string {
 function streamIdleTimeoutHint(cause: string): string {
 	if (!STREAM_IDLE_TIMEOUT_PATTERN.test(cause)) return "";
 	const separator = /[.!?]$/.test(cause) ? " " : ". ";
-	return `${separator}Hint: set PI_STREAM_IDLE_TIMEOUT_MS=300000 for slow reasoning/proxy streams, or PI_STREAM_IDLE_TIMEOUT_MS=0 to disable the watchdog.`;
+	return `${separator}Hint: set PI_STREAM_IDLE_TIMEOUT_MS=${getStreamIdleTimeoutRemediationMs()} for slow reasoning/proxy streams, or PI_STREAM_IDLE_TIMEOUT_MS=0 to disable the watchdog.`;
 }

package/src/modes/utils/interrupt-ownership.ts

@@ -0,0 +1,12 @@
+import type { InteractiveModeContext } from "../types";
+
+/** Ordinary focused UI owns interrupt/back before background work does. */
+export function focusedUiOwnsInterrupt(
+	ctx: Pick<InteractiveModeContext, "ui" | "editor" | "hookSelector" | "hookInput" | "hookEditor">,
+): boolean {
+	const focused = ctx.ui.getFocusedComponent?.();
+	if (!focused?.handleInput || focused === ctx.editor) return false;
+	// Non-inline hook prompts deliberately retain workflow-level interruption.
+	if (focused === ctx.hookSelector) return ctx.hookSelector.hasActiveInlineInput();
+	return focused !== ctx.hookInput && focused !== ctx.hookEditor;
+}

package/src/modes/utils/keybinding-matchers.ts

@@ -16,6 +16,10 @@ export function matchesAppInterrupt(data: string): boolean {
 	return matchesKey(data, "escape") || matchesKey(data, "esc");
 }
 
+export function matchesAppClear(data: string): boolean {
+	return getKeybindings().matches(data, "app.clear");
+}
+
 export function matchesSelectCancel(data: string): boolean {
 	return getKeybindings().matches(data, "tui.select.cancel");
 }

package/src/modes/utils/macos-option-forwarding.ts

@@ -0,0 +1,80 @@
+import type { KeyId } from "@gajae-code/tui";
+
+/**
+ * Characters macOS composes for Option+<letter> on the US/ABC layout when the
+ * terminal sends Option as text instead of Alt/Meta. Dead-key letters (e, i, n,
+ * u) compose nothing on their own and are absent.
+ */
+const MACOS_OPTION_COMPOSED_KEYS: ReadonlyMap<string, KeyId> = new Map<string, KeyId>([
+	["å", "alt+a"],
+	["∫", "alt+b"],
+	["ç", "alt+c"],
+	["∂", "alt+d"],
+	["ƒ", "alt+f"],
+	["©", "alt+g"],
+	["˙", "alt+h"],
+	["∆", "alt+j"],
+	["˚", "alt+k"],
+	["¬", "alt+l"],
+	["µ", "alt+m"],
+	["ø", "alt+o"],
+	["π", "alt+p"],
+	["œ", "alt+q"],
+	["®", "alt+r"],
+	["ß", "alt+s"],
+	["†", "alt+t"],
+	["√", "alt+v"],
+	["∑", "alt+w"],
+	["≈", "alt+x"],
+	["¥", "alt+y"],
+	["Ω", "alt+z"],
+]);
+
+/** The Option chord that composes `text` on the macOS US/ABC layout, if any. */
+export function macosOptionChordForComposedText(text: string): KeyId | undefined {
+	return MACOS_OPTION_COMPOSED_KEYS.get(text);
+}
+
+/** Terminal-specific instruction for sending Option as Alt/Meta, when the terminal is known. */
+export function macosOptionForwardingInstruction(terminalProgram: string | undefined): string | undefined {
+	const program = terminalProgram?.toLowerCase() ?? "";
+	if (program.includes("ghostty")) {
+		return "Ghostty: set macos-option-as-alt = true in its config, then reload the config or restart Ghostty.";
+	}
+	if (program === "apple_terminal") {
+		return "Terminal.app: enable Settings > Profiles > Keyboard > Use Option as Meta key.";
+	}
+	if (program === "iterm.app") {
+		return "iTerm2: set Settings > Profiles > Keys > Left and Right Option key to Esc+.";
+	}
+	return undefined;
+}
+
+export interface UnforwardedOptionChordWarnerOptions {
+	platform: NodeJS.Platform;
+	terminalProgram: string | undefined;
+	formatKeyHint: (key: KeyId) => string;
+	showWarning: (message: string) => void;
+}
+
+/**
+ * Builds the composer callback that explains, once, why a bound Option shortcut
+ * produced a character instead of firing. Returns undefined off macOS, where the
+ * composition table does not apply.
+ */
+export function createUnforwardedOptionChordWarner(
+	options: UnforwardedOptionChordWarnerOptions,
+): ((key: KeyId, text: string) => void) | undefined {
+	if (options.platform !== "darwin") return undefined;
+	let warned = false;
+	return (key, text) => {
+		if (warned) return;
+		warned = true;
+		const instruction =
+			macosOptionForwardingInstruction(options.terminalProgram) ??
+			"Configure the terminal to send Option as Alt/Meta (Esc+).";
+		options.showWarning(
+			`${options.formatKeyHint(key)} arrived as "${text}": the terminal is sending Option as text, so Option shortcuts cannot reach GJC. ${instruction} Or remap the shortcut to a Control chord in keybindings.json.`,
+		);
+	};
+}

package/src/progress/collect-project-progress.ts

@@ -0,0 +1,153 @@
+import type { SubagentLifecycle } from "../async/job-manager";
+import { readUltragoalPlan } from "../gjc-runtime/ultragoal-runtime";
+import type { Goal, GoalModeState } from "../goals/state";
+import type { SessionManager } from "../session/session-manager";
+import {
+	normalizeWorkflowHudSummary,
+	readVisibleSkillActiveStateWithStatus,
+	type VisibleSkillActiveStateReadStatus,
+} from "../skill-state/active-state";
+import { findLatestTodoPhasesFromEntries, type TodoPhase } from "../tools/todo-write";
+import type { ProgressDurableSource } from "./progress-contract";
+import {
+	computeProjectProgress,
+	type ProgressUltragoalInput,
+	type ProgressWorkflowInput,
+	type ProjectProgressInput,
+	type ProjectProgressReport,
+} from "./project-progress";
+
+/** Session-owned state the overview reads; everything else comes from durable `.gjc` files. */
+export interface ProjectProgressSessionView {
+	cwd: string;
+	/** GJC session id that scopes `.gjc/_session-{id}` state; without it no workflow state is read. */
+	sessionId: string | undefined;
+	goal: Goal | undefined;
+	todoPhases: readonly TodoPhase[];
+	subagents: readonly SubagentLifecycle[];
+}
+
+async function readWorkflows(
+	cwd: string,
+	sessionId: string,
+): Promise<{ status: VisibleSkillActiveStateReadStatus; workflows: ProgressWorkflowInput[] }> {
+	// The tolerant HUD reader maps an unreadable session snapshot to "nothing
+	// active" and lets snapshot-only rows survive; this projection must report
+	// unreadable state as unreadable, and never report a row without authority.
+	const { status, state } = await readVisibleSkillActiveStateWithStatus(cwd, sessionId);
+	const workflows = (state?.active_skills ?? [])
+		.filter(entry => entry.active !== false)
+		.map(entry => {
+			const hud = normalizeWorkflowHudSummary(entry.hud);
+			return {
+				skill: entry.skill,
+				phase: entry.phase?.trim() || "unknown",
+				...(hud?.summary ? { summary: hud.summary } : {}),
+				chips: (hud?.chips ?? []).map(chip => ({
+					label: chip.label,
+					...(chip.value ? { value: chip.value } : {}),
+					...(chip.severity ? { severity: chip.severity } : {}),
+				})),
+			};
+		});
+	return { status, workflows };
+}
+
+async function readUltragoal(cwd: string, sessionId: string): Promise<ProgressUltragoalInput | undefined> {
+	const plan = await readUltragoalPlan(cwd, sessionId);
+	if (!plan || plan.goals.length === 0) return undefined;
+	return {
+		objective: plan.gjcObjective,
+		stories: plan.goals.map(goal => ({
+			id: goal.id,
+			title: goal.title,
+			status: goal.status,
+			hasVerificationReceipt: typeof goal.completionVerification?.receiptId === "string",
+		})),
+	};
+}
+
+/**
+ * Gather progress input strictly by reading state. A source that fails to read
+ * is reported as unreadable and excluded; it never aborts the overview and is
+ * never replaced by a guess. A source rebuilt from authoritative per-entry
+ * records after its snapshot failed to read is reported as recovered; one whose
+ * readable derived snapshot listed stale rows is reported as discarded; one whose
+ * rows could not be attributed to an authority is reported as unresolved.
+ */
+export async function collectProjectProgressInput(view: ProjectProgressSessionView): Promise<ProjectProgressInput> {
+	const unreadable: ProgressDurableSource[] = [];
+	const recovered: ProgressDurableSource[] = [];
+	const discarded: ProgressDurableSource[] = [];
+	const unresolved: ProgressDurableSource[] = [];
+	const sessionId = view.sessionId?.trim() || undefined;
+	let workflows: ProgressWorkflowInput[] = [];
+	let ultragoal: ProgressUltragoalInput | undefined;
+	if (sessionId) {
+		const [workflowResult, ultragoalResult] = await Promise.allSettled([
+			readWorkflows(view.cwd, sessionId),
+			readUltragoal(view.cwd, sessionId),
+		]);
+		if (workflowResult.status === "rejected" || workflowResult.value.status === "failed") {
+			unreadable.push("workflow-state");
+		} else {
+			workflows = workflowResult.value.workflows;
+			if (workflowResult.value.status === "recovered") recovered.push("workflow-state");
+			else if (workflowResult.value.status === "discarded") discarded.push("workflow-state");
+			else if (workflowResult.value.status === "unresolved") unresolved.push("workflow-state");
+		}
+		if (ultragoalResult.status === "fulfilled") ultragoal = ultragoalResult.value;
+		else unreadable.push("ultragoal-plan");
+	}
+	return {
+		...(view.goal
+			? {
+					goal: {
+						objective: view.goal.objective,
+						status: view.goal.status,
+						timeUsedSeconds: view.goal.timeUsedSeconds,
+					},
+				}
+			: {}),
+		todos: view.todoPhases.flatMap(phase =>
+			phase.tasks.map(task => ({ content: task.content, status: task.status })),
+		),
+		workflows,
+		...(ultragoal ? { ultragoal } : {}),
+		subagents: [...view.subagents],
+		sessionStateRead: sessionId !== undefined,
+		unreadable,
+		recovered,
+		discarded,
+		unresolved,
+	};
+}
+
+/** The live session state `/progress` and `session.progress` read; satisfied by `AgentSession`. */
+export interface ProjectProgressSessionSource {
+	getGoalModeState(): GoalModeState | undefined;
+	getTodoPhases(): TodoPhase[];
+	getSubagentLifecycleStatuses(): SubagentLifecycle[];
+}
+
+/**
+ * Single entry point shared by the human view and the machine snapshot.
+ *
+ * Todos come from the persisted branch history, as `/todo` reads them: the live
+ * list drops completed and abandoned items when a session is resumed, so it is
+ * only the fallback when no todo state was ever persisted. A persisted empty
+ * list is authoritative and is not replaced by live state.
+ */
+export async function buildSessionProjectProgress(
+	session: ProjectProgressSessionSource,
+	sessionManager: Pick<SessionManager, "getCwd" | "getSessionId" | "getBranch">,
+): Promise<ProjectProgressReport> {
+	const input = await collectProjectProgressInput({
+		cwd: sessionManager.getCwd(),
+		sessionId: sessionManager.getSessionId(),
+		goal: session.getGoalModeState()?.goal,
+		todoPhases: findLatestTodoPhasesFromEntries(sessionManager.getBranch()) ?? session.getTodoPhases(),
+		subagents: session.getSubagentLifecycleStatuses(),
+	});
+	return computeProjectProgress(input);
+}