@gajae-code/coding-agent 0.4.4 → 0.4.5

package/src/main.ts

@@ -33,7 +33,7 @@ import { getDefault, type SettingPath, Settings, settings } from "./config/setti
 import { initializeWithSettings } from "./discovery";
 import { exportFromFile } from "./export/html";
 import type { ExtensionUIContext } from "./extensibility/extensions/types";
-import { InteractiveMode, runAcpMode, runBridgeMode, runPrintMode, runRpcMode } from "./modes";
+import type { InteractiveMode } from "./modes/interactive-mode";
 import { initTheme, stopThemeWatcher } from "./modes/theme/theme";
 import type { SubmittedUserInput } from "./modes/types";
 import type { MCPManager } from "./runtime-mcp";
@@ -304,6 +304,7 @@ async function runInteractiveMode(
 	initialMessage?: string,
 	initialImages?: ImageContent[],
 ): Promise<void> {
+	const { InteractiveMode } = await import("./modes/interactive-mode");
 	const mode = new InteractiveMode(
 		session,
 		version,
@@ -706,7 +707,7 @@ async function buildSessionOptions(
 interface RunRootCommandDependencies {
 	createAgentSession?: typeof createAgentSession;
 	discoverAuthStorage?: typeof discoverAuthStorage;
-	runAcpMode?: typeof runAcpMode;
+	runAcpMode?: (createSession: AcpSessionFactory) => Promise<void>;
 	settings?: Settings;
 }
 
@@ -927,7 +928,7 @@ export async function runRootCommand(
 			rawArgs,
 			createSession,
 		});
-		await (deps.runAcpMode ?? runAcpMode)(createAcpSession);
+		await (deps.runAcpMode ?? (await import("./modes/acp")).runAcpMode)(createAcpSession);
 	} else {
 		const { session, setToolUIContext, modelFallbackMessage, lspServers, mcpManager, eventBus } =
 			await createSession(sessionOptions);
@@ -973,8 +974,10 @@ export async function runRootCommand(
 		}
 
 		if (mode === "rpc" || mode === "rpc-ui") {
+			const { runRpcMode } = await import("./modes/rpc/rpc-mode");
 			await runRpcMode(session, mode === "rpc-ui" ? setToolUIContext : undefined);
 		} else if (mode === "bridge") {
+			const { runBridgeMode } = await import("./modes/bridge/bridge-mode");
 			await runBridgeMode(session, setToolUIContext);
 		} else if (isInteractive) {
 			const versionCheckPromise = checkForNewVersion(VERSION).catch(() => undefined);
@@ -1014,6 +1017,7 @@ export async function runRootCommand(
 				initialImages,
 			);
 		} else {
+			const { runPrintMode } = await import("./modes/print-mode");
 			await runPrintMode(session, {
 				mode,
 				messages: parsedArgs.messages,

package/src/modes/components/status-line.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import type { AgentMessage } from "@gajae-code/agent-core";
-import { estimateTokens } from "@gajae-code/agent-core/compaction";
+import { estimateMessageTokensHeuristic } from "@gajae-code/agent-core/compaction";
 import { type Component, truncateToWidth, visibleWidth } from "@gajae-code/tui";
 import { formatCount, getProjectDir } from "@gajae-code/utils";
 import { $ } from "bun";
@@ -50,7 +50,7 @@ export interface StatusLineSettings {
 
 /**
  * Symbol-keyed sidecar tagged onto each `AgentMessage` to memoize its
- * `estimateTokens` result. Keyed by message identity (the object itself);
+ * `estimateMessageTokensHeuristic` result. Keyed by message identity (the object itself);
  * a cheap content fingerprint detects in-place mutations (post-hoc error
  * attachment, retry-truncated branch rebuild, etc.) and forces recompute.
  *
@@ -64,11 +64,11 @@ interface TaggedMessage {
 }
 
 /**
- * Cheap structural fingerprint mirroring `estimateTokens`'s content walk.
+ * Cheap structural fingerprint mirroring `estimateMessageTokensHeuristic`'s content walk.
  * O(blocks) — only reads string `.length` and primitives, never copies or
  * serializes content. Any in-place mutation that alters total tokenized
  * content also alters one of the byte-length sums or block counts captured
- * here, forcing the cached `estimateTokens` value to be recomputed.
+ * here, forcing the cached heuristic token value to be recomputed.
  */
 function messageFingerprint(msg: AgentMessage): string {
 	const role = (msg as { role?: string }).role ?? "";
@@ -136,7 +136,7 @@ function tokensForMessage(msg: AgentMessage): number {
 	const tagged = msg as TaggedMessage;
 	const cached = tagged[kTokenCache];
 	if (cached && cached.fingerprint === fp) return cached.tokens;
-	const tokens = estimateTokens(msg);
+	const tokens = estimateMessageTokensHeuristic(msg);
 	tagged[kTokenCache] = { fingerprint: fp, tokens };
 	return tokens;
 }
@@ -560,7 +560,7 @@ export class StatusLineComponent implements Component {
 		let messagesTokens = 0;
 		const lastIdx = messages.length - 1;
 		for (let i = 0; i < messages.length; i++) {
-			messagesTokens += i === lastIdx ? estimateTokens(messages[i]) : tokensForMessage(messages[i]);
+			messagesTokens += i === lastIdx ? estimateMessageTokensHeuristic(messages[i]) : tokensForMessage(messages[i]);
 		}
 
 		const usedTokens = this.#nonMessageTokensCache + messagesTokens;

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

@@ -20,6 +20,7 @@ import type { AgentSessionEvent } from "../../session/agent-session";
 import { isSilentAbort, readPendingDisplayTag } from "../../session/messages";
 import type { ResolveToolDetails } from "../../tools/resolve";
 import { interruptHint } from "../shared";
+import { buildAbortDisplayMessage } from "../utils/abort-message";
 
 type AgentSessionEventKind = AgentSessionEvent["type"];
 
@@ -419,10 +420,10 @@ export class EventController {
 				// controller ran, so reaching this branch implies the abort was NOT a
 				// silent internal transition.
 				const retryAttempt = this.ctx.session.retryAttempt;
-				errorMessage =
-					retryAttempt > 0
-						? `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`
-						: "Operation aborted";
+				errorMessage = buildAbortDisplayMessage({
+					errorMessage: this.ctx.streamingMessage.errorMessage,
+					retryAttempt,
+				});
 				this.ctx.streamingMessage.errorMessage = errorMessage;
 			}
 			if (silentlyAborted || ttsrSilenced) {

package/src/modes/interactive-mode.ts

@@ -1057,7 +1057,7 @@ export class InteractiveMode implements InteractiveModeContext {
 				return;
 			}
 			if (event.state?.enabled === true && !this.#goalModePreviousTools) {
-				this.#goalModePreviousTools = this.session.getActiveToolNames().filter(name => name !== "goal");
+				this.#goalModePreviousTools = this.session.getActiveToolNames();
 			}
 			this.goalModeEnabled = event.state?.enabled === true;
 			this.goalModePaused = event.state?.enabled !== true && event.state?.goal?.status === "paused";
@@ -1146,10 +1146,9 @@ export class InteractiveMode implements InteractiveModeContext {
 			const restored = await this.session.goalRuntime.onThreadResumed();
 			this.goalModeEnabled = restored?.enabled === true;
 			this.goalModePaused = restored?.enabled !== true && restored?.goal.status === "paused";
-			// sdk.ts excludes "goal" from the initial active tool set unconditionally.
-			// Re-add it now so the agent can call resume, complete, or drop on this goal.
+			// Keep `goal` armed on resumed threads; it is part of the default active tool set.
 			if (restored?.goal) {
-				const previousTools = this.session.getActiveToolNames().filter(name => name !== "goal");
+				const previousTools = this.session.getActiveToolNames();
 				this.#goalModePreviousTools = previousTools;
 				await this.session.setActiveToolsByName([...new Set([...previousTools, "goal"])]);
 			}
@@ -1318,7 +1317,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.showWarning("Exit plan mode first.");
 			return;
 		}
-		const previousTools = this.session.getActiveToolNames().filter(name => name !== "goal");
+		const previousTools = this.session.getActiveToolNames();
 		const goalTools = [...new Set([...previousTools, "goal"])];
 		this.#goalModePreviousTools = previousTools;
 		this.goalModePaused = false;

package/src/modes/print-mode.ts

@@ -72,7 +72,7 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 	// In text mode, output final response
 	if (mode === "text") {
 		const state = session.state;
-		const lastMessage = state.messages[state.messages.length - 1];
+		const lastMessage = state.messages.findLast(message => message.role === "assistant");
 
 		if (lastMessage?.role === "assistant") {
 			const assistantMsg = lastMessage as AssistantMessage;

package/src/modes/theme/theme.ts

@@ -264,7 +264,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.context": "◫",
 	"icon.cost": "💲",
 	"icon.time": "⏱",
-	"icon.pi": "π",
+	"icon.pi": "🦞",
 	"icon.agents": "👥",
 	"icon.cache": "💾",
 	"icon.input": "⤵",
@@ -686,7 +686,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.context": "ctx:",
 	"icon.cost": "$",
 	"icon.time": "t:",
-	"icon.pi": "pi",
+	"icon.pi": "GJC",
 	"icon.agents": "AG",
 	"icon.cache": "cache",
 	"icon.input": "in:",

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

@@ -0,0 +1,41 @@
+const STREAM_IDLE_TIMEOUT_PATTERN = /\bstream stalled while waiting for the next event\b/i;
+const GENERIC_ABORT_PATTERN = /^Request was aborted\.?$/i;
+const ABORT_DISPLAY_LABEL_PATTERN = /^(?:Operation aborted|Aborted after \d+ retry attempts?)(?::|$)/;
+
+export function buildAbortDisplayMessage({
+	errorMessage,
+	retryAttempt,
+}: {
+	errorMessage?: string;
+	retryAttempt: number;
+}): string {
+	const existingDisplayMessage = normalizeExistingAbortDisplayMessage(errorMessage);
+	if (existingDisplayMessage) return existingDisplayMessage;
+
+	const baseMessage =
+		retryAttempt > 0
+			? `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`
+			: "Operation aborted";
+	const cause = normalizeAbortCause(errorMessage);
+	if (!cause) return baseMessage;
+
+	return `${baseMessage}: ${cause}${streamIdleTimeoutHint(cause)}`;
+}
+
+function normalizeExistingAbortDisplayMessage(errorMessage: string | undefined): string {
+	const trimmed = errorMessage?.trim();
+	if (!trimmed || !ABORT_DISPLAY_LABEL_PATTERN.test(trimmed)) return "";
+	return trimmed;
+}
+
+function normalizeAbortCause(errorMessage: string | undefined): string {
+	const trimmed = errorMessage?.trim();
+	if (!trimmed || GENERIC_ABORT_PATTERN.test(trimmed)) return "";
+	return trimmed;
+}
+
+function streamIdleTimeoutHint(cause: string): string {
+	if (!STREAM_IDLE_TIMEOUT_PATTERN.test(cause)) return "";
+	const separator = /[.!?]$/.test(cause) ? " " : ". ";
+	return `${separator}Hint: set PI_STREAM_IDLE_TIMEOUT_MS=300000 for slow reasoning/proxy streams, or PI_STREAM_IDLE_TIMEOUT_MS=0 to disable the watchdog.`;
+}

package/src/modes/utils/context-usage.ts

@@ -1,8 +1,12 @@
 import type { AgentMessage } from "@gajae-code/agent-core";
 import type { CompactionSettings } from "@gajae-code/agent-core/compaction";
-import { effectiveReserveTokens, estimateTokens, resolveThresholdTokens } from "@gajae-code/agent-core/compaction";
+import {
+	effectiveReserveTokens,
+	estimateMessageTokensHeuristic,
+	estimateTextTokensHeuristic,
+	resolveThresholdTokens,
+} from "@gajae-code/agent-core/compaction";
 import type { Model } from "@gajae-code/ai";
-import { countTokens } from "@gajae-code/natives";
 import { formatNumber } from "@gajae-code/utils";
 import type { Skill } from "../../extensibility/skills";
 import type { AgentSession } from "../../session/agent-session";
@@ -46,7 +50,7 @@ export function estimateSkillsTokens(skills: readonly Skill[]): number {
 		// concatenated form, so encode each piece separately and sum.
 		fragments.push(skill.name, skill.description);
 	}
-	return countTokens(fragments);
+	return estimateTextTokensHeuristic(fragments);
 }
 
 export function estimateToolSchemaTokens(
@@ -61,7 +65,7 @@ export function estimateToolSchemaTokens(
 			// Schema may contain functions or cycles; ignore.
 		}
 	}
-	return countTokens(fragments);
+	return estimateTextTokensHeuristic(fragments);
 }
 
 /**
@@ -100,8 +104,11 @@ function computeNonMessageBreakdown(session: AgentSession): {
 	const toolsTokens = estimateToolSchemaTokens(session.agent?.state?.tools ?? []);
 	const systemPromptParts = session.systemPrompt ?? [];
 	const rulesTokens = estimateRulesTokens(systemPromptParts);
-	const systemContextTokens = countTokens(systemPromptParts.slice(1));
-	const systemPromptTokens = Math.max(0, countTokens(systemPromptParts[0] ?? "") - skillsTokens - rulesTokens);
+	const systemContextTokens = estimateTextTokensHeuristic(systemPromptParts.slice(1));
+	const systemPromptTokens = Math.max(
+		0,
+		estimateTextTokensHeuristic(systemPromptParts[0] ?? "") - skillsTokens - rulesTokens,
+	);
 	return { rulesTokens, skillsTokens, toolsTokens, systemContextTokens, systemPromptTokens };
 }
 
@@ -112,7 +119,7 @@ function estimateRulesTokens(systemPromptParts: readonly string[]): number {
 			fragments.push(match[0]);
 		}
 	}
-	return fragments.length === 0 ? 0 : countTokens(fragments);
+	return fragments.length === 0 ? 0 : estimateTextTokensHeuristic(fragments);
 }
 
 function splitLastUserTurn(messages: readonly AgentMessage[]): {
@@ -130,7 +137,7 @@ function splitLastUserTurn(messages: readonly AgentMessage[]): {
 	let regularMessagesTokens = 0;
 	let lastUserTurnTokens = 0;
 	for (let i = 0; i < messages.length; i++) {
-		const tokens = estimateTokens(messages[i]);
+		const tokens = estimateMessageTokensHeuristic(messages[i]);
 		if (i === lastUserIndex) {
 			lastUserTurnTokens = tokens;
 		} else {

package/src/modes/utils/ui-helpers.ts

@@ -27,6 +27,7 @@ import {
 } from "../../session/messages";
 import type { SessionContext } from "../../session/session-manager";
 import { formatBytes, formatDuration } from "../../tools/render-utils";
+import { buildAbortDisplayMessage } from "./abort-message";
 
 type TextBlock = { type: "text"; text: string };
 interface RenderInitialMessagesOptions {
@@ -319,12 +320,10 @@ export class UiHelpers {
 					!isAbortedSilently && (message.stopReason === "aborted" || message.stopReason === "error");
 				const errorMessage = hasErrorStop
 					? message.stopReason === "aborted"
-						? (() => {
-								const retryAttempt = this.ctx.session.retryAttempt;
-								return retryAttempt > 0
-									? `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`
-									: "Operation aborted";
-							})()
+						? buildAbortDisplayMessage({
+								errorMessage: message.errorMessage,
+								retryAttempt: this.ctx.session.retryAttempt,
+							})
 						: message.errorMessage || "Error"
 					: null;
 

package/src/sdk.ts

@@ -1622,9 +1622,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		};
 
 		const toolNamesFromRegistry = Array.from(toolRegistry.keys());
-		const requestedToolNames =
-			(options.toolNames ? [...new Set(options.toolNames.map(name => name.toLowerCase()))] : undefined) ??
-			toolNamesFromRegistry;
+		const requestedToolNames = options.toolNames
+			? [
+					...new Set([
+						...options.toolNames.map(name => name.toLowerCase()),
+						...(settings.get("goal.enabled") ? ["goal"] : []),
+					]),
+				]
+			: toolNamesFromRegistry;
 		const normalizedRequested = requestedToolNames.filter(name => toolRegistry.has(name));
 		const requestedToolNameSet = new Set(normalizedRequested);
 		// Effective discovery mode only covers built-in tools; MCP tool discovery
@@ -1635,7 +1640,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const defaultInactiveToolNames = new Set(
 			registeredTools.filter(tool => tool.definition.defaultInactive).map(tool => tool.definition.name),
 		);
-		const requestedActiveToolNames = normalizedRequested.filter(name => name !== "goal");
+		const requestedActiveToolNames = normalizedRequested;
 		const initialRequestedActiveToolNames = options.toolNames
 			? requestedActiveToolNames
 			: requestedActiveToolNames.filter(name => !defaultInactiveToolNames.has(name));

package/src/session/agent-session.ts

@@ -41,6 +41,7 @@ import {
 	calculatePromptTokens,
 	collectEntriesForBranchSummary,
 	compact,
+	estimateMessageTokensHeuristic,
 	estimateTokens,
 	generateBranchSummary,
 	generateHandoff,
@@ -4388,7 +4389,7 @@ export class AgentSession {
 			return false;
 		}
 
-		const previousTools = this.getActiveToolNames().filter(name => name !== "goal");
+		const previousTools = this.getActiveToolNames();
 		const goalTools = [...new Set([...previousTools, "goal"])];
 		await this.#goalRuntime.createGoal({ objective: pendingGoal.objective });
 		await this.setActiveToolsByName(goalTools);
@@ -6063,6 +6064,9 @@ export class AgentSession {
 			return undefined;
 		}
 
+		// getBranch() returns materialized copies for blob-externalized entries, so
+		// the pruning mutations must be written back into the canonical store.
+		this.sessionManager.applyEntryMessageUpdates(result.prunedEntries);
 		await this.sessionManager.rewriteEntries();
 		const sessionContext = this.buildDisplaySessionContext();
 		this.agent.replaceMessages(sessionContext.messages);
@@ -6507,12 +6511,18 @@ export class AgentSession {
 		// Case 2: Threshold - turn succeeded but context is getting large
 		// Skip if this was an error (non-overflow errors don't have usage data)
 		if (assistantMessage.stopReason === "error") return;
-		const pruneResult = await this.#pruneToolOutputs();
 		let contextTokens = calculateContextTokens(assistantMessage.usage);
+		const maxOutputTokens = this.model?.maxTokens ?? 0;
+		// Cache-epoch invariant: pruning rewrites already-sent toolResult history,
+		// which breaks the provider prompt-cache prefix mid-epoch. Only prune at a
+		// sanctioned maintenance boundary, i.e. when the un-pruned context already
+		// crosses the compaction threshold. Pruning may then avert full compaction.
+		if (!shouldCompact(contextTokens, contextWindow, compactionSettings, maxOutputTokens)) return;
+		const pruneResult = await this.#pruneToolOutputs();
 		if (pruneResult) {
 			contextTokens = Math.max(0, contextTokens - pruneResult.tokensSaved);
 		}
-		if (shouldCompact(contextTokens, contextWindow, compactionSettings, this.model?.maxTokens ?? 0)) {
+		if (shouldCompact(contextTokens, contextWindow, compactionSettings, maxOutputTokens)) {
 			// Try promotion first — if a larger model is available, switch instead of compacting
 			const promoted = await this.#tryContextPromotion(assistantMessage);
 			if (!promoted) {
@@ -8338,6 +8348,7 @@ export class AgentSession {
 				onChunk,
 				signal: abortController.signal,
 				sessionKey: this.sessionId,
+				cwd,
 				timeout: clampTimeout("bash") * 1000,
 				env: buildGjcRuntimeSessionEnv({
 					sessionFile: this.sessionManager.getSessionFile(),
@@ -9527,7 +9538,7 @@ export class AgentSession {
 			// No usage data - estimate all messages
 			let estimated = 0;
 			for (const message of messages) {
-				estimated += estimateTokens(message);
+				estimated += estimateMessageTokensHeuristic(message);
 			}
 			return {
 				tokens: estimated,
@@ -9537,7 +9548,7 @@ export class AgentSession {
 		const usageTokens = calculatePromptTokens(lastUsage);
 		let trailingTokens = 0;
 		for (let i = lastUsageIndex + 1; i < messages.length; i++) {
-			trailingTokens += estimateTokens(messages[i]);
+			trailingTokens += estimateMessageTokensHeuristic(messages[i]);
 		}
 
 		return {

package/src/session/session-manager.ts

@@ -3125,6 +3125,26 @@ export class SessionManager {
 		return entry.id;
 	}
 
+	/**
+	 * Write mutated message entries back into the canonical entry store by id.
+	 *
+	 * `getBranch()` materializes resident-blob entries into copies, so in-place
+	 * mutation of returned entries (e.g. pruning tool outputs) does not affect
+	 * the canonical store. This applies such mutations for real.
+	 */
+	applyEntryMessageUpdates(entries: readonly SessionMessageEntry[]): void {
+		for (const updated of entries) {
+			const canonical = this.#byId.get(updated.id);
+			if (canonical?.type !== "message") continue;
+			const residentEntry = prepareEntryForResidentSync(
+				{ ...canonical, message: updated.message },
+				this.#residentBlobStore,
+			) as SessionMessageEntry;
+			canonical.message = residentEntry.message;
+		}
+		this.#needsFullRewriteOnNextPersist = true;
+	}
+
 	/**
 	 * Rewrite the session file after in-place entry updates.
 	 * Use sparingly (e.g., pruning old tool outputs).

package/src/setup/hermes/templates/operator-instructions.v1.md

@@ -10,15 +10,16 @@ These instructions teach a Hermes-style coordinator how to operate GJC through t
 2. Send exactly one bounded task prompt with `{{TOOL_PREFIX}}_send_prompt`.
 3. Store the returned `turn_id`.
 4. Poll `{{TOOL_PREFIX}}_read_turn` or `{{TOOL_PREFIX}}_await_turn` for that `turn_id` until the turn is terminal.
+   If a second task is needed while one turn is active, pass `queue: true`; the next queued turn is promoted after the active turn is reported terminal.
 5. If GJC asks a structured question, use `{{TOOL_PREFIX}}_list_questions` and answer with `{{TOOL_PREFIX}}_submit_question_answer`.
 6. Use `{{TOOL_PREFIX}}_report_status` for coordinator-visible status and final reports.
 7. Use `{{TOOL_PREFIX}}_read_tail` only as advisory debug output when structured turn state is insufficient.
 
 Do not report completion to the user until the GJC turn is terminal. Do not infer completion from terminal scrollback alone.
 
-## Model and provider policy
+## Worktree, model, and provider policy
 
-The Hermes bridge does not choose a model/provider. When no session command is configured, GJC uses its normal local model/provider resolution. If the operator config supplies `GJC_COORDINATOR_MCP_SESSION_COMMAND`, preserve it as explicit user intent.
+The Hermes bridge does not choose a model/provider. Generated setup configures `GJC_COORDINATOR_MCP_SESSION_COMMAND` to `gjc --worktree` by default, so GJC creates and tracks the worktree while still using normal local model/provider resolution. Keep worktree creation inside GJC rather than creating unmanaged Hermes-side git worktrees; this preserves the original project identity for session listing and resume. If the operator config supplies a different `GJC_COORDINATOR_MCP_SESSION_COMMAND`, preserve it as explicit user intent.
 
 Provider-specific commands are examples only, never product defaults.
 

package/src/setup/hermes-setup.ts

@@ -24,6 +24,8 @@ export interface HermesSetupFlags {
 	repo?: string;
 	profile?: string;
 	sessionCommand?: string;
+	noWorktree?: boolean;
+	worktreeName?: string;
 	stateRoot?: string;
 	mutation?: string[];
 	artifactByteCap?: string;
@@ -47,6 +49,11 @@ export interface CoordinatorSetupSpec {
 		repo?: string;
 	};
 	sessionCommand?: string;
+	sessionCommandSource: "default" | "explicit";
+	worktree: {
+		enabled: boolean;
+		name?: string;
+	};
 	stateRoot?: string;
 	mutationPolicy: {
 		classes: HermesMutationClass[];
@@ -157,6 +164,39 @@ function parseByteCap(value: string | undefined): number | undefined {
 	return parsed;
 }
 
+function normalizeWorktreeName(value: string | undefined): string | undefined {
+	const trimmed = optionalTrim(value);
+	if (!trimmed) return undefined;
+	if (trimmed.startsWith("-") || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,127}$/.test(trimmed)) {
+		throw new HermesSetupError(`Invalid Hermes worktree name: ${trimmed}`, 2);
+	}
+	return trimmed;
+}
+
+function resolveHermesWorktree(flags: HermesSetupFlags): CoordinatorSetupSpec["worktree"] {
+	if (flags.noWorktree && flags.worktreeName) {
+		throw new HermesSetupError("Use either --no-worktree or --worktree-name, not both.", 2);
+	}
+	const name = normalizeWorktreeName(flags.worktreeName);
+	return flags.noWorktree ? { enabled: false } : { enabled: true, ...(name ? { name } : {}) };
+}
+
+function resolveHermesSessionCommand(gjcCommand: string, flags: HermesSetupFlags): string {
+	const explicit = optionalTrim(flags.sessionCommand);
+	if (explicit) {
+		if (flags.noWorktree || flags.worktreeName) {
+			throw new HermesSetupError(
+				"Use either --session-command or Hermes worktree flags; explicit session commands are preserved exactly.",
+				2,
+			);
+		}
+		return explicit;
+	}
+	const worktree = resolveHermesWorktree(flags);
+	if (!worktree.enabled) return gjcCommand;
+	return worktree.name ? `${gjcCommand} --worktree ${worktree.name}` : `${gjcCommand} --worktree`;
+}
+
 function normalizeInstallTarget(flags: HermesSetupFlags): CoordinatorSetupSpec["installTarget"] {
 	if (flags.target && flags.profileDir) {
 		throw new HermesSetupError("Use exactly one of --target or --profile-dir for Hermes setup install targets.", 2);
@@ -169,20 +209,24 @@ function normalizeInstallTarget(flags: HermesSetupFlags): CoordinatorSetupSpec["
 
 export function buildHermesSetupSpec(flags: HermesSetupFlags): CoordinatorSetupSpec {
 	const roots = normalizeRoots(flags.root);
+	const gjcCommand = optionalTrim(flags.gjcCommand) ?? DEFAULT_GJC_COMMAND;
+	const sessionCommand = resolveHermesSessionCommand(gjcCommand, flags);
 	return {
 		schemaVersion: 1,
 		coordinator: "hermes",
 		serverKey: optionalTrim(flags.serverKey) ?? DEFAULT_SERVER_KEY,
 		serverName: COORDINATOR_MCP_SERVER_NAME,
 		protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION,
-		gjcCommand: optionalTrim(flags.gjcCommand) ?? DEFAULT_GJC_COMMAND,
+		gjcCommand,
 		args: ["mcp-serve", "coordinator"],
 		roots,
 		namespace: {
 			...(optionalTrim(flags.profile) ? { profile: optionalTrim(flags.profile) } : {}),
 			...(optionalTrim(flags.repo) ? { repo: optionalTrim(flags.repo) } : {}),
 		},
-		...(optionalTrim(flags.sessionCommand) ? { sessionCommand: flags.sessionCommand } : {}),
+		worktree: resolveHermesWorktree(flags),
+		sessionCommandSource: optionalTrim(flags.sessionCommand) ? "explicit" : "default",
+		sessionCommand,
 		...(optionalTrim(flags.stateRoot) ? { stateRoot: path.resolve(flags.stateRoot!) } : {}),
 		mutationPolicy: {
 			classes: parseMutationClasses(flags.mutation),
@@ -214,6 +258,8 @@ function signaturePayload(spec: CoordinatorSetupSpec): Record<string, unknown> {
 		contractDocVersion: spec.contractDocVersion,
 		coordinator: spec.coordinator,
 		mutationClasses: spec.mutationPolicy.classes,
+		worktree: spec.worktree,
+		sessionCommandSource: spec.sessionCommandSource,
 		namespace: spec.namespace,
 		operatorTemplateVersion: spec.operatorTemplateVersion,
 		roots: spec.roots,
@@ -360,7 +406,9 @@ async function runSmoke(spec: CoordinatorSetupSpec): Promise<HermesSetupResult["
 	const requiredTools = [...COORDINATOR_MCP_TOOL_NAMES];
 	const server = createCoordinatorMcpServer({ env: {} });
 	const listed = await server.handleJsonRpc({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} });
-	const advertised = new Set((listed.result?.tools ?? []).map((tool: { name: string }) => tool.name));
+	const listedResult = isRecord(listed.result) ? listed.result : {};
+	const tools = Array.isArray(listedResult.tools) ? listedResult.tools : [];
+	const advertised = new Set(tools.map(tool => (isRecord(tool) ? String(tool.name) : "")));
 	const missingTools = requiredTools.filter(tool => !advertised.has(tool));
 	return {
 		ok: missingTools.length === 0,
@@ -398,11 +446,18 @@ export async function runHermesSetup(flags: HermesSetupFlags): Promise<HermesSet
 		mode,
 		files_written,
 		previews,
-		warnings: spec.sessionCommand
-			? [
-					"Using explicit GJC_COORDINATOR_MCP_SESSION_COMMAND exactly as supplied; provider/model validation is not performed.",
-				]
-			: ["No session command supplied; spawned sessions use the default GJC command/model resolution."],
+		warnings:
+			spec.sessionCommandSource === "explicit"
+				? [
+						"Using explicit GJC_COORDINATOR_MCP_SESSION_COMMAND exactly as supplied; provider/model/worktree validation is not performed.",
+					]
+				: spec.worktree.enabled
+					? [
+							`GJC_COORDINATOR_MCP_SESSION_COMMAND defaults to '${spec.sessionCommand}' so GJC owns worktree creation and resume identity.`,
+						]
+					: [
+							"GJC_COORDINATOR_MCP_SESSION_COMMAND defaults to the configured gjc command with worktree isolation disabled by user request.",
+						],
 		smoke,
 	};
 }