@gajae-code/coding-agent 0.7.7 → 0.7.8

package/src/coordinator-mcp/server.ts

@@ -119,7 +119,7 @@ interface TurnRecord {
 		target: string | null;
 		tmux_keys_sent?: boolean;
 		prompt_acknowledged?: boolean;
-		state?: "queued" | "tmux_keys_sent" | "acknowledged" | "unavailable";
+		state?: "queued" | "tmux_keys_sent" | "acknowledged" | "unavailable" | "unacknowledged";
 		attempts: Array<{
 			delivered: boolean;
 			created_at: string;
@@ -214,6 +214,9 @@ interface CoordinatorEventInput {
 }
 
 const MISSING_FINAL_RESPONSE_ADVISORY = "completion_missing_final_response";
+const PROMPT_ACK_TIMEOUT_REASON = "runtime_prompt_ack_timeout";
+const DEFAULT_RUNTIME_PROMPT_ACK_TIMEOUT_MS = 10_000;
+const MAX_RUNTIME_PROMPT_ACK_TIMEOUT_MS = 5 * 60 * 1000;
 const ACTIVE_TURN_STATUSES = new Set<TurnStatus>(["delivering", "active", "waiting_for_answer", "completing"]);
 const TERMINAL_TURN_STATUSES = new Set<TurnStatus>(["completed", "failed", "cancelled", "superseded"]);
 const TURN_ID_PATTERN = /^turn-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -317,8 +320,14 @@ function toolSchema(name: CoordinatorToolName): {
 				properties: {
 					session_id: sessionId,
 					turn_id: { type: "string" },
-					timeout_ms: { type: "number" },
-					poll_interval_ms: { type: "number" },
+					timeout_ms: {
+						type: "number",
+						description: "Bounded await timeout in milliseconds, capped at 30 minutes.",
+					},
+					poll_interval_ms: {
+						type: "number",
+						description: "Bounded polling interval in milliseconds, capped at 10 seconds.",
+					},
 					lines: { type: "number" },
 				},
 				required: ["turn_id"],
@@ -406,7 +415,10 @@ function toolSchema(name: CoordinatorToolName): {
 					after_seq: { type: "number" },
 					session_id: sessionId,
 					event_types: { type: "array", items: { type: "string" } },
-					timeout_ms: { type: "number" },
+					timeout_ms: {
+						type: "number",
+						description: "Bounded event long-poll timeout in milliseconds, capped at 30 seconds.",
+					},
 					limit: { type: "number" },
 				},
 			},
@@ -447,7 +459,8 @@ function toolSchema(name: CoordinatorToolName): {
 					await_completion: { type: "boolean", description: "If true, poll the turn until terminal or timeout." },
 					timeout_ms: {
 						type: "number",
-						description: "Bounded await timeout; same cap semantics as gjc_coordinator_await_turn.",
+						description:
+							"Bounded await timeout in milliseconds, capped at 30 minutes like gjc_coordinator_await_turn.",
 					},
 					poll_interval_ms: { type: "number", description: "Bounded await polling interval." },
 					lines: { type: "number", description: "Bounded advisory tail lines returned with await/read payloads." },
@@ -1039,6 +1052,135 @@ async function markTurnTerminalFromSessionState(
 	return resolved;
 }
 
+function runtimeStateAcknowledgesTurn(turn: TurnRecord, sessionState: CoordinatorSessionState | null): boolean {
+	return (
+		sessionState?.source === "agent_session_event" &&
+		sessionState.current_turn_id === turn.turn_id &&
+		(sessionState.state === "running" ||
+			sessionState.state === "needs_user_input" ||
+			sessionState.state === "completed" ||
+			sessionState.state === "errored")
+	);
+}
+
+async function markTurnAcknowledgedFromRuntimeState(
+	namespaceDir: string,
+	turn: TurnRecord,
+	sessionState: CoordinatorSessionState,
+): Promise<TurnRecord> {
+	if (turn.delivery.prompt_acknowledged === true && turn.delivery.state === "acknowledged") return turn;
+	const timestamp = new Date().toISOString();
+	const acknowledged: TurnRecord = {
+		...turn,
+		delivery: {
+			...turn.delivery,
+			delivered: true,
+			prompt_acknowledged: true,
+			state: "acknowledged",
+			attempts: [
+				...turn.delivery.attempts,
+				{
+					delivered: true,
+					created_at: sessionState.updated_at,
+					reason: "runtime_prompt_acknowledged",
+					channel: "runtime_ack",
+					tmux_keys_sent: turn.delivery.tmux_keys_sent,
+				},
+			],
+		},
+		updated_at: timestamp,
+	};
+	await writeTurnRecord(namespaceDir, acknowledged);
+	await writeActiveTurn(namespaceDir, acknowledged);
+	return acknowledged;
+}
+
+function turnAwaitingRuntimeAckExpired(turn: TurnRecord, nowMs: number, ackTimeoutMs: number): boolean {
+	if (!ACTIVE_TURN_STATUSES.has(turn.status)) return false;
+	if (turn.delivery.tmux_keys_sent !== true) return false;
+	if (turn.delivery.prompt_acknowledged === true) return false;
+	if (turn.delivery.state !== "tmux_keys_sent") return false;
+	const deliveredAt =
+		turn.delivery.attempts.findLast(attempt => attempt.channel === "tmux_keys")?.created_at ?? turn.updated_at;
+	const deliveredMs = Date.parse(deliveredAt);
+	return Number.isFinite(deliveredMs) && nowMs - deliveredMs >= ackTimeoutMs;
+}
+
+async function markTurnFailedForUnacknowledgedDelivery(
+	namespaceDir: string,
+	turn: TurnRecord,
+	ackTimeoutMs: number,
+): Promise<TurnRecord> {
+	const timestamp = new Date().toISOString();
+	const message = `Tmux key delivery succeeded, but the GJC runtime did not acknowledge the prompt or emit turn_start within ${ackTimeoutMs}ms. The turn never started; stop waiting and inspect/retry the coordinator session.`;
+	const failed: TurnRecord = {
+		...turn,
+		status: "failed",
+		delivery: {
+			...turn.delivery,
+			delivered: false,
+			queued: false,
+			prompt_acknowledged: false,
+			state: "unacknowledged",
+			attempts: [
+				...turn.delivery.attempts,
+				{
+					delivered: false,
+					created_at: timestamp,
+					reason: PROMPT_ACK_TIMEOUT_REASON,
+					channel: "runtime_ack",
+					tmux_keys_sent: true,
+				},
+			],
+		},
+		final_response: {
+			text: message,
+			format: "markdown",
+			source: "coordinator_delivery_ack_timeout",
+			artifact_path: null,
+			truncated: false,
+		},
+		error: { code: PROMPT_ACK_TIMEOUT_REASON, message, recoverable: true },
+		evidence: [
+			...turn.evidence,
+			{
+				type: PROMPT_ACK_TIMEOUT_REASON,
+				message,
+				tmux_keys_sent: true,
+				prompt_acknowledged: false,
+				created_at: timestamp,
+			},
+		],
+		liveness: { checked_at: timestamp, live: turn.liveness.live, reason: PROMPT_ACK_TIMEOUT_REASON },
+		updated_at: timestamp,
+		completed_at: timestamp,
+	};
+	await writeTurnRecord(namespaceDir, failed);
+	await clearActiveTurn(namespaceDir, failed);
+	await writeSessionState(namespaceDir, failed.session_id, "stale", {
+		lastTurnId: failed.turn_id,
+		live: failed.liveness.live,
+		reason: PROMPT_ACK_TIMEOUT_REASON,
+	});
+	return failed;
+}
+
+async function reconcileRuntimeAcknowledgement(
+	namespaceDir: string,
+	turn: TurnRecord,
+	sessionState: CoordinatorSessionState | null,
+	ackTimeoutMs: number,
+	options: { failOnTimeout: boolean } = { failOnTimeout: true },
+): Promise<TurnRecord> {
+	if (sessionState && runtimeStateAcknowledgesTurn(turn, sessionState)) {
+		return await markTurnAcknowledgedFromRuntimeState(namespaceDir, turn, sessionState);
+	}
+	if (options.failOnTimeout && turnAwaitingRuntimeAckExpired(turn, Date.now(), ackTimeoutMs)) {
+		return await markTurnFailedForUnacknowledgedDelivery(namespaceDir, turn, ackTimeoutMs);
+	}
+	return turn;
+}
+
 function shellQuote(value: string): string {
 	return `'${value.replaceAll("'", "'\\''")}'`;
 }
@@ -1086,16 +1228,33 @@ function asTerminalTurnStatus(status: unknown): TurnStatus | null {
 	return null;
 }
 
-function boundedTimeoutMs(value: unknown): number {
+export const COORDINATOR_AWAIT_TURN_TIMEOUT_MAX_MS = 30 * 60 * 1000;
+export const COORDINATOR_RUNTIME_PROMPT_ACK_TIMEOUT_MAX_MS = MAX_RUNTIME_PROMPT_ACK_TIMEOUT_MS;
+export const COORDINATOR_EVENT_WATCH_TIMEOUT_MAX_MS = 30_000;
+export const COORDINATOR_POLL_INTERVAL_MAX_MS = 10_000;
+
+function parsePositiveIntegerMs(value: unknown, fallback: number): number {
 	const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
-	if (!Number.isFinite(parsed) || parsed <= 0) return 1000;
-	return Math.min(parsed, 30_000);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
 
-function boundedPollIntervalMs(value: unknown): number {
-	const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
-	if (!Number.isFinite(parsed) || parsed <= 0) return 100;
-	return Math.min(Math.max(parsed, 10), 1000);
+export function boundedAwaitTurnTimeoutMs(value: unknown): number {
+	return Math.min(parsePositiveIntegerMs(value, 1000), COORDINATOR_AWAIT_TURN_TIMEOUT_MAX_MS);
+}
+
+export function boundedRuntimePromptAckTimeoutMs(value: unknown): number {
+	return Math.min(
+		parsePositiveIntegerMs(value, DEFAULT_RUNTIME_PROMPT_ACK_TIMEOUT_MS),
+		COORDINATOR_RUNTIME_PROMPT_ACK_TIMEOUT_MAX_MS,
+	);
+}
+
+export function boundedEventWatchTimeoutMs(value: unknown): number {
+	return Math.min(parsePositiveIntegerMs(value, 1000), COORDINATOR_EVENT_WATCH_TIMEOUT_MAX_MS);
+}
+
+export function boundedPollIntervalMs(value: unknown): number {
+	return Math.min(Math.max(parsePositiveIntegerMs(value, 100), 10), COORDINATOR_POLL_INTERVAL_MAX_MS);
 }
 async function runCommand(command: string[]): Promise<{ exitCode: number; stdout: string; stderr: string }> {
 	const proc = Bun.spawn(command, { stdout: "pipe", stderr: "pipe" });
@@ -1387,7 +1546,9 @@ export async function readCoordinatorArtifact(
 }
 
 export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions = {}) {
-	const config = buildCoordinatorMcpConfig(options.env ?? process.env);
+	const env = options.env ?? process.env;
+	const config = buildCoordinatorMcpConfig(env);
+	const promptAckTimeoutMs = boundedRuntimePromptAckTimeoutMs(env.GJC_COORDINATOR_MCP_PROMPT_ACK_TIMEOUT_MS);
 	const services = options.services ?? {};
 	const namespaceDir = coordinatorNamespacePath(config);
 	const commandRunner = services.commandRunner ?? runCommand;
@@ -1485,14 +1646,17 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 		await writeTurnRecord(namespaceDir, activeTurn);
 		await writeActiveTurn(namespaceDir, activeTurn);
 		const sessionState = await readSessionState(namespaceDir, activeTurn.session_id);
-		const runtimeStateAlreadySettled =
-			sessionState?.current_turn_id === activeTurn.turn_id &&
-			(sessionState.state === "completed" || sessionState.state === "errored");
-		if (!runtimeStateAlreadySettled) {
-			await writeSessionState(namespaceDir, activeTurn.session_id, tmuxKeysSent ? "running" : "stale", {
+		const runtimeStateAlreadyAcknowledged =
+			sessionState !== null && runtimeStateAcknowledgesTurn(activeTurn, sessionState);
+		const resolvedTurn =
+			runtimeStateAlreadyAcknowledged && sessionState
+				? await markTurnAcknowledgedFromRuntimeState(namespaceDir, activeTurn, sessionState)
+				: activeTurn;
+		if (!runtimeStateAlreadyAcknowledged && !tmuxKeysSent) {
+			await writeSessionState(namespaceDir, activeTurn.session_id, "stale", {
 				currentTurnId: activeTurn.turn_id,
 				live,
-				reason: tmuxKeysSent ? null : "tmux_delivery_unavailable",
+				reason: "tmux_delivery_unavailable",
 			});
 		}
 		await appendCoordinatorEvent(namespaceDir, {
@@ -1505,7 +1669,7 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 			payloadRef: path.relative(namespaceDir, turnFile(namespaceDir, activeTurn.turn_id)),
 			metadata: { target: typeof target === "string" ? target : null, live },
 		});
-		return activeTurn;
+		return resolvedTurn;
 	}
 
 	async function promoteNextQueuedTurn(sessionId: string): Promise<TurnRecord | null> {
@@ -1533,33 +1697,67 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 		let resolvedTurn = turn;
 		let advisoryStatus: Record<string, unknown> = { live: false };
 		let sessionState = await readSessionState(namespaceDir, turn.session_id);
+		resolvedTurn = await reconcileRuntimeAcknowledgement(
+			namespaceDir,
+			resolvedTurn,
+			sessionState,
+			promptAckTimeoutMs,
+			{ failOnTimeout: false },
+		);
+		if (resolvedTurn !== turn) sessionState = await readSessionState(namespaceDir, resolvedTurn.session_id);
 		if (
 			sessionState &&
-			ACTIVE_TURN_STATUSES.has(turn.status) &&
-			sessionState.current_turn_id === turn.turn_id &&
+			ACTIVE_TURN_STATUSES.has(resolvedTurn.status) &&
+			(sessionState.current_turn_id === resolvedTurn.turn_id ||
+				(sessionState.state === "errored" &&
+					sessionState.source === "agent_session_event" &&
+					sessionState.current_turn_id == null)) &&
 			(sessionState.state === "completed" || sessionState.state === "errored")
 		) {
-			resolvedTurn = await markTurnTerminalFromSessionState(namespaceDir, turn, sessionState);
+			resolvedTurn = await markTurnTerminalFromSessionState(namespaceDir, resolvedTurn, sessionState);
 			sessionState = await readSessionState(namespaceDir, resolvedTurn.session_id);
 		} else if (
 			sessionState &&
-			ACTIVE_TURN_STATUSES.has(turn.status) &&
-			sessionState.current_turn_id === turn.turn_id &&
+			ACTIVE_TURN_STATUSES.has(resolvedTurn.status) &&
+			sessionState.current_turn_id === resolvedTurn.turn_id &&
 			sessionState.state === "stale" &&
 			sessionState.reason === "tmux_delivery_unavailable" &&
-			turn.delivery.state === "unavailable" &&
+			resolvedTurn.delivery.state === "unavailable" &&
 			session &&
 			hasTmuxIdentity(session)
 		) {
-			resolvedTurn = await markTurnFailedForUnavailableSession(namespaceDir, turn, "tmux_delivery_unavailable");
+			resolvedTurn = await markTurnFailedForUnavailableSession(
+				namespaceDir,
+				resolvedTurn,
+				"tmux_delivery_unavailable",
+			);
 			sessionState = await readSessionState(namespaceDir, resolvedTurn.session_id);
-		} else if (!session && ACTIVE_TURN_STATUSES.has(turn.status)) {
-			resolvedTurn = await markTurnFailedForUnavailableSession(namespaceDir, turn, "session_record_missing");
+		} else if (!session && ACTIVE_TURN_STATUSES.has(resolvedTurn.status)) {
+			resolvedTurn = await markTurnFailedForUnavailableSession(namespaceDir, resolvedTurn, "session_record_missing");
 			sessionState = await readSessionState(namespaceDir, resolvedTurn.session_id);
 		} else if (session) {
 			advisoryStatus = await inspectTmuxSession(session, boundedLineCount(lines), commandRunner);
-			if (ACTIVE_TURN_STATUSES.has(turn.status) && hasTmuxIdentity(session) && advisoryStatus.live === false) {
-				resolvedTurn = await markTurnFailedForUnavailableSession(namespaceDir, turn, "tmux_session_missing");
+			if (
+				ACTIVE_TURN_STATUSES.has(resolvedTurn.status) &&
+				hasTmuxIdentity(session) &&
+				advisoryStatus.live === false
+			) {
+				resolvedTurn = await markTurnFailedForUnavailableSession(
+					namespaceDir,
+					resolvedTurn,
+					"tmux_session_missing",
+				);
+				sessionState = await readSessionState(namespaceDir, resolvedTurn.session_id);
+			}
+		}
+		if (ACTIVE_TURN_STATUSES.has(resolvedTurn.status)) {
+			resolvedTurn = await reconcileRuntimeAcknowledgement(
+				namespaceDir,
+				resolvedTurn,
+				sessionState,
+				promptAckTimeoutMs,
+			);
+			if (!ACTIVE_TURN_STATUSES.has(resolvedTurn.status)) {
 				sessionState = await readSessionState(namespaceDir, resolvedTurn.session_id);
 			}
 		}
@@ -1579,6 +1777,46 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 		};
 	}
 
+	async function reconcileActiveTurnAcknowledgements(): Promise<void> {
+		const turns = (await listJsonFiles(turnsDir(namespaceDir)))
+			.map(turn => asRecord(turn) as TurnRecord | null)
+			.filter((turn): turn is TurnRecord => turn !== null && ACTIVE_TURN_STATUSES.has(turn.status));
+		for (const turn of turns) {
+			let sessionState = await readSessionState(namespaceDir, turn.session_id);
+			const resolvedTurn = await reconcileRuntimeAcknowledgement(
+				namespaceDir,
+				turn,
+				sessionState,
+				promptAckTimeoutMs,
+				{ failOnTimeout: false },
+			);
+			if (!ACTIVE_TURN_STATUSES.has(resolvedTurn.status)) continue;
+			if (resolvedTurn !== turn) sessionState = await readSessionState(namespaceDir, resolvedTurn.session_id);
+			const session = asRecord(await readJsonFile(sessionFile(resolvedTurn.session_id)));
+			if (
+				sessionState &&
+				sessionState.current_turn_id === resolvedTurn.turn_id &&
+				sessionState.state === "stale" &&
+				sessionState.reason === "tmux_delivery_unavailable" &&
+				resolvedTurn.delivery.state === "unavailable" &&
+				session &&
+				hasTmuxIdentity(session)
+			) {
+				await markTurnFailedForUnavailableSession(namespaceDir, resolvedTurn, "tmux_delivery_unavailable");
+				continue;
+			}
+			if (!session) {
+				await markTurnFailedForUnavailableSession(namespaceDir, resolvedTurn, "session_record_missing");
+				continue;
+			}
+			if (hasTmuxIdentity(session) && (await hasTmuxSession(session, commandRunner)) === false) {
+				await markTurnFailedForUnavailableSession(namespaceDir, resolvedTurn, "tmux_session_missing");
+				continue;
+			}
+			await reconcileRuntimeAcknowledgement(namespaceDir, resolvedTurn, sessionState, promptAckTimeoutMs);
+		}
+	}
+
 	async function callTool(name: string, args: Record<string, unknown> = {}): Promise<Record<string, unknown>> {
 		try {
 			if (name === "gjc_coordinator_list_sessions") return { ok: true, sessions: await listSessions() };
@@ -1619,6 +1857,7 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 				};
 			}
 			if (name === "gjc_coordinator_read_status") {
+				await reconcileActiveTurnAcknowledgements();
 				const sessionId = args.session_id;
 				if (sessionId) {
 					const session = asRecord(await readJsonFile(sessionFile(sessionId)));
@@ -1651,6 +1890,7 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 			if (name === "gjc_coordinator_read_artifact")
 				return await readCoordinatorArtifact(config, { path: args.path });
 			if (name === "gjc_coordinator_read_coordination_status") {
+				await reconcileActiveTurnAcknowledgements();
 				const sessions = jsonRecords(await listSessions());
 				const sessionStates = jsonRecords(await listJsonFiles(path.join(namespaceDir, "session-states")));
 				const turns = jsonRecords(await listJsonFiles(turnsDir(namespaceDir)));
@@ -1684,13 +1924,15 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 				};
 			}
 			if (name === "gjc_coordinator_watch_events") {
+				await reconcileActiveTurnAcknowledgements();
 				const limit = boundedEventLimit(args.limit);
-				const timeoutMs = boundedTimeoutMs(args.timeout_ms);
+				const timeoutMs = boundedEventWatchTimeoutMs(args.timeout_ms);
 				let events = await readCoordinatorEvents(namespaceDir);
 				let matched = filterCoordinatorEvents(events, args, limit);
 				let timedOut = false;
 				if (matched.length === 0 && timeoutMs > 0) {
 					await waitForCoordinatorEvents(namespaceDir, timeoutMs);
+					await reconcileActiveTurnAcknowledgements();
 					events = await readCoordinatorEvents(namespaceDir);
 					matched = filterCoordinatorEvents(events, args, limit);
 					timedOut = matched.length === 0;
@@ -1819,7 +2061,7 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 				};
 				if (promptAliasIgnored) base.prompt_alias_ignored = true;
 				if (args.await_completion === true && !shouldQueue) {
-					const timeoutMs = boundedTimeoutMs(args.timeout_ms);
+					const timeoutMs = boundedAwaitTurnTimeoutMs(args.timeout_ms);
 					const pollIntervalMs = boundedPollIntervalMs(args.poll_interval_ms);
 					const deadline = Date.now() + timeoutMs;
 					let payload = await readTurnPayload(turn.turn_id, sessionId, args.lines);
@@ -1979,7 +2221,7 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 				return await readTurnPayload(args.turn_id, args.session_id, args.lines);
 			}
 			if (name === "gjc_coordinator_await_turn") {
-				const timeoutMs = boundedTimeoutMs(args.timeout_ms);
+				const timeoutMs = boundedAwaitTurnTimeoutMs(args.timeout_ms);
 				const pollIntervalMs = boundedPollIntervalMs(args.poll_interval_ms);
 				const deadline = Date.now() + timeoutMs;
 				let payload = await readTurnPayload(args.turn_id, args.session_id, args.lines);

package/src/gjc-runtime/launch-tmux.ts

@@ -6,6 +6,7 @@ import type { Args } from "../cli/args";
 import { tmuxRuntimeSessionPath } from "./session-layout";
 import { GJC_COORDINATOR_SESSION_ID_ENV, GJC_COORDINATOR_SESSION_STATE_FILE_ENV } from "./session-state-sidecar";
 import {
+	buildGjcTmuxExactSessionTarget,
 	buildGjcTmuxProfileCommands,
 	buildGjcTmuxSessionName,
 	buildGjcTmuxSessionSlug,
@@ -21,6 +22,7 @@ import {
 import { findGjcTmuxSessionByName, findGjcTmuxSessionByScope, type GjcTmuxSessionStatus } from "./tmux-sessions";
 
 export {
+	buildGjcTmuxExactSessionTarget,
 	buildGjcTmuxProfileCommands,
 	GJC_DEFAULT_TMUX_SESSION,
 	GJC_TMUX_COMMAND_ENV,
@@ -201,12 +203,24 @@ function buildWindowsPowerShellInnerCommand(context: CommandResolutionContext, r
 	const envLines = Object.entries({ [GJC_TMUX_LAUNCHED_ENV]: "1", ...(context.extraEnv ?? {}) }).map(
 		([key, value]) => `$env:${key} = ${powershellQuote(value)}`,
 	);
-	const invocation = ["&", ...command.map(powershellQuote), ...stripRootTmuxFlag(rawArgs).map(powershellQuote)].join(
-		" ",
-	);
+	// The inner `&` invocation must wrap the resolved gjc command in a
+	// script-block so the trailing PowerShell exec-policy flags from the
+	// outer invocation are not forwarded into the bun / node / .bat
+	// binary the gjc command resolves to. Without the wrapping, the flags
+	// reach the runtime binary and cause an immediate failure that closes
+	// the psmux pane before the gjc --tmux attach can land.
+	const resolvedCommand = command.map(powershellQuote).join(" ");
+	const innerArgs = stripRootTmuxFlag(rawArgs).map(powershellQuote).join(" ");
+	const invocation = `& { ${resolvedCommand} ${innerArgs} }`;
 	const exitLine = "if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE } else { exit 1 }";
 	const script = [...envLines, invocation, exitLine].join("\n");
-	const encodedCommand = Buffer.from(script, "utf16le").toString("base64");
+	// PowerShell -EncodedCommand requires a UTF-16LE BOM (0xFF 0xFE) at the
+	// start of the decoded buffer; without it pwsh may misinterpret the
+	// leading bytes and reject the script with a parse error, which would
+	// kill the psmux pane before the gjc --tmux attach could land.
+	const bom = Buffer.from([0xff, 0xfe]);
+	const body = Buffer.from(script, "utf16le");
+	const encodedCommand = Buffer.concat([bom, body]).toString("base64");
 	return `pwsh -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encodedCommand}`;
 }
 
@@ -395,7 +409,11 @@ function readCurrentBranch(cwd: string): string | null {
 }
 
 function cleanupCreatedTmuxSession(plan: TmuxLaunchPlan, spawnSync: TmuxSpawnSync, options: TmuxSpawnOptions): void {
-	spawnSync(plan.tmuxCommand, ["kill-session", "-t", `=${plan.sessionName}`], options);
+	spawnSync(
+		plan.tmuxCommand,
+		["kill-session", "-t", buildGjcTmuxExactSessionTarget(plan.sessionName, { env: options.env })],
+		options,
+	);
 }
 function isTmuxAttachDisconnectError(result: TmuxSpawnResult): boolean {
 	if (result.signalCode === "SIGHUP") return true;
@@ -499,7 +517,11 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 	};
 
 	if (plan.attachSessionName) {
-		const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.attachSessionName}`], options);
+		const attached = spawnSync(
+			plan.tmuxCommand,
+			["attach-session", "-t", buildGjcTmuxExactSessionTarget(plan.attachSessionName, { env })],
+			options,
+		);
 		if (attached.exitCode === 0) return true;
 	}
 
@@ -510,7 +532,7 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 			buildGjcTmuxWindowTitle(plan.project ?? plan.cwd, plan.branch),
 			spawnSync,
 			options,
-			`=${plan.sessionName}`,
+			buildGjcTmuxExactSessionTarget(plan.sessionName, { env }),
 		);
 
 		const profile = applyGjcTmuxProfile({
@@ -535,7 +557,11 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 		}
 	}
 	if (created.exitCode !== 0) return false;
-	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.sessionName}`], options);
+	const attached = spawnSync(
+		plan.tmuxCommand,
+		["attach-session", "-t", buildGjcTmuxExactSessionTarget(plan.sessionName, { env })],
+		options,
+	);
 	if (attached.exitCode === 0) return true;
 	if (isTmuxAttachDisconnectError(attached)) {
 		(context.diagnosticWriter ?? safeStderrWrite)(formatTmuxLaunchDiagnostic("attach disconnected", attached.stderr));

package/src/gjc-runtime/launch-worktree.ts

@@ -118,6 +118,20 @@ function findWorktreeByPath(entries: GitWorktreeEntry[], worktreePath: string):
 	return entries.find(entry => path.resolve(entry.path) === resolved) ?? null;
 }
 
+function describeWorktreeEntry(entry: GitWorktreeEntry): string {
+	return entry.detached ? `detached HEAD ${entry.head}` : (entry.branchRef ?? `HEAD ${entry.head}`);
+}
+
+function formatWorktreeTargetMismatch(plan: GjcLaunchWorktreePlan, existing: GitWorktreeEntry): string {
+	const expected = plan.detached ? `detached HEAD ${plan.baseRef}` : `branch refs/heads/${plan.branchName ?? ""}`;
+	return [
+		`worktree_target_mismatch:${plan.worktreePath}`,
+		`GJC launch worktree target is already registered for ${describeWorktreeEntry(existing)}, but this launch expects ${expected}.`,
+		`Path: ${plan.worktreePath}`,
+		"Refusing to delete or reuse the conflicting worktree automatically. Safe remediation: inspect the path, commit/stash any work, then remove or prune the stale worktree with git worktree remove <path> when it is no longer needed, or choose a different --worktree name.",
+	].join("\n");
+}
+
 function hasBranchInUse(entries: GitWorktreeEntry[], branchName: string, worktreePath: string): boolean {
 	const expectedRef = `refs/heads/${branchName}`;
 	const resolvedPath = path.resolve(worktreePath);
@@ -228,7 +242,7 @@ export function ensureLaunchWorktree(
 		let dirty = isWorktreeDirty(plan.worktreePath);
 		if (plan.detached) {
 			if (!existingAtPath.detached) {
-				throw new Error(`worktree_target_mismatch:${plan.worktreePath}`);
+				throw new Error(formatWorktreeTargetMismatch(plan, existingAtPath));
 			}
 			if (existingAtPath.head !== plan.baseRef) {
 				if (dirty) throw new Error(`worktree_dirty:${plan.worktreePath}`);
@@ -236,7 +250,7 @@ export function ensureLaunchWorktree(
 				dirty = false;
 			}
 		} else if (existingAtPath.branchRef !== expectedBranchRef) {
-			throw new Error(`worktree_target_mismatch:${plan.worktreePath}`);
+			throw new Error(formatWorktreeTargetMismatch(plan, existingAtPath));
 		}
 		return {
 			...plan,

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

@@ -1896,13 +1896,27 @@ function readCurrentTmuxLeaderContext(tmuxCommand: string, env: NodeJS.ProcessEn
 	}
 	return { sessionName, windowIndex, leaderPaneId, target: `${sessionName}:${windowIndex}` };
 }
-export function resolveGjcWorkerCommand(cwd = process.cwd(), env: NodeJS.ProcessEnv = process.env): string {
+export function resolveGjcWorkerCommand(
+	cwd = process.cwd(),
+	env: NodeJS.ProcessEnv = process.env,
+	platform: NodeJS.Platform = process.platform,
+	argv: string[] = process.argv,
+	execPath = process.execPath,
+): string {
 	const explicit = env.GJC_TEAM_WORKER_COMMAND?.trim();
 	if (explicit) return explicit;
-	const entrypoint = process.argv[1];
-	if (entrypoint?.endsWith(".ts"))
-		return `${shellQuote(process.execPath)} ${shellQuote(path.resolve(cwd, entrypoint))}`;
-	if (entrypoint && path.basename(entrypoint).startsWith("gjc")) return shellQuote(path.resolve(cwd, entrypoint));
+	const entrypoint = argv[1];
+	if (!entrypoint) return "gjc";
+	const pathModule = platform === "win32" ? path.win32 : path;
+	const resolvedEntrypoint = pathModule.isAbsolute(entrypoint) ? entrypoint : pathModule.resolve(cwd, entrypoint);
+	if (platform === "win32") {
+		if (entrypoint.endsWith(".ts") || entrypoint.endsWith(".js") || entrypoint.endsWith(".mjs"))
+			return `${powershellQuote(execPath)} ${powershellQuote(resolvedEntrypoint)}`;
+		if (pathModule.basename(entrypoint).startsWith("gjc")) return powershellQuote(resolvedEntrypoint);
+		return "gjc";
+	}
+	if (entrypoint.endsWith(".ts")) return `${shellQuote(execPath)} ${shellQuote(resolvedEntrypoint)}`;
+	if (path.basename(entrypoint).startsWith("gjc")) return shellQuote(path.resolve(cwd, entrypoint));
 	return "gjc";
 }
 /** @internal Exported for unit tests. */
@@ -1937,7 +1951,8 @@ export function buildWorkerCommand(
 		...(worker.worktree_path ? [envAssignment("GJC_TEAM_WORKTREE_PATH", worker.worktree_path)] : []),
 	];
 	const joined = platform === "win32" ? envLines.join(" ") : envLines.join(" ");
-	return `${joined} ${config.worker_command} ${quote(prompt)}`;
+	const invocation = platform === "win32" ? `& ${config.worker_command}` : config.worker_command;
+	return `${joined} ${invocation} ${quote(prompt)}`;
 }
 interface GjcTeamInitialLane {
 	label: string;

package/src/gjc-runtime/tmux-common.ts

@@ -86,6 +86,22 @@ export function buildGjcTmuxExactOptionTarget(
 	return `=${sessionName}:`;
 }
 
+/**
+ * Build the exact-session target for tmux *session-scoped* commands such as
+ * `attach-session` and `kill-session`. Native tmux accepts `=NAME` for an
+ * exact session match, but Windows psmux 3.3.x rejects that target form for
+ * session commands even though the bare `NAME` resolves. Keep native tmux on
+ * exact targets and intentionally use the bare session name for psmux.
+ */
+export function buildGjcTmuxExactSessionTarget(
+	sessionName: string,
+	opts: { env?: NodeJS.ProcessEnv; platform?: NodeJS.Platform; binary?: ResolvedTmuxBinary } = {},
+): string {
+	const binary = opts.binary ?? resolveGjcTmuxBinary({ env: opts.env, platform: opts.platform });
+	if (binary.isPsmux) return sessionName;
+	return `=${sessionName}`;
+}
+
 export const GJC_TMUX_UNTAGGED_REASON = "gjc_tmux_session_untagged";
 
 export function buildGjcTmuxUntaggedSessionHint(tmuxCommand: string): string {