@gajae-code/coding-agent 0.12.0 → 0.12.1

package/src/gjc-runtime/team-runtime.ts

@@ -551,6 +551,40 @@ export const GJC_TEAM_API_OPERATIONS = [
 	"write-task-approval",
 ] as const;
 
+export type GjcTeamApiOperation = (typeof GJC_TEAM_API_OPERATIONS)[number];
+
+export class UnknownGjcTeamApiOperationError extends Error {
+	readonly code = "unknown_team_api_operation";
+	readonly operation: string;
+	readonly suggestions: readonly string[];
+
+	constructor(operation: string, suggestions: readonly string[]) {
+		const guidance =
+			suggestions.length > 0
+				? `did you mean ${suggestions.join(" or ")}?`
+				: "run gjc team api --help for supported operations";
+		super(`unknown_team_api_operation:${operation}; ${guidance}`);
+		this.name = "UnknownGjcTeamApiOperationError";
+		this.operation = operation;
+		this.suggestions = suggestions;
+	}
+}
+
+function isGjcTeamApiOperation(operation: string): operation is GjcTeamApiOperation {
+	return (GJC_TEAM_API_OPERATIONS as readonly string[]).includes(operation);
+}
+
+function unknownGjcTeamApiOperationSuggestions(operation: string): readonly string[] {
+	if (operation === "heartbeat") return ["read-worker-heartbeat", "update-worker-heartbeat"];
+	if (operation === "get-task") return ["read-task"];
+	return [];
+}
+
+function resolveGjcTeamApiOperation(operation: string): GjcTeamApiOperation {
+	if (isGjcTeamApiOperation(operation)) return operation;
+	throw new UnknownGjcTeamApiOperationError(operation, unknownGjcTeamApiOperationSuggestions(operation));
+}
+
 function currentTimeMs(): number {
 	return gjcTeamRuntimeTestSeams?.nowMs?.() ?? Date.now();
 }
@@ -1494,6 +1528,7 @@ async function relaunchWorkerPaneForMemoryGuard(input: {
 	startupAckPath: string;
 	replacementToken: string;
 	startupAckTimeoutMs: number;
+	env: NodeJS.ProcessEnv;
 }): Promise<string> {
 	if (input.config.dry_run)
 		return `%memory-guard-${input.worker.id}-${stableHash(`${input.worker.id}:${now()}`).slice(0, 8)}`;
@@ -1502,6 +1537,7 @@ async function relaunchWorkerPaneForMemoryGuard(input: {
 		input.worker,
 		input.platform,
 		`Send startup ACK before resuming: gjc team api worker-startup-ack --input '{"team_name":"${input.config.team_name}","worker_id":"${input.worker.id}","protocol_version":"1","replacement_token":"${input.replacementToken}"}' --json. ${GJC_TEAM_CONTINUATION_PROMPT}`,
+		input.env,
 	);
 	const workerCwd = input.worker.worktree_path ?? input.config.leader.cwd;
 	const useSendKeysFallback = shouldDispatchWorkerWithSendKeys(input.config.tmux_command, input.platform);
@@ -1602,7 +1638,12 @@ async function applyWorkerMemoryGuardUnlocked(input: {
 	allowAutomaticAction?: boolean;
 	replacementToken?: string;
 	dir: string;
-	taskMutation: GjcTeamTaskMutationCapability;
+	/**
+	 * Acquire the team task-mutation fence only for the blocked-state transition.
+	 * Must not be held across the successor startup-ack wait: concurrent
+	 * `worker-startup-ack` must publish while replacement is in flight.
+	 */
+	withTaskMutation: <T>(fn: (capability: GjcTeamTaskMutationCapability) => Promise<T>) => Promise<T>;
 }): Promise<Record<string, unknown>> {
 	const dir = input.dir;
 	const config = await readConfig(dir);
@@ -1782,16 +1823,18 @@ async function applyWorkerMemoryGuardUnlocked(input: {
 		ledger = retried.ledger;
 		await writeWorkerMemoryGuardLedger(dir, ledger);
 		if (retried.finalBlocked)
-			await finalizeWorkerMemoryGuardBlockedState({
-				teamName: input.teamName,
-				dir,
-				worker,
-				task,
-				taskMutation: input.taskMutation,
-				reason: checkpoint.reason,
-				cwd: input.cwd,
-				env: input.env,
-			});
+			await input.withTaskMutation(taskMutation =>
+				finalizeWorkerMemoryGuardBlockedState({
+					teamName: input.teamName,
+					dir,
+					worker,
+					task,
+					taskMutation,
+					reason: checkpoint.reason,
+					cwd: input.cwd,
+					env: input.env,
+				}),
+			);
 		await appendWorkerMemoryGuardAction({
 			dir,
 			teamName: input.teamName,
@@ -1853,6 +1896,7 @@ async function applyWorkerMemoryGuardUnlocked(input: {
 			startupAckPath,
 			replacementToken,
 			startupAckTimeoutMs,
+			env: input.env,
 		});
 	} catch (error) {
 		await restorePredecessorStartupState();
@@ -1868,16 +1912,18 @@ async function applyWorkerMemoryGuardUnlocked(input: {
 		ledger = retried.ledger;
 		await writeWorkerMemoryGuardLedger(dir, ledger);
 		if (retried.finalBlocked)
-			await finalizeWorkerMemoryGuardBlockedState({
-				teamName: input.teamName,
-				dir,
-				worker,
-				task,
-				taskMutation: input.taskMutation,
-				reason,
-				cwd: input.cwd,
-				env: input.env,
-			});
+			await input.withTaskMutation(taskMutation =>
+				finalizeWorkerMemoryGuardBlockedState({
+					teamName: input.teamName,
+					dir,
+					worker,
+					task,
+					taskMutation,
+					reason,
+					cwd: input.cwd,
+					env: input.env,
+				}),
+			);
 		await appendWorkerMemoryGuardAction({
 			dir,
 			teamName: input.teamName,
@@ -2043,12 +2089,17 @@ async function applyWorkerMemoryGuardUnlocked(input: {
 }
 
 async function applyWorkerMemoryGuard(
-	input: Omit<Parameters<typeof applyWorkerMemoryGuardUnlocked>[0], "dir" | "taskMutation">,
+	input: Omit<Parameters<typeof applyWorkerMemoryGuardUnlocked>[0], "dir" | "withTaskMutation">,
 ): Promise<Record<string, unknown>> {
 	const dir = await findTeamDir(input.teamName, input.cwd, input.env);
-	return withGjcTeamTaskMutation(taskStore(dir), taskMutation =>
-		applyWorkerMemoryGuardUnlocked({ ...input, dir, taskMutation }),
-	);
+	// Do not hold withGjcTeamTaskMutation across relaunchWorkerPaneForMemoryGuard's
+	// startup-ack poll (default 120s). That fence would serialize concurrent
+	// worker-startup-ack publication and hang selector-replacement under CI load.
+	return applyWorkerMemoryGuardUnlocked({
+		...input,
+		dir,
+		withTaskMutation: fn => withGjcTeamTaskMutation(taskStore(dir), fn),
+	});
 }
 async function readPhase(dir: string): Promise<GjcTeamPhase> {
 	try {
@@ -2484,7 +2535,11 @@ function tagTmuxSessionAsGjcLeader(tmuxCommand: string, sessionName: string): bo
 	return result.exitCode === 0;
 }
 
-function readCurrentTmuxLeaderContext(tmuxCommand: string, env: NodeJS.ProcessEnv): GjcTmuxLeaderContext {
+function readCurrentTmuxLeaderContext(
+	tmuxCommand: string,
+	env: NodeJS.ProcessEnv,
+	adoptUnmanagedSession = true,
+): GjcTmuxLeaderContext {
 	if (Bun.which(tmuxCommand) === null)
 		throw new Error(buildTeamTmuxLeaderRequirementMessage(`tmux_not_installed:${tmuxCommand}`));
 	// Prefer the explicit GJC-managed session name propagated by `gjc --tmux`
@@ -2517,7 +2572,7 @@ function readCurrentTmuxLeaderContext(tmuxCommand: string, env: NodeJS.ProcessEn
 	const [sessionName = "", windowIndex = ""] = sessionAndWindow.split(":");
 	if (!sessionName || !windowIndex || !leaderPaneId.startsWith("%"))
 		throw new Error(buildTeamTmuxLeaderRequirementMessage(`invalid_tmux_context:${result.stdout.toString().trim()}`));
-	if (readGjcTmuxProfileValue(tmuxCommand, sessionName) !== GJC_TMUX_PROFILE_VALUE) {
+	if (adoptUnmanagedSession && readGjcTmuxProfileValue(tmuxCommand, sessionName) !== GJC_TMUX_PROFILE_VALUE) {
 		// Adopt any real tmux leader as a GJC team leader — including a session
 		// the user created outside `gjc --tmux` — by writing GJC's @gjc-profile
 		// ownership tag and reading it back. A provider that round-trips tmux
@@ -2540,6 +2595,20 @@ function readCurrentTmuxLeaderContext(tmuxCommand: string, env: NodeJS.ProcessEn
 		target: `${sessionName}:${windowIndex}`,
 	};
 }
+/**
+ * Check whether the current process can launch a team without changing tmux state.
+ * Unlike the launch path, this never adopts or tags an unmanaged tmux session.
+ */
+export function probeGjcTeamAvailability(
+	env: NodeJS.ProcessEnv = process.env,
+): { available: true } | { available: false; reason: string } {
+	try {
+		readCurrentTmuxLeaderContext(resolveGjcTmuxCommand(env), env, false);
+		return { available: true };
+	} catch (error) {
+		return { available: false, reason: error instanceof Error ? error.message : String(error) };
+	}
+}
 function isBunVirtualPath(candidate: string | undefined): boolean {
 	const normalized = candidate?.trim().replace(/\\/g, "/").toLowerCase();
 	return (
@@ -2718,7 +2787,7 @@ async function startTmuxSession(
 			const splitDirection: string = worker.index === 1 ? "-h" : "-v";
 			const splitTarget: string =
 				worker.index === 1 ? config.tmux_target : (rightStackRootPaneId ?? config.tmux_target);
-			const workerCommand = buildWorkerCommand(config, worker);
+			const workerCommand = buildWorkerCommand(config, worker, process.platform, undefined, env);
 			const workerCwd = worker.worktree_path ?? config.leader.cwd;
 			const useSendKeysFallback = shouldDispatchWorkerWithSendKeys(config.tmux_command);
 			const splitArgs = [
@@ -4247,11 +4316,13 @@ function parseDurationEnv(env: NodeJS.ProcessEnv, name: string, fallbackMs: numb
 	return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallbackMs;
 }
 
-function parseHeartbeatStaleMs(env: NodeJS.ProcessEnv): number {
+/** Positive stale windows are clamped so a worker can publish strictly before expiry. */
+export function parseHeartbeatStaleMs(env: NodeJS.ProcessEnv): number {
 	const raw = env.GJC_TEAM_HEARTBEAT_STALE_MS?.trim();
 	if (!raw) return 120_000;
 	const parsed = Number(raw);
-	return Number.isFinite(parsed) ? parsed : 120_000;
+	if (!Number.isFinite(parsed)) return 120_000;
+	return parsed > 0 ? Math.max(3, parsed) : parsed;
 }
 async function writeLifecycleNudge(
 	dir: string,
@@ -4751,6 +4822,41 @@ export async function updateGjcWorkerHeartbeat(
 		updateWorkerHeartbeat(workerRuntime, teamName, worker, heartbeat, cwd, env),
 	);
 }
+/**
+ * Refresh liveness without discarding metadata written by other heartbeat
+ * producers. The read/merge/write sequence shares the team mutation fence with
+ * CLI heartbeat updates, so a runtime tick cannot overwrite a newer turn count.
+ */
+export async function refreshGjcWorkerHeartbeat(
+	teamName: string,
+	worker: string,
+	pid: number,
+	cwd = process.cwd(),
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<WorkerHeartbeatFile> {
+	const dir = await findTeamDir(teamName, cwd, env);
+	return withGjcTeamMutationFence(dir, async () => {
+		const current = await readWorkerHeartbeat(workerRuntime, teamName, worker, cwd, env);
+		const processStartTime = await readLinuxProcessStartTime(pid);
+		const turnCount = current?.turn_count;
+		return updateWorkerHeartbeat(
+			workerRuntime,
+			teamName,
+			worker,
+			{
+				...current,
+				pid,
+				last_turn_at: now(),
+				turn_count: Number.isSafeInteger(turnCount) && (turnCount ?? -1) >= 0 ? (turnCount ?? 0) : 0,
+				alive: true,
+				// Never carry another process's incarnation across a pid change.
+				process_start_time: processStartTime ?? (current?.pid === pid ? current.process_start_time : undefined),
+			},
+			cwd,
+			env,
+		);
+	});
+}
 export async function writeGjcWorkerInbox(
 	teamName: string,
 	worker: string,
@@ -4896,12 +5002,13 @@ export async function executeGjcTeamApiOperation(
 	cwd = process.cwd(),
 	env: NodeJS.ProcessEnv = process.env,
 ): Promise<unknown> {
+	const resolvedOperation = resolveGjcTeamApiOperation(operation);
 	const teamName = String(input.team_name ?? input.teamName ?? "").trim();
 	if (!teamName) throw new Error("missing_team_name");
 	const workerInput = input.worker ?? input.worker_id ?? input.workerId;
 	const worker = String(workerInput ?? "worker-1");
 	const explicitWorker = workerInput == null ? undefined : String(workerInput);
-	switch (operation) {
+	switch (resolvedOperation) {
 		case "list-tasks":
 			return { tasks: await listGjcTeamTasks(teamName, cwd, env) };
 		case "read-task":
@@ -5247,7 +5354,8 @@ export async function executeGjcTeamApiOperation(
 		case "read-shutdown-ack":
 			return readGjcShutdownAck(teamName, worker, cwd, env);
 		default:
-			throw new Error(`unknown_team_api_operation:${operation}`);
+			resolvedOperation satisfies never;
+			throw new UnknownGjcTeamApiOperationError(operation, []);
 	}
 }
 

package/src/gjc-runtime/team-worker-heartbeat.ts

@@ -0,0 +1,149 @@
+/**
+ * Runtime-owned `gjc team` worker heartbeat.
+ *
+ * Worker liveness used to be published only when the model remembered to call
+ * `gjc team api update-worker-heartbeat` between turns. A worker inside a
+ * single tool call longer than `GJC_TEAM_HEARTBEAT_STALE_MS` (default 120s) was
+ * therefore reported as stale and had its task claim requeued mid-flight — even
+ * though the claim lease it invalidated is 30 minutes long. This module makes
+ * the worker process itself publish liveness while a turn is in flight, so the
+ * heartbeat records what the process is doing instead of what the model
+ * remembered to report.
+ *
+ * The published record carries the writer's real pid, so leader-side diagnostics
+ * name the process that is actually working rather than a placeholder.
+ */
+import { logger } from "@gajae-code/utils";
+import { parseHeartbeatStaleMs, refreshGjcWorkerHeartbeat, type WorkerHeartbeatFile } from "./team-runtime";
+
+/** Publish several times per stale window so one missed tick cannot cross it. */
+const HEARTBEAT_INTERVAL_DIVISOR = 3;
+const MIN_HEARTBEAT_INTERVAL_MS = 1;
+const MAX_HEARTBEAT_INTERVAL_MS = 30_000;
+
+export interface GjcTeamWorkerIdentity {
+	teamName: string;
+	workerId: string;
+}
+
+/** Resolves the team identity injected into a worker pane by `gjc team` startup. */
+export function resolveGjcTeamWorkerIdentity(env: NodeJS.ProcessEnv = process.env): GjcTeamWorkerIdentity | undefined {
+	const teamName = env.GJC_TEAM_NAME?.trim();
+	const workerId = env.GJC_TEAM_WORKER_ID?.trim() || env.GJC_TEAM_INTERNAL_WORKER?.split("/").pop()?.trim();
+	return teamName && workerId ? { teamName, workerId } : undefined;
+}
+
+/** Refresh cadence derived from the leader's stale window; `0` disables publishing. */
+export function resolveGjcTeamWorkerHeartbeatIntervalMs(env: NodeJS.ProcessEnv = process.env): number {
+	const staleMs = parseHeartbeatStaleMs(env);
+	if (staleMs <= 0) return 0;
+	return Math.min(
+		MAX_HEARTBEAT_INTERVAL_MS,
+		Math.max(MIN_HEARTBEAT_INTERVAL_MS, Math.floor(staleMs / HEARTBEAT_INTERVAL_DIVISOR)),
+	);
+}
+
+/**
+ * Publish one runtime-owned heartbeat for the worker this process is running as.
+ * Returns `undefined` when the process is not a team worker.
+ *
+ * `turn_count` and process-incarnation metadata are merged under the same
+ * mutation fence used by CLI heartbeat updates.
+ */
+export async function writeGjcTeamWorkerRuntimeHeartbeat(
+	cwd: string = process.cwd(),
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<WorkerHeartbeatFile | undefined> {
+	const identity = resolveGjcTeamWorkerIdentity(env);
+	if (!identity) return undefined;
+	return refreshGjcWorkerHeartbeat(identity.teamName, identity.workerId, process.pid, cwd, env);
+}
+
+export interface GjcTeamWorkerHeartbeatReporterOptions {
+	write: () => Promise<void>;
+	intervalMs: number;
+}
+
+/**
+ * Publishes a worker heartbeat while a turn is in flight.
+ *
+ * Writes never overlap; a slow or failing write is logged and skipped rather
+ * than queued, because only the most recent record matters. The timer is
+ * unreferenced so it can never hold the process open.
+ */
+export class GjcTeamWorkerHeartbeatReporter {
+	readonly #write: () => Promise<void>;
+	readonly #intervalMs: number;
+	#timer: NodeJS.Timeout | undefined;
+	#inFlight: Promise<void> | undefined;
+	#disposed = false;
+
+	constructor(options: GjcTeamWorkerHeartbeatReporterOptions) {
+		this.#write = options.write;
+		this.#intervalMs = options.intervalMs;
+	}
+
+	/** Reporter for the current process, or `undefined` when it is not a team worker. */
+	static forProcess(
+		cwd: () => string,
+		env: NodeJS.ProcessEnv = process.env,
+	): GjcTeamWorkerHeartbeatReporter | undefined {
+		if (!resolveGjcTeamWorkerIdentity(env)) return undefined;
+		const intervalMs = resolveGjcTeamWorkerHeartbeatIntervalMs(env);
+		if (intervalMs <= 0) return undefined;
+		return new GjcTeamWorkerHeartbeatReporter({
+			intervalMs,
+			write: async () => {
+				await writeGjcTeamWorkerRuntimeHeartbeat(cwd(), env);
+			},
+		});
+	}
+
+	get isRunning(): boolean {
+		return this.#timer !== undefined;
+	}
+
+	/** Publish immediately, then keep publishing until {@link stop} or {@link dispose}. */
+	start(): void {
+		if (this.#disposed || this.#timer) return;
+		this.#publish();
+		this.#timer = setInterval(() => this.#publish(), this.#intervalMs);
+		this.#timer.unref?.();
+	}
+
+	/** Stop periodic publishing after one final record, so the idle stamp is fresh. */
+	stop(): void {
+		if (!this.#timer) return;
+		clearInterval(this.#timer);
+		this.#timer = undefined;
+		this.#publish();
+	}
+
+	/** Await the write in flight, if any. */
+	async flush(): Promise<void> {
+		while (this.#inFlight) {
+			await this.#inFlight;
+		}
+	}
+
+	/** Permanently stop publishing. Idempotent. */
+	dispose(): void {
+		this.#disposed = true;
+		if (this.#timer) {
+			clearInterval(this.#timer);
+			this.#timer = undefined;
+		}
+	}
+
+	#publish(): void {
+		if (this.#disposed || this.#inFlight) return;
+		const run = this.#write()
+			.catch((error: unknown) => {
+				logger.warn("GJC team worker heartbeat publish failed", { error: String(error) });
+			})
+			.finally(() => {
+				if (this.#inFlight === run) this.#inFlight = undefined;
+			});
+		this.#inFlight = run;
+	}
+}

package/src/gjc-runtime/tmux-owner-isolation.ts

@@ -110,6 +110,16 @@ export interface TmuxServerProof {
 	startTime?: string;
 	cgroup?: CgroupInfo;
 	sessionNames?: string[];
+	/**
+	 * Whether `pid` is kernel-proved evidence about the live tmux server.
+	 *
+	 * Only Linux can prove a server PID (`/proc` + cgroup classification), so
+	 * probes on other platforms may report a placeholder PID with this flag set
+	 * to `false`. Guards must not build a `#{pid}` predicate from an unproven
+	 * PID: no live tmux server can ever satisfy it. Omitted means proven, which
+	 * keeps every probe that reads a real `#{pid}` unchanged.
+	 */
+	pidProven?: boolean;
 }
 
 export interface PlanRequest {

package/src/gjc-runtime/tmux-sessions.ts

@@ -407,6 +407,7 @@ export function createGjcTmuxSession(
 				pid: 1,
 				startTime: "not-applicable",
 				cgroup: { classification: "not_applicable" },
+				pidProven: false,
 			};
 		}
 		const result = Bun.spawnSync([tmuxCommand, "display-message", "-p", "#{pid}"], {
@@ -534,6 +535,7 @@ export function createGjcTmuxSession(
 				env,
 				server.pid,
 				server.startTime,
+				server.pidProven,
 			);
 		},
 	});
@@ -551,7 +553,7 @@ export function createGjcTmuxSession(
 		tagCreatedTmuxSession(
 			nativeSessionId,
 			sessionName,
-			outcome.server_pid,
+			{ pid: outcome.server_pid, pidProven: server.pidProven },
 			env,
 			{
 				sessionId,
@@ -571,6 +573,7 @@ export function createGjcTmuxSession(
 				env,
 				outcome.server_pid,
 				outcome.server_start_time,
+				server.pidProven,
 			);
 		} catch (cleanupError) {
 			throw new AggregateError([tagError, cleanupError], "gjc_tmux_profile_tag_failed_cleanup_failed");
@@ -597,6 +600,7 @@ export function createGjcTmuxSession(
 					env,
 					outcome.server_pid,
 					outcome.server_start_time,
+					finalServer.pidProven,
 				);
 			} catch (cleanupError) {
 				throw new AggregateError(
@@ -619,6 +623,7 @@ export function createGjcTmuxSession(
 				env,
 				outcome.server_pid,
 				outcome.server_start_time,
+				server.pidProven,
 			);
 		} catch (cleanupError) {
 			throw new AggregateError(
@@ -645,8 +650,18 @@ function tmuxCommandArgument(value: string): string {
 	return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("$", "\\$").replaceAll("`", "\\`")}"`;
 }
 
+/**
+ * Build the guard predicate for an exact tmux session mutation.
+ *
+ * The `#{pid}` clause is emitted only when the server proof actually proved a
+ * PID. Non-Linux probes report a placeholder PID (see {@link TmuxServerProof}),
+ * and pinning `#{pid}` to a placeholder produces a predicate no live tmux
+ * server can satisfy, which refuses every mutation on those platforms. The
+ * remaining clauses still pin the exact session id, session name and owner
+ * generation.
+ */
 function guardedTmuxSessionPredicate(
-	expectedPid: number,
+	expectedServer: { pid: number; pidProven?: boolean },
 	nativeSessionId: string,
 	sessionName: string,
 	expectedOwnerGeneration?: string,
@@ -654,13 +669,14 @@ function guardedTmuxSessionPredicate(
 	const ownerGenerationPredicate = expectedOwnerGeneration
 		? `#{==:#{${GJC_TMUX_OWNER_GENERATION_OPTION}},${expectedOwnerGeneration}}`
 		: "1";
-	return `#{&&:#{==:#{pid},${expectedPid}},#{&&:#{==:#{session_id},${nativeSessionId}},#{&&:#{==:#{session_name},${sessionName}},${ownerGenerationPredicate}}}}`;
+	const serverPidPredicate = expectedServer.pidProven === false ? "1" : `#{==:#{pid},${expectedServer.pid}}`;
+	return `#{&&:${serverPidPredicate},#{&&:#{==:#{session_id},${nativeSessionId}},#{&&:#{==:#{session_name},${sessionName}},${ownerGenerationPredicate}}}}`;
 }
 
 function runGuardedTmuxSessionCommand(
 	nativeSessionId: string,
 	sessionName: string,
-	expectedPid: number,
+	expectedServer: { pid: number; pidProven?: boolean },
 	env: NodeJS.ProcessEnv,
 	thenCommand: string,
 	expectedOwnerGeneration?: string,
@@ -671,7 +687,7 @@ function runGuardedTmuxSessionCommand(
 			"-t",
 			normalizeExactTmuxTarget(nativeSessionId, env, "session"),
 			"-F",
-			guardedTmuxSessionPredicate(expectedPid, nativeSessionId, sessionName, expectedOwnerGeneration),
+			guardedTmuxSessionPredicate(expectedServer, nativeSessionId, sessionName, expectedOwnerGeneration),
 			`${thenCommand} ; display-message -p __gjc_tmux_guarded_mutation_ok__`,
 			"display-message -p __gjc_tmux_guarded_mutation_refused__",
 		],
@@ -683,7 +699,7 @@ function runGuardedTmuxSessionCommand(
 function tagCreatedTmuxSession(
 	nativeSessionId: string,
 	sessionName: string,
-	expectedPid: number,
+	expectedServer: { pid: number; pidProven?: boolean },
 	env: NodeJS.ProcessEnv,
 	metadata: {
 		branch?: string | null;
@@ -701,7 +717,7 @@ function tagCreatedTmuxSession(
 	const commands = buildGjcTmuxProfileCommands(target, env, metadata, { tmuxCommand })
 		.map(command => command.args.map(tmuxCommandArgument).join(" "))
 		.join(" ; ");
-	runGuardedTmuxSessionCommand(nativeSessionId, sessionName, expectedPid, env, commands);
+	runGuardedTmuxSessionCommand(nativeSessionId, sessionName, expectedServer, env, commands);
 }
 
 function cleanupExactCreatedTmuxSession(
@@ -711,6 +727,7 @@ function cleanupExactCreatedTmuxSession(
 	env: NodeJS.ProcessEnv,
 	expectedPid: number,
 	expectedStartTime: string,
+	expectedPidProven?: boolean,
 ): void {
 	const server = requireSafeTmuxServerForMutation(tmuxCommand, env);
 	if (server.pid !== expectedPid || server.startTime !== expectedStartTime)
@@ -718,7 +735,7 @@ function cleanupExactCreatedTmuxSession(
 	runGuardedTmuxSessionCommand(
 		nativeSessionId,
 		sessionName,
-		expectedPid,
+		{ pid: expectedPid, pidProven: expectedPidProven ?? server.pidProven },
 		env,
 		`kill-session -t ${tmuxCommandArgument(normalizeExactTmuxTarget(nativeSessionId, env, "session"))}`,
 	);
@@ -727,7 +744,7 @@ function cleanupExactCreatedTmuxSession(
 function requireSafeTmuxServerForMutation(
 	tmuxCommand: string,
 	env: NodeJS.ProcessEnv,
-): { pid: number; startTime: string } {
+): { pid: number; startTime: string; pidProven?: boolean } {
 	if (mutationServerProofTestDependency) {
 		const proof = mutationServerProofTestDependency(tmuxCommand, env);
 		if (
@@ -739,7 +756,7 @@ function requireSafeTmuxServerForMutation(
 			return proof as { pid: number; startTime: string };
 		return { pid: 1, startTime: "test" };
 	}
-	if (process.platform !== "linux") return { pid: 1, startTime: "not-applicable" };
+	if (process.platform !== "linux") return { pid: 1, startTime: "not-applicable", pidProven: false };
 	const result = Bun.spawnSync([tmuxCommand, "display-message", "-p", "#{pid}"], {
 		stdout: "pipe",
 		stderr: "pipe",
@@ -953,7 +970,7 @@ export function removeGjcTmuxSession(
 	runGuardedTmuxSessionCommand(
 		nativeSessionId,
 		session.name,
-		finalServer.pid,
+		finalServer,
 		env,
 		`kill-session -t '${nativeSessionId}'`,
 		expectedIdentity?.ownerGeneration,
@@ -962,6 +979,13 @@ export function removeGjcTmuxSession(
 }
 
 async function readProcessStartTime(pid: number): Promise<string | null> {
+	// `/proc/<pid>/stat` only exists on Linux. Everywhere else the natives
+	// process reference carries the same kernel-derived start identity (macOS
+	// reports `darwin:<start_tvsec>:<start_tvusec>` from the BSD proc info), and
+	// callers only ever compare these values for equality against another value
+	// produced here. Returning null off Linux made every owner-identity proof
+	// unverifiable, so no session could be closed there.
+	if (process.platform !== "linux") return Process.fromPid(pid)?.incarnation ?? null;
 	return readLinuxProcStartTime(pid);
 }
 
@@ -973,6 +997,27 @@ function exactManagedOwnerSupervisor(supervisorPid: number, supervisorStartTime:
 	return supervisor;
 }
 
+/**
+ * Deliver SIGTERM to exactly one already-proved owner PID.
+ *
+ * `Process.signalRoot` routes through the owned pidfd on Linux and the owned
+ * process handle on Windows, so PID reuse cannot redirect the signal. macOS has
+ * no equivalent kernel authority and the native binding deliberately fails
+ * closed there, which would leave every macOS force-close unable to signal its
+ * owner at all. On that platform the caller has already re-proved the PID's
+ * start-time incarnation immediately before this call — the same evidence the
+ * native macOS signal path re-validates — so deliver to that exact PID.
+ */
+function signalManagedOwnerTerm(supervisor: Process, pid: number): boolean {
+	if (process.platform !== "darwin") return supervisor.signalRoot(15);
+	try {
+		process.kill(pid, "SIGTERM");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 async function readCurrentGeneration(stateDir: string, sessionId: string): Promise<string | null> {
 	try {
 		const value: unknown = JSON.parse(
@@ -1185,7 +1230,7 @@ export async function forceCloseGjcTmuxSession(
 					deps.signalTerm(pid);
 				} else {
 					const supervisor = exactManagedOwnerSupervisor(pid, identity.startTime);
-					if (!supervisor.signalRoot(15)) throw new Error("managed_owner_supervisor_signal_failed");
+					if (!signalManagedOwnerTerm(supervisor, pid)) throw new Error("managed_owner_supervisor_signal_failed");
 					operatorVerdict = supervisor
 						.waitForExit({ timeoutMs: FORCE_CLOSE_VERDICT_TIMEOUT_MS - 500 })
 						.then(async exited => {
@@ -1227,7 +1272,7 @@ export async function forceCloseGjcTmuxSession(
 					runGuardedTmuxSessionCommand(
 						nativeSessionId,
 						session.name,
-						initialServer.pid,
+						initialServer,
 						env,
 						`kill-session -t '${nativeSessionId}'`,
 						identity.generation,