@gajae-code/coding-agent 0.7.3 → 0.7.5

package/src/extensibility/gjc-plugins/validation.ts

@@ -1,12 +1,15 @@
 import { isKnownWorkflowState } from "../../gjc-runtime/workflow-manifest";
 import type { CanonicalGjcWorkflowSkill } from "../../skill-state/active-state";
+import { assertMcpInstallPolicy } from "./mcp-policy";
 import {
 	GJC_AGENT_SUBSKILL_PHASES,
 	GJC_SUBSKILL_PARENT_AGENTS,
 	GJC_SUBSKILL_PARENT_SKILLS,
 	GjcPluginLoadError,
+	type GjcPluginRegistryEntry,
 	type GjcSubskillParentAgent,
 	type LoadedSubskillBinding,
+	type NormalizedGjcPluginBundle,
 	type SubskillFrontmatter,
 } from "./types";
 
@@ -74,3 +77,80 @@ export function buildParentPhaseSet(bindings: readonly LoadedSubskillBinding[]):
 	}
 	return new Set(seen.keys());
 }
+
+/**
+ * Hard install-time collision + security validation for a compiled bundle
+ * against the effective installed registry (other plugins in the target scope
+ * universe). Collisions are hard errors; the registry is the collision
+ * authority, never capability first-wins.
+ */
+export function validateInstallPlan(
+	bundle: NormalizedGjcPluginBundle,
+	effectiveEntries: readonly GjcPluginRegistryEntry[],
+): void {
+	const others = effectiveEntries.filter(e => e.name !== bundle.name);
+
+	const toolNames = new Set<string>();
+	const hookKeys = new Set<string>();
+	const mcpNames = new Set<string>();
+	const appendixIds = new Set<string>();
+	const subskillArgs = new Set<string>();
+	const parentPhases = new Set<string>();
+	for (const e of others) {
+		for (const t of e.surfaces.tools) toolNames.add(t.name);
+		for (const h of e.surfaces.hooks) hookKeys.add(h.extensionId);
+		for (const m of e.surfaces.mcps) mcpNames.add(m.name);
+		for (const a of e.surfaces.systemAppendices) appendixIds.add(a.extensionId);
+		for (const a of e.surfaces.agentAppendices) appendixIds.add(a.extensionId);
+		for (const s of e.surfaces.subskills) {
+			subskillArgs.add(`${s.parent}\u0000${s.activationArg}`);
+			parentPhases.add(`${s.parent}\u0000${s.phase}`);
+		}
+	}
+
+	// Check candidate surfaces against the effective registry AND against each
+	// other (intra-bundle duplicates are also hard errors).
+	for (const t of bundle.surfaces.tools) {
+		if (toolNames.has(t.name)) {
+			throw new GjcPluginLoadError("duplicate_tool", `GJC plugin tool name collides: ${t.name}`);
+		}
+		toolNames.add(t.name);
+	}
+	for (const h of bundle.surfaces.hooks) {
+		if (hookKeys.has(h.extensionId)) {
+			throw new GjcPluginLoadError("duplicate_hook", `GJC plugin hook collides: ${h.extensionId}`);
+		}
+		hookKeys.add(h.extensionId);
+	}
+	for (const m of bundle.surfaces.mcps) {
+		if (mcpNames.has(m.name)) {
+			throw new GjcPluginLoadError("duplicate_mcp", `GJC plugin MCP name collides: ${m.name}`);
+		}
+		mcpNames.add(m.name);
+		assertMcpInstallPolicy(m.config, { pluginRoot: bundle.root });
+	}
+	for (const a of [...bundle.surfaces.systemAppendices, ...bundle.surfaces.agentAppendices]) {
+		if (appendixIds.has(a.extensionId)) {
+			throw new GjcPluginLoadError("duplicate_appendix", `GJC plugin appendix collides: ${a.extensionId}`);
+		}
+		appendixIds.add(a.extensionId);
+	}
+	for (const s of bundle.surfaces.subskills) {
+		const argKey = `${s.parent}\u0000${s.activationArg}`;
+		const phaseKey = `${s.parent}\u0000${s.phase}`;
+		if (subskillArgs.has(argKey)) {
+			throw new GjcPluginLoadError(
+				"duplicate_arg",
+				`GJC plugin subskill activation_arg collides for ${s.parent}: ${s.activationArg}`,
+			);
+		}
+		if (parentPhases.has(phaseKey)) {
+			throw new GjcPluginLoadError(
+				"duplicate_parent_phase",
+				`GJC plugin subskill parent/phase collides: ${s.parent}/${s.phase}`,
+			);
+		}
+		subskillArgs.add(argKey);
+		parentPhases.add(phaseKey);
+	}
+}

package/src/extensibility/skills.ts

@@ -10,6 +10,7 @@ import type { SkillPromptDetails } from "../session/messages";
 import { expandTilde } from "../tools/path-utils";
 import type { LoadedSubskillActivation } from "./gjc-plugins";
 import { buildSubskillInjection } from "./gjc-plugins/injection";
+import { renderSkillAdvertisement } from "./gjc-plugins/runtime-adapters";
 export interface Skill {
 	name: string;
 	description: string;
@@ -415,6 +416,20 @@ export async function buildSkillPromptMessage(
 		} else if (context.subskillActivation) {
 			details.subskillActivation = context.subskillActivation;
 		}
+		// Tier-1 advertisement: metadata-only list of installed sub-skills bound to
+		// this parent skill, so the agent can choose one contextually.
+		if (context.cwd) {
+			try {
+				const advert = await renderSkillAdvertisement({
+					cwd: context.cwd,
+					skillName: skill.name,
+					phase: context.currentPhase,
+				});
+				if (advert) message += `\n\n${advert}`;
+			} catch {
+				// Advertisement is best-effort; never block skill prompt construction.
+			}
+		}
 	}
 	return {
 		message,

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

@@ -1,7 +1,7 @@
 import { Buffer } from "node:buffer";
 import * as path from "node:path";
-import { safeStderrWrite } from "@gajae-code/utils";
 import { VERSION } from "@gajae-code/utils/dirs";
+import { safeStderrWrite } from "@gajae-code/utils/safe-stderr";
 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";
@@ -15,6 +15,7 @@ import {
 	GJC_TMUX_PROFILE_ENV,
 	GJC_TMUX_SESSION_PREFIX,
 	type GjcTmuxProfileCommand,
+	resolveGjcTmuxBinary,
 	resolveGjcTmuxCommand,
 } from "./tmux-common";
 import { findGjcTmuxSessionByName, findGjcTmuxSessionByScope, type GjcTmuxSessionStatus } from "./tmux-sessions";
@@ -31,6 +32,7 @@ export {
 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";
 
 type LaunchPolicy = "direct" | "tmux";
 
@@ -166,6 +168,18 @@ function formatTmuxLaunchDiagnostic(stage: string, stderr?: string): string {
 	return `gjc --tmux failed after creating tmux session: ${stage}.${suffix}\n`;
 }
 
+function formatTmuxUnavailableDiagnostic(platform: NodeJS.Platform, tmuxCommand: string): string {
+	if (platform === "win32") {
+		return (
+			`gjc --tmux requested but no tmux executable was found; starting without a tmux-backed session. ` +
+			`GJC searched for psmux, pmux, and tmux on PATH (got \`${tmuxCommand}\`). ` +
+			"Install psmux (https://github.com/psmux/psmux) for native Windows tmux support, or use WSL with real tmux. " +
+			"You can also point GJC at a specific binary via GJC_TMUX_COMMAND.\n"
+		);
+	}
+	return `gjc --tmux requested but no ${tmuxCommand} executable was found; starting without a tmux-backed session.\n`;
+}
+
 function shellQuote(value: string): string {
 	if (value.length === 0) return "''";
 	return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -199,14 +213,26 @@ function buildWindowsPowerShellInnerCommand(context: CommandResolutionContext, r
 export function applyGjcTmuxProfile(context: GjcTmuxProfileContext): GjcTmuxProfileResult {
 	const env = context.env ?? process.env;
 	const branchSlug = context.branch ? buildGjcTmuxSessionSlug(context.branch) : (context.branchSlug ?? null);
-	const commands = buildGjcTmuxProfileCommands(context.target, env, {
-		branch: context.branch ?? null,
-		branchSlug,
-		project: context.project ?? null,
-		sessionId: context.sessionId ?? env[GJC_COORDINATOR_SESSION_ID_ENV] ?? null,
-		sessionStateFile: context.sessionStateFile ?? env[GJC_COORDINATOR_SESSION_STATE_FILE_ENV] ?? null,
-		version: context.version ?? null,
-	});
+	// The psmux UX filter (mouse / set-clipboard / mode-style /
+	// set-window-option) now lives in buildGjcTmuxProfileCommands so every
+	// caller — gjc --tmux planning, gjc session create, gjc team bootstrap —
+	// applies the same drop set when the active multiplexer is psmux. We pass
+	// the resolved tmuxCommand through the new opts seam so the filter
+	// engages for this exact command, not whatever the resolver returns at
+	// profile-build time.
+	const commands = buildGjcTmuxProfileCommands(
+		context.target,
+		env,
+		{
+			branch: context.branch ?? null,
+			branchSlug,
+			project: context.project ?? null,
+			sessionId: context.sessionId ?? env[GJC_COORDINATOR_SESSION_ID_ENV] ?? null,
+			sessionStateFile: context.sessionStateFile ?? env[GJC_COORDINATOR_SESSION_STATE_FILE_ENV] ?? null,
+			version: context.version ?? null,
+		},
+		{ tmuxCommand: context.tmuxCommand },
+	);
 	if (commands.length === 0) return { skipped: true, commands: [], failures: [] };
 	const spawnSync = context.spawnSync ?? defaultSpawnSync;
 	const cwd = context.cwd ?? process.cwd();
@@ -280,8 +306,15 @@ function truncateVisibleTail(value: string, maxWidth: number): string {
 	return `…${result}`;
 }
 
+function sanitizeTmuxWindowProjectName(project: string): string {
+	const trimmed = project.trim();
+	if (!trimmed || /^\.+$/.test(trimmed)) return "gjc";
+	if (trimmed.startsWith(".")) return `dot-${trimmed.replace(/^\.+/, "")}`;
+	return trimmed;
+}
+
 export function buildGjcTmuxWindowTitle(cwd: string, branch: string | null | undefined): string {
-	const project = path.basename(path.resolve(cwd)) || "gjc";
+	const project = sanitizeTmuxWindowProjectName(path.basename(path.resolve(cwd)) || "gjc");
 	const trimmedBranch = branch?.trim();
 	if (!trimmedBranch) return truncateVisible(project, GJC_TMUX_WINDOW_LABEL_MAX_WIDTH);
 
@@ -315,8 +348,10 @@ function renameExistingTmuxWindowIfNeeded(context: TmuxLaunchContext): void {
 	if (!env.TMUX || env[GJC_TMUX_LAUNCHED_ENV] === "1") return;
 	if (parseLaunchPolicy(env) === "direct") return;
 
-	const platform = context.platform ?? process.platform;
-	if (platform === "win32") return;
+	// Note: Windows is intentionally allowed here. Psmux supports
+	// `rename-window` and we want the leader window to inherit the
+	// project:branch title even on native Windows, where gjc --tmux runs
+	// through PowerShell to a psmux backend.
 
 	const tty = context.tty ?? { stdin: Boolean(process.stdin.isTTY), stdout: Boolean(process.stdout.isTTY) };
 	if (!isInteractiveRootLaunch(context.parsed, tty)) return;
@@ -375,7 +410,12 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 	const branch = context.worktreeBranch ?? context.currentBranch ?? readCurrentBranch(cwd);
 	const project = context.project ?? cwd;
 	const sessionName = buildGjcTmuxSessionName(env, { branch });
-	const tmuxCommand = resolveGjcTmuxCommand(env);
+	// Pick the most appropriate tmux binary for this platform. On native Windows
+	// the resolver walks psmux / pmux / tmux and uses the first one present on
+	// PATH, so the default `gjc --tmux` flow lands on a real multiplexer even
+	// without an explicit GJC_TMUX_COMMAND override.
+	const resolvedBinary = resolveGjcTmuxBinary({ platform, env });
+	const tmuxCommand = resolvedBinary.command;
 	const sessionId = env[GJC_COORDINATOR_SESSION_ID_ENV]?.trim() || sessionName;
 	// The session ROOT is keyed by the active GJC session (GJC_SESSION_ID), NOT the
 	// coordinator/tmux identity. Fall back to the coordinator id only for standalone
@@ -385,7 +425,10 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 		env[GJC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim() ||
 		tmuxRuntimeSessionPath(cwd, gjcSessionId, buildGjcTmuxSessionSlug(sessionName));
 	const tmuxAvailable = context.tmuxAvailable ?? Bun.which(tmuxCommand) !== null;
-	if (!tmuxAvailable) return undefined;
+	if (!tmuxAvailable) {
+		(context.diagnosticWriter ?? safeStderrWrite)(formatTmuxUnavailableDiagnostic(platform, tmuxCommand));
+		return undefined;
+	}
 	const existingSessionName = allowsExistingTmuxAttach(context.parsed, env)
 		? "existingBranchSessionName" in context
 			? (context.existingBranchSessionName ?? undefined)
@@ -451,7 +494,7 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 
 	if (plan.attachSessionName) {
 		const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.attachSessionName}`], options);
-		return attached.exitCode === 0;
+		if (attached.exitCode === 0) return true;
 	}
 
 	const created = spawnSync(plan.tmuxCommand, plan.newSessionArgs, options);

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

@@ -0,0 +1,239 @@
+/**
+ * Windows psmux detection and tmux-binary resolution.
+ *
+ * Recent psmux releases (see docs/compatibility.md in the psmux repo) close
+ * the round-trip gap for set-option / show-options user options and the
+ * set-window-option profile values gjc emits, which is what unblocks the
+ * native Windows gjc --tmux path. This module detects that capability so gjc
+ * can pick psmux when tmux is missing on Windows, and so callers can decide
+ * whether to treat a given tmux binary as psmux (affecting e.g. the untagged
+ * diagnostic wording and namespace handling).
+ *
+ * The probe is intentionally lightweight: it runs a single tmux -V (or
+ * --version) once per process and caches the verdict. Cache invalidation
+ * knobs:
+ *   - force: true re-probes on every call (used by tests).
+ *   - GJC_PSMUX_FORCE_DETECT=1 re-probes each call.
+ *   - GJC_PSMUX_DETECTION=off skips probing entirely.
+ */
+
+export const GJC_PSMUX_COMMAND_ENV = "GJC_PSMUX_COMMAND";
+export const GJC_PSMUX_DETECTION_ENV = "GJC_PSMUX_DETECTION";
+export const GJC_PSMUX_FORCE_DETECT_ENV = "GJC_PSMUX_FORCE_DETECT";
+
+/** Names that psmux installs as the canonical executable / alias. */
+export const PSMUX_BINARY_NAMES = ["psmux", "pmux", "tmux"] as const;
+
+/** Substrings that uniquely identify psmux in version/help output. */
+const PSMUX_VERSION_MARKERS = ["psmux", "pmux"] as const;
+
+export type PsmuxSpawnRunner = (
+	command: string,
+	args: string[],
+) => { exitCode: number | null; stdout?: string; stderr?: string };
+
+/**
+ * Resolves a tmux-class binary name (e.g. "psmux", "tmux") to an absolute
+ * filesystem path or returns null when the binary cannot be located. The
+ * default implementation uses `Bun.which`; production callers leave it
+ * alone and unit tests inject a stub via `__setBinaryResolverForTests`
+ * so the version-banner probe can be exercised hermetically.
+ */
+export type BinaryResolver = (candidate: string) => string | null;
+
+const DEFAULT_BINARY_RESOLVER: BinaryResolver = candidate => {
+	if (!candidate) return null;
+	const stripped = candidate.trim().replace(/^["']|["']$/g, "");
+	if (!stripped) return null;
+	if (Bun.which(stripped)) return stripped;
+	return null;
+};
+
+let activeBinaryResolver: BinaryResolver = DEFAULT_BINARY_RESOLVER;
+
+/** @internal Test-only seam; production code never calls this. */
+export function __setBinaryResolverForTests(resolver: BinaryResolver | null): void {
+	activeBinaryResolver = resolver ?? DEFAULT_BINARY_RESOLVER;
+}
+
+interface CacheEntry {
+	command: string;
+	isPsmux: boolean;
+}
+
+const detectionCache = new Map<string, CacheEntry>();
+
+export function envDisabled(value: string | undefined): boolean {
+	const normalized = value?.trim().toLowerCase();
+	return normalized === "0" || normalized === "false" || normalized === "off" || normalized === "no";
+}
+
+/**
+ * GJC_PSMUX_FORCE_DETECT opt-in re-probe switch. Any non-empty value other
+ * than a "disabled" sentinel forces a fresh probe on every call. The unset
+ * (undefined) case must NOT force probing, otherwise the in-process cache
+ * never engages.
+ */
+function envForcesProbe(value: string | undefined): boolean {
+	if (value === undefined) return false;
+	if (envDisabled(value)) return false;
+	return value.trim().length > 0;
+}
+
+function readSpawnRunner(): PsmuxSpawnRunner {
+	return (command, args) => {
+		try {
+			const result = Bun.spawnSync({
+				cmd: [command, ...args],
+				stdout: "pipe",
+				stderr: "pipe",
+				env: process.env,
+			});
+			return {
+				exitCode: result.exitCode,
+				stdout: result.stdout.toString(),
+				stderr: result.stderr.toString(),
+			};
+		} catch {
+			return { exitCode: -1, stdout: "", stderr: "" };
+		}
+	};
+}
+
+function probeVersionOutput(command: string, runner: PsmuxSpawnRunner): string {
+	const flags = ["-V", "--version"];
+	for (const flag of flags) {
+		const result = runner(command, [flag]);
+		const text = `${result.stdout ?? ""}\n${result.stderr ?? ""}`.toLowerCase();
+		if (result.exitCode === 0 && text.trim().length > 0) return text;
+	}
+	return "";
+}
+
+function outputMentionsPsmux(output: string): boolean {
+	if (!output) return false;
+	return PSMUX_VERSION_MARKERS.some(marker => output.includes(marker));
+}
+
+function resolveBinaryPath(candidate: string): string | null {
+	return activeBinaryResolver(candidate);
+}
+
+function detectPsmuxForCommand(command: string, runner: PsmuxSpawnRunner): boolean {
+	const resolved = resolveBinaryPath(command);
+	if (!resolved) return false;
+	const output = probeVersionOutput(resolved, runner);
+	return outputMentionsPsmux(output);
+}
+
+/**
+ * Decide whether command resolves to a psmux binary by probing its version
+ * output. The result is cached per process unless force is set or
+ * GJC_PSMUX_FORCE_DETECT=1.
+ */
+export function detectPsmux(
+	command: string,
+	options: { force?: boolean; env?: NodeJS.ProcessEnv; runner?: PsmuxSpawnRunner } = {},
+): boolean {
+	const env = options.env ?? process.env;
+	const explicit = env[GJC_PSMUX_COMMAND_ENV]?.trim();
+	if (explicit) {
+		// The override is authoritative on its own — we trust the user's
+		// GJC_PSMUX_COMMAND value when they name a psmux-class binary, even
+		// when the binary cannot be located on PATH in the current process.
+		// This keeps the override usable from CI runners and from test
+		// environments where Bun.which would otherwise return null.
+		const normalized = explicit.toLowerCase();
+		if (
+			normalized === "psmux" ||
+			normalized === "pmux" ||
+			normalized.endsWith("/psmux") ||
+			normalized.endsWith("/pmux") ||
+			normalized.endsWith("\\psmux") ||
+			normalized.endsWith("\\pmux")
+		) {
+			return true;
+		}
+		const explicitPath = resolveBinaryPath(explicit);
+		if (explicitPath && explicitPath === resolveBinaryPath(command)) return true;
+	}
+	if (envDisabled(env[GJC_PSMUX_DETECTION_ENV])) return false;
+	const force = options.force === true || envForcesProbe(env[GJC_PSMUX_FORCE_DETECT_ENV]);
+	const useCache = !force && !options.force;
+	if (useCache) {
+		const cached = detectionCache.get(command);
+		if (cached) return cached.isPsmux;
+	}
+	const runner = options.runner ?? readSpawnRunner();
+	const isPsmux = detectPsmuxForCommand(command, runner);
+	if (useCache) detectionCache.set(command, { command, isPsmux });
+	return isPsmux;
+}
+
+export interface ResolveGjcTmuxBinaryOptions {
+	platform?: NodeJS.Platform;
+	env?: NodeJS.ProcessEnv;
+	runner?: PsmuxSpawnRunner;
+}
+
+export interface ResolvedTmuxBinary {
+	command: string;
+	isPsmux: boolean;
+	viaExplicitOverride: boolean;
+}
+
+/**
+ * Resolve the tmux command GJC should invoke. Honors the existing
+ * GJC_TMUX_COMMAND / GJC_TEAM_TMUX_COMMAND overrides; on Windows when no
+ * override is set, psmux (installed as psmux, pmux, or tmux) is picked
+ * automatically so the default gjc --tmux flow lands on a real multiplexer.
+ */
+export function resolveGjcTmuxBinary(options: ResolveGjcTmuxBinaryOptions = {}): ResolvedTmuxBinary {
+	const env = options.env ?? process.env;
+	const platform = options.platform ?? process.platform;
+	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 });
+		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 });
+				return { command: candidate, isPsmux, viaExplicitOverride: false };
+			}
+		}
+	}
+	const tmuxPath = resolveBinaryPath("tmux");
+	if (tmuxPath) {
+		const isPsmux = detectPsmux("tmux", { env, runner });
+		return { command: "tmux", isPsmux, viaExplicitOverride: false };
+	}
+	return { command: "tmux", isPsmux: false, viaExplicitOverride: false };
+}
+
+/** Test-only helper: drop the in-process detection cache. */
+export function clearPsmuxDetectionCache(): void {
+	detectionCache.clear();
+}
+
+export interface PsmuxProbe {
+	command: string;
+	versionOutput: string;
+	isPsmux: boolean;
+}
+
+export function probePsmux(
+	command: string,
+	options: { env?: NodeJS.ProcessEnv; runner?: PsmuxSpawnRunner; force?: boolean } = {},
+): PsmuxProbe {
+	const env = options.env ?? process.env;
+	const runner = options.runner ?? readSpawnRunner();
+	const resolved = resolveBinaryPath(command);
+	if (!resolved) return { command, versionOutput: "", isPsmux: false };
+	if (options.force) clearPsmuxDetectionCache();
+	const output = probeVersionOutput(resolved, runner);
+	const isPsmux = outputMentionsPsmux(output) || env[GJC_PSMUX_COMMAND_ENV]?.trim() === resolved;
+	return { command: resolved, versionOutput: output, isPsmux };
+}

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

@@ -5,7 +5,7 @@ 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";
 import type { GcPidProbe, GcRecord } from "./gc-runtime";
-import { applyGjcTmuxProfile, GJC_TMUX_LAUNCHED_ENV } from "./launch-tmux";
+import { applyGjcTmuxProfile } from "./launch-tmux";
 import { modeStatePath, sessionIdFromDirName, sessionReportsDir, teamStateRoot } from "./session-layout";
 import { resolveGjcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import {
@@ -595,6 +595,16 @@ function teamDir(stateRoot: string, teamName: string): string {
 function shellQuote(value: string): string {
 	return `'${value.replace(/'/g, "'\\''")}'`;
 }
+
+/**
+ * PowerShell-safe single-quote escape: doubles single quotes inside a
+ * single-quoted PowerShell literal ('it''s ok') and uses the same
+ * surrounding quotes. Used to build worker command strings that psmux
+ * will hand to a Windows ConPTY pane running PowerShell.
+ */
+function powershellQuote(value: string): string {
+	return `'${value.replace(/'/g, "''")}'`;
+}
 function safePathSegment(kind: string, value: string): string {
 	assertSafeId(kind, value);
 	return value;
@@ -1812,7 +1822,7 @@ async function ensureWorkerWorktree(
 
 function buildTeamTmuxLeaderRequirementMessage(detail?: string): string {
 	const suffix = detail?.trim() ? `:${detail.trim()}` : "";
-	return `gjc_team_requires_tmux_leader: run \`gjc --tmux\` first, then run \`gjc team ...\` inside that tmux-backed leader session, or use \`gjc team --dry-run\` for state-only smoke tests${suffix}`;
+	return `gjc_team_requires_tmux_leader: start a tmux session first (run \`gjc --tmux\`, or launch tmux yourself), then run \`gjc team ...\` inside it, or use \`gjc team --dry-run\` for state-only smoke tests${suffix}`;
 }
 function readGjcTmuxProfileValue(tmuxCommand: string, sessionName: string): string {
 	const result = Bun.spawnSync(
@@ -1826,7 +1836,7 @@ function readGjcTmuxProfileValue(tmuxCommand: string, sessionName: string): stri
 	return result.stdout.toString().trim();
 }
 
-function retagGjcLaunchedTmuxSession(tmuxCommand: string, sessionName: string): boolean {
+function tagTmuxSessionAsGjcLeader(tmuxCommand: string, sessionName: string): boolean {
 	const result = Bun.spawnSync(
 		[
 			tmuxCommand,
@@ -1845,25 +1855,39 @@ function retagGjcLaunchedTmuxSession(tmuxCommand: string, sessionName: string):
 }
 
 function readCurrentTmuxLeaderContext(tmuxCommand: string, env: NodeJS.ProcessEnv): GjcTmuxLeaderContext {
+	if (Bun.which(tmuxCommand) === null)
+		throw new Error(buildTeamTmuxLeaderRequirementMessage(`tmux_not_installed:${tmuxCommand}`));
 	const paneTarget = env.TMUX_PANE?.trim();
 	const args = paneTarget
 		? ["display-message", "-p", "-t", paneTarget, "#S:#I #{pane_id}"]
 		: ["display-message", "-p", "#S:#I #{pane_id}"];
 	const result = Bun.spawnSync([tmuxCommand, ...args], { stdout: "pipe", stderr: "pipe" });
-	if (result.exitCode !== 0) throw new Error(buildTeamTmuxLeaderRequirementMessage(result.stderr.toString()));
+	if (result.exitCode !== 0) {
+		// Distinguish "you are not inside any tmux session" from a genuine tmux
+		// query failure so the caller gets actionable guidance instead of raw
+		// tmux stderr. `gjc team` needs a tmux leader; outside tmux there is none.
+		const insideTmux = Boolean(env.TMUX?.trim() || env.TMUX_PANE?.trim());
+		const stderr = result.stderr.toString().trim();
+		throw new Error(
+			buildTeamTmuxLeaderRequirementMessage(
+				insideTmux ? `tmux_query_failed${stderr ? `:${stderr}` : ""}` : "not_inside_tmux",
+			),
+		);
+	}
 	const [sessionAndWindow = "", leaderPaneId = ""] = result.stdout.toString().trim().split(/\s+/);
 	const [sessionName = "", windowIndex = ""] = sessionAndWindow.split(":");
 	if (!sessionName || !windowIndex || !leaderPaneId.startsWith("%"))
 		throw new Error(buildTeamTmuxLeaderRequirementMessage(`invalid_tmux_context:${result.stdout.toString().trim()}`));
 	if (readGjcTmuxProfileValue(tmuxCommand, sessionName) !== GJC_TMUX_PROFILE_VALUE) {
-		// Self-heal: a pane launched through `gjc --tmux` exports
-		// GJC_TMUX_LAUNCHED=1, but the session can lose (or never receive) the
-		// @gjc-profile user-option tag when startup attach fails mid-way or the
-		// registry write races. That stranded-but-genuinely-GJC leader pane
-		// previously hard-failed as unmanaged_tmux_session; re-tag it instead.
-		const launchedByGjc = env[GJC_TMUX_LAUNCHED_ENV] === "1";
-		const retagged = launchedByGjc && retagGjcLaunchedTmuxSession(tmuxCommand, sessionName);
-		if (!retagged || readGjcTmuxProfileValue(tmuxCommand, sessionName) !== GJC_TMUX_PROFILE_VALUE)
+		// Adopt any real tmux leader as a GJC team leader — including a session
+		// the user created outside `gjc --tmux` — by writing GJC's @gjc-profile
+		// ownership tag and reading it back. A provider that round-trips tmux
+		// user options (real tmux) keeps the tag and is adopted; one that does
+		// not (e.g. psmux on Windows) drops it, so the readback still fails and
+		// the leader is rejected as unmanaged. This also self-heals a genuine
+		// `gjc --tmux` pane that lost its @gjc-profile tag mid-startup.
+		const tagged = tagTmuxSessionAsGjcLeader(tmuxCommand, sessionName);
+		if (!tagged || readGjcTmuxProfileValue(tmuxCommand, sessionName) !== GJC_TMUX_PROFILE_VALUE)
 			throw new Error(
 				buildTeamTmuxLeaderRequirementMessage(
 					`unmanaged_tmux_session:${sessionName} — ${buildGjcTmuxUntaggedSessionHint(tmuxCommand)}`,
@@ -1881,7 +1905,15 @@ export function resolveGjcWorkerCommand(cwd = process.cwd(), env: NodeJS.Process
 	if (entrypoint && path.basename(entrypoint).startsWith("gjc")) return shellQuote(path.resolve(cwd, entrypoint));
 	return "gjc";
 }
-function buildWorkerCommand(config: GjcTeamConfig, worker: GjcTeamWorker): string {
+/** @internal Exported for unit tests. */
+export function buildWorkerCommand(
+	config: GjcTeamConfig,
+	worker: GjcTeamWorker,
+	platform: NodeJS.Platform = process.platform,
+): string {
+	const quote = platform === "win32" ? powershellQuote : shellQuote;
+	const envAssignment = (key: string, value: string): string =>
+		platform === "win32" ? `$env:${key} = ${quote(value)};` : `${key}=${quote(value)}`;
 	const workspace = worker.worktree_path
 		? `Worker worktree: ${worker.worktree_path}.`
 		: `Worker cwd: ${config.leader.cwd}.`;
@@ -1894,17 +1926,18 @@ function buildWorkerCommand(config: GjcTeamConfig, worker: GjcTeamWorker): strin
 		`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 env = [
-		`GJC_TEAM_WORKER=${shellQuote(`${config.team_name}/${worker.id}`)}`,
-		`GJC_TEAM_INTERNAL_WORKER=${shellQuote(`${config.team_name}/${worker.id}`)}`,
-		`GJC_TEAM_NAME=${shellQuote(config.team_name)}`,
-		`GJC_TEAM_WORKER_ID=${shellQuote(worker.id)}`,
-		`GJC_TEAM_STATE_ROOT=${shellQuote(config.state_root)}`,
-		`GJC_TEAM_LEADER_CWD=${shellQuote(config.leader.cwd)}`,
-		`GJC_TEAM_DISPLAY_NAME=${shellQuote(config.display_name)}`,
-		...(worker.worktree_path ? [`GJC_TEAM_WORKTREE_PATH=${shellQuote(worker.worktree_path)}`] : []),
+	const envLines = [
+		envAssignment("GJC_TEAM_WORKER", `${config.team_name}/${worker.id}`),
+		envAssignment("GJC_TEAM_INTERNAL_WORKER", `${config.team_name}/${worker.id}`),
+		envAssignment("GJC_TEAM_NAME", config.team_name),
+		envAssignment("GJC_TEAM_WORKER_ID", worker.id),
+		envAssignment("GJC_TEAM_STATE_ROOT", config.state_root),
+		envAssignment("GJC_TEAM_LEADER_CWD", config.leader.cwd),
+		envAssignment("GJC_TEAM_DISPLAY_NAME", config.display_name),
+		...(worker.worktree_path ? [envAssignment("GJC_TEAM_WORKTREE_PATH", worker.worktree_path)] : []),
 	];
-	return `${env.join(" ")} ${config.worker_command} ${shellQuote(prompt)}`;
+	const joined = platform === "win32" ? envLines.join(" ") : envLines.join(" ");
+	return `${joined} ${config.worker_command} ${quote(prompt)}`;
 }
 interface GjcTeamInitialLane {
 	label: string;