@gajae-code/coding-agent 0.4.4 → 0.4.5

package/src/cli/setup-cli.ts

@@ -48,6 +48,8 @@ export interface SetupCommandArgs {
 		repo?: string;
 		profile?: string;
 		sessionCommand?: string;
+		noWorktree?: boolean;
+		worktreeName?: string;
 		stateRoot?: string;
 		mutation?: string[];
 		artifactByteCap?: string;
@@ -119,6 +121,10 @@ export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
 			flags.profile = args[++i];
 		} else if (arg === "--session-command") {
 			flags.sessionCommand = args[++i];
+		} else if (arg === "--no-worktree") {
+			flags.noWorktree = true;
+		} else if (arg === "--worktree-name") {
+			flags.worktreeName = args[++i];
 		} else if (arg === "--state-root") {
 			flags.stateRoot = args[++i];
 		} else if (arg === "--mutation") {
@@ -493,7 +499,8 @@ ${chalk.bold("Provider example:")}
 ${chalk.bold("Hermes example:")}
   ${APP_NAME} setup hermes --root /path/to/repo
   ${APP_NAME} setup hermes --root /path/to/repo --profile my-bot --repo gajae-code --profile-dir /path/to/hermes/profile --install
-  ${APP_NAME} setup hermes --root /path/to/repo --session-command "gjc --model <provider/model>"
+  ${APP_NAME} setup hermes --root /path/to/repo --worktree-name hermes-gajae-code
+  ${APP_NAME} setup hermes --root /path/to/repo --session-command "gjc --worktree hermes-custom --model <provider/model>"
 
 ${chalk.bold("Options:")}
   -c, --check       Check if dependencies are installed without installing
@@ -511,7 +518,9 @@ ${chalk.bold("Options:")}
   --root            Allowed Hermes MCP workdir/artifact root (repeatable)
   --profile         Hermes MCP profile namespace
   --repo            Hermes MCP repo namespace
-  --session-command Explicit GJC session command; omitted by default
+  --session-command Explicit GJC session command; disables generated worktree flags
+  --no-worktree     Disable default GJC --worktree isolation for Hermes sessions
+  --worktree-name   Named GJC --worktree branch for Hermes sessions
   --mutation        Hermes MCP mutation classes: sessions,questions,reports,all
   --target          Hermes config file target for config-only install
   --profile-dir     Hermes profile directory for full setup install
@@ -522,7 +531,7 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} setup defaults --check Check bundled GJC default workflow skills are installed
   ${APP_NAME} setup hooks            Install native Codex skill-state hooks
   ${APP_NAME} setup hooks --check    Check native Codex skill-state hooks
-  ${APP_NAME} setup hermes           Render a model-agnostic Hermes MCP setup preview
+  ${APP_NAME} setup hermes --root /path/to/repo Render a model-agnostic Hermes MCP setup preview
   ${APP_NAME} setup python           Install Python execution dependencies
   ${APP_NAME} setup stt              Install speech-to-text dependencies
   ${APP_NAME} setup stt --check      Check if STT dependencies are available

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) },
@@ -54,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) {
@@ -62,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.
@@ -109,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

@@ -4,6 +4,7 @@ import {
 	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)}
@@ -24,6 +25,38 @@ function coordinatorContractPayload(): {
 	};
 }
 
+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;
@@ -39,7 +72,7 @@ export default class Coordinator extends Command {
 	async run(): Promise<void> {
 		const { args, flags } = await this.parse(Coordinator);
 		const action = args.action ?? "check";
-		if (action !== "check" && action !== "tools") {
+		if (action !== "check" && action !== "tools" && action !== "doctor") {
 			const payload = { ok: false, reason: "unknown_coordinator_subcommand", subcommand: action };
 			if (flags.json) writeJson(payload);
 			else
@@ -48,6 +81,16 @@ export default class Coordinator extends Command {
 			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);

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

@@ -11,7 +11,7 @@ function writeJson(value: unknown): void {
 }
 
 export function validateMcpServeSubcommandForTest(server: string | undefined): void {
-	if (server !== "coordinator") throw new Error(`unknown_mcp_serve_subcommand:${server ?? ""}`);
+	if (server !== "coordinator" && server !== "hermes") throw new Error(`unknown_mcp_serve_subcommand:${server ?? ""}`);
 }
 
 export default class McpServe extends Command {
@@ -19,7 +19,7 @@ export default class McpServe extends Command {
 	static strict = false;
 
 	static args = {
-		server: Args.string({ description: "MCP server to run (coordinator)", required: false }),
+		server: Args.string({ description: "MCP server to run (coordinator or hermes alias)", required: false }),
 	};
 
 	static flags = {
@@ -39,6 +39,7 @@ export default class McpServe extends Command {
 			} else {
 				process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
 			}
+			process.exitCode = 1;
 			return;
 		}
 

package/src/commands/setup.ts

@@ -28,6 +28,8 @@ export default class Setup extends Command {
 		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",
@@ -68,6 +70,8 @@ export default class Setup extends Command {
 				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"],

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

@@ -9,6 +9,7 @@ export const COORDINATOR_MCP_TOOL_NAMES = [
 	"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",