@gajae-code/coding-agent 0.11.1 → 0.11.2

package/src/harness-control-plane/session-lease.ts

@@ -9,6 +9,8 @@
 import { createHash, randomBytes } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { withFileLock } from "../config/file-lock";
+
 import { controlSocketPath, sessionPaths } from "./storage";
 
 export interface SessionLease {
@@ -51,21 +53,8 @@ async function writeLeaseAtomic(file: string, lease: SessionLease): Promise<void
 	await fs.writeFile(tmp, `${JSON.stringify(lease, null, 2)}\n`, "utf8");
 	await fs.rename(tmp, file);
 }
-const LEASE_LOCK_RETRIES = 100;
-const LEASE_LOCK_RETRY_DELAY_MS = 20;
-const LEASE_LOCK_FILE_SUFFIX = ".json";
-
-interface LeaseLockInfo {
-	pid: number;
-	token: string;
-}
-
 function leaseMutationLockPath(root: string, sessionId: string): string {
-	return `${sessionPaths(root, sessionId).lease}.lock`;
-}
-
-function leaseMutationLockFile(lockPath: string, token: string): string {
-	return path.join(lockPath, `${token}${LEASE_LOCK_FILE_SUFFIX}`);
+	return sessionPaths(root, sessionId).lease;
 }
 
 function isOwnedUnixEndpointPath(root: string, sessionId: string, endpointPath: string, fallbackPath: string): boolean {
@@ -77,128 +66,21 @@ function isOwnedUnixEndpointPath(root: string, sessionId: string, endpointPath:
 		return false;
 	}
 }
-
-function isPathExistsError(error: unknown): boolean {
-	const code = (error as NodeJS.ErrnoException).code;
-	return code === "EEXIST" || code === "ENOTEMPTY" || code === "EISDIR" || code === "ENOTDIR";
-}
-
-function isIgnorableLockDirRemoveError(error: unknown): boolean {
-	const code = (error as NodeJS.ErrnoException).code;
-	return code === "ENOENT" || code === "ENOTEMPTY" || code === "EEXIST";
-}
-
-async function removeEmptyLockDir(lockPath: string): Promise<void> {
-	try {
-		await fs.rmdir(lockPath);
-	} catch (error) {
-		if (!isIgnorableLockDirRemoveError(error)) throw error;
-	}
-}
-
-function parseLeaseLockInfo(raw: string): LeaseLockInfo | null {
-	try {
-		const parsed = JSON.parse(raw) as unknown;
-		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-		const info = parsed as Record<string, unknown>;
-		return typeof info.pid === "number" && typeof info.token === "string"
-			? { pid: info.pid, token: info.token }
-			: null;
-	} catch {
-		return null;
-	}
-}
-
-async function readLeaseLockInfo(lockFile: string): Promise<LeaseLockInfo | null> {
-	try {
-		return parseLeaseLockInfo(await fs.readFile(lockFile, "utf8"));
-	} catch {
-		return null;
-	}
-}
-
-async function createLeaseMutationLock(lockPath: string, info: LeaseLockInfo): Promise<boolean> {
-	const tmpPath = `${lockPath}.tmp-${info.token}`;
-	await fs.rm(tmpPath, { recursive: true, force: true });
-	await fs.mkdir(tmpPath, { mode: 0o700 });
+async function withLeaseMutationLock<T>(root: string, sessionId: string, fn: () => Promise<T>): Promise<T> {
+	const lockPath = leaseMutationLockPath(root, sessionId);
+	await fs.mkdir(path.dirname(lockPath), { recursive: true });
 	try {
-		await fs.writeFile(leaseMutationLockFile(tmpPath, info.token), `${JSON.stringify(info)}\n`, {
-			encoding: "utf8",
-			mode: 0o600,
+		return await withFileLock(lockPath, fn, {
+			staleMs: 30_000,
+			retries: 100,
+			retryDelayMs: 20,
 		});
-		await fs.rename(tmpPath, lockPath);
-		return true;
-	} catch (error) {
-		await fs.rm(tmpPath, { recursive: true, force: true });
-		if (isPathExistsError(error)) return false;
-		throw error;
-	}
-}
-
-async function recoverLegacyStaleLeaseLock(lockPath: string): Promise<void> {
-	const info = await readLeaseLockInfo(lockPath);
-	if (!info || defaultPidStatusProbe(info.pid) !== "dead") return;
-	try {
-		await fs.unlink(lockPath);
 	} catch (error) {
-		const code = (error as NodeJS.ErrnoException).code;
-		if (code !== "ENOENT" && code !== "EISDIR") throw error;
-	}
-}
-
-async function recoverStaleLeaseMutationLock(lockPath: string): Promise<void> {
-	let entries: string[];
-	try {
-		entries = await fs.readdir(lockPath);
-	} catch (error) {
-		const code = (error as NodeJS.ErrnoException).code;
-		if (code === "ENOENT") return;
-		if (code === "ENOTDIR") {
-			await recoverLegacyStaleLeaseLock(lockPath);
-			return;
+		if (error instanceof Error && error.message.startsWith("Failed to acquire lock")) {
+			throw new LeaseError(`lease_lock_timeout:${sessionId}`, "lease_lock_timeout");
 		}
 		throw error;
 	}
-	const lockFiles = entries.filter(entry => entry.endsWith(LEASE_LOCK_FILE_SUFFIX));
-	if (lockFiles.length === 0) {
-		await removeEmptyLockDir(lockPath);
-		return;
-	}
-	if (lockFiles.length !== 1) return;
-	const lockFile = lockFiles[0];
-	const info = await readLeaseLockInfo(path.join(lockPath, lockFile));
-	if (!info || lockFile !== `${info.token}${LEASE_LOCK_FILE_SUFFIX}`) return;
-	if (defaultPidStatusProbe(info.pid) !== "dead") return;
-	// Delete only the stale owner's token-named file; a fresh lock uses a different file name.
-	await fs.rm(path.join(lockPath, lockFile), { force: true });
-	await removeEmptyLockDir(lockPath);
-}
-
-async function releaseLeaseMutationLock(lockPath: string, token: string): Promise<void> {
-	await fs.rm(leaseMutationLockFile(lockPath, token), { force: true });
-	await removeEmptyLockDir(lockPath);
-}
-
-async function acquireLeaseMutationLock(root: string, sessionId: string): Promise<() => Promise<void>> {
-	const lockPath = leaseMutationLockPath(root, sessionId);
-	await fs.mkdir(path.dirname(lockPath), { recursive: true });
-	for (let attempt = 0; attempt < LEASE_LOCK_RETRIES; attempt++) {
-		const token = randomBytes(16).toString("hex");
-		const info: LeaseLockInfo = { pid: process.pid, token };
-		if (await createLeaseMutationLock(lockPath, info)) return () => releaseLeaseMutationLock(lockPath, token);
-		await recoverStaleLeaseMutationLock(lockPath);
-		await Bun.sleep(LEASE_LOCK_RETRY_DELAY_MS);
-	}
-	throw new LeaseError(`lease_lock_timeout:${sessionId}`, "lease_lock_timeout");
-}
-
-async function withLeaseMutationLock<T>(root: string, sessionId: string, fn: () => Promise<T>): Promise<T> {
-	const release = await acquireLeaseMutationLock(root, sessionId);
-	try {
-		return await fn();
-	} finally {
-		await release();
-	}
 }
 
 export async function readLease(root: string, sessionId: string): Promise<SessionLease | null> {

package/src/hindsight/backend.ts

@@ -48,23 +48,23 @@ export const hindsightBackend: MemoryBackend = {
 		if (options.taskDepth > 0) {
 			const parent = options.parentHindsightSessionState;
 			if (!parent) return;
-			const previous = session.setHindsightSessionState(
-				new HindsightSessionState({
-					sessionId,
-					client: parent.client,
-					bankId: parent.bankId,
-					retainTags: parent.retainTags,
-					recallTags: parent.recallTags,
-					recallTagsMatch: parent.recallTagsMatch,
-					config: parent.config,
-					session,
-					missionsSet: parent.missionsSet,
-					lastRetainedTurn: 0,
-					hasRecalledForFirstTurn: true,
-					aliasOf: parent,
-				}),
-			);
-			previous?.dispose();
+			const replacement = new HindsightSessionState({
+				sessionId,
+				client: parent.client,
+				bankId: parent.bankId,
+				retainTags: parent.retainTags,
+				recallTags: parent.recallTags,
+				recallTagsMatch: parent.recallTagsMatch,
+				config: parent.config,
+				session,
+				missionsSet: parent.missionsSet,
+				lastRetainedTurn: 0,
+				hasRecalledForFirstTurn: true,
+				aliasOf: parent,
+			});
+			const previous = session.getHindsightSessionState();
+			await previous?.dispose();
+			session.setHindsightSessionState(replacement);
 			return;
 		}
 
@@ -91,10 +91,12 @@ export const hindsightBackend: MemoryBackend = {
 			hasRecalledForFirstTurn: false,
 		});
 
-		// Cleanup any stale state for this session (defensive — prevents leaks
-		// when a session is reused without going through dispose).
-		const previous = session.setHindsightSessionState(state);
-		previous?.dispose();
+		// Close and drain the old queue while it still owns this session. Closing
+		// rejects concurrent enqueues, so no retain can land between the final flush
+		// and replacement.
+		const previous = session.getHindsightSessionState();
+		await previous?.dispose();
+		session.setHindsightSessionState(state);
 		state.attachSessionListeners();
 
 		// Kick off mental-model bootstrap. Resolves asynchronously; the first
@@ -114,15 +116,12 @@ export const hindsightBackend: MemoryBackend = {
 
 		const state = session?.getHindsightSessionState();
 		const primary = state?.aliasOf ?? state;
-		const recallSnippet = primary?.lastRecallSnippet;
 		const mentalModelsSnippet = primary?.mentalModelsSnippet;
 
-		// Order: static instructions → mental models (stable, curated) → recall
-		// (volatile per turn). Stable context first so the LLM's prior is
-		// anchored on curated knowledge.
+		// Static instructions and curated mental models are prefix-stable. Recall
+		// is injected by AgentSession as volatile user-role context instead.
 		const parts = [STATIC_INSTRUCTIONS];
 		if (mentalModelsSnippet) parts.push(mentalModelsSnippet);
-		if (recallSnippet) parts.push(recallSnippet);
 		return parts.join("\n\n");
 	},
 
@@ -141,7 +140,7 @@ export const hindsightBackend: MemoryBackend = {
 		const state = session?.getHindsightSessionState();
 		if (state) await state.flushRetainQueue();
 		const previous = session?.setHindsightSessionState(undefined);
-		previous?.dispose();
+		await previous?.dispose();
 		logger.warn(
 			"Hindsight memory is server-side; only the local recall cache was cleared. " +
 				"Delete the Hindsight bank from the UI to wipe upstream state.",

package/src/hindsight/state.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 import { logger } from "@gajae-code/utils";
 import type { AgentSession } from "../session/agent-session";
 import { type BankScope, ensureBankMission } from "./bank";
@@ -5,7 +7,6 @@ import type { HindsightApi, MemoryItemInput } from "./client";
 import type { HindsightConfig } from "./config";
 import {
 	composeRecallQuery,
-	formatCurrentTime,
 	formatMemories,
 	type HindsightMessage,
 	prepareRetentionTranscript,
@@ -105,33 +106,31 @@ export class HindsightRetainQueue {
 			this.#timer = undefined;
 		}
 
-		if (this.#flushing) {
-			// Coalesce: wait for the in-flight flush, then drain anything that
-			// landed after it started so we don't strand items.
-			await this.#flushing;
-			if (this.#items.length > 0) await this.flush();
-			return;
-		}
-
+		if (this.#flushing) return this.#flushing;
 		if (this.#items.length === 0) return;
 
-		const items = this.#items.splice(0);
-		const flushPromise = this.#doFlush(items);
-		this.#flushing = flushPromise;
+		this.#flushing = this.#flushLoop();
 		try {
-			await flushPromise;
+			await this.#flushing;
 		} finally {
 			this.#flushing = undefined;
 		}
 	}
 
-	dispose(): void {
+	async #flushLoop(): Promise<void> {
+		while (this.#items.length > 0) {
+			const items = this.#items.splice(0);
+			await this.#doFlush(items);
+		}
+	}
+
+	async dispose(): Promise<void> {
 		this.#closed = true;
 		if (this.#timer) {
 			clearTimeout(this.#timer);
 			this.#timer = undefined;
 		}
-		this.#items = [];
+		await this.flush();
 	}
 
 	async #doFlush(items: PendingRetainItem[]): Promise<void> {
@@ -202,6 +201,7 @@ export class HindsightSessionState {
 	lastRetainedTurn: number;
 	hasRecalledForFirstTurn: boolean;
 	lastRecallSnippet?: string;
+	lastInjectedRecallSnippetHash?: string;
 	/** Cached `<mental_models>` block injected into developer instructions. */
 	mentalModelsSnippet?: string;
 	/** When the cached snippet was last refreshed; gates the agent_end re-list. */
@@ -215,6 +215,9 @@ export class HindsightSessionState {
 	unsubscribe?: () => void;
 	/** Alias states delegate persistence config to a primary parent state. */
 	aliasOf?: HindsightSessionState;
+	/** One auto-retain may run at a time; one later agent_end is coalesced. */
+	#autoRetainInFlight?: Promise<void>;
+	#autoRetainPending = false;
 	readonly retainQueue: HindsightRetainQueue;
 
 	constructor(options: HindsightSessionStateOptions) {
@@ -241,6 +244,30 @@ export class HindsightSessionState {
 		this.lastRetainedTurn = 0;
 		this.hasRecalledForFirstTurn = false;
 		this.lastRecallSnippet = undefined;
+		this.lastInjectedRecallSnippetHash = undefined;
+	}
+
+	/** Return the current recall payload, resolving subagent aliases to their primary state. */
+	getRecallSnippet(): string | undefined {
+		return this.aliasOf ? this.aliasOf.getRecallSnippet() : this.lastRecallSnippet;
+	}
+	/** Return the current recall payload without consuming its one-shot injection eligibility. */
+	getRecallSnippetForInjection(): string | undefined {
+		if (this.aliasOf) return this.aliasOf.getRecallSnippetForInjection();
+		const snippet = this.lastRecallSnippet;
+		if (!snippet) return undefined;
+		const hash = createHash("sha256").update(snippet).digest("hex");
+		return hash === this.lastInjectedRecallSnippetHash ? undefined : snippet;
+	}
+
+	/** Mark a recall payload consumed only after it has been accepted for provider injection. */
+	markRecallSnippetInjected(snippet: string): boolean {
+		if (this.aliasOf) return this.aliasOf.markRecallSnippetInjected(snippet);
+		if (snippet !== this.lastRecallSnippet) return false;
+		const hash = createHash("sha256").update(snippet).digest("hex");
+		if (hash === this.lastInjectedRecallSnippetHash) return false;
+		this.lastInjectedRecallSnippetHash = hash;
+		return true;
 	}
 
 	enqueueRetain(content: string, context?: string): void {
@@ -264,7 +291,7 @@ export class HindsightSessionState {
 			const results = response.results ?? [];
 			if (results.length === 0) return { context: null, ok: true };
 			const formatted = formatMemories(results);
-			const block = `<memories>\n${this.config.recallPromptPreamble}\nCurrent time: ${formatCurrentTime()} UTC\n\n${formatted}\n</memories>`;
+			const block = `<memories>\n${this.config.recallPromptPreamble}\n\n${formatted}\n</memories>`;
 			return { context: block, ok: true };
 		} catch (err) {
 			if (this.config.debug) {
@@ -274,13 +301,14 @@ export class HindsightSessionState {
 		}
 	}
 
-	async retainSession(messages: HindsightMessage[]): Promise<void> {
+	async retainSession(messages: HindsightMessage[]): Promise<boolean> {
 		const retainFullWindow = this.config.retainMode === "full-session";
 		let target: HindsightMessage[];
 		let documentId: string;
 
 		if (retainFullWindow) {
-			target = messages;
+			target = sliceMessagesAfterUserTurns(messages, this.lastRetainedTurn);
+			if (target.length === 0) return false;
 			documentId = this.sessionId;
 		} else {
 			const windowTurns = this.config.retainEveryNTurns + this.config.retainOverlapTurns;
@@ -289,19 +317,40 @@ export class HindsightSessionState {
 		}
 
 		const { transcript } = prepareRetentionTranscript(target, true);
-		if (!transcript) return;
+		if (!transcript) return false;
 
 		await ensureBankMission(this.client, this.bankId, this.config, this.missionsSet);
 		await this.client.retain(this.bankId, transcript, {
 			documentId,
+			updateMode: "append",
 			context: this.config.retainContext,
 			metadata: { session_id: this.sessionId },
 			tags: this.retainTags,
 			async: true,
 		});
+		return true;
 	}
 
 	async maybeRetainOnAgentEnd(): Promise<void> {
+		if (this.#autoRetainInFlight) {
+			this.#autoRetainPending = true;
+			return;
+		}
+
+		const retain = this.#maybeRetainOnAgentEnd();
+		this.#autoRetainInFlight = retain;
+		try {
+			await retain;
+		} finally {
+			this.#autoRetainInFlight = undefined;
+			if (this.#autoRetainPending) {
+				this.#autoRetainPending = false;
+				void this.maybeRetainOnAgentEnd();
+			}
+		}
+	}
+
+	async #maybeRetainOnAgentEnd(): Promise<void> {
 		if (!this.config.autoRetain) return;
 		const messages = extractMessages(this.session.sessionManager);
 		if (messages.length === 0) return;
@@ -309,7 +358,8 @@ export class HindsightSessionState {
 		if (userTurns - this.lastRetainedTurn < this.config.retainEveryNTurns) return;
 
 		try {
-			await this.retainSession(messages);
+			const retained = await this.retainSession(messages);
+			if (!retained) return;
 			this.lastRetainedTurn = userTurns;
 			if (this.config.debug) {
 				logger.debug("Hindsight: auto-retain succeeded", {
@@ -332,7 +382,8 @@ export class HindsightSessionState {
 		const messages = extractMessages(this.session.sessionManager);
 		if (messages.length === 0) return;
 		try {
-			await this.retainSession(messages);
+			const retained = await this.retainSession(messages);
+			if (!retained) return;
 			this.lastRetainedTurn = messages.filter(m => m.role === "user").length;
 		} catch (err) {
 			logger.warn("Hindsight: forced retain failed", {
@@ -358,7 +409,6 @@ export class HindsightSessionState {
 		if (!context) return;
 
 		this.lastRecallSnippet = context;
-		await this.#refreshBaseSystemPromptAfter("recall");
 	}
 
 	async beforeAgentStartPrompt(promptText: string): Promise<string | undefined> {
@@ -409,21 +459,23 @@ export class HindsightSessionState {
 			}
 		}
 
-		await this.refreshMentalModelsSnippet();
-		await this.#refreshBaseSystemPromptAfter("MM load");
+		const changed = await this.refreshMentalModelsSnippet();
+		if (changed) await this.#refreshBaseSystemPromptAfter("MM load");
 	}
 
-	async refreshMentalModelsSnippet(): Promise<void> {
+	async refreshMentalModelsSnippet(): Promise<boolean> {
 		const snippet = await loadMentalModelsBlock(this.client, this.bankId, this.config.mentalModelMaxRenderChars);
+		const changed = contentHash(snippet) !== contentHash(this.mentalModelsSnippet);
 		this.mentalModelsSnippet = snippet;
 		this.mentalModelsLoadedAt = Date.now();
+		return changed;
 	}
 
 	async reloadMentalModels(): Promise<boolean> {
 		if (this.aliasOf) return false;
 		if (!this.config.mentalModelsEnabled) return false;
-		await this.refreshMentalModelsSnippet();
-		await this.#refreshBaseSystemPromptAfter("MM reload");
+		const changed = await this.refreshMentalModelsSnippet();
+		if (changed) await this.#refreshBaseSystemPromptAfter("MM reload");
 		return true;
 	}
 
@@ -445,21 +497,21 @@ export class HindsightSessionState {
 					this.mentalModelsLoadedAt !== undefined &&
 					Date.now() - this.mentalModelsLoadedAt >= this.config.mentalModelRefreshIntervalMs
 				) {
-					void this.refreshMentalModelsSnippet().then(async () => {
-						await this.#refreshBaseSystemPromptAfter("MM TTL reload");
+					void this.refreshMentalModelsSnippet().then(async changed => {
+						if (changed) await this.#refreshBaseSystemPromptAfter("MM TTL reload");
 					});
 				}
 			}
 		});
 	}
 
-	dispose(): void {
+	async dispose(): Promise<void> {
 		this.unsubscribe?.();
 		this.unsubscribe = undefined;
-		this.retainQueue.dispose();
+		await this.retainQueue.dispose();
 	}
 
-	async #refreshBaseSystemPromptAfter(reason: "recall" | "MM load" | "MM reload" | "MM TTL reload"): Promise<void> {
+	async #refreshBaseSystemPromptAfter(reason: "MM load" | "MM reload" | "MM TTL reload"): Promise<void> {
 		try {
 			await this.session.refreshBaseSystemPrompt();
 		} catch (err) {
@@ -467,3 +519,20 @@ export class HindsightSessionState {
 		}
 	}
 }
+
+/** Return the tail beginning with the first user turn after `retainedTurns`. */
+function sliceMessagesAfterUserTurns(messages: HindsightMessage[], retainedTurns: number): HindsightMessage[] {
+	if (retainedTurns <= 0) return messages;
+
+	let seenTurns = 0;
+	for (let i = 0; i < messages.length; i++) {
+		if (messages[i].role !== "user") continue;
+		seenTurns += 1;
+		if (seenTurns > retainedTurns) return messages.slice(i);
+	}
+	return [];
+}
+
+function contentHash(content: string | undefined): string {
+	return Bun.hash(content ?? "").toString(16);
+}

package/src/hooks/skill-state.ts

@@ -12,6 +12,7 @@ import {
 	writeGuardedWorkflowEnvelopeAtomic,
 } from "../gjc-runtime/state-writer";
 import { isUltragoalBypassPrompt, verifyUltragoalDurableCompletionState } from "../gjc-runtime/ultragoal-guard";
+import { getSkillManifest } from "../gjc-runtime/workflow-manifest";
 import { buildSessionContext, loadEntriesFromFile, type SessionEntry } from "../session/session-manager";
 import {
 	readVisibleSkillActiveState as readCanonicalVisibleSkillActiveState,
@@ -20,6 +21,7 @@ import {
 	syncSkillActiveState,
 } from "../skill-state/active-state";
 import { initialPhaseForSkill } from "../skill-state/initial-phase";
+import { readWorkflowGuardContext } from "../skill-state/workflow-mutation-guard";
 
 // Re-export for existing callers and tests that imported it from this module.
 export { initialPhaseForSkill };
@@ -531,7 +533,6 @@ function isTerminalModeState(state: ModeState | null): boolean {
  * declared it is ready to chain but has not yet been demoted/cleared, so it
  * must keep blocking until the chain (or an explicit clear) removes it.
  */
-const STOP_RELEASING_PHASES = ["complete", "completed", "failed", "cancelled", "canceled", "inactive"] as const;
 
 /**
  * Handoff workflows must never stop silently — they always have to offer the
@@ -553,13 +554,13 @@ function isHandoffRequiredSkill(skill: GjcWorkflowSkill): boolean {
  * mode-state preserves the historical fail-open behavior so a broken state file
  * cannot lock a session.
  */
-function modeStateReleasesStop(state: ModeState | null, handoffRequired: boolean): boolean {
+function modeStateReleasesStop(state: ModeState | null, handoffRequired: boolean, skill: GjcWorkflowSkill): boolean {
 	if (!state) return !handoffRequired;
 	if (state.active !== true) return true;
 	const phase = String(state.current_phase ?? "")
 		.trim()
 		.toLowerCase();
-	if ((STOP_RELEASING_PHASES as readonly string[]).includes(phase)) return true;
+	if (getSkillManifest(skill).stopReleasingPhases.includes(phase)) return true;
 	if (!handoffRequired && phase === "handoff") return true;
 	return false;
 }
@@ -743,12 +744,21 @@ function buildHandoffModeStateRecoveryMessage(skill: GjcWorkflowSkill, phase: st
 }
 
 function buildHandoffForceAskMessage(skill: GjcWorkflowSkill, phase: string, statePath: string): string {
+	if (skill === "deep-interview" && phase.trim().toLowerCase() === "interviewing") {
+		return `GJC deep-interview is still interviewing and must not stop (${statePath}). Continue the active round immediately: score and persist an answered round, then report progress. Use the ask tool for the next question. Only stop after crystallizing, recording a handoff, or explicitly cancelling the workflow. ${buildHandoffStopReleaseGuidance(skill)}`;
+	}
 	return `GJC handoff skill "${skill}" must not stop without offering a next step (phase: ${phase}; state: ${statePath}). ${buildHandoffStopReleaseGuidance(skill)}`;
 }
 
 export async function buildSkillStopOutput(input: StopHookInput): Promise<Record<string, unknown> | null> {
-	const resolvedSessionId = await resolveBoundarySessionId(input.cwd, input.sessionId);
-	const skillState = await readVisibleSkillActiveState(input.cwd, resolvedSessionId, input.stateDir);
+	const guardContext = await readWorkflowGuardContext(input.cwd, {
+		sessionId: input.sessionId,
+		threadId: input.threadId,
+	});
+	const resolvedSessionId = guardContext.sessionId;
+	if (!resolvedSessionId) return null;
+	const skillState = guardContext.activeState;
+
 	const activeEntries = listActiveSkills(skillState)
 		.filter(isWorkflowActiveEntry)
 		.filter(entry =>
@@ -757,11 +767,7 @@ export async function buildSkillStopOutput(input: StopHookInput): Promise<Record
 	if (!skillState || activeEntries.length === 0) return null;
 
 	for (const entry of activeEntries) {
-		const modeState = await readValidatedJsonFile<ModeState>(
-			modeStatePath(input.cwd, entry.skill, resolvedSessionId),
-			"mode-state",
-			ModeStateSchema,
-		);
+		const modeState = guardContext.modeStates.get(entry.skill) ?? null;
 		const handoffRequired = isHandoffRequiredSkill(entry.skill);
 		if (!modeState && handoffRequired) {
 			const phase = String(entry.phase ?? skillState.phase ?? "active");
@@ -784,7 +790,7 @@ export async function buildSkillStopOutput(input: StopHookInput): Promise<Record
 				systemMessage: rescueMessage,
 			};
 		}
-		if (modeStateReleasesStop(modeState, handoffRequired)) {
+		if (modeStateReleasesStop(modeState, handoffRequired, entry.skill)) {
 			// A mode-state that claims it releases the Stop block must agree with
 			// authoritative durable state. If a stale/incoherent mode-state would
 			// release while the plan/ledger still shows pending work, block instead