@gajae-code/coding-agent 0.12.19 → 0.12.20

package/src/commands/sdk.ts

@@ -2,6 +2,7 @@ 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 { logger } from "@gajae-code/utils";
 import { Args, CliParseError, Command, Flags, renderCommandHelp } from "@gajae-code/utils/cli";
 import type { Args as ParsedArgs } from "../cli/args";
 import { Settings } from "../config/settings";
@@ -16,6 +17,9 @@ import {
 	readSessionLifecycleLaunchRequest,
 	type SessionLifecycleLaunchRequest,
 	type SessionLifecycleTranscriptIdentity,
+	sessionHostAttachedClients,
+	sessionHostWorkInFlight,
+	startBrokerDeadRegistrationSweep,
 	writeSessionLifecycleFailure,
 	writeSessionLifecycleReady,
 } from "../sdk/broker/lifecycle";
@@ -107,6 +111,96 @@ export async function watchSessionHostBrokerLiveness(deps: {
 	}
 }
 
+/**
+ * How long a session host that has served at least one client tolerates having
+ * no client attached before treating itself as abandoned.
+ *
+ * This cannot fire during healthy work. "Attached" is the host's own live
+ * socket-subscription count, so a client that is merely idle — an editor
+ * sitting on an open ACP session, a long agent turn with nobody typing — still
+ * holds a socket and resets the window on every poll. Only a client that is
+ * actually gone opens it, and 30 minutes is far longer than any client
+ * reconnect budget (ACP's is seconds), so a crashed-and-restarted client
+ * reattaches long before the window closes.
+ */
+export const SESSION_HOST_DETACHED_IDLE_GRACE_MS = 30 * 60_000;
+
+/**
+ * How long a freshly spawned session host waits for its very first client
+ * before treating itself as abandoned.
+ *
+ * A host is ready before its client has finished dialing, so a host that has
+ * never seen an attachment must not be judged by the detached window above. One
+ * hour is orders of magnitude beyond the slowest observed cold start (worktree
+ * preparation, MCP server launch, model-profile application) and beyond any
+ * lifecycle readiness deadline the broker will wait on, so it can only elapse
+ * for a host nobody ever came for.
+ */
+export const SESSION_HOST_FIRST_ATTACH_GRACE_MS = 60 * 60_000;
+
+const SESSION_HOST_ATTACHMENT_POLL_MS = 30_000;
+
+/**
+ * Resolves once this host is provably abandoned: either it has been detached
+ * from every client for the full idle grace, or nobody has come for it at all
+ * for the full first-attach grace.
+ *
+ * `readAttachedClients` reports the host's own live client/socket subscription
+ * count; `undefined` means the SDK endpoint publishes no such evidence yet and
+ * is deliberately *not* treated as detachment, so a host can never be reaped on
+ * missing evidence — only on observed absence of clients.
+ *
+ * `readWorkInFlight` reports whether the host is running agent work right now.
+ * Work is positive proof that a client did come for this host: a prompt can
+ * only arrive over the endpoint a client dialed. So for a host that has never
+ * been *observed* attached — a client that connected, prompted and dropped
+ * between two 30s polls, or a client count that is momentarily unreadable — the
+ * first-attach window is measured from the last moment work was in flight
+ * rather than from process start. That still bounds a host whose SDK runtime
+ * never came up: with no transport it can never receive a prompt, so it never
+ * reports work and its window keeps running from start. And any real turn ends,
+ * after which the window resumes; live work defers the bound, never removes it.
+ */
+export async function watchSessionHostClientAttachment(deps: {
+	readAttachedClients: () => number | undefined;
+	readWorkInFlight?: () => boolean;
+	now?: () => number;
+	sleep?: (ms: number) => Promise<void>;
+	idleGraceMs?: number;
+	firstAttachGraceMs?: number;
+	pollMs?: number;
+}): Promise<void> {
+	const now = deps.now ?? Date.now;
+	const sleep = deps.sleep ?? (async ms => await Bun.sleep(ms));
+	const readWorkInFlight = deps.readWorkInFlight ?? (() => false);
+	const idleGraceMs = deps.idleGraceMs ?? SESSION_HOST_DETACHED_IDLE_GRACE_MS;
+	const firstAttachGraceMs = deps.firstAttachGraceMs ?? SESSION_HOST_FIRST_ATTACH_GRACE_MS;
+	const pollMs = deps.pollMs ?? SESSION_HOST_ATTACHMENT_POLL_MS;
+	let everAttached = false;
+	let detachedSince: number | null = null;
+	/** Start of the current window in which nobody has been shown to want this host. */
+	let unattendedSince = now();
+	for (;;) {
+		const attached = deps.readAttachedClients();
+		if (readWorkInFlight()) unattendedSince = now();
+		if (attached === undefined) {
+			// No endpoint evidence at all is ambiguity, not abandonment; it still
+			// accrues against the first-attach bound so a host whose SDK runtime
+			// never came up cannot outlive that bound either.
+			if (!everAttached && now() - unattendedSince >= firstAttachGraceMs) return;
+		} else if (attached > 0) {
+			everAttached = true;
+			detachedSince = null;
+		} else if (everAttached) {
+			detachedSince ??= now();
+			if (now() - detachedSince >= idleGraceMs) return;
+		} else if (now() - unattendedSince >= firstAttachGraceMs) {
+			return;
+		}
+		await sleep(pollMs);
+	}
+}
+
 type LifecycleTranscriptSource = {
 	cwd: string;
 	path: string;
@@ -222,6 +316,7 @@ export async function openLifecycleSessionManager(
 			SessionManager.managedDestination(cwd, agentDir),
 			undefined,
 			migrationPolicy,
+			lifecycleSettings.get("sessionMemory.mode"),
 		);
 		if (opened.kind === "error")
 			throw new Error("Lifecycle saved session authority changed while the session host opened it.");
@@ -238,6 +333,7 @@ export async function openLifecycleSessionManager(
 			cwd,
 			SessionManager.managedDestination(cwd, agentDir),
 			migrationPolicy,
+			lifecycleSettings.get("sessionMemory.mode"),
 		);
 		if (forked.kind === "error")
 			throw new Error("Lifecycle saved session authority changed while the session host forked it.");
@@ -246,6 +342,22 @@ export async function openLifecycleSessionManager(
 	return { parsed, sessionManager };
 }
 
+/**
+ * Starts the memory backend a lifecycle session deferred past its readiness
+ * window.
+ *
+ * Deliberately not awaited: the local backend summarises every queued rollout
+ * through the model, so its duration scales with the backlog and would eat the
+ * broker's readiness budget. The session is already published as ready here, so
+ * a failure is a degraded-memory condition, not a startup failure — it is
+ * logged and swallowed instead of surfacing as an unhandled rejection.
+ */
+export function startMemoryBackendAfterReadiness(start: () => Promise<void>): void {
+	void start().catch(error => {
+		logger.warn("Deferred memory backend startup failed after readiness", { error: String(error) });
+	});
+}
+
 /** Runs the same persisted AgentSession bootstrap used by the production CLI. */
 export async function runSessionHost(
 	timing: {
@@ -438,7 +550,7 @@ export async function runSessionHost(
 
 		throw created.failure;
 	}
-	const { session, capability, rollback } = created;
+	const { session, capability, rollback, startDeferredMemoryBackend } = created;
 	let sessionDisposal: Promise<void> | undefined;
 	const disposeSession = (): Promise<void> => {
 		sessionDisposal ??= session.dispose().catch(() => {});
@@ -553,12 +665,24 @@ export async function runSessionHost(
 		await failAfterRollback(durableFailure);
 		throw error;
 	}
+	// Readiness is published; the session is live. Memory startup issues one LLM
+	// request per queued rollout, so it must run outside the readiness window and
+	// its failure must never take the session down.
+	startMemoryBackendAfterReadiness(startDeferredMemoryBackend);
 	process.once("SIGTERM", stop);
 	process.once("SIGINT", stop);
-	// A detached host whose broker is gone for good would otherwise live (and
-	// hold its session's memory) forever; reap it through the same graceful
-	// teardown a SIGTERM would take once the bounded absence grace elapses.
-	await watchSessionHostBrokerLiveness({ agentDir });
+	// Two independent bounds, either of which reaps this detached host through
+	// the same graceful teardown a SIGTERM would take. The first covers a broker
+	// that is gone for good; the second covers the opposite case, a perfectly
+	// healthy broker whose host nobody is attached to any more and for which no
+	// `session.close` will ever arrive.
+	await Promise.race([
+		watchSessionHostBrokerLiveness({ agentDir }),
+		watchSessionHostClientAttachment({
+			readAttachedClients: sessionHostAttachedClients,
+			readWorkInFlight: sessionHostWorkInFlight,
+		}),
+	]);
 	stop();
 	await new Promise<void>(() => {});
 }
@@ -617,9 +741,19 @@ export default class Sdk extends Command {
 		});
 		await broker.start();
 		if (!broker.ownsDiscovery) return;
-		const stop = () => void broker.stop();
+		// A live broker must not keep advertising sessions whose host process is
+		// gone; the sweep is the broker-side half of the host reaping bound.
+		const stopSweep = startBrokerDeadRegistrationSweep(broker);
+		const stop = () => {
+			stopSweep();
+			void broker.stop();
+		};
 		process.once("SIGTERM", stop);
 		process.once("SIGINT", stop);
-		await completeBrokerProcess(broker);
+		try {
+			await completeBrokerProcess(broker);
+		} finally {
+			stopSweep();
+		}
 	}
 }

package/src/config/settings-schema.ts

@@ -2079,6 +2079,20 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	// Bounded-memory cold-session offloading (rollout knobs; budgets are fixed
+	// implementation constants in the sidecar primitives, not user-tunable
+	// fields). "shadow" (default) measures and offloads without changing
+	// observable behavior; canary/default-on are release-channel states, not
+	// user-facing enum values.
+	"sessionMemory.mode": {
+		type: "enum",
+		values: ["off", "shadow", "enabled"] as const,
+		default: "shadow",
+	},
+	// Independent runtime switch for AgentSession's async compact-once overflow
+	// recovery. The synchronous bounded context preflight stays always on.
+	"sessionMemory.contextOverflowRecovery": { type: "boolean", default: true },
+
 	// ────────────────────────────────────────────────────────────────────────
 	// Editing
 	// ────────────────────────────────────────────────────────────────────────
@@ -2810,6 +2824,29 @@ export const SETTINGS_SCHEMA = {
 			description: "Parent-process RSS (MB) above which idle tabs are opportunistically evicted LRU.",
 		},
 	},
+	// `gjc gc --disk` retention policy. Report-only unless `--prune` is also passed;
+	// these knobs never run implicitly and never affect the PID-liveness axis.
+	"gc.sessions.maxAgeDays": {
+		type: "number",
+		default: 60,
+		validate: (value: number) => Number.isFinite(value) && value >= 0,
+	},
+	// 0 disables the size axis; only the age axis retires transcripts then.
+	"gc.sessions.maxTotalBytes": {
+		type: "number",
+		default: 0,
+		validate: (value: number) => Number.isFinite(value) && value >= 0,
+	},
+	"gc.natives.keepVersions": {
+		type: "number",
+		default: 2,
+		validate: (value: number) => Number.isInteger(value) && value >= 0,
+	},
+	"gc.backups.maxAgeDays": {
+		type: "number",
+		default: 30,
+		validate: (value: number) => Number.isFinite(value) && value >= 0,
+	},
 	"resourceGc.sweepIntervalMs": {
 		type: "number",
 		default: 30_000,
@@ -4136,6 +4173,11 @@ export interface ShellMinimizerSettings {
 	maxCaptureBytes: number;
 }
 
+export interface SessionMemorySettings {
+	mode: "off" | "shadow" | "enabled";
+	contextOverflowRecovery: boolean;
+}
+
 export interface MemoryGuardSettings {
 	enabled: boolean;
 	checkIntervalMs: number;
@@ -4211,6 +4253,7 @@ export interface GroupTypeMap {
 	thinkingBudgets: ThinkingBudgetsSettings;
 	stt: SttSettings;
 	memoryGuard: MemoryGuardSettings;
+	sessionMemory: SessionMemorySettings;
 	modelRoles: Record<string, ModelSelectorValue>;
 	modelTags: ModelTagsSettings;
 	cycleOrder: string[];

package/src/coordinator-mcp/server.ts

@@ -16,6 +16,7 @@ import { listMcpDelegateHostContexts } from "../hooks/mcp-delegate-host-context"
 import type { WorkflowGate, WorkflowGateQueryRecord } from "../modes/shared/agent-wire/workflow-gate-types";
 import type { BrokerDiscovery } from "../sdk/broker/discovery";
 import { type EnsureBrokerSettings, ensureBroker } from "../sdk/broker/ensure";
+import { lifecycleRequestTimeoutMs } from "../sdk/broker/startup-budget";
 import { UnsupportedStateVersionError } from "../sdk/broker/state-version";
 import { SdkClient, SdkClientError } from "../sdk/client/client";
 import { readSdkBrokerDiscovery } from "../sdk/client/discovery";
@@ -3183,7 +3184,11 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 		let requestError: SdkClientError | undefined;
 		let result: unknown;
 		try {
-			result = await client.global(operation, input, { ...(idempotencyKey ? { idempotencyKey } : {}) });
+			const timeoutMs = lifecycleRequestTimeoutMs(operation, input);
+			result = await client.global(operation, input, {
+				...(idempotencyKey ? { idempotencyKey } : {}),
+				...(timeoutMs === undefined ? {} : { timeoutMs }),
+			});
 		} catch (error) {
 			requestError = toCoordinatorBrokerError("request", error);
 		}

package/src/export/html/index.ts

@@ -1,8 +1,9 @@
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { AgentState } from "@gajae-code/agent-core";
 import { APP_NAME, isEnoent } from "@gajae-code/utils";
 import { getResolvedThemeColors, getThemeExportColors } from "../../modes/theme/theme";
-import { type SessionEntry, type SessionHeader, SessionManager } from "../../session/session-manager";
+import { SessionManager } from "../../session/session-manager";
 // Pre-generated template (created by scripts/generate-template.ts at publish time)
 import { TEMPLATE } from "./template.generated";
 
@@ -90,26 +91,72 @@ async function generateThemeVars(themeName?: string): Promise<string> {
 	return lines.join(" ");
 }
 
-interface SessionData {
-	header: SessionHeader | null;
-	entries: SessionEntry[];
-	leafId: string | null;
-	systemPrompt?: string;
-	tools?: { name: string; description: string }[];
+class Base64StreamEncoder {
+	#carry = Buffer.alloc(0);
+
+	write(value: string): string {
+		const incoming = Buffer.from(value, "utf8");
+		const bytes = this.#carry.byteLength === 0 ? incoming : Buffer.concat([this.#carry, incoming]);
+		const completeLength = bytes.byteLength - (bytes.byteLength % 3);
+		this.#carry = bytes.subarray(completeLength);
+		return completeLength === 0 ? "" : bytes.subarray(0, completeLength).toString("base64");
+	}
+
+	finish(): string {
+		const final = this.#carry.toString("base64");
+		this.#carry = Buffer.alloc(0);
+		return final;
+	}
 }
 
-/** Generate HTML from bundled template with runtime substitutions. */
-async function generateHtml(sessionData: SessionData, themeName?: string): Promise<string> {
+async function writeSessionHtml(
+	sm: SessionManager,
+	state: AgentState | undefined,
+	outputPath: string,
+	themeName?: string,
+): Promise<void> {
 	const themeVars = await generateThemeVars(themeName);
-	const sessionDataBase64 = Buffer.from(JSON.stringify(sessionData)).toBase64();
-
-	// Use function replacements so `$'`, `$&`, `$$`, `$n`, etc. in the
-	// substituted CSS/base64 are not interpreted as substitution patterns
-	// (see https://mdn.io/String.replace).
-	return TEMPLATE.replace("<theme-vars/>", () => `<style>:root { ${themeVars} }</style>`).replace(
-		"{{SESSION_DATA}}",
-		() => sessionDataBase64,
-	);
+	const themedTemplate = TEMPLATE.replace("<theme-vars/>", () => `<style>:root { ${themeVars} }</style>`);
+	const marker = "{{SESSION_DATA}}";
+	const markerOffset = themedTemplate.indexOf(marker);
+	if (markerOffset < 0) throw new Error("HTML export template is missing the session-data marker");
+	const sourcePath = sm.getSessionFile();
+	if (sourcePath) {
+		const sourceIdentity = await fs.realpath(sourcePath).catch(() => path.resolve(sourcePath));
+		const outputIdentity = await fs.realpath(outputPath).catch(() => path.resolve(outputPath));
+		if (sourceIdentity === outputIdentity)
+			throw new Error("HTML export output must not overwrite the source transcript");
+	}
+	const sink = Bun.file(outputPath).writer();
+	const encoder = new Base64StreamEncoder();
+	const writeEncoded = (value: string): void => {
+		const encoded = encoder.write(value);
+		if (encoded) sink.write(encoded);
+	};
+	try {
+		sink.write(themedTemplate.slice(0, markerOffset));
+		writeEncoded(`{"header":${JSON.stringify(sm.getHeader())},"entries":[`);
+		let first = true;
+		sm.visitEntriesForExport(entry => {
+			writeEncoded(`${first ? "" : ","}${JSON.stringify(entry)}`);
+			first = false;
+		});
+		writeEncoded(`],"leafId":${JSON.stringify(sm.getLeafId())}`);
+		if (state?.systemPrompt !== undefined)
+			writeEncoded(`,"systemPrompt":${JSON.stringify(state.systemPrompt.join("\n\n"))}`);
+		if (state?.tools !== undefined)
+			writeEncoded(
+				`,"tools":${JSON.stringify(state.tools.map(tool => ({ name: tool.name, description: tool.description })))}`,
+			);
+		writeEncoded("}");
+		const final = encoder.finish();
+		if (final) sink.write(final);
+		sink.write(themedTemplate.slice(markerOffset + marker.length));
+		await sink.end();
+	} catch (error) {
+		await sink.end();
+		throw error;
+	}
 }
 
 /** Export session to HTML using SessionManager and AgentState. */
@@ -123,18 +170,8 @@ export async function exportSessionToHtml(
 	const sessionFile = sm.getSessionFile();
 	if (!sessionFile) throw new Error("Cannot export in-memory session to HTML");
 
-	const sessionData: SessionData = {
-		header: sm.getHeader(),
-		entries: sm.getEntriesForExport(),
-		leafId: sm.getLeafId(),
-		systemPrompt: state?.systemPrompt.join("\n\n"),
-		tools: state?.tools?.map(t => ({ name: t.name, description: t.description })),
-	};
-
-	const html = await generateHtml(sessionData, opts.themeName);
 	const outputPath = opts.outputPath || `${APP_NAME}-session-${path.basename(sessionFile, ".jsonl")}.html`;
-
-	await Bun.write(outputPath, html);
+	await writeSessionHtml(sm, state, outputPath, opts.themeName);
 	return outputPath;
 }
 
@@ -143,24 +180,31 @@ export async function exportFromFile(inputPath: string, options?: ExportOptions
 	const opts: ExportOptions = typeof options === "string" ? { outputPath: options } : options || {};
 
 	let sm: SessionManager;
+	const artifactRoot = inputPath.endsWith(".jsonl") ? inputPath.slice(0, -6) : inputPath;
+	const hasExistingSidecars = (
+		await Promise.all(
+			["idx", "tail", "commit"].map(kind =>
+				Bun.file(path.join(artifactRoot, `.session-memory.spill.${kind}`)).exists(),
+			),
+		)
+	).some(Boolean);
+	if (!(await Bun.file(inputPath).exists())) throw new Error(`File not found: ${inputPath}`);
 	try {
-		sm = await SessionManager.open(inputPath);
+		sm = await SessionManager.open(
+			inputPath,
+			undefined,
+			undefined,
+			"copy-retain",
+			hasExistingSidecars ? "off" : "enabled",
+		);
 	} catch (err) {
 		if (isEnoent(err)) throw new Error(`File not found: ${inputPath}`);
 		throw err;
 	}
 
 	try {
-		const sessionData: SessionData = {
-			header: sm.getHeader(),
-			entries: sm.getEntriesForExport(),
-			leafId: sm.getLeafId(),
-		};
-
-		const html = await generateHtml(sessionData, opts.themeName);
 		const outputPath = opts.outputPath || `${APP_NAME}-session-${path.basename(inputPath, ".jsonl")}.html`;
-
-		await Bun.write(outputPath, html);
+		await writeSessionHtml(sm, undefined, outputPath, opts.themeName);
 		return outputPath;
 	} finally {
 		await sm.close();