@sayknow-cli/coding-agent 0.3.15 → 0.4.0

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

@@ -3,7 +3,8 @@ import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { AssistantMessage } from "@sayknow-cli/ai";
-import { postmortem } from "@sayknow-cli/utils";
+import { normalizePathForComparison, postmortem } from "@sayknow-cli/utils";
+import { withFileLock } from "../config/file-lock";
 import { sessionRuntimeDir } from "./session-layout";
 import {
 	isValidOwnerIntent,
@@ -76,6 +77,8 @@ export interface RuntimeStateContext {
 	sessionId: string;
 	cwd: string;
 	sessionFile?: string | null;
+	/** Optional platform seam for deterministic cross-platform path identity checks. */
+	platform?: NodeJS.Platform;
 	branch?: string | null;
 	/** Public-safe owner metadata used to persist the canonical terminal verdict. */
 	ownerTerminal?: OwnerTerminalContext | null;
@@ -83,6 +86,14 @@ export interface RuntimeStateContext {
 	ownerTerminalMetadataInvalid?: boolean;
 }
 
+interface RuntimeStateIdentity {
+	sessionId: string;
+	cwd: string;
+	workdir: string;
+	sessionFile: string | null;
+	platform: NodeJS.Platform;
+}
+
 interface RuntimeStateSidecarPayload {
 	schema_version?: unknown;
 	session_id?: unknown;
@@ -201,27 +212,27 @@ export async function persistCoordinatorRuntimeInputReady(): Promise<RuntimeInpu
 	}
 }
 
-function sameResolvedPath(left: string, right: string): boolean {
-	return path.resolve(left) === path.resolve(right);
+function sameResolvedPath(left: string, right: string, platform: NodeJS.Platform = process.platform): boolean {
+	return normalizePathForComparison(left, platform) === normalizePathForComparison(right, platform);
 }
 
-function normalizedIdentity(context: Pick<RuntimeStateContext, "sessionId" | "cwd" | "sessionFile">): {
-	sessionId: string;
-	cwd: string;
-	workdir: string;
-	sessionFile: string | null;
-} {
+function normalizedIdentity(
+	context: Pick<RuntimeStateContext, "sessionId" | "cwd" | "sessionFile" | "platform">,
+): RuntimeStateIdentity {
 	const explicitStateFile = process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
 	const sessionId = explicitStateFile
 		? process.env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || context.sessionId.trim()
 		: context.sessionId.trim();
 	const cwd = context.cwd.trim();
+	const platform = context.platform ?? process.platform;
+	const pathApi = platform === "win32" ? path.win32 : path;
 	if (!sessionId || !cwd) throw new PreviousRuntimeStateReadError();
 	return {
 		sessionId,
-		cwd: path.resolve(cwd),
-		workdir: path.resolve(cwd),
-		sessionFile: context.sessionFile == null ? null : path.resolve(context.sessionFile),
+		cwd: pathApi.resolve(cwd),
+		workdir: pathApi.resolve(cwd),
+		sessionFile: context.sessionFile == null ? null : pathApi.resolve(context.sessionFile),
+		platform,
 	};
 }
 
@@ -268,7 +279,10 @@ export async function readTerminalRuntimeStateMarker(input: {
 	sessionId?: string | null;
 	cwd?: string | null;
 	sessionFile?: string | null;
+	platform?: NodeJS.Platform;
 }): Promise<TerminalRuntimeStateStatus> {
+	const platform = input.platform ?? process.platform;
+	const pathApi = platform === "win32" ? path.win32 : path;
 	const stateFile = input.stateFile?.trim();
 	const sessionId = input.sessionId?.trim();
 	const cwd = input.cwd?.trim();
@@ -287,15 +301,18 @@ export async function readTerminalRuntimeStateMarker(input: {
 	if (!validRuntimeStateMarker(value)) return { terminal: false, reason: "invalid_state_marker" };
 	const payload = value;
 	if (payload.session_id !== sessionId) return { terminal: false, reason: "session_id_mismatch" };
-	if (!sameResolvedPath(payload.cwd as string, cwd) || !sameResolvedPath(payload.workdir as string, cwd))
+	if (
+		!sameResolvedPath(payload.cwd as string, cwd, platform) ||
+		!sameResolvedPath(payload.workdir as string, cwd, platform)
+	)
 		return { terminal: false, reason: "cwd_mismatch" };
-	const sessionFile = input.sessionFile == null ? null : path.resolve(input.sessionFile);
+	const sessionFile = input.sessionFile == null ? null : pathApi.resolve(input.sessionFile);
 	if (
 		payload.session_file !== sessionFile &&
 		!(
 			typeof payload.session_file === "string" &&
 			typeof sessionFile === "string" &&
-			sameResolvedPath(payload.session_file, sessionFile)
+			sameResolvedPath(payload.session_file, sessionFile, platform)
 		)
 	)
 		return { terminal: false, reason: "session_file_mismatch" };
@@ -484,41 +501,35 @@ function rememberWrittenPayload(stateFile: string, payload: Record<string, unkno
 		lastPayloadByStateFile.delete(stateFile);
 	}
 }
-function shouldPreserveTerminalPayload(
-	previous: RuntimeStateSidecarPayload,
-	input: { sessionId: string; cwd: string; sessionFile: string | null },
-): boolean {
+function shouldPreserveTerminalPayload(previous: RuntimeStateSidecarPayload, input: RuntimeStateIdentity): boolean {
 	if (!validRuntimeStateMarker(previous)) return false;
 	if (previous.state !== "completed" && previous.state !== "errored") return false;
 	const source = previous.final_response?.source;
 	if (source !== "agent_end" && source !== "launch_error") return false;
 	return (
 		previous.session_id === input.sessionId &&
-		sameResolvedPath(previous.cwd as string, input.cwd) &&
-		sameResolvedPath(previous.workdir as string, input.cwd) &&
+		sameResolvedPath(previous.cwd as string, input.cwd, input.platform) &&
+		sameResolvedPath(previous.workdir as string, input.cwd, input.platform) &&
 		(previous.session_file === input.sessionFile ||
 			(typeof previous.session_file === "string" &&
 				typeof input.sessionFile === "string" &&
-				sameResolvedPath(previous.session_file, input.sessionFile)))
+				sameResolvedPath(previous.session_file, input.sessionFile, input.platform)))
 	);
 }
 
-function assertPreviousRuntimeStateIdentity(
-	previous: Record<string, unknown>,
-	input: { sessionId: string; cwd: string; sessionFile: string | null },
-): void {
+function assertPreviousRuntimeStateIdentity(previous: Record<string, unknown>, input: RuntimeStateIdentity): void {
 	if (Object.keys(previous).length === 0) return;
 	if (
 		previous.session_id !== input.sessionId ||
 		typeof previous.cwd !== "string" ||
 		typeof previous.workdir !== "string" ||
-		!sameResolvedPath(previous.cwd, input.cwd) ||
-		!sameResolvedPath(previous.workdir, input.cwd) ||
+		!sameResolvedPath(previous.cwd, input.cwd, input.platform) ||
+		!sameResolvedPath(previous.workdir, input.cwd, input.platform) ||
 		(previous.session_file !== input.sessionFile &&
 			!(
 				typeof previous.session_file === "string" &&
 				typeof input.sessionFile === "string" &&
-				sameResolvedPath(previous.session_file, input.sessionFile)
+				sameResolvedPath(previous.session_file, input.sessionFile, input.platform)
 			))
 	)
 		throw new PreviousRuntimeStateReadError();
@@ -724,117 +735,15 @@ async function writeStateFileSync(stateFile: string, payload: Record<string, unk
 	await writeStateFile(stateFile, payload);
 }
 
-interface StateFileLockOwner {
-	pid: number;
-	start_time: string;
-	token: string;
-}
-
-function processStartTime(pid: number): string | null {
-	try {
-		const stat = fsSync.readFileSync(`/proc/${pid}/stat`, "utf8");
-		const close = stat.lastIndexOf(")");
-		const fields = stat
-			.slice(close + 1)
-			.trim()
-			.split(/\s+/);
-		return fields[19] ?? null;
-	} catch {
-		return null;
-	}
-}
-
-function validLockOwner(value: unknown): value is StateFileLockOwner {
-	if (!value || typeof value !== "object") return false;
-	const owner = value as Partial<StateFileLockOwner>;
-	return (
-		typeof owner.pid === "number" &&
-		Number.isSafeInteger(owner.pid) &&
-		owner.pid > 0 &&
-		typeof owner.start_time === "string" &&
-		typeof owner.token === "string" &&
-		owner.token.length > 0
-	);
-}
-
-function lockOwnerIsAlive(value: unknown): boolean {
-	if (!validLockOwner(value)) return false;
-	const owner = value;
-	try {
-		process.kill(owner.pid, 0);
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ESRCH") return false;
-		return true;
-	}
-	const currentStartTime = processStartTime(owner.pid);
-	return currentStartTime === null || currentStartTime === owner.start_time;
-}
-
-async function reclaimStaleStateFileLock(lockFile: string): Promise<void> {
-	let raw: string;
-	try {
-		raw = await fs.readFile(lockFile, "utf8");
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
-		throw error;
-	}
-	let owner: unknown;
-	try {
-		owner = JSON.parse(raw);
-	} catch {
-		owner = null;
-	}
-	if (!validLockOwner(owner)) {
-		const stat = await fs.stat(lockFile);
-		if (Date.now() - stat.mtimeMs < 30_000) return;
-	} else if (lockOwnerIsAlive(owner)) return;
+async function withStateFileLock<T>(stateFile: string, operation: () => Promise<T>): Promise<T> {
 	try {
-		if ((await fs.readFile(lockFile, "utf8")) === raw) await fs.rm(lockFile);
+		return await withFileLock(stateFile, operation, { staleMs: 30_000, retries: 12_000, retryDelayMs: 5 });
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-	}
-}
-
-async function withStateFileLock<T>(stateFile: string, operation: () => Promise<T>): Promise<T> {
-	const lockFile = `${stateFile}.lock`;
-	const owner: StateFileLockOwner = {
-		pid: process.pid,
-		start_time: processStartTime(process.pid) ?? "unknown",
-		token: randomUUID(),
-	};
-	await fs.mkdir(path.dirname(stateFile), { recursive: true });
-	for (let attempt = 0; attempt < 12_000; attempt++) {
-		let handle: fs.FileHandle | undefined;
-		try {
-			handle = await fs.open(lockFile, "wx");
-			try {
-				await handle.writeFile(JSON.stringify(owner));
-			} catch (error) {
-				await handle.close().catch(() => undefined);
-				handle = undefined;
-				await fs.rm(lockFile, { force: true }).catch(() => undefined);
-				throw error;
-			}
-			const outcome = await operation().then(
-				value => ({ ok: true as const, value }),
-				error => ({ ok: false as const, error }),
-			);
-			await handle.close();
-			try {
-				if ((await fs.readFile(lockFile, "utf8")) === JSON.stringify(owner)) await fs.rm(lockFile);
-			} catch (error) {
-				if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-			}
-			if (!outcome.ok) throw outcome.error;
-			return outcome.value;
-		} catch (error) {
-			if (handle) throw error;
-			if ((error as { code?: unknown }).code !== "EEXIST") throw error;
-			await reclaimStaleStateFileLock(lockFile);
-			await Bun.sleep(5);
+		if (error instanceof Error && error.message.startsWith("Failed to acquire lock")) {
+			throw new PreviousRuntimeStateReadError();
 		}
+		throw error;
 	}
-	throw new PreviousRuntimeStateReadError();
 }
 
 function coordinatorTransactionLockFile(stateFile: string): string {
@@ -1112,7 +1021,7 @@ export async function persistCoordinatorRuntimeStateFromPostmortem(
 						if (shouldPreserveTerminalPayload(previous as RuntimeStateSidecarPayload, identity)) return;
 						// The immutable owner verdict remains in its lifecycle artifact; never replace a
 						// complete agent terminal payload merely to mirror that verdict here.
-						if (process.platform === "linux" && context.ownerTerminalMetadataInvalid) {
+						if (context.ownerTerminalMetadataInvalid) {
 							await persistInvalidOwnerTerminalMetadata(
 								reason,
 								context,
@@ -1122,7 +1031,7 @@ export async function persistCoordinatorRuntimeStateFromPostmortem(
 							);
 							return;
 						}
-						if (process.platform === "linux" && context.ownerTerminal) {
+						if (context.ownerTerminal) {
 							await persistCoordinatorRuntimeStateFromOwnerTerminalPostmortem(
 								reason,
 								context,

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

@@ -0,0 +1,292 @@
+import { CANONICAL_SKC_WORKFLOW_SKILLS, type CanonicalSkcWorkflowSkill } from "../skill-state/canonical-skills";
+import { typedArgsFor } from "./workflow-manifest";
+
+export type StateAction =
+	| "read"
+	| "write"
+	| "clear"
+	| "contract"
+	| "handoff"
+	| "graph"
+	| "prune"
+	| "gc"
+	| "migrate"
+	| "status"
+	| "doctor";
+
+export const STATE_ACTION_NAMES: ReadonlySet<StateAction> = new Set([
+	"read",
+	"write",
+	"clear",
+	"contract",
+	"handoff",
+	"graph",
+	"prune",
+	"gc",
+	"migrate",
+	"status",
+	"doctor",
+]);
+
+export const STATE_FLAGS_WITH_VALUES: ReadonlySet<string> = new Set([
+	"--input",
+	"--mode",
+	"--session-id",
+	"--thread-id",
+	"--turn-id",
+	"--to",
+	"--skill",
+	"--format",
+	"--older-than",
+	"--status",
+	"--fields",
+	"--since",
+	"--limit",
+]);
+
+export const STATE_BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
+	"--json",
+	"--replace",
+	"--hard",
+	"--dry-run",
+	"--migrate",
+	"--compact",
+	"--history",
+	"--force",
+]);
+
+export interface StateFlagOccurrence {
+	name: string;
+	index: number;
+	value?: string;
+	arity: "boolean" | "value";
+	form: "separate" | "attached";
+	malformed: boolean;
+}
+
+export interface StateSelectorCandidate {
+	source: "mode" | "positional" | "input.mode" | "input.skill";
+	value: string | undefined;
+	index: number;
+}
+
+export type StateInputKind = "empty" | "inline" | "file" | "invalid";
+
+export interface StateInputClassification {
+	index: number;
+	raw: string;
+	kind: StateInputKind;
+	selectors: StateSelectorCandidate[];
+}
+
+export interface StateArgvClassification {
+	argv: readonly string[];
+	action: StateAction;
+	effectiveAction: StateAction;
+	positionalSkill?: string;
+	positionals: readonly string[];
+	flags: readonly StateFlagOccurrence[];
+	unknownFlags: readonly string[];
+	inputs: readonly StateInputClassification[];
+	runtimeSelectorCandidates: readonly StateSelectorCandidate[];
+	selectorCandidates: readonly StateSelectorCandidate[];
+}
+
+function normalizedFlagName(arg: string): string | undefined {
+	if (!arg.startsWith("--")) return undefined;
+	const equalsIndex = arg.indexOf("=");
+	return equalsIndex < 0 ? arg : arg.slice(0, equalsIndex);
+}
+
+function normalizedSelector(value: unknown): string | undefined {
+	return typeof value === "string" ? value.trim() || undefined : undefined;
+}
+
+interface StatePositional {
+	value: string;
+	index: number;
+}
+
+function parseRuntimePositionals(argv: readonly string[]): StatePositional[] {
+	const positionals: StatePositional[] = [];
+	let skipNext = false;
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index]!;
+		if (skipNext) {
+			skipNext = false;
+			continue;
+		}
+		if (STATE_FLAGS_WITH_VALUES.has(arg)) {
+			skipNext = true;
+			continue;
+		}
+		if (!arg.startsWith("-")) positionals.push({ value: arg, index });
+	}
+	return positionals;
+}
+
+function parseAction(positionals: readonly StatePositional[]): {
+	action: StateAction;
+	positionalSkill?: string;
+	positionalSkillIndex: number;
+} {
+	const [first, second] = positionals;
+	if (first?.value && STATE_ACTION_NAMES.has(first.value as StateAction)) {
+		return {
+			action: first.value as StateAction,
+			...(second?.value ? { positionalSkill: second.value } : {}),
+			positionalSkillIndex: second?.value ? second.index : -1,
+		};
+	}
+	if (first?.value && second?.value && STATE_ACTION_NAMES.has(second.value as StateAction)) {
+		return { action: second.value as StateAction, positionalSkill: first.value, positionalSkillIndex: first.index };
+	}
+	if (first?.value && !second?.value) {
+		return { action: "read", positionalSkill: first.value, positionalSkillIndex: first.index };
+	}
+	return { action: "read", positionalSkillIndex: -1 };
+}
+
+function stateFlagArities(
+	action: StateAction,
+	positionalSkill: string | undefined,
+): ReadonlyMap<string, "boolean" | "value"> {
+	const arities = new Map<string, "boolean" | "value">();
+	for (const flag of STATE_FLAGS_WITH_VALUES) arities.set(flag, "value");
+	for (const flag of STATE_BOOLEAN_FLAGS) arities.set(flag, "boolean");
+
+	const skills =
+		positionalSkill && CANONICAL_SKC_WORKFLOW_SKILLS.includes(positionalSkill as CanonicalSkcWorkflowSkill)
+			? [positionalSkill as CanonicalSkcWorkflowSkill]
+			: CANONICAL_SKC_WORKFLOW_SKILLS;
+	for (const skill of skills) {
+		for (const arg of typedArgsFor(skill, action)) {
+			const name = `--${arg.name}`;
+			if (!arities.has(name)) arities.set(name, arg.type === "boolean" ? "boolean" : "value");
+		}
+	}
+	return arities;
+}
+
+function classifyInput(occurrence: StateFlagOccurrence): StateInputClassification {
+	const raw = occurrence.value ?? "";
+	const trimmed = raw.trim();
+	if (!trimmed) return { index: occurrence.index, raw, kind: "empty", selectors: [] };
+	if (trimmed.startsWith("@")) return { index: occurrence.index, raw, kind: "file", selectors: [] };
+	try {
+		const payload = JSON.parse(trimmed) as unknown;
+		if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+			return { index: occurrence.index, raw, kind: "invalid", selectors: [] };
+		}
+		const record = payload as Record<string, unknown>;
+		return {
+			index: occurrence.index,
+			raw,
+			kind: "inline",
+			selectors: [
+				{ source: "input.mode", value: normalizedSelector(record.mode), index: occurrence.index },
+				{ source: "input.skill", value: normalizedSelector(record.skill), index: occurrence.index },
+			],
+		};
+	} catch {
+		return { index: occurrence.index, raw, kind: "invalid", selectors: [] };
+	}
+}
+
+export function firstStateFlagValue(classification: StateArgvClassification, name: string): string | undefined {
+	const index = classification.argv.indexOf(name);
+	return index < 0 ? undefined : classification.argv[index + 1];
+}
+
+export function classifyStateArgv(argv: readonly string[]): StateArgvClassification {
+	const preservedArgv = [...argv];
+	const positionalEntries = parseRuntimePositionals(preservedArgv);
+	const positionals = positionalEntries.map(positional => positional.value);
+	const { action, positionalSkill, positionalSkillIndex } = parseAction(positionalEntries);
+	const flagArities = stateFlagArities(action, positionalSkill);
+	const flags: StateFlagOccurrence[] = [];
+	const unknownFlags: string[] = [];
+
+	for (let index = 0; index < preservedArgv.length; index += 1) {
+		const arg = preservedArgv[index]!;
+		const name = normalizedFlagName(arg);
+		if (!name) continue;
+		const arity = flagArities.get(name);
+		if (!arity) {
+			unknownFlags.push(name);
+			continue;
+		}
+		if (arg !== name) {
+			flags.push({
+				name,
+				index,
+				value: arg.slice(name.length + 1),
+				arity,
+				form: "attached",
+				malformed: true,
+			});
+			continue;
+		}
+		if (arity === "boolean") {
+			flags.push({ name, index, arity, form: "separate", malformed: false });
+			continue;
+		}
+		const value = preservedArgv[index + 1];
+		flags.push({
+			name,
+			index,
+			...(value === undefined ? {} : { value }),
+			arity,
+			form: "separate",
+			malformed: value === undefined || value.startsWith("--"),
+		});
+	}
+	const effectiveAction = action === "read" && preservedArgv.includes("--migrate") ? "migrate" : action;
+
+	const modeFlags = flags.filter(flag => flag.name === "--mode" && flag.form === "separate");
+	const inputFlags = flags.filter(flag => flag.name === "--input" && flag.form === "separate");
+	const inputs = inputFlags.map(classifyInput);
+	const positionalCandidate: StateSelectorCandidate = {
+		source: "positional",
+		value: normalizedSelector(positionalSkill),
+		index: positionalSkillIndex,
+	};
+	const modeCandidates = modeFlags.map(flag => ({
+		source: "mode" as const,
+		value: normalizedSelector(flag.value),
+		index: flag.index,
+	}));
+	const selectorCandidates = [positionalCandidate, ...modeCandidates, ...inputs.flatMap(input => input.selectors)];
+	const firstModeIndex = preservedArgv.indexOf("--mode");
+	const firstModeCandidate: StateSelectorCandidate = {
+		source: "mode",
+		value: normalizedSelector(firstModeIndex < 0 ? undefined : preservedArgv[firstModeIndex + 1]),
+		index: firstModeIndex,
+	};
+	const firstInputIndex = preservedArgv.indexOf("--input");
+	const firstInput =
+		firstInputIndex < 0
+			? undefined
+			: classifyInput({
+					name: "--input",
+					index: firstInputIndex,
+					value: preservedArgv[firstInputIndex + 1],
+					arity: "value",
+					form: "separate",
+					malformed: false,
+				});
+	const runtimeSelectorCandidates = [firstModeCandidate, positionalCandidate, ...(firstInput?.selectors ?? [])];
+
+	return {
+		argv: preservedArgv,
+		action,
+		effectiveAction,
+		...(positionalSkill === undefined ? {} : { positionalSkill }),
+		positionals,
+		flags,
+		unknownFlags,
+		inputs,
+		runtimeSelectorCandidates,
+		selectorCandidates,
+	};
+}

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

@@ -18,7 +18,7 @@ export interface MigrateAndPersistLegacyStateArgs {
 	cwd: string;
 	skill: string;
 	statePath: string;
-	sessionId?: string;
+	sessionId: string;
 }
 
 export interface MigrateAndPersistLegacyStateResult {