@gajae-code/coding-agent 0.18.7 → 0.18.9

package/src/sdk/broker/broker-exit.ts

@@ -22,6 +22,7 @@ export type BrokerFenceReason = "suspect-unpublished" | "observation-ambiguous"
 export type BrokerExitReason =
 	| "ownership-fence-expired"
 	| "publication-liveness-timeout"
+	| "heartbeat-renewal-blocked"
 	| "restart-committed"
 	| "shutdown-request"
 	| "startup-failure"
@@ -39,6 +40,8 @@ export interface BrokerExitRecord {
 	fenceReason: BrokerFenceReason | null;
 	fencedForMs: number;
 	uptimeMs: number;
+	/** For a blocked heartbeat renewal: retained removal transition path. */
+	blockingLockPath?: string;
 	pid: number;
 	signal: "SIGINT" | "SIGTERM" | null;
 	writtenAt: number;
@@ -47,7 +50,7 @@ export interface BrokerExitRecord {
 export interface BrokerStartupExitRecord {
 	version: 1;
 	mode: "startup";
-	reason: "startup-deadline" | "startup-signal";
+	reason: "startup-deadline" | "startup-signal" | "startup-lock-blocked";
 	fenceReason: null;
 	fencedForMs: 0;
 	uptimeMs: number;
@@ -56,6 +59,8 @@ export interface BrokerStartupExitRecord {
 	exitCode: 1 | 130 | 143;
 	timeoutMs: number | null;
 	writtenAt: number;
+	/** For lock-blocked reason: path to the retained removal transition. */
+	blockingLockPath?: string;
 }
 
 export type BrokerStartupExitWriteStatus =
@@ -71,6 +76,7 @@ const lastWriteGenerationByPath = new Map<string, number>();
 const EXIT_REASONS = new Set<BrokerExitReason>([
 	"ownership-fence-expired",
 	"publication-liveness-timeout",
+	"heartbeat-renewal-blocked",
 	"restart-committed",
 	"shutdown-request",
 	"startup-failure",
@@ -94,11 +100,20 @@ function isBrokerExitRecord(value: unknown): value is BrokerExitRecord {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
 	const record = value as Partial<BrokerExitRecord>;
 	const keys = Object.keys(record).sort();
+	const requiredKeys = [
+		"fenceReason",
+		"fencedForMs",
+		"mode",
+		"pid",
+		"reason",
+		"signal",
+		"uptimeMs",
+		"version",
+		"writtenAt",
+	];
 	return (
-		keys.join(",") ===
-			["fenceReason", "fencedForMs", "mode", "pid", "reason", "signal", "uptimeMs", "version", "writtenAt"]
-				.sort()
-				.join(",") &&
+		keys.every(key => requiredKeys.includes(key) || key === "blockingLockPath") &&
+		requiredKeys.every(key => keys.includes(key)) &&
 		record.version === 1 &&
 		(record.mode === "owned-root" || record.mode === "lost-root") &&
 		typeof record.reason === "string" &&
@@ -115,6 +130,14 @@ function isBrokerExitRecord(value: unknown): value is BrokerExitRecord {
 		(record.pid as number) > 0 &&
 		(record.signal === null || record.signal === "SIGINT" || record.signal === "SIGTERM") &&
 		(record.reason === "signal") === (record.signal !== null) &&
+		(record.reason === "heartbeat-renewal-blocked"
+			? record.mode === "owned-root" &&
+				record.fenceReason === null &&
+				record.fencedForMs === 0 &&
+				record.signal === null &&
+				typeof record.blockingLockPath === "string" &&
+				record.blockingLockPath.length > 0
+			: record.blockingLockPath === undefined) &&
 		Number.isSafeInteger(record.writtenAt) &&
 		(record.writtenAt as number) > 0
 	);
@@ -125,26 +148,29 @@ function isBrokerStartupExitRecord(value: unknown): value is BrokerStartupExitRe
 	const record = value as Partial<BrokerStartupExitRecord>;
 	const signalExitCode = record.signal === "SIGINT" ? 130 : record.signal === "SIGTERM" ? 143 : null;
 	const keys = Object.keys(record).sort();
+	const requiredKeys = [
+		"exitCode",
+		"fenceReason",
+		"fencedForMs",
+		"mode",
+		"pid",
+		"reason",
+		"signal",
+		"timeoutMs",
+		"uptimeMs",
+		"version",
+		"writtenAt",
+	];
+	const isValidShape =
+		keys.every(k => requiredKeys.includes(k) || k === "blockingLockPath") &&
+		requiredKeys.every(k => keys.includes(k));
 	return (
-		keys.join(",") ===
-			[
-				"exitCode",
-				"fenceReason",
-				"fencedForMs",
-				"mode",
-				"pid",
-				"reason",
-				"signal",
-				"timeoutMs",
-				"uptimeMs",
-				"version",
-				"writtenAt",
-			]
-				.sort()
-				.join(",") &&
+		isValidShape &&
 		record.version === 1 &&
 		record.mode === "startup" &&
-		(record.reason === "startup-deadline" || record.reason === "startup-signal") &&
+		(record.reason === "startup-deadline" ||
+			record.reason === "startup-signal" ||
+			record.reason === "startup-lock-blocked") &&
 		record.fenceReason === null &&
 		record.fencedForMs === 0 &&
 		Number.isSafeInteger(record.uptimeMs) &&
@@ -154,7 +180,10 @@ function isBrokerStartupExitRecord(value: unknown): value is BrokerStartupExitRe
 		(record.signal === null || record.signal === "SIGINT" || record.signal === "SIGTERM") &&
 		(record.exitCode === 1 || record.exitCode === 130 || record.exitCode === 143) &&
 		(record.timeoutMs === null || (Number.isSafeInteger(record.timeoutMs) && (record.timeoutMs as number) > 0)) &&
-		(record.reason === "startup-deadline"
+		(record.reason === "startup-lock-blocked"
+			? typeof record.blockingLockPath === "string" && record.blockingLockPath.length > 0
+			: record.blockingLockPath === undefined) &&
+		(record.reason === "startup-deadline" || record.reason === "startup-lock-blocked"
 			? record.exitCode === 1 && record.signal === null && record.timeoutMs !== null
 			: record.exitCode === signalExitCode && signalExitCode !== null && record.timeoutMs === null) &&
 		Number.isSafeInteger(record.writtenAt) &&

package/src/sdk/broker/broker.ts

@@ -6,9 +6,14 @@ import path from "node:path";
 import type { NativeBrokerRestartIntent, NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
 import { logger, resolveEquivalentPath } from "@gajae-code/utils";
 import packageJson from "../../../package.json" with { type: "json" };
+import { FileLockAcquireError } from "../../config/file-lock";
 import type { ModelProfileErrorDetails } from "../../config/model-profile-contract";
 import { planLaunchWorktree } from "../../gjc-runtime/launch-worktree";
 import { readExistingStateForMutation, withWorkflowStateLock } from "../../gjc-runtime/state-writer";
+import type {
+	TaskArtifactOwnerDeletionEvidence,
+	TaskArtifactOwnerRetirementContinuation,
+} from "../../session/task-artifact-owner-codec";
 import { SdkClient, SdkClientError } from "../client";
 import {
 	BROKER_RUNTIME_ABORT_CAPABILITY_FIELD,
@@ -127,6 +132,7 @@ import {
 	type SpawnSubstrateProvider,
 } from "./spawn-authority";
 import { createSpawnSubstrateProvider } from "./spawn-substrate";
+import type { BrokerTaskArtifactOwnerRetirementDisposition } from "./task-artifact-owner-validation";
 import { BrokerTransport } from "./transport";
 
 export interface BrokerSettings {
@@ -158,6 +164,8 @@ export interface BrokerSettings {
 	restartRequestId?: string;
 	/** Cancel bootstrap before retained publication when the owning CLI receives a signal. */
 	startupAbortSignal?: AbortSignal;
+	/** Monotonic checkpoint deadline, leaving time for retained publication. */
+	startupCheckpointDeadline?: number;
 	/** Called synchronously when retained publication establishes broker readiness. */
 	onStartupReady?: () => void;
 	/** Test-only delay after session checkpoint to verify unpublished discovery ownership. */
@@ -293,6 +301,19 @@ export type BrokerCleanupEvidence = {
 	retainedTranscriptSuccessorPath?: string;
 	retainedTranscriptPlaceholderPath?: string;
 	retainedTranscriptUnknownPath?: string;
+	/** Immutable task-artifact owner authority captured before the first deletion effect. */
+	taskArtifactOwnerDeletionEvidence?: TaskArtifactOwnerDeletionEvidence;
+	/** Latest exact native remnant; it never replaces the original deletion evidence. */
+	taskArtifactOwnerRetirementContinuation?: TaskArtifactOwnerRetirementContinuation;
+	/** Strict owner-only wire disposition, decoded only with its separately stored evidence. */
+	taskArtifactOwnerRetirementOutcome?: BrokerTaskArtifactOwnerRetirementDisposition;
+	taskArtifactOwnerPayloadRetired?: true;
+	taskArtifactOwnerNamespaceRetained?: true;
+	taskArtifactOwnerRetired?: true;
+	/** Durable fact that transcript retirement completed while the owner namespace remains. */
+	taskArtifactOwnerTranscriptDeleted?: true;
+	/** Stable artifacts-phase owner refusal diagnostic. */
+	taskArtifactOwnerCleanupError?: string;
 	/** Durable proof that artifact cleanup completed before transcript mutation. */
 	artifactsRemoved?: boolean;
 	artifactsAbsentAtAuthorization?: true;
@@ -756,6 +777,17 @@ function normalizeAliasedString(
 	return { value: values[0] };
 }
 
+const BROKER_TASK_ARTIFACT_OWNER_CLEANUP_FIELDS = [
+	"taskArtifactOwnerDeletionEvidence",
+	"taskArtifactOwnerRetirementContinuation",
+	"taskArtifactOwnerRetirementOutcome",
+	"taskArtifactOwnerPayloadRetired",
+	"taskArtifactOwnerNamespaceRetained",
+	"taskArtifactOwnerRetired",
+	"taskArtifactOwnerTranscriptDeleted",
+	"taskArtifactOwnerCleanupError",
+] as const;
+
 export function normalizeBrokerInput(operation: string, input: Record<string, unknown>): InputNormalization {
 	const normalized: Record<string, unknown> = { ...input };
 	const session = normalizeAliasedString(input, "sessionId", ["id"]);
@@ -834,6 +866,18 @@ export function normalizeBrokerInput(operation: string, input: Record<string, un
 	if (cwd.value !== undefined) normalized.stateRoot = path.join(cwd.value, ".gjc", "state");
 	else if (stateRoot.value !== undefined) return error("invalid_input", "stateRoot requires cwd.");
 
+	if (operation === "session.delete") {
+		const hasOwnerField = (value: unknown): boolean =>
+			typeof value === "object" &&
+			value !== null &&
+			!Array.isArray(value) &&
+			BROKER_TASK_ARTIFACT_OWNER_CLEANUP_FIELDS.some(key => Object.hasOwn(value, key));
+		if (hasOwnerField(input) || hasOwnerField(target) || hasOwnerField(input.cleanup))
+			return error(
+				"invalid_input",
+				"Task-artifact owner cleanup state is broker-managed and cannot be supplied by clients.",
+			);
+	}
 	if (target) {
 		const normalizedTarget = { ...target };
 		delete normalizedTarget.path;
@@ -1530,12 +1574,14 @@ export class Broker {
 	#transport: BrokerTransport | null = null;
 	#heartbeatTimer: NodeJS.Timeout | null = null;
 	#startupAbortSignal: AbortSignal | undefined;
+	#startupCheckpointDeadline: number | undefined;
 	#onStartupReady: (() => void) | undefined;
 	#startupPrePublicationDelayMs: number;
 	#startupPrePublicationTestHook: (() => Promise<void>) | undefined;
 	#startupAfterDiscoveryWriteTestHook: (() => Promise<void>) | undefined;
 	#startupPostPublicationDelayMs: number;
 	#completionTask: Promise<void> | null = null;
+	#terminalExit: { mode: BrokerExitMode; reason: BrokerExitReason } | null = null;
 	#completion!: Promise<void>;
 	#resolveCompletion!: () => void;
 	#rejectCompletion!: (error: unknown) => void;
@@ -1569,6 +1615,7 @@ export class Broker {
 		this.#ownsResolveModelPin = settings.resolveModelPin === undefined;
 		this.#resolveModelPin = settings.resolveModelPin ?? createDefaultSdkHostModelResolver(this.settings.agentDir);
 		this.#startupAbortSignal = settings.startupAbortSignal;
+		this.#startupCheckpointDeadline = settings.startupCheckpointDeadline;
 		this.#onStartupReady = settings.onStartupReady;
 		this.#startupPrePublicationDelayMs =
 			Number.isSafeInteger(settings.startupPrePublicationDelayMs) &&
@@ -3898,7 +3945,7 @@ export class Broker {
 			// checkpoint settles. The bootstrap watchdog owns this pre-publication
 			// interval; publishing first allowed it to kill an endpoint already handed
 			// to callers when a legitimate index-lock wait outlived the fence.
-			await this.#checkpointSessionHeartbeats();
+			await this.#checkpointSessionHeartbeats(this.#startupAbortSignal, this.#startupCheckpointDeadline);
 			this.#throwIfStartupAborted();
 			await this.#startupPrePublicationTestHook?.();
 			if (this.#startupPrePublicationDelayMs > 0) await Bun.sleep(this.#startupPrePublicationDelayMs);
@@ -3973,6 +4020,10 @@ export class Broker {
 	get completion(): Promise<void> {
 		return this.#completion;
 	}
+	/** Why this broker completed, or null while it is still running. */
+	get terminalExit(): { readonly mode: BrokerExitMode; readonly reason: BrokerExitReason } | null {
+		return this.#terminalExit;
+	}
 	#restartIdentity(): BrokerRestartOwnerIdentity | undefined {
 		const d = this.discovery;
 		if (!d?.incarnation) return undefined;
@@ -4231,15 +4282,29 @@ export class Broker {
 		if (publication) await this.#writeHeartbeat(publication);
 	}
 	/** Re-observes provably live session hosts and checkpoints their liveness. */
-	async heartbeatSessions(now = Date.now()): Promise<number> {
-		return await this.index.checkpointLiveHeartbeats(now);
+	async heartbeatSessions(now = Date.now(), abortSignal?: AbortSignal, deadlineAt?: number): Promise<number> {
+		return await this.index.checkpointLiveHeartbeats(now, abortSignal, deadlineAt);
 	}
-	async #checkpointSessionHeartbeats(): Promise<void> {
+	async #checkpointSessionHeartbeats(abortSignal?: AbortSignal, startupCheckpointDeadline?: number): Promise<void> {
 		if (this.#checkpointInFlight || this.#stopping) return;
 		this.#checkpointInFlight = true;
 		try {
-			await this.heartbeatSessions();
+			// The CLI reserves publication headroom in this startup deadline.
+			// Periodic passes use their own budget, not a retired startup signal.
+			await this.heartbeatSessions(Date.now(), abortSignal, startupCheckpointDeadline);
 		} catch (error) {
+			if (
+				error instanceof FileLockAcquireError &&
+				error.orphanPath &&
+				this.#publication !== null &&
+				this.#publicationState === "healthy-owned" &&
+				this.#fenceReason === null &&
+				this.#completionTask === null &&
+				this.#provenOwnedRoot()
+			) {
+				await this.#complete("owned-root", "heartbeat-renewal-blocked", null, error.orphanPath);
+				return;
+			}
 			logger.warn(`sdk broker: session heartbeat checkpoint failed: ${String(error)}`);
 		} finally {
 			this.#checkpointInFlight = false;
@@ -4249,8 +4314,10 @@ export class Broker {
 		mode: BrokerExitMode,
 		reason: BrokerExitReason,
 		signal: BrokerExitRecord["signal"] = null,
+		blockingLockPath?: string,
 	): Promise<void> {
 		if (this.#completionTask) return this.#completionTask;
+		this.#terminalExit = { mode, reason };
 		const now = process.hrtime.bigint();
 		const fenceStartedAt = this.#lossAt ?? this.#ambiguousAt;
 		const exitRecord: BrokerExitRecord & Record<string, unknown> = {
@@ -4260,11 +4327,19 @@ export class Broker {
 			fenceReason: this.#fenceReason,
 			fencedForMs: fenceStartedAt === null ? 0 : Math.max(0, Number((now - fenceStartedAt) / 1_000_000n)),
 			uptimeMs: this.#startedAt === null ? 0 : Math.max(0, Number((now - this.#startedAt) / 1_000_000n)),
+			...(blockingLockPath === undefined ? {} : { blockingLockPath }),
 			pid: process.pid,
 			signal,
 			writtenAt: Date.now(),
 		};
-		(mode === "lost-root" ? logger.warn : logger.info)("sdk broker: exiting", exitRecord);
+		const message =
+			reason === "heartbeat-renewal-blocked" && blockingLockPath
+				? `blocked by retained removal transition ${blockingLockPath}`
+				: undefined;
+		(mode === "lost-root" || message !== undefined ? logger.warn : logger.info)("sdk broker: exiting", {
+			...exitRecord,
+			...(message === undefined ? {} : { message }),
+		});
 		this.#stopping = true;
 		this.#checkpointInFlight = false;
 		this.#publicationState = "stopping";

package/src/sdk/broker/doctor-restart.ts

@@ -9,6 +9,7 @@ import type {
 } from "./broker";
 import { launchAuthorizedBrokerSuccessor, oldOwnerConfirmedExited } from "./daemon-entry";
 import { type BrokerDiscovery, readBrokerDiscovery } from "./discovery";
+import { isBrokerAttachOnly } from "./ensure";
 
 export interface DoctorBrokerRestartOptions {
 	agentDir: string;
@@ -33,6 +34,8 @@ export type DoctorBrokerRestartOutcome =
 			adopted: boolean;
 	  }
 	| { kind: "owner_unavailable"; reason: "no_discovery" | "owner_not_confirmed_live" }
+	/** Attach-only mode: the broker belongs to an external supervisor, so restart through it. */
+	| { kind: "attach_only_refused"; reason: "supervisor_owned" }
 	| { kind: "prepare_refused"; code: string; message: string }
 	| { kind: "commit_refused"; code: string; message: string }
 	| { kind: "old_owner_exit_timeout"; requestId: string; oldOwner: BrokerRestartOwnerIdentity }
@@ -163,6 +166,7 @@ const OLD_OWNER_EXIT_POLL_MS = 50;
  * proven it owns the root -- never here, and never before that proof exists.
  */
 export async function restartBrokerForDoctor(options: DoctorBrokerRestartOptions): Promise<DoctorBrokerRestartOutcome> {
+	if (isBrokerAttachOnly()) return { kind: "attach_only_refused", reason: "supervisor_owned" };
 	const old = await readBrokerDiscovery(options.agentDir);
 	if (!old) return { kind: "owner_unavailable", reason: "no_discovery" };
 	const oldOwner = identity(old);

package/src/sdk/broker/ensure.ts

@@ -6,7 +6,7 @@ import path from "node:path";
 import packageJson from "../../../package.json" with { type: "json" };
 import { acquireFileLock, type FileLockOptions, withFileLock } from "../../config/file-lock";
 import { loadInstallationHostId, loadLegacyInstallationHostId } from "../../config/machine-identity";
-import { SdkClient } from "../client/client";
+import { SdkClient, SdkClientError } from "../client/client";
 import { type BrokerStartupExitRecord, clearBrokerStartupExitRecord, readBrokerStartupExitRecord } from "./broker-exit";
 import {
 	type BrokerDiscovery,
@@ -41,6 +41,8 @@ function brokerStartupFailureReason(marker: BrokerStartupFailureMarker | undefin
 
 function brokerStartupExitReason(record: BrokerStartupExitRecord | undefined): string | undefined {
 	if (!record) return undefined;
+	if (record.reason === "startup-lock-blocked")
+		return `SDK broker startup blocked by retained removal transition ${record.blockingLockPath}.`;
 	if (record.reason === "startup-deadline")
 		return `SDK broker startup exceeded its ${record.timeoutMs}ms fence deadline.`;
 	return `SDK broker startup interrupted by ${record.signal} before readiness.`;
@@ -1001,9 +1003,36 @@ function startEnsure(settings: EnsureBrokerSettings, initiator: EnsureInitiator)
 	return entry;
 }
 
-/** Starts the detached broker entrypoint when discovery has no live owner. */
+/**
+ * Attach-only client mode. When `GJC_SDK_BROKER_AUTOSTART=0`, `ensureBroker`
+ * never spawns, retires or restarts a broker: it returns a live, reusable
+ * discovery or fails with `broker_unavailable`. Hosts that supervise their own
+ * broker (for example a system service) set it for every client they run. The
+ * broker entrypoints never call `ensureBroker`, so they ignore the variable and
+ * their descendants may inherit it.
+ */
+export const SDK_BROKER_AUTOSTART_ENV = "GJC_SDK_BROKER_AUTOSTART";
+
+export function isBrokerAttachOnly(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env[SDK_BROKER_AUTOSTART_ENV] === "0";
+}
+
+async function attachExistingBroker(settings: EnsureBrokerSettings): Promise<BrokerDiscovery> {
+	const discovery = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+	if (discovery && (await isBrokerReusable(discovery))) return discovery;
+	throw new SdkClientError(
+		"broker_unavailable",
+		`SDK broker is not running and ${SDK_BROKER_AUTOSTART_ENV}=0 forbids starting one.`,
+	);
+}
+
+/**
+ * Starts the detached broker entrypoint when discovery has no live owner. In
+ * attach-only mode (`SDK_BROKER_AUTOSTART_ENV`) it only attaches.
+ */
 export function ensureBroker(settings: EnsureBrokerSettings): Promise<BrokerDiscovery> {
 	const resolvedSettings = { ...settings, agentDir: path.resolve(settings.agentDir) };
+	if (isBrokerAttachOnly()) return attachExistingBroker(resolvedSettings);
 	const inFlight = ensureInFlight.get(resolvedSettings.agentDir) ?? startEnsure(resolvedSettings, "discovery");
 	return inFlight.discovery;
 }