@sayknow-cli/coding-agent 0.3.0 → 0.3.2

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

@@ -1,7 +1,7 @@
 import { Buffer } from "node:buffer";
 import * as path from "node:path";
-import { safeStderrWrite } from "@sayknow-cli/utils";
 import { VERSION } from "@sayknow-cli/utils/dirs";
+import { safeStderrWrite } from "@sayknow-cli/utils/safe-stderr";
 import type { Args } from "../cli/args";
 import { tmuxRuntimeSessionPath } from "./session-layout";
 import { SKC_COORDINATOR_SESSION_ID_ENV, SKC_COORDINATOR_SESSION_STATE_FILE_ENV } from "./session-state-sidecar";
@@ -9,6 +9,7 @@ import {
 	buildSkcTmuxProfileCommands,
 	buildSkcTmuxSessionName,
 	buildSkcTmuxSessionSlug,
+	resolveSkcTmuxBinary,
 	resolveSkcTmuxCommand,
 	SKC_DEFAULT_TMUX_SESSION,
 	SKC_TMUX_COMMAND_ENV,
@@ -31,6 +32,7 @@ export {
 export const SKC_TMUX_LAUNCHED_ENV = "SKC_TMUX_LAUNCHED";
 export const SKC_LAUNCH_POLICY_ENV = "SKC_LAUNCH_POLICY";
 export const SKC_TMUX_WINDOW_LABEL_MAX_WIDTH = 48;
+export const SKC_PSMUX_PROFILE_FORCE_ENV = "SKC_PSMUX_PROFILE_FORCE";
 
 type LaunchPolicy = "direct" | "tmux";
 
@@ -93,6 +95,10 @@ function hasCurrentSkcVersion(session: SkcTmuxSessionStatus | undefined): boolea
 	return session?.version === VERSION;
 }
 
+function allowsExistingTmuxAttach(parsed: Args, env: NodeJS.ProcessEnv): boolean {
+	return Boolean(parsed.continue || parsed.resume || explicitTmuxSessionName(env));
+}
+
 function findExistingSessionForLaunch(context: {
 	env: NodeJS.ProcessEnv;
 	project: string;
@@ -162,6 +168,18 @@ function formatTmuxLaunchDiagnostic(stage: string, stderr?: string): string {
 	return `skc --tmux failed after creating tmux session: ${stage}.${suffix}\n`;
 }
 
+function formatTmuxUnavailableDiagnostic(platform: NodeJS.Platform, tmuxCommand: string): string {
+	if (platform === "win32") {
+		return (
+			`skc --tmux requested but no tmux executable was found; starting without a tmux-backed session. ` +
+			`SKC 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 SKC at a specific binary via SKC_TMUX_COMMAND.\n"
+		);
+	}
+	return `skc --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, `'\\''`)}'`;
@@ -195,14 +213,26 @@ function buildWindowsPowerShellInnerCommand(context: CommandResolutionContext, r
 export function applySkcTmuxProfile(context: SkcTmuxProfileContext): SkcTmuxProfileResult {
 	const env = context.env ?? process.env;
 	const branchSlug = context.branch ? buildSkcTmuxSessionSlug(context.branch) : (context.branchSlug ?? null);
-	const commands = buildSkcTmuxProfileCommands(context.target, env, {
-		branch: context.branch ?? null,
-		branchSlug,
-		project: context.project ?? null,
-		sessionId: context.sessionId ?? env[SKC_COORDINATOR_SESSION_ID_ENV] ?? null,
-		sessionStateFile: context.sessionStateFile ?? env[SKC_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 buildSkcTmuxProfileCommands so every
+	// caller — skc --tmux planning, skc session create, skc 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 = buildSkcTmuxProfileCommands(
+		context.target,
+		env,
+		{
+			branch: context.branch ?? null,
+			branchSlug,
+			project: context.project ?? null,
+			sessionId: context.sessionId ?? env[SKC_COORDINATOR_SESSION_ID_ENV] ?? null,
+			sessionStateFile: context.sessionStateFile ?? env[SKC_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();
@@ -276,20 +306,33 @@ function truncateVisibleTail(value: string, maxWidth: number): string {
 	return `…${result}`;
 }
 
+const SKC_TMUX_WINDOW_BRANCH_SEPARATOR = "-";
+
+function sanitizeTmuxWindowTitleSegment(value: string): string {
+	return value.replace(/:+/g, "-");
+}
+
+function sanitizeTmuxWindowProjectName(project: string): string {
+	const trimmed = project.trim();
+	if (!trimmed || /^\.+$/.test(trimmed)) return "skc";
+	if (trimmed.startsWith(".")) return sanitizeTmuxWindowTitleSegment(`dot-${trimmed.replace(/^\.+/, "")}`);
+	return sanitizeTmuxWindowTitleSegment(trimmed);
+}
+
 export function buildSkcTmuxWindowTitle(cwd: string, branch: string | null | undefined): string {
-	const project = path.basename(path.resolve(cwd)) || "skc";
-	const trimmedBranch = branch?.trim();
+	const project = sanitizeTmuxWindowProjectName(path.basename(path.resolve(cwd)) || "skc");
+	const trimmedBranch = sanitizeTmuxWindowTitleSegment(branch?.trim() ?? "");
 	if (!trimmedBranch) return truncateVisible(project, SKC_TMUX_WINDOW_LABEL_MAX_WIDTH);
 
-	const separatorWidth = visibleWidth(":");
+	const separatorWidth = visibleWidth(SKC_TMUX_WINDOW_BRANCH_SEPARATOR);
 	const projectWidth = visibleWidth(project);
-	const fullTitle = `${project}:${trimmedBranch}`;
+	const fullTitle = `${project}${SKC_TMUX_WINDOW_BRANCH_SEPARATOR}${trimmedBranch}`;
 	if (visibleWidth(fullTitle) <= SKC_TMUX_WINDOW_LABEL_MAX_WIDTH) return fullTitle;
 
 	const remainingBranchWidth = SKC_TMUX_WINDOW_LABEL_MAX_WIDTH - projectWidth - separatorWidth;
 	if (remainingBranchWidth <= 0) return truncateVisible(project, SKC_TMUX_WINDOW_LABEL_MAX_WIDTH);
 
-	return `${project}:${truncateVisibleTail(trimmedBranch, remainingBranchWidth)}`;
+	return `${project}${SKC_TMUX_WINDOW_BRANCH_SEPARATOR}${truncateVisibleTail(trimmedBranch, remainingBranchWidth)}`;
 }
 
 function buildTmuxRenameWindowArgs(title: string, target?: string): string[] {
@@ -311,8 +354,10 @@ function renameExistingTmuxWindowIfNeeded(context: TmuxLaunchContext): void {
 	if (!env.TMUX || env[SKC_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
+	// sanitized project-branch title even on native Windows, where
+	// skc --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;
@@ -352,6 +397,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);
 }
+function isTmuxAttachDisconnectError(result: TmuxSpawnResult): boolean {
+	if (result.signalCode === "SIGHUP") return true;
+	const stderr = result.stderr?.toLowerCase() ?? "";
+	return stderr.includes("eio") || stderr.includes("input/output error");
+}
 
 export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaunchPlan | undefined {
 	const env = context.env ?? process.env;
@@ -366,7 +416,12 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 	const branch = context.worktreeBranch ?? context.currentBranch ?? readCurrentBranch(cwd);
 	const project = context.project ?? cwd;
 	const sessionName = buildSkcTmuxSessionName(env, { branch });
-	const tmuxCommand = resolveSkcTmuxCommand(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 `skc --tmux` flow lands on a real multiplexer even
+	// without an explicit SKC_TMUX_COMMAND override.
+	const resolvedBinary = resolveSkcTmuxBinary({ platform, env });
+	const tmuxCommand = resolvedBinary.command;
 	const sessionId = env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || sessionName;
 	// The session ROOT is keyed by the active SKC session (SKC_SESSION_ID), NOT the
 	// coordinator/tmux identity. Fall back to the coordinator id only for standalone
@@ -376,15 +431,19 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 		env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim() ||
 		tmuxRuntimeSessionPath(cwd, skcSessionId, buildSkcTmuxSessionSlug(sessionName));
 	const tmuxAvailable = context.tmuxAvailable ?? Bun.which(tmuxCommand) !== null;
-	if (!tmuxAvailable) return undefined;
-	const existingSessionName =
-		"existingBranchSessionName" in context
+	if (!tmuxAvailable) {
+		(context.diagnosticWriter ?? safeStderrWrite)(formatTmuxUnavailableDiagnostic(platform, tmuxCommand));
+		return undefined;
+	}
+	const existingSessionName = allowsExistingTmuxAttach(context.parsed, env)
+		? "existingBranchSessionName" in context
 			? (context.existingBranchSessionName ?? undefined)
 			: findExistingSessionForLaunch({
 					env,
 					project,
 					branch,
-				});
+				})
+		: undefined;
 	const innerCommand = buildInnerCommand(
 		{
 			cwd,
@@ -441,7 +500,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);
@@ -478,6 +537,10 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 	if (created.exitCode !== 0) return false;
 	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.sessionName}`], options);
 	if (attached.exitCode === 0) return true;
+	if (isTmuxAttachDisconnectError(attached)) {
+		(context.diagnosticWriter ?? safeStderrWrite)(formatTmuxLaunchDiagnostic("attach disconnected", attached.stderr));
+		return true;
+	}
 	cleanupCreatedTmuxSession(plan, spawnSync, options);
 	(context.diagnosticWriter ?? safeStderrWrite)(formatTmuxLaunchDiagnostic("attach failed", attached.stderr));
 	return true;

package/src/skc-runtime/ledger-event-renderer.ts

@@ -93,6 +93,7 @@ const RALPLAN_STAGE_CODES: Record<string, string> = {
 	architect: "A",
 	critic: "C",
 	adr: "D",
+	"post-interview": "I",
 	final: "F",
 };
 

package/src/skc-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 skc emits, which is what unblocks the
+ * native Windows skc --tmux path. This module detects that capability so skc
+ * 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).
+ *   - SKC_PSMUX_FORCE_DETECT=1 re-probes each call.
+ *   - SKC_PSMUX_DETECTION=off skips probing entirely.
+ */
+
+export const SKC_PSMUX_COMMAND_ENV = "SKC_PSMUX_COMMAND";
+export const SKC_PSMUX_DETECTION_ENV = "SKC_PSMUX_DETECTION";
+export const SKC_PSMUX_FORCE_DETECT_ENV = "SKC_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";
+}
+
+/**
+ * SKC_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
+ * SKC_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[SKC_PSMUX_COMMAND_ENV]?.trim();
+	if (explicit) {
+		// The override is authoritative on its own — we trust the user's
+		// SKC_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[SKC_PSMUX_DETECTION_ENV])) return false;
+	const force = options.force === true || envForcesProbe(env[SKC_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 ResolveSkcTmuxBinaryOptions {
+	platform?: NodeJS.Platform;
+	env?: NodeJS.ProcessEnv;
+	runner?: PsmuxSpawnRunner;
+}
+
+export interface ResolvedTmuxBinary {
+	command: string;
+	isPsmux: boolean;
+	viaExplicitOverride: boolean;
+}
+
+/**
+ * Resolve the tmux command SKC should invoke. Honors the existing
+ * SKC_TMUX_COMMAND / SKC_TEAM_TMUX_COMMAND overrides; on Windows when no
+ * override is set, psmux (installed as psmux, pmux, or tmux) is picked
+ * automatically so the default skc --tmux flow lands on a real multiplexer.
+ */
+export function resolveSkcTmuxBinary(options: ResolveSkcTmuxBinaryOptions = {}): ResolvedTmuxBinary {
+	const env = options.env ?? process.env;
+	const platform = options.platform ?? process.platform;
+	const runner = options.runner ?? readSpawnRunner();
+	const explicit = env.SKC_TMUX_COMMAND?.trim() || env.SKC_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[SKC_PSMUX_COMMAND_ENV]?.trim() === resolved;
+	return { command: resolved, versionOutput: output, isPsmux };
+}

package/src/skc-runtime/ralplan-runtime.ts

@@ -37,7 +37,7 @@ import {
  *
  * 2. **Artifact write**: `skc ralplan --write --stage <type> --stage_n <N> --artifact
  *    <path-or-string> [--run-id <id>] [--session-id <id>] [--json]` persists Planner / Architect
- *    / Critic / revision / ADR / final markdown under `.skc/plans/ralplan/<run-id>/`, maintains
+ *    / Critic / revision / post-interview / ADR / final markdown under `.skc/plans/ralplan/<run-id>/`, maintains
  *    an `index.jsonl` audit log, copies `final` stages to `pending-approval.md`, and advances
  *    the HUD chip to reflect the latest persisted stage.
  */
@@ -48,7 +48,7 @@ export interface RalplanCommandResult {
 	stderr?: string;
 }
 
-const KNOWN_STAGES = ["planner", "architect", "critic", "revision", "adr", "final"] as const;
+const KNOWN_STAGES = ["planner", "architect", "critic", "revision", "post-interview", "adr", "final"] as const;
 type RalplanStage = (typeof KNOWN_STAGES)[number];
 
 const KNOWN_ARCHITECT_KINDS = new Set(["openai-code"]);

package/src/skc-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 { applySkcTmuxProfile, SKC_TMUX_LAUNCHED_ENV } from "./launch-tmux";
+import { applySkcTmuxProfile } from "./launch-tmux";
 import { modeStatePath, sessionIdFromDirName, sessionReportsDir, teamStateRoot } from "./session-layout";
 import { resolveSkcSessionForWrite, 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 `skc_team_requires_tmux_leader: run \`skc --tmux\` first, then run \`skc team ...\` inside that tmux-backed leader session, or use \`skc team --dry-run\` for state-only smoke tests${suffix}`;
+	return `skc_team_requires_tmux_leader: start a tmux session first (run \`skc --tmux\`, or launch tmux yourself), then run \`skc team ...\` inside it, or use \`skc team --dry-run\` for state-only smoke tests${suffix}`;
 }
 function readSkcTmuxProfileValue(tmuxCommand: string, sessionName: string): string {
 	const result = Bun.spawnSync(
@@ -1826,7 +1836,7 @@ function readSkcTmuxProfileValue(tmuxCommand: string, sessionName: string): stri
 	return result.stdout.toString().trim();
 }
 
-function retagSkcLaunchedTmuxSession(tmuxCommand: string, sessionName: string): boolean {
+function tagTmuxSessionAsSkcLeader(tmuxCommand: string, sessionName: string): boolean {
 	const result = Bun.spawnSync(
 		[
 			tmuxCommand,
@@ -1845,25 +1855,39 @@ function retagSkcLaunchedTmuxSession(tmuxCommand: string, sessionName: string):
 }
 
 function readCurrentTmuxLeaderContext(tmuxCommand: string, env: NodeJS.ProcessEnv): SkcTmuxLeaderContext {
+	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. `skc 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 (readSkcTmuxProfileValue(tmuxCommand, sessionName) !== SKC_TMUX_PROFILE_VALUE) {
-		// Self-heal: a pane launched through `skc --tmux` exports
-		// SKC_TMUX_LAUNCHED=1, but the session can lose (or never receive) the
-		// @skc-profile user-option tag when startup attach fails mid-way or the
-		// registry write races. That stranded-but-genuinely-SKC leader pane
-		// previously hard-failed as unmanaged_tmux_session; re-tag it instead.
-		const launchedBySkc = env[SKC_TMUX_LAUNCHED_ENV] === "1";
-		const retagged = launchedBySkc && retagSkcLaunchedTmuxSession(tmuxCommand, sessionName);
-		if (!retagged || readSkcTmuxProfileValue(tmuxCommand, sessionName) !== SKC_TMUX_PROFILE_VALUE)
+		// Adopt any real tmux leader as a SKC team leader — including a session
+		// the user created outside `skc --tmux` — by writing SKC's @skc-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
+		// `skc --tmux` pane that lost its @skc-profile tag mid-startup.
+		const tagged = tagTmuxSessionAsSkcLeader(tmuxCommand, sessionName);
+		if (!tagged || readSkcTmuxProfileValue(tmuxCommand, sessionName) !== SKC_TMUX_PROFILE_VALUE)
 			throw new Error(
 				buildTeamTmuxLeaderRequirementMessage(
 					`unmanaged_tmux_session:${sessionName} — ${buildSkcTmuxUntaggedSessionHint(tmuxCommand)}`,
@@ -1881,7 +1905,15 @@ export function resolveSkcWorkerCommand(cwd = process.cwd(), env: NodeJS.Process
 	if (entrypoint && path.basename(entrypoint).startsWith("skc")) return shellQuote(path.resolve(cwd, entrypoint));
 	return "skc";
 }
-function buildWorkerCommand(config: SkcTeamConfig, worker: SkcTeamWorker): string {
+/** @internal Exported for unit tests. */
+export function buildWorkerCommand(
+	config: SkcTeamConfig,
+	worker: SkcTeamWorker,
+	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: SkcTeamConfig, worker: SkcTeamWorker): strin
 		`Before claiming work, send startup ACK: skc team api worker-startup-ack --input '{"team_name":"${config.team_name}","worker_id":"${worker.id}","protocol_version":"1"}' --json.`,
 		`Use skc 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 = [
-		`SKC_TEAM_WORKER=${shellQuote(`${config.team_name}/${worker.id}`)}`,
-		`SKC_TEAM_INTERNAL_WORKER=${shellQuote(`${config.team_name}/${worker.id}`)}`,
-		`SKC_TEAM_NAME=${shellQuote(config.team_name)}`,
-		`SKC_TEAM_WORKER_ID=${shellQuote(worker.id)}`,
-		`SKC_TEAM_STATE_ROOT=${shellQuote(config.state_root)}`,
-		`SKC_TEAM_LEADER_CWD=${shellQuote(config.leader.cwd)}`,
-		`SKC_TEAM_DISPLAY_NAME=${shellQuote(config.display_name)}`,
-		...(worker.worktree_path ? [`SKC_TEAM_WORKTREE_PATH=${shellQuote(worker.worktree_path)}`] : []),
+	const envLines = [
+		envAssignment("SKC_TEAM_WORKER", `${config.team_name}/${worker.id}`),
+		envAssignment("SKC_TEAM_INTERNAL_WORKER", `${config.team_name}/${worker.id}`),
+		envAssignment("SKC_TEAM_NAME", config.team_name),
+		envAssignment("SKC_TEAM_WORKER_ID", worker.id),
+		envAssignment("SKC_TEAM_STATE_ROOT", config.state_root),
+		envAssignment("SKC_TEAM_LEADER_CWD", config.leader.cwd),
+		envAssignment("SKC_TEAM_DISPLAY_NAME", config.display_name),
+		...(worker.worktree_path ? [envAssignment("SKC_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 SkcTeamInitialLane {
 	label: string;