@gajae-code/coding-agent 0.5.0 → 0.5.1

package/src/modes/shared/agent-wire/session-registry.ts

@@ -0,0 +1,109 @@
+/**
+ * Cross-process registry of running gjc RPC sessions (issue 10).
+ *
+ * Each live RPC server writes a record under `<agent-dir>/rpc-sessions/<id>.json`
+ * on start and removes it on shutdown, so a separate process can discover which
+ * sessions are alive (and, once persistence lands in issue 09, how to reach
+ * them). Listing reaps records whose owning process is no longer alive, so a
+ * crashed server never leaves a permanent phantom entry.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getAgentDir } from "@gajae-code/utils";
+
+export type RpcSessionTransport = "stdio" | "bridge" | "socket";
+
+export interface RpcSessionRecord {
+	sessionId: string;
+	pid: number;
+	transport: RpcSessionTransport;
+	cwd: string;
+	model?: string;
+	/** ISO-8601 start timestamp. */
+	startedAt: string;
+	/** Reachable endpoint for persistent transports (issue 09); absent for stdio. */
+	endpoint?: string;
+}
+
+/** Registry directory: `<agent-dir>/rpc-sessions` (honors GJC_CODING_AGENT_DIR via getAgentDir). */
+function rpcSessionsDir(agentDir?: string): string {
+	return path.join(agentDir ?? getAgentDir(), "rpc-sessions");
+}
+
+function recordPath(sessionId: string, agentDir?: string): string {
+	return path.join(rpcSessionsDir(agentDir), `${sessionId}.json`);
+}
+
+/**
+ * Write (or replace) the registry record for a session. The record is written to
+ * a same-directory temp file and atomically renamed into place so a concurrent
+ * reader never observes (and reaps) a partially-written record.
+ */
+export async function registerRpcSession(record: RpcSessionRecord, agentDir?: string): Promise<string> {
+	const file = recordPath(record.sessionId, agentDir);
+	// `.tmp` suffix keeps the staging file out of the `*.json` listing/reaping path.
+	const staging = `${file}.${process.pid}.tmp`;
+	await Bun.write(staging, JSON.stringify(record));
+	await fs.rename(staging, file);
+	return file;
+}
+
+/** Remove a session's registry record. Best-effort: a missing file is not an error. */
+export async function unregisterRpcSession(sessionId: string, agentDir?: string): Promise<void> {
+	await fs.rm(recordPath(sessionId, agentDir), { force: true });
+}
+
+function isProcessAlive(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		// Signal 0 performs error checking without delivering a signal.
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		// ESRCH => no such process (dead). EPERM => alive but owned by another user.
+		return (err as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+function parseRecord(raw: string): RpcSessionRecord | undefined {
+	let obj: Partial<RpcSessionRecord>;
+	try {
+		obj = JSON.parse(raw) as Partial<RpcSessionRecord>;
+	} catch {
+		return undefined;
+	}
+	if (typeof obj.sessionId !== "string" || typeof obj.pid !== "number") return undefined;
+	return obj as RpcSessionRecord;
+}
+
+/**
+ * List live RPC sessions, reaping records whose process is gone or whose file is
+ * unparseable. Returns records sorted by `startedAt` ascending.
+ */
+export async function listRpcSessions(agentDir?: string): Promise<RpcSessionRecord[]> {
+	const dir = rpcSessionsDir(agentDir);
+	let entries: string[];
+	try {
+		entries = await fs.readdir(dir);
+	} catch {
+		return [];
+	}
+	const live: RpcSessionRecord[] = [];
+	for (const entry of entries) {
+		if (!entry.endsWith(".json")) continue;
+		const file = path.join(dir, entry);
+		let raw: string;
+		try {
+			raw = await fs.readFile(file, "utf8");
+		} catch {
+			continue;
+		}
+		const record = parseRecord(raw);
+		if (!record || !isProcessAlive(record.pid)) {
+			await fs.rm(file, { force: true });
+			continue;
+		}
+		live.push(record);
+	}
+	return live.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+}

package/src/modes/shared/agent-wire/unattended-action-policy.ts

@@ -45,6 +45,30 @@ export function actionClassForScope(scope: BridgeCommandScope): RpcUnattendedAct
 	}
 }
 
+/** Runtime list of every v1 action class — membership-validation source for negotiate (#319). */
+export const RPC_UNATTENDED_ACTION_CLASSES: readonly RpcUnattendedActionClass[] = [
+	"command.prompt",
+	"command.control",
+	"command.bash",
+	"command.export",
+	"command.session",
+	"command.model",
+	"command.message_read",
+	"command.host_tools",
+	"command.host_uri",
+	"command.admin",
+	"bash.readonly",
+	"bash.mutating",
+	"bash.destructive",
+	"git.force_push",
+	"file.delete",
+	"file.write",
+	"host_tool.invoke",
+	"host_uri.read",
+	"host_uri.write",
+	"auth.login",
+];
+
 const READONLY_COMMANDS = new Set([
 	"ls",
 	"cat",

package/src/modes/shared/agent-wire/unattended-run-controller.ts

@@ -24,7 +24,8 @@ import type {
 	RpcUnattendedRefusalCode,
 } from "../../rpc/rpc-types";
 import type { BridgeCommandScope } from "./scopes";
-import { actionClassForScope, classifyBashAction } from "./unattended-action-policy";
+import { BRIDGE_COMMAND_SCOPES, MANDATORY_FLOOR_COMMAND_SCOPES } from "./scopes";
+import { actionClassForScope, classifyBashAction, RPC_UNATTENDED_ACTION_CLASSES } from "./unattended-action-policy";
 
 /** Coordinated abort surfaces invoked exactly once on a budget breach / abort. */
 export interface UnattendedAbortHooks {
@@ -157,8 +158,11 @@ export class UnattendedRunController {
 		this.sessionId = ctx.sessionId;
 		this.actor = declaration.actor;
 		this.budget = budget;
-		this.scopes = new Set(declaration.scopes);
-		this.actionAllowlist = new Set(declaration.action_allowlist);
+		this.scopes = new Set([...declaration.scopes, ...MANDATORY_FLOOR_COMMAND_SCOPES]);
+		this.actionAllowlist = new Set([
+			...declaration.action_allowlist,
+			...MANDATORY_FLOOR_COMMAND_SCOPES.map(actionClassForScope),
+		]);
 		this.now = ctx.now ?? Date.now;
 		this.audit = ctx.audit;
 		this.abortHooks = ctx.abortHooks ?? {};
@@ -183,6 +187,22 @@ export class UnattendedRunController {
 				"declaration.action_allowlist must be string[]",
 			);
 		}
+		const unknownScopes = d.scopes.filter(scope => !BRIDGE_COMMAND_SCOPES.includes(scope as BridgeCommandScope));
+		if (unknownScopes.length > 0) {
+			throw new UnattendedNegotiationError(
+				"invalid_unattended_declaration",
+				`declaration.scopes contains unknown scope(s): ${unknownScopes.join(", ")}`,
+			);
+		}
+		const unknownActions = d.action_allowlist.filter(
+			action => !RPC_UNATTENDED_ACTION_CLASSES.includes(action as RpcUnattendedActionClass),
+		);
+		if (unknownActions.length > 0) {
+			throw new UnattendedNegotiationError(
+				"invalid_unattended_declaration",
+				`declaration.action_allowlist contains unknown action class(es): ${unknownActions.join(", ")}`,
+			);
+		}
 		const budget = validateBudget(d.budget);
 		// Reject providers that cannot account for tokens/cost (fail-closed): require
 		// an explicit positive capability signal — omitted/unknown is refused too.

package/src/modes/shared/agent-wire/unattended-session.ts

@@ -31,6 +31,13 @@ import {
 } from "./unattended-run-controller";
 import { type GateStore, MemoryGateStore, type OpenGateInput, WorkflowGateBroker } from "./workflow-gate-broker";
 
+/**
+ * RPC commands that perform agent/tool work and therefore consume one unit of the
+ * `max_tool_calls` budget. Read-only/control/cancellation commands are wall-time-bounded
+ * and scope-checked but must NOT charge the tool-call budget (issue 04).
+ */
+const CHARGED_COMMAND_TYPES = new Set<RpcCommand["type"]>(["bash", "prompt", "steer", "follow_up", "abort_and_prompt"]);
+
 /** Minimal surface a skill runtime / ask tool uses to emit a gate and await its answer. */
 export interface WorkflowGateEmitter {
 	/** True only when unattended mode has been negotiated. */
@@ -116,7 +123,15 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 
 	preflightCommand(command: RpcCommand): void {
 		if (!this.#controller) return;
-		this.#controller.preflightToolCall(`${command.type} preflight`);
+		const phase = `${command.type} preflight`;
+		// Always enforce wall-time; only charge the tool-call budget for commands that perform
+		// agent/tool work (issue 04). Read-only/control/cancellation commands must not consume
+		// max_tool_calls, but remain wall-time-bounded and scope/action-checked.
+		if (CHARGED_COMMAND_TYPES.has(command.type)) {
+			this.#controller.preflightToolCall(phase);
+		} else {
+			this.#controller.checkWallTime(phase);
+		}
 		if (command.type === "bash") {
 			this.#controller.authorizeBash(command.command);
 			return;

package/src/sdk.ts

@@ -32,7 +32,7 @@ import {
 	Snowflake,
 } from "@gajae-code/utils";
 
-import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled } from "./async";
+import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled, jobElapsedMs } from "./async";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
 import { ModelRegistry } from "./config/model-registry";
@@ -50,6 +50,7 @@ import { CursorExecHandlers } from "./cursor";
 import "./discovery";
 import { resolveConfigValue } from "./config/resolve-config-value";
 import { getEmbeddedDefaultGjcSkills } from "./defaults/gjc-defaults";
+import { BUNDLED_GROK_BUILD_EXTENSION_ID, getBundledGrokBuildExtensionFactory } from "./defaults/gjc-grok-cli";
 import { initializeWithSettings } from "./discovery";
 import { disposeAllKernelSessions, disposeKernelSessionsByOwner } from "./eval/py/executor";
 import { TtsrManager } from "./export/ttsr";
@@ -1124,7 +1125,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						const formattedResult = await formatAsyncResultForFollowUp(result);
 						if (asyncJobManager!.isDeliverySuppressed(jobId)) return;
 
-						const durationMs = job ? Math.max(0, Date.now() - job.startTime) : undefined;
+						const durationMs = job ? jobElapsedMs(job) : undefined;
 						session.yieldQueue.enqueue<AsyncResultEntry>("async-result", {
 							jobId,
 							result: formattedResult,
@@ -1341,13 +1342,26 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 
 		// Extension/module discovery is quarantined; retain only the private
-		// runtime needed for explicitly supplied SDK extensions and custom tools.
+		// runtime needed for bundled product extensions, explicitly supplied SDK
+		// extension factories, and custom tools. Filesystem extension paths remain
+		// ignored here even when options.additionalExtensionPaths is supplied.
 		const extensionsResult: LoadExtensionsResult = options.preloadedExtensions ?? {
 			extensions: [],
 			errors: [],
 			runtime: new ExtensionRuntime(),
 		};
 
+		if (!extensionsResult.extensions.some(extension => extension.path === BUNDLED_GROK_BUILD_EXTENSION_ID)) {
+			const bundledGrokExtension = await loadExtensionFromFactory(
+				getBundledGrokBuildExtensionFactory(),
+				cwd,
+				eventBus,
+				extensionsResult.runtime,
+				BUNDLED_GROK_BUILD_EXTENSION_ID,
+			);
+			extensionsResult.extensions.push(bundledGrokExtension);
+		}
+
 		// Load inline extensions from factories
 		if (inlineExtensions.length > 0) {
 			for (let i = 0; i < inlineExtensions.length; i++) {

package/src/session/agent-session.ts

@@ -322,7 +322,10 @@ function isUnderProjectGjc(cwd: string, targetPath: string): boolean {
 
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
-export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime" | "metadata">;
+export type AsyncJobSnapshotItem = Pick<
+	AsyncJob,
+	"id" | "type" | "status" | "label" | "startTime" | "endTime" | "metadata"
+>;
 
 export interface AsyncJobSnapshot {
 	running: AsyncJobSnapshotItem[];
@@ -903,6 +906,7 @@ export class AgentSession {
 	// Compaction state
 	#compactionAbortController: AbortController | undefined = undefined;
 	#autoCompactionAbortController: AbortController | undefined = undefined;
+	#prePromptContextCheckPromise: Promise<void> | undefined = undefined;
 
 	// Branch summarization state
 	#branchSummaryAbortController: AbortController | undefined = undefined;
@@ -1563,6 +1567,7 @@ export class AgentSession {
 			status: job.status,
 			label: job.label,
 			startTime: job.startTime,
+			endTime: job.endTime,
 			metadata: job.metadata,
 		}));
 		const recent = manager.getRecentJobs(options?.recentLimit ?? 5, ownerFilter).map(job => ({
@@ -1571,6 +1576,7 @@ export class AgentSession {
 			status: job.status,
 			label: job.label,
 			startTime: job.startTime,
+			endTime: job.endTime,
 			metadata: job.metadata,
 		}));
 		const delivery = manager.getDeliveryState(ownerFilter);
@@ -4754,7 +4760,11 @@ export class AgentSession {
 				await this.#checkCompaction(lastAssistant, false);
 			}
 			if (!options?.skipCompactionCheck) {
-				await this.#checkEstimatedContextBeforePrompt();
+				await this.#checkEstimatedContextBeforePrompt([
+					...(options?.prependMessages ?? []),
+					message,
+					...this.#pendingNextTurnMessages,
+				]);
 			}
 
 			// Build messages array (session context, eager todo prelude, then active prompt message)
@@ -5219,7 +5229,9 @@ export class AgentSession {
 				}
 				await this.#syncSkillPromptActiveStateSafely(appMessage, true);
 				try {
-					await this.agent.prompt(appMessage);
+					await this.#promptWithMessage(appMessage, this.#getCustomMessageTextContent(appMessage), {
+						skipPostPromptRecoveryWait: true,
+					});
 				} finally {
 					await this.#syncSkillPromptActiveStateSafely(appMessage, false);
 				}
@@ -5243,7 +5255,9 @@ export class AgentSession {
 			}
 			await this.#syncSkillPromptActiveStateSafely(appMessage, true);
 			try {
-				await this.agent.prompt(appMessage);
+				await this.#promptWithMessage(appMessage, this.#getCustomMessageTextContent(appMessage), {
+					skipPostPromptRecoveryWait: true,
+				});
 			} finally {
 				await this.#syncSkillPromptActiveStateSafely(appMessage, false);
 			}
@@ -6546,7 +6560,23 @@ export class AgentSession {
 		}
 	}
 
-	async #checkEstimatedContextBeforePrompt(): Promise<void> {
+	async #checkEstimatedContextBeforePrompt(pendingMessages: readonly AgentMessage[] = []): Promise<void> {
+		if (this.#prePromptContextCheckPromise) {
+			await this.#prePromptContextCheckPromise;
+		}
+
+		const checkPromise = this.#checkEstimatedContextBeforePromptOnce(pendingMessages);
+		this.#prePromptContextCheckPromise = checkPromise;
+		try {
+			await checkPromise;
+		} finally {
+			if (this.#prePromptContextCheckPromise === checkPromise) {
+				this.#prePromptContextCheckPromise = undefined;
+			}
+		}
+	}
+
+	async #checkEstimatedContextBeforePromptOnce(pendingMessages: readonly AgentMessage[]): Promise<void> {
 		const model = this.model;
 		if (!model) return;
 		const contextWindow = model.contextWindow ?? 0;
@@ -6554,7 +6584,7 @@ export class AgentSession {
 		const compactionSettings = this.settings.getGroup("compaction");
 		if (!compactionSettings.enabled || compactionSettings.strategy === "off") return;
 
-		let contextTokens = this.#estimateContextTokens().tokens;
+		let contextTokens = this.#estimateContextTokensForCompaction(pendingMessages).tokens;
 		const maxOutputTokens = model.maxTokens ?? 0;
 		if (!shouldCompact(contextTokens, contextWindow, compactionSettings, maxOutputTokens)) return;
 
@@ -9597,6 +9627,21 @@ export class AgentSession {
 	 */
 	#estimateContextTokens(): {
 		tokens: number;
+	} {
+		return this.#estimateContextTokensWith(message => this.#estimateMessageDisplayTokens(message));
+	}
+
+	#estimateContextTokensForCompaction(pendingMessages: readonly AgentMessage[]): {
+		tokens: number;
+	} {
+		const estimate = this.#estimateContextTokensWith(message => this.#estimateMessageNativeContextTokens(message));
+		return {
+			tokens: estimate.tokens + this.#estimateMessagesNativeContextTokens(pendingMessages),
+		};
+	}
+
+	#estimateContextTokensWith(estimateMessage: (message: AgentMessage) => number): {
+		tokens: number;
 	} {
 		const messages = this.messages;
 
@@ -9619,7 +9664,7 @@ export class AgentSession {
 			// No usage data - estimate all messages
 			let estimated = 0;
 			for (const message of messages) {
-				estimated += estimateMessageTokensHeuristic(message);
+				estimated += estimateMessage(message);
 			}
 			return {
 				tokens: estimated,
@@ -9629,7 +9674,7 @@ export class AgentSession {
 		const usageTokens = calculatePromptTokens(lastUsage);
 		let trailingTokens = 0;
 		for (let i = lastUsageIndex + 1; i < messages.length; i++) {
-			trailingTokens += estimateMessageTokensHeuristic(messages[i]);
+			trailingTokens += estimateMessage(messages[i]);
 		}
 
 		return {
@@ -9637,6 +9682,30 @@ export class AgentSession {
 		};
 	}
 
+	#estimateMessagesNativeContextTokens(messages: readonly AgentMessage[]): number {
+		let tokens = 0;
+		for (const message of messages) {
+			tokens += this.#estimateMessageNativeContextTokens(message);
+		}
+		return tokens;
+	}
+
+	#estimateMessageDisplayTokens(message: AgentMessage): number {
+		let tokens = 0;
+		for (const llmMessage of convertToLlm([message])) {
+			tokens += estimateMessageTokensHeuristic(llmMessage);
+		}
+		return tokens;
+	}
+
+	#estimateMessageNativeContextTokens(message: AgentMessage): number {
+		let tokens = 0;
+		for (const llmMessage of convertToLlm([message])) {
+			tokens += estimateTokens(llmMessage);
+		}
+		return tokens;
+	}
+
 	/**
 	 * Export session to HTML.
 	 * @param outputPath Optional output path (defaults to session directory)

package/src/session/blob-store.ts

@@ -267,7 +267,13 @@ export function externalizeImageDataSync(blobStore: BlobStore, base64Data: strin
 /**
  * Resolve an externalized provider image data URL back to its original string.
  * If the data is not a blob reference, returns it unchanged.
- * If the blob is missing, logs a warning and returns the reference as-is.
+ *
+ * LEGACY PERSISTED-IMAGE COMPATIBILITY BOUNDARY: when the persisted blob is missing
+ * (e.g. resuming an old session whose image blob was pruned), this warns and returns
+ * the reference as-is rather than throwing, so legacy resume degrades gracefully.
+ * New resident byte-sensitive TEXT uses the fail-closed path instead
+ * (`resolveTextBlobSync` -> `ResidentBlobMissingError`). Do NOT route new byte-sensitive
+ * resident data through this warn-and-return path.
  */
 export async function resolveImageDataUrl(blobStore: BlobStore, data: string): Promise<string> {
 	const hash = parseBlobRef(data);
@@ -284,7 +290,11 @@ export async function resolveImageDataUrl(blobStore: BlobStore, data: string): P
 /**
  * Resolve a blob reference back to base64 data.
  * If the data is not a blob reference, returns it unchanged.
- * If the blob is missing, logs a warning and returns a placeholder.
+ *
+ * LEGACY PERSISTED-IMAGE COMPATIBILITY BOUNDARY: when the blob is missing this warns
+ * and returns the reference as-is (downstream sees an invalid base64 ref but does not
+ * crash), preserving legacy-session resume. Byte-sensitive resident TEXT is fail-closed
+ * via `resolveTextBlobSync`; do NOT route new byte-sensitive resident data here.
  */
 export async function resolveImageData(blobStore: BlobStore, data: string): Promise<string> {
 	const hash = parseBlobRef(data);
@@ -322,7 +332,14 @@ export function resolveImageDataSync(blobStore: BlobStore, data: string): string
 	return buffer.toString("base64");
 }
 
-/** Synchronously resolve a blob reference back to utf8 text. */
+/**
+ * Synchronously resolve a blob reference back to utf8 text.
+ *
+ * FAIL-CLOSED byte-sensitive path: a missing resident blob throws
+ * `ResidentBlobMissingError` rather than degrading, so a missing resident text blob can
+ * never silently leak a `blob:sha256:` ref into provider payloads, UI, or exports.
+ * (Contrast the legacy persisted-image warn-and-return resolvers above.)
+ */
 export function resolveTextBlobSync(
 	blobStore: BlobStore,
 	data: string,
@@ -336,3 +353,42 @@ export function resolveTextBlobSync(
 	}
 	return buffer.toString("utf8");
 }
+
+/**
+ * FAIL-CLOSED resident variant of {@link resolveImageDataUrlSync}: a missing resident
+ * image-data-url blob throws `ResidentBlobMissingError` ("imageUrl") instead of warn-returning,
+ * so resident byte-sensitive provider image data can never leak a `blob:sha256:` ref into
+ * materialized entries, context, or provider payloads. The warn-and-return `resolveImageDataUrl*`
+ * resolvers remain ONLY for legacy persisted-image resume.
+ */
+export function resolveResidentImageDataUrlSync(
+	blobStore: BlobStore,
+	data: string,
+	context?: { sessionId?: string; sessionFile?: string },
+): string {
+	const hash = parseBlobRef(data);
+	if (!hash) return data;
+	const buffer = blobStore.getSync(hash);
+	if (!buffer) {
+		throw new ResidentBlobMissingError(hash, "imageUrl", context?.sessionId, context?.sessionFile);
+	}
+	return buffer.toString("utf8");
+}
+
+/**
+ * FAIL-CLOSED resident variant of {@link resolveImageDataSync}: a missing resident image blob
+ * throws `ResidentBlobMissingError` ("imageData") instead of warn-returning a placeholder.
+ */
+export function resolveResidentImageDataSync(
+	blobStore: BlobStore,
+	data: string,
+	context?: { sessionId?: string; sessionFile?: string },
+): string {
+	const hash = parseBlobRef(data);
+	if (!hash) return data;
+	const buffer = blobStore.getSync(hash);
+	if (!buffer) {
+		throw new ResidentBlobMissingError(hash, "imageData", context?.sessionId, context?.sessionFile);
+	}
+	return buffer.toString("base64");
+}

package/src/session/session-manager.ts

@@ -41,9 +41,9 @@ import {
 	isImageDataUrl,
 	MemoryBlobStore,
 	resolveImageData,
-	resolveImageDataSync,
 	resolveImageDataUrl,
-	resolveImageDataUrlSync,
+	resolveResidentImageDataSync,
+	resolveResidentImageDataUrlSync,
 	resolveTextBlobSync,
 } from "./blob-store";
 import {
@@ -1265,9 +1265,9 @@ function materializeResidentValueSync(
 		if (cached !== undefined) return cached;
 		const resolved =
 			obj.kind === "imageUrl"
-				? resolveImageDataUrlSync(stores.imageStore, obj.ref)
+				? resolveResidentImageDataUrlSync(stores.imageStore, obj.ref, stores)
 				: obj.kind === "imageData"
-					? resolveImageDataSync(stores.imageStore, obj.ref)
+					? resolveResidentImageDataSync(stores.imageStore, obj.ref, stores)
 					: resolveTextBlobSync(stores.textStore, obj.ref, stores);
 		cache.set(cacheKey, resolved);
 		return resolved;

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

@@ -9,14 +9,20 @@ These instructions teach a Hermes-style coordinator how to operate GJC through t
 1. Use `{{TOOL_PREFIX}}_list_sessions` to find an existing session, or `{{TOOL_PREFIX}}_start_session` when a new session is required and mutation is enabled.
 2. Send exactly one bounded task prompt with `{{TOOL_PREFIX}}_send_prompt`.
 3. Store the returned `turn_id`.
-4. Poll `{{TOOL_PREFIX}}_read_turn` or `{{TOOL_PREFIX}}_await_turn` for that `turn_id` until the turn is terminal.
+4. Prefer `{{TOOL_PREFIX}}_watch_events` with the stored `latest_seq` for event-driven progress; fall back to `{{TOOL_PREFIX}}_read_turn` or `{{TOOL_PREFIX}}_await_turn` for a specific `turn_id` until terminal.
    If a second task is needed while one turn is active, pass `queue: true`; the next queued turn is promoted after the active turn is reported terminal.
 5. If GJC asks a structured question, use `{{TOOL_PREFIX}}_list_questions` and answer with `{{TOOL_PREFIX}}_submit_question_answer`.
 6. Use `{{TOOL_PREFIX}}_report_status` for coordinator-visible status and final reports.
 7. Use `{{TOOL_PREFIX}}_read_tail` only as advisory debug output when structured turn state is insufficient.
 
+## Event watch
+
+`{{TOOL_PREFIX}}_watch_events` is a bounded long-poll read tool. Call it with `after_seq` set to the last stored sequence number, optional `session_id` or `event_types`, `timeout_ms` up to 30000, and `limit` up to 100. Store the returned `latest_seq` before the next wait. A timeout with no events is not failure; call again or use the turn/status read tools for a snapshot.
+
 Do not report completion to the user until the GJC turn is terminal. Do not infer completion from terminal scrollback alone.
 
+Coordinator MCP is a durable polling/await bridge, not a push subscription stream. Use `{{TOOL_PREFIX}}_read_coordination_status`, `{{TOOL_PREFIX}}_read_turn`, and bounded `{{TOOL_PREFIX}}_await_turn` as the authoritative consumption surface.
+
 ## Worktree, model, and provider policy
 
 The Hermes bridge does not choose a model/provider. Generated setup configures `GJC_COORDINATOR_MCP_SESSION_COMMAND` to `gjc --worktree` by default, so GJC creates and tracks the worktree while still using normal local model/provider resolution. Keep worktree creation inside GJC rather than creating unmanaged Hermes-side git worktrees; this preserves the original project identity for session listing and resume. If the operator config supplies a different `GJC_COORDINATOR_MCP_SESSION_COMMAND`, preserve it as explicit user intent.