@gajae-code/coding-agent 0.4.2 → 0.4.4

package/src/modes/shared/agent-wire/protocol.ts

@@ -1,100 +1,43 @@
 /**
  * Shared agent-wire protocol primitives for GJC bridge surfaces.
  *
- * This module is the transport-agnostic, versioned frame contract that the
- * RPC mode and the (in-progress) `--mode bridge` wiring site both build on.
- * It carries the SEMANTIC agent surface — events, responses, and UI/permission
- * requests — never pixels. See `.gjc/specs/deep-interview-gjc-backend-bridge.md`
- * and `.gjc/plans/ralplan/gjc-backend-bridge/pending-approval.md`.
+ * The canonical event/frame contract now lives in `event-contract.ts`. This
+ * module re-exports it under the historical `Bridge*` names so existing RPC and
+ * Bridge code keeps compiling while the adapters migrate to the canonical
+ * `AgentWire*` names. See `.gjc/specs/deep-interview-reconcile-rpc-adapters.md`.
  */
-import type { AgentSessionEvent } from "../../../session/agent-session";
+import type {
+	AgentWireEventFrame,
+	AgentWireEventPayload,
+	AgentWireEventType,
+	AgentWireFrameEnvelope,
+	AgentWireFrameType,
+} from "./event-contract";
+import { AGENT_WIRE_EVENT_TYPES, AGENT_WIRE_PROTOCOL_VERSION } from "./event-contract";
 
 /** Wire protocol version. Bump on breaking envelope/semantic changes. */
-export const BRIDGE_PROTOCOL_VERSION = 1 as const;
+export const BRIDGE_PROTOCOL_VERSION = AGENT_WIRE_PROTOCOL_VERSION;
 
 /** The discriminant of every `AgentSessionEvent` the agent can emit. */
-export type AgentSessionEventType = AgentSessionEvent["type"];
-
-/**
- * Compile-time exhaustive registry of every `AgentSessionEvent` variant.
- *
- * Adding a new variant to `AgentSessionEvent` without registering it here is a
- * type error. This keeps the bridge wire surface in lockstep with the agent
- * event union — the "event/element drift → silent incompleteness" mitigation
- * from the plan's pre-mortem.
- */
-const AGENT_SESSION_EVENT_TYPE_REGISTRY: Record<AgentSessionEventType, true> = {
-	agent_start: true,
-	agent_end: true,
-	turn_start: true,
-	turn_end: true,
-	message_start: true,
-	message_update: true,
-	message_end: true,
-	tool_execution_start: true,
-	tool_execution_update: true,
-	tool_execution_end: true,
-	auto_compaction_start: true,
-	auto_compaction_end: true,
-	auto_retry_start: true,
-	auto_retry_end: true,
-	retry_fallback_applied: true,
-	retry_fallback_succeeded: true,
-	ttsr_triggered: true,
-	todo_reminder: true,
-	todo_auto_clear: true,
-	irc_message: true,
-	notice: true,
-	thinking_level_changed: true,
-	goal_updated: true,
-};
+export type AgentSessionEventType = AgentWireEventType;
 
 /** Every agent-session event type, derived from the exhaustive registry. */
-export const AGENT_SESSION_EVENT_TYPES: readonly AgentSessionEventType[] = Object.keys(
-	AGENT_SESSION_EVENT_TYPE_REGISTRY,
-) as AgentSessionEventType[];
+export const AGENT_SESSION_EVENT_TYPES: readonly AgentSessionEventType[] = AGENT_WIRE_EVENT_TYPES;
 
 /** Top-level frame categories carried over any bridge transport. */
-export type BridgeFrameType =
-	| "ready"
-	| "event"
-	| "response"
-	| "ui_request"
-	| "permission_request"
-	| "host_tool_call"
-	| "host_uri_request"
-	| "reset"
-	| "workflow_gate"
-	| "error";
+export type BridgeFrameType = AgentWireFrameType;
 
-/**
- * Universal frame envelope. Every frame on every transport carries these
- * fields so clients can order (`seq`), resume (`seq` cursor), and correlate
- * request/response pairs (`correlation_id`). `session_id` is present from v1
- * even though v1 runs one session per process, so in-process multiplexing is
- * an additive, non-breaking change later.
- */
-export interface BridgeFrameEnvelope<TType extends BridgeFrameType = BridgeFrameType, TPayload = unknown> {
-	protocol_version: typeof BRIDGE_PROTOCOL_VERSION;
-	session_id: string;
-	/** Monotonic per-session sequence number, starting at 1. */
-	seq: number;
-	/** Unique id for this frame. */
-	frame_id: string;
-	/** Ties a request frame to its response frame, when applicable. */
-	correlation_id?: string;
-	type: TType;
-	payload: TPayload;
-}
+/** Universal frame envelope. See {@link AgentWireFrameEnvelope}. */
+export type BridgeFrameEnvelope<
+	TType extends BridgeFrameType = BridgeFrameType,
+	TPayload = unknown,
+> = AgentWireFrameEnvelope<TType, TPayload>;
 
-/** Payload carried by an `event` frame. */
-export interface BridgeEventPayload {
-	event_type: AgentSessionEventType;
-	event: AgentSessionEvent;
-}
+/** Payload carried by an `event` frame. See {@link AgentWireEventPayload}. */
+export type BridgeEventPayload = AgentWireEventPayload;
 
 /** An `AgentSessionEvent` serialized into a versioned wire frame. */
-export type BridgeEventFrame = BridgeFrameEnvelope<"event", BridgeEventPayload>;
+export type BridgeEventFrame = AgentWireEventFrame;
 
 /** A `workflow_gate` event serialized into a versioned wire frame (#321). */
 export type BridgeWorkflowGateFrame = BridgeFrameEnvelope<

package/src/modes/utils/context-usage.ts

@@ -197,14 +197,14 @@ export function computeContextBreakdown(
 	if (contextWindow > 0) {
 		const compactionSettings = session.settings.getGroup("compaction") as CompactionSettings;
 		if (compactionSettings.enabled && compactionSettings.strategy !== "off") {
-			const threshold = resolveThresholdTokens(contextWindow, compactionSettings);
+			const threshold = resolveThresholdTokens(contextWindow, compactionSettings, model?.maxTokens ?? 0);
 			autoCompactBufferTokens = Math.max(0, contextWindow - threshold);
 		} else {
 			autoCompactBufferTokens = 0;
 		}
 		// Even when fully disabled, fall back to a sensible reserve floor for display.
 		if (autoCompactBufferTokens === 0 && compactionSettings.enabled) {
-			autoCompactBufferTokens = effectiveReserveTokens(contextWindow, compactionSettings);
+			autoCompactBufferTokens = effectiveReserveTokens(contextWindow, compactionSettings, model?.maxTokens ?? 0);
 		}
 	}
 	autoCompactBufferTokens = Math.min(autoCompactBufferTokens, Math.max(0, contextWindow - usedTokens));

package/src/prompts/agents/architect.md

@@ -83,4 +83,10 @@ Prioritized concrete actions.
 
 ## Trade-offs
 Table or bullets comparing viable options when relevant.
+
+Persist this full review as the durable artifact via the restricted bash CLI, passing the markdown inline (never a file path, never `/tmp`):
+
+  gjc ralplan --write --stage architect --stage_n <N> --artifact "<full review markdown>" --json
+
+Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus the compact verdict (Architectural Status + Code Review Recommendation). Never paste the full review body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/agents/critic.md

@@ -56,4 +56,10 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 - Risk/Verification Rigor
 
 If not OKAY, list concrete required fixes.
+
+Persist this full evaluation as the durable artifact via the restricted bash CLI, passing the markdown inline (never a file path, never `/tmp`):
+
+  gjc ralplan --write --stage critic --stage_n <N> --artifact "<full evaluation markdown>" --json
+
+Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus the compact verdict (OKAY / ITERATE / REJECT). Never paste the full evaluation body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/agents/explore.md

@@ -2,7 +2,7 @@
 name: explore
 description: Fast read-only codebase scout returning compressed context for handoff
 tools: read, search, find, web_search
-model: pi/smol
+model: pi/default
 thinking-level: med
 output:
   properties:

package/src/prompts/agents/plan.md

@@ -3,7 +3,7 @@ name: plan
 description: Software architect for complex multi-file architectural decisions. NOT for simple tasks, single-file changes, or tasks completable in <5 tool calls.
 tools: read, search, find, bash, lsp, web_search, ast_grep
 spawns: explore
-model: pi/plan, pi/slow
+model: pi/default
 thinking-level: high
 hide: true
 ---

package/src/prompts/agents/planner.md

@@ -18,6 +18,7 @@ Leave execution with a right-sized, evidence-grounded plan: scope, steps, accept
 <constraints>
 - Read-only: never write, edit, format, commit, push, or mutate files.
 - Exception: you may use the restricted `bash` tool only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the plan markdown inline in `--artifact`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Persist durable plans only through `gjc ralplan --write`. Never write plan files to `/tmp`, the repository, or any other path, and never rely on a file the caller must read back. The CLI is your only persistence channel.
 - Inspect the repository before asking about code facts.
 - Ask only about priorities, tradeoffs, scope decisions, timelines, or preferences that repository inspection cannot resolve.
 - Right-size the step count to the task; do not default to a fixed number of steps.
@@ -42,7 +43,7 @@ Leave execution with a right-sized, evidence-grounded plan: scope, steps, accept
 </success_criteria>
 
 <output_contract>
-Return:
+Build the full plan as a single markdown document containing:
 - Summary
 - In scope / out of scope
 - File-level changes
@@ -50,4 +51,10 @@ Return:
 - Acceptance criteria
 - Verification
 - Risks and mitigations
+
+Persist that markdown as the durable artifact via the restricted bash CLI, passing the plan inline (never a file path, never `/tmp`):
+
+  gjc ralplan --write --stage planner --stage_n <N> --artifact "<full plan markdown>" --json
+
+Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus a compact plan summary (<=10 lines). Never paste the full plan body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/agents/reviewer.md

@@ -3,7 +3,7 @@ name: reviewer
 description: "Code review specialist for quality/security analysis"
 tools: read, search, find, bash, lsp, web_search, ast_grep, report_finding
 spawns: explore
-model: pi/slow
+model: pi/default
 thinking-level: high
 blocking: true
 output:

package/src/prompts/tools/browser.md

@@ -2,10 +2,11 @@ Drives a real Chromium tab with full puppeteer access via JS execution.
 
 <instruction>
 - For static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL — reader-mode text without spinning up a browser. Use this tool when you need JS execution, authentication, or interactive actions.
-- Three actions only:
+- Four actions:
   - `open` — acquire (or reuse) a named tab. `name` defaults to `"main"`. Optional `url` navigates after the tab is ready. Optional `viewport` sets dimensions. Optional `dialogs: "accept" | "dismiss"` auto-handles `alert`/`confirm`/`beforeunload` so navigation/clicks don't hang (default: leave dialogs unhandled — page hangs until caller wires `page.on('dialog', …)`).
   - `close` — release a tab by `name`, or every tab with `all: true`. For spawned-app browsers, set `kill: true` to terminate the process tree (default leaves it running).
   - `run` — execute JS against an existing tab. `code` is the body of an async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. The function's return value is JSON-stringified into the tool result; multiple `display(value)` calls accumulate text/images.
+  - `act` — run a list of structured `actions` against an existing tab without writing JS (preferred for routine navigation/interaction). Each step is `{ verb, … }`; verbs: `navigate {url, wait_until?}`, `click {id|selector}`, `type {id|selector, text}`, `fill {selector, value}`, `select {selector, values}`, `press {key, selector?}`, `scroll {dx?, dy?}`, `back`, `wait {selector?|ms?}`, `observe {viewport_only?, include_all?}`, `extract {format?}`, `screenshot`. Address elements by the numeric `id` from a prior `observe` (preferred) or a selector. Steps run in order; the tool returns an array of per-step results (observations/extracted content included). Use `run` only when a verb does not cover what you need.
 - Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.
 - Browser kinds, selected by the `app` field on `open`:
   - default (no `app`) → headless Chromium with stealth patches.
@@ -32,7 +33,7 @@ Drives a real Chromium tab with full puppeteer access via JS execution.
 </instruction>
 
 <critical>
-- You MUST call `open` before `run`. `run` does not implicitly create a tab.
+- You MUST call `open` before `run` or `act`. Neither implicitly creates a tab.
 - You NEVER screenshot just to "see what's on the page" — `tab.observe()` returns structured data with element ids you can act on immediately.
 - After a `tab.goto()` or any navigation, prior element ids from `tab.observe()` are invalidated. Re-observe before referencing them.
 - `code` runs with full Node access. Treat it as your code, not sandboxed code.

package/src/runtime-mcp/manager.ts

@@ -304,6 +304,7 @@ export class MCPManager {
 			config: MCPServerConfig;
 			tracked: TrackedPromise<ToolLoadResult>;
 			toolsPromise: Promise<ToolLoadResult>;
+			connectionAbort: AbortController;
 		};
 
 		const errors = new Map<string, string>();
@@ -424,7 +425,7 @@ export class MCPManager {
 			this.#pendingToolLoads.set(name, toolsPromise);
 
 			const tracked = trackPromise(toolsPromise);
-			connectionTasks.push({ name, config, tracked, toolsPromise });
+			connectionTasks.push({ name, config, tracked, toolsPromise, connectionAbort });
 
 			void toolsPromise
 				.then(async ({ connection, serverTools }) => {
@@ -475,7 +476,19 @@ export class MCPManager {
 
 				const pendingWithoutCache = pendingTasks.filter(task => !cachedTools.has(task.name));
 				if (pendingWithoutCache.length > 0) {
-					await Promise.allSettled(pendingWithoutCache.map(task => task.tracked.promise));
+					for (const task of pendingWithoutCache) {
+						const message = `MCP server connection timed out during startup: ${task.name}`;
+						errors.set(task.name, message);
+						reportedErrors.add(task.name);
+						task.connectionAbort.abort(new Error(message));
+						if (this.#pendingConnections.has(task.name)) this.#pendingConnections.delete(task.name);
+						if (this.#pendingToolLoads.get(task.name) === task.toolsPromise)
+							this.#pendingToolLoads.delete(task.name);
+						this.#pendingConnectionControllers.delete(task.name);
+					}
+					// Do not await these promises here: a misbehaving stdio/MCP transport can ignore
+					// AbortSignal and keep startup blocked indefinitely. The background toolsPromise
+					// handler will clean up if it eventually settles.
 				}
 			}
 

package/src/sdk.ts

@@ -868,7 +868,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		imageProvider === "auto" ||
 		imageProvider === "openai" ||
 		imageProvider === "gemini" ||
-		imageProvider === "openrouter"
+		imageProvider === "openrouter" ||
+		imageProvider === "antigravity"
 	) {
 		setPreferredImageProvider(imageProvider);
 	}
@@ -1222,6 +1223,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					timestamp: Date.now(),
 				}),
 			sendCustomMessage: (msg, opts) => session.sendCustomMessage(msg, opts),
+			purgeQueuedCustomMessages: predicate => session.purgeQueuedCustomMessages(predicate),
 			peekQueueInvoker: () => session.peekQueueInvoker(),
 			peekStandingResolveHandler: () => session.peekStandingResolveHandler(),
 			setStandingResolveHandler: handler => session.setStandingResolveHandler(handler),

package/src/session/agent-session.ts

@@ -89,6 +89,15 @@ export interface ForkContextSeedMetadata {
 	skippedReasons: Record<string, number>;
 }
 
+export interface PurgeQueuedCustomMessagesResult {
+	agentSteering: number;
+	agentFollowUp: number;
+	pendingNextTurn: number;
+	displaySteering: number;
+	displayFollowUp: number;
+	totalExecutable: number;
+}
+
 export interface ForkContextSeed {
 	messages: Message[];
 	agentMessages: AgentMessage[];
@@ -171,6 +180,7 @@ 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 { persistCoordinatorRuntimeStateFromEvent } from "../gjc-runtime/session-state-sidecar";
 import { writeArtifact } from "../gjc-runtime/state-writer";
 import { requestGjcWorkerIntegrationAttempt } from "../gjc-runtime/team-runtime";
 import { GoalRuntime } from "../goals/runtime";
@@ -1617,6 +1627,11 @@ export class AgentSession {
 	}
 
 	async #emitSessionEvent(event: AgentSessionEvent): Promise<void> {
+		await persistCoordinatorRuntimeStateFromEvent(event, {
+			sessionId: this.sessionId,
+			cwd: this.sessionManager.getCwd(),
+			sessionFile: this.sessionManager.getSessionFile(),
+		});
 		if (event.type === "message_update") {
 			this.#emit(event);
 			void this.#queueExtensionEvent(event);
@@ -4363,7 +4378,10 @@ export class AgentSession {
 
 	async #activatePendingGjcGoalModeRequest(): Promise<boolean> {
 		if (!this.settings.get("goal.enabled")) return false;
-		const pendingGoal = await consumePendingGoalModeRequest(this.sessionManager.getCwd());
+		const pendingGoal = await consumePendingGoalModeRequest(
+			this.sessionManager.getCwd(),
+			this.sessionManager.getSessionId(),
+		);
 		if (!pendingGoal) return false;
 		const currentState = this.getGoalModeState();
 		if (currentState?.goal && currentState.goal.status !== "complete" && currentState.goal.status !== "dropped") {
@@ -5058,6 +5076,10 @@ export class AgentSession {
 		this.#queueHiddenNextTurnMessage(message, true);
 	}
 
+	queueDeferredMessageForTests(message: CustomMessage, triggerTurn = true): void {
+		this.#queueHiddenNextTurnMessage(message, triggerTurn);
+	}
+
 	#queueHiddenNextTurnMessage(message: CustomMessage, triggerTurn: boolean): void {
 		this.#pendingNextTurnMessages.push(message);
 		if (!triggerTurn) return;
@@ -5230,6 +5252,46 @@ export class AgentSession {
 		);
 	}
 
+	/** Remove undelivered queued custom messages matching `predicate` from executable queues and tagged display mirrors. */
+	purgeQueuedCustomMessages(predicate: (message: CustomMessage) => boolean): PurgeQueuedCustomMessagesResult {
+		const isMatch = (m: AgentMessage): boolean => m.role === "custom" && predicate(m as CustomMessage);
+		const removedTags = new Set<string>();
+		for (const m of [...this.agent.snapshotSteering(), ...this.agent.snapshotFollowUp()]) {
+			if (isMatch(m)) {
+				const tag = readPendingDisplayTag((m as CustomMessage).details);
+				if (tag) removedTags.add(tag);
+			}
+		}
+		const agentRemoved = this.agent.removeQueuedMessages(isMatch);
+		const beforeNext = this.#pendingNextTurnMessages.length;
+		for (const m of this.#pendingNextTurnMessages) {
+			if (predicate(m)) {
+				const tag = readPendingDisplayTag(m.details);
+				if (tag) removedTags.add(tag);
+			}
+		}
+		this.#pendingNextTurnMessages = this.#pendingNextTurnMessages.filter(m => !predicate(m));
+		const pendingNextTurn = beforeNext - this.#pendingNextTurnMessages.length;
+		let displaySteering = 0;
+		let displayFollowUp = 0;
+		if (removedTags.size > 0) {
+			const beforeS = this.#steeringMessages.length;
+			this.#steeringMessages = this.#steeringMessages.filter(e => !(e.tag && removedTags.has(e.tag)));
+			displaySteering = beforeS - this.#steeringMessages.length;
+			const beforeF = this.#followUpMessages.length;
+			this.#followUpMessages = this.#followUpMessages.filter(e => !(e.tag && removedTags.has(e.tag)));
+			displayFollowUp = beforeF - this.#followUpMessages.length;
+		}
+		return {
+			agentSteering: agentRemoved.steering,
+			agentFollowUp: agentRemoved.followUp,
+			pendingNextTurn,
+			displaySteering,
+			displayFollowUp,
+			totalExecutable: agentRemoved.total + pendingNextTurn,
+		};
+	}
+
 	/**
 	 * Send a user message to the agent.
 	 * When deliverAs is set, queue the message instead of starting a new turn.
@@ -5704,7 +5766,7 @@ export class AgentSession {
 	/**
 	 * Cycle through configured role models in a fixed order.
 	 * Skips missing roles.
-	 * @param roleOrder - Order of roles to cycle through (e.g., ["slow", "default", "smol"])
+	 * @param roleOrder - Order of roles to cycle through (e.g., ["default"])
 	 * @param options - Optional settings: `temporary` to not persist to settings
 	 */
 	async cycleRoleModels(
@@ -6450,7 +6512,7 @@ export class AgentSession {
 		if (pruneResult) {
 			contextTokens = Math.max(0, contextTokens - pruneResult.tokensSaved);
 		}
-		if (shouldCompact(contextTokens, contextWindow, compactionSettings)) {
+		if (shouldCompact(contextTokens, contextWindow, compactionSettings, this.model?.maxTokens ?? 0)) {
 			// Try promotion first — if a larger model is available, switch instead of compacting
 			const promoted = await this.#tryContextPromotion(assistantMessage);
 			if (!promoted) {
@@ -7086,7 +7148,7 @@ export class AgentSession {
 		}
 		return new Error(
 			`Compaction requires usable credentials for ${currentModel.provider}/${currentModel.id}. ` +
-				`Configure ${currentModel.provider} credentials or assign an authenticated fallback role such as modelRoles.smol.`,
+				`Configure ${currentModel.provider} credentials or assign an authenticated fallback via modelRoles.default.`,
 		);
 	}
 

package/src/session/session-manager.ts

@@ -104,7 +104,7 @@ export interface ModelChangeEntry extends SessionEntryBase {
 	type: "model_change";
 	/** Model in "provider/modelId" format */
 	model: string;
-	/** Role: "default", "smol", "slow", etc. Undefined treated as "default" */
+	/** Role: "default" or an agent role. Undefined treated as "default" */
 	role?: string;
 }
 

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

@@ -0,0 +1,29 @@
+# GJC Hermes operator instructions v{{TEMPLATE_VERSION}}
+
+Server key: {{SERVER_KEY}}
+
+These instructions teach a Hermes-style coordinator how to operate GJC through the `{{TOOL_PREFIX}}_*` MCP tools. They are setup guidance, not a GJC workflow skill.
+
+## Core loop
+
+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.
+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.
+
+Do not report completion to the user until the GJC turn is terminal. Do not infer completion from terminal scrollback alone.
+
+## Model and provider policy
+
+The Hermes bridge does not choose a model/provider. When no session command is configured, GJC uses its normal local model/provider resolution. If the operator config supplies `GJC_COORDINATOR_MCP_SESSION_COMMAND`, preserve it as explicit user intent.
+
+Provider-specific commands are examples only, never product defaults.
+
+## Safety
+
+- Mutating tools require bridge startup mutation classes and per-call consent.
+- Allowed roots restrict workdir and artifact paths.
+- Artifact reads are bounded and should be treated as evidence, not unlimited filesystem access.