@gajae-code/coding-agent 0.9.1 → 0.9.3

package/src/discovery/mcp-json.ts

@@ -30,6 +30,7 @@ interface MCPConfigFile {
 			command?: string;
 			args?: string[];
 			env?: Record<string, string>;
+			noInheritEnv?: boolean;
 			cwd?: string;
 			url?: string;
 			headers?: Record<string, string>;
@@ -92,6 +93,18 @@ function transformMCPConfig(config: MCPConfigFile, source: SourceMeta): MCPServe
 				}
 			}
 
+			let noInheritEnv: boolean | undefined;
+			if (serverConfig.noInheritEnv !== undefined) {
+				if (typeof serverConfig.noInheritEnv === "boolean") {
+					noInheritEnv = serverConfig.noInheritEnv;
+				} else {
+					logger.warn("MCP server has invalid 'noInheritEnv' value, ignoring", {
+						name,
+						value: serverConfig.noInheritEnv,
+					});
+				}
+			}
+
 			const server: MCPServer = {
 				name,
 				enabled,
@@ -100,6 +113,7 @@ function transformMCPConfig(config: MCPConfigFile, source: SourceMeta): MCPServe
 				command: serverConfig.command,
 				args: serverConfig.args,
 				env: serverConfig.env,
+				noInheritEnv,
 				cwd: serverConfig.cwd,
 				url: serverConfig.url,
 				headers: serverConfig.headers,

package/src/extensibility/runtime-skill-discovery.ts

@@ -0,0 +1,229 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { findRepoRoot } from "../capability/fs";
+import type { Skill as CapabilitySkill } from "../capability/skill";
+import type { SkillsSettings } from "../config/settings-schema";
+import { compareSkillOrder, scanSkillsFromDir } from "../discovery/helpers";
+import type { Skill } from "./skills";
+
+export type RuntimeSkillDiscoverySource = "project" | "user";
+
+export interface RuntimeSkillDiscoveryCandidate {
+	name: string;
+	description: string;
+	source: RuntimeSkillDiscoverySource;
+	path: string;
+	useWhen?: string[];
+}
+
+export interface DiscoverRuntimeSkillsOptions {
+	cwd: string;
+	home?: string;
+	query?: string;
+	limit?: number;
+	source?: RuntimeSkillDiscoverySource | "all";
+	policy?: SkillsSettings;
+}
+
+function getRuntimeHome(): string {
+	return process.env.HOME || os.homedir();
+}
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 50;
+
+function normalizeLimit(limit: number | undefined): number {
+	if (limit === undefined || !Number.isFinite(limit)) return DEFAULT_LIMIT;
+	return Math.max(1, Math.min(MAX_LIMIT, Math.trunc(limit)));
+}
+
+async function getProjectSkillDirs(cwd: string, home: string): Promise<{ dirs: string[]; repoRoot: string | null }> {
+	const dirs: string[] = [];
+	let current = path.resolve(cwd);
+	const resolvedHome = path.resolve(home);
+	const repoRoot = await findRepoRoot(current);
+	const stop = path.resolve(repoRoot ?? current);
+	while (true) {
+		if (current !== resolvedHome) {
+			dirs.push(path.join(current, ".gjc", "skills"));
+		}
+		if (current === stop) break;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return { dirs, repoRoot };
+}
+
+function getUseWhen(skill: CapabilitySkill): string[] | undefined {
+	const frontmatter = skill.frontmatter as Record<string, unknown> | undefined;
+	const values: string[] = [];
+	const globs = frontmatter?.globs;
+	if (Array.isArray(globs)) {
+		values.push(...globs.filter((value): value is string => typeof value === "string"));
+	} else if (typeof globs === "string") {
+		values.push(globs);
+	}
+	for (const key of ["use_when", "useWhen", "conditions"]) {
+		const raw = frontmatter?.[key];
+		if (typeof raw === "string") values.push(raw);
+		if (Array.isArray(raw)) values.push(...raw.filter((value): value is string => typeof value === "string"));
+	}
+	return values.length > 0 ? values : undefined;
+}
+
+function toRuntimeSkill(skill: CapabilitySkill, source: RuntimeSkillDiscoverySource): Skill {
+	return {
+		name: skill.name,
+		description: typeof skill.frontmatter?.description === "string" ? skill.frontmatter.description : "",
+		filePath: skill.path,
+		baseDir: skill.path.replace(/[\\/]SKILL\.md$/, ""),
+		source: `runtime:${source}`,
+		hide: skill.frontmatter?.hide === true,
+		_source: { ...skill._source, providerName: "Runtime skill discovery" },
+	};
+}
+function sourceEnabled(source: RuntimeSkillDiscoverySource, policy: SkillsSettings | undefined): boolean {
+	if (policy?.enabled !== true) return false;
+	if (source === "project") return policy.enablePiProject === true;
+	if (source === "user") return policy.enablePiUser === true;
+	return false;
+}
+
+function matchesIncludePatterns(name: string, includeSkills: string[] | undefined): boolean {
+	if (!includeSkills || includeSkills.length === 0) return true;
+	return includeSkills.some(pattern => new Bun.Glob(pattern).match(name));
+}
+
+function matchesIgnorePatterns(name: string, ignoredSkills: string[] | undefined): boolean {
+	if (!ignoredSkills || ignoredSkills.length === 0) return false;
+	return ignoredSkills.some(pattern => new Bun.Glob(pattern).match(name));
+}
+
+function isDisabledSkill(name: string, disabledExtensions: string[] | undefined): boolean {
+	return (disabledExtensions ?? []).some(id => id === `skill:${name}`);
+}
+
+function isAllowedByPolicy(
+	skill: CapabilitySkill,
+	source: RuntimeSkillDiscoverySource,
+	policy: SkillsSettings | undefined,
+): boolean {
+	if (!sourceEnabled(source, policy)) return false;
+	if (isDisabledSkill(skill.name, policy?.disabledExtensions)) return false;
+	if (matchesIgnorePatterns(skill.name, policy?.ignoredSkills)) return false;
+	if (!matchesIncludePatterns(skill.name, policy?.includeSkills)) return false;
+	return true;
+}
+function matchesQuery(candidate: RuntimeSkillDiscoveryCandidate, query: string): boolean {
+	const normalized = query.trim().toLowerCase();
+	if (!normalized) return true;
+	const haystack = [candidate.name, candidate.description, candidate.source, ...(candidate.useWhen ?? [])]
+		.join("\n")
+		.toLowerCase();
+	return normalized
+		.split(/\s+/)
+		.filter(Boolean)
+		.every(term => haystack.includes(term));
+}
+
+async function realPathOrSelf(filePath: string): Promise<string> {
+	try {
+		return await fs.realpath(filePath);
+	} catch {
+		return filePath;
+	}
+}
+
+export async function discoverRuntimeSkills(
+	options: DiscoverRuntimeSkillsOptions,
+): Promise<RuntimeSkillDiscoveryCandidate[]> {
+	const home = options.home ?? getRuntimeHome();
+	const source = options.source ?? "all";
+	const policy = options.policy;
+	const scanJobs: Array<Promise<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource }[]>> = [];
+	const projectSkills = await getProjectSkillDirs(options.cwd, home);
+	const projectContext = { cwd: options.cwd, home, repoRoot: projectSkills.repoRoot };
+	if ((source === "all" || source === "project") && sourceEnabled("project", policy)) {
+		for (const dir of projectSkills.dirs) {
+			scanJobs.push(
+				scanSkillsFromDir(projectContext, {
+					dir,
+					providerId: "runtime",
+					level: "project",
+					requireDescription: true,
+				}).then(result => result.items.map(skill => ({ skill, source: "project" as const }))),
+			);
+		}
+	}
+	if ((source === "all" || source === "user") && sourceEnabled("user", policy)) {
+		scanJobs.push(
+			scanSkillsFromDir(
+				{ cwd: options.cwd, home, repoRoot: home },
+				{ dir: path.join(home, ".gjc", "skills"), providerId: "runtime", level: "user", requireDescription: true },
+			).then(result => result.items.map(skill => ({ skill, source: "user" as const }))),
+		);
+	}
+
+	const seenNames = new Set<string>();
+	const seenPaths = new Set<string>();
+	const candidates: RuntimeSkillDiscoveryCandidate[] = [];
+	for (const entry of (await Promise.all(scanJobs)).flat()) {
+		if (!isAllowedByPolicy(entry.skill, entry.source, policy)) continue;
+		const realPath = await realPathOrSelf(entry.skill.path);
+		if (seenPaths.has(realPath) || seenNames.has(entry.skill.name)) continue;
+		seenPaths.add(realPath);
+		seenNames.add(entry.skill.name);
+		const candidate: RuntimeSkillDiscoveryCandidate = {
+			name: entry.skill.name,
+			description:
+				typeof entry.skill.frontmatter?.description === "string" ? entry.skill.frontmatter.description : "",
+			source: entry.source,
+			path: entry.skill.path,
+			useWhen: getUseWhen(entry.skill),
+		};
+		if (matchesQuery(candidate, options.query ?? "")) candidates.push(candidate);
+	}
+	candidates.sort((a, b) => compareSkillOrder(a.name, a.path, b.name, b.path));
+	return candidates.slice(0, normalizeLimit(options.limit));
+}
+
+export async function findRuntimeSkillByName(
+	cwd: string,
+	name: string,
+	policy?: SkillsSettings,
+	home = getRuntimeHome(),
+): Promise<Skill | undefined> {
+	const normalized = name.trim();
+	if (!normalized) return undefined;
+	const scanJobs: Array<Promise<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource }[]>> = [];
+	const projectSkills = await getProjectSkillDirs(cwd, home);
+	const projectContext = { cwd, home, repoRoot: projectSkills.repoRoot };
+	if (sourceEnabled("project", policy)) {
+		scanJobs.push(
+			...projectSkills.dirs.map(dir =>
+				scanSkillsFromDir(projectContext, {
+					dir,
+					providerId: "runtime",
+					level: "project",
+					requireDescription: true,
+				}).then(result => result.items.map(skill => ({ skill, source: "project" as const }))),
+			),
+		);
+	}
+	if (sourceEnabled("user", policy)) {
+		scanJobs.push(
+			scanSkillsFromDir(
+				{ cwd, home, repoRoot: home },
+				{ dir: path.join(home, ".gjc", "skills"), providerId: "runtime", level: "user", requireDescription: true },
+			).then(result => result.items.map(skill => ({ skill, source: "user" as const }))),
+		);
+	}
+	for (const entry of (await Promise.all(scanJobs)).flat()) {
+		if (entry.skill.name === normalized && isAllowedByPolicy(entry.skill, entry.source, policy)) {
+			return toRuntimeSkill(entry.skill, entry.source);
+		}
+	}
+	return undefined;
+}

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

@@ -158,11 +158,43 @@ export interface GjcTmuxProfileContext {
 	version?: string | null;
 }
 
+function tmuxExitMarkerPath(sessionStateFile: string): string {
+	return path.join(path.dirname(sessionStateFile), "tmux-exit.json");
+}
+
+function buildPosixTmuxExitMarkerPrefix(markerPath: string): string {
+	const markerDir = path.dirname(markerPath);
+	return [
+		`__gjc_tmux_exit_marker=${shellQuote(markerPath)}`,
+		"__gjc_tmux_write_exit_marker() { __gjc_tmux_status=$?",
+		"__gjc_tmux_ended_at=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date)",
+		`mkdir -p ${shellQuote(markerDir)} 2>/dev/null || true`,
+		'printf \'{"schema_version":1,"source":"tmux_inner_shell","ended_at":"%s","exit_code":%s}\\n\' "$__gjc_tmux_ended_at" "$__gjc_tmux_status" > "$__gjc_tmux_exit_marker" 2>/dev/null || true',
+		"}",
+		"trap __gjc_tmux_write_exit_marker EXIT",
+	].join("; ");
+}
+
+function buildPowerShellTmuxExitMarkerFinally(markerPath: string): string {
+	const markerDir = path.win32.dirname(markerPath);
+	return [
+		"} finally {",
+		"\ttry {",
+		`\t\tNew-Item -ItemType Directory -Force -Path ${powershellQuote(markerDir)} -ErrorAction Stop | Out-Null`,
+		"\t\t$__gjcTmuxExitMarker = @{ schema_version = 1; source = 'tmux_inner_shell'; ended_at = (Get-Date).ToUniversalTime().ToString('o'); exit_code = $__gjcTmuxExitCode } | ConvertTo-Json -Compress",
+		`\t\tSet-Content -LiteralPath ${powershellQuote(markerPath)} -Value $__gjcTmuxExitMarker -Encoding UTF8 -ErrorAction Stop`,
+		"\t} catch {",
+		"\t}",
+		"}",
+	].join("\n");
+}
+
 interface CommandResolutionContext {
 	cwd: string;
 	argv: string[];
 	execPath: string;
 	extraEnv?: Record<string, string>;
+	tmuxExitMarkerPath?: string;
 	platform?: NodeJS.Platform;
 }
 
@@ -286,7 +318,17 @@ function buildWindowsPowerShellInnerCommand(context: CommandResolutionContext, r
 	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 script = context.tmuxExitMarkerPath
+		? [
+				...envLines,
+				"$__gjcTmuxExitCode = 1",
+				"try {",
+				`\t${invocation}`,
+				"\tif ($null -ne $LASTEXITCODE) { $__gjcTmuxExitCode = $LASTEXITCODE } else { $__gjcTmuxExitCode = 1 }",
+				buildPowerShellTmuxExitMarkerFinally(context.tmuxExitMarkerPath),
+				"exit $__gjcTmuxExitCode",
+			].join("\n")
+		: [...envLines, invocation, exitLine].join("\n");
 	// 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
@@ -366,7 +408,9 @@ function buildInnerCommand(context: CommandResolutionContext, rawArgs: string[])
 	if (isWindowsPlatform(context.platform)) return buildWindowsPowerShellInnerCommand(context, rawArgs);
 	const command = resolveCurrentGjcCommand(context);
 	const quoted = [...command, ...stripRootTmuxFlag(rawArgs)].map(shellQuote).join(" ");
-	return `exec env ${GJC_TMUX_LAUNCHED_ENV}=1${buildEnvAssignments(context.extraEnv)} ${quoted}`;
+	const invocation = `env ${GJC_TMUX_LAUNCHED_ENV}=1${buildEnvAssignments(context.extraEnv)} ${quoted}`;
+	if (!context.tmuxExitMarkerPath) return `exec ${invocation}`;
+	return `${buildPosixTmuxExitMarkerPrefix(context.tmuxExitMarkerPath)}; ${invocation}; exit $?`;
 }
 
 function visibleWidth(value: string): number {
@@ -404,6 +448,9 @@ 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: ";
+const GJC_TMUX_ROOT_TERMINAL_TITLE_OPTION = "@gjc-root-terminal-title";
+const GJC_TMUX_ROOT_TERMINAL_TITLE_SESSION_OPTION = "@gjc-root-terminal-title-session";
+const GJC_TMUX_DYNAMIC_SESSION_TITLE = "GJC: #{session_name}";
 
 function sanitizeTmuxWindowTitleSegment(value: string): string {
 	return value.replace(/:+/g, "-");
@@ -445,17 +492,31 @@ function sanitizeGjcTmuxRootTerminalTitle(title: string): string {
 	return title.replace(TERMINAL_TITLE_CONTROL_CHARS, "").trim() || "GJC";
 }
 
-function escapeTmuxFormatLiteral(value: string): string {
-	return value.replace(/#/g, "##");
+function buildGjcTmuxRootTerminalTitleFormat(sessionName: string): string {
+	if (!sessionName.startsWith(GJC_TMUX_SESSION_PREFIX)) return GJC_TMUX_DYNAMIC_SESSION_TITLE;
+	return `#{?#{==:#{${GJC_TMUX_ROOT_TERMINAL_TITLE_SESSION_OPTION}},#{session_name}},#{${GJC_TMUX_ROOT_TERMINAL_TITLE_OPTION}},${GJC_TMUX_DYNAMIC_SESSION_TITLE}}`;
 }
 
-function buildGjcTmuxRootTerminalTitleCommands(target: string, title: string): GjcTmuxProfileCommand[] {
-	const sanitized = escapeTmuxFormatLiteral(sanitizeGjcTmuxRootTerminalTitle(title));
+function buildGjcTmuxRootTerminalTitleCommands(
+	target: string,
+	sessionName: string,
+	title: string,
+): GjcTmuxProfileCommand[] {
+	const sanitized = sanitizeGjcTmuxRootTerminalTitle(title);
+	const format = buildGjcTmuxRootTerminalTitleFormat(sessionName);
 	return [
+		{
+			description: "remember tmux client terminal title fallback",
+			args: ["set-option", "-t", target, GJC_TMUX_ROOT_TERMINAL_TITLE_OPTION, sanitized],
+		},
+		{
+			description: "remember tmux client terminal title session",
+			args: ["set-option", "-t", target, GJC_TMUX_ROOT_TERMINAL_TITLE_SESSION_OPTION, sessionName],
+		},
 		{ 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],
+			description: "set dynamic tmux client terminal title",
+			args: ["set-option", "-t", target, "set-titles-string", format],
 		},
 	];
 }
@@ -468,10 +529,8 @@ function applyGjcTmuxRootTerminalTitleProfile(context: {
 	options: TmuxSpawnOptions;
 }): void {
 	if (!context.title) return;
-	for (const command of buildGjcTmuxRootTerminalTitleCommands(
-		buildGjcTmuxExactOptionTarget(context.target, { env: context.options.env }),
-		context.title,
-	)) {
+	const optionTarget = buildGjcTmuxExactOptionTarget(context.target, { env: context.options.env });
+	for (const command of buildGjcTmuxRootTerminalTitleCommands(optionTarget, context.target, context.title)) {
 		context.spawnSync(context.tmuxCommand, command.args, context.options);
 	}
 }
@@ -695,6 +754,7 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 				// session, which would split/send workers into the wrong session.
 				[GJC_TMUX_ACTIVE_SESSION_ENV]: sessionName,
 			},
+			tmuxExitMarkerPath: tmuxExitMarkerPath(sessionStateFile),
 			platform,
 		},
 		context.rawArgs,

package/src/gjc-runtime/psmux-detect.ts

@@ -115,6 +115,20 @@ function outputMentionsPsmux(output: string): boolean {
 	return PSMUX_VERSION_MARKERS.some(marker => output.includes(marker));
 }
 
+function normalizedCommandBaseName(command: string): string {
+	const normalized = command
+		.trim()
+		.replace(/^['"]|['"]$/g, "")
+		.replace(/\\/g, "/");
+	const basename = normalized.slice(normalized.lastIndexOf("/") + 1).toLowerCase();
+	return basename.endsWith(".exe") ? basename.slice(0, -4) : basename;
+}
+
+function isNamedPsmuxCommand(command: string): boolean {
+	const basename = normalizedCommandBaseName(command);
+	return basename === "psmux" || basename === "pmux";
+}
+
 function resolveBinaryPath(candidate: string): string | null {
 	return activeBinaryResolver(candidate);
 }
@@ -194,13 +208,14 @@ export function resolveGjcTmuxBinary(options: ResolveGjcTmuxBinaryOptions = {}):
 	const runner = options.runner ?? readSpawnRunner();
 	const explicit = env.GJC_TMUX_COMMAND?.trim() || env.GJC_TEAM_TMUX_COMMAND?.trim();
 	if (explicit) {
-		const isPsmux = detectPsmux(explicit, { env, runner });
+		const isPsmux =
+			platform === "win32" && isNamedPsmuxCommand(explicit) ? true : detectPsmux(explicit, { env, runner });
 		return { command: explicit, isPsmux, viaExplicitOverride: true };
 	}
 	if (platform === "win32") {
 		for (const candidate of PSMUX_BINARY_NAMES) {
 			if (resolveBinaryPath(candidate)) {
-				const isPsmux = detectPsmux(candidate, { env, runner });
+				const isPsmux = isNamedPsmuxCommand(candidate) ? true : detectPsmux(candidate, { env, runner });
 				return { command: candidate, isPsmux, viaExplicitOverride: false };
 			}
 		}

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

@@ -242,9 +242,12 @@ function assertSafePathComponent(value: string, label: string): void {
 		throw new StateCommandError(2, `invalid path component for --${label}: ${value}`);
 	}
 }
+function isKnownMode(mode: string): mode is CanonicalGjcWorkflowSkill {
+	return KNOWN_MODES.includes(mode);
+}
 
 function assertKnownMode(mode: string): asserts mode is CanonicalGjcWorkflowSkill {
-	if (!KNOWN_MODES.includes(mode)) {
+	if (!isKnownMode(mode)) {
 		throw new StateCommandError(2, `unknown --mode: ${mode}. Expected one of: ${KNOWN_MODES.join(", ")}.`);
 	}
 }
@@ -1580,14 +1583,15 @@ async function handleHandoff(
 	if (!calleeRaw) {
 		throw new StateCommandError(2, "gjc state handoff requires --to <callee>");
 	}
-	assertKnownMode(calleeRaw);
-	const callee = calleeRaw as CanonicalGjcWorkflowSkill;
+	assertSafePathComponent(calleeRaw, "to");
+	const callee = calleeRaw;
+	const calleeIsWorkflow = isKnownMode(callee);
 	if (callee === caller) {
 		throw new StateCommandError(2, `gjc state handoff: --to must differ from caller (both are "${caller}")`);
 	}
 
 	const callerPath = modeStateFile(cwd, caller, sessionId);
-	const calleePath = modeStateFile(cwd, callee, sessionId);
+	const calleePath = calleeIsWorkflow ? modeStateFile(cwd, callee, sessionId) : undefined;
 	const forced = hasFlag(args, "--force");
 	const callerRead = await readExistingStateForMutation(callerPath);
 	if (callerRead.kind === "corrupt" && !forced) {
@@ -1602,15 +1606,7 @@ async function handleHandoff(
 			`gjc state ${caller} handoff: caller is not active (no mode-state file at ${callerPath})`,
 		);
 	}
-	const calleeRead = await readExistingStateForMutation(calleePath);
-	if (calleeRead.kind === "corrupt" && !forced) {
-		throw new StateCommandError(
-			2,
-			`existing state for ${callee} is corrupt or tampered (${calleeRead.error}); use --force to overwrite`,
-		);
-	}
 	const existingCaller = callerRead.kind === "valid" ? callerRead.value : {};
-	const existingCallee = calleeRead.kind === "valid" ? calleeRead.value : {};
 
 	const handoffAt = nowIso();
 	const mutationId = `${caller}:handoff:${callee}:${handoffAt}`;
@@ -1623,6 +1619,103 @@ async function handleHandoff(
 		nowIso: handoffAt,
 		mutationId,
 	});
+
+	// Runtime callees have no native mode-state to clear later, so do not
+	// persist them as active-state entries; the prompt observer tracks them
+	// in memory the same way direct `/skill:<runtime>` invocation does.
+	if (!calleeIsWorkflow) {
+		const normalizedCaller =
+			caller === "deep-interview"
+				? (normalizeDeepInterviewEnvelope(migrateWorkflowState(existingCaller, caller).state) as Record<
+						string,
+						unknown
+					>)
+				: migrateWorkflowState(existingCaller, caller).state;
+		const mergedCallerState: Record<string, unknown> = {
+			...normalizedCaller,
+			skill: caller,
+			version: WORKFLOW_STATE_VERSION,
+			active: false,
+			current_phase: "handoff",
+			handoff_to: callee,
+			handoff_at: handoffAt,
+			updated_at: handoffAt,
+			receipt: callerReceipt,
+		};
+		const force = hasFlag(args, "--force");
+		await beginWorkflowTransactionJournal({
+			cwd,
+			sessionId,
+			mutationId,
+			caller,
+			paths: [callerPath, activeStateFile(cwd, sessionId)],
+		});
+		const callerWrite = await writeJsonAtomic(cwd, callerPath, mergedCallerState, "handoff", {
+			sessionId,
+			skill: caller,
+			mutationId,
+			force,
+			fromPhase: typeof existingCaller.current_phase === "string" ? existingCaller.current_phase : undefined,
+			toPhase: "handoff",
+		});
+		await updateWorkflowTransactionJournal(cwd, sessionId, mutationId, { steps: ["caller-mode-state"] });
+		if (callerWrite.warning) process.stderr.write(`${callerWrite.warning}\n`);
+		const stampedCallerReceipt = isPlainObject(callerWrite.stamped.receipt) ? callerWrite.stamped.receipt : {};
+		await syncSkillActiveState({
+			cwd,
+			skill: caller,
+			active: false,
+			phase: "handoff",
+			sessionId,
+			threadId,
+			turnId,
+			source: "gjc-state-cli",
+			hud: buildHudForMode(caller, mergedCallerState),
+			handoff_to: callee,
+			handoff_at: handoffAt,
+			receipt: callerReceipt,
+		});
+		await updateWorkflowTransactionJournal(cwd, sessionId, mutationId, {
+			steps: ["caller-mode-state", "active-state"],
+		});
+		await completeWorkflowTransactionJournal(cwd, sessionId, mutationId);
+		await touchStateActivityMarker(cwd, sessionId, callerPath);
+		return {
+			status: 0,
+			stdout: renderCliWriteReceipt({
+				ok: true,
+				from: caller,
+				to: callee,
+				handoff_at: handoffAt,
+				phases: {
+					from: mergedCallerState.current_phase,
+				},
+				receipts: {
+					from: {
+						mutation_id: stampedCallerReceipt.mutation_id,
+						status: stampedCallerReceipt.status,
+						content_sha256: stampedCallerReceipt.content_sha256,
+					},
+				},
+				paths: {
+					from: callerPath,
+					active_state: activeStateFile(cwd, sessionId),
+				},
+			}),
+		};
+	}
+
+	if (!calleePath) {
+		throw new StateCommandError(2, `gjc state handoff failed to resolve workflow callee path for ${callee}`);
+	}
+	const calleeRead = await readExistingStateForMutation(calleePath);
+	if (calleeRead.kind === "corrupt" && !forced) {
+		throw new StateCommandError(
+			2,
+			`existing state for ${callee} is corrupt or tampered (${calleeRead.error}); use --force to overwrite`,
+		);
+	}
+	const existingCallee = calleeRead.kind === "valid" ? calleeRead.value : {};
 	const calleeReceipt = buildWorkflowStateReceipt({
 		cwd,
 		skill: callee,

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

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { getWorktreesDir } from "@gajae-code/utils/dirs";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import { buildTeamHudSummary as buildWorkflowTeamHudSummary } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
@@ -25,6 +26,7 @@ import {
 	GJC_TMUX_ACTIVE_SESSION_ENV,
 	GJC_TMUX_PROFILE_OPTION,
 	GJC_TMUX_PROFILE_VALUE,
+	resolveGjcTmuxBinary,
 	resolveGjcTmuxCommand,
 } from "./tmux-common";
 
@@ -288,6 +290,7 @@ export interface GjcTeamStartOptions {
 	cwd?: string;
 	env?: NodeJS.ProcessEnv;
 	dryRun?: boolean;
+	platform?: NodeJS.Platform;
 	mailboxDeliveryTransport?: GjcTeamMailboxDeliveryTransport;
 }
 
@@ -1844,18 +1847,41 @@ function findWorktreePath(repoRoot: string, worktreePath: string): string | null
 		if (line.startsWith("worktree ") && path.resolve(line.slice("worktree ".length)) === resolved) return resolved;
 	return null;
 }
+export function resolveWorkerWorktreePath(input: {
+	repoRoot: string;
+	stateDir: string;
+	teamName: string;
+	workerId: string;
+	platform: NodeJS.Platform;
+	isPsmux: boolean;
+}): string {
+	if (input.platform === "win32" && input.isPsmux) {
+		const slug = stableHash([input.repoRoot, input.stateDir, input.teamName].join("\0")).slice(0, 12);
+		return path.join(getWorktreesDir(), `team-${slug}-${input.workerId}`);
+	}
+	return path.join(input.stateDir, "worktrees", input.workerId);
+}
 async function ensureWorkerWorktree(
 	cwd: string,
 	dir: string,
 	teamName: string,
 	worker: GjcTeamWorker,
 	mode: GjcTeamWorktreeMode,
+	platform: NodeJS.Platform,
+	isPsmux: boolean,
 ): Promise<GjcTeamWorker> {
 	if (!mode.enabled) return worker;
 	if (!isGitRepository(cwd)) throw new Error(`team_worktree_requires_git_repo:${cwd}`);
 	const repoRoot = runGit(cwd, ["rev-parse", "--show-toplevel"]);
 	const baseRef = runGit(repoRoot, ["rev-parse", "HEAD"]);
-	const worktreePath = path.join(dir, "worktrees", worker.id);
+	const worktreePath = resolveWorkerWorktreePath({
+		repoRoot,
+		stateDir: dir,
+		teamName,
+		workerId: worker.id,
+		platform,
+		isPsmux,
+	});
 	const existing = findWorktreePath(repoRoot, worktreePath);
 	let created = false;
 	const branchName = mode.detached
@@ -2994,7 +3020,9 @@ export async function startGjcTeam(options: GjcTeamStartOptions): Promise<GjcTea
 	const dir = teamDir(stateRoot, teamName);
 	const createdAt = now();
 	const worktreeMode = resolveDefaultWorktreeMode(options.worktreeMode);
-	const tmuxCommand = resolveGjcTmuxCommand(env);
+	const platform = options.platform ?? process.platform;
+	const tmuxBinary = resolveGjcTmuxBinary({ env, platform });
+	const tmuxCommand = tmuxBinary.command;
 	const tmuxContext = options.dryRun
 		? { sessionName: "dry-run", windowIndex: "0", leaderPaneId: "%dry-run-leader", target: "dry-run:0" }
 		: readCurrentTmuxLeaderContext(tmuxCommand, env);
@@ -3003,7 +3031,11 @@ export async function startGjcTeam(options: GjcTeamStartOptions): Promise<GjcTea
 	const workers: GjcTeamWorker[] = [];
 	try {
 		for (const worker of initialWorkers)
-			workers.push(options.dryRun ? worker : await ensureWorkerWorktree(cwd, dir, teamName, worker, worktreeMode));
+			workers.push(
+				options.dryRun
+					? worker
+					: await ensureWorkerWorktree(cwd, dir, teamName, worker, worktreeMode, platform, tmuxBinary.isPsmux),
+			);
 	} catch (error) {
 		await rollbackCreatedWorktrees(workers);
 		throw error;