@gajae-code/coding-agent 0.6.3 → 0.6.5

package/src/runtime-mcp/config-writer.ts

@@ -149,6 +149,52 @@ export async function updateMCPServer(filePath: string, name: string, config: MC
 	await writeMCPConfigFile(filePath, updated);
 }
 
+/**
+ * Result of an {@link upsertMCPServer} call.
+ * - `added`: server did not exist and was written.
+ * - `updated`: server existed and was overwritten because `force` was set.
+ * - `skipped`: server existed and `force` was not set, so nothing was written.
+ */
+export type UpsertMCPServerResult =
+	| { status: "added" }
+	| { status: "updated" }
+	| { status: "skipped"; reason: "exists" };
+
+/**
+ * Add an MCP server, or overwrite an existing one only when `force` is set.
+ *
+ * Collision-aware wrapper over {@link addMCPServer} / {@link updateMCPServer} used by
+ * `gjc migrate`. Never connects to the server. Reuses the underlying writers so the
+ * rest of the config file (including `disabledServers`) is preserved on update.
+ *
+ * @throws Error if the server name or config is invalid (validated before any write).
+ */
+export async function upsertMCPServer(
+	filePath: string,
+	name: string,
+	config: MCPServerConfig,
+	options: { force?: boolean } = {},
+): Promise<UpsertMCPServerResult> {
+	// Validate name up front so an invalid name fails regardless of collision state.
+	const nameError = validateServerName(name);
+	if (nameError) {
+		throw new Error(nameError);
+	}
+
+	const existing = await getMCPServer(filePath, name);
+	if (existing) {
+		if (!options.force) {
+			return { status: "skipped", reason: "exists" };
+		}
+		// updateMCPServer preserves the rest of MCPConfigFile, incl. disabledServers.
+		await updateMCPServer(filePath, name, config);
+		return { status: "updated" };
+	}
+
+	await addMCPServer(filePath, name, config);
+	return { status: "added" };
+}
+
 /**
  * Remove an MCP server from a config file.
  *

package/src/session/agent-session.ts

@@ -183,6 +183,11 @@ import type { HookCommandContext } from "../extensibility/hooks/types";
 import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
 import { buildGjcRuntimeSessionEnv, consumePendingGoalModeRequest } from "../gjc-runtime/goal-mode-request";
+import {
+	assertNonEmptyGjcSessionId,
+	modeStatePath as sessionModeStatePath,
+	sessionStateDir,
+} from "../gjc-runtime/session-layout";
 import { persistCoordinatorRuntimeStateFromEvent } from "../gjc-runtime/session-state-sidecar";
 import { writeArtifact } from "../gjc-runtime/state-writer";
 import { requestGjcWorkerIntegrationAttempt } from "../gjc-runtime/team-runtime";
@@ -312,13 +317,6 @@ export type AgentSessionEvent =
 	| { type: "thinking_level_changed"; thinkingLevel: ThinkingLevel | undefined }
 	| { type: "goal_updated"; goal: Goal | null; state?: GoalModeState };
 
-/**
- * Safe path component pattern used to validate session-id segments before
- * joining them into `.gjc/state` paths. Mirrors the regex used by the
- * `gjc state` runtime selector resolver.
- */
-const SAFE_PATH_COMPONENT = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
-
 function isUnderProjectGjc(cwd: string, targetPath: string): boolean {
 	const relative = path.relative(path.join(path.resolve(cwd), ".gjc"), path.resolve(targetPath));
 	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
@@ -1370,21 +1368,17 @@ export class AgentSession {
 	getActiveSkillPhase(): string | undefined {
 		const active = this.#activeSkillState;
 		if (!active) return undefined;
-		// Path safety: refuse to read mode-state files when the skill or
-		// session-id are not safe path components. The `skill` tool
-		// interprets undefined as a non-terminal phase, so chaining is
-		// refused — there is no risk of bypassing the guard via a custom
-		// skill name with `..` or a session-id with separators.
 		if (!isCanonicalGjcWorkflowSkill(active.skill)) return undefined;
-		if (active.sessionId !== undefined && !SAFE_PATH_COMPONENT.test(active.sessionId)) {
-			return undefined;
-		}
+		const sessionId = active.sessionId ?? this.sessionManager.getSessionId();
 		try {
-			const stateDir = path.join(this.sessionManager.getCwd(), ".gjc", "state");
-			const segments = active.sessionId
-				? [stateDir, "sessions", encodeURIComponent(active.sessionId).replaceAll(".", "%2E")]
-				: [stateDir];
-			const filePath = path.join(...segments, `${active.skill}-state.json`);
+			assertNonEmptyGjcSessionId(sessionId, "AgentSession.getActiveSkillPhase");
+			// Keep the session-state-dir construction explicit here so the chain guard
+			// refuses to fall back to a legacy root `.gjc/state` read.
+			const stateDir = sessionStateDir(this.sessionManager.getCwd(), sessionId);
+			const filePath = path.join(
+				stateDir,
+				path.basename(sessionModeStatePath(this.sessionManager.getCwd(), sessionId, active.skill)),
+			);
 			const raw = fs.readFileSync(filePath, "utf-8");
 			const parsed = JSON.parse(raw) as { current_phase?: unknown };
 			return typeof parsed.current_phase === "string" ? parsed.current_phase : undefined;
@@ -3763,7 +3757,7 @@ export class AgentSession {
 	 * prompts or tool execution can run.
 	 */
 	#wrapToolForDeepInterviewMutationGuard<T extends AgentTool>(tool: T): T {
-		if (!["edit", "write", "ast_edit", "bash"].includes(tool.name)) return tool;
+		if (!["edit", "write", "ast_edit"].includes(tool.name)) return tool;
 		return new Proxy(tool, {
 			get: (target, prop) => {
 				if (prop !== "execute") return Reflect.get(target, prop, target);

package/src/session/session-manager.ts

@@ -1129,6 +1129,23 @@ function formatTimeAgo(date: Date): string {
 	return date.toLocaleDateString();
 }
 
+async function movePathAcrossDevicesSafe(source: string, destination: string): Promise<void> {
+	try {
+		await fs.promises.rename(source, destination);
+		return;
+	} catch (error) {
+		if (!hasFsCode(error, "EXDEV")) throw error;
+	}
+	const stat = await fs.promises.stat(source);
+	if (stat.isDirectory()) {
+		await fs.promises.cp(source, destination, { recursive: true, force: false, errorOnExist: true });
+		await fs.promises.rm(source, { recursive: true, force: false });
+		return;
+	}
+	await fs.promises.copyFile(source, destination, fs.constants.COPYFILE_EXCL);
+	await fs.promises.unlink(source);
+}
+
 const MAX_PERSIST_CHARS = 500_000;
 const TRUNCATION_NOTICE = "\n\n[Session persistence truncated large content]";
 /** Minimum base64 length to externalize to blob store (skip tiny inline images) */
@@ -2498,14 +2515,14 @@ export class SessionManager {
 			try {
 				// Guard: session file may not exist yet (no assistant messages persisted)
 				if (hadSessionFile) {
-					await fs.promises.rename(oldSessionFile, newSessionFile);
+					await movePathAcrossDevicesSafe(oldSessionFile, newSessionFile);
 					movedSessionFile = true;
 				}
 
 				try {
 					const stat = await fs.promises.stat(oldArtifactDir);
 					if (stat.isDirectory()) {
-						await fs.promises.rename(oldArtifactDir, newArtifactDir);
+						await movePathAcrossDevicesSafe(oldArtifactDir, newArtifactDir);
 						movedArtifactDir = true;
 					}
 				} catch (err) {

package/src/setup/hermes/templates/operator-instructions.v1.md

@@ -29,6 +29,14 @@ The Hermes bridge does not choose a model/provider. Generated setup configures `
 
 Provider-specific commands are examples only, never product defaults.
 
+## Visible routed-session fallback
+
+If a Hermes/OpenClaw/Clawhip-style operator needs a human-visible, channel-routed GJC pane instead of a pure Coordinator MCP session, use the visible session pattern in [`docs/gjc-session-clawhip-routing.md`](../../../../../../docs/gjc-session-clawhip-routing.md).
+
+Use that pattern only when the router must watch tmux output, send stale-session alerts, or inject follow-up prompts into the same visible pane. The short version is: prepare a dedicated worktree, register a stable tmux session through the host router, start interactive `gjc`, wait for TUI readiness, inject the task prompt separately, and verify actual tool/work activity before reporting acceptance.
+
+Do not put private channel ids, mention targets, socket names, tokens, or local routing policy into portable setup output. Keep those in the host/operator deployment.
+
 ## Safety
 
 - Mutating tools require bridge startup mutation classes and per-call consent.

package/src/setup/hermes-setup.ts

@@ -404,7 +404,7 @@ async function installConfig(spec: CoordinatorSetupSpec, force: boolean): Promis
 
 async function runSmoke(spec: CoordinatorSetupSpec): Promise<HermesSetupResult["smoke"]> {
 	const requiredTools = [...COORDINATOR_MCP_TOOL_NAMES];
-	const server = createCoordinatorMcpServer({ env: {} });
+	const server = createCoordinatorMcpServer({ env: renderHermesServerBlock(spec).env as NodeJS.ProcessEnv });
 	const listed = await server.handleJsonRpc({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} });
 	const listedResult = isRecord(listed.result) ? listed.result : {};
 	const tools = Array.isArray(listedResult.tools) ? listedResult.tools : [];

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

@@ -1,4 +1,6 @@
-import * as path from "node:path";
+import * as logger from "@gajae-code/utils/logger";
+import { activeSnapshotPath, assertNonEmptyGjcSessionId, modeStatePath } from "../gjc-runtime/session-layout";
+import { resolveGjcSessionForRead, SessionResolutionError } from "../gjc-runtime/session-resolution";
 import {
 	type ActiveSessionScope,
 	readActiveEntries,
@@ -6,13 +8,12 @@ import {
 	removeActiveEntry,
 	writeActiveEntry,
 } from "../gjc-runtime/state-writer";
+import { CANONICAL_GJC_WORKFLOW_SKILLS, type CanonicalGjcWorkflowSkill } from "./canonical-skills";
 import type { WorkflowStateReceipt } from "./workflow-state-contract";
 
 export const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
 
-export const CANONICAL_GJC_WORKFLOW_SKILLS = ["deep-interview", "ralplan", "ultragoal", "team"] as const;
-
-export type CanonicalGjcWorkflowSkill = (typeof CANONICAL_GJC_WORKFLOW_SKILLS)[number];
+export { CANONICAL_GJC_WORKFLOW_SKILLS, type CanonicalGjcWorkflowSkill };
 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 resolveGjcSessionForRead(cwd, { envSessionId: process.env.GJC_SESSION_ID }).then(
+		context => context.gjcSessionId,
+	);
 }
 
 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, ".gjc", "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),
-	};
+	assertNonEmptyGjcSessionId(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(
+				`gjc 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: CanonicalGjcWorkflowSkill,
 ): Promise<string | undefined> {
-	const stateDir = path.join(cwd, ".gjc", "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;
@@ -603,57 +598,50 @@ export function collapsePlanningPipeline(entries: readonly SkillActiveEntry[]):
 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 collapsePlanningPipeline(
-		dedupeVisibleBySkill([...merged.values()], sessionId)
-			.filter(entry => entry.active !== false)
-			.map(entry => withCanonicalRalplanPhase(entry, canonicalRalplanPhase)),
-	);
+	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: "gjc-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: "gjc-runtime" as const, ...(sessionId ? { sessionId } : {}) };
 }
 
 async function persistActiveEntry(
@@ -664,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),
 		});
 	}
 }
@@ -681,12 +670,15 @@ 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(
@@ -698,7 +690,7 @@ async function removeSupersededPlanningPipelineEntries(
 	for (const skill of upstreamPlanningPipelineSkills(entry.skill)) {
 		await removeActiveEntry(cwd, sessionScope, skill, {
 			cwd,
-			audit: activeStateWriterAudit("remove-superseded-pipeline-entry"),
+			audit: activeStateWriterAudit("remove-superseded-pipeline-entry", sessionScope),
 		});
 	}
 }
@@ -708,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)
@@ -745,12 +736,8 @@ export async function syncSkillActiveState(options: SyncSkillActiveStateOptions)
 			: preservedActiveSubskills
 				? { active_subskills: preservedActiveSubskills }
 				: {}),
+		...(typeof options.sourceRevision === "number" ? { source_state_revision: options.sourceRevision } : {}),
 	};
-	await removeSupersededPlanningPipelineEntries(options.cwd, undefined, entry);
-	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);
@@ -768,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);
+	assertNonEmptyGjcSessionId(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);
@@ -805,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,
@@ -822,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);
@@ -833,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 GJC workflow skill identifiers. */
+export const CANONICAL_GJC_WORKFLOW_SKILLS = ["deep-interview", "ralplan", "ultragoal", "team"] as const;
+
+export type CanonicalGjcWorkflowSkill = (typeof CANONICAL_GJC_WORKFLOW_SKILLS)[number];