@gajae-code/coding-agent 0.11.3 → 0.11.5

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

@@ -1,4 +1,3 @@
-import { Buffer } from "node:buffer";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -6,6 +5,18 @@ import { VERSION } from "@gajae-code/utils/dirs";
 import { safeStderrWrite } from "@gajae-code/utils/safe-stderr";
 import type { Args } from "../cli/args";
 import { readLinuxProcStartTimeSync } from "./linux-proc";
+import {
+	MANAGED_OWNER_PREDECESSOR_GENERATION_ENV,
+	MANAGED_OWNER_PREDECESSOR_INCARNATION_ENV,
+	MANAGED_OWNER_PREDECESSOR_RUN_ID_ENV,
+	MANAGED_OWNER_PREDECESSOR_TOKEN_ENV,
+	MANAGED_OWNER_TRANSCRIPT_PATH_ENV,
+} from "./managed-owner-admission";
+import {
+	MANAGED_OWNER_INCARNATION_ENV,
+	MANAGED_OWNER_RUN_ID_ENV,
+	MANAGED_OWNER_SUPERVISOR_ARG,
+} from "./managed-owner-supervisor";
 import { tmuxRuntimeSessionPath } from "./session-layout";
 import {
 	GJC_COORDINATOR_SESSION_BRANCH_ENV,
@@ -42,6 +53,7 @@ import {
 	type OwnerIsolationProbeSync,
 	planTmuxOwnerIsolationSync,
 	replaceOwnerGenerationSync,
+	resolveManagedOwnerPredecessorSync,
 	type TmuxServerProof,
 } from "./tmux-owner-isolation";
 import {
@@ -152,6 +164,9 @@ export interface TmuxLaunchPlan {
 	sessionStateFile?: string | null;
 	/** Immutable Linux-managed owner provenance, assigned immediately before creation. */
 	ownerGeneration?: string;
+	/** Immutable run and endpoint identities bound into the supervised command. */
+	ownerRunId?: string;
+	ownerIncarnation?: string;
 	/** Generation state captured before owner-isolation planning; required for publication CAS. */
 	ownerGenerationBaseline?: import("./tmux-owner-isolation").OwnerGenerationBaseline;
 	/** Native tmux session identity emitted atomically by `new-session -P -F`. */
@@ -334,6 +349,7 @@ interface CommandResolutionContext {
 	extraEnv?: Record<string, string>;
 	tmuxExitMarkerPath?: string;
 	platform?: NodeJS.Platform;
+	managedOwnerSupervisor?: boolean;
 }
 
 function parseLaunchPolicy(env: NodeJS.ProcessEnv): LaunchPolicy {
@@ -553,8 +569,15 @@ function buildInnerCommand(context: CommandResolutionContext, rawArgs: string[])
 			tmuxExitMarkerPath: context.tmuxExitMarkerPath,
 		});
 	const command = resolveCurrentGjcCommand(context);
-	const quoted = [...command, ...stripRootTmuxFlag(rawArgs)].map(shellQuote).join(" ");
-	const invocation = `env ${GJC_TMUX_LAUNCHED_ENV}=1${buildEnvAssignments(context.extraEnv)} ${quoted}`;
+	const childArgs = stripRootTmuxFlag(rawArgs);
+	const supervisorEnv: Record<string, string> = context.managedOwnerSupervisor
+		? { GJC_MANAGED_OWNER_COMMAND_JSON: JSON.stringify([...command, ...childArgs]) }
+		: {};
+	const invocationArgs = context.managedOwnerSupervisor
+		? [...command, MANAGED_OWNER_SUPERVISOR_ARG]
+		: [...command, ...childArgs];
+	const quoted = invocationArgs.map(shellQuote).join(" ");
+	const invocation = `env ${GJC_TMUX_LAUNCHED_ENV}=1${buildEnvAssignments({ ...context.extraEnv, ...supervisorEnv })} ${quoted}`;
 	if (!context.tmuxExitMarkerPath) return `exec ${invocation}`;
 	return `${buildPosixTmuxExitMarkerPrefix(context.tmuxExitMarkerPath)}; ${invocation}; exit $?`;
 }
@@ -1026,15 +1049,29 @@ export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaun
 	};
 }
 
+function trustedReplacementAuthority(
+	stateDir: string,
+	sessionId: string,
+	baseline: ReturnType<typeof captureOwnerGenerationBaselineSync>,
+): ReturnType<typeof resolveManagedOwnerPredecessorSync> {
+	return resolveManagedOwnerPredecessorSync(stateDir, sessionId, baseline);
+}
+
 function prepareManagedOwnerLifecycle(plan: TmuxLaunchPlan, context: TmuxLaunchContext): void {
 	if (plan.ownerGeneration) return;
 	const sessionId = plan.sessionId ?? plan.sessionName;
 	const stateDir = path.dirname(plan.sessionStateFile ?? path.join(plan.cwd, ".gjc", "runtime"));
+	const baseline = captureOwnerGenerationBaselineSync(stateDir, sessionId);
+	const replacement = trustedReplacementAuthority(stateDir, sessionId, baseline);
 	const generation = crypto.randomUUID();
-	// Stage the generation in the child command. It becomes current only after
+	const runId = crypto.randomUUID();
+	const incarnation = crypto.randomUUID();
+	plan.ownerGenerationBaseline = baseline;
+	// Stage immutable identity in the child command. It becomes current only after
 	// immutable creation proof and ownership tagging complete.
-
 	plan.ownerGeneration = generation;
+	plan.ownerRunId = runId;
+	plan.ownerIncarnation = incarnation;
 	const innerCommand = buildInnerCommand(
 		{
 			cwd: plan.cwd,
@@ -1047,11 +1084,24 @@ function prepareManagedOwnerLifecycle(plan: TmuxLaunchPlan, context: TmuxLaunchC
 				[GJC_TMUX_OWNER_GENERATION_ENV]: generation,
 				[GJC_TMUX_OWNER_STATE_DIR_ENV]: stateDir,
 				[GJC_TMUX_OWNER_SERVER_KEY_ENV]: plan.tmuxCommand,
+				[MANAGED_OWNER_RUN_ID_ENV]: runId,
+				[MANAGED_OWNER_INCARNATION_ENV]: incarnation,
+				...(replacement
+					? {
+							[MANAGED_OWNER_PREDECESSOR_TOKEN_ENV]: replacement.predecessorToken,
+							[MANAGED_OWNER_PREDECESSOR_GENERATION_ENV]: replacement.generation,
+							[MANAGED_OWNER_PREDECESSOR_RUN_ID_ENV]: replacement.runId,
+							[MANAGED_OWNER_PREDECESSOR_INCARNATION_ENV]: replacement.incarnation,
+							[MANAGED_OWNER_TRANSCRIPT_PATH_ENV]:
+								context.env?.GJC_SESSION_FILE ?? process.env.GJC_SESSION_FILE ?? "",
+						}
+					: {}),
 			},
 			// Linux managed owner close signals the pane PID. Do not place the exit-marker shell
 			// in front of it; `buildInnerCommand` therefore execs the GJC owner directly.
 			tmuxExitMarkerPath: plan.platform === "linux" ? undefined : tmuxExitMarkerPath(plan.sessionStateFile ?? ""),
 			platform: plan.platform,
+			managedOwnerSupervisor: plan.platform === "linux",
 		},
 		context.rawArgs,
 	);
@@ -1182,7 +1232,7 @@ function createIsolatedTmuxSession(
 ): TmuxSpawnResult {
 	const sessionId = plan.sessionId ?? plan.sessionName;
 	const stateDir = path.dirname(plan.sessionStateFile ?? path.join(plan.cwd, ".gjc", "runtime"));
-	const baseline = captureOwnerGenerationBaselineSync(stateDir, sessionId);
+	const baseline = plan.ownerGenerationBaseline ?? captureOwnerGenerationBaselineSync(stateDir, sessionId);
 	plan.ownerGenerationBaseline = baseline;
 	const ownerPlan = planTmuxOwnerIsolationSync(
 		{
@@ -1572,6 +1622,11 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 		return true;
 	}
 	try {
+		resolveManagedOwnerPredecessorSync(
+			path.dirname(plan.sessionStateFile!),
+			plan.sessionId!,
+			plan.ownerGenerationBaseline!,
+		);
 		replaceOwnerGenerationSync(
 			path.dirname(plan.sessionStateFile!),
 			plan.sessionId!,

package/src/gjc-runtime/managed-owner-admission.ts

@@ -0,0 +1,352 @@
+import { Buffer } from "node:buffer";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { openRecoveryFsRoot } from "@gajae-code/natives";
+import {
+	MANAGED_OWNER_CHILD_TOKEN_ENV,
+	MANAGED_OWNER_GENERATION_ENV,
+	MANAGED_OWNER_INCARNATION_ENV,
+	MANAGED_OWNER_RUN_ID_ENV,
+	MANAGED_OWNER_SESSION_ID_ENV,
+	MANAGED_OWNER_STATE_DIR_ENV,
+	type ManagedOwnerBinding,
+	type ManagedOwnerSigabrtReceipt,
+} from "./managed-owner-supervisor";
+import { assertSafePathComponent } from "./session-layout";
+import { lifecyclePaths } from "./tmux-owner-isolation";
+import {
+	persistUltragoalRecoveryDecision,
+	planUltragoalOwnerLossRecovery,
+	type UltragoalRecoveryDecision,
+} from "./ultragoal-owner-loss-recovery";
+
+export const MANAGED_OWNER_PREDECESSOR_TOKEN_ENV = "GJC_MANAGED_OWNER_PREDECESSOR_TOKEN";
+export const MANAGED_OWNER_PREDECESSOR_GENERATION_ENV = "GJC_MANAGED_OWNER_PREDECESSOR_GENERATION";
+export const MANAGED_OWNER_PREDECESSOR_RUN_ID_ENV = "GJC_MANAGED_OWNER_PREDECESSOR_RUN_ID";
+export const MANAGED_OWNER_PREDECESSOR_INCARNATION_ENV = "GJC_MANAGED_OWNER_PREDECESSOR_INCARNATION";
+export const MANAGED_OWNER_TRANSCRIPT_PATH_ENV = "GJC_MANAGED_OWNER_TRANSCRIPT_PATH";
+
+export interface ManagedOwnerRecoveryContext {
+	root: string;
+	binding: ManagedOwnerBinding;
+	receipt: ManagedOwnerSigabrtReceipt;
+	admission: { session_id: string; endpoint_incarnation: string; owner_generation: string; admitted: true };
+	decision: UltragoalRecoveryDecision;
+}
+export type ManagedOwnerAdmission =
+	| { kind: "fresh" | "supervised" }
+	| { kind: "recovery"; context: ManagedOwnerRecoveryContext }
+	| { kind: "blocked" };
+
+function ownerEnvironment(): {
+	root: string;
+	generation: string;
+	sessionId: string;
+	runId: string;
+	incarnation: string;
+} | null {
+	const stateDir = process.env[MANAGED_OWNER_STATE_DIR_ENV]?.trim();
+	const sessionId = process.env[MANAGED_OWNER_SESSION_ID_ENV]?.trim();
+	const generation = process.env[MANAGED_OWNER_GENERATION_ENV]?.trim();
+	const runId = process.env[MANAGED_OWNER_RUN_ID_ENV]?.trim();
+	const incarnation = process.env[MANAGED_OWNER_INCARNATION_ENV]?.trim();
+	if (!stateDir && !sessionId && !generation && !runId && !incarnation) return null;
+	if (!stateDir || !sessionId || !generation || !runId || !incarnation || !path.isAbsolute(stateDir))
+		throw new Error("managed_owner_admission_metadata_invalid");
+	for (const [value, label] of [
+		[sessionId, "managed owner session id"],
+		[generation, "managed owner generation"],
+		[runId, "managed owner run id"],
+		[incarnation, "managed owner incarnation"],
+	] as const)
+		assertSafePathComponent(value, label);
+	const root = lifecyclePaths(stateDir, sessionId, generation).root;
+	if (!root.startsWith(`${path.resolve(stateDir)}${path.sep}`)) throw new Error("managed_owner_admission_path_unsafe");
+	return { root, generation, sessionId, runId, incarnation };
+}
+
+function isCommand(command: unknown): command is string[] {
+	return (
+		Array.isArray(command) &&
+		command.length > 0 &&
+		command.every(value => typeof value === "string" && value.length > 0)
+	);
+}
+
+function isBinding(
+	value: unknown,
+	expected: { generation: string; sessionId: string; runId: string; incarnation: string; token: string },
+): value is ManagedOwnerBinding {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const binding = value as Partial<ManagedOwnerBinding>;
+	return (
+		binding.schema_version === 2 &&
+		binding.generation === expected.generation &&
+		binding.session_id === expected.sessionId &&
+		binding.run_id === expected.runId &&
+		binding.endpoint_incarnation === expected.incarnation &&
+		binding.child_token === expected.token &&
+		isCommand(binding.command) &&
+		typeof binding.command_sha256 === "string" &&
+		binding.command_sha256 === crypto.createHash("sha256").update(JSON.stringify(binding.command)).digest("hex") &&
+		typeof binding.supervisor_pid === "number" &&
+		Number.isSafeInteger(binding.supervisor_pid) &&
+		binding.supervisor_pid > 0 &&
+		typeof binding.supervisor_start_time === "string" &&
+		typeof binding.created_at === "string"
+	);
+}
+
+function isReceipt(value: unknown, binding: ManagedOwnerBinding): value is ManagedOwnerSigabrtReceipt {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const receipt = value as Partial<ManagedOwnerSigabrtReceipt>;
+	return (
+		receipt.schema_version === 2 &&
+		receipt.generation === binding.generation &&
+		receipt.session_id === binding.session_id &&
+		receipt.run_id === binding.run_id &&
+		receipt.endpoint_incarnation === binding.endpoint_incarnation &&
+		receipt.child_token === binding.child_token &&
+		receipt.command_sha256 === binding.command_sha256 &&
+		receipt.supervisor_pid === binding.supervisor_pid &&
+		receipt.supervisor_start_time === binding.supervisor_start_time &&
+		typeof receipt.child_pid === "number" &&
+		Number.isSafeInteger(receipt.child_pid) &&
+		receipt.child_pid > 0 &&
+		typeof receipt.child_start_time === "string" &&
+		receipt.signal === "SIGABRT" &&
+		receipt.signal_number === 6 &&
+		(receipt.exit_code === null || Number.isSafeInteger(receipt.exit_code)) &&
+		typeof receipt.received_at === "string"
+	);
+}
+
+function safeChildToken(value: string): boolean {
+	try {
+		assertSafePathComponent(value, "managed owner child token");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function readExactJsons(root: string, files: readonly string[]): Promise<unknown[] | null> {
+	if (process.platform !== "linux") return null;
+	try {
+		const authority = openRecoveryFsRoot(root);
+		try {
+			const values: unknown[] = [];
+			for (const file of files) {
+				const result = authority.read(file, 64 * 1024);
+				if (!result.ok || !result.data) return null;
+				const content = Buffer.from(result.data).toString("utf8");
+				if (!content.endsWith("\n") || content.indexOf("\n") !== content.length - 1) return null;
+				values.push(JSON.parse(content));
+			}
+			return values;
+		} finally {
+			authority.close();
+		}
+	} catch {
+		return null;
+	}
+}
+
+async function durableHandoff(
+	root: string,
+	generation: string,
+	sessionId: string,
+	reason: string,
+	details: Record<string, unknown> = {},
+): Promise<void> {
+	await fs.mkdir(root, { recursive: true, mode: 0o700 });
+	const file = path.join(root, `admission-handoff-${crypto.randomUUID()}.json`);
+	const record = {
+		schema_version: 2,
+		generation,
+		session_id: sessionId,
+		state: "fail_closed_handoff",
+		reason,
+		...details,
+		created_at: new Date().toISOString(),
+	};
+	const handle = await fs.open(file, "wx", 0o600);
+	try {
+		await handle.writeFile(`${JSON.stringify(record)}\n`);
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	const directory = await fs.open(root, "r");
+	try {
+		await directory.sync();
+	} finally {
+		await directory.close();
+	}
+}
+
+/**
+ * This is the pre-CLI barrier. A replacement is identified only by the exact
+ * predecessor token supplied by its launch binding; directory enumeration is
+ * deliberately never an authority source.
+ */
+export async function admitManagedOwnerBeforeCli(): Promise<ManagedOwnerAdmission> {
+	const owner = ownerEnvironment();
+	if (!owner) return { kind: "fresh" };
+	const childToken = process.env[MANAGED_OWNER_CHILD_TOKEN_ENV]?.trim();
+	const predecessorToken = process.env[MANAGED_OWNER_PREDECESSOR_TOKEN_ENV]?.trim();
+	if (childToken && !predecessorToken) {
+		if (!safeChildToken(childToken)) {
+			await durableHandoff(owner.root, owner.generation, owner.sessionId, "exact_child_binding_unavailable");
+			process.exitCode = 75;
+			return { kind: "blocked" };
+		}
+		const [binding] = (await readExactJsons(owner.root, [`child-${childToken}.binding.json`])) ?? [];
+		if (
+			isBinding(binding, {
+				generation: owner.generation,
+				sessionId: owner.sessionId,
+				runId: owner.runId,
+				incarnation: owner.incarnation,
+				token: childToken,
+			})
+		)
+			return { kind: "supervised" };
+		await durableHandoff(owner.root, owner.generation, owner.sessionId, "exact_child_binding_unavailable");
+		process.exitCode = 75;
+		return { kind: "blocked" };
+	}
+	const predecessorGeneration = process.env[MANAGED_OWNER_PREDECESSOR_GENERATION_ENV]?.trim();
+	const predecessorRunId = process.env[MANAGED_OWNER_PREDECESSOR_RUN_ID_ENV]?.trim();
+	const predecessorIncarnation = process.env[MANAGED_OWNER_PREDECESSOR_INCARNATION_ENV]?.trim();
+	if (!predecessorGeneration || !predecessorRunId || !predecessorIncarnation) {
+		await durableHandoff(owner.root, owner.generation, owner.sessionId, "replacement_predecessor_identity_missing");
+		process.exitCode = 75;
+		return { kind: "blocked" };
+	}
+	if (!predecessorToken) {
+		await durableHandoff(owner.root, owner.generation, owner.sessionId, "replacement_predecessor_binding_missing");
+		process.exitCode = 75;
+		return { kind: "blocked" };
+	}
+	if (!safeChildToken(predecessorToken)) {
+		await durableHandoff(owner.root, owner.generation, owner.sessionId, "replacement_predecessor_binding_untrusted");
+		process.exitCode = 75;
+		return { kind: "blocked" };
+	}
+	const [binding, receipt] =
+		(await readExactJsons(owner.root, [
+			`child-${predecessorToken}.binding.json`,
+			`sigabrt-${predecessorToken}.receipt.json`,
+		])) ?? [];
+	if (
+		!isBinding(binding, {
+			generation: predecessorGeneration,
+			sessionId: owner.sessionId,
+			runId: predecessorRunId,
+			incarnation: predecessorIncarnation,
+			token: predecessorToken,
+		})
+	) {
+		await durableHandoff(owner.root, owner.generation, owner.sessionId, "replacement_predecessor_binding_untrusted");
+		process.exitCode = 75;
+		return { kind: "blocked" };
+	}
+	if (!isReceipt(receipt, binding)) {
+		await durableHandoff(owner.root, owner.generation, owner.sessionId, "exact_sigabrt_receipt_untrusted");
+		process.exitCode = 75;
+		return { kind: "blocked" };
+	}
+	const admission = {
+		session_id: owner.sessionId,
+		endpoint_incarnation: predecessorIncarnation,
+		owner_generation: predecessorGeneration,
+		admitted: true,
+	} as const;
+	const decision = await planUltragoalOwnerLossRecovery({
+		binding: {
+			sessionId: owner.sessionId,
+			endpointIncarnation: predecessorIncarnation,
+			ownerGeneration: predecessorGeneration,
+			cwd: process.cwd(),
+		},
+		receipt,
+		admission,
+		transcriptPath: process.env[MANAGED_OWNER_TRANSCRIPT_PATH_ENV] ?? "",
+	});
+	await persistUltragoalRecoveryDecision({
+		cwd: process.cwd(),
+		sessionId: owner.sessionId,
+		binding: {
+			sessionId: owner.sessionId,
+			endpointIncarnation: predecessorIncarnation,
+			ownerGeneration: predecessorGeneration,
+			cwd: process.cwd(),
+		},
+		decision,
+	});
+	if (decision.disposition !== "resume") {
+		await durableHandoff(owner.root, owner.generation, owner.sessionId, decision.reason);
+		process.exitCode = 75;
+		return { kind: "blocked" };
+	}
+	return { kind: "recovery", context: { root: owner.root, binding, receipt, admission, decision } };
+}
+
+/**
+ * The ordinary CLI factory has no recovery-owned writer-lease or exact-child
+ * reconciliation capability.  Do not route a recovered owner through it: first
+ * revalidate the immutable evidence and B0, then publish a terminal handoff.
+ */
+export async function completeManagedOwnerRecovery(
+	context: ManagedOwnerRecoveryContext,
+): Promise<{ kind: "handoff"; exitCode: 75 }> {
+	const recoveryBinding = {
+		sessionId: context.binding.session_id,
+		endpointIncarnation: context.binding.endpoint_incarnation,
+		ownerGeneration: context.binding.generation,
+		cwd: process.cwd(),
+	};
+	const revalidated = await planUltragoalOwnerLossRecovery({
+		binding: recoveryBinding,
+		receipt: context.receipt,
+		admission: context.admission,
+		transcriptPath: process.env[MANAGED_OWNER_TRANSCRIPT_PATH_ENV] ?? "",
+		protectedPaths: context.decision.snapshot?.protectedPaths,
+		sanctionedDeltas: context.decision.snapshot?.sanctionedDeltas,
+		absentArtifacts: context.decision.snapshot?.absentArtifacts,
+		transientHistory: context.decision.snapshot?.transientHistory,
+	});
+	const b0Unchanged =
+		context.decision.snapshot !== undefined &&
+		revalidated.snapshot !== undefined &&
+		context.decision.snapshot.b0.planSha256 === revalidated.snapshot.b0.planSha256 &&
+		context.decision.snapshot.b0.ledgerSha256 === revalidated.snapshot.b0.ledgerSha256;
+	const transcriptUnchanged =
+		context.decision.terminal?.yieldId !== undefined &&
+		revalidated.terminal?.yieldId === context.decision.terminal.yieldId;
+	const reason =
+		revalidated.disposition !== "resume"
+			? `recovery_authority_changed:${revalidated.reason}`
+			: !b0Unchanged
+				? "recovery_b0_changed"
+				: !transcriptUnchanged
+					? "recovery_transcript_changed"
+					: "safe_session_resume_seam_unavailable";
+	const decision: UltragoalRecoveryDecision = { disposition: "handoff", reason };
+	await persistUltragoalRecoveryDecision({
+		cwd: recoveryBinding.cwd,
+		sessionId: recoveryBinding.sessionId,
+		binding: recoveryBinding,
+		decision,
+	});
+	await durableHandoff(context.root, context.binding.generation, context.binding.session_id, reason, {
+		predecessor_child_token: context.binding.child_token,
+		predecessor_run_id: context.binding.run_id,
+		terminal_reconciliation: "unavailable_without_owning_store_cas",
+		b0_preserved: b0Unchanged,
+	});
+	process.exitCode = 75;
+	return { kind: "handoff", exitCode: 75 };
+}

package/src/gjc-runtime/managed-owner-supervisor.ts

@@ -0,0 +1,162 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { readLinuxProcStartTime } from "./linux-proc";
+import { assertSafePathComponent } from "./session-layout";
+import { lifecyclePaths } from "./tmux-owner-isolation";
+
+export const MANAGED_OWNER_SUPERVISOR_ARG = "--internal-managed-owner-supervisor";
+export const MANAGED_OWNER_CHILD_TOKEN_ENV = "GJC_MANAGED_OWNER_CHILD_TOKEN";
+export const MANAGED_OWNER_COMMAND_ENV = "GJC_MANAGED_OWNER_COMMAND_JSON";
+export const MANAGED_OWNER_SESSION_ID_ENV = "GJC_COORDINATOR_SESSION_ID";
+export const MANAGED_OWNER_GENERATION_ENV = "GJC_TMUX_OWNER_GENERATION";
+export const MANAGED_OWNER_STATE_DIR_ENV = "GJC_TMUX_OWNER_STATE_DIR";
+export const MANAGED_OWNER_RUN_ID_ENV = "GJC_MANAGED_OWNER_RUN_ID";
+export const MANAGED_OWNER_INCARNATION_ENV = "GJC_MANAGED_OWNER_INCARNATION";
+
+export interface ManagedOwnerBinding {
+	schema_version: 2;
+	generation: string;
+	session_id: string;
+	run_id: string;
+	endpoint_incarnation: string;
+	child_token: string;
+	command: string[];
+	command_sha256: string;
+	supervisor_pid: number;
+	supervisor_start_time: string;
+	created_at: string;
+}
+
+export interface ManagedOwnerSigabrtReceipt {
+	schema_version: 2;
+	generation: string;
+	session_id: string;
+	run_id: string;
+	endpoint_incarnation: string;
+	child_token: string;
+	command_sha256: string;
+	supervisor_pid: number;
+	supervisor_start_time: string;
+	child_pid: number;
+	child_start_time: string;
+	signal: "SIGABRT";
+	signal_number: 6;
+	exit_code: number | null;
+	received_at: string;
+}
+
+function requiredEnvironment(name: string): string {
+	const value = process.env[name]?.trim();
+	if (!value) throw new Error(`managed_owner_${name.toLowerCase()}_missing`);
+	return value;
+}
+
+function lifecycleRoot(): { root: string; generation: string; sessionId: string; runId: string; incarnation: string } {
+	const stateDir = requiredEnvironment(MANAGED_OWNER_STATE_DIR_ENV);
+	const sessionId = requiredEnvironment(MANAGED_OWNER_SESSION_ID_ENV);
+	const generation = requiredEnvironment(MANAGED_OWNER_GENERATION_ENV);
+	const runId = requiredEnvironment(MANAGED_OWNER_RUN_ID_ENV);
+	const incarnation = requiredEnvironment(MANAGED_OWNER_INCARNATION_ENV);
+	for (const [value, label] of [
+		[sessionId, "managed owner session id"],
+		[generation, "managed owner generation"],
+		[runId, "managed owner run id"],
+		[incarnation, "managed owner incarnation"],
+	] as const)
+		assertSafePathComponent(value, label);
+	if (!path.isAbsolute(stateDir)) throw new Error("managed_owner_lifecycle_path_unsafe");
+	const root = lifecyclePaths(stateDir, sessionId, generation).root;
+	if (!root.startsWith(`${path.resolve(stateDir)}${path.sep}`)) throw new Error("managed_owner_lifecycle_path_unsafe");
+	return { root, generation, sessionId, runId, incarnation };
+}
+
+function commandDigest(command: readonly string[]): string {
+	return crypto.createHash("sha256").update(JSON.stringify(command)).digest("hex");
+}
+
+async function writeDurableExclusive(file: string, value: object): Promise<void> {
+	const handle = await fs.open(file, "wx", 0o600);
+	try {
+		await handle.writeFile(`${JSON.stringify(value)}\n`);
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	const directory = await fs.open(path.dirname(file), "r");
+	try {
+		await directory.sync();
+	} finally {
+		await directory.close();
+	}
+	const persisted = JSON.parse(await fs.readFile(file, "utf8")) as unknown;
+	if (JSON.stringify(persisted) !== JSON.stringify(value)) throw new Error("managed_owner_durable_reread_failed");
+}
+
+function childCommand(): string[] {
+	const command = JSON.parse(requiredEnvironment(MANAGED_OWNER_COMMAND_ENV)) as unknown;
+	if (!Array.isArray(command) || command.length === 0 || command.some(value => typeof value !== "string" || !value))
+		throw new Error("managed_owner_command_invalid");
+	return command;
+}
+
+export function isManagedOwnerSupervisorArgv(args: readonly string[]): boolean {
+	return args.length === 1 && args[0] === MANAGED_OWNER_SUPERVISOR_ARG;
+}
+
+/** Runs one exact child and publishes authority only for a directly observed Linux signal 6. */
+export async function runManagedOwnerSupervisor(): Promise<void> {
+	const { root, generation, sessionId, runId, incarnation } = lifecycleRoot();
+	const command = childCommand();
+	const supervisorStartTime = await readLinuxProcStartTime(process.pid);
+	if (!supervisorStartTime) throw new Error("managed_owner_supervisor_start_time_unavailable");
+	await fs.mkdir(root, { recursive: true, mode: 0o700 });
+	const childToken = crypto.randomUUID();
+	const binding: ManagedOwnerBinding = {
+		schema_version: 2,
+		generation,
+		session_id: sessionId,
+		run_id: runId,
+		endpoint_incarnation: incarnation,
+		child_token: childToken,
+		command,
+		command_sha256: commandDigest(command),
+		supervisor_pid: process.pid,
+		supervisor_start_time: supervisorStartTime,
+		created_at: new Date().toISOString(),
+	};
+	await writeDurableExclusive(path.join(root, `child-${childToken}.binding.json`), binding);
+	const child = Bun.spawn({
+		cmd: command,
+		stdin: "inherit",
+		stdout: "inherit",
+		stderr: "inherit",
+		env: { ...process.env, [MANAGED_OWNER_CHILD_TOKEN_ENV]: childToken },
+	});
+	const childStartTime = await readLinuxProcStartTime(child.pid);
+	if (!childStartTime) throw new Error("managed_owner_child_start_time_unavailable");
+	const exitCode = await child.exited;
+	if (child.signalCode === "SIGABRT") {
+		const receipt: ManagedOwnerSigabrtReceipt = {
+			schema_version: 2,
+			generation,
+			session_id: sessionId,
+			run_id: runId,
+			endpoint_incarnation: incarnation,
+			child_token: childToken,
+			command_sha256: binding.command_sha256,
+			supervisor_pid: process.pid,
+			supervisor_start_time: supervisorStartTime,
+			child_pid: child.pid,
+			child_start_time: childStartTime,
+			signal: "SIGABRT",
+			signal_number: 6,
+			exit_code: exitCode,
+			received_at: new Date().toISOString(),
+		};
+		await writeDurableExclusive(path.join(root, `sigabrt-${childToken}.receipt.json`), receipt);
+		process.exitCode = 134;
+		return;
+	}
+	process.exitCode = exitCode;
+}