@gajae-code/coding-agent 0.4.3 → 0.4.5

package/src/cli.ts

@@ -1,24 +1,11 @@
 #!/usr/bin/env bun
-import { installH2Fetch } from "@gajae-code/ai";
-import { APP_NAME, MIN_BUN_VERSION, procmgr, VERSION } from "@gajae-code/utils";
-
-// Activate HTTP/2 for all `fetch()` calls (provider streams, OAuth, model
-// discovery, web tools). Bun's HTTP/2 client is gated on a startup flag we
-// can't toggle from JS, so we patch globalThis.fetch to pass
-// `protocol: "http2"` per request, with transparent HTTP/1.1 fallback on
-// `HTTP2Unsupported`. See @gajae-code/ai/utils/h2-fetch for details.
-installH2Fetch();
-
-// Strip macOS malloc-stack-logging env vars before any subprocess is spawned.
-// Otherwise every child bun process (subagents, plugin installs, ptree spawns,
-// etc.) prints a `MallocStackLogging: can't turn off …` warning to stderr.
-procmgr.scrubProcessEnv();
 
 /**
  * CLI entry point — registers all commands explicitly and delegates to the
  * lightweight CLI runner from pi-utils.
  */
-import { type CliConfig, type CommandEntry, run } from "@gajae-code/utils/cli";
+import { Args, type CliConfig, Command, type CommandEntry, Flags, run } from "@gajae-code/utils/cli";
+import { APP_NAME, MIN_BUN_VERSION, VERSION } from "@gajae-code/utils/dirs";
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 	process.stderr.write(
@@ -28,6 +15,8 @@ if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 }
 
 process.title = APP_NAME;
+const rootHelpFlags = ["--help", "-h", "help"];
+const versionFlags = ["--version", "-v"];
 
 const commands: CommandEntry[] = [
 	{ name: "codex-native-hook", load: () => import("./commands/codex-native-hook").then(m => m.default) },
@@ -36,10 +25,12 @@ const commands: CommandEntry[] = [
 	{ name: "skills", load: () => import("./commands/skills").then(m => m.default) },
 	{ name: "session", load: () => import("./commands/session").then(m => m.default) },
 	{ name: "harness", load: () => import("./commands/harness").then(m => m.default) },
+	{ name: "coordinator", load: () => import("./commands/coordinator").then(m => m.default) },
 	{ name: "team", load: () => import("./commands/team").then(m => m.default) },
 	{ name: "ultragoal", load: () => import("./commands/ultragoal").then(m => m.default) },
 	{ name: "ralplan", load: () => import("./commands/ralplan").then(m => m.default) },
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
+	{ name: "mcp-serve", load: () => import("./commands/mcp-serve").then(m => m.default) },
 	{
 		name: "contribute-pr",
 		aliases: ["contribution-prep"],
@@ -52,7 +43,7 @@ const commands: CommandEntry[] = [
 
 async function showHelp(config: CliConfig): Promise<void> {
 	const { renderRootHelp } = await import("@gajae-code/utils/cli");
-	const { getExtraHelpText } = await import("./cli/args");
+	const { getExtraHelpText } = await import("./cli/fast-help");
 	renderRootHelp(config);
 	const extra = getExtraHelpText();
 	if (extra.trim().length > 0) {
@@ -60,6 +51,93 @@ async function showHelp(config: CliConfig): Promise<void> {
 	}
 }
 
+async function installRuntimeGlobals(): Promise<void> {
+	const [{ installH2Fetch }, { procmgr }] = await Promise.all([import("@gajae-code/ai"), import("@gajae-code/utils")]);
+	// Activate HTTP/2 for all `fetch()` calls (provider streams, OAuth, model
+	// discovery, web tools). Bun's HTTP/2 client is gated on a startup flag we
+	// can't toggle from JS, so we patch globalThis.fetch to pass
+	// `protocol: "http2"` per request, with transparent HTTP/1.1 fallback on
+	// `HTTP2Unsupported`. See @gajae-code/ai/utils/h2-fetch for details.
+	installH2Fetch();
+
+	// Strip macOS malloc-stack-logging env vars before any subprocess is spawned.
+	// Otherwise every child bun process (subagents, plugin installs, ptree spawns,
+	// etc.) prints a `MallocStackLogging: can't turn off …` warning to stderr.
+	procmgr.scrubProcessEnv();
+}
+
+class RootHelpCommand extends Command {
+	static description = "Red-claw AI coding assistant";
+	static hidden = true;
+	static args = {
+		messages: Args.string({
+			description: "Messages to send (prefix files with @)",
+			required: false,
+			multiple: true,
+		}),
+	};
+	static flags = {
+		model: Flags.string({ description: 'Model to use (fuzzy match: "opus", "gpt-5.2", or "openai/gpt-5.2")' }),
+		smol: Flags.string({ description: "Smol/fast model for lightweight tasks (or GJC_SMOL_MODEL env)" }),
+		slow: Flags.string({ description: "Slow/reasoning model for thorough analysis (or GJC_SLOW_MODEL env)" }),
+		plan: Flags.string({ description: "Plan model for architectural planning (or GJC_PLAN_MODEL env)" }),
+		mpreset: Flags.string({ description: "Model profile preset to activate for this session" }),
+		default: Flags.boolean({ description: "Persist --mpreset as the default model profile" }),
+		provider: Flags.string({ description: "Provider to use (legacy; prefer --model)" }),
+		"api-key": Flags.string({ description: "API key (defaults to env vars)" }),
+		"system-prompt": Flags.string({ description: "System prompt (default: coding assistant prompt)" }),
+		"append-system-prompt": Flags.string({ description: "Append text or file contents to the system prompt" }),
+		"allow-home": Flags.boolean({ description: "Allow starting in ~ without auto-switching to a temp dir" }),
+		mode: Flags.string({
+			description: "Output mode: text (default), json, rpc, acp, rpc-ui, or bridge",
+			options: ["text", "json", "rpc", "acp", "rpc-ui", "bridge"],
+		}),
+		print: Flags.boolean({ char: "p", description: "Non-interactive mode: process prompt and exit" }),
+		continue: Flags.boolean({ char: "c", description: "Continue previous session" }),
+		resume: Flags.string({ char: "r", description: "Resume a session (by ID prefix, path, or picker if omitted)" }),
+		"session-dir": Flags.string({ description: "Directory for session storage and lookup" }),
+		"no-session": Flags.boolean({ description: "Don't save session (ephemeral)" }),
+		models: Flags.string({ description: "Comma-separated model patterns for Ctrl+P cycling" }),
+		"no-tools": Flags.boolean({ description: "Disable all built-in tools" }),
+		"no-lsp": Flags.boolean({ description: "Disable LSP tools, formatting, and diagnostics" }),
+		"no-pty": Flags.boolean({ description: "Disable PTY-based interactive bash execution" }),
+		tmux: Flags.boolean({ description: "Launch interactive startup inside tmux" }),
+		tools: Flags.string({ description: "Comma-separated list of tools to enable (default: all)" }),
+		thinking: Flags.string({
+			description: "Set thinking level: ultra, high, medium, low",
+			options: ["ultra", "high", "medium", "low"],
+		}),
+		hook: Flags.string({ description: "Load a hook/extension file (can be used multiple times)", multiple: true }),
+		extension: Flags.string({
+			char: "e",
+			description: "Load an extension file (can be used multiple times)",
+			multiple: true,
+		}),
+		"no-extensions": Flags.boolean({ description: "Disable extension discovery (explicit -e paths still work)" }),
+		"no-skills": Flags.boolean({ description: "Disable skills discovery and loading" }),
+		skills: Flags.string({ description: "Comma-separated glob patterns to filter skills (e.g., git-*,docker)" }),
+		"no-rules": Flags.boolean({ description: "Disable rules discovery and loading" }),
+		export: Flags.string({ description: "Export session file to HTML and exit" }),
+		"list-models": Flags.string({ description: "List available models (with optional fuzzy search)" }),
+		"no-title": Flags.boolean({ description: "Disable title auto-generation" }),
+	};
+	static examples = [
+		`# Interactive mode\n  ${APP_NAME}`,
+		`# Interactive mode with initial prompt\n  ${APP_NAME} "List all .ts files in src/"`,
+		`# Include files in initial message\n  ${APP_NAME} @prompt.md @image.png "What color is the sky?"`,
+		`# Non-interactive mode (process and exit)\n  ${APP_NAME} -p "List all .ts files in src/"`,
+		`# Continue previous session\n  ${APP_NAME} --continue "What did we discuss?"`,
+		`# Launch in a sibling git worktree\n  ${APP_NAME} --worktree`,
+		`# Use different model (fuzzy matching)\n  ${APP_NAME} --model opus "Help me refactor this code"`,
+		`# Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o`,
+		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-standard`,
+		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencode-go-pro --default`,
+		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.gjc/agent/sessions/--path--/session.jsonl`,
+	];
+	static strict = false;
+	async run(): Promise<void> {}
+}
+
 /**
  * Determine whether argv[0] is a known subcommand name.
  * If not, the entire argv is treated as args to the default "launch" command.
@@ -107,6 +185,21 @@ export async function runCli(argv: string[]): Promise<void> {
 		await runSmokeTest();
 		return;
 	}
+	if (rootHelpFlags.includes(argv[0] ?? "")) {
+		const { renderRootHelp } = await import("@gajae-code/utils/cli");
+		const { getExtraHelpText } = await import("./cli/fast-help");
+		renderRootHelp({ bin: APP_NAME, version: VERSION, commands: new Map([["launch", RootHelpCommand]]) });
+		const extra = getExtraHelpText();
+		if (extra.trim().length > 0) {
+			process.stdout.write(`\n${extra}\n`);
+		}
+		return;
+	}
+	if (versionFlags.includes(argv[0] ?? "")) {
+		process.stdout.write(`${APP_NAME}/${VERSION}\n`);
+		return;
+	}
+	await installRuntimeGlobals();
 	// --help and --version are handled by run() directly, don't rewrite those.
 	// Everything else that isn't a known subcommand routes to "launch".
 	const first = argv[0];

package/src/commands/coordinator.ts

@@ -0,0 +1,113 @@
+import { Args, Command, Flags } from "@gajae-code/utils/cli";
+import {
+	COORDINATOR_MCP_PROTOCOL_VERSION,
+	COORDINATOR_MCP_SERVER_NAME,
+	COORDINATOR_MCP_TOOL_NAMES,
+} from "../coordinator/contract";
+import { buildCoordinatorMcpConfig } from "../coordinator-mcp/policy";
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+
+function coordinatorContractPayload(): {
+	ok: true;
+	server: { name: string; protocolVersion: string };
+	readOnly: true;
+	tools: string[];
+} {
+	return {
+		ok: true,
+		server: { name: COORDINATOR_MCP_SERVER_NAME, protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION },
+		readOnly: true,
+		tools: [...COORDINATOR_MCP_TOOL_NAMES],
+	};
+}
+
+function coordinatorDoctorPayload(): {
+	ok: boolean;
+	checks: Array<{ id: string; status: "pass" | "warn" | "fail"; detail: string }>;
+} {
+	const config = buildCoordinatorMcpConfig(process.env);
+	const checks: Array<{ id: string; status: "pass" | "warn" | "fail"; detail: string }> = [];
+	checks.push({
+		id: "workdir_roots",
+		status: config.allowedRoots.length > 0 ? "pass" : "fail",
+		detail:
+			config.allowedRoots.length > 0 ? config.allowedRoots.join(":") : "GJC_COORDINATOR_MCP_WORKDIR_ROOTS is empty",
+	});
+	checks.push({
+		id: "session_mutations",
+		status: config.mutationClasses.has("sessions") ? "pass" : "fail",
+		detail: config.mutationClasses.has("sessions") ? "sessions mutation enabled" : "sessions mutation disabled",
+	});
+	checks.push({
+		id: "session_command",
+		status: config.sessionCommand ? "pass" : "warn",
+		detail:
+			config.sessionCommand ??
+			"GJC_COORDINATOR_MCP_SESSION_COMMAND is unset; registration can still reuse visible sessions",
+	});
+	checks.push({
+		id: "namespace",
+		status: config.namespace.profile && config.namespace.repo ? "pass" : "warn",
+		detail: `profile=${config.namespace.profile ?? "<unset>"} repo=${config.namespace.repo ?? "<unset>"}`,
+	});
+	return { ok: checks.every(check => check.status !== "fail"), checks };
+}
+
+export default class Coordinator extends Command {
+	static description = "Inspect GJC coordinator MCP bridge contracts";
+	static strict = false;
+
+	static args = {
+		action: Args.string({ description: "Action to run (check or tools)", required: false }),
+	};
+
+	static flags = {
+		json: Flags.boolean({ char: "j", description: "Emit machine-readable JSON", default: false }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Coordinator);
+		const action = args.action ?? "check";
+		if (action !== "check" && action !== "tools" && action !== "doctor") {
+			const payload = { ok: false, reason: "unknown_coordinator_subcommand", subcommand: action };
+			if (flags.json) writeJson(payload);
+			else
+				process.stderr.write(`unknown_coordinator_subcommand:${action}
+`);
+			process.exit(1);
+		}
+
+		if (action === "doctor") {
+			const doctor = coordinatorDoctorPayload();
+			if (flags.json) {
+				writeJson(doctor);
+				return;
+			}
+			process.stdout.write(`ok: ${doctor.ok}\n`);
+			for (const check of doctor.checks) process.stdout.write(`${check.status}\t${check.id}\t${check.detail}\n`);
+			return;
+		}
+		const payload = coordinatorContractPayload();
+		if (flags.json) {
+			writeJson(action === "tools" ? { ok: true, tools: payload.tools } : payload);
+			return;
+		}
+		if (action === "tools") {
+			for (const tool of payload.tools)
+				process.stdout.write(`${tool}
+`);
+			return;
+		}
+		process.stdout.write(
+			`server: ${payload.server.name}
+protocol: ${payload.server.protocolVersion}
+readOnly: true
+tools: ${payload.tools.length}
+`,
+		);
+	}
+}

package/src/commands/harness.ts

@@ -10,7 +10,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import { resolveGjcTmuxCommand, sanitizeTmuxToken } from "../gjc-runtime/tmux-common";
 import { classifyRecovery } from "../harness-control-plane/classifier";
@@ -247,6 +247,30 @@ interface OwnerExitEvidence {
 	transient: boolean;
 	/** ISO timestamp of the most recent non-terminal RPC-derived owner event, if any (observability only). */
 	lastRpcActivityAt: string | null;
+	/**
+	 * True when the owner started (reported live) but died before accepting the first prompt.
+	 * This is a startup blocker, not a healthy live gate: callers must recover before submit.
+	 */
+	startupBlocker: boolean;
+	/** Explicit, human-actionable recovery guidance for the surfaced exit reason. */
+	recoveryGuidance: string;
+}
+
+function ownerExitGuidance(reason: string, startupBlocker: boolean): string {
+	if (startupBlocker) {
+		return "owner started and reported live but exited before accepting the first prompt; run `gjc harness recover --session <id>` to respawn the owner, then resubmit the prompt";
+	}
+	switch (reason) {
+		case "owner-exited-after-prompt-acceptance":
+			return "owner exited after accepting a prompt; run `gjc harness recover --session <id>` to preserve in-flight work and classify the vanish before resubmitting";
+		case "owner-lease-expired":
+		case "owner-endpoint-unreachable":
+			return "owner lease is stale or its endpoint did not route; run `gjc harness recover --session <id>` to respawn or take over the owner";
+		case "owner-liveness-unknown-permission-denied":
+			return "owner liveness cannot be probed (permission denied); verify the owner process out-of-band before recover";
+		default:
+			return "no live owner holds this session; run `gjc harness recover --session <id>` to (re)spawn an owner, then resubmit";
+	}
 }
 
 async function buildOwnerExitEvidence(root: string, state: SessionState): Promise<OwnerExitEvidence> {
@@ -286,6 +310,12 @@ async function buildOwnerExitEvidence(root: string, state: SessionState): Promis
 	} else {
 		reason = "owner-endpoint-unreachable";
 	}
+	// A just-started owner that emitted `owner_started` (so it reported live) but is now terminal
+	// without ever accepting a prompt died during startup. Surface this as an explicit, actionable
+	// startup blocker rather than letting `submit` fall through to a misleading `owner-not-live` gate.
+	const ownerStarted = events.some(event => event.kind === "owner_started");
+	const startupBlocker = terminal && ownerStarted && !promptAcceptedSeen && !completedSeen;
+	if (startupBlocker) reason = "owner-died-before-first-prompt";
 	return {
 		reason,
 		leaseStatus,
@@ -301,6 +331,8 @@ async function buildOwnerExitEvidence(root: string, state: SessionState): Promis
 		terminal,
 		transient,
 		lastRpcActivityAt,
+		startupBlocker,
+		recoveryGuidance: ownerExitGuidance(reason, startupBlocker),
 	};
 }
 
@@ -404,6 +436,29 @@ async function markVanishedOwnerBlocked(
 	return state;
 }
 
+const OWNER_STARTUP_BLOCKER = "owner-died-before-first-prompt";
+
+/**
+ * Persist an explicit startup blocker when an owner started, reported live, but died before
+ * accepting the first prompt. This makes the failure an actionable lifecycle state instead of a
+ * silent `owner-not-live` gate, so observe/recover surface it and recover can respawn the owner.
+ */
+async function markStartupOwnerBlocked(
+	root: string,
+	state: SessionState,
+	ownerExit: OwnerExitEvidence,
+): Promise<SessionState> {
+	if (!ownerExit.startupBlocker) return state;
+	if (state.lifecycle === "completed" || state.lifecycle === "retired") return state;
+	state.lifecycle = "blocked";
+	state.blockers = state.blockers.includes(OWNER_STARTUP_BLOCKER)
+		? state.blockers
+		: [...state.blockers, OWNER_STARTUP_BLOCKER];
+	state.updatedAt = nowIso();
+	await writeSessionState(root, state);
+	return state;
+}
+
 function resolveRetryBudget(input: Record<string, unknown>): RetryBudget {
 	const supplied = input.retryBudget;
 	if (supplied && typeof supplied === "object" && !Array.isArray(supplied)) {
@@ -453,6 +508,7 @@ export default class Harness extends Command {
 
 	static flags = {
 		input: Flags.string({ description: "JSON object input for the verb", default: "" }),
+		"prompt-file": Flags.string({ description: "Read submit prompt text from a file (submit verb only)" }),
 		session: Flags.string({ char: "s", description: "Session id (re-grab a session)" }),
 		cursor: Flags.string({ description: "Event cursor for events --follow (exclusive)", default: "0" }),
 		follow: Flags.boolean({ description: "Tail the owner-written event log", default: false }),
@@ -472,6 +528,14 @@ export default class Harness extends Command {
 		let root = resolveHarnessRoot();
 		try {
 			const input = parseInput(flags.input);
+			const promptFile = flags["prompt-file"];
+			if (promptFile !== undefined) {
+				if (verb !== "submit") throw new Error("prompt_file_only_supported_for_submit");
+				if (typeof input.prompt === "string" && input.prompt.length > 0) {
+					throw new Error("prompt_file_conflicts_with_input_prompt");
+				}
+				input.prompt = readFileSync(promptFile, "utf8");
+			}
 			const sessionId = flags.session ?? (typeof input.sessionId === "string" ? input.sessionId : undefined);
 			const expectedWorkspace = typeof input.workspace === "string" ? resolveInputWorkspace(input) : undefined;
 			if (verb !== "start" && sessionId) {
@@ -834,10 +898,12 @@ export default class Harness extends Command {
 		state = await reconcileCompletedOwnerExited(root, state, observation, completedTerminalEvent);
 		const vanishedOwnerBlock = needsVanishedOwnerBlock(state, observation, completedTerminalEvent);
 		state = await markVanishedOwnerBlocked(root, state, observation, completedTerminalEvent);
-		const ownerExit =
-			!ownerLive && (vanishedOwnerBlock || completedTerminalEvent)
-				? await buildOwnerExitEvidence(root, state)
-				: null;
+		// Build owner-exit evidence whenever the owner is gone so a startup death (owner started,
+		// reported live, then died before the first prompt) is detectable, not just vanish/completion.
+		const ownerExit = !ownerLive ? await buildOwnerExitEvidence(root, state) : null;
+		const startupBlocked = ownerExit?.startupBlocker ?? false;
+		if (ownerExit && startupBlocked) state = await markStartupOwnerBlocked(root, state, ownerExit);
+		const includeOwnerExit = Boolean(ownerExit && (vanishedOwnerBlock || completedTerminalEvent || startupBlocked));
 		writeJson(
 			buildResponse(state, ownerLive, {
 				observation: { ...observation, lifecycle: state.lifecycle },
@@ -848,7 +914,10 @@ export default class Harness extends Command {
 				...(completedTerminalEvent && !ownerLive
 					? { completedOwnerExited: true, terminalResult: completedTerminalEvent }
 					: {}),
-				...(ownerExit ? { ownerExit } : {}),
+				...(startupBlocked
+					? { startupBlocked: true, blockerReason: OWNER_STARTUP_BLOCKER, guidance: ownerExit?.recoveryGuidance }
+					: {}),
+				...(includeOwnerExit && ownerExit ? { ownerExit } : {}),
 			}),
 		);
 	}
@@ -910,9 +979,22 @@ export default class Harness extends Command {
 	async #submit(root: string, input: Record<string, unknown>, flagSession: string | undefined): Promise<void> {
 		const sessionId = requireSessionId(input, flagSession);
 		if (await this.#tryOwnerRoute(root, sessionId, "submit", { ...input, sessionId })) return;
-		const state = await loadState(root, sessionId);
-		// No live owner: submission is blocked (never echoed-as-accepted).
-		writeJson(buildResponse(state, false, { accepted: false, submitted: false, reason: "owner-not-live" }, false));
+		let state = await loadState(root, sessionId);
+		// No live owner: submission is blocked (never echoed-as-accepted). Surface owner exit
+		// evidence + explicit recovery guidance so the caller is not left with a bare gate.
+		const ownerExit = await buildOwnerExitEvidence(root, state);
+		// An owner that started, reported live, then died before accepting the first prompt is a
+		// startup blocker, not a healthy `owner-not-live` gate — persist it and report it as such.
+		if (ownerExit.startupBlocker) state = await markStartupOwnerBlocked(root, state, ownerExit);
+		const reason = ownerExit.startupBlocker ? ownerExit.reason : "owner-not-live";
+		writeJson(
+			buildResponse(
+				state,
+				false,
+				{ accepted: false, submitted: false, reason, ownerExit, guidance: ownerExit.recoveryGuidance },
+				false,
+			),
+		);
 		process.exitCode = 1;
 	}
 
@@ -1030,6 +1112,7 @@ export default class Harness extends Command {
 					decision,
 					observation: { ...observation, lifecycle: state.lifecycle },
 					ownerExit: afterExit,
+					guidance: afterExit.recoveryGuidance,
 					...(restoredOwner
 						? {
 								restoreAttempt: {

package/src/commands/mcp-serve.ts

@@ -0,0 +1,63 @@
+import { Args, Command, Flags } from "@gajae-code/utils/cli";
+import {
+	COORDINATOR_MCP_PROTOCOL_VERSION,
+	COORDINATOR_MCP_SERVER_NAME,
+	COORDINATOR_MCP_TOOL_NAMES,
+} from "../coordinator/contract";
+import { runCoordinatorMcpStdio } from "../coordinator-mcp/server";
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function validateMcpServeSubcommandForTest(server: string | undefined): void {
+	if (server !== "coordinator" && server !== "hermes") throw new Error(`unknown_mcp_serve_subcommand:${server ?? ""}`);
+}
+
+export default class McpServe extends Command {
+	static description = "Serve GJC MCP compatibility bridges";
+	static strict = false;
+
+	static args = {
+		server: Args.string({ description: "MCP server to run (coordinator or hermes alias)", required: false }),
+	};
+
+	static flags = {
+		json: Flags.boolean({ char: "j", description: "Emit machine-readable JSON", default: false }),
+		check: Flags.boolean({ description: "Validate server configuration and print a smoke summary", default: false }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(McpServe);
+		const server = args.server ?? "";
+		try {
+			validateMcpServeSubcommandForTest(server);
+		} catch (error) {
+			const subcommand = server;
+			if (flags.json) {
+				writeJson({ ok: false, reason: "unknown_mcp_serve_subcommand", subcommand });
+			} else {
+				process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+			}
+			process.exitCode = 1;
+			return;
+		}
+
+		if (flags.check) {
+			const payload = {
+				ok: true,
+				server: { name: COORDINATOR_MCP_SERVER_NAME, protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION },
+				readOnly: true,
+				tools: [...COORDINATOR_MCP_TOOL_NAMES],
+			};
+			if (flags.json) writeJson(payload);
+			else
+				process.stdout.write(
+					`server: ${payload.server.name}\nprotocol: ${payload.server.protocolVersion}\ntools: ${payload.tools.length}\n`,
+				);
+			return;
+		}
+
+		await runCoordinatorMcpStdio();
+	}
+}

package/src/commands/setup.ts

@@ -5,7 +5,7 @@ import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import { runSetupCommand, type SetupCommandArgs, type SetupComponent } from "../cli/setup-cli";
 import { initTheme } from "../modes/theme/theme";
 
-const COMPONENTS: SetupComponent[] = ["defaults", "hooks", "provider", "python", "stt"];
+const COMPONENTS: SetupComponent[] = ["defaults", "hermes", "hooks", "provider", "python", "stt"];
 
 export default class Setup extends Command {
 	static description = "Install GJC defaults or optional feature dependencies";
@@ -22,6 +22,24 @@ export default class Setup extends Command {
 		check: Flags.boolean({ char: "c", description: "Check if dependencies are installed" }),
 		force: Flags.boolean({ char: "f", description: "Overwrite existing default workflow skill files" }),
 		json: Flags.boolean({ description: "Output status as JSON" }),
+		smoke: Flags.boolean({ description: "Run Hermes MCP setup smoke checks" }),
+		install: Flags.boolean({ description: "Install generated Hermes setup files" }),
+		root: Flags.string({ description: "Allowed Hermes MCP workdir/artifact root (repeatable)", multiple: true }),
+		repo: Flags.string({ description: "Hermes MCP repo namespace" }),
+		profile: Flags.string({ description: "Hermes MCP profile namespace" }),
+		"session-command": Flags.string({ description: "Explicit GJC session command for Hermes to launch" }),
+		"no-worktree": Flags.boolean({ description: "Disable default GJC --worktree isolation for Hermes sessions" }),
+		"worktree-name": Flags.string({ description: "Named GJC --worktree branch for Hermes sessions" }),
+		"state-root": Flags.string({ description: "Hermes MCP coordination state root" }),
+		mutation: Flags.string({
+			description: "Hermes MCP mutation classes: sessions,questions,reports,all",
+			multiple: true,
+		}),
+		"artifact-byte-cap": Flags.string({ description: "Hermes MCP artifact read byte cap" }),
+		"server-key": Flags.string({ description: "Hermes MCP server key in coordinator config" }),
+		"gjc-command": Flags.string({ description: "Command used to start `gjc mcp-serve coordinator`" }),
+		target: Flags.string({ description: "Hermes config file target for config-only install" }),
+		"profile-dir": Flags.string({ description: "Hermes profile directory for full setup install" }),
 		preset: Flags.string({ description: "Provider preset: minimax, minimax-cn, or glm" }),
 		compat: Flags.string({ description: "Provider compatibility: openai or anthropic" }),
 		provider: Flags.string({ description: "Provider id to add to models.yml" }),
@@ -46,6 +64,21 @@ export default class Setup extends Command {
 				apiKeyEnv: flags["api-key-env"],
 				model: flags.model,
 				modelsPath: flags["models-path"],
+				smoke: flags.smoke,
+				install: flags.install,
+				root: flags.root,
+				repo: flags.repo,
+				profile: flags.profile,
+				sessionCommand: flags["session-command"],
+				noWorktree: flags["no-worktree"],
+				worktreeName: flags["worktree-name"],
+				stateRoot: flags["state-root"],
+				mutation: flags.mutation,
+				artifactByteCap: flags["artifact-byte-cap"],
+				serverKey: flags["server-key"],
+				gjcCommand: flags["gjc-command"],
+				target: flags.target,
+				profileDir: flags["profile-dir"],
 			},
 		};
 		await initTheme();

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

@@ -36,6 +36,7 @@ export const OpenAICompatSchema = z.object({
 	allowsSyntheticReasoningContentForToolCalls: z.boolean().optional(),
 	requiresAssistantContentForToolCalls: z.boolean().optional(),
 	supportsToolChoice: z.boolean().optional(),
+	supportsForcedToolChoice: z.boolean().optional(),
 	disableReasoningOnForcedToolChoice: z.boolean().optional(),
 	disableReasoningOnToolChoice: z.boolean().optional(),
 	thinkingFormat: z.enum(["openai", "openrouter", "zai", "qwen", "qwen-chat-template"]).optional(),

package/src/coordinator/contract.ts

@@ -0,0 +1,21 @@
+export const COORDINATOR_MCP_PROTOCOL_VERSION = "2024-11-05";
+export const COORDINATOR_MCP_SERVER_NAME = "gjc-coordinator-mcp";
+
+export const COORDINATOR_MCP_TOOL_NAMES = [
+	"gjc_coordinator_list_sessions",
+	"gjc_coordinator_read_status",
+	"gjc_coordinator_read_tail",
+	"gjc_coordinator_list_questions",
+	"gjc_coordinator_list_artifacts",
+	"gjc_coordinator_read_artifact",
+	"gjc_coordinator_read_coordination_status",
+	"gjc_coordinator_register_session",
+	"gjc_coordinator_start_session",
+	"gjc_coordinator_send_prompt",
+	"gjc_coordinator_submit_question_answer",
+	"gjc_coordinator_read_turn",
+	"gjc_coordinator_await_turn",
+	"gjc_coordinator_report_status",
+] as const;
+
+export type CoordinatorToolName = (typeof COORDINATOR_MCP_TOOL_NAMES)[number];