@gajae-code/coding-agent 0.7.7 → 0.7.9

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

@@ -1,4 +1,5 @@
 import { Buffer } from "node:buffer";
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { VERSION } from "@gajae-code/utils/dirs";
 import { safeStderrWrite } from "@gajae-code/utils/safe-stderr";
@@ -6,6 +7,8 @@ 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 {
+	buildGjcTmuxExactOptionTarget,
+	buildGjcTmuxExactSessionTarget,
 	buildGjcTmuxProfileCommands,
 	buildGjcTmuxSessionName,
 	buildGjcTmuxSessionSlug,
@@ -21,6 +24,7 @@ import {
 import { findGjcTmuxSessionByName, findGjcTmuxSessionByScope, type GjcTmuxSessionStatus } from "./tmux-sessions";
 
 export {
+	buildGjcTmuxExactSessionTarget,
 	buildGjcTmuxProfileCommands,
 	GJC_DEFAULT_TMUX_SESSION,
 	GJC_TMUX_COMMAND_ENV,
@@ -33,6 +37,7 @@ export const GJC_TMUX_LAUNCHED_ENV = "GJC_TMUX_LAUNCHED";
 export const GJC_LAUNCH_POLICY_ENV = "GJC_LAUNCH_POLICY";
 export const GJC_TMUX_WINDOW_LABEL_MAX_WIDTH = 48;
 export const GJC_PSMUX_PROFILE_FORCE_ENV = "GJC_PSMUX_PROFILE_FORCE";
+const TERMINAL_TITLE_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
 
 type LaunchPolicy = "direct" | "tmux";
 
@@ -70,9 +75,18 @@ export type TmuxSpawnSync = (command: string, args: string[], options: TmuxSpawn
 export interface TmuxSpawnOptions {
 	cwd: string;
 	env: NodeJS.ProcessEnv;
-	stdin: "inherit";
-	stdout: "inherit";
-	stderr: "inherit";
+	stdin: "inherit" | "pipe";
+	stdout: "inherit" | "pipe";
+	stderr: "inherit" | "pipe";
+	/**
+	 * When true, the spawn captures stderr into a buffer and forwards it to
+	 * the parent stderr so the user still sees the live output. The captured
+	 * text is also returned in TmuxSpawnResult.stderr for diagnostic
+	 * surfacing in "attach failed" / "profile tagging failed" messages.
+	 * Defaults to false to preserve the previous PTY-binding behavior for
+	 * attach-session and other interactive commands.
+	 */
+	captureStderr?: boolean;
 }
 
 export interface TmuxLaunchPlan {
@@ -168,6 +182,48 @@ function formatTmuxLaunchDiagnostic(stage: string, stderr?: string): string {
 	return `gjc --tmux failed after creating tmux session: ${stage}.${suffix}\n`;
 }
 
+/**
+ * Detect a corrupted gjc.cmd / gjc.bat wrapper at well-known PATH locations.
+ * On Windows, `gjc.cmd` / `gjc.bat` files at the front of PATH that turn out
+ * to be PE-binary garbage (e.g. a 194MB PE image written over the wrapper)
+ * cause cmd.exe to hang silently when invoked from PowerShell — cmd reads
+ * the binary as text and never returns, so the user sees the prompt return
+ * with no output but no actual launch. This probe surfaces that failure mode
+ * in the diagnostic so the user gets a clear "wrapper corrupted" hint instead
+ * of a silent exit. Best-effort: returns null when the file is missing,
+ * unreadable, or under 1KB (real CMD wrappers are 100-500 bytes; the original
+ * 194MB PE-binary garbage was obviously out of band). Sync because the
+ * call site (launchDefaultTmuxIfNeeded) is sync; uses statSync + 2-byte
+ * read.
+ */
+function detectCorruptedGjcWrapper(): string | null {
+	if (process.platform !== "win32") return null;
+	const pathEnv = process.env.PATH ?? "";
+	if (!pathEnv) return null;
+	const seen = new Set<string>();
+	for (const dir of pathEnv.split(path.delimiter)) {
+		for (const name of ["gjc.cmd", "gjc.bat"]) {
+			const full = path.join(dir, name);
+			if (seen.has(full)) continue;
+			seen.add(full);
+			try {
+				const stat = fs.statSync(full);
+				if (!stat.isFile()) continue;
+				if (stat.size < 1024) continue;
+				if (stat.size > 64 * 1024) {
+					return `Detected suspicious gjc wrapper at ${full}: ${stat.size} bytes (expected <1KB). The wrapper may be corrupted; cmd.exe will hang reading it as text. Recreate it from the gjc-tmux.cmd template.`;
+				}
+				const head = fs.readFileSync(full);
+				if (head.byteLength < 2) continue;
+				const view = new Uint8Array(head);
+				if (view[0] === 0x4d && view[1] === 0x5a) {
+					return `Detected PE-binary gjc wrapper at ${full} (MZ header, ${stat.size} bytes). cmd.exe will hang reading it as text. Recreate the wrapper from the gjc-tmux.cmd template.`;
+				}
+			} catch {}
+		}
+	}
+	return null;
+}
 function formatTmuxUnavailableDiagnostic(platform: NodeJS.Platform, tmuxCommand: string): string {
 	if (platform === "win32") {
 		return (
@@ -201,12 +257,30 @@ 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(
-		" ",
-	);
+	// Resolve the inner command and arguments. PowerShell's `&` call operator
+	// accepts a single command followed by its arguments directly (no script
+	// block needed). Wrapping the call in `& { ... }` would be invalid because
+	// adjacent single-quoted tokens inside a script block body are a parser
+	// error: `& { 'a' 'b' }` fails with "Unexpected token 'b'" because PowerShell
+	// only concatenates adjacent *double-quoted* strings, and even then only in
+	// expression position. Emitting the arguments as a comma-separated array
+	// (`& 'cmd' @('a','b')`) is also rejected because arrays are not valid as
+	// the second-and-later positional arguments to `&` in command position. The
+	// correct form is `& 'cmd' 'arg1' 'arg2'` — exactly what the joined
+	// resolvedCommand + innerArgs produces below.
+	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");
+	// Encode the script as UTF-16LE base64 for pwsh -EncodedCommand. Do NOT
+	// prepend a UTF-16LE BOM (0xFF 0xFE): the BOM survives the decode and is
+	// inserted as a literal U+FEFF character in front of the first script
+	// token, which pwsh then reports as a "term not recognized" parse error
+	// (e.g. "$env:GJC_TMUX_LAUNCHED"). pwsh expects the decoded buffer to
+	// start with the first character of the script, not with a BOM.
+	const body = Buffer.from(script, "utf16le");
+	const encodedCommand = body.toString("base64");
 	return `pwsh -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encodedCommand}`;
 }
 
@@ -236,7 +310,14 @@ export function applyGjcTmuxProfile(context: GjcTmuxProfileContext): GjcTmuxProf
 	if (commands.length === 0) return { skipped: true, commands: [], failures: [] };
 	const spawnSync = context.spawnSync ?? defaultSpawnSync;
 	const cwd = context.cwd ?? process.cwd();
-	const options: TmuxSpawnOptions = { cwd, env, stdin: "inherit", stdout: "inherit", stderr: "inherit" };
+	const options: TmuxSpawnOptions = {
+		cwd,
+		env,
+		stdin: "inherit",
+		stdout: "inherit",
+		stderr: "inherit",
+		captureStderr: true,
+	};
 	const failures: GjcTmuxProfileResult["failures"] = [];
 	for (const command of commands) {
 		const result = spawnSync(context.tmuxCommand, command.args, options);
@@ -307,6 +388,8 @@ function truncateVisibleTail(value: string, maxWidth: number): string {
 }
 
 const GJC_TMUX_WINDOW_BRANCH_SEPARATOR = "-";
+const GJC_TMUX_WINDOW_TITLE_PREFIX = "GJC-";
+const GJC_TMUX_TERMINAL_TITLE_PREFIX = "GJC: ";
 
 function sanitizeTmuxWindowTitleSegment(value: string): string {
 	return value.replace(/:+/g, "-");
@@ -319,20 +402,68 @@ function sanitizeTmuxWindowProjectName(project: string): string {
 	return sanitizeTmuxWindowTitleSegment(trimmed);
 }
 
-export function buildGjcTmuxWindowTitle(cwd: string, branch: string | null | undefined): string {
+function buildGjcTmuxPrefixedTitle(prefix: string, cwd: string, branch: string | null | undefined): string {
 	const project = sanitizeTmuxWindowProjectName(path.basename(path.resolve(cwd)) || "gjc");
+	const projectTitle = `${prefix}${project}`;
 	const trimmedBranch = sanitizeTmuxWindowTitleSegment(branch?.trim() ?? "");
-	if (!trimmedBranch) return truncateVisible(project, GJC_TMUX_WINDOW_LABEL_MAX_WIDTH);
+	if (!trimmedBranch) return truncateVisible(projectTitle, GJC_TMUX_WINDOW_LABEL_MAX_WIDTH);
 
 	const separatorWidth = visibleWidth(GJC_TMUX_WINDOW_BRANCH_SEPARATOR);
-	const projectWidth = visibleWidth(project);
-	const fullTitle = `${project}${GJC_TMUX_WINDOW_BRANCH_SEPARATOR}${trimmedBranch}`;
+	const projectWidth = visibleWidth(projectTitle);
+	const fullTitle = `${projectTitle}${GJC_TMUX_WINDOW_BRANCH_SEPARATOR}${trimmedBranch}`;
 	if (visibleWidth(fullTitle) <= GJC_TMUX_WINDOW_LABEL_MAX_WIDTH) return fullTitle;
 
 	const remainingBranchWidth = GJC_TMUX_WINDOW_LABEL_MAX_WIDTH - projectWidth - separatorWidth;
-	if (remainingBranchWidth <= 0) return truncateVisible(project, GJC_TMUX_WINDOW_LABEL_MAX_WIDTH);
+	if (remainingBranchWidth <= 0) return truncateVisible(projectTitle, GJC_TMUX_WINDOW_LABEL_MAX_WIDTH);
+
+	return `${projectTitle}${GJC_TMUX_WINDOW_BRANCH_SEPARATOR}${truncateVisibleTail(trimmedBranch, remainingBranchWidth)}`;
+}
+
+export function buildGjcTmuxWindowTitle(cwd: string, branch: string | null | undefined): string {
+	return buildGjcTmuxPrefixedTitle(GJC_TMUX_WINDOW_TITLE_PREFIX, cwd, branch);
+}
 
-	return `${project}${GJC_TMUX_WINDOW_BRANCH_SEPARATOR}${truncateVisibleTail(trimmedBranch, remainingBranchWidth)}`;
+function buildGjcTmuxRootTerminalTitle(cwd: string, branch: string | null | undefined): string {
+	return buildGjcTmuxPrefixedTitle(GJC_TMUX_TERMINAL_TITLE_PREFIX, cwd, branch);
+}
+
+function sanitizeGjcTmuxRootTerminalTitle(title: string): string {
+	return title.replace(TERMINAL_TITLE_CONTROL_CHARS, "").trim() || "GJC";
+}
+
+function escapeTmuxFormatLiteral(value: string): string {
+	return value.replace(/#/g, "##");
+}
+
+function buildGjcTmuxRootTerminalTitleCommands(target: string, title: string): GjcTmuxProfileCommand[] {
+	const sanitized = escapeTmuxFormatLiteral(sanitizeGjcTmuxRootTerminalTitle(title));
+	return [
+		{ description: "enable tmux client terminal title", args: ["set-option", "-t", target, "set-titles", "on"] },
+		{
+			description: "set tmux client terminal title",
+			args: ["set-option", "-t", target, "set-titles-string", sanitized],
+		},
+	];
+}
+
+function applyGjcTmuxRootTerminalTitleProfile(context: {
+	tmuxCommand: string;
+	target: string;
+	title: string | undefined;
+	spawnSync: TmuxSpawnSync;
+	options: TmuxSpawnOptions;
+}): void {
+	if (!context.title) return;
+	for (const command of buildGjcTmuxRootTerminalTitleCommands(
+		buildGjcTmuxExactOptionTarget(context.target, { env: context.options.env }),
+		context.title,
+	)) {
+		context.spawnSync(context.tmuxCommand, command.args, context.options);
+	}
+}
+
+function shouldSetGjcTmuxRootTerminalTitle(parsed: Args, env: NodeJS.ProcessEnv): boolean {
+	return !parsed.noTitle && !env.PI_NO_TITLE;
 }
 
 function buildTmuxRenameWindowArgs(title: string, target?: string): string[] {
@@ -395,7 +526,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;
@@ -472,15 +607,33 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 }
 
 function defaultSpawnSync(command: string, args: string[], options: TmuxSpawnOptions): TmuxSpawnResult {
+	// When captureStderr is set on the options, route stderr through a
+	// pipe so we can both forward it to the parent stderr (so the user
+	// still sees the live output) and retain it in TmuxSpawnResult.stderr
+	// for diagnostic surfacing. PTY-bound commands (attach-session) keep
+	// stderr: "inherit" because psmux needs a real terminal handle.
+	const stdio = options.captureStderr
+		? { stdin: options.stdin, stdout: options.stdout, stderr: "pipe" as const }
+		: { stdin: options.stdin, stdout: options.stdout, stderr: options.stderr };
 	const result = Bun.spawnSync({
 		cmd: [command, ...args],
 		cwd: options.cwd,
 		env: options.env,
-		stdin: options.stdin,
-		stdout: options.stdout,
-		stderr: options.stderr,
+		...stdio,
 	});
-	return { exitCode: result.exitCode, signalCode: result.signalCode };
+	let stderrText: string | undefined;
+	if (options.captureStderr) {
+		const stderrBytes = result.stderr;
+		stderrText = stderrBytes ? new TextDecoder().decode(stderrBytes) : "";
+		if (stderrText.length > 0) {
+			try {
+				process.stderr.write(stderrText);
+			} catch {
+				// parent stderr already closed during shutdown; ignore.
+			}
+		}
+	}
+	return { exitCode: result.exitCode, signalCode: result.signalCode, stderr: stderrText };
 }
 
 export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
@@ -497,23 +650,64 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 		stdout: "inherit",
 		stderr: "inherit",
 	};
+	const attachOptions: TmuxSpawnOptions = { ...options };
+	const controlOptions: TmuxSpawnOptions = { ...options, captureStderr: true };
+	// has-session / new-session retry / profile-tagging probe share these
+	// pipe-stdio options. PTY-bound commands (attach-session, rename-window,
+	// set-option in applyGjcTmuxProfile when we explicitly need the live TTY)
+	// use `options` or `attachOptions` instead.
+	const probeOptions: TmuxSpawnOptions = {
+		...options,
+		stdin: "pipe",
+		stdout: "pipe",
+		stderr: "pipe",
+		captureStderr: true,
+	};
+	// new-session needs pipe stdio (not inherit) because the user terminal must
+	// remain untouched until attach-session takes over. Inheriting psmux's
+	// stdout/stderr for new-session can corrupt the terminal state or race with
+	// attach-session on Windows, where psmux 3.3.0/3.3.6's server can die if it
+	// sees the controlling TTY in an inconsistent state mid-spawn. Capturing
+	// both streams also gives the diagnostic writer the full error detail when
+	// new-session itself fails.
+	const newSessionOptions: TmuxSpawnOptions = {
+		...options,
+		stdin: "pipe",
+		stdout: "pipe",
+		stderr: "pipe",
+		captureStderr: true,
+	};
 
-	if (plan.attachSessionName) {
-		const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.attachSessionName}`], options);
-		if (attached.exitCode === 0) return true;
-	}
+	const windowTitle = buildGjcTmuxWindowTitle(plan.project ?? plan.cwd, plan.branch);
+	const rootTerminalTitle = shouldSetGjcTmuxRootTerminalTitle(context.parsed, env)
+		? buildGjcTmuxRootTerminalTitle(plan.project ?? plan.cwd, plan.branch)
+		: undefined;
 
-	const created = spawnSync(plan.tmuxCommand, plan.newSessionArgs, options);
-	if (created.exitCode === 0) {
-		renameTmuxWindow(
-			plan.tmuxCommand,
-			buildGjcTmuxWindowTitle(plan.project ?? plan.cwd, plan.branch),
+	if (plan.attachSessionName) {
+		applyGjcTmuxRootTerminalTitleProfile({
+			tmuxCommand: plan.tmuxCommand,
+			target: plan.attachSessionName,
+			title: rootTerminalTitle,
 			spawnSync,
 			options,
-			`=${plan.sessionName}`,
+		});
+		const attached = spawnSync(
+			plan.tmuxCommand,
+			["attach-session", "-t", buildGjcTmuxExactSessionTarget(plan.attachSessionName, { env })],
+			attachOptions,
 		);
-
-		const profile = applyGjcTmuxProfile({
+		if (attached.exitCode === 0) return true;
+	}
+	const created = spawnSync(plan.tmuxCommand, plan.newSessionArgs, newSessionOptions);
+	if (created.exitCode === 0) {
+		// On Windows + psmux 3.3.0/3.3.6, new-session can return exit 0
+		// before the psmux server finishes registering the session on its
+		// control socket. The follow-up set-option / attach-session then
+		// fails with "can't find session / no server running". Probe the
+		// server first, and if the race fired, retry new-session before
+		// we hand the session to rename-window / applyGjcTmuxProfile so the
+		// profile-tagging path always sees a registered session.
+		const buildProfileInputs = (): GjcTmuxProfileContext => ({
 			tmuxCommand: plan.tmuxCommand,
 			target: plan.sessionName,
 			cwd: plan.cwd,
@@ -525,17 +719,106 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 			sessionStateFile: plan.sessionStateFile ?? null,
 			version: VERSION,
 		});
+		const probeHasSession = (): TmuxSpawnResult =>
+			spawnSync(
+				plan.tmuxCommand,
+				["has-session", "-t", buildGjcTmuxExactSessionTarget(plan.sessionName, { env })],
+				probeOptions,
+			);
+		const probeResult = probeHasSession();
+		if (probeResult.exitCode !== 0) {
+			const retry = spawnSync(plan.tmuxCommand, plan.newSessionArgs, newSessionOptions);
+			const retryProbe = probeHasSession();
+			if (retry.exitCode !== 0 || retryProbe.exitCode !== 0) {
+				(context.diagnosticWriter ?? safeStderrWrite)(
+					formatTmuxLaunchDiagnostic(
+						"new-session retry failed after missing session",
+						retry.stderr ?? retryProbe.stderr ?? created.stderr,
+					),
+				);
+				cleanupCreatedTmuxSession(plan, spawnSync, options);
+				return false;
+			}
+		}
+		renameTmuxWindow(
+			plan.tmuxCommand,
+			windowTitle,
+			spawnSync,
+			controlOptions,
+			buildGjcTmuxExactSessionTarget(plan.sessionName, { env }),
+		);
+		const profile = applyGjcTmuxProfile(buildProfileInputs());
+		// If the @gjc-profile ownership write failed, the cause can be
+		// either (a) a real psmux persistence-tag rejection (e.g.
+		// unsupported option on this server), or (b) the same new-session
+		// registration race above — psmux returned 0 but the server died
+		// before registering, so the follow-up set-option failed with
+		// "can't find session". Distinguish the two: re-probe; if the
+		// session is genuinely missing, retry new-session and re-apply the
+		// profile. Otherwise, surface the persistence-tag failure.
 		const ownershipFailure = profile.failures.find(item => item.command.args.includes("@gjc-profile"));
 		if (ownershipFailure) {
-			cleanupCreatedTmuxSession(plan, spawnSync, options);
-			(context.diagnosticWriter ?? safeStderrWrite)(
-				formatTmuxLaunchDiagnostic("profile tagging failed", ownershipFailure.stderr),
-			);
-			return true;
+			const probeAfterOwnership = probeHasSession();
+			if (probeAfterOwnership.exitCode === 0) {
+				// Session is present; tagging failed for a real reason.
+				cleanupCreatedTmuxSession(plan, spawnSync, options);
+				(context.diagnosticWriter ?? safeStderrWrite)(
+					formatTmuxLaunchDiagnostic("profile tagging failed", ownershipFailure.stderr),
+				);
+				return true;
+			}
+			// Session is missing — retry.
+			const retry = spawnSync(plan.tmuxCommand, plan.newSessionArgs, newSessionOptions);
+			const retryProbe = probeHasSession();
+			if (retry.exitCode !== 0 || retryProbe.exitCode !== 0) {
+				cleanupCreatedTmuxSession(plan, spawnSync, options);
+				(context.diagnosticWriter ?? safeStderrWrite)(
+					formatTmuxLaunchDiagnostic(
+						"new-session retry failed after ownership failure",
+						retry.stderr ?? retryProbe.stderr ?? ownershipFailure.stderr,
+					),
+				);
+				return true;
+			}
+			const retryProfile = applyGjcTmuxProfile(buildProfileInputs());
+			const retryOwnershipFailure = retryProfile.failures.find(item => item.command.args.includes("@gjc-profile"));
+			if (retryOwnershipFailure) {
+				cleanupCreatedTmuxSession(plan, spawnSync, options);
+				(context.diagnosticWriter ?? safeStderrWrite)(
+					formatTmuxLaunchDiagnostic("profile tagging failed after retry", retryOwnershipFailure.stderr),
+				);
+				return true;
+			}
+			// Recovery succeeded via retry — fall through to attach-session below.
 		}
+		applyGjcTmuxRootTerminalTitleProfile({
+			tmuxCommand: plan.tmuxCommand,
+			target: plan.sessionName,
+			title: rootTerminalTitle,
+			spawnSync,
+			options,
+		});
 	}
-	if (created.exitCode !== 0) return false;
-	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.sessionName}`], options);
+	const probeWarning = detectCorruptedGjcWrapper();
+	if (created.exitCode !== 0) {
+		// The new-session spawn failed. Surface the captured stderr so the
+		// user sees the actual psmux rejection (e.g. "cannot create session:
+		// server is shutting down") instead of a silent exit. The wrapper
+		// probe gives the user a deterministic hint when the silent-exit
+		// symptom is actually caused by a corrupted gjc.cmd / gjc.bat on
+		// PATH (a 194MB PE-binary at the wrapper path produces cmd.exe
+		// hangs that look like a tmux/psmux failure from the user's seat).
+		const stderr = created.stderr;
+		const suffix = probeWarning ? ` Wrapper warning: ${probeWarning}` : "";
+		(context.diagnosticWriter ?? safeStderrWrite)(formatTmuxLaunchDiagnostic("new-session failed", stderr) + suffix);
+		return false;
+	}
+	// attach-session needs PTY inherit for the user-facing attach; keep it unchanged.
+	const attached = spawnSync(
+		plan.tmuxCommand,
+		["attach-session", "-t", buildGjcTmuxExactSessionTarget(plan.sessionName, { env })],
+		attachOptions,
+	);
 	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. */
@@ -1917,7 +1931,22 @@ export function buildWorkerCommand(
 	const workspace = worker.worktree_path
 		? `Worker worktree: ${worker.worktree_path}.`
 		: `Worker cwd: ${config.leader.cwd}.`;
-	const prompt = [
+	// The worker prompt body is dispatched into the pane through
+	// `tmux send-keys`, which treats embedded LF characters as Enter
+	// keypresses. A multi-line prompt therefore lands in the pane as
+	// multiple prompt bodies followed by premature Enter presses, which on
+	// Windows + psmux/ConPTY causes the worker CLI to bail out before the
+	// startup ACK fires. Normalize the body to a single line by replacing
+	// any LF/CRLF with a space, and strip a defensive U+FEFF in case a
+	// caller managed to inject a UTF-8 BOM into the task text. Empty /
+	// whitespace-only bodies fall back to a one-line placeholder so the
+	// worker never sits idle at an empty prompt.
+	const normalizePrompt = (raw: string): string =>
+		raw
+			.replace(/[\uFEFF\u200B]/g, "")
+			.replace(/\r?\n+/g, " ")
+			.trim();
+	const rawPrompt = [
 		`You are ${worker.id} in gjc team ${config.team_name}.`,
 		`Team state root: ${config.state_root}.`,
 		workspace,
@@ -1926,6 +1955,7 @@ export function buildWorkerCommand(
 		`Before claiming work, send startup ACK: gjc team api worker-startup-ack --input '{"team_name":"${config.team_name}","worker_id":"${worker.id}","protocol_version":"1"}' --json.`,
 		`Use gjc team api update-worker-status to report task-local activity, then claim-task/transition-task-status with this worker id; keep heartbeat current during long work, record completion_evidence (summary plus a passed command or verified inspection/artifact item) before completed, and do not mutate leader-owned goal state.`,
 	].join("\n");
+	const prompt = normalizePrompt(rawPrompt) || `Worker ${worker.id} ready.`;
 	const envLines = [
 		envAssignment("GJC_TEAM_WORKER", `${config.team_name}/${worker.id}`),
 		envAssignment("GJC_TEAM_INTERNAL_WORKER", `${config.team_name}/${worker.id}`),
@@ -1937,6 +1967,32 @@ export function buildWorkerCommand(
 		...(worker.worktree_path ? [envAssignment("GJC_TEAM_WORKTREE_PATH", worker.worktree_path)] : []),
 	];
 	const joined = platform === "win32" ? envLines.join(" ") : envLines.join(" ");
+	// On Windows we wrap the worker command invocation in `& { & 'cmd' 'arg1' ... }`
+	// so pwsh keeps the whole multi-statement body in command position. Two
+	// failure modes this avoids:
+	//   1. Bare `bun 'cli.ts' 'prompt'` after `$env:X = 'y'; ...` would be
+	//      parsed in expression position and PowerShell would reject the
+	//      second quoted token with "Unexpected token '<cli.ts>'".
+	//   2. `& { 'cmd' 'arg1' 'arg2' }` (single & inside a block with adjacent
+	//      single-quoted tokens) is itself invalid because pwsh does not
+	//      concatenate adjacent single-quoted strings inside a script block.
+	// The nested `&` inside the block forces command-position parsing for
+	// the invocation. POSIX shells do not need this — they already treat
+	// `cmd 'arg'` as a normal command invocation after `;`-separated
+	// variable assignments.
+	//
+	// ASSUMPTION: this branch only fires when the worker pane is a PowerShell
+	// shell. psmux launches pwsh by default on Windows, so the unset /
+	// unset-and-replace cases are correct. If a user has explicitly set
+	// `set -g default-shell "C:/Program Files/Git/bin/bash.exe"` (or any
+	// other non-pwsh shell), this branch will send PowerShell syntax to a
+	// bash pane and the worker will fail with a parse error. Detecting the
+	// pane's shell at runtime and switching the quoting + invocation style
+	// accordingly is a follow-up; for now the pwsh default is assumed.
+	if (platform === "win32") {
+		const invocation = `& ${config.worker_command} ${quote(prompt)}`;
+		return `& { ${joined} ${invocation} }`;
+	}
 	return `${joined} ${config.worker_command} ${quote(prompt)}`;
 }
 interface GjcTeamInitialLane {
@@ -2055,7 +2111,6 @@ async function startTmuxSession(
 					"#{pane_id}",
 					"-c",
 					worker.worktree_path ?? config.leader.cwd,
-					buildWorkerCommand(config, worker),
 				],
 				{ stdout: "pipe", stderr: "pipe" },
 			);
@@ -2066,6 +2121,31 @@ async function startTmuxSession(
 			rollbackPaneIds.push(paneId);
 			if (worker.index === 1) rightStackRootPaneId = paneId;
 			workers.push({ ...worker, pane_id: paneId });
+			// On psmux/ConPTY (Windows pwsh default-shell) panes, tmux writes the
+			// split-window command argv to the new pane's stdin but pwsh's
+			// readline never receives an Enter, so the worker never starts.
+			// Create the pane without a command, then dispatch the worker
+			// command through send-keys + Enter so it actually executes.
+			// Two-step dispatch because tmux's `-l` (literal mode) flag is
+			// global per send-keys invocation, not per arg: passing `-l
+			// <body> Enter` would treat "Enter" as literal text too. Sending
+			// the body in literal mode first and the Enter keypress second
+			// keeps the body verbatim while still submitting the prompt as a
+			// keystroke.
+			const body = buildWorkerCommand(config, worker);
+			Bun.spawnSync([config.tmux_command, "send-keys", "-l", "-t", paneId, body], {
+				stdout: "ignore",
+				stderr: "ignore",
+			});
+			const sendKeys = Bun.spawnSync([config.tmux_command, "send-keys", "-t", paneId, "Enter"], {
+				stdout: "ignore",
+				stderr: "ignore",
+			});
+			// void-cast the exit code so the linter does not flag an unused
+			// expression; the value is intentionally discarded here because
+			// the actual spawn outcome is recovered by the leader through
+			// the worker startup-ack watcher, not via the spawn exit code.
+			void sendKeys.exitCode;
 		}
 		Bun.spawnSync([config.tmux_command, "select-layout", "-t", config.tmux_target, "main-vertical"], {
 			stdout: "ignore",