@gajae-code/coding-agent 0.18.5 → 0.18.6

package/src/cli-ordinary.ts

@@ -0,0 +1,197 @@
+/** Ordinary CLI graph: everything the inert entry must not load eagerly.
+ *
+ * This module owns the effectful bootstrap (startup timing, stderr drainer,
+ * bash-shell worker protocol) plus the unchanged ordinary routing order:
+ * bash-shell workers -> darwin malloc re-exec -> internal smoke -> tmux owner
+ * isolation -> managed-owner supervisor/admission/recovery -> private sdk
+ * stderr drainer -> public family dispatch -> community app -> doctor worker /
+ * probe / cli -> full registry. `cli.ts` imports it lazily, only after argv has
+ * been proven not to be a `sdk diagnostics` observation. */
+
+import { APP_NAME, VERSION } from "@gajae-code/utils/cli-metadata";
+import { startTiming } from "@gajae-code/utils/logger";
+import { commands } from "./cli-commands";
+import {
+	BASH_SHELL_RUNTIME_ARG,
+	BASH_SHELL_SUPERVISOR_ARG,
+	BASH_SHELL_WORKER_ARG,
+} from "./exec/bash-shell-worker-protocol";
+import { runSdkStderrDrainerFromArgv } from "./sdk/broker/stderr-drainer";
+
+export { commands };
+
+const MANAGED_OWNER_SUPERVISOR_ARG = "--internal-managed-owner-supervisor";
+const MANAGED_OWNER_CHILD_TOKEN_ENV = "GJC_MANAGED_OWNER_CHILD_TOKEN";
+const TMUX_OWNER_ISOLATION_ARG = "--internal-tmux-owner-isolation";
+
+// Anchor startup timing before the heavy CLI module graph is loaded so the
+// printed tree includes runtime/bootstrap costs as well as dispatch work.
+if (process.env.GJC_TIMING || process.env.PI_TIMING) {
+	startTiming();
+}
+
+async function installRuntimeGlobals(writeNoFileWarning?: (text: string) => void): Promise<void> {
+	// fetch() deliberately stays on HTTP/1.1. Bun's HTTP/2 client (per-request
+	// `protocol: "http2"`) wedges a pooled connection while uploading large
+	// request bodies (~300KB): every later request on it waits forever for
+	// response headers. Do not re-enable HTTP/2 without re-running that probe.
+
+	const { warnIfMacOSNoFileLimitTooLow } = await import("./cli/nofile-limit");
+	warnIfMacOSNoFileLimitTooLow({ writeStderr: writeNoFileWarning });
+
+	// Secondary in-process scrub of the macOS malloc-stack-logging vars. The real
+	// boundary is the darwin re-exec guard at the top of runOrdinaryCli(): Bun snapshots
+	// the spawn-default environment at startup, so deleting these here does NOT clean the
+	// env children inherit by default — it only tidies `process.env` for code that
+	// reads it directly. Kept as belt-and-braces for the rare re-exec-unavailable
+	// fallback; managed spawns already use filterProcessEnv and the native PTY lane
+	// strips them independently.
+	delete process.env.MallocStackLogging;
+	delete process.env.MallocStackLoggingNoCompact;
+}
+
+async function dispatchPublicFamily(argv: string[]): Promise<void> {
+	const family = argv[0];
+	if (family !== "sdk" && family !== "daemon") return;
+	const { dispatchPublicCommand } = await import("./cli/public-command-entry");
+	const load = commands.find(entry => entry.name === family)!.load;
+	await dispatchPublicCommand(argv.slice(1), {
+		bin: APP_NAME,
+		version: VERSION,
+		command: family,
+		load,
+		setup: report => installRuntimeGlobals(text => report({ code: "macos_nofile_limit_low", successStderr: text })),
+	});
+}
+
+function isDoctorArgv(argv: readonly string[]): boolean {
+	return argv[0] === "doctor";
+}
+
+async function runDoctor(argv: string[]): Promise<void> {
+	const { runDoctorCli } = await import("./cli/doctor-cli");
+	await runDoctorCli(argv.slice(1));
+}
+
+/** Run every non-diagnostics command with the original admission order. */
+export async function runOrdinaryCli(argv: string[]): Promise<void> {
+	if (argv.length === 1 && argv[0] === BASH_SHELL_WORKER_ARG) {
+		const { runBashShellGuardian } = await import("./exec/bash-shell-guardian");
+		await runBashShellGuardian();
+		return;
+	}
+	if (argv.length === 1 && argv[0] === BASH_SHELL_SUPERVISOR_ARG) {
+		const { runBashShellSupervisor } = await import("./exec/bash-shell-supervisor");
+		await runBashShellSupervisor();
+		return;
+	}
+	if (argv.length === 1 && argv[0] === BASH_SHELL_RUNTIME_ARG) {
+		const { runBashShellWorker } = await import("./exec/bash-shell-worker");
+		await runBashShellWorker();
+		return;
+	}
+	if (
+		process.platform === "darwin" &&
+		process.env.GJC_MALLOC_ENV_REEXEC === undefined &&
+		(process.env.MallocStackLogging !== undefined || process.env.MallocStackLoggingNoCompact !== undefined)
+	) {
+		const { reexecWithScrubbedMallocEnv } = await import("./cli/malloc-env-guard");
+		const code = await reexecWithScrubbedMallocEnv();
+		if (code !== null) {
+			process.exitCode = code;
+			return;
+		}
+	}
+	if (argv.length === 3 && argv[0] === "internal" && argv[1] === "memory-guard-native-smoke" && argv[2] === "--json") {
+		const { runMemoryGuardNativeSmoke } = await import("./cli/native-smoke");
+		await runMemoryGuardNativeSmoke();
+		return;
+	}
+	if (argv.length === 1 && argv[0] === TMUX_OWNER_ISOLATION_ARG) {
+		const { runTmuxOwnerIsolationCliFromStdin } = await import("./gjc-runtime/tmux-owner-isolation-cli");
+		await runTmuxOwnerIsolationCliFromStdin();
+		return;
+	}
+	if (argv.length === 1 && argv[0] === MANAGED_OWNER_SUPERVISOR_ARG) {
+		const { runManagedOwnerSupervisor } = await import("./gjc-runtime/managed-owner-supervisor");
+		await runManagedOwnerSupervisor();
+		return;
+	}
+	if (process.env[MANAGED_OWNER_CHILD_TOKEN_ENV] !== undefined) {
+		const { admitManagedOwnerBeforeCli, completeManagedOwnerRecovery } = await import(
+			"./gjc-runtime/managed-owner-admission"
+		);
+		const admission = await admitManagedOwnerBeforeCli();
+		if (admission.kind === "blocked") return;
+		if (admission.kind === "recovery") {
+			await completeManagedOwnerRecovery(admission.context);
+			return;
+		}
+	}
+	if (argv[0] === "sdk" && argv[1] === "stderr-drain-internal") {
+		// Private lifecycle stderr drainer: must stay ahead of the public sdk family
+		// dispatcher, which would otherwise reject the private argv as a usage error.
+		try {
+			await runSdkStderrDrainerFromArgv(argv.slice(2));
+		} catch {
+			process.stderr.write("gjc sdk: invalid internal stderr drainer invocation\n");
+			process.exitCode = 2;
+		}
+		return;
+	}
+	if (argv[0] === "sdk" || argv[0] === "daemon") {
+		await dispatchPublicFamily(argv);
+		return;
+	}
+	if (argv.length === 1 && argv[0] === "--supports-macos-community-app") {
+		process.stdout.write("macos-community-app-offer\n");
+		return;
+	}
+	if (argv.length === 1 && argv[0] === "--internal-macos-community-app-offer") {
+		try {
+			const { offerMacosCommunityApp } = await import("./cli/macos-community-app");
+			await offerMacosCommunityApp({ log: message => process.stderr.write(`${message}\n`) });
+		} catch {
+			const { COMMUNITY_APP_REPOSITORY } = await import("./cli/macos-community-app");
+			process.stderr.write(
+				`Optional community app offer failed; GJC remains installed. https://github.com/${COMMUNITY_APP_REPOSITORY}\n`,
+			);
+		}
+		return;
+	}
+	if (argv[0] === "--internal-doctor-worker") {
+		// Non-forgeable route: reachable only with the exact per-spawn token env var
+		// AND a non-TTY stdin (isRoutableDoctorWorkerInvocation), so a user's own
+		// interactive terminal can never land on the worker's confirmation-refusal
+		// path merely by passing this argv marker.
+		const { isRoutableDoctorWorkerInvocation, runDoctorWorker } = await import("./cli/doctor-worker");
+		if (argv.length !== 1 || !isRoutableDoctorWorkerInvocation(process.env, process.stdin.isTTY)) {
+			process.stderr.write("gjc doctor: invalid internal worker invocation\n");
+			process.exitCode = 2;
+			return;
+		}
+		await runDoctorWorker();
+		return;
+	}
+	if (argv[0] === "--internal-doctor-probe") {
+		if (argv.length !== 2 || (argv[1] !== "native" && argv[1] !== "projection")) {
+			process.stderr.write("gjc doctor: invalid internal probe invocation\n");
+			process.exitCode = 2;
+			return;
+		}
+		try {
+			const { runDoctorProbe } = await import("./cli/doctor/probe");
+			await runDoctorProbe(argv[1]);
+		} catch {
+			process.stderr.write("gjc doctor: internal probe unavailable\n");
+			process.exitCode = 3;
+		}
+		return;
+	}
+	if (isDoctorArgv(argv)) {
+		await runDoctor(argv);
+		return;
+	}
+	const { runCliAfterAdmission } = await import("./cli-main");
+	await runCliAfterAdmission(argv);
+}

package/src/cli.ts

@@ -1,26 +1,20 @@
 #!/usr/bin/env bun
 
-import type { CommandEntry } from "@gajae-code/utils/cli";
-/** Lightweight CLI bootstrap. Heavy command registration is loaded only after
- * security admission; `gjc doctor` stays reachable when normal startup breaks. */
-import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@gajae-code/utils/dirs";
-import { startTiming } from "@gajae-code/utils/logger";
-import {
-	BASH_SHELL_RUNTIME_ARG,
-	BASH_SHELL_SUPERVISOR_ARG,
-	BASH_SHELL_WORKER_ARG,
-} from "./exec/bash-shell-worker-protocol";
-import { runSdkStderrDrainerFromArgv } from "./sdk/broker/stderr-drainer";
-
-const MANAGED_OWNER_SUPERVISOR_ARG = "--internal-managed-owner-supervisor";
-const MANAGED_OWNER_CHILD_TOKEN_ENV = "GJC_MANAGED_OWNER_CHILD_TOKEN";
-const TMUX_OWNER_ISOLATION_ARG = "--internal-tmux-owner-isolation";
-
-// Anchor startup timing before the heavy CLI module graph is loaded so the
-// printed tree includes runtime/bootstrap costs as well as dispatch work.
-if (process.env.GJC_TIMING || process.env.PI_TIMING) {
-	startTiming();
-}
+/** Inert CLI entry.
+ *
+ * `bin/gjc.js` imports THIS module, so anything statically imported here runs
+ * before argv is inspected. Keep it to pure metadata: the read-only
+ * `sdk diagnostics` observation route must not be able to resolve directories,
+ * consult NSS for a missing/ambiguous HOME, load the native addon, install
+ * runtime globals, re-exec for malloc env vars, run managed-owner admission or
+ * recovery, or touch the error-evidence store. Everything effectful lives in
+ * `./cli-ordinary`, which is imported lazily for every other command with its
+ * original ordering and admission semantics. */
+
+import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION } from "@gajae-code/utils/cli-metadata";
+import { commands } from "./cli-commands";
+
+export { commands };
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 	process.stderr.write(
@@ -30,175 +24,24 @@ if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 }
 process.title = APP_NAME;
 
-/** Public-family hooks kept available for private-worker tests without loading the full registry. */
-export const commands: CommandEntry[] = [
-	{ name: "sdk", load: () => import("./commands/sdk").then(module => module.default) },
-	{ name: "daemon", load: () => import("./commands/daemon").then(module => module.default) },
-];
-
-async function installRuntimeGlobals(writeNoFileWarning?: (text: string) => void): Promise<void> {
-	// fetch() deliberately stays on HTTP/1.1. Bun's HTTP/2 client (per-request
-	// `protocol: "http2"`) wedges a pooled connection while uploading large
-	// request bodies (~300KB): every later request on it waits forever for
-	// response headers. Do not re-enable HTTP/2 without re-running that probe.
-	const { warnIfMacOSNoFileLimitTooLow } = await import("./cli/nofile-limit");
-	warnIfMacOSNoFileLimitTooLow({ writeStderr: writeNoFileWarning });
-
-	// Secondary in-process scrub of the macOS malloc-stack-logging vars. The real
-	// boundary is the darwin re-exec guard at the top of runCli(): Bun snapshots the
-	// spawn-default environment at startup, so deleting these here does NOT clean the
-	// env children inherit by default — it only tidies `process.env` for code that
-	// reads it directly. Kept as belt-and-braces for the rare re-exec-unavailable
-	// fallback; managed spawns already use filterProcessEnv and the native PTY lane
-	// strips them independently.
-	delete process.env.MallocStackLogging;
-	delete process.env.MallocStackLoggingNoCompact;
-}
-
-async function dispatchPublicFamily(argv: string[]): Promise<void> {
-	const family = argv[0];
-	if (family !== "sdk" && family !== "daemon") return;
-	const { dispatchPublicCommand } = await import("./cli/public-command-entry");
-	const load = commands.find(entry => entry.name === family)!.load;
-	await dispatchPublicCommand(argv.slice(1), {
-		bin: APP_NAME,
-		version: VERSION,
-		command: family,
-		load,
-		setup: report => installRuntimeGlobals(text => report({ code: "macos_nofile_limit_low", successStderr: text })),
-	});
-}
-
-function isDoctorArgv(argv: readonly string[]): boolean {
-	return argv[0] === "doctor";
-}
-
-async function runDoctor(argv: string[]): Promise<void> {
-	const { runDoctorCli } = await import("./cli/doctor-cli");
-	await runDoctorCli(argv.slice(1));
-}
-
 /** Run the CLI with argv excluding process.argv prefix. */
 export async function runCli(argv: string[]): Promise<void> {
-	if (argv.length === 1 && argv[0] === BASH_SHELL_WORKER_ARG) {
-		const { runBashShellGuardian } = await import("./exec/bash-shell-guardian");
-		await runBashShellGuardian();
-		return;
-	}
-	if (argv.length === 1 && argv[0] === BASH_SHELL_SUPERVISOR_ARG) {
-		const { runBashShellSupervisor } = await import("./exec/bash-shell-supervisor");
-		await runBashShellSupervisor();
-		return;
-	}
-	if (argv.length === 1 && argv[0] === BASH_SHELL_RUNTIME_ARG) {
-		const { runBashShellWorker } = await import("./exec/bash-shell-worker");
-		await runBashShellWorker();
-		return;
-	}
-	if (
-		process.platform === "darwin" &&
-		process.env.GJC_MALLOC_ENV_REEXEC === undefined &&
-		(process.env.MallocStackLogging !== undefined || process.env.MallocStackLoggingNoCompact !== undefined)
-	) {
-		const { reexecWithScrubbedMallocEnv } = await import("./cli/malloc-env-guard");
-		const code = await reexecWithScrubbedMallocEnv();
-		if (code !== null) {
-			process.exitCode = code;
-			return;
-		}
-	}
-	if (argv.length === 3 && argv[0] === "internal" && argv[1] === "memory-guard-native-smoke" && argv[2] === "--json") {
-		const { runMemoryGuardNativeSmoke } = await import("./cli/native-smoke");
-		await runMemoryGuardNativeSmoke();
-		return;
-	}
-	if (argv.length === 1 && argv[0] === TMUX_OWNER_ISOLATION_ARG) {
-		const { runTmuxOwnerIsolationCliFromStdin } = await import("./gjc-runtime/tmux-owner-isolation-cli");
-		await runTmuxOwnerIsolationCliFromStdin();
-		return;
-	}
-	if (argv.length === 1 && argv[0] === MANAGED_OWNER_SUPERVISOR_ARG) {
-		const { runManagedOwnerSupervisor } = await import("./gjc-runtime/managed-owner-supervisor");
-		await runManagedOwnerSupervisor();
-		return;
-	}
-	if (process.env[MANAGED_OWNER_CHILD_TOKEN_ENV] !== undefined) {
-		const { admitManagedOwnerBeforeCli, completeManagedOwnerRecovery } = await import(
-			"./gjc-runtime/managed-owner-admission"
-		);
-		const admission = await admitManagedOwnerBeforeCli();
-		if (admission.kind === "blocked") return;
-		if (admission.kind === "recovery") {
-			await completeManagedOwnerRecovery(admission.context);
-			return;
-		}
-	}
-	if (argv[0] === "sdk" && argv[1] === "stderr-drain-internal") {
-		// Private lifecycle stderr drainer: must stay ahead of the public sdk family
-		// dispatcher, which would otherwise reject the private argv as a usage error.
+	// Exact-token diagnostics selector, ahead of every effectful branch. A private
+	// worker marker AFTER this prefix is a diagnostics usage error, never a worker
+	// dispatch; a private marker BEFORE it is not a diagnostics invocation at all
+	// and keeps its ordinary admission below.
+	if (argv[0] === "sdk" && argv[1] === "diagnostics") {
 		try {
-			await runSdkStderrDrainerFromArgv(argv.slice(2));
+			const { runDiagnosticsCli } = await import("./sdk/cli/diagnostics-cli");
+			await runDiagnosticsCli(argv.slice(2));
 		} catch {
-			process.stderr.write("gjc sdk: invalid internal stderr drainer invocation\n");
+			process.stderr.write("gjc sdk diagnostics: observation unavailable\n");
 			process.exitCode = 2;
 		}
 		return;
 	}
-	if (argv[0] === "sdk" || argv[0] === "daemon") {
-		await dispatchPublicFamily(argv);
-		return;
-	}
-	if (argv.length === 1 && argv[0] === "--supports-macos-community-app") {
-		process.stdout.write("macos-community-app-offer\n");
-		return;
-	}
-	if (argv.length === 1 && argv[0] === "--internal-macos-community-app-offer") {
-		try {
-			const { offerMacosCommunityApp } = await import("./cli/macos-community-app");
-			await offerMacosCommunityApp({ log: message => process.stderr.write(`${message}\n`) });
-		} catch {
-			const { COMMUNITY_APP_REPOSITORY } = await import("./cli/macos-community-app");
-			process.stderr.write(
-				`Optional community app offer failed; GJC remains installed. https://github.com/${COMMUNITY_APP_REPOSITORY}\n`,
-			);
-		}
-		return;
-	}
-	if (argv[0] === "--internal-doctor-worker") {
-		// Non-forgeable route: reachable only with the exact per-spawn token env var
-		// AND a non-TTY stdin (isRoutableDoctorWorkerInvocation), so a user's own
-		// interactive terminal can never land on the worker's confirmation-refusal
-		// path merely by passing this argv marker.
-		const { isRoutableDoctorWorkerInvocation, runDoctorWorker } = await import("./cli/doctor-worker");
-		if (argv.length !== 1 || !isRoutableDoctorWorkerInvocation(process.env, process.stdin.isTTY)) {
-			process.stderr.write("gjc doctor: invalid internal worker invocation\n");
-			process.exitCode = 2;
-			return;
-		}
-		await runDoctorWorker();
-		return;
-	}
-	if (argv[0] === "--internal-doctor-probe") {
-		if (argv.length !== 2 || (argv[1] !== "native" && argv[1] !== "projection")) {
-			process.stderr.write("gjc doctor: invalid internal probe invocation\n");
-			process.exitCode = 2;
-			return;
-		}
-		try {
-			const { runDoctorProbe } = await import("./cli/doctor/probe");
-			await runDoctorProbe(argv[1]);
-		} catch {
-			process.stderr.write("gjc doctor: internal probe unavailable\n");
-			process.exitCode = 3;
-		}
-		return;
-	}
-	if (isDoctorArgv(argv)) {
-		await runDoctor(argv);
-		return;
-	}
-	const { runCliAfterAdmission } = await import("./cli-main");
-	await runCliAfterAdmission(argv);
+	const { runOrdinaryCli } = await import("./cli-ordinary");
+	await runOrdinaryCli(argv);
 }
 
 if (import.meta.main) await runCli(process.argv.slice(2));

package/src/commands/contribution-prep.ts

@@ -9,12 +9,11 @@ export default class ContributionPrep extends Command {
 	static strict = false;
 
 	static flags = {
-		"no-spawn": Flags.boolean({ description: "Only write artifacts; do not spawn a fresh GJC worker" }),
 		"source-session-id": Flags.string({ description: "Source session id to record in the manifest" }),
 		"artifact-root": Flags.string({ description: "Directory where contribute-pr artifacts are written" }),
 	};
 
-	static examples = ["gjc contribute-pr", "gjc contribute-pr --no-spawn"];
+	static examples = ["gjc contribute-pr"];
 
 	async run(): Promise<void> {
 		const { flags } = await this.parse(ContributionPrep);
@@ -27,7 +26,6 @@ export default class ContributionPrep extends Command {
 				messages: [],
 			},
 			{
-				spawnWorker: !flags["no-spawn"],
 				artifactRoot: flags["artifact-root"],
 			},
 		);

package/src/commands/sdk.ts

@@ -1,3 +1,4 @@
+import { type ChildProcess, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import * as nodeFs from "node:fs";
 import * as fs from "node:fs/promises";
@@ -42,6 +43,7 @@ import {
 	writeSessionLifecycleReady,
 } from "../sdk/broker/lifecycle";
 import { processIncarnation } from "../sdk/broker/process-incarnation";
+import { resolveSdkInternalSpawnCommand } from "../sdk/broker/runtime";
 import { writeBrokerStartupFailureMarker } from "../sdk/broker/startup-failure";
 import { runSdkStderrDrainer } from "../sdk/broker/stderr-drainer";
 import { renderSdkSearchTable, runSdkSearch, runSdkSessionCli } from "../sdk/cli";
@@ -1441,6 +1443,7 @@ export async function runSessionHost(
 
 export type SdkInternalArgv =
 	| { action: "broker-internal"; agentDir: string }
+	| { action: "broker-trampoline-internal"; agentDir: string }
 	| { action: "session-host-internal" }
 	| { action: "stderr-drain-internal"; logPath: string; maxBytes: number };
 
@@ -1455,6 +1458,14 @@ export function parseSdkInternalArgv(argv: readonly string[]): SdkInternalArgv {
 		isSafeSdkInternalAgentDir(argv[2])
 	)
 		return { action: "broker-internal", agentDir: argv[2] };
+	if (
+		argv[0] === "broker-trampoline-internal" &&
+		argv.length === 3 &&
+		argv[1] === "--agent-dir" &&
+		typeof argv[2] === "string" &&
+		isSafeSdkInternalAgentDir(argv[2])
+	)
+		return { action: "broker-trampoline-internal", agentDir: argv[2] };
 	if (
 		argv[0] === "stderr-drain-internal" &&
 		argv.length === 5 &&
@@ -1494,6 +1505,7 @@ export default class Sdk extends Command {
 	async run(): Promise<void> {
 		if (
 			this.argv[0] !== "broker-internal" &&
+			this.argv[0] !== "broker-trampoline-internal" &&
 			this.argv[0] !== "session-host-internal" &&
 			this.argv[0] !== "stderr-drain-internal"
 		) {
@@ -1596,6 +1608,53 @@ export default class Sdk extends Command {
 		}
 
 		const internal = parseSdkInternalArgv(this.argv);
+		if (internal.action === "broker-trampoline-internal") {
+			if (process.platform === "win32") throw new CliParseError("Broker trampoline is unavailable on Windows.");
+			const command = resolveSdkInternalSpawnCommand("broker-internal");
+			let child: ChildProcess;
+			try {
+				child = spawn(command.file, [...command.args, "--agent-dir", internal.agentDir], {
+					detached: true,
+					stdio: ["ignore", "ignore", "inherit"],
+					env: command.env,
+					...(command.kind === "bun-source" ? { cwd: command.cwd } : {}),
+				});
+			} catch (error) {
+				throw new Error("Broker trampoline could not start broker.", { cause: error });
+			}
+			let spawnError: Error | undefined;
+			child.once("error", error => {
+				spawnError = error;
+			});
+			if (child.pid === undefined) throw new Error("Broker trampoline could not start broker.");
+			const incarnation = processIncarnation(child.pid);
+			if (!incarnation) {
+				try {
+					child.kill("SIGKILL");
+				} catch {
+					// The child may already have exited; either way identity was not established.
+				}
+				throw new Error("Broker trampoline could not observe broker identity.");
+			}
+			if (spawnError) throw new Error("Broker trampoline could not start broker.", { cause: spawnError });
+			const stdoutWrite = Promise.withResolvers<void>();
+			process.stdout.write(`${child.pid}\t${incarnation}\n`, error => {
+				if (error) stdoutWrite.reject(error);
+				else stdoutWrite.resolve();
+			});
+			try {
+				await stdoutWrite.promise;
+			} catch (error) {
+				try {
+					child.kill("SIGKILL");
+				} catch {
+					// The child may already have exited; reporting failure remains authoritative.
+				}
+				throw error;
+			}
+			child.unref();
+			return;
+		}
 		if (internal.action === "broker-internal") usePostmortemSignalExitAuthority();
 		if (internal.action === "session-host-internal") {
 			await runSessionHost();

package/src/commands/update.ts

@@ -13,6 +13,20 @@ import {
 } from "../config/update-channel";
 import { initTheme } from "../modes/theme/theme";
 
+export async function runUpdateRecoveryCommand(
+	recover: () => Promise<void> = () => runManagedNotifyRecovery({}),
+): Promise<void> {
+	try {
+		await recover();
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		process.stderr.write(
+			`Post-update recovery failed: ${reason}. For each configured notification daemon (telegram, discord, or slack), manually run 'gjc daemon stop <kind> --force' and then 'gjc daemon reload <kind>', then run 'gjc notify recovery'.\n`,
+		);
+		process.exitCode = 1;
+	}
+}
+
 export default class Update extends Command {
 	static description = "Check for and install updates";
 
@@ -35,7 +49,7 @@ export default class Update extends Command {
 	async run(): Promise<void> {
 		const { args, flags } = await this.parse(Update);
 		if (args.action === "update-recovery") {
-			await runManagedNotifyRecovery({});
+			await runUpdateRecoveryCommand();
 			return;
 		}
 		let channel: UpdateChannel | undefined;