@sayknow-cli/coding-agent 0.2.4 → 0.2.5

package/src/skill-state/active-state.ts

@@ -1,4 +1,6 @@
-import * as path from "node:path";
+import * as logger from "@sayknow-cli/utils/logger";
+import { activeSnapshotPath, assertNonEmptySkcSessionId, modeStatePath } from "../skc-runtime/session-layout";
+import { resolveSkcSessionForRead, SessionResolutionError } from "../skc-runtime/session-resolution";
 import {
 	type ActiveSessionScope,
 	readActiveEntries,
@@ -6,13 +8,12 @@ import {
 	removeActiveEntry,
 	writeActiveEntry,
 } from "../skc-runtime/state-writer";
+import { CANONICAL_SKC_WORKFLOW_SKILLS, type CanonicalSkcWorkflowSkill } from "./canonical-skills";
 import type { WorkflowStateReceipt } from "./workflow-state-contract";
 
 export const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
 
-export const CANONICAL_SKC_WORKFLOW_SKILLS = ["deep-interview", "ralplan", "ultragoal", "team"] as const;
-
-export type CanonicalSkcWorkflowSkill = (typeof CANONICAL_SKC_WORKFLOW_SKILLS)[number];
+export { CANONICAL_SKC_WORKFLOW_SKILLS, type CanonicalSkcWorkflowSkill };
 export type WorkflowHudSeverity = "info" | "warning" | "blocked" | "error" | "success";
 
 export interface WorkflowHudChip {
@@ -60,6 +61,7 @@ export interface SkillActiveEntry {
 	handoff_to?: string;
 	handoff_at?: string;
 	active_subskills?: ActiveSubskillEntry[];
+	source_state_revision?: number;
 }
 
 export interface SkillActiveState {
@@ -83,7 +85,7 @@ export interface SkillActiveState {
 
 export interface SkillActiveStatePaths {
 	rootPath: string;
-	sessionPath?: string;
+	sessionPath: string;
 }
 
 export interface SyncSkillActiveStateOptions {
@@ -102,6 +104,7 @@ export interface SyncSkillActiveStateOptions {
 	handoff_to?: string;
 	handoff_at?: string;
 	active_subskills?: ActiveSubskillEntry[];
+	sourceRevision?: number;
 }
 
 const HUD_TEXT_LIMIT = 80;
@@ -246,8 +249,12 @@ function unionActiveSubskillEntries(...entrySets: Array<ActiveSubskillEntry[] |
 	return merged;
 }
 
-function encodePathSegment(value: string): string {
-	return encodeURIComponent(value).replaceAll(".", "%2E");
+function resolveBoundarySessionId(cwd: string, sessionId?: string): Promise<string> {
+	const normalizedSessionId = safeString(sessionId).trim();
+	if (normalizedSessionId) return Promise.resolve(normalizedSessionId);
+	return resolveSkcSessionForRead(cwd, { envSessionId: process.env.SKC_SESSION_ID }).then(
+		context => context.skcSessionId,
+	);
 }
 
 function entryKey(entry: Pick<SkillActiveEntry, "skill" | "session_id">): string {
@@ -343,14 +350,10 @@ export function normalizeSkillActiveState(raw: unknown): SkillActiveState | null
 }
 
 export function getSkillActiveStatePaths(cwd: string, sessionId?: string): SkillActiveStatePaths {
-	const stateDir = path.join(cwd, ".skc", "state");
-	const rootPath = path.join(stateDir, SKILL_ACTIVE_STATE_FILE);
 	const normalizedSessionId = safeString(sessionId).trim();
-	if (!normalizedSessionId) return { rootPath };
-	return {
-		rootPath,
-		sessionPath: path.join(stateDir, "sessions", encodePathSegment(normalizedSessionId), SKILL_ACTIVE_STATE_FILE),
-	};
+	assertNonEmptySkcSessionId(normalizedSessionId, "getSkillActiveStatePaths");
+	const sessionPath = activeSnapshotPath(cwd, normalizedSessionId);
+	return { rootPath: sessionPath, sessionPath };
 }
 
 /**
@@ -380,7 +383,12 @@ async function readRawActiveStateForHandoff(filePath: string, strict: boolean):
 		if (!parsed || typeof parsed !== "object") return null;
 		return parsed as SkillActiveState;
 	} catch (err) {
-		if (!strict) return null;
+		if (!strict) {
+			logger.warn(
+				`skc skill-state: invalid skill-active-state at ${filePath}: invalid JSON: ${(err as Error).message}`,
+			);
+			return null;
+		}
 		throw err;
 	}
 }
@@ -419,14 +427,10 @@ function rawActiveEntries(state: SkillActiveState | null): SkillActiveEntry[] {
 
 async function readModeStatePhase(
 	cwd: string,
-	sessionId: string | undefined,
+	sessionId: string,
 	skill: CanonicalSkcWorkflowSkill,
 ): Promise<string | undefined> {
-	const stateDir = path.join(cwd, ".skc", "state");
-	const normalizedSessionId = safeString(sessionId).trim();
-	const filePath = normalizedSessionId
-		? path.join(stateDir, "sessions", encodePathSegment(normalizedSessionId), `${skill}-state.json`)
-		: path.join(stateDir, `${skill}-state.json`);
+	const filePath = modeStatePath(cwd, sessionId, skill);
 	try {
 		const parsed = JSON.parse(await Bun.file(filePath).text());
 		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
@@ -473,15 +477,6 @@ function withCanonicalRalplanPhase(entry: SkillActiveEntry, canonicalPhase: stri
 	};
 }
 
-function filterRootEntriesForSession(entries: SkillActiveEntry[], sessionId?: string): SkillActiveEntry[] {
-	const normalizedSessionId = safeString(sessionId).trim();
-	if (!normalizedSessionId) return entries;
-	return entries.filter(entry => {
-		const entrySessionId = safeString(entry.session_id).trim();
-		return entrySessionId.length === 0 || entrySessionId === normalizedSessionId;
-	});
-}
-
 function entryRecency(entry: SkillActiveEntry): number {
 	const stamp = entry.handoff_at || entry.updated_at || entry.activated_at;
 	const ms = stamp ? Date.parse(stamp) : Number.NaN;
@@ -559,94 +554,94 @@ function dedupeVisibleBySkill(entries: SkillActiveEntry[], sessionId?: string):
 
 /**
  * The planning pipeline advances one stage at a time: `deep-interview →
- * ralplan → ultragoal`. Each stage is activated through its own command path
- * (`skc deep-interview`, `skc ralplan`, `skc ultragoal`), and those activations
- * do not demote the previous stage's row — only the explicit `handoff` verb
- * does. Without this collapse, activating ultragoal while ralplan is still
- * `active:true` would render both stages and keep showing a workflow that has
- * already handed control forward. Keep only the most recently updated pipeline
- * stage so the HUD reflects the single current workflow. `team` is intentionally
- * excluded — it runs alongside ultragoal — and every non-pipeline skill is left
- * untouched.
- *
- * This is a HUD-display policy only. It is applied by the skill HUD renderer and
- * deliberately NOT folded into `readVisibleSkillActiveState`, whose callers (the
- * deep-interview mutation guard and handoff caller inference) must keep seeing
- * every genuinely-active skill rather than the single most-recent pipeline stage.
+ * ralplan → ultragoal`. Activating a downstream stage supersedes upstream
+ * stages so stale rows cannot keep owning the HUD, gate, or primary active
+ * snapshot. `team` is intentionally excluded — it runs alongside ultragoal —
+ * and every non-pipeline skill is left untouched.
  */
 const PLANNING_PIPELINE_SKILLS = new Set<string>(["deep-interview", "ralplan", "ultragoal"]);
+const PLANNING_PIPELINE_RANK = new Map<string, number>([
+	["deep-interview", 0],
+	["ralplan", 1],
+	["ultragoal", 2],
+]);
+
+function planningPipelineRank(skill: string): number | undefined {
+	return PLANNING_PIPELINE_RANK.get(skill);
+}
+
+function comparePipelineEntry(a: SkillActiveEntry, b: SkillActiveEntry): number {
+	const aRank = planningPipelineRank(a.skill);
+	const bRank = planningPipelineRank(b.skill);
+	if (aRank !== undefined || bRank !== undefined) return (bRank ?? -1) - (aRank ?? -1);
+	const aRecency = entryRecency(a);
+	const bRecency = entryRecency(b);
+	if (Number.isFinite(aRecency) || Number.isFinite(bRecency)) return (bRecency || 0) - (aRecency || 0);
+	return 0;
+}
+
+function upstreamPlanningPipelineSkills(skill: string): string[] {
+	const rank = planningPipelineRank(skill);
+	if (rank === undefined) return [];
+	return [...PLANNING_PIPELINE_RANK.entries()]
+		.filter(([, candidateRank]) => candidateRank < rank)
+		.map(([candidate]) => candidate);
+}
 
 export function collapsePlanningPipeline(entries: readonly SkillActiveEntry[]): SkillActiveEntry[] {
 	const pipeline = entries.filter(entry => PLANNING_PIPELINE_SKILLS.has(entry.skill));
 	if (pipeline.length <= 1) return [...entries];
-	let current = pipeline[0];
-	let currentRecency = entryRecency(current);
-	for (const entry of pipeline) {
-		const recency = entryRecency(entry);
-		// Prefer a strictly-newer valid timestamp; a valid timestamp also beats a
-		// missing/unparseable one. Ties (or all-invalid) keep the first stage
-		// deterministically rather than letting an unknown-recency row win.
-		const better = Number.isFinite(recency) && (!Number.isFinite(currentRecency) || recency > currentRecency);
-		if (better) {
-			current = entry;
-			currentRecency = recency;
-		}
-	}
+	const current = pipeline.toSorted(comparePipelineEntry)[0];
 	return entries.filter(entry => !PLANNING_PIPELINE_SKILLS.has(entry.skill) || entry === current);
 }
 
 async function mergeVisibleEntries(
 	cwd: string,
 	sessionState: SkillActiveState | null,
-	rootState: SkillActiveState | null,
-	sessionId?: string,
+	sessionId: string,
 ): Promise<SkillActiveEntry[]> {
 	// Use the raw (active + inactive) rows so a handoff demotion stays visible
 	// long enough to supersede a stale same-skill row before the active filter.
 	// Per-skill files in active/<skill>.json are authoritative and are merged
 	// after the derived snapshot cache, so a stale skill-active-state.json row
 	// cannot override the latest entry file.
-	const rootEntries = filterRootEntriesForSession(
-		[...rawActiveEntries(rootState), ...(await readActiveEntries(cwd))],
-		sessionId,
-	);
-	const merged = new Map(rootEntries.map(entry => [entryKey(entry), entry]));
-	const sessionEntries = sessionId
-		? [...rawActiveEntries(sessionState), ...(await readActiveEntries(cwd, { sessionId }))]
-		: rawActiveEntries(sessionState);
-	for (const entry of sessionEntries) {
-		merged.set(entryKey(entry), entry);
-	}
+	const entries = [...rawActiveEntries(sessionState), ...(await readActiveEntries(cwd, { sessionId }))];
+	const merged = new Map(entries.map(entry => [entryKey(entry), entry]));
 	const canonicalRalplanPhase = await readModeStatePhase(cwd, sessionId, "ralplan");
-	return dedupeVisibleBySkill([...merged.values()], sessionId)
+	const visibleEntries = dedupeVisibleBySkill([...merged.values()], sessionId)
 		.filter(entry => entry.active !== false)
 		.map(entry => withCanonicalRalplanPhase(entry, canonicalRalplanPhase));
+	return collapsePlanningPipeline(visibleEntries).toSorted(comparePipelineEntry);
 }
 
 export async function readVisibleSkillActiveState(cwd: string, sessionId?: string): Promise<SkillActiveState | null> {
-	const { rootPath, sessionPath } = getSkillActiveStatePaths(cwd, sessionId);
-	const [rootState, sessionState] = await Promise.all([
-		readRawActiveStateForHandoff(rootPath, false),
-		sessionPath ? readRawActiveStateForHandoff(sessionPath, false) : Promise.resolve(null),
-	]);
-	const activeSkills = await mergeVisibleEntries(cwd, sessionState, rootState, sessionId);
+	let resolvedSessionId: string;
+	try {
+		resolvedSessionId = await resolveBoundarySessionId(cwd, sessionId);
+	} catch (error) {
+		if (error instanceof SessionResolutionError && error.code === "no_session") return null;
+		throw error;
+	}
+	const { sessionPath } = getSkillActiveStatePaths(cwd, resolvedSessionId);
+	const sessionState = await readRawActiveStateForHandoff(sessionPath, false);
+	const activeSkills = await mergeVisibleEntries(cwd, sessionState, resolvedSessionId);
 	if (activeSkills.length === 0) return null;
 	const primary = activeSkills[0];
 	return {
-		...(rootState ?? {}),
 		...(sessionState ?? {}),
 		version: 1,
 		active: true,
-		skill: primary?.skill ?? "",
-		phase: primary?.phase ?? "",
-		session_id: safeString(sessionId).trim() || primary?.session_id,
+		skill: sessionState?.skill ?? primary?.skill ?? "",
+		phase: sessionState?.phase ?? primary?.phase ?? "",
+		session_id: resolvedSessionId,
 		active_skills: activeSkills,
 		active_subskills: activeSkills.flatMap(entry => entry.active_subskills ?? []),
 	};
 }
 
-function activeStateWriterAudit(verb: string) {
-	return { category: "state" as const, verb, owner: "skc-runtime" as const };
+function activeStateWriterAudit(verb: string, sessionScope?: ActiveSessionScope | string) {
+	const sessionId = typeof sessionScope === "string" ? sessionScope : sessionScope?.sessionId;
+	return { category: "state" as const, verb, owner: "skc-runtime" as const, ...(sessionId ? { sessionId } : {}) };
 }
 
 async function persistActiveEntry(
@@ -657,12 +652,13 @@ async function persistActiveEntry(
 	if (entry.active === false) {
 		await removeActiveEntry(cwd, sessionScope, entry.skill, {
 			cwd,
-			audit: activeStateWriterAudit("remove-active-entry"),
+			audit: activeStateWriterAudit("remove-active-entry", sessionScope),
+			sourceRevision: entry.source_state_revision,
 		});
 	} else {
 		await writeActiveEntry(cwd, sessionScope, entry.skill, entry, {
 			cwd,
-			audit: activeStateWriterAudit("write-active-entry"),
+			audit: activeStateWriterAudit("write-active-entry", sessionScope),
 		});
 	}
 }
@@ -674,12 +670,29 @@ async function writeHandoffEntry(
 ): Promise<void> {
 	await writeActiveEntry(cwd, sessionScope, entry.skill, entry, {
 		cwd,
-		audit: activeStateWriterAudit("write-active-entry"),
+		audit: activeStateWriterAudit("write-active-entry", sessionScope),
 	});
 }
 
 async function rebuildActiveState(cwd: string, sessionScope?: ActiveSessionScope): Promise<void> {
-	await rebuildActiveSnapshot(cwd, sessionScope, { cwd, audit: activeStateWriterAudit("rebuild-active-snapshot") });
+	await rebuildActiveSnapshot(cwd, sessionScope, {
+		cwd,
+		audit: activeStateWriterAudit("rebuild-active-snapshot", sessionScope),
+	});
+}
+
+async function removeSupersededPlanningPipelineEntries(
+	cwd: string,
+	sessionScope: ActiveSessionScope | undefined,
+	entry: SkillActiveEntry,
+): Promise<void> {
+	if (entry.active === false) return;
+	for (const skill of upstreamPlanningPipelineSkills(entry.skill)) {
+		await removeActiveEntry(cwd, sessionScope, skill, {
+			cwd,
+			audit: activeStateWriterAudit("remove-superseded-pipeline-entry", sessionScope),
+		});
+	}
 }
 
 async function activeSubskillsForExistingEntry(
@@ -687,18 +700,17 @@ async function activeSubskillsForExistingEntry(
 	sessionId: string | undefined,
 	skill: string,
 ): Promise<ActiveSubskillEntry[] | undefined> {
-	const { rootPath, sessionPath } = getSkillActiveStatePaths(cwd, sessionId);
-	const [rootState, sessionState] = await Promise.all([
-		readRawActiveStateForHandoff(rootPath, false),
-		sessionPath ? readRawActiveStateForHandoff(sessionPath, false) : Promise.resolve(null),
-	]);
-	const existing = (await mergeVisibleEntries(cwd, sessionState, rootState, sessionId)).find(
+	const resolvedSessionId = await resolveBoundarySessionId(cwd, sessionId);
+	const { sessionPath } = getSkillActiveStatePaths(cwd, resolvedSessionId);
+	const sessionState = await readRawActiveStateForHandoff(sessionPath, false);
+	const existing = (await mergeVisibleEntries(cwd, sessionState, resolvedSessionId)).find(
 		entry => entry.skill === skill,
 	);
 	return existing?.active_subskills;
 }
 
 export async function syncSkillActiveState(options: SyncSkillActiveStateOptions): Promise<void> {
+	if (!options.sessionId) return;
 	const preservedActiveSubskills =
 		options.active_subskills === undefined
 			? await activeSubskillsForExistingEntry(options.cwd, options.sessionId, options.skill)
@@ -724,12 +736,10 @@ export async function syncSkillActiveState(options: SyncSkillActiveStateOptions)
 			: preservedActiveSubskills
 				? { active_subskills: preservedActiveSubskills }
 				: {}),
+		...(typeof options.sourceRevision === "number" ? { source_state_revision: options.sourceRevision } : {}),
 	};
-	await persistActiveEntry(options.cwd, undefined, entry);
-	await rebuildActiveState(options.cwd);
-
-	if (!options.sessionId) return;
 	const sessionScope = { sessionId: options.sessionId };
+	await removeSupersededPlanningPipelineEntries(options.cwd, sessionScope, entry);
 	await persistActiveEntry(options.cwd, sessionScope, entry);
 	await rebuildActiveState(options.cwd, sessionScope);
 }
@@ -745,36 +755,23 @@ export interface ApplyHandoffOptions {
 }
 
 /**
- * Atomically apply a workflow-skill handoff to both the session-scoped and
- * root `skill-active-state.json` files in a single write per file.
- *
- * Write order: **session first, root last**. The session file is the
- * source of truth for HUD; the root aggregate must never lead the session
- * during a handoff window. Each file is rewritten once with caller demoted
- * to `active:false` (preserving `handoff_to`/`handoff_at` lineage) and
- * callee promoted to `active:true` (with `handoff_from`/`handoff_at`).
+ * Atomically apply a workflow-skill handoff to the session-scoped active state.
  */
 export async function applyHandoffToActiveState(options: ApplyHandoffOptions): Promise<void> {
 	const nowIso = options.nowIso ?? new Date().toISOString();
 	const callerEntry = buildSyncEntry(options.caller, nowIso);
 	const calleeEntry = buildSyncEntry(options.callee, nowIso);
 	const sessionId = options.callee.sessionId ?? options.caller.sessionId;
-	const { rootPath, sessionPath } = getSkillActiveStatePaths(options.cwd, sessionId);
+	assertNonEmptySkcSessionId(sessionId, "applyHandoffToActiveState");
+	const { sessionPath } = getSkillActiveStatePaths(options.cwd, sessionId);
 	const readState = (filePath: string) => readRawActiveStateForHandoff(filePath, options.strict === true);
-	await Promise.all([readState(rootPath), ...(sessionPath ? [readState(sessionPath)] : [])]);
-
-	// A skill can hold more than one visible row in this session's scope — e.g.
-	// it was seeded without a session id (rendered globally) and is now handed
-	// off under a concrete session id. Supersede every same-session-scope row of
-	// the caller and callee skills, not just the exact `skill::session_id` key,
-	// so a stale `active:true` row cannot survive the demotion and keep showing
-	// in the HUD. Rows owned by other sessions are left untouched.
+	await readState(sessionPath);
+
 	const handoffSession = safeString(sessionId).trim();
 	const reassignedSkills = new Set([callerEntry.skill, calleeEntry.skill]);
 	const supersedesVisible = (entry: SkillActiveEntry): boolean => {
 		if (!reassignedSkills.has(entry.skill)) return false;
-		const entrySession = safeString(entry.session_id).trim();
-		return entrySession.length === 0 || entrySession === handoffSession;
+		return safeString(entry.session_id).trim() === handoffSession;
 	};
 	const applyEntries = (entries: SkillActiveEntry[]): SkillActiveEntry[] => {
 		const callerKey = entryKey(callerEntry);
@@ -782,9 +779,6 @@ export async function applyHandoffToActiveState(options: ApplyHandoffOptions): P
 			entries.find(e => entryKey(e) === callerKey) ??
 			entries.find(e => e.skill === callerEntry.skill && supersedesVisible(e) && Boolean(e.handoff_from));
 		const kept = entries.filter(e => !supersedesVisible(e));
-		// Merge prior lineage into the demoted caller so multi-step handoff
-		// chains preserve `handoff_from` from the previous transition while
-		// the new `handoff_to`/`handoff_at` describe this one.
 		const mergedCaller: SkillActiveEntry = priorCaller
 			? {
 					...callerEntry,
@@ -799,10 +793,7 @@ export async function applyHandoffToActiveState(options: ApplyHandoffOptions): P
 			activeSubskills.length > 0 ? { ...calleeEntry, active_subskills: activeSubskills } : calleeEntry;
 		return [...kept, mergedCaller, mergedCallee];
 	};
-	const writeEntries = async (
-		sessionScope: ActiveSessionScope | undefined,
-		prior: SkillActiveState | null,
-	): Promise<void> => {
+	const writeEntries = async (sessionScope: ActiveSessionScope, prior: SkillActiveState | null): Promise<void> => {
 		const nextEntries = applyEntries(rawActiveEntries(prior));
 		for (const entry of nextEntries) {
 			await writeHandoffEntry(options.cwd, sessionScope, entry);
@@ -810,12 +801,8 @@ export async function applyHandoffToActiveState(options: ApplyHandoffOptions): P
 		await rebuildActiveState(options.cwd, sessionScope);
 	};
 
-	if (sessionPath) {
-		const prior = await readState(sessionPath);
-		await writeEntries({ sessionId }, prior);
-	}
-	const priorRoot = await readState(rootPath);
-	await writeEntries(undefined, priorRoot);
+	const prior = await readState(sessionPath);
+	await writeEntries({ sessionId }, prior);
 }
 
 function buildSyncEntry(options: SyncSkillActiveStateOptions, nowIso: string): SkillActiveEntry {

package/src/skill-state/canonical-skills.ts

@@ -0,0 +1,4 @@
+/** Native-free canonical SKC workflow skill identifiers. */
+export const CANONICAL_SKC_WORKFLOW_SKILLS = ["deep-interview", "ralplan", "ultragoal", "team"] as const;
+
+export type CanonicalSkcWorkflowSkill = (typeof CANONICAL_SKC_WORKFLOW_SKILLS)[number];