@gajae-code/coding-agent 0.3.1 → 0.3.2

package/src/config/model-profiles.ts

@@ -0,0 +1,155 @@
+import type { GjcModelAssignmentTargetId } from "./model-registry";
+import type { ModelsConfig } from "./models-config-schema";
+
+export type ModelProfileRole = GjcModelAssignmentTargetId;
+
+export interface ModelProfileDefinition {
+	name: string;
+	requiredProviders: string[];
+	modelMapping: Partial<Record<ModelProfileRole, string>>;
+	source: "builtin" | "user";
+}
+
+export interface ResolvedProfileBinding {
+	defaultSelector?: string;
+	agentModelOverrides: Partial<Record<Exclude<ModelProfileRole, "default">, string>>;
+}
+
+function parseModelSelectorProvider(selector: string): string | undefined {
+	const slashIdx = selector.indexOf("/");
+	if (slashIdx <= 0) return undefined;
+	return selector.slice(0, slashIdx);
+}
+
+export function deriveModelProfileMappedProviders(definition: Pick<ModelProfileDefinition, "modelMapping">): string[] {
+	const providers = new Set<string>();
+	for (const selector of Object.values(definition.modelMapping)) {
+		if (!selector) continue;
+		const provider = parseModelSelectorProvider(selector);
+		if (provider) providers.add(provider);
+	}
+	return [...providers].sort((a, b) => a.localeCompare(b));
+}
+
+export function aggregateModelProfileRequiredProviders(
+	requiredProviders: readonly string[],
+	definition: Pick<ModelProfileDefinition, "modelMapping">,
+): string[] {
+	const providers = new Set(requiredProviders);
+	for (const provider of deriveModelProfileMappedProviders(definition)) {
+		providers.add(provider);
+	}
+	return [...providers];
+}
+
+const profile = (
+	name: string,
+	requiredProviders: string[],
+	modelMapping: Record<ModelProfileRole, string>,
+): ModelProfileDefinition => ({
+	name,
+	requiredProviders: aggregateModelProfileRequiredProviders(requiredProviders, { modelMapping }),
+	modelMapping,
+	source: "builtin",
+});
+
+export const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[] = [
+	profile("opencode-go-eco", ["opencode-go"], {
+		default: "opencode-go/deepseek-v4-flash",
+		executor: "opencode-go/qwen3.5-plus",
+		architect: "opencode-go/glm-5",
+		planner: "opencode-go/minimax-m2.5",
+		critic: "opencode-go/kimi-k2.5",
+	}),
+	profile("opencode-go-standard", ["opencode-go"], {
+		default: "opencode-go/kimi-k2.6",
+		executor: "opencode-go/qwen3.6-plus",
+		architect: "opencode-go/glm-5.1",
+		planner: "opencode-go/minimax-m2.7",
+		critic: "opencode-go/deepseek-v4-pro",
+	}),
+	profile("opencode-go-pro", ["opencode-go"], {
+		default: "opencode-go/qwen3.7-max",
+		executor: "opencode-go/kimi-k2.6",
+		architect: "opencode-go/deepseek-v4-pro:high",
+		planner: "opencode-go/glm-5.1:high",
+		critic: "opencode-go/minimax-m2.7:high",
+	}),
+	profile("codex-eco", ["openai-codex"], {
+		default: "openai-codex/gpt-5.4-mini",
+		executor: "openai-codex/gpt-5.4-nano",
+		architect: "openai-codex/gpt-5.4-mini",
+		planner: "openai-codex/gpt-5.4-mini",
+		critic: "openai-codex/gpt-5.4-mini",
+	}),
+	profile("codex-standard", ["openai-codex"], {
+		default: "openai-codex/gpt-5.4:medium",
+		executor: "openai-codex/gpt-5.4:low",
+		architect: "openai-codex/gpt-5.4:xhigh",
+		planner: "openai-codex/gpt-5.4:medium",
+		critic: "openai-codex/gpt-5.4:high",
+	}),
+	profile("codex-pro", ["openai-codex"], {
+		default: "openai-codex/gpt-5.5",
+		executor: "openai-codex/gpt-5.2-codex",
+		architect: "openai-codex/gpt-5.1-codex-max:high",
+		planner: "openai-codex/gpt-5.5:high",
+		critic: "openai-codex/gpt-5.3-codex-spark:high",
+	}),
+	profile("opencode-go-codex-eco", ["opencode-go", "openai-codex"], {
+		default: "opencode-go/deepseek-v4-flash",
+		executor: "opencode-go/qwen3.5-plus",
+		architect: "openai-codex/gpt-5.4-mini",
+		planner: "openai-codex/gpt-5.4-mini",
+		critic: "openai-codex/gpt-5.4-mini",
+	}),
+	profile("opencode-go-codex-standard", ["opencode-go", "openai-codex"], {
+		default: "opencode-go/kimi-k2.6",
+		executor: "opencode-go/qwen3.6-plus",
+		architect: "openai-codex/gpt-5.4",
+		planner: "openai-codex/gpt-5.4",
+		critic: "openai-codex/gpt-5.4",
+	}),
+	profile("opencode-go-codex-pro", ["opencode-go", "openai-codex"], {
+		default: "opencode-go/qwen3.7-max",
+		executor: "opencode-go/kimi-k2.6",
+		architect: "openai-codex/gpt-5.1-codex-max:high",
+		planner: "openai-codex/gpt-5.5:high",
+		critic: "openai-codex/gpt-5.3-codex-spark:high",
+	}),
+];
+
+export function mergeModelProfiles(userProfiles?: ModelsConfig["profiles"]): Map<string, ModelProfileDefinition> {
+	const profiles = new Map<string, ModelProfileDefinition>();
+	for (const definition of BUILTIN_MODEL_PROFILES) {
+		profiles.set(definition.name, {
+			...definition,
+			requiredProviders: [...definition.requiredProviders],
+			modelMapping: { ...definition.modelMapping },
+		});
+	}
+	for (const [name, definition] of Object.entries(userProfiles ?? {})) {
+		const modelMapping = { ...definition.model_mapping };
+		profiles.set(name, {
+			name,
+			requiredProviders: aggregateModelProfileRequiredProviders(definition.required_providers, { modelMapping }),
+			modelMapping,
+			source: "user",
+		});
+	}
+	return profiles;
+}
+
+export function resolveProfileBindings(definition: ModelProfileDefinition): ResolvedProfileBinding {
+	const { default: defaultSelector, executor, architect, planner, critic } = definition.modelMapping;
+	const agentModelOverrides: ResolvedProfileBinding["agentModelOverrides"] = {};
+	if (executor !== undefined) agentModelOverrides.executor = executor;
+	if (architect !== undefined) agentModelOverrides.architect = architect;
+	if (planner !== undefined) agentModelOverrides.planner = planner;
+	if (critic !== undefined) agentModelOverrides.critic = critic;
+	return { defaultSelector, agentModelOverrides };
+}
+
+export function formatAvailableProfileNames(profiles: ReadonlyMap<string, ModelProfileDefinition>): string {
+	return [...profiles.keys()].sort((a, b) => a.localeCompare(b)).join(", ");
+}

package/src/config/model-registry.ts

@@ -43,6 +43,7 @@ import {
 	formatCanonicalVariantSelector,
 	type ModelEquivalenceConfig,
 } from "./model-equivalence";
+import { type ModelProfileDefinition, mergeModelProfiles } from "./model-profiles";
 import {
 	type ModelOverride,
 	type ModelsConfig,
@@ -511,6 +512,7 @@ interface CustomModelsResult {
 	configuredProviders?: Set<string>;
 	equivalence?: ModelEquivalenceConfig;
 	modelBindings?: NonNullable<ModelsConfig["modelBindings"]>;
+	profiles?: ModelsConfig["profiles"];
 	error?: ConfigError;
 	found: boolean;
 }
@@ -954,6 +956,7 @@ export class ModelRegistry {
 	#modelOverrides: Map<string, Map<string, ModelOverride>> = new Map();
 	#equivalenceConfig: ModelEquivalenceConfig | undefined;
 	#configuredModelBindings: NonNullable<ModelsConfig["modelBindings"]> | undefined;
+	#modelProfiles: Map<string, ModelProfileDefinition> = mergeModelProfiles();
 	#modelBindingsTargetSettings: Settings | undefined;
 	#appliedModelBindingRoles = new Set<string>();
 	#appliedAgentModelBindingOverrides = new Set<string>();
@@ -1093,6 +1096,7 @@ export class ModelRegistry {
 			configuredProviders = new Set(),
 			equivalence,
 			modelBindings,
+			profiles,
 			error: configError,
 		} = this.#loadCustomModels();
 		this.#configError = configError;
@@ -1103,6 +1107,7 @@ export class ModelRegistry {
 		this.#modelOverrides = modelOverrides;
 		this.#equivalenceConfig = equivalence;
 		this.#configuredModelBindings = modelBindings;
+		this.#modelProfiles = mergeModelProfiles(profiles);
 
 		this.#addImplicitDiscoverableProviders(configuredProviders);
 		const builtInModels = this.#applyHardcodedModelPolicies(this.#loadBuiltInModels(overrides));
@@ -1343,6 +1348,7 @@ export class ModelRegistry {
 				discoverableProviders: [],
 				configuredProviders: new Set(),
 				error,
+				profiles: undefined,
 				found: true,
 			};
 		} else if (status === "not-found") {
@@ -1353,6 +1359,7 @@ export class ModelRegistry {
 				keylessProviders: new Set(),
 				discoverableProviders: [],
 				configuredProviders: new Set(),
+				profiles: undefined,
 				found: false,
 			};
 		}
@@ -1441,10 +1448,22 @@ export class ModelRegistry {
 			configuredProviders,
 			equivalence: value.equivalence,
 			modelBindings: value.modelBindings,
+			profiles: value.profiles,
 			found: true,
 		};
 	}
 
+	getModelProfiles(): Map<string, ModelProfileDefinition> {
+		return new Map(this.#modelProfiles);
+	}
+
+	getModelProfile(name: string): ModelProfileDefinition | undefined {
+		return this.#modelProfiles.get(name);
+	}
+
+	getAvailableModelProfileNames(): string[] {
+		return [...this.#modelProfiles.keys()].sort((a, b) => a.localeCompare(b));
+	}
 	applyConfiguredModelBindings(targetSettings: Settings): void {
 		this.#modelBindingsTargetSettings = targetSettings;
 		this.#applyConfiguredModelBindingsToTarget();

package/src/config/model-resolver.ts

@@ -764,6 +764,7 @@ export async function resolveModelOverrideWithAuthFallback(
 	parentActiveModelPattern: string | undefined,
 	modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">,
 	settings?: Settings,
+	sessionId?: string,
 ): Promise<{
 	model?: Model<Api>;
 	thinkingLevel?: ThinkingLevel;
@@ -775,7 +776,7 @@ export async function resolveModelOverrideWithAuthFallback(
 		return { ...primary, authFallbackUsed: false };
 	}
 
-	const primaryKey = await modelRegistry.getApiKey(primary.model);
+	const primaryKey = await modelRegistry.getApiKey(primary.model, sessionId);
 	if (primaryKey === kNoAuth || isAuthenticated(primaryKey)) {
 		return { ...primary, authFallbackUsed: false };
 	}
@@ -787,7 +788,7 @@ export async function resolveModelOverrideWithAuthFallback(
 	if (modelsAreEqual(fallback.model, primary.model)) {
 		return { ...primary, authFallbackUsed: false };
 	}
-	const fallbackKey = await modelRegistry.getApiKey(fallback.model);
+	const fallbackKey = await modelRegistry.getApiKey(fallback.model, sessionId);
 	if (!isAuthenticated(fallbackKey)) {
 		return { ...primary, authFallbackUsed: false };
 	}

package/src/config/models-config-schema.ts

@@ -76,6 +76,39 @@ const ModelBindingsSchema = z.object({
 	modelRoles: z.record(z.string(), z.string().min(1)).optional(),
 	agentModelOverrides: z.record(z.string(), z.string().min(1)).optional(),
 });
+export const ProfileRoleSchema = z.enum(["default", "executor", "architect", "planner", "critic"]);
+
+function isValidProfileModelSelector(value: string): boolean {
+	if (value.includes(",")) return false;
+	const slashIdx = value.indexOf("/");
+	if (slashIdx <= 0 || slashIdx === value.length - 1) return false;
+	const provider = value.slice(0, slashIdx);
+	const modelId = value.slice(slashIdx + 1);
+	if (!provider || !modelId) return false;
+	const parts = modelId.split(":");
+	if (parts.length > 2) return false;
+	const [base, suffix] = parts;
+	if (!base) return false;
+	return suffix === undefined || ["minimal", "low", "medium", "high", "xhigh"].includes(suffix);
+}
+
+export const ProfileModelSelectorSchema = z
+	.string()
+	.min(1)
+	.refine(value => isValidProfileModelSelector(value), {
+		message: "Expected provider/modelId with optional :effort suffix",
+	});
+
+export const ProfileModelMappingSchema = z.partialRecord(ProfileRoleSchema, ProfileModelSelectorSchema);
+
+export const ProfileDefinitionSchema = z
+	.object({
+		required_providers: z.array(z.string().min(1)).min(1),
+		model_mapping: ProfileModelMappingSchema,
+	})
+	.strict();
+
+export const ProfilesSchema = z.record(z.string().min(1), ProfileDefinitionSchema);
 
 const ModelDefinitionSchema = z
 	.object({
@@ -205,7 +238,10 @@ export const ModelsConfigSchema = z
 		providers: z.record(z.string(), ProviderConfigSchema).optional(),
 		modelBindings: ModelBindingsSchema.optional(),
 		equivalence: EquivalenceConfigSchema.optional(),
+		profiles: ProfilesSchema.optional(),
 	})
 	.strict();
 
 export type ModelsConfig = z.infer<typeof ModelsConfigSchema>;
+export type ModelProfileConfig = z.infer<typeof ProfileDefinitionSchema>;
+export type ModelProfilesConfig = z.infer<typeof ProfilesSchema>;

package/src/config/settings-schema.ts

@@ -314,6 +314,16 @@ export const SETTINGS_SCHEMA = {
 	disabledExtensions: { type: "array", default: DEFAULT_DISABLED_EXTENSIONS },
 
 	modelRoles: { type: "record", default: EMPTY_STRING_RECORD },
+	"modelProfile.default": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "model",
+			label: "Default Model Profile",
+			description: "Model profile applied automatically at startup",
+			options: "runtime",
+		},
+	},
 
 	modelTags: { type: "record", default: EMPTY_MODEL_TAGS_RECORD },
 

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

@@ -161,12 +161,22 @@ gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evid
 
 Workers do not own ultragoal goal state, do not create worker ultragoal ledgers, and do not checkpoint Ultragoal. Workers must not run `gjc ultragoal checkpoint`; checkpoint authority stays with the leader after worker tasks are terminal. Team launch remains explicit; Ultragoal does not auto-launch Team and performs no hidden goal mutation.
 
+## Internal Ultragoal sub-skill fragments
+
+The completion-gate cleanup sweep is driven by `ai-slop-cleaner`, an internal Ultragoal sub-skill bundled as a `kind: "skill-fragment"` prompt with parent skill `ultragoal` (installed at `skill-fragments/ultragoal/ai-slop-cleaner.md`). It is analogous to deep-interview's auto-research fragment: loaded on demand for one specific hook, never a user-facing skill.
+
+- It is not slash-command discoverable, has no public skill-listing entry, and is never resolvable through `skill://`.
+- It is a read-only detector+reporter over the active story's changed files only: it never edits code, writes files, mutates `.gjc/`, checkpoints, calls goal tools, or spawns workflows.
+- It classifies every finding as blocking or advisory across the full taxonomy (fallback-like masking vs. grounded, duplication, dead code, needless abstraction, boundary violations, UI/design slop, missing tests).
+- The leader and a leader-spawned `executor` own all fixes; the cleaner reruns until zero blocking findings remain. Advisory findings live in the gate report only.
+- Recursion guard: it must not spawn nested `ralplan`/`team`/`deep-interview`/`ultragoal`; broad or architectural findings are handed back to the leader as review blockers.
+
 ## Mandatory completion cleanup and review gate
 
 An ultragoal story cannot be checkpointed `complete` until the active agent has run the quality gate. The gate is plan-first, contract-driven, and surface-based:
 
 1. Run targeted implementation verification for the story.
-2. Run a cleanup/refactor review pass on changed files only; if there are no relevant edits, the cleaner still runs and records a passed/no-op report.
+2. Run the internal ai-slop-cleaner skill fragment as the final cleanup sweep on the story's changed files only, before verification and red-team so only clean code is reviewed. It is a read-only detector that emits an `AI SLOP CLEANUP REPORT`; if there are no relevant edits it still runs and records a passed/no-op report. Every BLOCKING cleaner finding is a completion blocker: the leader spawns an `executor` to fix blocking findings only, then reruns the cleaner until blocking findings are zero. Advisory findings are included in the gate report only and are not written to the Ultragoal ledger. Carry the report through the existing `qualityGate.iteration.evidence` field; do not add a new top-level quality-gate key.
 3. Rerun verification after the cleaner pass.
 4. Delegate an `architect` review covering all three lanes:
    - architecture-side: system boundaries, layering, data/control flow, operational risks.

package/src/defaults/gjc/skills/ultragoal/ai-slop-cleaner.md

@@ -0,0 +1,61 @@
+# Ultragoal AI Slop Cleaner Fragment
+
+You are the AI slop cleaner for the Ultragoal completion gate. This is an internal Ultragoal sub-skill, loaded on demand as a `kind: "skill-fragment"` prompt with parent skill `ultragoal`. It is never user-facing: not slash-command discoverable, no public skill listing entry, and never resolvable through `skill://`.
+
+You are a **read-only detector and reporter**. You never edit code, write files, run formatters, mutate `.gjc/` state, checkpoint, call goal tools, or spawn workflows. You detect slop in the active Ultragoal story's changed files, classify each finding, and emit a report. The Ultragoal leader spawns an `executor` to fix BLOCKING findings; you do not fix anything yourself.
+
+## Scope
+
+- Inspect ONLY the active Ultragoal story's changed-files list. No broad rewrites, no inspection outside that scope, no new dependencies.
+- Allow only narrow supporting reads needed to understand the contracts of changed files; if you need broader context, report that need to the leader instead of expanding scope.
+- If there are no relevant edits, emit a passed/no-op report (`Gate Result: PASS`, `Changed Files Reviewed` listing the files as "no relevant edits").
+- Recursion guard: you are already inside an Ultragoal workflow. Do NOT spawn nested `ralplan`, `team`, `deep-interview`, or `ultragoal` workflows. Broad, ambiguous, cross-layer, or architectural findings are handed to the leader as review blockers, not resolved here.
+
+## Taxonomy
+
+Classify every finding against the full taxonomy:
+
+1. **Fallback-like code** — classify each as **masking fallback slop** or **grounded compatibility/fail-safe fallback**.
+   - Masking signals (blocking): swallowed errors, silent defaults, bypassed validation/tests, untested alternate execution paths, primary-contract suppression.
+   - Grounded signals (advisory): scoped to an external/version/fail-safe boundary, documented rationale, preserved failure evidence, and regression tests covering both primary and fallback behavior.
+2. **Duplication** — repeated logic, copy-paste branches, redundant helpers.
+3. **Dead code** — unused code, unreachable branches, stale flags, debug leftovers.
+4. **Needless abstraction** — pass-through wrappers, speculative indirection, single-use helper layers.
+5. **Boundary violations** — hidden coupling, leaky responsibilities, wrong-layer imports or side effects.
+6. **UI/design slop** — context-sensitive signals, not absolute bans; preserve intentional brand/design-system/accessibility/product rationale. Signals: small Korean body copy (challenge 11-12px; Korean body text generally needs 14px+ unless a dense accessible system supports smaller), gratuitous shadows/depth, repetitive eyebrow+title+description scaffolding and filler/emoji badges, default blue/purple palettes (e.g. #3B82F6) without rationale, over-perfect uniform 3/4-column grids, and extreme "AI demo" gradients.
+7. **Missing tests** — behavior not locked, weak regression coverage, missing edge/failure-mode cases.
+
+## Blocking vs advisory
+
+- **Blocking** if it can mask failures, violate accepted contracts, weaken boundaries, leave changed behavior untested, create maintenance traps, or make later verification unsafe.
+- **Advisory** if it is nice-to-have, stylistic/contextual, or outside safe story scope.
+- Advisory findings stay in the gate report only; they are NOT written to the Ultragoal ledger.
+
+## Report
+
+Emit exactly this text block with these mandated labels:
+
+```text
+AI SLOP CLEANUP REPORT
+======================
+
+Scope: [changed files inspected]
+Mode: read-only detector/report; no edits performed
+Blocking Findings: [none, or numbered findings with file, category, evidence, required executor fix]
+Advisory Findings: [none, or numbered findings with file, category, evidence, why advisory]
+Fallback Findings: [none, or finding -> masking fallback slop / grounded compatibility/fail-safe fallback -> blocking/advisory]
+UI/Design Findings: [none/N/A, or signal -> blocking/advisory -> rationale]
+Missing Test Findings: [none, or gap -> blocking/advisory -> required coverage]
+Recursion Guard: [confirmed no nested ralplan/team/deep-interview/ultragoal spawned; broad findings handed to leader]
+Changed Files Reviewed:
+- [path] - [reviewed / no relevant edits]
+
+Gate Result: PASS | BLOCKED
+Leader Action:
+- PASS: continue to verification, architect review, and executor red-team QA.
+- BLOCKED: spawn executor to fix BLOCKING findings only, then rerun this sweep until Blocking Findings is none.
+Remaining Risks:
+- [none, or advisory/deferred risks]
+```
+
+Port the oh-my-codex taxonomy and report shape, not its editing workflow. Do not instruct yourself to execute cleanup passes — detect and report only.

package/src/defaults/gjc-defaults.ts

@@ -7,6 +7,7 @@ import autoResearchGreenfieldFragment from "./gjc/skills/deep-interview/auto-res
 import deepInterviewSkill from "./gjc/skills/deep-interview/SKILL.md" with { type: "text" };
 import ralplanSkill from "./gjc/skills/ralplan/SKILL.md" with { type: "text" };
 import teamSkill from "./gjc/skills/team/SKILL.md" with { type: "text" };
+import aiSlopCleanerFragment from "./gjc/skills/ultragoal/ai-slop-cleaner.md" with { type: "text" };
 import ultragoalSkill from "./gjc/skills/ultragoal/SKILL.md" with { type: "text" };
 
 export const DEFAULT_GJC_DEFINITION_NAMES = ["deep-interview", "ralplan", "team", "ultragoal"] as const;
@@ -92,6 +93,12 @@ const DEFAULT_GJC_DEFINITIONS: readonly DefaultGjcDefinition[] = [
 		relativePath: "skill-fragments/deep-interview/auto-answer-uncertain.md",
 		content: autoAnswerUncertainFragment,
 	},
+	{
+		kind: "skill-fragment",
+		parentSkillName: "ultragoal",
+		relativePath: "skill-fragments/ultragoal/ai-slop-cleaner.md",
+		content: aiSlopCleanerFragment,
+	},
 ];
 
 export function getDefaultGjcDefinitions(): readonly DefaultGjcDefinition[] {

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

@@ -1,11 +1,18 @@
 import * as crypto from "node:crypto";
 import * as path from "node:path";
-import type { WorkflowHudSummary } from "../skill-state/active-state";
+import { syncSkillActiveState, type WorkflowHudSummary } from "../skill-state/active-state";
 import { buildUltragoalHudSummary as buildWorkflowUltragoalHudSummary } from "../skill-state/workflow-hud";
+import { WORKFLOW_STATE_VERSION, workflowStateStoragePath } from "../skill-state/workflow-state-contract";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
 import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
 import { renderUltragoalStatusMarkdown } from "./state-renderer";
-import { appendJsonl, writeArtifact, writeJsonAtomic } from "./state-writer";
+import {
+	appendJsonl,
+	readExistingStateForMutation,
+	writeArtifact,
+	writeJsonAtomic,
+	writeWorkflowEnvelopeAtomic,
+} from "./state-writer";
 
 export type UltragoalGjcGoalMode = "aggregate" | "per-story";
 export type UltragoalGoalStatus =
@@ -474,6 +481,92 @@ export function buildUltragoalHudSummary(
 		updatedAt: new Date().toISOString(),
 	});
 }
+function currentSessionId(): string | undefined {
+	const sessionId = process.env.GJC_SESSION_ID?.trim();
+	return sessionId || undefined;
+}
+
+function ultragoalModeStateFromSummary(
+	summary: UltragoalStatusSummary,
+	latestLedger: UltragoalLedgerEvent | undefined,
+	existing: Record<string, unknown> | undefined,
+	sessionId: string | undefined,
+): Record<string, unknown> {
+	const updatedAt = new Date().toISOString();
+	return {
+		...(existing ?? {}),
+		skill: "ultragoal",
+		version: WORKFLOW_STATE_VERSION,
+		active: summary.exists && summary.status !== "complete",
+		current_phase: summary.status,
+		status: summary.status,
+		active_goal_id: summary.currentGoal?.id,
+		counts: summary.counts,
+		brief_path: summary.paths.briefPath,
+		ledger_path: summary.paths.ledgerPath,
+		goals_path: summary.paths.goalsPath,
+		latest_ledger_event: latestLedger?.event,
+		latest_ledger_event_id: latestLedger?.eventId,
+		updated_at: updatedAt,
+		...(sessionId ? { session_id: sessionId } : {}),
+	};
+}
+
+export async function syncUltragoalWorkflowState(cwd: string): Promise<void> {
+	const summary = await getUltragoalStatus(cwd);
+	const ledger = await readUltragoalLedger(cwd);
+	const latestLedger = ledger.at(-1);
+	const sessionId = currentSessionId();
+	const modeStateActive = summary.exists && summary.status !== "complete";
+	const syncModeState = async (targetSessionId: string | undefined): Promise<void> => {
+		const statePath = workflowStateStoragePath(cwd, "ultragoal", targetSessionId);
+		const existing = await readExistingStateForMutation(statePath);
+		if (existing.kind === "corrupt" && modeStateActive)
+			throw new Error(`Cannot sync corrupt ultragoal mode-state: ${existing.error}`);
+		const existingValue = existing.kind === "valid" ? existing.value : undefined;
+		await writeWorkflowEnvelopeAtomic(
+			statePath,
+			ultragoalModeStateFromSummary(summary, latestLedger, existingValue, targetSessionId),
+			{
+				cwd,
+				receipt: {
+					cwd,
+					skill: "ultragoal",
+					owner: "gjc-runtime",
+					command: "gjc ultragoal sync",
+					sessionId: targetSessionId,
+				},
+				audit: {
+					category: "state",
+					verb: "sync",
+					owner: "gjc-runtime",
+					skill: "ultragoal",
+					fromPhase: typeof existingValue?.current_phase === "string" ? existingValue.current_phase : undefined,
+					toPhase: summary.status,
+				},
+			},
+		);
+	};
+	await syncModeState(undefined);
+	if (sessionId) await syncModeState(sessionId);
+	await syncSkillActiveState({
+		cwd,
+		skill: "ultragoal",
+		active: summary.exists && summary.status !== "complete",
+		phase: summary.status,
+		sessionId: currentSessionId(),
+		hud: buildUltragoalHudSummary(summary, latestLedger),
+		source: "gjc-ultragoal",
+	});
+}
+
+async function syncUltragoalWorkflowStateBestEffort(cwd: string): Promise<void> {
+	try {
+		await syncUltragoalWorkflowState(cwd);
+	} catch {
+		// HUD and mode-state sync are best-effort and must not change command semantics.
+	}
+}
 
 function clampTitle(title: string): string {
 	return title.length > 80 ? `${title.slice(0, 77)}...` : title;
@@ -1311,14 +1404,18 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 	try {
 		const command = commandName(args);
 		const json = hasFlag(args, "--json");
+		let result: UltragoalCommandResult;
 		switch (command) {
 			case "status":
-				return { status: 0, stdout: renderStatus(await getUltragoalStatus(cwd), json) };
+				await syncUltragoalWorkflowStateBestEffort(cwd);
+				result = { status: 0, stdout: renderStatus(await getUltragoalStatus(cwd), json) };
+				break;
 			case "create":
 			case "create-goals": {
 				const mode = flagValue(args, "--gjc-goal-mode") === "per-story" ? "per-story" : "aggregate";
 				const plan = await createUltragoalPlan({ cwd, brief: await readBrief(cwd, args), gjcGoalMode: mode });
-				return {
+				await syncUltragoalWorkflowStateBestEffort(cwd);
+				result = {
 					status: 0,
 					createdPlan: true,
 					stdout: json
@@ -1330,16 +1427,17 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 							})
 						: `Created ultragoal plan with ${plan.goals.length} goal${plan.goals.length === 1 ? "" : "s"} at ${getUltragoalPaths(cwd).goalsPath}.\n`,
 				};
+				break;
 			}
-			case "complete-goals":
-				return {
+			case "complete-goals": {
+				const handoff = await startNextUltragoalGoal({ cwd, retryFailed: hasFlag(args, "--retry-failed") });
+				await syncUltragoalWorkflowStateBestEffort(cwd);
+				result = {
 					status: 0,
-					stdout: renderCompleteHandoff(
-						await startNextUltragoalGoal({ cwd, retryFailed: hasFlag(args, "--retry-failed") }),
-						json,
-						cwd,
-					),
+					stdout: renderCompleteHandoff(handoff, json, cwd),
 				};
+				break;
+			}
 			case "checkpoint": {
 				const goalId = flagValue(args, "--goal-id") ?? "";
 				const status = parseGoalStatus(flagValue(args, "--status"));
@@ -1352,8 +1450,9 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					gjcGoalJson: flagValue(args, "--gjc-goal-json"),
 					qualityGateJson: flagValue(args, "--quality-gate-json"),
 				});
+				await syncUltragoalWorkflowStateBestEffort(cwd);
 				const goal = plan.goals.find(item => item.id === goalId);
-				return {
+				result = {
 					status: 0,
 					stdout: json
 						? renderCliWriteReceipt({
@@ -1366,6 +1465,7 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 							})
 						: `ultragoal checkpoint goal-id=${goalId} status=${status}\n`,
 				};
+				break;
 			}
 			case "steer": {
 				const kind = flagValue(args, "--kind");
@@ -1377,8 +1477,9 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					evidence: flagValue(args, "--evidence") ?? "",
 					rationale: flagValue(args, "--rationale") ?? "",
 				});
+				await syncUltragoalWorkflowStateBestEffort(cwd);
 				const goal = plan.goals.at(-1);
-				return {
+				result = {
 					status: 0,
 					stdout: json
 						? renderCliWriteReceipt({
@@ -1389,6 +1490,7 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 							})
 						: "Accepted add_subgoal steering.\n",
 				};
+				break;
 			}
 			case "record-review-blockers": {
 				const plan = await recordUltragoalReviewBlockers({
@@ -1399,17 +1501,20 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					evidence: flagValue(args, "--evidence") ?? "",
 					gjcGoalJson: flagValue(args, "--gjc-goal-json"),
 				});
+				await syncUltragoalWorkflowStateBestEffort(cwd);
 				const goal = plan.goals.at(-1);
-				return {
+				result = {
 					status: 0,
 					stdout: json
 						? renderCliWriteReceipt({ ok: true, goal_id: goal?.id, goals_path: getUltragoalPaths(cwd).goalsPath })
 						: "Recorded review blockers.\n",
 				};
+				break;
 			}
 			default:
 				return { status: 1, stderr: `Unknown gjc ultragoal command: ${command}\n` };
 		}
+		return result;
 	} catch (error) {
 		return { status: 1, stderr: `${error instanceof Error ? error.message : String(error)}\n` };
 	}