@sayknow-cli/coding-agent 0.2.3 → 0.2.5

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

@@ -27,6 +27,13 @@ import {
 } from "../skill-state/workflow-state-contract";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
 import { mergeDeepInterviewEnvelope, normalizeDeepInterviewEnvelope } from "./deep-interview-state";
+import { activeSnapshotPath, auditPath, modeStatePath, sessionStateDir } from "./session-layout";
+import {
+	resolveSkcSessionForRead,
+	resolveSkcSessionForWrite,
+	SessionResolutionError,
+	writeSessionActivityMarker,
+} from "./session-resolution";
 import { renderStateGraph, type StateGraphFormat } from "./state-graph";
 import { migrateAndPersistLegacyState, migrateWorkflowState } from "./state-migrations";
 import {
@@ -53,16 +60,16 @@ import {
 	softDelete,
 	updateWorkflowTransactionJournal,
 	type WorkflowEnvelopeIntegrityMismatch,
-	writeWorkflowEnvelopeAtomic,
+	writeGuardedWorkflowEnvelopeAtomic,
 } from "./state-writer";
 import { getSkillManifest, isKnownWorkflowState, isValidTransition, typedArgsFor } from "./workflow-manifest";
 
 /**
  * Native implementation of the `skc state read|write|clear` command surface.
  *
- * Simple file-receipt operations against `.skc/state/[sessions/<id>/]<mode>-state.json` and
- * `.skc/state/[sessions/<id>/]skill-active-state.json`. This is the sanctioned CLI mediator for
- * the mutation-guarded `.skc/state` ACL — agents call it instead of editing those files directly.
+ * Simple file-receipt operations against session-scoped state under
+ * `.skc/_session-{id}/state/`. This is the sanctioned CLI mediator for
+ * mutation-guarded SKC state — agents call it instead of editing those files directly.
  */
 
 export interface StateCommandResult {
@@ -72,6 +79,7 @@ export interface StateCommandResult {
 }
 
 const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
+const TERMINAL_CLEAR_PHASES = new Set(["complete", "completed", "cancelled", "canceled", "failed"]);
 const PATH_COMPONENT_RE = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
 const KNOWN_MODES: readonly string[] = CANONICAL_SKC_WORKFLOW_SKILLS;
 
@@ -269,16 +277,22 @@ async function readInputJson(value: string | undefined, cwd: string): Promise<Re
 
 interface ResolvedSelectors {
 	mode: CanonicalSkcWorkflowSkill | undefined;
-	sessionId: string | undefined;
+	skcSessionId: string;
 	threadId: string | undefined;
 	turnId: string | undefined;
 	payload: Record<string, unknown> | undefined;
 }
 
+// `clear` resolves like a read (explicit -> payload -> env -> latest-activity marker)
+// per the spec: read/status/clear may fall back to the most-recent session. Commands
+// that create or mutate new state roots still require an explicit/env session id.
+const WRITE_SESSION_ACTIONS = new Set<ParsedInvocation["action"]>(["write", "handoff", "prune", "migrate"]);
+
 async function resolveSelectors(
 	args: readonly string[],
 	cwd: string,
 	positionalSkill: string | undefined,
+	action: ParsedInvocation["action"],
 ): Promise<ResolvedSelectors> {
 	const payload = await readInputJson(flagValue(args, "--input"), cwd);
 
@@ -297,33 +311,32 @@ async function resolveSelectors(
 	}
 	if (mode) assertKnownMode(mode);
 
-	const explicitSessionId = flagValue(args, "--session-id");
-	// Session-id resolution order: explicit --session-id flag, then payload
-	// session_id, then SKC_SESSION_ID env var (set by AgentSession.sdk for
-	// agent-initiated CLI invocations). The env-var default keeps shell
-	// snippets in skill docs short while still routing writes/reads to the
-	// caller's session-scoped state files.
-	let sessionId = explicitSessionId !== undefined ? explicitSessionId.trim() || undefined : undefined;
-	if (!sessionId && payload && typeof payload.session_id === "string") {
-		sessionId = payload.session_id.trim() || undefined;
-	}
-	if (!sessionId && explicitSessionId === undefined) {
-		const envSessionId = process.env.SKC_SESSION_ID?.trim();
-		if (envSessionId) sessionId = envSessionId;
-	}
-	if (sessionId) assertSafePathComponent(sessionId, "session-id");
+	const sessionSources = {
+		flagValue: flagValue(args, "--session-id"),
+		payloadSessionId: payload?.session_id,
+		envSessionId: process.env.SKC_SESSION_ID,
+	};
+	const session = WRITE_SESSION_ACTIONS.has(action)
+		? resolveSkcSessionForWrite(cwd, sessionSources)
+		: await resolveSkcSessionForRead(cwd, sessionSources);
 
 	const threadId = flagValue(args, "--thread-id")?.trim() || undefined;
 	if (threadId) assertSafePathComponent(threadId, "thread-id");
 	const turnId = flagValue(args, "--turn-id")?.trim() || undefined;
 	if (turnId) assertSafePathComponent(turnId, "turn-id");
 
-	return { mode: mode as CanonicalSkcWorkflowSkill | undefined, sessionId, threadId, turnId, payload };
+	return {
+		mode: mode as CanonicalSkcWorkflowSkill | undefined,
+		skcSessionId: session.skcSessionId,
+		threadId,
+		turnId,
+		payload,
+	};
 }
 
 async function inferModeFromActiveState(
 	cwd: string,
-	sessionId: string | undefined,
+	sessionId: string,
 ): Promise<CanonicalSkcWorkflowSkill | undefined> {
 	const state = await readVisibleSkillActiveState(cwd, sessionId);
 	const entries = listActiveSkills(state);
@@ -333,22 +346,53 @@ async function inferModeFromActiveState(
 	return canonical ?? undefined;
 }
 
-function encodeSessionSegment(value: string): string {
-	return encodeURIComponent(value).replaceAll(".", "%2E");
+function stateDirFor(cwd: string, sessionId: string): string {
+	return sessionStateDir(cwd, sessionId);
 }
 
-function stateDirFor(cwd: string, sessionId: string | undefined): string {
-	const base = path.join(cwd, ".skc", "state");
-	if (!sessionId) return base;
-	return path.join(base, "sessions", encodeSessionSegment(sessionId));
+function modeStateFile(cwd: string, mode: string, sessionId: string): string {
+	return modeStatePath(cwd, sessionId, mode);
 }
 
-function modeStateFile(cwd: string, mode: string, sessionId: string | undefined): string {
-	return path.join(stateDirFor(cwd, sessionId), `${mode}-state.json`);
+function activeStateFile(cwd: string, sessionId: string): string {
+	return activeSnapshotPath(cwd, sessionId);
+}
+
+function stateRelativePath(cwd: string, filePath: string): string {
+	return path.relative(cwd, filePath).split(path.sep).join(path.posix.sep);
+}
+
+async function touchStateActivityMarker(cwd: string, sessionId: string, filePath: string): Promise<void> {
+	await writeSessionActivityMarker(cwd, sessionId, {
+		writer: "state-runtime",
+		path: stateRelativePath(cwd, filePath),
+	});
+}
+
+async function readActivePhaseForSkill(
+	cwd: string,
+	sessionId: string,
+	mode: CanonicalSkcWorkflowSkill,
+): Promise<string | undefined> {
+	const state = await readVisibleSkillActiveState(cwd, sessionId);
+	const entries = listActiveSkills(state);
+	const entry = entries.find(item => item.skill === mode) ?? (state?.skill === mode ? state : undefined);
+	return isPlainObject(entry) && typeof entry.phase === "string" ? entry.phase.trim() || undefined : undefined;
 }
 
-function activeStateFile(cwd: string, sessionId: string | undefined): string {
-	return path.join(stateDirFor(cwd, sessionId), SKILL_ACTIVE_STATE_FILE);
+async function describeStaleClearState(
+	cwd: string,
+	sessionId: string,
+	mode: CanonicalSkcWorkflowSkill,
+	existing: Record<string, unknown>,
+): Promise<string | undefined> {
+	const phase = typeof existing.current_phase === "string" ? existing.current_phase.trim() : undefined;
+	if (phase && TERMINAL_CLEAR_PHASES.has(phase)) return `mode-state is already terminal (${phase})`;
+	const activePhase = await readActivePhaseForSkill(cwd, sessionId, mode);
+	if (activePhase && phase && activePhase !== phase) {
+		return `active-state phase ${activePhase} differs from mode-state phase ${phase}`;
+	}
+	return undefined;
 }
 
 async function readJsonFile(filePath: string): Promise<Record<string, unknown> | null> {
@@ -438,7 +482,7 @@ function doctorProblem(
 		: { type, path: pathValue, message, fixCommand };
 }
 
-function activeEntryDir(cwd: string, sessionId: string | undefined): string {
+function activeEntryDir(cwd: string, sessionId: string): string {
 	return path.join(stateDirFor(cwd, sessionId), "active");
 }
 
@@ -499,9 +543,9 @@ function pushPhaseDriftProblem(options: {
 async function collectDoctorSummary(
 	cwd: string,
 	skill: CanonicalSkcWorkflowSkill | undefined,
-	sessionId: string | undefined,
+	sessionId: string,
 ): Promise<DoctorSummary> {
-	const root = path.join(cwd, ".skc", "state");
+	const root = sessionStateDir(cwd, sessionId);
 	const skills = skill ? [skill] : [...CANONICAL_SKC_WORKFLOW_SKILLS];
 	const problems: DoctorProblem[] = [];
 	let filesScanned = 0;
@@ -575,7 +619,7 @@ async function collectDoctorSummary(
 		}
 	}
 
-	const inspectActiveScope = async (scopeSessionId: string | undefined): Promise<void> => {
+	const inspectActiveScope = async (scopeSessionId: string): Promise<void> => {
 		const snapshotPath = activeStateFile(cwd, scopeSessionId);
 		const snapshot = await readRawJson(snapshotPath);
 		if (snapshot.exists) filesScanned += 1;
@@ -616,7 +660,9 @@ async function collectDoctorSummary(
 			}
 		}
 		if (isPlainObject(snapshot.value)) {
-			const activeSkills = Array.isArray(snapshot.value.active_skills) ? snapshot.value.active_skills : [];
+			const activeSkills: unknown[] = Array.isArray(snapshot.value.active_skills)
+				? snapshot.value.active_skills
+				: [];
 			for (const entry of activeSkills) {
 				const entrySkill = skillFromActiveValue(entry);
 				if (!entrySkill) continue;
@@ -650,21 +696,6 @@ async function collectDoctorSummary(
 	};
 
 	await inspectActiveScope(sessionId);
-	if (!sessionId) {
-		const sessionsDir = path.join(root, "sessions");
-		let sessions: string[] = [];
-		try {
-			const entries = await fs.readdir(sessionsDir, { withFileTypes: true });
-			sessions = entries
-				.filter(entry => entry.isDirectory())
-				.map(entry => entry.name)
-				.sort();
-		} catch (error) {
-			const err = error as NodeJS.ErrnoException;
-			if (err.code !== "ENOENT") throw error;
-		}
-		for (const rawSession of sessions) await inspectActiveScope(decodeURIComponent(rawSession));
-	}
 
 	problems.sort(
 		(a, b) =>
@@ -718,9 +749,17 @@ async function handleDoctor(
 ): Promise<StateCommandResult> {
 	const rawSkill = flagValue(args, "--skill")?.trim() || flagValue(args, "--mode")?.trim() || positionalSkill?.trim();
 	if (rawSkill) assertKnownMode(rawSkill);
-	const sessionId = flagValue(args, "--session-id")?.trim() || undefined;
-	if (sessionId) assertSafePathComponent(sessionId, "session-id");
-	const summary = await collectDoctorSummary(cwd, rawSkill as CanonicalSkcWorkflowSkill | undefined, sessionId);
+	const payload = await readInputJson(flagValue(args, "--input"), cwd);
+	const session = await resolveSkcSessionForRead(cwd, {
+		flagValue: flagValue(args, "--session-id"),
+		payloadSessionId: payload?.session_id,
+		envSessionId: process.env.SKC_SESSION_ID,
+	});
+	const summary = await collectDoctorSummary(
+		cwd,
+		rawSkill as CanonicalSkcWorkflowSkill | undefined,
+		session.skcSessionId,
+	);
 	return {
 		status: summary.ok ? 0 : 1,
 		stdout: hasFlag(args, "--json") ? `${JSON.stringify(summary, null, 2)}\n` : renderDoctorText(summary),
@@ -729,6 +768,7 @@ async function handleDoctor(
 
 async function warnAndAuditOutOfBandIfNeeded(
 	cwd: string,
+	sessionId: string,
 	filePath: string,
 	skill: CanonicalSkcWorkflowSkill,
 	options?: { mutationId?: string; forced?: boolean },
@@ -743,7 +783,7 @@ async function warnAndAuditOutOfBandIfNeeded(
 	}
 	if (!mismatch) return undefined;
 	const message = `WARNING: workflow mode-state out-of-band edit detected for ${skill}: ${filePath} expected sha256 ${mismatch.expected} but found ${mismatch.actual}`;
-	await appendAuditEntry(cwd, {
+	await appendAuditEntry(cwd, sessionId, {
 		ts: new Date().toISOString(),
 		skill,
 		category: "state",
@@ -758,12 +798,19 @@ async function warnAndAuditOutOfBandIfNeeded(
 	return message;
 }
 
+function existingStateRevision(value: unknown): number | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const revision = (value as Record<string, unknown>).state_revision;
+	return typeof revision === "number" && Number.isFinite(revision) ? revision : 0;
+}
+
 async function writeJsonAtomic(
 	cwd: string,
 	filePath: string,
 	value: unknown,
 	verb: "write" | "clear" | "handoff" | "reconcile" = "write",
 	options?: {
+		sessionId: string;
 		skill?: CanonicalSkcWorkflowSkill;
 		mutationId?: string;
 		force?: boolean;
@@ -773,7 +820,7 @@ async function writeJsonAtomic(
 	},
 ): Promise<{ warning?: string; stamped: Record<string, unknown> }> {
 	const warning = options?.skill
-		? await warnAndAuditOutOfBandIfNeeded(cwd, filePath, options.skill, {
+		? await warnAndAuditOutOfBandIfNeeded(cwd, options.sessionId, filePath, options.skill, {
 				mutationId: options.mutationId,
 				forced: options.force ?? false,
 			})
@@ -781,9 +828,15 @@ async function writeJsonAtomic(
 	if (warning && !options?.force) {
 		throw new StateCommandError(2, `${warning}; use --force to overwrite tampered mode-state`);
 	}
-	await writeWorkflowEnvelopeAtomic(filePath, value, {
+	// Authoritative CLI/runtime write. Stamp the next state_revision under the
+	// writer lock; do not enforce an optimistic `expectedRevision` here (tamper
+	// detection is handled by warnAndAuditOutOfBandIfNeeded above, and a forced
+	// write must succeed over corrupt/missing prior state).
+	await writeGuardedWorkflowEnvelopeAtomic(filePath, value, {
 		cwd,
+		policy: "source",
 		audit: {
+			sessionId: options?.sessionId ?? "",
 			category: "state",
 			verb,
 			owner: options?.owner ?? "skc-state-cli",
@@ -843,13 +896,14 @@ function parseSinceFlag(args: readonly string[]): string | undefined {
 async function readAuditWindow(
 	cwd: string,
 	args: readonly string[],
+	sessionId: string,
 ): Promise<{ entries: unknown[]; limit: number; since?: string; truncated: boolean }> {
 	const limit = parseLimitFlag(args);
 	const since = parseSinceFlag(args);
-	const auditPath = path.join(cwd, ".skc", "state", "audit.jsonl");
+	const auditFile = auditPath(cwd, sessionId);
 	let raw = "";
 	try {
-		raw = await fs.readFile(auditPath, "utf-8");
+		raw = await fs.readFile(auditFile, "utf-8");
 	} catch (error) {
 		const err = error as NodeJS.ErrnoException;
 		if (err.code !== "ENOENT") throw error;
@@ -957,6 +1011,14 @@ function buildHudForMode(
 								typeof (rawLedger as Record<string, unknown>).timestamp === "string"
 									? ((rawLedger as Record<string, unknown>).timestamp as string)
 									: undefined,
+							kind:
+								typeof (rawLedger as Record<string, unknown>).kind === "string"
+									? ((rawLedger as Record<string, unknown>).kind as string)
+									: undefined,
+							evidence:
+								typeof (rawLedger as Record<string, unknown>).evidence === "string"
+									? ((rawLedger as Record<string, unknown>).evidence as string)
+									: undefined,
 						}
 					: undefined;
 			const status = typeof payload.status === "string" ? (payload.status as string) : (phase ?? "pending");
@@ -1006,7 +1068,7 @@ function buildHudForMode(
 async function syncWorkflowSkillState(options: {
 	cwd: string;
 	mode: CanonicalSkcWorkflowSkill;
-	sessionId: string | undefined;
+	sessionId: string;
 	threadId?: string;
 	turnId?: string;
 	active: boolean;
@@ -1026,6 +1088,7 @@ async function syncWorkflowSkillState(options: {
 			source: "skc-state-cli",
 			hud: buildHudForMode(options.mode, options.payload),
 			...(options.receipt ? { receipt: options.receipt } : {}),
+			sourceRevision: existingStateRevision(options.payload),
 		});
 	} catch {
 		// HUD sync is best-effort and must not change command semantics.
@@ -1045,14 +1108,19 @@ async function syncWorkflowSkillState(options: {
 export async function reconcileWorkflowSkillState(options: {
 	cwd: string;
 	mode: CanonicalSkcWorkflowSkill;
-	sessionId: string | undefined;
+	sessionId?: string;
 	threadId?: string;
 	turnId?: string;
 	active: boolean;
 	phase: string;
 	payload: Record<string, unknown>;
+	sourceRevision?: number;
 }): Promise<{ stateFile: string }> {
-	const { cwd, mode, sessionId, threadId, turnId, active, payload } = options;
+	const { cwd, mode, threadId, turnId, active, payload } = options;
+	const { skcSessionId: sessionId } = resolveSkcSessionForWrite(cwd, {
+		payloadSessionId: options.sessionId,
+		envSessionId: process.env.SKC_SESSION_ID,
+	});
 	const filePath = modeStateFile(cwd, mode, sessionId);
 	const existingRead = await readExistingStateForMutation(filePath);
 	const existingPayload = existingRead.kind === "valid" ? existingRead.value : {};
@@ -1096,14 +1164,37 @@ export async function reconcileWorkflowSkillState(options: {
 	const validation = validateWorkflowStateEnvelope(mode, merged);
 	if (!validation.valid) throw new StateCommandError(2, validation.error ?? `invalid ${mode} state envelope`);
 
-	await writeJsonAtomic(cwd, filePath, merged, "reconcile", {
-		skill: mode,
-		mutationId,
-		force: true,
-		fromPhase,
-		toPhase: trimmedPhase,
-		owner: "skc-runtime",
+	if (existingRead.kind === "corrupt") await fs.rm(filePath, { force: true });
+	await writeGuardedWorkflowEnvelopeAtomic(filePath, merged, {
+		cwd,
+		policy: "source",
+		receipt: {
+			cwd,
+			skill: mode,
+			owner: "skc-runtime",
+			command: `skc ${mode} (reconcile)`,
+			sessionId,
+			nowIso: nowIsoStr,
+			mutationId,
+			verb: "reconcile",
+			forced: true,
+			fromPhase,
+			toPhase: trimmedPhase,
+		},
+		audit: {
+			category: "state",
+			verb: "reconcile",
+			owner: "skc-runtime",
+			sessionId,
+			skill: mode,
+			mutationId,
+			forced: true,
+			fromPhase,
+			toPhase: trimmedPhase,
+		},
 	});
+	const persisted = (await readJsonFile(filePath)) ?? {};
+	const sourceRevision = options.sourceRevision ?? existingStateRevision(persisted);
 
 	// Reconciliation drives the active-state/HUD update directly (not via the
 	// best-effort syncWorkflowSkillState wrapper) so a failed HUD/active-state write
@@ -1120,7 +1211,9 @@ export async function reconcileWorkflowSkillState(options: {
 		source: "skc-runtime-reconcile",
 		hud: buildHudForMode(mode, merged),
 		receipt,
+		sourceRevision,
 	});
+	await touchStateActivityMarker(cwd, sessionId, filePath);
 	return { stateFile: filePath };
 }
 export async function readWorkflowStateJson(
@@ -1128,7 +1221,11 @@ export async function readWorkflowStateJson(
 	skill: CanonicalSkcWorkflowSkill,
 	sessionId?: string,
 ): Promise<Record<string, unknown>> {
-	return (await readJsonFile(modeStateFile(cwd, skill, sessionId))) ?? {};
+	const session = await resolveSkcSessionForRead(cwd, {
+		payloadSessionId: sessionId,
+		envSessionId: process.env.SKC_SESSION_ID,
+	});
+	return (await readJsonFile(modeStateFile(cwd, skill, session.skcSessionId))) ?? {};
 }
 
 async function handleRead(
@@ -1136,12 +1233,12 @@ async function handleRead(
 	cwd: string,
 	positionalSkill: string | undefined,
 ): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill);
-	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.sessionId));
+	const selectors = await resolveSelectors(args, cwd, positionalSkill, "read");
+	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.skcSessionId));
 	const fields = parseFieldsFlag(args);
 	if (mode) {
-		const filePath = modeStateFile(cwd, mode, selectors.sessionId);
-		const existing = await readWorkflowStateJson(cwd, mode, selectors.sessionId);
+		const filePath = modeStateFile(cwd, mode, selectors.skcSessionId);
+		const existing = await readWorkflowStateJson(cwd, mode, selectors.skcSessionId);
 		const envelope = { skill: mode, state: existing, storage_path: filePath };
 		const manifest = getSkillManifest(mode);
 		if (fields) {
@@ -1169,7 +1266,7 @@ async function handleRead(
 				: renderStateMarkdown(mode, envelope, manifest),
 		};
 	}
-	const filePath = activeStateFile(cwd, selectors.sessionId);
+	const filePath = activeStateFile(cwd, selectors.skcSessionId);
 	const existingRaw = await readJsonValue(filePath);
 	const existing = isPlainObject(existingRaw) ? existingRaw : null;
 	return { status: 0, stdout: `${JSON.stringify(existing ?? {}, null, 2)}\n` };
@@ -1180,16 +1277,16 @@ async function handleStatus(
 	cwd: string,
 	positionalSkill: string | undefined,
 ): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill);
-	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.sessionId));
+	const selectors = await resolveSelectors(args, cwd, positionalSkill, "read");
+	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.skcSessionId));
 	if (!mode) {
 		throw new StateCommandError(
 			2,
-			"skc state status requires --mode <skill>, positional <skill>, input.skill, or an active workflow in .skc/state/skill-active-state.json",
+			"skc state status requires --mode <skill>, positional <skill>, input.skill, or an active workflow in the current session active state",
 		);
 	}
-	const filePath = modeStateFile(cwd, mode, selectors.sessionId);
-	const existing = await readWorkflowStateJson(cwd, mode, selectors.sessionId);
+	const filePath = modeStateFile(cwd, mode, selectors.skcSessionId);
+	const existing = await readWorkflowStateJson(cwd, mode, selectors.skcSessionId);
 	const summary = buildStateStatusSummary(
 		mode,
 		{ skill: mode, state: existing, storage_path: filePath },
@@ -1207,14 +1304,14 @@ async function handleWrite(
 	cwd: string,
 	positionalSkill: string | undefined,
 ): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill);
-	const { sessionId, threadId, turnId, payload } = selectors;
+	const selectors = await resolveSelectors(args, cwd, positionalSkill, "write");
+	const { skcSessionId: sessionId, threadId, turnId, payload } = selectors;
 	if (!payload) throw new StateCommandError(2, "skc state write requires --input '<json>'");
 	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, sessionId));
 	if (!mode)
 		throw new StateCommandError(
 			2,
-			"skc state write requires --mode <skill>, positional <skill>, input.skill, or an active workflow in .skc/state/skill-active-state.json",
+			"skc state write requires --mode <skill>, positional <skill>, input.skill, or an active workflow in the current session active state",
 		);
 
 	const filePath = modeStateFile(cwd, mode, sessionId);
@@ -1303,6 +1400,7 @@ async function handleWrite(
 	if (!validation.valid) throw new StateCommandError(2, validation.error ?? `invalid ${mode} state envelope`);
 
 	const { warning: outOfBandWarning, stamped } = await writeJsonAtomic(cwd, filePath, merged, "write", {
+		sessionId,
 		skill: mode,
 		mutationId,
 		force: forced,
@@ -1313,7 +1411,14 @@ async function handleWrite(
 
 	const phase = typeof merged.current_phase === "string" ? merged.current_phase : undefined;
 	const active = merged.active !== false;
+	// Reflect the freshly stamped mode-state revision onto the in-memory payload so the
+	// active-state/HUD sync derives a `sourceRevision` from the persisted revision, not the
+	// stale pre-write value; otherwise the active-state writer stale-skips the update and the
+	// mirror keeps the prior phase (e.g. staying "interviewing" after a "handoff" write).
+	const stampedRevision = existingStateRevision(stamped);
+	if (typeof stampedRevision === "number") merged.state_revision = stampedRevision;
 	await syncWorkflowSkillState({ cwd, mode, sessionId, threadId, turnId, active, phase, payload: merged, receipt });
+	await touchStateActivityMarker(cwd, sessionId, filePath);
 
 	return {
 		status: 0,
@@ -1336,13 +1441,13 @@ async function handleClear(
 	cwd: string,
 	positionalSkill: string | undefined,
 ): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill);
-	const { sessionId, threadId, turnId } = selectors;
+	const selectors = await resolveSelectors(args, cwd, positionalSkill, "clear");
+	const { skcSessionId: sessionId, threadId, turnId } = selectors;
 	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, sessionId));
 	if (!mode)
 		throw new StateCommandError(
 			2,
-			"skc state clear requires --mode <skill>, positional <skill>, input.skill, or an active workflow in .skc/state/skill-active-state.json",
+			"skc state clear requires --mode <skill>, positional <skill>, input.skill, or an active workflow in the current session active state",
 		);
 
 	const filePath = modeStateFile(cwd, mode, sessionId);
@@ -1355,6 +1460,10 @@ async function handleClear(
 		);
 	}
 	const existing = existingRead.kind === "valid" ? existingRead.value : {};
+	const staleReason = await describeStaleClearState(cwd, sessionId, mode, existing);
+	if (staleReason && !forced) {
+		throw new StateCommandError(2, `existing state for ${mode} is stale (${staleReason}); use --force to clear`);
+	}
 	const clearedAt = nowIso();
 	const cleared: Record<string, unknown> = {
 		skill: mode,
@@ -1377,6 +1486,7 @@ async function handleClear(
 	});
 	cleared.receipt = receipt;
 	const { warning: outOfBandWarning, stamped } = await writeJsonAtomic(cwd, filePath, cleared, "clear", {
+		sessionId,
 		skill: mode,
 		mutationId,
 		force: forced,
@@ -1395,6 +1505,7 @@ async function handleClear(
 		phase: "complete",
 		payload: cleared,
 	});
+	await touchStateActivityMarker(cwd, sessionId, filePath);
 	return {
 		status: 0,
 		stdout: renderCliWriteReceipt({
@@ -1435,13 +1546,13 @@ async function handleHandoff(
 	cwd: string,
 	positionalSkill: string | undefined,
 ): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill);
-	const { sessionId, threadId, turnId } = selectors;
+	const selectors = await resolveSelectors(args, cwd, positionalSkill, "handoff");
+	const { skcSessionId: sessionId, threadId, turnId } = selectors;
 	const caller = selectors.mode ?? (await inferModeFromActiveState(cwd, sessionId));
 	if (!caller) {
 		throw new StateCommandError(
 			2,
-			"skc state handoff requires --mode <caller>, positional <caller>, input.skill, or an active workflow in .skc/state/skill-active-state.json",
+			"skc state handoff requires --mode <caller>, positional <caller>, input.skill, or an active workflow in the current session active state",
 		);
 	}
 	const calleeRaw = flagValue(args, "--to")?.trim();
@@ -1544,6 +1655,7 @@ async function handleHandoff(
 
 	await beginWorkflowTransactionJournal({
 		cwd,
+		sessionId,
 		mutationId,
 		caller,
 		callee,
@@ -1559,21 +1671,23 @@ async function handleHandoff(
 	// only; corrupt JSON / IO failures propagate as non-zero CLI status.
 	const force = hasFlag(args, "--force");
 	const calleeWrite = await writeJsonAtomic(cwd, calleePath, mergedCalleeState, "handoff", {
+		sessionId,
 		skill: callee,
 		mutationId,
 		force,
 		fromPhase: typeof existingCallee.current_phase === "string" ? existingCallee.current_phase : undefined,
 		toPhase: calleeInitial,
 	});
-	await updateWorkflowTransactionJournal(cwd, mutationId, { steps: ["callee-mode-state"] });
+	await updateWorkflowTransactionJournal(cwd, sessionId, mutationId, { steps: ["callee-mode-state"] });
 	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, mutationId, {
+	await updateWorkflowTransactionJournal(cwd, sessionId, mutationId, {
 		steps: ["callee-mode-state", "caller-mode-state"],
 	});
 	const warnings = [calleeWrite.warning, callerWrite.warning].filter(
@@ -1618,10 +1732,11 @@ async function handleHandoff(
 			receipt: calleeReceipt,
 		},
 	});
-	await updateWorkflowTransactionJournal(cwd, mutationId, {
+	await updateWorkflowTransactionJournal(cwd, sessionId, mutationId, {
 		steps: ["callee-mode-state", "caller-mode-state", "active-state"],
 	});
-	await completeWorkflowTransactionJournal(cwd, mutationId);
+	await completeWorkflowTransactionJournal(cwd, sessionId, mutationId);
+	await touchStateActivityMarker(cwd, sessionId, callerPath);
 
 	return {
 		status: 0,
@@ -1660,7 +1775,7 @@ async function handleContract(
 	cwd: string,
 	positionalSkill: string | undefined,
 ): Promise<StateCommandResult> {
-	const { mode } = await resolveSelectors(args, cwd, positionalSkill);
+	const { mode } = await resolveSelectors(args, cwd, positionalSkill, "read");
 	if (!mode) {
 		throw new StateCommandError(2, "skc state contract requires --mode <skill>, positional <skill>, or input.skill");
 	}
@@ -1715,11 +1830,7 @@ function categoryForStateRelativePath(relativePath: string): string | undefined
 	if (normalized === "audit.jsonl") return undefined;
 	if (normalized === SKILL_ACTIVE_STATE_FILE || normalized.endsWith(`/${SKILL_ACTIVE_STATE_FILE}`)) return undefined;
 	if (normalized.startsWith("active/") || normalized.includes("/active/")) return undefined;
-	if (
-		/^[^/]+-state\.json$/.test(normalized) ||
-		(normalized.includes("/sessions/") && /\/[^/]+-state\.json$/.test(normalized))
-	)
-		return undefined;
+	if (/^[^/]+-state\.json$/.test(normalized) || false) return undefined;
 	if (normalized.startsWith("artifacts/") || normalized.includes("/artifacts/")) return "artifact";
 	if (
 		normalized.startsWith("logs/") ||
@@ -1745,9 +1856,10 @@ function categoryForStateRelativePath(relativePath: string): string | undefined
 
 async function collectRetentionCandidates(
 	cwd: string,
+	sessionId: string,
 	skills: readonly CanonicalSkcWorkflowSkill[],
 ): Promise<RetentionCandidate[]> {
-	const stateRoot = path.join(cwd, ".skc", "state");
+	const stateRoot = sessionStateDir(cwd, sessionId);
 	const policies = new Map<string, { keep?: number; maxAgeDays?: number }>();
 	for (const skill of skills) {
 		for (const policy of getSkillManifest(skill).retention) {
@@ -1828,7 +1940,11 @@ async function buildGcSummary(
 		flagValue(args, "--skill")?.trim() || flagValue(args, "--mode")?.trim() || positionalSkill?.trim() || "all";
 	if (rawSkill !== "all") assertKnownMode(rawSkill);
 	const skills = rawSkill === "all" ? CANONICAL_SKC_WORKFLOW_SKILLS : [rawSkill as CanonicalSkcWorkflowSkill];
-	const eligible = selectRetentionEligible(await collectRetentionCandidates(cwd, skills));
+	const session = await resolveSkcSessionForRead(cwd, {
+		flagValue: flagValue(args, "--session-id"),
+		envSessionId: process.env.SKC_SESSION_ID,
+	});
+	const eligible = selectRetentionEligible(await collectRetentionCandidates(cwd, session.skcSessionId, skills));
 	const counts: Record<string, number> = {};
 	for (const candidate of eligible) counts[candidate.category] = (counts[candidate.category] ?? 0) + 1;
 	const targets: GenericHardPruneTarget[] = eligible.map(candidate => ({
@@ -1842,6 +1958,7 @@ async function buildGcSummary(
 			cwd,
 			audit: {
 				cwd,
+				sessionId: session.skcSessionId,
 				skill: rawSkill,
 				category: "prune",
 				verb: "gc",
@@ -1853,7 +1970,7 @@ async function buildGcSummary(
 		skill: rawSkill as CanonicalSkcWorkflowSkill | "all",
 		dry_run: dryRun,
 		eligible: eligible.map(candidate => candidate.relativePath),
-		pruned: pruned.map(filePath => path.relative(path.join(cwd, ".skc", "state"), filePath)),
+		pruned: pruned.map(filePath => path.relative(sessionStateDir(cwd, session.skcSessionId), filePath)),
 		counts,
 	};
 }
@@ -1864,7 +1981,11 @@ async function handleGraph(
 	positionalSkill: string | undefined,
 ): Promise<StateCommandResult> {
 	if (hasFlag(args, "--history")) {
-		const history = await readAuditWindow(_cwd, args);
+		const session = await resolveSkcSessionForRead(_cwd, {
+			flagValue: flagValue(args, "--session-id"),
+			envSessionId: process.env.SKC_SESSION_ID,
+		});
+		const history = await readAuditWindow(_cwd, args, session.skcSessionId);
 		return {
 			status: 0,
 			stdout: hasFlag(args, "--json") ? `${JSON.stringify(history, null, 2)}\n` : renderHistoryMarkdown(history),
@@ -1887,20 +2008,21 @@ async function handlePrune(
 	cwd: string,
 	positionalSkill: string | undefined,
 ): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill);
-	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.sessionId));
+	const selectors = await resolveSelectors(args, cwd, positionalSkill, "prune");
+	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.skcSessionId));
 	if (!mode) {
 		throw new StateCommandError(
 			2,
-			"skc state prune requires --mode <skill>, positional <skill>, input.skill, or an active workflow in .skc/state/skill-active-state.json",
+			"skc state prune requires --mode <skill>, positional <skill>, input.skill, or an active workflow in the current session active state",
 		);
 	}
-	const filePath = modeStateFile(cwd, mode, selectors.sessionId);
+	const filePath = modeStateFile(cwd, mode, selectors.skcSessionId);
 	const olderThanDays = parseNonNegativeIntegerFlag(args, "--older-than");
 	const status = flagValue(args, "--status")?.trim();
 	const targets: GenericHardPruneTarget[] = [{ path: filePath, category: "prune" }];
 	const audit: StateWriterAuditContext = {
 		cwd,
+		sessionId: selectors.skcSessionId,
 		skill: mode,
 		category: "prune",
 		verb: hasFlag(args, "--hard") ? "hard-prune" : "soft-delete",
@@ -1956,17 +2078,17 @@ async function handleMigrate(
 	cwd: string,
 	positionalSkill: string | undefined,
 ): Promise<StateCommandResult> {
-	const selectors = await resolveSelectors(args, cwd, positionalSkill);
-	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.sessionId));
+	const selectors = await resolveSelectors(args, cwd, positionalSkill, "migrate");
+	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.skcSessionId));
 	if (!mode) {
 		throw new StateCommandError(
 			2,
-			"skc state migrate requires --mode <skill>, positional <skill>, input.skill, or an active workflow in .skc/state/skill-active-state.json",
+			"skc state migrate requires --mode <skill>, positional <skill>, input.skill, or an active workflow in the current session active state",
 		);
 	}
-	const filePath = modeStateFile(cwd, mode, selectors.sessionId);
+	const filePath = modeStateFile(cwd, mode, selectors.skcSessionId);
 	const forced = hasFlag(args, "--force");
-	const mismatchWarning = await warnAndAuditOutOfBandIfNeeded(cwd, filePath, mode, {
+	const mismatchWarning = await warnAndAuditOutOfBandIfNeeded(cwd, selectors.skcSessionId, filePath, mode, {
 		forced,
 	});
 	if (mismatchWarning && !forced) {
@@ -1976,7 +2098,7 @@ async function handleMigrate(
 		cwd,
 		skill: mode,
 		statePath: filePath,
-		sessionId: selectors.sessionId,
+		sessionId: selectors.skcSessionId,
 	});
 	return {
 		status: 0,
@@ -2018,6 +2140,7 @@ export async function runNativeStateCommand(args: string[], cwd = process.cwd())
 		}
 	} catch (error) {
 		if (error instanceof StateCommandError) return { status: error.exitStatus, stderr: `${error.message}\n` };
+		if (error instanceof SessionResolutionError) return { status: 2, stderr: `${error.message}\n` };
 		return { status: 1, stderr: `${error instanceof Error ? error.message : String(error)}\n` };
 	}
 }