@gajae-code/coding-agent 0.4.4 → 0.5.0

package/src/cli/fast-help.ts

@@ -0,0 +1,80 @@
+import { APP_NAME, CONFIG_DIR_NAME } from "@gajae-code/utils/dirs";
+
+export function getExtraHelpText(): string {
+	return `Environment Variables:
+  # Core Providers
+  ANTHROPIC_API_KEY          - Anthropic Claude models
+  ANTHROPIC_OAUTH_TOKEN      - Anthropic OAuth (takes precedence over API key)
+  CLAUDE_CODE_USE_FOUNDRY    - Enable Anthropic Foundry mode (uses Foundry endpoint + mTLS)
+  FOUNDRY_BASE_URL           - Anthropic Foundry base URL (e.g., https://<foundry-host>)
+  ANTHROPIC_FOUNDRY_API_KEY  - Anthropic token used as Authorization: Bearer <token> in Foundry mode
+  ANTHROPIC_CUSTOM_HEADERS   - Extra Foundry headers (e.g., "user-id: USERNAME")
+  CLAUDE_CODE_CLIENT_CERT    - Client certificate (PEM path or inline PEM) for mTLS
+  CLAUDE_CODE_CLIENT_KEY     - Client private key (PEM path or inline PEM) for mTLS
+  NODE_EXTRA_CA_CERTS        - CA bundle path (or inline PEM) for server certificate validation
+  OPENAI_API_KEY             - OpenAI GPT models
+  GEMINI_API_KEY             - Google Gemini models
+  GITHUB_TOKEN               - GitHub Copilot (or GH_TOKEN, COPILOT_GITHUB_TOKEN)
+
+  # Additional LLM Providers
+  AZURE_OPENAI_API_KEY       - Azure OpenAI models
+  GROQ_API_KEY               - Groq models
+  CEREBRAS_API_KEY           - Cerebras models
+  XAI_API_KEY                - xAI Grok models
+  OPENROUTER_API_KEY         - OpenRouter aggregated models
+  KILO_API_KEY               - Kilo Gateway models
+  MISTRAL_API_KEY            - Mistral models
+  ZAI_API_KEY                - z.ai models (ZhipuAI/GLM)
+  MINIMAX_API_KEY            - MiniMax models
+  OPENCODE_API_KEY           - OpenCode Zen/OpenCode Go models
+  CURSOR_ACCESS_TOKEN        - Cursor AI models
+  AI_GATEWAY_API_KEY         - Vercel AI Gateway
+
+  # Cloud Providers
+  AWS_PROFILE                - AWS Bedrock (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
+  GOOGLE_CLOUD_PROJECT       - Google Vertex AI (requires GOOGLE_CLOUD_LOCATION)
+  GOOGLE_APPLICATION_CREDENTIALS - Service account for Vertex AI
+
+  # Search & Tools
+  EXA_API_KEY                - Exa web search
+  BRAVE_API_KEY              - Brave web search
+  PERPLEXITY_API_KEY         - Perplexity web search (API)
+  PERPLEXITY_COOKIES         - Perplexity web search (session cookie)
+  TAVILY_API_KEY             - Tavily web search
+  ANTHROPIC_SEARCH_API_KEY   - Anthropic search provider
+
+  # Configuration
+  GJC_CODING_AGENT_DIR       - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  GJC_PACKAGE_DIR            - Override package directory (for Nix/Guix store paths)
+  GJC_SMOL_MODEL              - Override smol/fast model (see --smol)
+  GJC_SLOW_MODEL              - Override slow/reasoning model (see --slow)
+  GJC_PLAN_MODEL              - Override planning model (see --plan)
+  GJC_NO_PTY                  - Disable PTY-based interactive bash execution
+  --tmux                       - Launch interactive startup inside a new tmux session
+  gjc session                  - List, inspect, create, remove, or attach tagged GJC-managed tmux sessions
+  GJC_LAUNCH_POLICY           - Launch policy for --tmux startup: tmux or direct
+  GJC_TMUX_SESSION            - Explicit tmux session name override for --tmux startup
+
+  For complete environment variable reference, see:
+  docs/environment-variables.md
+Available Tools (default-enabled unless noted):
+  read          - Read file contents
+  bash          - Execute bash commands
+  edit          - Edit files with find/replace
+  write         - Write files (creates/overwrites)
+  grep          - Search file contents
+  find          - Find files by glob pattern
+  lsp           - Language server protocol (code intelligence)
+  python        - Execute Python code (requires: ${APP_NAME} setup python)
+  notebook      - Edit Jupyter notebooks
+  inspect_image - Analyze images with a vision model
+  browser       - Browser automation (Puppeteer)
+  task          - Launch sub-agents for parallel tasks
+  todo_write    - Manage todo/task lists
+  web_search    - Search the web
+  ask           - Ask user questions (interactive mode only)
+
+Useful Commands:
+  ${APP_NAME} --list-models        - List configured provider models
+  ${APP_NAME} --help               - Show this help`;
+}

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,33 +1,26 @@
 #!/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, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@gajae-code/utils/dirs";
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 	process.stderr.write(
-		`error: Bun runtime must be >= ${MIN_BUN_VERSION} (found v${Bun.version}). Please upgrade: bun upgrade\n`,
+		formatBunRuntimeError({
+			currentVersion: Bun.version,
+			minVersion: MIN_BUN_VERSION,
+			execPath: process.execPath,
+		}),
 	);
 	process.exit(1);
 }
 
 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 +47,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 +55,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-medium`,
+		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencodego --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 +189,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,17 +10,19 @@
  */
 import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import { resolveGjcTmuxCommand, sanitizeTmuxToken } from "../gjc-runtime/tmux-common";
 import { classifyRecovery } from "../harness-control-plane/classifier";
 import { callEndpoint, EndpointUnreachableError } from "../harness-control-plane/control-endpoint";
 import { type ResolvedOwner, RuntimeOwner, resolveOwner } from "../harness-control-plane/owner";
 import { preserveDirtyWorktree } from "../harness-control-plane/preserve";
+import { RECEIPT_SPOOL_DIR_ENV } from "../harness-control-plane/receipt-spool";
 import { buildReceipt, requiresVanishBeforeAction, type VanishEvidence } from "../harness-control-plane/receipts";
 import { GajaeCodeRpc } from "../harness-control-plane/rpc-adapter";
 import { classifyLeaseStatus, readLease } from "../harness-control-plane/session-lease";
-import { buildResponse, buildStateView } from "../harness-control-plane/state-machine";
+import { buildResponse, buildStateView, submitUnavailableReason } from "../harness-control-plane/state-machine";
 import {
 	canonicalWorkspacePath,
 	generateSessionId,
@@ -247,6 +249,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 +312,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 +333,8 @@ async function buildOwnerExitEvidence(root: string, state: SessionState): Promis
 		terminal,
 		transient,
 		lastRpcActivityAt,
+		startupBlocker,
+		recoveryGuidance: ownerExitGuidance(reason, startupBlocker),
 	};
 }
 
@@ -404,6 +438,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,10 +510,14 @@ 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 }),
 		json: Flags.boolean({ char: "j", description: "Emit machine-readable JSON", default: true }),
+		"receipt-spool-dir": Flags.string({
+			description: "Append persisted ReceiptEnvelope records to spool.jsonl under this directory",
+		}),
 	};
 
 	static examples = [
@@ -471,7 +532,20 @@ export default class Harness extends Command {
 		const verb = String(args.verb);
 		let root = resolveHarnessRoot();
 		try {
+			const receiptSpoolDir = flags["receipt-spool-dir"];
+			if (receiptSpoolDir !== undefined) {
+				if (!receiptSpoolDir.trim()) throw new Error("receipt_spool_dir_empty");
+				process.env[RECEIPT_SPOOL_DIR_ENV] = path.resolve(receiptSpoolDir.trim());
+			}
 			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) {
@@ -612,6 +686,9 @@ export default class Harness extends Command {
 		}
 		const sessionName = deterministicHarnessTmuxSessionName(sessionId);
 		const envAssignments = [`GJC_HARNESS_STATE_ROOT=${shellQuote(root)}`];
+		if (process.env[RECEIPT_SPOOL_DIR_ENV]) {
+			envAssignments.push(`${RECEIPT_SPOOL_DIR_ENV}=${shellQuote(process.env[RECEIPT_SPOOL_DIR_ENV])}`);
+		}
 		if (process.env.GJC_HARNESS_RPC_COMMAND) {
 			envAssignments.push(`GJC_HARNESS_RPC_COMMAND=${shellQuote(process.env.GJC_HARNESS_RPC_COMMAND)}`);
 		}
@@ -651,6 +728,9 @@ export default class Harness extends Command {
 			env: {
 				...process.env,
 				GJC_HARNESS_STATE_ROOT: root,
+				...(process.env[RECEIPT_SPOOL_DIR_ENV]
+					? { [RECEIPT_SPOOL_DIR_ENV]: process.env[RECEIPT_SPOOL_DIR_ENV] }
+					: {}),
 				...(process.env.GJC_HARNESS_TEST_NODE_MODULES
 					? { GJC_HARNESS_TEST_NODE_MODULES: process.env.GJC_HARNESS_TEST_NODE_MODULES }
 					: {}),
@@ -814,7 +894,9 @@ export default class Harness extends Command {
 	): Promise<boolean> {
 		const owner = await resolveOwner(root, sessionId);
 		if (!owner.live || !owner.socketPath) return false;
+		const priorSpoolDir = input[RECEIPT_SPOOL_DIR_ENV];
 		try {
+			if (process.env[RECEIPT_SPOOL_DIR_ENV]) input[RECEIPT_SPOOL_DIR_ENV] = process.env[RECEIPT_SPOOL_DIR_ENV];
 			const res = (await callEndpoint(owner.socketPath, { verb, input })) as { ok?: boolean };
 			writeJson(res);
 			if (res?.ok === false) process.exitCode = 1;
@@ -822,6 +904,9 @@ export default class Harness extends Command {
 		} catch (error) {
 			if (error instanceof EndpointUnreachableError) return false;
 			throw error;
+		} finally {
+			if (priorSpoolDir === undefined) delete input[RECEIPT_SPOOL_DIR_ENV];
+			else input[RECEIPT_SPOOL_DIR_ENV] = priorSpoolDir;
 		}
 	}
 
@@ -834,10 +919,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 +935,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 } : {}),
 			}),
 		);
 	}
@@ -909,10 +999,36 @@ 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);
+		const noOwnerGate = submitUnavailableReason(state.lifecycle, false);
+		if (!noOwnerGate || noOwnerGate === "owner-not-live") {
+			if (await this.#tryOwnerRoute(root, sessionId, "submit", { ...input, sessionId })) return;
+			state = await loadState(root, sessionId);
+		}
+		const blockedByOwnerLiveness = state.blockers.some(
+			blocker => isOwnerLivenessBlocker(blocker) || blocker === OWNER_STARTUP_BLOCKER,
+		);
+		const lifecycleGate = submitUnavailableReason(state.lifecycle, false);
+		if (lifecycleGate && lifecycleGate !== "owner-not-live" && !blockedByOwnerLiveness) {
+			writeJson(buildResponse(state, false, { accepted: false, submitted: false, reason: lifecycleGate }, false));
+			process.exitCode = 1;
+			return;
+		}
+		// 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 +1146,7 @@ export default class Harness extends Command {
 					decision,
 					observation: { ...observation, lifecycle: state.lifecycle },
 					ownerExit: afterExit,
+					guidance: afterExit.recoveryGuidance,
 					...(restoredOwner
 						? {
 								restoreAttempt: {

package/src/commands/launch.ts

@@ -142,8 +142,8 @@ export default class Index extends Command {
 		`# 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`,
+		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-medium`,
+		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencodego --default`,
 		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.gjc/agent/sessions/--path--/session.jsonl`,
 	];
 

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;
 		}