@gajae-code/coding-agent 0.9.1 → 0.9.3

package/dist/types/session/agent-session.d.ts

@@ -156,6 +156,10 @@ export interface AsyncJobSnapshot {
     recent: AsyncJobSnapshotItem[];
     delivery: AsyncJobDeliveryState;
 }
+export interface RetainedMemorySample {
+    tuiChatChildren?: number;
+    tuiCachedRenderBytes?: number;
+}
 export interface AgentSessionConfig {
     agent: Agent;
     sessionManager: SessionManager;
@@ -237,6 +241,8 @@ export interface AgentSessionConfig {
      * **MUST NOT** dispose it on their own teardown.
      */
     ownedAsyncJobManager?: AsyncJobManager;
+    /** Cheap TUI retained-memory counters; absent for headless sessions. */
+    retainedMemorySampler?: () => RetainedMemorySample;
     /**
      * MCPManager whose lifecycle this session owns (top-level sessions that
      * connected plugin-bundle MCP servers). Only the owned manager is
@@ -270,6 +276,8 @@ export interface PromptOptions {
     images?: ImageContent[];
     /** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). */
     streamingBehavior?: "steer" | "followUp";
+    /** When set to "sequential", this follow-up is delivered one prompt at a time even if followUpMode is "all". */
+    followUpQueuePolicy?: "respect-mode" | "sequential";
     /** Optional tool choice override for the next LLM call. */
     toolChoice?: ToolChoice;
     /** Send as developer/system message instead of user. Providers that support it use the developer role; others fall back to user. */
@@ -366,6 +374,15 @@ export declare const __agentSessionPerfCounters: {
     reset(): void;
 };
 export declare function buildContextInjectionSignature(kind: string, parts: readonly string[]): string;
+export declare class StreamingEditFileCache {
+    #private;
+    get(path: string): string | undefined;
+    set(path: string, content: string): void;
+    delete(path: string): void;
+    clear(): void;
+    has(path: string): boolean;
+    get totalBytes(): number;
+}
 export declare class AgentSession {
     #private;
     readonly agent: Agent;
@@ -657,7 +674,7 @@ export declare class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     prompt(text: string, options?: PromptOptions): Promise<void>;
-    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice">): Promise<void>;
+    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy">): Promise<void>;
     /**
      * Queue a steering message to interrupt the agent mid-run.
      */
@@ -665,7 +682,7 @@ export declare class AgentSession {
     /**
      * Queue a follow-up message to process after the agent would otherwise stop.
      */
-    followUp(text: string, images?: ImageContent[]): Promise<void>;
+    followUp(text: string, images?: ImageContent[], options?: Pick<PromptOptions, "followUpQueuePolicy">): Promise<void>;
     queueDeferredMessage(message: CustomMessage): void;
     queueDeferredMessageForTests(message: CustomMessage, triggerTurn?: boolean): void;
     /**
@@ -679,6 +696,7 @@ export declare class AgentSession {
     sendCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: {
         triggerTurn?: boolean;
         deliverAs?: "steer" | "followUp" | "nextTurn";
+        followUpQueuePolicy?: "respect-mode" | "sequential";
     }): Promise<void>;
     /** Remove undelivered queued custom messages matching `predicate` from executable queues and tagged display mirrors. */
     purgeQueuedCustomMessages(predicate: (message: CustomMessage) => boolean): PurgeQueuedCustomMessagesResult;
@@ -834,7 +852,7 @@ export declare class AgentSession {
     getAvailableModels(): Model[];
     /**
      * Set thinking level.
-     * Saves the effective metadata-clamped level to session and settings only if it changes.
+     * Saves the effective metadata-clamped level to the session, and to settings when requested.
      */
     setThinkingLevel(level: ThinkingLevel | undefined, persist?: boolean): void;
     /**
@@ -932,6 +950,7 @@ export declare class AgentSession {
     prepareContributionPrep(options?: ContributionPrepOptions): Promise<ContributionPrepResult>;
     /** Test seam: override the emergency-compaction resource sampler so tests never read real RSS. */
     setResourceSampler(sampler: () => EmergencyCompactionSample): void;
+    setRetainedMemorySampler(sampler: (() => RetainedMemorySample) | undefined): void;
     /**
      * Toggle auto-compaction setting.
      */

package/dist/types/session/session-manager.d.ts

@@ -535,6 +535,7 @@ export declare class SessionManager {
     getInjectedTtsrRules(): string[];
     getLeafId(): string | null;
     getLeafEntry(): SessionEntry | undefined;
+    getResidentImageBytes(): number;
     /**
      * Get the most recent model role from the current session path.
      * Returns undefined if no model change has been recorded.

package/dist/types/tools/index.d.ts

@@ -53,6 +53,7 @@ export * from "./review";
 export * from "./search";
 export * from "./search-tool-bm25";
 export * from "./skill";
+export * from "./skill-discovery";
 export * from "./ssh";
 export * from "./subagent";
 export * from "./telegram-send";

package/dist/types/tools/skill-discovery.d.ts

@@ -0,0 +1,40 @@
+import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
+import * as z from "zod/v4";
+import { type RuntimeSkillDiscoveryCandidate } from "../extensibility/runtime-skill-discovery";
+import type { ToolSession } from ".";
+declare const skillDiscoverySchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        project: "project";
+        user: "user";
+    }>>>;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+}, z.core.$strict>;
+export type SkillDiscoveryToolInput = z.infer<typeof skillDiscoverySchema>;
+export interface SkillDiscoveryToolDetails {
+    candidates: RuntimeSkillDiscoveryCandidate[];
+    count: number;
+}
+export declare class SkillDiscoveryTool implements AgentTool<typeof skillDiscoverySchema, SkillDiscoveryToolDetails> {
+    #private;
+    readonly name = "skill_discovery";
+    readonly label = "SkillDiscovery";
+    readonly summary = "Discover project and user runtime skills by thin metadata";
+    readonly loadMode = "essential";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        query: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+            all: "all";
+            project: "project";
+            user: "user";
+        }>>>;
+        limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    }, z.core.$strict>;
+    readonly strict = true;
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): SkillDiscoveryTool | null;
+    execute(_toolCallId: string, input: SkillDiscoveryToolInput, signal?: AbortSignal): Promise<AgentToolResult<SkillDiscoveryToolDetails>>;
+}
+export {};

package/dist/types/tools/skill.d.ts

@@ -4,15 +4,16 @@
  * Lets the agent hand off to another available skill in the current turn. The
  * callee's SKILL.md is dispatched through the same custom-message path used by
  * `/skill:<name>` typing, as a user-attribution message delivered same-turn
- * (without `deliverAs: "nextTurn"`). Before dispatch, the tool calls
- * `gjc state <caller> handoff --to <callee>` in-process via the state-runtime
- * function so caller and callee mode-states plus `skill-active-state.json`
- * transition atomically.
+ * (without `deliverAs: "nextTurn"`). When the caller is one of the canonical
+ * workflow skills, the tool first runs the native state handoff so workflow
+ * mode-state and `skill-active-state.json` transition atomically. Runtime
+ * project/user skills have no native workflow mode-state, so they are dispatched
+ * directly and tracked by the prompt observer instead.
  *
- * Chaining is refused unless the caller's `current_phase` is in
- * `{complete, completed, handoff, failed, cancelled, canceled, inactive}`. The
- * agent declares readiness either by writing `current_phase: "handoff"` to its
- * mode-state or by running the handoff verb directly.
+ * Canonical workflow chaining is refused unless the caller's `current_phase` is
+ * in `{complete, completed, handoff, failed, cancelled, canceled, inactive}`.
+ * The agent declares readiness either by writing `current_phase: "handoff"` to
+ * its mode-state or by running the handoff verb directly.
  */
 import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
 import * as z from "zod/v4";

package/dist/types/utils/linkedom.d.ts

@@ -0,0 +1,4 @@
+type LinkedomModule = typeof import("linkedom");
+type ParseHtml = LinkedomModule["parseHTML"];
+export declare function parseHtmlLazy(markup: string): Promise<ReturnType<ParseHtml>>;
+export {};

package/dist/types/utils/pasted-image-path.d.ts

@@ -23,8 +23,10 @@ export interface ResolvePastedImagePathOptions extends DecodePastedPathOptions {
  */
 export declare function decodePastedPathCandidate(text: string, options?: DecodePastedPathOptions): string | undefined;
 /**
- * Returns the resolved path when the whole pasted text is a single path to an
- * existing image file (verified by extension AND content signature),
- * otherwise `undefined` (the paste is inserted as text).
+ * Returns the resolved path when the whole pasted text is a recognized clipboard
+ * temp path to an existing image file, otherwise `undefined` (the paste is
+ * inserted as text). Arbitrary saved image paths are not auto-attached here;
+ * users attach them explicitly with `@path/to/image.png`.
  */
 export declare function resolvePastedImagePath(text: string, options?: ResolvePastedImagePathOptions): string | undefined;
+export declare function formatPastedImageReference(placeholder: string, imagePath: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.9.1",
+	"version": "0.9.3",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -49,12 +49,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.9.1",
-		"@gajae-code/agent-core": "0.9.1",
-		"@gajae-code/ai": "0.9.1",
-		"@gajae-code/natives": "0.9.1",
-		"@gajae-code/tui": "0.9.1",
-		"@gajae-code/utils": "0.9.1",
+		"@gajae-code/stats": "0.9.3",
+		"@gajae-code/agent-core": "0.9.3",
+		"@gajae-code/ai": "0.9.3",
+		"@gajae-code/natives": "0.9.3",
+		"@gajae-code/tui": "0.9.3",
+		"@gajae-code/utils": "0.9.3",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",
@@ -85,6 +85,10 @@
 		"README.md",
 		"CHANGELOG.md",
 		"vendor",
+		"!vendor/insane-search/engine/tests/**",
+		"!src/export/html/template.html",
+		"!src/export/html/template.css",
+		"!src/export/html/template.js",
 		"dist/types"
 	],
 	"exports": {

package/scripts/build-binary.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import * as path from "node:path";
+import { buildDevCompileArgs } from "./compile-args";
 
 const packageDir = path.join(import.meta.dir, "..");
 const outputPath = path.join(packageDir, "dist", "gjc");
@@ -34,46 +35,7 @@ async function main(): Promise<void> {
 		await runCommand(["bun", "--cwd=../natives", "run", "embed:native"]);
 		try {
 			const buildEnv = shouldAdhocSignDarwinBinary() ? { ...Bun.env, BUN_NO_CODESIGN_MACHO_BINARY: "1" } : Bun.env;
-			await runCommand(
-				[
-					"bun",
-					"build",
-					"--compile",
-					// Minify shrinks the bundled JS the compiled binary must parse at
-					// startup (302MB → ~114MB --help RSS measured on darwin-arm64).
-					// --keep-names below preserves identifiers for error reports.
-					"--minify",
-					"--no-compile-autoload-bunfig",
-					"--no-compile-autoload-dotenv",
-					"--no-compile-autoload-tsconfig",
-					"--no-compile-autoload-package-json",
-					"--keep-names",
-					"--define",
-					'process.env.PI_COMPILED="true"',
-					"--external",
-					"mupdf",
-					"--root",
-					"../..",
-					"./src/cli.ts",
-					// Worker entrypoints. Bun's `--compile` discovers the literal in
-					// `new Worker("…", …)` at each spawn site, but only actually
-					// emits the worker into the bunfs root when it is listed here as
-					// an explicit additional entry. Paths are relative to this
-					// script's cwd (packages/coding-agent) and the `--root` above
-					// (../..) makes them appear inside the binary at
-					// `/$bunfs/root/packages/<pkg>/src/<worker>.js`, which is
-					// exactly what the literals at the spawn sites resolve to.
-					"../stats/src/sync-worker.ts",
-					"./src/tools/browser/tab-worker-entry.ts",
-					"./src/eval/js/worker-entry.ts",
-					// Hidden notify daemon CLI (loaded via dynamic import from notify-cli); list it
-					// explicitly so Bun standalone keeps `gjc notify daemon-internal` usable.
-					"./src/notifications/telegram-daemon-cli.ts",
-					"--outfile",
-					"dist/gjc",
-				],
-				buildEnv,
-			);
+			await runCommand(buildDevCompileArgs(), buildEnv);
 
 			await stageWorkspaceNativeAddons();
 			// Bun 1.3.12 emits a truncated Mach-O signature on darwin builds.

package/scripts/compile-args.ts

@@ -0,0 +1,91 @@
+export interface CompileArgOptions {
+	root: string;
+	entrypoints: string[];
+	outfile: string;
+	target?: string;
+	defines?: string[];
+	externals?: string[];
+}
+
+export const compileAutoloadDisableFlags = [
+	"--no-compile-autoload-bunfig",
+	"--no-compile-autoload-dotenv",
+	"--no-compile-autoload-tsconfig",
+	"--no-compile-autoload-package-json",
+];
+
+export const compiledDefineFlags = ['process.env.PI_COMPILED="true"'];
+export const compiledExternalPackages = ["mupdf"];
+
+export const releaseEntrypoints = [
+	"./packages/coding-agent/src/cli.ts",
+	"./packages/stats/src/sync-worker.ts",
+	"./packages/coding-agent/src/tools/browser/tab-worker-entry.ts",
+	"./packages/coding-agent/src/eval/js/worker-entry.ts",
+	"./packages/natives/native/index.js",
+	"./packages/coding-agent/src/notifications/telegram-daemon-cli.ts",
+	"./packages/ai/src/models.json",
+	"./node_modules/handlebars/lib/index.js",
+];
+
+export const devEntrypoints = [
+	"./src/cli.ts",
+	"../stats/src/sync-worker.ts",
+	"./src/tools/browser/tab-worker-entry.ts",
+	"./src/eval/js/worker-entry.ts",
+	"./src/notifications/telegram-daemon-cli.ts",
+	"../ai/src/models.json",
+	"../../node_modules/handlebars/lib/index.js",
+];
+
+export function buildReleaseCompileArgs(target: string, outfile: string): string[] {
+	return buildCompileArgs({
+		root: ".",
+		entrypoints: releaseEntrypoints,
+		outfile,
+		target,
+		defines: compiledDefineFlags,
+		externals: compiledExternalPackages,
+	});
+}
+
+export function buildDevCompileArgs(outfile = "dist/gjc"): string[] {
+	return buildCompileArgs({
+		root: "../..",
+		entrypoints: devEntrypoints,
+		outfile,
+		defines: compiledDefineFlags,
+		externals: compiledExternalPackages,
+	});
+}
+
+export function buildCompileArgs(options: CompileArgOptions): string[] {
+	const args = [
+		"bun",
+		"build",
+		"--compile",
+		// Minify shrinks the bundled JS the compiled binary must parse at
+		// startup (302MB → ~114MB --help RSS measured on darwin-arm64).
+		// --keep-names below preserves identifiers for error reports.
+		"--minify",
+		...compileAutoloadDisableFlags,
+		"--keep-names",
+	];
+
+	for (const define of options.defines ?? []) {
+		args.push("--define", define);
+	}
+
+	args.push("--root", options.root);
+
+	for (const external of options.externals ?? []) {
+		args.push("--external", external);
+	}
+
+	if (options.target) {
+		args.push("--target", options.target);
+	}
+
+	args.push(...options.entrypoints, "--outfile", options.outfile);
+	return args;
+}

package/scripts/generate-docs-index.ts

@@ -58,6 +58,7 @@ const mapEntries = docsWithContent
 	.join("\n");
 const output = [
 	"// Auto-generated by scripts/generate-docs-index.ts - DO NOT EDIT",
+	`Reflect.set(globalThis, Symbol.for("gjc.docs-index.generated.loaded"), true);`,
 	"",
 	`export const EMBEDDED_DOC_FILENAMES: readonly string[] = ${filenamesLiteral};`,
 	"",

package/src/capability/mcp.ts

@@ -15,7 +15,7 @@ export interface MCPServer {
 	name: string;
 	/** Whether this server is enabled (default: true) */
 	enabled?: boolean;
-	/** Whether to connect automatically at session startup (default: true) */
+	/** Whether explicit runtime MCP consumers should connect automatically (default: true) */
 	autoload?: boolean;
 	/** Connection timeout in milliseconds */
 	timeout?: number;
@@ -25,6 +25,8 @@ export interface MCPServer {
 	args?: string[];
 	/** Environment variables */
 	env?: Record<string, string>;
+	/** Whether explicit stdio runtime consumers should avoid inheriting host environment */
+	noInheritEnv?: boolean;
 	/** Working directory for stdio transport */
 	cwd?: string;
 	/** URL (for HTTP/SSE transport) */

package/src/cli/args.ts

@@ -3,6 +3,7 @@
  */
 import { type Effort, THINKING_EFFORTS } from "@gajae-code/ai";
 import { APP_NAME, CONFIG_DIR_NAME, logger } from "@gajae-code/utils";
+import { CliParseError } from "@gajae-code/utils/cli";
 import chalk from "chalk";
 import { parseEffort } from "../thinking";
 import { BUILTIN_TOOLS } from "../tools";
@@ -20,6 +21,7 @@ export interface Args {
 	mpreset?: string;
 	default?: boolean;
 	apiKey?: string;
+	credential?: string;
 	systemPrompt?: string;
 	appendSystemPrompt?: string;
 	thinking?: Effort;
@@ -136,6 +138,12 @@ export function parseArgs(args: string[]): Args {
 			result.default = true;
 		} else if (arg === "--api-key" && i + 1 < args.length) {
 			result.apiKey = args[++i];
+		} else if (arg === "--credential") {
+			const next = args[i + 1];
+			if (!next || next.startsWith("-")) {
+				throw new CliParseError("--credential requires <selector>");
+			}
+			result.credential = args[++i];
 		} else if (arg === "--system-prompt" && i + 1 < args.length) {
 			result.systemPrompt = args[++i];
 		} else if (arg === "--append-system-prompt" && i + 1 < args.length) {

package/src/cli/mcp-cli.ts

@@ -37,14 +37,27 @@ interface ScopedPath {
 	path: string;
 }
 
+interface RuntimeDisclosure {
+	runtimeStatus: "storage-only";
+	runtimeLoadedByStandalone: false;
+	runtimeNote: string;
+}
+
 interface RedactedServerEntry {
 	name: string;
 	config: MCPServerConfig;
 }
 
+interface RuntimeRedactedServerEntry extends RedactedServerEntry, RuntimeDisclosure {}
+
 const REDACTED = "<redacted>";
 const SENSITIVE_KEY_PATTERN =
 	/(?:token|secret|key|credential|password|passwd|pwd|authorization|auth|bearer|cookie|session)/i;
+const STORAGE_ONLY_RUNTIME_DISCLOSURE: RuntimeDisclosure = {
+	runtimeStatus: "storage-only",
+	runtimeLoadedByStandalone: false,
+	runtimeNote: "Stored MCP registrations are not loaded by normal standalone gjc sessions today.",
+};
 
 function resolvePath(args: MCPCommandArgs): ScopedPath {
 	const scope = args.flags.project ? "project" : "user";
@@ -128,6 +141,50 @@ function redactRecord(
 	);
 }
 
+function redactUrl(value: string | undefined): string | undefined {
+	if (!value) return value;
+	try {
+		const url = new URL(value);
+		if (url.username) url.username = REDACTED;
+		if (url.password) url.password = REDACTED;
+		if (url.search) {
+			for (const key of Array.from(url.searchParams.keys())) {
+				url.searchParams.set(key, REDACTED);
+			}
+		}
+		url.hash = "";
+		return url.toString();
+	} catch {
+		return SENSITIVE_KEY_PATTERN.test(value) ? REDACTED : value;
+	}
+}
+
+function redactArgs(args: string[] | undefined): string[] | undefined {
+	if (!args) return undefined;
+	const redacted: string[] = [];
+	let redactNext = false;
+	for (const arg of args) {
+		if (redactNext) {
+			redacted.push(REDACTED);
+			redactNext = false;
+			continue;
+		}
+		const equalsIndex = arg.indexOf("=");
+		if (equalsIndex > 0) {
+			const key = arg.slice(0, equalsIndex);
+			redacted.push(SENSITIVE_KEY_PATTERN.test(key) ? `${key}=${REDACTED}` : arg);
+			continue;
+		}
+		if (arg.startsWith("-") && SENSITIVE_KEY_PATTERN.test(arg)) {
+			redacted.push(arg);
+			redactNext = true;
+			continue;
+		}
+		redacted.push(SENSITIVE_KEY_PATTERN.test(arg) ? REDACTED : arg);
+	}
+	return redacted;
+}
+
 export function redactMCPServerConfig(config: MCPServerConfig): MCPServerConfig {
 	const redacted = { ...config } as MCPServerConfig;
 	if ("env" in redacted) {
@@ -138,11 +195,19 @@ export function redactMCPServerConfig(config: MCPServerConfig): MCPServerConfig
 		const headers = redactRecord(redacted.headers, true);
 		if (headers) redacted.headers = headers;
 	}
+	if ("url" in redacted) {
+		const url = redactUrl(redacted.url);
+		if (url) redacted.url = url;
+	}
+	if ("args" in redacted) {
+		const args = redactArgs(redacted.args);
+		if (args) redacted.args = args;
+	}
 	if (redacted.auth) {
 		redacted.auth = {
 			type: redacted.auth.type,
 			credentialId: redacted.auth.credentialId ? REDACTED : undefined,
-			tokenUrl: redacted.auth.tokenUrl,
+			tokenUrl: redactUrl(redacted.auth.tokenUrl),
 			clientId: redacted.auth.clientId ? REDACTED : undefined,
 			clientSecret: redacted.auth.clientSecret ? REDACTED : undefined,
 		};
@@ -151,7 +216,7 @@ export function redactMCPServerConfig(config: MCPServerConfig): MCPServerConfig
 		redacted.oauth = {
 			clientId: redacted.oauth.clientId ? REDACTED : undefined,
 			clientSecret: redacted.oauth.clientSecret ? REDACTED : undefined,
-			redirectUri: redacted.oauth.redirectUri,
+			redirectUri: redactUrl(redacted.oauth.redirectUri),
 			callbackPort: redacted.oauth.callbackPort,
 			callbackPath: redacted.oauth.callbackPath,
 		};
@@ -159,10 +224,14 @@ export function redactMCPServerConfig(config: MCPServerConfig): MCPServerConfig
 	return redacted;
 }
 
-function collectEntries(config: MCPConfigFile): RedactedServerEntry[] {
+function withRuntimeDisclosure<T extends object>(value: T): T & RuntimeDisclosure {
+	return { ...value, ...STORAGE_ONLY_RUNTIME_DISCLOSURE };
+}
+
+function collectEntries(config: MCPConfigFile): RuntimeRedactedServerEntry[] {
 	return Object.entries(config.mcpServers ?? {})
 		.sort(([a], [b]) => a.localeCompare(b))
-		.map(([name, serverConfig]) => ({ name, config: redactMCPServerConfig(serverConfig) }));
+		.map(([name, serverConfig]) => withRuntimeDisclosure({ name, config: redactMCPServerConfig(serverConfig) }));
 }
 
 function writeJson(value: unknown): void {
@@ -188,37 +257,46 @@ async function runAdd(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
 	const result = await upsertMCPServer(scoped.path, args.name, config, { force: args.flags.force });
 	const redacted = redactMCPServerConfig(config);
 	if (args.flags.json) {
-		writeJson({
-			action: "add",
-			status: result.status,
-			name: args.name,
-			scope: scoped.scope,
-			path: scoped.path,
-			config: redacted,
-		});
+		writeJson(
+			withRuntimeDisclosure({
+				action: "add",
+				status: result.status,
+				name: args.name,
+				scope: scoped.scope,
+				path: scoped.path,
+				config: redacted,
+			}),
+		);
 		return;
 	}
 	if (result.status === "skipped") {
 		process.stdout.write(
-			`MCP server "${args.name}" already exists in ${scoped.scope} config. Pass --force to overwrite.\n`,
+			`MCP server "${args.name}" already exists in ${scoped.scope} config. Pass --force to overwrite. ` +
+				"Status: storage-only; normal standalone gjc sessions do not load stored MCP registrations today.\n",
 		);
 		return;
 	}
-	process.stdout.write(`MCP server "${args.name}" ${result.status} in ${scoped.scope} config: ${scoped.path}\n`);
+	process.stdout.write(
+		`MCP server "${args.name}" ${result.status} in ${scoped.scope} config: ${scoped.path}\nStatus: storage-only; normal standalone gjc sessions do not load stored MCP registrations today.\n`,
+	);
 }
 
 async function runList(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
 	const config = await readMCPConfigFile(scoped.path);
 	const entries = collectEntries(config);
 	if (args.flags.json) {
-		writeJson({ action: "list", scope: scoped.scope, path: scoped.path, servers: entries });
+		writeJson(withRuntimeDisclosure({ action: "list", scope: scoped.scope, path: scoped.path, servers: entries }));
 		return;
 	}
 	if (entries.length === 0) {
-		process.stdout.write(`No MCP servers registered in ${scoped.scope} config: ${scoped.path}\n`);
+		process.stdout.write(
+			`No MCP servers registered in ${scoped.scope} config: ${scoped.path}\nStatus: storage-only; normal standalone gjc sessions do not load stored MCP registrations today.\n`,
+		);
 		return;
 	}
-	process.stdout.write(`MCP servers in ${scoped.scope} config: ${scoped.path}\n`);
+	process.stdout.write(
+		`MCP servers in ${scoped.scope} config: ${scoped.path}\nStatus: storage-only; normal standalone gjc sessions do not load stored MCP registrations today.\n`,
+	);
 	for (const entry of entries) {
 		process.stdout.write(`${renderDetails(entry)}\n`);
 	}
@@ -233,17 +311,21 @@ async function runRemove(args: MCPCommandArgs, scoped: ScopedPath): Promise<void
 	await removeMCPServer(scoped.path, args.name);
 	const entry = { name: args.name, config: redactMCPServerConfig(existing) };
 	if (args.flags.json) {
-		writeJson({
-			action: "remove",
-			status: "removed",
-			name: args.name,
-			scope: scoped.scope,
-			path: scoped.path,
-			removed: entry,
-		});
+		writeJson(
+			withRuntimeDisclosure({
+				action: "remove",
+				status: "removed",
+				name: args.name,
+				scope: scoped.scope,
+				path: scoped.path,
+				removed: entry,
+			}),
+		);
 		return;
 	}
-	process.stdout.write(`Removed MCP server "${args.name}" from ${scoped.scope} config: ${scoped.path}\n`);
+	process.stdout.write(
+		`Removed MCP server "${args.name}" from ${scoped.scope} config: ${scoped.path}\nStatus: storage-only; normal standalone gjc sessions do not load stored MCP registrations today.\n`,
+	);
 	process.stdout.write(`${renderDetails(entry)}\n`);
 }