@sayknow-cli/coding-agent 0.2.3 → 0.2.5

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

@@ -1,6 +1,8 @@
+import { Buffer } from "node:buffer";
 import * as path from "node:path";
 import { safeStderrWrite } from "@sayknow-cli/utils";
 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";
 import {
 	buildSkcTmuxProfileCommands,
@@ -14,7 +16,7 @@ import {
 	SKC_TMUX_SESSION_PREFIX,
 	type SkcTmuxProfileCommand,
 } from "./tmux-common";
-import { findSkcTmuxSessionByBranch } from "./tmux-sessions";
+import { findSkcTmuxSessionByName, findSkcTmuxSessionByScope } from "./tmux-sessions";
 
 export {
 	buildSkcTmuxProfileCommands,
@@ -83,6 +85,20 @@ export interface TmuxLaunchPlan {
 	sessionStateFile?: string | null;
 }
 
+function explicitTmuxSessionName(env: NodeJS.ProcessEnv): string | undefined {
+	return env.SKC_TMUX_SESSION?.trim() || undefined;
+}
+
+function findExistingSessionForLaunch(context: {
+	env: NodeJS.ProcessEnv;
+	project: string;
+	branch?: string | null;
+}): string | undefined {
+	const explicit = explicitTmuxSessionName(context.env);
+	if (explicit) return findSkcTmuxSessionByName(explicit, context.env)?.name;
+	return findSkcTmuxSessionByScope(context.project, context.branch, context.env)?.name;
+}
+
 export interface SkcTmuxProfileResult {
 	skipped: boolean;
 	commands: SkcTmuxProfileCommand[];
@@ -107,6 +123,7 @@ interface CommandResolutionContext {
 	argv: string[];
 	execPath: string;
 	extraEnv?: Record<string, string>;
+	platform?: NodeJS.Platform;
 }
 
 function parseLaunchPolicy(env: NodeJS.ProcessEnv): LaunchPolicy {
@@ -148,6 +165,26 @@ function buildEnvAssignments(values: Record<string, string> | undefined): string
 	const entries = Object.entries(values ?? {});
 	return entries.length === 0 ? "" : ` ${entries.map(([key, value]) => `${key}=${shellQuote(value)}`).join(" ")}`;
 }
+function powershellQuote(value: string): string {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function stripRootTmuxFlag(rawArgs: string[]): string[] {
+	return rawArgs.filter(arg => arg !== "--tmux");
+}
+
+function buildWindowsPowerShellInnerCommand(context: CommandResolutionContext, rawArgs: string[]): string {
+	const command = resolveCurrentSkcCommand(context);
+	const envLines = Object.entries({ [SKC_TMUX_LAUNCHED_ENV]: "1", ...(context.extraEnv ?? {}) }).map(
+		([key, value]) => `$env:${key} = ${powershellQuote(value)}`,
+	);
+	const invocation = ["&", ...command.map(powershellQuote), ...stripRootTmuxFlag(rawArgs).map(powershellQuote)].join(
+		" ",
+	);
+	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");
+	return `pwsh -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encodedCommand}`;
+}
 
 export function applySkcTmuxProfile(context: SkcTmuxProfileContext): SkcTmuxProfileResult {
 	const env = context.env ?? process.env;
@@ -177,16 +214,26 @@ function resolveCurrentSkcCommand(context: CommandResolutionContext): string[] {
 	if (isBunVirtualPath(entrypoint)) {
 		return isBunVirtualPath(context.execPath) ? ["skc"] : [context.execPath];
 	}
-	const resolvedEntrypoint = path.isAbsolute(entrypoint) ? entrypoint : path.resolve(context.cwd, entrypoint);
+	const pathModule = pathModuleForPlatform(context.platform);
+	const resolvedEntrypoint = pathModule.isAbsolute(entrypoint)
+		? entrypoint
+		: pathModule.resolve(context.cwd, entrypoint);
 	if (entrypoint.endsWith(".ts") || entrypoint.endsWith(".js") || entrypoint.endsWith(".mjs")) {
 		return [context.execPath, resolvedEntrypoint];
 	}
 	return [resolvedEntrypoint];
 }
+function isWindowsPlatform(platform: NodeJS.Platform | undefined): boolean {
+	return platform === "win32";
+}
+function pathModuleForPlatform(platform: NodeJS.Platform | undefined): typeof path.win32 | typeof path {
+	return isWindowsPlatform(platform) ? path.win32 : path;
+}
 
 function buildInnerCommand(context: CommandResolutionContext, rawArgs: string[]): string {
+	if (isWindowsPlatform(context.platform)) return buildWindowsPowerShellInnerCommand(context, rawArgs);
 	const command = resolveCurrentSkcCommand(context);
-	const quoted = [...command, ...rawArgs].map(shellQuote).join(" ");
+	const quoted = [...command, ...stripRootTmuxFlag(rawArgs)].map(shellQuote).join(" ");
 	return `exec env ${SKC_TMUX_LAUNCHED_ENV}=1${buildEnvAssignments(context.extraEnv)} ${quoted}`;
 }
 
@@ -305,7 +352,6 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 	if (!context.parsed.tmux || policy === "direct") return undefined;
 	if (env.TMUX || env[SKC_TMUX_LAUNCHED_ENV] === "1") return undefined;
 	const platform = context.platform ?? process.platform;
-	if (platform === "win32") return undefined;
 	const tty = context.tty ?? { stdin: Boolean(process.stdin.isTTY), stdout: Boolean(process.stdout.isTTY) };
 	if (policy === "tmux" && !isInteractiveRootLaunch(context.parsed, tty)) return undefined;
 
@@ -315,17 +361,23 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 	const sessionName = buildSkcTmuxSessionName(env, { branch });
 	const tmuxCommand = resolveSkcTmuxCommand(env);
 	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
+	// tmux launches with no SKC session context.
+	const skcSessionId = env.SKC_SESSION_ID?.trim() || sessionId;
 	const sessionStateFile =
 		env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim() ||
-		path.join(cwd, ".skc", "runtime", "tmux-sessions", `${buildSkcTmuxSessionSlug(sessionName)}.json`);
+		tmuxRuntimeSessionPath(cwd, skcSessionId, buildSkcTmuxSessionSlug(sessionName));
 	const tmuxAvailable = context.tmuxAvailable ?? Bun.which(tmuxCommand) !== null;
 	if (!tmuxAvailable) return undefined;
-	const existingBranchSessionName =
+	const existingSessionName =
 		"existingBranchSessionName" in context
 			? (context.existingBranchSessionName ?? undefined)
-			: context.worktreeBranch
-				? findSkcTmuxSessionByBranch(context.worktreeBranch, env, project)?.name
-				: undefined;
+			: findExistingSessionForLaunch({
+					env,
+					project,
+					branch,
+				});
 	const innerCommand = buildInnerCommand(
 		{
 			cwd,
@@ -335,6 +387,7 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 				[SKC_COORDINATOR_SESSION_ID_ENV]: sessionId,
 				[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]: sessionStateFile,
 			},
+			platform,
 		},
 		context.rawArgs,
 	);
@@ -348,7 +401,7 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 		project,
 		sessionId,
 		sessionStateFile,
-		attachSessionName: existingBranchSessionName,
+		attachSessionName: existingSessionName,
 	};
 }
 
@@ -405,19 +458,19 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 			sessionId: plan.sessionId ?? null,
 			sessionStateFile: plan.sessionStateFile ?? null,
 		});
-		if (profile.failures.length > 0) {
+		const ownershipFailure = profile.failures.find(item => item.command.args.includes("@skc-profile"));
+		if (ownershipFailure) {
 			cleanupCreatedTmuxSession(plan, spawnSync, options);
-			const failure =
-				profile.failures.find(item => item.command.args.includes("@skc-profile")) ?? profile.failures[0];
 			(context.diagnosticWriter ?? safeStderrWrite)(
-				formatTmuxLaunchDiagnostic("profile tagging failed", failure?.stderr),
+				formatTmuxLaunchDiagnostic("profile tagging failed", ownershipFailure.stderr),
 			);
 			return true;
 		}
 	}
 	if (created.exitCode !== 0) return false;
-	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", plan.sessionName], options);
+	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.sessionName}`], options);
 	if (attached.exitCode === 0) return true;
+	cleanupCreatedTmuxSession(plan, spawnSync, options);
 	(context.diagnosticWriter ?? safeStderrWrite)(formatTmuxLaunchDiagnostic("attach failed", attached.stderr));
 	return true;
 }

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

@@ -12,6 +12,8 @@ import {
 	summarizeRalplanIndex,
 } from "./ledger-event-renderer";
 import { isRestrictedRoleAgentBash } from "./restricted-role-agent-bash";
+import { modeStatePath, sessionPlansDir } from "./session-layout";
+import { resolveSkcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import { migrateWorkflowState } from "./state-migrations";
 import { runNativeStateCommand } from "./state-runtime";
 import {
@@ -169,18 +171,15 @@ interface ResolvedArtifactArgs {
 	stageN: number;
 	runId: string;
 	artifact: string;
-	sessionId: string | undefined;
+	sessionId: string;
 	json: boolean;
 }
 
-function ralplanStatePath(cwd: string, sessionId: string | undefined): string {
-	const stateDir = sessionId
-		? path.join(cwd, ".skc", "state", "sessions", encodeSessionSegment(sessionId))
-		: path.join(cwd, ".skc", "state");
-	return path.join(stateDir, "ralplan-state.json");
+function ralplanStatePath(cwd: string, sessionId: string): string {
+	return modeStatePath(cwd, sessionId, "ralplan");
 }
 
-async function readActiveRunId(cwd: string, sessionId: string | undefined): Promise<string | undefined> {
+async function readActiveRunId(cwd: string, sessionId: string): Promise<string | undefined> {
 	const statePath = ralplanStatePath(cwd, sessionId);
 	const existingRead = await readExistingStateForMutation(statePath);
 	if (existingRead.kind === "absent") return undefined;
@@ -221,12 +220,7 @@ function advanceCurrentPhase(existingPhase: unknown, stage: RalplanStage): strin
 	return stage;
 }
 
-async function persistActiveRunId(
-	cwd: string,
-	sessionId: string | undefined,
-	runId: string,
-	stage: RalplanStage,
-): Promise<void> {
+async function persistActiveRunId(cwd: string, sessionId: string, runId: string, stage: RalplanStage): Promise<void> {
 	const statePath = ralplanStatePath(cwd, sessionId);
 	const existingRead = await readExistingStateForMutation(statePath);
 	if (existingRead.kind === "corrupt") {
@@ -261,7 +255,7 @@ async function persistActiveRunId(
 	await writeWorkflowEnvelopeAtomic(statePath, existing, {
 		cwd,
 		receipt: { cwd, skill: "ralplan", owner: "skc-runtime", command: "skc ralplan persist-run-id", sessionId },
-		audit: { category: "state", verb: "write", owner: "skc-runtime", skill: "ralplan" },
+		audit: { category: "state", verb: "write", owner: "skc-runtime", skill: "ralplan", sessionId },
 	});
 }
 
@@ -384,11 +378,7 @@ function plannerStatePayload(update: PlannerStateUpdate): Record<string, unknown
  * audit/routing hint only — it records what the caller has already proven and is
  * NOT a durable cross-process subagent registry.
  */
-async function applyPlannerStateUpdate(
-	cwd: string,
-	sessionId: string | undefined,
-	update: PlannerStateUpdate,
-): Promise<void> {
+async function applyPlannerStateUpdate(cwd: string, sessionId: string, update: PlannerStateUpdate): Promise<void> {
 	const statePath = ralplanStatePath(cwd, sessionId);
 	const existingRead = await readExistingStateForMutation(statePath);
 	if (existingRead.kind === "corrupt") {
@@ -407,7 +397,7 @@ async function applyPlannerStateUpdate(
 	await writeWorkflowEnvelopeAtomic(statePath, existing, {
 		cwd,
 		receipt: { cwd, skill: "ralplan", owner: "skc-runtime", command: "skc ralplan planner-state", sessionId },
-		audit: { category: "state", verb: "write", owner: "skc-runtime", skill: "ralplan" },
+		audit: { category: "state", verb: "write", owner: "skc-runtime", skill: "ralplan", sessionId },
 	});
 }
 
@@ -423,9 +413,13 @@ async function resolveArtifactArgs(args: readonly string[], cwd: string): Promis
 		throw new RalplanCommandError(2, "--artifact is required for ralplan --write");
 	}
 
-	const sessionIdRaw = flagValue(args, "--session-id")?.trim();
-	const sessionId = sessionIdRaw || undefined;
-	if (sessionId) assertSafePathComponent(sessionId, "session-id");
+	const session = resolveSkcSessionForWrite(cwd, {
+		flagValue: flagValue(args, "--session-id"),
+		envSessionId: process.env.SKC_SESSION_ID,
+	});
+	const sessionId = session.skcSessionId;
+	assertSafePathComponent(sessionId, "session-id");
+	const sessionIdRaw = sessionId;
 
 	// Precedence for run_id:
 	//   1. explicit --run-id flag
@@ -469,13 +463,19 @@ async function persistArtifact(
 	content: string,
 	sha256: string,
 ): Promise<PersistedArtifact> {
-	const runDir = path.join(cwd, ".skc", "plans", "ralplan", resolved.runId);
+	const runDir = path.join(sessionPlansDir(cwd, resolved.sessionId), "ralplan", resolved.runId);
 
 	const fileName = `stage-${pad2(resolved.stageN)}-${resolved.stage}.md`;
 	const filePath = path.join(runDir, fileName);
 	await writeArtifact(filePath, content, {
 		cwd,
-		audit: { category: "artifact", verb: "write", owner: "skc-runtime", skill: "ralplan" },
+		audit: {
+			category: "artifact",
+			verb: "write",
+			owner: "skc-runtime",
+			skill: "ralplan",
+			sessionId: resolved.sessionId,
+		},
 	});
 
 	const createdAt = new Date().toISOString();
@@ -488,7 +488,13 @@ async function persistArtifact(
 	};
 	await appendJsonlIdempotent(path.join(runDir, "index.jsonl"), indexEntry, {
 		cwd,
-		audit: { category: "ledger", verb: "append", owner: "skc-runtime", skill: "ralplan" },
+		audit: {
+			category: "ledger",
+			verb: "append",
+			owner: "skc-runtime",
+			skill: "ralplan",
+			sessionId: resolved.sessionId,
+		},
 		key: ralplanIndexKey,
 	});
 
@@ -497,7 +503,13 @@ async function persistArtifact(
 		pendingApprovalPath = path.join(runDir, "pending-approval.md");
 		await writeArtifact(pendingApprovalPath, content, {
 			cwd,
-			audit: { category: "artifact", verb: "write", owner: "skc-runtime", skill: "ralplan" },
+			audit: {
+				category: "artifact",
+				verb: "write",
+				owner: "skc-runtime",
+				skill: "ralplan",
+				sessionId: resolved.sessionId,
+			},
 		});
 	}
 
@@ -528,11 +540,12 @@ interface ExistingStageArtifact {
  */
 async function findExistingStageArtifact(
 	cwd: string,
+	sessionId: string,
 	runId: string,
 	stage: RalplanStage,
 	stageN: number,
 ): Promise<ExistingStageArtifact | undefined> {
-	const indexPath = path.join(cwd, ".skc", "plans", "ralplan", runId, "index.jsonl");
+	const indexPath = path.join(sessionPlansDir(cwd, sessionId), "ralplan", runId, "index.jsonl");
 	let text: string;
 	try {
 		text = await fs.readFile(indexPath, "utf8");
@@ -566,9 +579,9 @@ async function findExistingStageArtifact(
  * Read and parse the run's `index.jsonl` rows. Best-effort: returns [] when the
  * file is absent or unreadable so HUD sync never fails on a missing index.
  */
-async function readRalplanIndexRows(cwd: string, runId: string): Promise<RalplanIndexRow[]> {
+async function readRalplanIndexRows(cwd: string, sessionId: string, runId: string): Promise<RalplanIndexRow[]> {
 	try {
-		const indexPath = path.join(cwd, ".skc", "plans", "ralplan", runId, "index.jsonl");
+		const indexPath = path.join(sessionPlansDir(cwd, sessionId), "ralplan", runId, "index.jsonl");
 		const text = await fs.readFile(indexPath, "utf8");
 		const rows: RalplanIndexRow[] = [];
 		for (const line of text.split(/\r?\n/)) {
@@ -583,7 +596,7 @@ async function readRalplanIndexRows(cwd: string, runId: string): Promise<Ralplan
 
 async function syncRalplanHud(options: {
 	cwd: string;
-	sessionId?: string;
+	sessionId: string;
 	stage: string;
 	pendingApproval: boolean;
 	iteration?: number;
@@ -612,11 +625,12 @@ async function buildRalplanHud(options: {
 	iteration?: number;
 	latestSummary?: string;
 	runId?: string;
+	sessionId?: string;
 }) {
 	let iterationFromIndex: number | undefined;
 	let stages: string | undefined;
-	if (options.runId) {
-		const rows = await readRalplanIndexRows(options.cwd, options.runId);
+	if (options.runId && options.sessionId) {
+		const rows = await readRalplanIndexRows(options.cwd, options.sessionId, options.runId);
 		if (rows.length > 0) {
 			const summary = summarizeRalplanIndex(rows);
 			iterationFromIndex = summary.iteration;
@@ -643,7 +657,13 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 	// Duplicate-write guard: a second `--write` for the same (stage, stage_n) must not
 	// silently clobber the artifact or append a duplicate ledger row. Classify before any
 	// state mutation so a conflict never regresses run-state phase.
-	const existingArtifact = await findExistingStageArtifact(cwd, resolved.runId, resolved.stage, resolved.stageN);
+	const existingArtifact = await findExistingStageArtifact(
+		cwd,
+		resolved.sessionId,
+		resolved.runId,
+		resolved.stage,
+		resolved.stageN,
+	);
 	if (existingArtifact) {
 		if (existingArtifact.sha256 !== sha256) {
 			throw new RalplanCommandError(
@@ -660,6 +680,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 	if (plannerState) {
 		await applyPlannerStateUpdate(cwd, resolved.sessionId, plannerState);
 	}
+	await writeSessionActivityMarker(cwd, resolved.sessionId, { writer: "ralplan-runtime", path: persisted.path });
 	await syncRalplanHud({
 		cwd,
 		sessionId: resolved.sessionId,
@@ -706,7 +727,12 @@ function buildDeduplicatedResult(
 		deduplicated: true,
 	};
 	if (resolved.stage === "final") {
-		payload.pending_approval_path = path.join(cwd, ".skc", "plans", "ralplan", resolved.runId, "pending-approval.md");
+		payload.pending_approval_path = path.join(
+			sessionPlansDir(cwd, resolved.sessionId),
+			"ralplan",
+			resolved.runId,
+			"pending-approval.md",
+		);
 	}
 	const stdout = resolved.json
 		? `${JSON.stringify(payload, null, 2)}\n`
@@ -721,7 +747,7 @@ interface ConsensusHandoffArgs {
 	deliberate: boolean;
 	architectKind?: string;
 	criticKind?: string;
-	sessionId?: string;
+	sessionId: string;
 	task: string;
 	json: boolean;
 }
@@ -747,7 +773,7 @@ function extractPositionalTask(args: readonly string[]): string {
 	return parts.join(" ").trim();
 }
 
-function resolveConsensusArgs(args: readonly string[]): ConsensusHandoffArgs {
+function resolveConsensusArgs(args: readonly string[], cwd: string): ConsensusHandoffArgs {
 	const architectKind = flagValue(args, "--architect")?.trim() || undefined;
 	if (architectKind && !KNOWN_ARCHITECT_KINDS.has(architectKind)) {
 		throw new RalplanCommandError(
@@ -762,8 +788,12 @@ function resolveConsensusArgs(args: readonly string[]): ConsensusHandoffArgs {
 			`unknown --critic kind: ${criticKind}. Expected one of: ${[...KNOWN_CRITIC_KINDS].join(", ")}.`,
 		);
 	}
-	const sessionId = flagValue(args, "--session-id")?.trim() || undefined;
-	if (sessionId) assertSafePathComponent(sessionId, "session-id");
+	const session = resolveSkcSessionForWrite(cwd, {
+		flagValue: flagValue(args, "--session-id"),
+		envSessionId: process.env.SKC_SESSION_ID,
+	});
+	const sessionId = session.skcSessionId;
+	assertSafePathComponent(sessionId, "session-id");
 	const task = extractPositionalTask(args);
 	return {
 		interactive: hasFlag(args, "--interactive"),
@@ -776,19 +806,11 @@ function resolveConsensusArgs(args: readonly string[]): ConsensusHandoffArgs {
 	};
 }
 
-function encodeSessionSegment(value: string): string {
-	return encodeURIComponent(value).replaceAll(".", "%2E");
-}
-
 async function seedRalplanState(
 	cwd: string,
 	resolved: ConsensusHandoffArgs,
 ): Promise<{ statePath: string; runId: string }> {
-	const stateDir = resolved.sessionId
-		? path.join(cwd, ".skc", "state", "sessions", encodeSessionSegment(resolved.sessionId))
-		: path.join(cwd, ".skc", "state");
-
-	const statePath = path.join(stateDir, "ralplan-state.json");
+	const statePath = ralplanStatePath(cwd, resolved.sessionId);
 	// Reuse an existing run id when present so a re-invocation of `skc ralplan "task"` doesn't
 	// orphan in-progress artifacts under a fresh run id.
 	const existingRunId = await readActiveRunId(cwd, resolved.sessionId);
@@ -818,13 +840,20 @@ async function seedRalplanState(
 			command: "skc ralplan seed",
 			sessionId: resolved.sessionId,
 		},
-		audit: { category: "state", verb: "write", owner: "skc-runtime", skill: "ralplan" },
+		audit: {
+			category: "state",
+			verb: "write",
+			owner: "skc-runtime",
+			skill: "ralplan",
+			sessionId: resolved.sessionId,
+		},
 	});
+	await writeSessionActivityMarker(cwd, resolved.sessionId, { writer: "ralplan-runtime", path: statePath });
 	return { statePath, runId };
 }
 
 async function handleConsensusHandoff(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
-	const resolved = resolveConsensusArgs(args);
+	const resolved = resolveConsensusArgs(args, cwd);
 	if (!resolved.task) {
 		throw new RalplanCommandError(2, 'skc ralplan requires a task description, e.g. `skc ralplan "<task>"`.');
 	}

package/src/skc-runtime/session-layout.ts

@@ -0,0 +1,180 @@
+/**
+ * Pure path layout for session-scoped SKC workflow state.
+ *
+ * Every generated/runtime artifact for a SKC session lives under
+ * `<cwd>/.skc/_session-{encodedSessionId}/...`. The `_session-` prefix is what
+ * discriminates a session directory from shared, user-authored/installed config
+ * (settings.json, secrets.yml, agents/, skc-plugins/, agent/, python-env/, user
+ * skills/commands), which always stays at the `.skc/` root.
+ *
+ * This module is PURE and acyclic: every export is a deterministic function of
+ * its arguments. It never reads `process.env` and never touches the filesystem.
+ * Session resolution (flag/payload/env/latest-activity-marker) and any
+ * filesystem scanning live in `session-resolution.ts`, the boundary module.
+ */
+import * as path from "node:path";
+
+export const SKC_DIR = ".skc";
+export const SKC_SESSION_PREFIX = "_session-";
+export const SKC_SESSION_ACTIVITY_FILE = ".session-activity.json";
+
+/** Source that produced a resolved SKC session id, for audit/diagnostics. */
+export type SkcSessionSource = "flag" | "payload" | "env" | "latest";
+
+export interface SkcSessionContext {
+	skcSessionId: string;
+	sessionRoot: string;
+	source: SkcSessionSource;
+}
+
+/**
+ * Encode a session id into a single safe path segment. Matches the historical
+ * encoding used across the runtimes so ids round-trip identically:
+ * `encodeURIComponent` plus dot-escaping (dots are legal in filenames but we
+ * avoid `.`/`..` traversal ambiguity).
+ */
+export function encodeSessionSegment(value: string): string {
+	return encodeURIComponent(value).replaceAll(".", "%2E");
+}
+
+/** Inverse of {@link encodeSessionSegment}. */
+export function decodeSessionSegment(segment: string): string {
+	return decodeURIComponent(segment.replaceAll("%2E", "."));
+}
+
+/** Throw when a session id is missing or blank; never let blank suppress callers. */
+export function assertNonEmptySkcSessionId(value: string | undefined, source: string): asserts value is string {
+	if (typeof value !== "string" || value.trim() === "") {
+		throw new Error(`a non-empty SKC session id is required (${source})`);
+	}
+}
+
+/**
+ * Assert a value is safe to use as a single path segment: non-blank and free of
+ * path separators or `.`/`..` traversal. Use for already-safe identifiers
+ * (skill modes, slugs) where we want identical filenames but fail closed on
+ * traversal rather than silently normalizing out of the intended directory.
+ */
+export function assertSafePathComponent(value: string, label: string): void {
+	const trimmed = value.trim();
+	if (trimmed === "") throw new Error(`${label} is required`);
+	if (trimmed === "." || trimmed === ".." || /[/\\]/.test(trimmed)) {
+		throw new Error(`${label} must be a safe path component (no separators or traversal): ${value}`);
+	}
+}
+
+/** The shared `.skc/` root (holds shared config; never session-scoped). */
+export function skcRoot(cwd: string): string {
+	return path.join(cwd, SKC_DIR);
+}
+
+/** The per-session root directory: `<cwd>/.skc/_session-{encodedId}`. */
+export function sessionRoot(cwd: string, skcSessionId: string): string {
+	assertNonEmptySkcSessionId(skcSessionId, "sessionRoot");
+	return path.join(skcRoot(cwd), `${SKC_SESSION_PREFIX}${encodeSessionSegment(skcSessionId)}`);
+}
+
+/** Directory name (no path) for a session id, e.g. `_session-abc`. */
+export function sessionDirName(skcSessionId: string): string {
+	assertNonEmptySkcSessionId(skcSessionId, "sessionDirName");
+	return `${SKC_SESSION_PREFIX}${encodeSessionSegment(skcSessionId)}`;
+}
+
+/** Return the decoded session id for a `_session-*` directory name, else undefined. */
+export function sessionIdFromDirName(name: string): string | undefined {
+	if (!name.startsWith(SKC_SESSION_PREFIX)) return undefined;
+	const suffix = name.slice(SKC_SESSION_PREFIX.length);
+	if (suffix === "") return undefined;
+	let decoded: string;
+	try {
+		decoded = decodeSessionSegment(suffix);
+	} catch {
+		return undefined;
+	}
+	return decoded.trim() === "" ? undefined : decoded;
+}
+
+/** Authoritative per-session activity marker path. */
+export function sessionActivityPath(cwd: string, skcSessionId: string): string {
+	return path.join(sessionRoot(cwd, skcSessionId), SKC_SESSION_ACTIVITY_FILE);
+}
+
+// ---- Top-level per-category subdir resolvers ----
+
+export function sessionStateDir(cwd: string, skcSessionId: string): string {
+	return path.join(sessionRoot(cwd, skcSessionId), "state");
+}
+export function sessionSpecsDir(cwd: string, skcSessionId: string): string {
+	return path.join(sessionRoot(cwd, skcSessionId), "specs");
+}
+export function sessionPlansDir(cwd: string, skcSessionId: string): string {
+	return path.join(sessionRoot(cwd, skcSessionId), "plans");
+}
+export function sessionUltragoalDir(cwd: string, skcSessionId: string): string {
+	return path.join(sessionRoot(cwd, skcSessionId), "ultragoal");
+}
+export function sessionAuditDir(cwd: string, skcSessionId: string): string {
+	return path.join(sessionRoot(cwd, skcSessionId), "audit");
+}
+export function sessionReportsDir(cwd: string, skcSessionId: string): string {
+	return path.join(sessionRoot(cwd, skcSessionId), "reports");
+}
+export function sessionLogsDir(cwd: string, skcSessionId: string): string {
+	return path.join(sessionRoot(cwd, skcSessionId), "logs");
+}
+export function sessionRuntimeDir(cwd: string, skcSessionId: string): string {
+	return path.join(sessionRoot(cwd, skcSessionId), "runtime");
+}
+export function sessionRlmDir(cwd: string, skcSessionId: string): string {
+	return path.join(sessionRoot(cwd, skcSessionId), "rlm");
+}
+
+// ---- Nested resolvers under <sessionRoot>/state ----
+
+export function activeStateDir(cwd: string, skcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, skcSessionId), "active");
+}
+export function activeSnapshotPath(cwd: string, skcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, skcSessionId), "skill-active-state.json");
+}
+export function activeEntryPath(cwd: string, skcSessionId: string, skill: string): string {
+	const normalized = skill.trim();
+	if (normalized === "") throw new Error("skill is required");
+	return path.join(activeStateDir(cwd, skcSessionId), `${encodeSessionSegment(normalized)}.json`);
+}
+export function modeStatePath(cwd: string, skcSessionId: string, mode: string): string {
+	const normalized = mode.trim();
+	assertSafePathComponent(normalized, "mode");
+	return path.join(sessionStateDir(cwd, skcSessionId), `${normalized}-state.json`);
+}
+export function auditPath(cwd: string, skcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, skcSessionId), "audit.jsonl");
+}
+export function transactionJournalPath(cwd: string, skcSessionId: string, mutationId: string): string {
+	return path.join(sessionStateDir(cwd, skcSessionId), "transactions", `${encodeSessionSegment(mutationId)}.json`);
+}
+export function teamStateRoot(cwd: string, skcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, skcSessionId), "team");
+}
+export function workflowGatePath(cwd: string, skcSessionId: string, gateId: string): string {
+	return path.join(sessionStateDir(cwd, skcSessionId), "workflow-gates", `${encodeSessionSegment(gateId)}.json`);
+}
+export function harnessStateRoot(cwd: string, skcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, skcSessionId), "harness");
+}
+export function coordinatorMcpStateRoot(cwd: string, skcSessionId: string): string {
+	return path.join(sessionStateDir(cwd, skcSessionId), "coordinator-mcp");
+}
+
+// ---- Nested resolvers under other top-level categories ----
+
+export function tmuxRuntimeSessionPath(cwd: string, skcSessionId: string, slug: string): string {
+	const normalized = slug.trim();
+	assertSafePathComponent(normalized, "slug");
+	return path.join(sessionRuntimeDir(cwd, skcSessionId), "tmux-sessions", `${normalized}.json`);
+}
+export function rlmArtifactRoot(cwd: string, skcSessionId: string, rlmSessionId: string): string {
+	const normalized = rlmSessionId.trim();
+	if (normalized === "") throw new Error("rlmSessionId is required");
+	return path.join(sessionRlmDir(cwd, skcSessionId), encodeSessionSegment(normalized));
+}