@gajae-code/coding-agent 0.11.10 → 0.11.11

package/dist/types/tools/resource-gc.d.ts

@@ -1,3 +1,4 @@
+import type { WindowsJobMemoryProbeResult } from "@gajae-code/natives";
 import type { Settings } from "../config/settings";
 import { type TabGcSnapshot } from "./browser/tab-supervisor";
 export interface BrowserGcPolicy {
@@ -16,7 +17,10 @@ export declare function resolveSweepIntervalMs(settings: Settings): number;
 /** Injectable seams so the controller is fully testable without real browsers/filesystem/RSS. */
 export interface ResourceGcDeps {
     now: () => number;
+    monotonicNow: () => number;
     rssBytes: () => number;
+    memorySnapshot: () => Promise<MemoryPressureSnapshot>;
+    runGc: () => void;
     logWarn: (msg: string, meta?: Record<string, unknown>) => void;
     listTabs: () => TabGcSnapshot[];
     releaseTab: (name: string, policy: {
@@ -43,6 +47,21 @@ export interface ResourceGcRegistration {
  */
 export declare function registerResourceGcSession(reg: ResourceGcRegistration): () => void;
 export declare function sweepOnce(d?: ResourceGcDeps): Promise<void>;
+export interface MemoryPressureDomain {
+    hardCapBytes: number;
+    totalUsageBytes: number;
+    source: MemoryPressureSnapshot["source"];
+}
+export interface MemoryPressureSnapshot {
+    hardCapBytes: number;
+    totalUsageBytes: number;
+    parentBytes: number;
+    source: "host" | "linux_cgroup_v2" | "linux_cgroup_v1" | "windows_job" | "windows_process_job_limit";
+    domains?: MemoryPressureDomain[];
+}
+export declare function __sampleLinuxCgroupHierarchyForTest(mountInfo: string, membership: string, fsType: "cgroup" | "cgroup2", hostBytes: number, parentBytes: number): Promise<MemoryPressureSnapshot | null>;
+export declare function __sampleWindowsJobMemoryForTest(hostBytes: number, parentBytes: number, probeResult?: WindowsJobMemoryProbeResult): MemoryPressureSnapshot | null;
+export declare function __selectMemoryPressureDomainForTest(snapshot: MemoryPressureSnapshot, policyLimitBytes: number | null): MemoryPressureSnapshot;
 export declare function __setResourceGcDepsForTest(overrides: Partial<ResourceGcDeps>): void;
 export declare function __setResourceGcSchedulerNowForTest(now: () => number): void;
 export declare function __runResourceGcTickForTest(): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.11.10",
+	"version": "0.11.11",
 	"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",
@@ -53,13 +53,13 @@
 		"@agentclientprotocol/sdk": "1.2.1",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.11.10",
-		"@gajae-code/agent-core": "0.11.10",
-		"@gajae-code/ai": "0.11.10",
-		"@gajae-code/bridge-client": "0.11.10",
-		"@gajae-code/natives": "0.11.10",
-		"@gajae-code/tui": "0.11.10",
-		"@gajae-code/utils": "0.11.10",
+		"@gajae-code/stats": "0.11.11",
+		"@gajae-code/agent-core": "0.11.11",
+		"@gajae-code/ai": "0.11.11",
+		"@gajae-code/bridge-client": "0.11.11",
+		"@gajae-code/natives": "0.11.11",
+		"@gajae-code/tui": "0.11.11",
+		"@gajae-code/utils": "0.11.11",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/scripts/generate-sdk-operation-inventory.ts

@@ -86,6 +86,7 @@ const LOCKED_EXCLUSIONS: Readonly<Record<string, string>> = {
 	"agent_session:refreshMCPTools": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:refreshGjcSubskillTools": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:buildDisplaySessionContext": "internal accessor/plumbing, not a user-facing control seam",
+	"agent_session:buildPreparedDisplaySessionContext": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:convertMessagesToLlm": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:prepareSimpleStreamOptions": "internal accessor/plumbing, not a user-facing control seam",
 	"agent_session:getPlanModeState": "internal accessor/plumbing, not a user-facing control seam",
@@ -198,6 +199,7 @@ const SEAM_TO_SDK: Readonly<Record<string, string>> = {
 	"agent_session:setSessionName": "session.rename",
 	"agent_session:setModel": "model.set",
 	"agent_session:setDefaultModelSelection": "model.set",
+	"agent_session:activateModelProfileForControl": "model.profile.set",
 	"agent_session:cycleModel": "model.cycle",
 	"agent_session:setThinkingLevel": "thinking.set",
 	"agent_session:cycleThinkingLevel": "thinking.cycle",

package/scripts/run-test-manifest.ts

@@ -36,6 +36,8 @@ try {
 function validateRowReceipts(rows: ManifestAdapterRow[]): void {
 	const ids = new Set<string>();
 	const counts = new Map<string, number>();
+	// Each operation has one receipt, plus the dedicated config.patch secret-input receipt.
+	const expectedRowsPerAdapter = OPERATIONS.length + 1;
 	for (const row of rows) {
 		if (ids.has(row.adapterTestId)) throw new Error(`Duplicate adapter test ID: ${row.adapterTestId}`);
 		ids.add(row.adapterTestId);
@@ -60,11 +62,11 @@ function validateRowReceipts(rows: ManifestAdapterRow[]): void {
 		}
 		counts.set(row.adapter, (counts.get(row.adapter) ?? 0) + 1);
 	}
-	if (rows.length !== ADAPTERS.length * 93)
-		throw new Error(`Expected ${ADAPTERS.length * 93} adapter rows; received ${rows.length}.`);
+	if (rows.length !== ADAPTERS.length * expectedRowsPerAdapter)
+		throw new Error(`Expected ${ADAPTERS.length * expectedRowsPerAdapter} adapter rows; received ${rows.length}.`);
 	for (const adapter of ADAPTERS) {
-		if (counts.get(adapter) !== 93)
-			throw new Error(`Expected 93 ${adapter} rows; received ${counts.get(adapter) ?? 0}.`);
+		if (counts.get(adapter) !== expectedRowsPerAdapter)
+			throw new Error(`Expected ${expectedRowsPerAdapter} ${adapter} rows; received ${counts.get(adapter) ?? 0}.`);
 	}
 	process.stdout.write(
 		`manifest check: ${rows.length} row receipts (${[...counts].map(([adapter, count]) => `${adapter}=${count}`).join(", ")})\n`,

package/src/cli/args.ts

@@ -205,17 +205,23 @@ export function parseArgs(args: string[]): Args {
 				}
 			}
 			result.tools = validTools;
-		} else if (arg === "--thinking" && i + 1 < args.length) {
+		} else if (arg === "--thinking") {
+			// Match --credential / --mcp-config: a missing value or a following flag is
+			// a usage error, not a silent no-op / accidental consumption of `-p`.
+			const next = args[i + 1];
+			if (!next || next.startsWith("-")) {
+				throw new CliParseError(`--thinking requires <level> (${THINKING_EFFORTS.join(", ")})`);
+			}
 			const rawThinking = args[++i];
 			const thinking = parseEffort(rawThinking);
-			if (thinking !== undefined) {
-				result.thinking = thinking;
-			} else {
-				logger.warn("Invalid thinking level passed to --thinking", {
-					level: rawThinking,
-					validThinkingLevels: THINKING_EFFORTS,
-				});
+			if (thinking === undefined) {
+				// Fail closed: a silent ignore left users believing `ultra` (or any typo)
+				// was applied. Help / Flags.options advertise the real Effort enum.
+				throw new CliParseError(
+					`Invalid --thinking level "${rawThinking}". Expected one of: ${THINKING_EFFORTS.join(", ")}`,
+				);
 			}
+			result.thinking = thinking;
 		} else if (arg === "--print" || arg === "-p") {
 			result.print = true;
 		} else if (arg === "--export" && i + 1 < args.length) {

package/src/cli/fast-help.ts

@@ -84,7 +84,7 @@ Environment Variables:
   GJC_LAUNCH_POLICY           - Launch policy for --tmux startup: tmux or direct
   GJC_TMUX_SESSION            - Explicit tmux session name override for --tmux startup
   GJC_TMUX_PROFILE            - Apply GJC tmux scroll/mouse/clipboard profile to --tmux sessions (set 0/off to skip)
-  GJC_MOUSE                   - Mouse-wheel scroll in --tmux sessions (set 0/off to let the host terminal scroll)
+  GJC_MOUSE                   - Apply tmux copy-mode mouse capture in --tmux sessions (set 0/off to skip)
 
   For complete environment variable reference, see:
   docs/environment-variables.md

package/src/cli.ts

@@ -5,8 +5,10 @@
  * lightweight CLI runner from pi-utils.
  */
 import "@gajae-code/utils/postmortem";
+import { THINKING_EFFORTS } from "@gajae-code/ai";
 import { Args, type CliConfig, Command, type CommandEntry, Flags, run } from "@gajae-code/utils/cli";
 import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@gajae-code/utils/dirs";
+import { loadNative as loadNativeBindings } from "../../natives/native/loader-state.js";
 import { runFixtureReport } from "./cli/fixture-report";
 import { admitManagedOwnerBeforeCli, completeManagedOwnerRecovery } from "./gjc-runtime/managed-owner-admission";
 import {
@@ -174,6 +176,46 @@ async function runChatDaemonInternalFastPath(argv: string[]): Promise<void> {
 	await runChatDaemonInternal(action === "discord-internal" ? "discord" : "slack", argv.slice(2));
 }
 
+type MemoryGuardNativeSmokeLoad = () => Record<string, unknown>;
+type WindowsJobMemoryProbeResult = Record<string, unknown> & { kind: string };
+type MemoryGuardNativeSmokeReceipt = {
+	api: "memory_guard_windows_job_probe_v1";
+	source: "pi_natives";
+	result: WindowsJobMemoryProbeResult;
+};
+
+export function isMemoryGuardNativeSmokeFastPath(argv: readonly string[]): boolean {
+	return (
+		argv.length === 3 && argv[0] === "internal" && argv[1] === "memory-guard-native-smoke" && argv[2] === "--json"
+	);
+}
+
+function parseWindowsJobMemoryProbeResult(value: unknown): WindowsJobMemoryProbeResult {
+	if (!value || typeof value !== "object") {
+		throw new Error("memory-guard-native-smoke: native probe returned a non-object result");
+	}
+	const result = value as Record<string, unknown>;
+	if (typeof result.kind !== "string") {
+		throw new Error("memory-guard-native-smoke: native probe result is missing a string kind tag");
+	}
+	return result as WindowsJobMemoryProbeResult;
+}
+
+export function runMemoryGuardNativeSmokeFastPath(
+	options: { loadNative?: MemoryGuardNativeSmokeLoad; writeStdout?: (text: string) => void } = {},
+): void {
+	const probe = (options.loadNative ?? loadNativeBindings)().probeWindowsJobMemory;
+	if (typeof probe !== "function") {
+		throw new Error("memory-guard-native-smoke: probeWindowsJobMemory export missing from native addon");
+	}
+	const receipt: MemoryGuardNativeSmokeReceipt = {
+		api: "memory_guard_windows_job_probe_v1",
+		source: "pi_natives",
+		result: parseWindowsJobMemoryProbeResult((probe as () => unknown)()),
+	};
+	(options.writeStdout ?? (text => process.stdout.write(text)))(`${JSON.stringify(receipt)}\n`);
+}
+
 function rootFixtureArg(argv: string[]): { present: boolean; id: string | undefined } {
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
@@ -244,8 +286,8 @@ export class RootHelpCommand extends Command {
 		tmux: Flags.boolean({ description: "Launch interactive startup inside tmux" }),
 		tools: Flags.string({ description: "Comma-separated list of tools to enable (default: all)" }),
 		thinking: Flags.string({
-			description: "Set thinking level: ultra, high, medium, low",
-			options: ["ultra", "high", "medium", "low"],
+			description: `Set thinking level: ${THINKING_EFFORTS.join(", ")}`,
+			options: [...THINKING_EFFORTS],
 		}),
 		hook: Flags.string({ description: "Load a hook/extension file (can be used multiple times)", multiple: true }),
 		extension: Flags.string({
@@ -382,6 +424,10 @@ export async function runCli(argv: string[]): Promise<void> {
 		}
 		// Re-exec could not be spawned; fall through and run in this process.
 	}
+	if (isMemoryGuardNativeSmokeFastPath(argv)) {
+		runMemoryGuardNativeSmokeFastPath();
+		return;
+	}
 	if (isTmuxOwnerIsolationCliArgv(argv)) {
 		await runTmuxOwnerIsolationCliFromStdin();
 		return;

package/src/commands/sdk.ts

@@ -1,11 +1,13 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
 import { Args, CliParseError, Command, Flags, renderCommandHelp } from "@gajae-code/utils/cli";
 import type { Args as ParsedArgs } from "../cli/args";
 import { Settings } from "../config/settings";
 import { applyStartupModelProfiles, createSessionManager } from "../main";
 import { initializeExtensions } from "../modes/runtime-init";
+import { ACP_MCP_REQUEST_TIMEOUT_MS, ACP_MCP_STARTUP_HEADROOM_MS } from "../sdk/acp/mcp";
 import { Broker } from "../sdk/broker/broker";
 import { completeBrokerProcess } from "../sdk/broker/internal";
 import {
@@ -285,17 +287,99 @@ export async function runSessionHost(
 		throw new Error("SDK startup did not complete before readiness cutoff.");
 	}
 
-	let opened: { parsed: ParsedArgs; sessionManager: SessionManager | undefined };
-	let created: CreateLifecycleAgentSessionResult;
-	try {
-		opened = await openLifecycleSessionManager(request, cwd, agentDir);
-		created = await createLifecycleAgentSession({ cwd, agentDir, sessionManager: opened.sessionManager });
-	} catch (error) {
+	// Inlined rather than extracted to a helper: TypeScript's definite-assignment
+	// analysis does not see a `Promise<never>` helper as terminating, so hoisting
+	// this would make `opened`/`created` "used before assigned" below.
+	const registrationFailure = async (error: unknown): Promise<SdkStartupFailure> => {
 		const rollback = new SdkStartupRollbackTracker();
 		rollback.recordAbsent();
 		const failure = normalizeSdkStartupFailure("registration", "failed", error);
 		await writeFailure(failure, rollback.result);
-		throw failure;
+		return failure;
+	};
+
+	let opened: { parsed: ParsedArgs; sessionManager: SessionManager | undefined };
+	let created: CreateLifecycleAgentSessionResult;
+	let mcpConfigDirectory: string | undefined;
+	try {
+		let mcpConfigPath: string | undefined;
+		try {
+			opened = await openLifecycleSessionManager(request, cwd, agentDir);
+			if (request.mcpServers && request.mcpServers.length > 0) {
+				mcpConfigDirectory = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "gjc-acp-mcp-")));
+				mcpConfigPath = path.join(mcpConfigDirectory, "mcp.json");
+				await Bun.write(
+					mcpConfigPath,
+					JSON.stringify({
+						mcpServers: Object.fromEntries(
+							request.mcpServers.map(server => [
+								server.name,
+								"url" in server
+									? {
+											type: server.type,
+											url: server.url,
+											...(server.headers ? { headers: server.headers } : {}),
+											timeout: ACP_MCP_REQUEST_TIMEOUT_MS,
+										}
+									: {
+											type: "stdio",
+											command: server.command,
+											args: server.args,
+											...(server.env ? { env: server.env } : {}),
+											noInheritEnv: true,
+											timeout: ACP_MCP_REQUEST_TIMEOUT_MS,
+										},
+							]),
+						),
+					}),
+				);
+			}
+		} catch (error) {
+			throw await registrationFailure(error);
+		}
+
+		// The longer MCP startup ceiling is scoped to ACP lifecycle launches only:
+		// it applies when this request actually carried `mcpServers`. Ordinary
+		// CLI/SDK `mcpConfigPath` consumers keep the manager's short default.
+		//
+		// This recheck deliberately sits OUTSIDE the registration catch above.
+		// Inside it, the throw would be caught, reclassified as
+		// `registration`/`failed`, and written a second time, losing the
+		// `startup`/`pending` outcome the readiness cutoff is supposed to report.
+		// Session-manager open and MCP config write already consumed part of the
+		// budget, so re-read the clock here rather than reusing the earlier check.
+		let mcpStartupTimeoutMs: number | undefined;
+		if (mcpConfigPath !== undefined) {
+			const remaining = request.semanticReadyDeadlineAt - now() - ACP_MCP_STARTUP_HEADROOM_MS;
+			if (remaining <= 0) {
+				const absent = new SdkStartupRollbackTracker();
+				absent.recordAbsent();
+				await writeFailure(
+					{
+						phase: "startup",
+						reason: "pending",
+						message: "SDK startup did not complete before readiness cutoff.",
+					},
+					absent.result,
+				);
+				throw new Error("SDK startup did not complete before readiness cutoff.");
+			}
+			mcpStartupTimeoutMs = remaining;
+		}
+
+		try {
+			created = await createLifecycleAgentSession({
+				cwd,
+				agentDir,
+				sessionManager: opened.sessionManager,
+				...(mcpConfigPath ? { mcpConfigPath } : {}),
+				...(mcpStartupTimeoutMs !== undefined ? { mcpStartupTimeoutMs } : {}),
+			});
+		} catch (error) {
+			throw await registrationFailure(error);
+		}
+	} finally {
+		if (mcpConfigDirectory) await fs.rm(mcpConfigDirectory, { recursive: true, force: true });
 	}
 	const { parsed } = opened;
 	if ("failure" in created) {

package/src/config/model-profile-activation.ts

@@ -222,6 +222,7 @@ export function materializeActiveModelProfileAssignments(options: MaterializeMod
 }
 
 export class ModelProfileCredentialError extends Error {
+	readonly code = "authentication_failed";
 	readonly profileLabel: string;
 	readonly providers: readonly string[];
 

package/src/config/model-profile-contract.ts

@@ -10,6 +10,7 @@ export interface ModelProfileCatalogItem {
 	id: string;
 	displayName: string;
 	source: "builtin" | "configured";
+	available?: boolean;
 }
 
 export interface UnknownModelProfileDetails {
@@ -124,6 +125,18 @@ export function projectModelProfileCatalog(
 		.sort((left, right) => left.id.localeCompare(right.id));
 }
 
+export function isModelProfileProviderAvailable(
+	profile: ModelProfileDefinition,
+	authenticatedProviders: ReadonlySet<string>,
+): boolean {
+	const alternativeGroups = profile.alternativeProviderGroups ?? [];
+	const alternativeProviders = new Set(alternativeGroups.flat());
+	for (const provider of profile.requiredProviders) {
+		if (!alternativeProviders.has(provider) && !authenticatedProviders.has(provider)) return false;
+	}
+	return alternativeGroups.every(group => group.some(provider => authenticatedProviders.has(provider)));
+}
+
 export function isModelProfileError(value: unknown): value is {
 	code: ModelProfileErrorCode;
 	message: string;

package/src/config/model-profiles.ts

@@ -207,6 +207,27 @@ export const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[] = [
 		critic: "xai/grok-4.3:xhigh",
 		architect: "xai/grok-4.3:xhigh",
 	}),
+	profile("grok-45-eco", ["xai"], {
+		default: "xai/grok-4.5:low",
+		executor: "xai/grok-4.5:minimal",
+		planner: "xai/grok-4.5:low",
+		critic: "xai/grok-4.5:medium",
+		architect: "xai/grok-4.5:high",
+	}),
+	profile("grok-45-medium", ["xai"], {
+		default: "xai/grok-4.5:medium",
+		executor: "xai/grok-4.5:low",
+		planner: "xai/grok-4.5:medium",
+		critic: "xai/grok-4.5:high",
+		architect: "xai/grok-4.5:high",
+	}),
+	profile("grok-45-pro", ["xai"], {
+		default: "xai/grok-4.5:high",
+		executor: "xai/grok-4.5:medium",
+		planner: "xai/grok-4.5:high",
+		critic: "xai/grok-4.5:high",
+		architect: "xai/grok-4.5:high",
+	}),
 	profile("grok-build-pro", ["grok-build"], {
 		default: "grok-build/grok-composer-2.5-fast",
 		executor: "grok-build/grok-build",
@@ -321,6 +342,9 @@ const PROFILE_PRESENTATION: Record<string, ModelProfilePresentation> = {
 	"grok-eco": { displayName: "Grok Eco", providerGroup: "GROK" },
 	"grok-medium": { displayName: "Grok Medium", providerGroup: "GROK" },
 	"grok-pro": { displayName: "Grok Pro", providerGroup: "GROK" },
+	"grok-45-eco": { displayName: "Grok 4.5 Eco", providerGroup: "GROK" },
+	"grok-45-medium": { displayName: "Grok 4.5 Medium", providerGroup: "GROK" },
+	"grok-45-pro": { displayName: "Grok 4.5 Pro", providerGroup: "GROK" },
 	"grok-build-pro": { displayName: "Grok Build Pro", providerGroup: "GROK" },
 	"cursor-eco": { displayName: "Cursor Eco", providerGroup: "CURSOR" },
 	"cursor-medium": { displayName: "Cursor Medium", providerGroup: "CURSOR" },

package/src/config/settings-schema.ts

@@ -309,7 +309,7 @@ export const SETTINGS_SCHEMA = {
 	},
 	"notifications.telegram.toolActivity.enabled": {
 		type: "boolean",
-		default: true,
+		default: false,
 		ui: {
 			tab: "notifications",
 			label: "Telegram Tool Activity",
@@ -501,6 +501,11 @@ export const SETTINGS_SCHEMA = {
 		default: 0.05,
 		validate: (value: number) => Number.isFinite(value) && value > 0 && value <= 1,
 	},
+	"gjc.ralplan.maxIterations": {
+		type: "number",
+		default: 5,
+		validate: (value: number) => Number.isInteger(value) && value >= 1 && value <= 20,
+	},
 
 	// ────────────────────────────────────────────────────────────────────────
 	// Appearance
@@ -1244,7 +1249,8 @@ export const SETTINGS_SCHEMA = {
 		ui: {
 			tab: "interaction",
 			label: "Mouse Support",
-			description: "Enable SGR mouse wheel scrolling and overlay row selection. Disabled in tmux and screen.",
+			description:
+				"Enable GJC session scrolling, drag-to-copy text selection, and overlay row selection with the mouse. Disabled by default to preserve native terminal or tmux scrollback and selection.",
 		},
 	},
 	// Conversation flow
@@ -2653,6 +2659,47 @@ export const SETTINGS_SCHEMA = {
 			description: "How often the resource GC sweeps browser tabs and stale screenshot directories.",
 		},
 	},
+	"memoryGuard.enabled": {
+		type: "boolean",
+		default: false,
+	},
+	"memoryGuard.checkIntervalMs": {
+		type: "number",
+		default: 30_000,
+		validate: (value: number) => Number.isFinite(value) && value > 0,
+	},
+	"memoryGuard.gcThresholdPercent": {
+		type: "number",
+		default: 70,
+		validate: (value: number) => Number.isFinite(value) && value >= 0 && value <= 100,
+	},
+	"memoryGuard.restartThresholdPercent": {
+		type: "number",
+		default: 85,
+		validate: (value: number) => Number.isFinite(value) && value >= 0 && value <= 100,
+	},
+	"memoryGuard.restartThresholdWindowMs": {
+		type: "number",
+		default: 90_000,
+		validate: (value: number) => Number.isFinite(value) && value > 0,
+	},
+	"memoryGuard.cooldownMs": {
+		type: "number",
+		default: 600_000,
+		validate: (value: number) => Number.isFinite(value) && value >= 0,
+	},
+	"memoryGuard.parentReserveMb": {
+		type: "number",
+		default: 1024,
+		validate: (value: number) =>
+			Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER / (1024 * 1024),
+	},
+	"memoryGuard.policyLimitMb": {
+		type: "number",
+		default: 0,
+		validate: (value: number) =>
+			Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER / (1024 * 1024),
+	},
 
 	"computer.enabled": {
 		type: "boolean",
@@ -3844,6 +3891,17 @@ export interface ShellMinimizerSettings {
 	maxCaptureBytes: number;
 }
 
+export interface MemoryGuardSettings {
+	enabled: boolean;
+	checkIntervalMs: number;
+	gcThresholdPercent: number;
+	restartThresholdPercent: number;
+	restartThresholdWindowMs: number;
+	cooldownMs: number;
+	parentReserveMb: number;
+	policyLimitMb: number;
+}
+
 export interface NotificationsSettings {
 	enabled: boolean;
 	telegram: {
@@ -3902,6 +3960,7 @@ export interface GroupTypeMap {
 	statusLine: StatusLineSettings;
 	thinkingBudgets: ThinkingBudgetsSettings;
 	stt: SttSettings;
+	memoryGuard: MemoryGuardSettings;
 	modelRoles: Record<string, ModelSelectorValue>;
 	modelTags: ModelTagsSettings;
 	cycleOrder: string[];

package/src/config/settings.ts

@@ -363,6 +363,7 @@ export class Settings implements NotificationSettingsReader {
 	/** Pending debounced ordinary save; its queue slot is reserved immediately. */
 	#saveTimer?: NodeJS.Timeout;
 	#savePromise?: Promise<void>;
+	#changeListeners = new Set<(path: SettingPath) => void>();
 	#pendingSaveSlot?: PendingSaveSlot;
 
 	/** Legacy fallback migration warnings emitted once per settings instance. */
@@ -522,6 +523,11 @@ export class Settings implements NotificationSettingsReader {
 		return structuredClone(this.#schemaReport);
 	}
 
+	onChanged(listener: (path: SettingPath) => void): () => void {
+		this.#changeListeners.add(listener);
+		return () => this.#changeListeners.delete(listener);
+	}
+
 	/**
 	 * Set a setting value (sync).
 	 * Updates global settings and reserves its background persistence slot before
@@ -555,6 +561,7 @@ export class Settings implements NotificationSettingsReader {
 
 		const hook = SETTING_HOOKS[path];
 		if (hook) hook(value, prev);
+		for (const listener of this.#changeListeners) listener(path);
 	}
 
 	/**
@@ -579,6 +586,7 @@ export class Settings implements NotificationSettingsReader {
 
 		const hook = SETTING_HOOKS[path];
 		if (hook) hook(this.get(path), prev);
+		for (const listener of this.#changeListeners) listener(path);
 	}
 
 	/**

package/src/defaults/gjc/skills/ralplan/SKILL.md

@@ -67,14 +67,15 @@ The consensus workflow:
    - **Plan-only Critic lane**: independently check quality, principle-option consistency, alternatives, risks, acceptance criteria, and verification; when the plan is thin, request concrete expansion rather than only defects. Persist with `gjc ralplan --write --stage critic --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json`, then return receipt/path plus `OKAY`/`ITERATE`/`REJECT`.
    - **Sequential fallback**: if Critic must evaluate Architect findings, verdict, antithesis, tradeoffs, synthesis, status, or any Architect-produced artifact, await the Architect result before issuing that Architect-dependent Critic pass.
 4. **Review join gate**: before consensus, revision, reconciliation, finalization, or approval, verify both Architect and Critic receipts/verdicts exist for the same Planner artifact/pass (`path`, `sha256`, `stage_n`). A non-`CLEAR` Architect verdict, non-`APPROVE` Architect decision, or any non-`OKAY` Critic verdict routes back to Planner revision; do not finalize from only one review lane.
-5. **Re-review loop** (max 5 iterations): Any non-`OKAY` Critic verdict (`ITERATE` or `REJECT`) or Architect result that is not `CLEAR`/`APPROVE` MUST run the same full closed loop:
+5. **Re-review loop** (max 5 iterations; **runtime-enforced**): Any non-`OKAY` Critic verdict (`ITERATE` or `REJECT`) or Architect result that is not `CLEAR`/`APPROVE` MUST run the same full closed loop:
    a. Collect Architect + Critic feedback
    b. Revise the plan by resuming the SAME persisted Planner subagent with consolidated Architect + Critic feedback (see **Persisted Planner** below); fall back to a fresh Planner spawn only per the fallback routing table
    c. Return to the review fan-out or sequential fallback path above
       - Persist each Planner revision with `gjc ralplan --write --stage revision --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json` before re-review, then pass the receipt/path forward instead of duplicating the full revision markdown in the parent conversation.
    d. Re-join Architect and Critic verdicts for the same revised Planner artifact/pass
    e. Repeat this loop until Critic returns `OKAY` **and** Architect is `CLEAR`/`APPROVE` for the same Planner artifact/pass, or 5 iterations are reached
-   f. If 5 iterations are reached without Critic `OKAY` plus Architect `CLEAR`/`APPROVE`, present the best version to the user
+   f. If 5 iterations are reached without Critic `OKAY` plus Architect `CLEAR`/`APPROVE`, **stop opening further planner/revision passes**. Present the best version to the user (interactive) or surface `PLANNING-STUCK` (headless). Do **not** auto-start implementation.
+   g. **Runtime budget (#3165):** native `gjc ralplan --write` refuses a new `planner`/`revision` that would open consensus iteration **> max** (default **5**, overridable via `gjc.ralplan.maxIterations` in project/user `.gjc/settings.json`, integer 1..20). Cap uses the same iteration definition as the HUD (`planner`/`revision` openers in `index.jsonl`). Overflow exits **3**, prints operator-visible **`PLANNING-STUCK`** on stdout (and stderr detail; JSON includes `planning_stuck: true`), and still allows `architect`/`critic` within an already-opened pass plus `post-interview`/`adr`/`final` so the best plan can be escalated to `pending approval` without auto-execution. A new `--run-id` starts a fresh budget.
 6. **Post-ralplan interview** (intent reconciliation gate): After the review join gate has both Critic `OKAY` and Architect `CLEAR`/`APPROVE` for the same Planner artifact/pass, and before the plan is finalized, reconcile the consensus plan against the user's actual intent. The goal is to make sure ralplan did not silently bake in assumptions that conflict with what the user wants.
    a. **Collect open items** from the run: every assumption the Planner/Architect/Critic resolved by assumption rather than by stated fact, every ambiguity flagged during review, and every decision the loop made without explicit user input. Source these from the persisted `planner`/`architect`/`critic`/`revision` stage artifacts, not from memory.
    b. **Cross-check prior context for conflicts**: glob `.gjc/_session-{sessionid}/specs/deep-interview-*.md` and other prior specs/plans/context relevant by topic. For each, list points where the consensus plan contradicts, weakens, or expands beyond a previously crystallized decision, constraint, or non-goal. Cite the conflicting artifact and line/section.
@@ -103,6 +104,24 @@ The consensus workflow:
 
 > **Important:** Architect and Critic MAY run in the same parallel batch only for the plan-only Critic lane after Planner persistence. Any Architect-dependent Critic pass MUST remain sequential: await Architect before issuing Critic, then apply the same review join gate before consensus.
 
+## Consensus iteration cap (operator contract)
+
+- Default max consensus iterations: **5** (`gjc.ralplan.maxIterations`).
+- On cap: exit code **3**, marker **`PLANNING-STUCK`** (stdout), no silent re-loop, no automatic ultragoal/team handoff. Opener budget is `max(index.jsonl openers, on-disk stage-*-{planner,revision}.md count)` so a missing/empty/malformed ledger cannot fail open after prior openers.
+- Headless/CI: treat `PLANNING-STUCK` / exit 3 as terminal planning failure for orchestration/watchdogs.
+- Interactive: present best existing plan via the final approval gate; residual critic findings stay as caveats.
+- Override example (project `.gjc/settings.json`):
+
+```json
+{
+  "gjc": {
+    "ralplan": {
+      "maxIterations": 3
+    }
+  }
+}
+```
+
 
 Follow this ralplan-internal consensus workflow for consensus mode details.
 

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -279,7 +279,7 @@ An ultragoal story cannot be checkpointed `complete` until the active agent has
    - architecture-side: system boundaries, layering, data/control flow, operational risks.
    - product-side: user-visible behavior, acceptance criteria, edge cases, regressions.
    - code-side: maintainability, tests, integration points, and unsafe shortcuts.
-5. Delegate an `executor` QA/red-team lane to build and run the e2e/read-teaming QA suite appropriate for the story. This lane must try to break the change, not just confirm the happy path. It must start from the approved plan/spec/acceptance criteria, then user-facing contracts, and only then implementation code as supporting evidence. Plan/code mismatches are blockers, not items to paper over with implementation intent.
+5. Delegate an `executor` QA/red-team lane with typed `executionMode: "ultragoal-red-team"` (preferred) — or assignment text that explicitly labels Ultragoal completion QA/red-team — to build and run the e2e/red-teaming QA suite appropriate for the story. A bare `executorQa` field-name mention is not enough to activate the mode. This lane must try to break the change, not just confirm the happy path. It must start from the approved plan/spec/acceptance criteria, then user-facing contracts, and only then implementation code as supporting evidence. Plan/code mismatches are blockers, not items to paper over with implementation intent.
 6. The executor QA/red-team lane must prove evidence by the real surface under test:
    - GUI/web surfaces require a valid automation transcript plus a non-uniform screenshot. Bare `inlineEvidence` text or typed receipts never prove live GUI/web execution.
    - CLI surfaces require runtime argv replay: `schemaVersion: 1`, `kind: "cli-replay"`, `replaySafe: true`, an allowlisted argv `command`, and replayed output validation. The complete field-by-field replay schema, command allowlist, and `replayExempt` audit contract are specified once in the "For CLI replay artifacts" paragraph below the quality-gate JSON; follow it exactly.