@gajae-code/coding-agent 0.15.6 → 0.16.0

package/src/sdk/broker/worktree-occupancy.ts

@@ -0,0 +1,90 @@
+/**
+ * Which session currently holds a GJC-managed worktree.
+ *
+ * Both launch paths need this answer and must not disagree about it: the broker
+ * refuses a lifecycle launch into an occupied worktree, and the interactive
+ * `gjc --worktree` launch refuses for the same reason. Keeping one predicate —
+ * and one definition of "still running" — here prevents the two from drifting
+ * into different notions of liveness.
+ */
+
+import type * as NativeBindings from "@gajae-code/natives";
+import { resolveEquivalentPath } from "@gajae-code/utils";
+import { probeLinuxProcPidSync } from "../../gjc-runtime/linux-proc";
+import { processIncarnation } from "./process-incarnation";
+import type { IndexedSession } from "./session-index";
+
+function nativeLifecycle(): typeof NativeBindings {
+	return require("@gajae-code/natives") as typeof NativeBindings;
+}
+
+export type ProcessObservation = "alive" | "exited" | "uncertain";
+
+/** Only ESRCH or a changed, readable incarnation proves the owned process exited. */
+export function observeProcess(
+	pid: number,
+	expectedIncarnation: string | undefined,
+	readIncarnation: (pid: number) => string | undefined = processIncarnation,
+): ProcessObservation {
+	if (process.platform === "win32") {
+		try {
+			const reference = nativeLifecycle().Process.fromPid(pid);
+			if (reference?.status() !== "running") return "exited";
+		} catch {
+			return "uncertain";
+		}
+		if (!expectedIncarnation) return "uncertain";
+		const actualIncarnation = readIncarnation(pid);
+		if (!actualIncarnation) return "uncertain";
+		return actualIncarnation === expectedIncarnation ? "alive" : "exited";
+	}
+	try {
+		process.kill(pid, 0);
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "ESRCH" ? "exited" : "uncertain";
+	}
+	if (process.platform === "linux") {
+		const probe = probeLinuxProcPidSync(pid);
+		if (probe.kind === "live" && probe.state === "Z" && expectedIncarnation === `linux:${probe.startTime}`)
+			return "exited";
+	}
+	if (!expectedIncarnation) return "uncertain";
+	const actualIncarnation = readIncarnation(pid);
+	if (!actualIncarnation) return "uncertain";
+	return actualIncarnation === expectedIncarnation ? "alive" : "exited";
+}
+
+/**
+ * The id of a session still occupying `worktreePath`, or null when it is free.
+ *
+ * `ensureLaunchWorktree` reuses an existing worktree without asking whether
+ * anyone is in it, and an unnamed launch derives its directory deterministically
+ * from the repository's current branch. Two concurrent sessions in one
+ * repository therefore land in the same checkout and overwrite each other's
+ * files with no error.
+ *
+ * Only a process observed as definitively exited releases the worktree.
+ * `uncertain` counts as occupied: refusing a launch is recoverable by picking
+ * another worktree name, whereas two live sessions sharing a checkout corrupts
+ * work already done.
+ */
+export function worktreeOccupant(
+	sessions: readonly IndexedSession[],
+	worktreePath: string,
+	observe: (pid: number, expectedIncarnation: string | undefined) => ProcessObservation = observeProcess,
+): string | null {
+	// Session locators retain the canonical Git worktree root separately from the
+	// session cwd. A host may start below that root, and a launch plan may arrive
+	// through a symlink, so compare the root identity rather than the cwd spelling.
+	const target = resolveEquivalentPath(worktreePath);
+	for (const session of sessions) {
+		const sessionWorktreeRoot = session.locator.worktreeRoot;
+		if (session.terminal || typeof sessionWorktreeRoot !== "string" || sessionWorktreeRoot.length === 0) continue;
+		if (resolveEquivalentPath(sessionWorktreeRoot) !== target) continue;
+		// `live` is heartbeat-derived and can be stale. Only positive process-exit
+		// evidence releases a matching retained session's worktree.
+		if (observe(session.pid, session.hostIncarnation ?? session.processIncarnation) === "exited") continue;
+		return session.sessionId;
+	}
+	return null;
+}

package/src/sdk/bus/chat-daemon-control.ts

@@ -130,10 +130,13 @@ export type ChatDaemonAction = "stop" | "reload";
  * session-index lock every 2s; staleness retirement moved to a 30s sweep and
  * lease heartbeats no longer force an authority reconcile. A pre-upgrade owner
  * would retain the old hot polling loop, so replacement is required.
+ * Discord generation 72 / Slack generation 75 serialize same-generation
+ * successor attachment admission behind predecessor provider retirement, so a
+ * pre-upgrade owner cannot retain the queue race fixed by #5120.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
-	discord: 71,
-	slack: 74,
+	discord: 72,
+	slack: 75,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {

package/src/sdk/bus/chat-daemon-runtime.ts

@@ -258,6 +258,7 @@ export class ChatDaemonRuntime {
 	readonly #router: SessionRouter;
 	readonly #attachments = new Map<string, SessionAttachment>();
 	readonly #cleanupWork = new Map<string, Promise<void>>();
+	readonly #retirementWork = new Map<string, Promise<void>>();
 	readonly #attachmentBarriers = new Map<string, Promise<void>>();
 	#discord: DiscordNotificationDaemon | undefined;
 	#slack: SlackNotificationDaemon | undefined;
@@ -281,12 +282,18 @@ export class ChatDaemonRuntime {
 	}
 
 	async start(): Promise<void> {
-		if (this.#cleanupWork.size > 0) {
+		if (this.#cleanupWork.size > 0 || this.#retirementWork.size > 0) {
+			const retirements = [...this.#retirementWork.entries()];
 			const settled = await Promise.race([
-				Promise.allSettled([...this.#cleanupWork.values()]).then(() => true),
+				Promise.all([
+					Promise.allSettled([...this.#cleanupWork.values()]),
+					Promise.all(retirements.map(([, retirement]) => retirement)),
+				]).then(() => true),
 				Bun.sleep(5_000).then(() => false),
 			]);
 			if (!settled) throw new Error("Prior provider cleanup did not settle before chat daemon restart.");
+			for (const [sessionId, retirement] of retirements)
+				if (this.#retirementWork.get(sessionId) === retirement) this.#retirementWork.delete(sessionId);
 		}
 		this.#attachments.clear();
 		const retainedProvider =
@@ -428,6 +435,12 @@ export class ChatDaemonRuntime {
 		const discord = this.#discord;
 		const slack = this.#slack;
 		const barrier = (async () => {
+			const retirement = this.#retirementWork.get(attachment.sessionId);
+			if (retirement) {
+				await retirement;
+				if (this.#retirementWork.get(attachment.sessionId) === retirement)
+					this.#retirementWork.delete(attachment.sessionId);
+			}
 			await this.#cleanupWork.get(attachment.sessionId)?.catch(() => undefined);
 			await discord?.recoverCleanup(attachment.sessionId, attachment.generation);
 			await slack?.recoverCleanup(attachment.sessionId, attachment.generation);
@@ -451,13 +464,31 @@ export class ChatDaemonRuntime {
 	): Promise<void> {
 		if (this.#attachments.get(attachment.sessionId) !== attachment) return;
 		if (reason === "replaced_same_generation") {
-			await this.#discord?.retireAttachment(attachment.sessionId, attachment.generation);
-			await this.#slack?.retireAttachment(attachment.sessionId, attachment.generation);
+			const retirement = this.#trackRetirement(attachment);
+			this.#attachments.delete(attachment.sessionId);
+			await retirement;
+			return;
 		}
 		this.#attachments.delete(attachment.sessionId);
 		if (reason === "removed") await this.#trackCleanup(attachment);
 	}
 
+	#trackRetirement(attachment: SessionAttachment): Promise<void> {
+		const sessionId = attachment.sessionId;
+		const discord = this.#discord;
+		const slack = this.#slack;
+		const previous = this.#retirementWork.get(sessionId);
+		const work = (previous ?? Promise.resolve()).then(async () => {
+			// Capture the predecessor providers before stop() can clear the runtime
+			// fields. The successor barrier owns this promise until every retirement
+			// waiter settles, even when takeover overlaps worker shutdown.
+			await discord?.retireAttachment(sessionId, attachment.generation);
+			await slack?.retireAttachment(sessionId, attachment.generation);
+		});
+		this.#retirementWork.set(sessionId, work);
+		return work;
+	}
+
 	async #handleFrame(attachment: SessionAttachment, correlated: CorrelatedFrame): Promise<void> {
 		if (this.#attachments.get(attachment.sessionId) !== attachment) return;
 		await this.#attachmentBarriers.get(attachment.sessionId);

package/src/sdk/bus/index.ts

@@ -90,14 +90,17 @@ import { acpFinalTextFromMessage } from "../acp/final-text";
 import { ensureBroker } from "../broker/ensure";
 import { publishSessionHostRuntimeEvidence, type SessionHostRuntimePublication } from "../broker/lifecycle";
 import { processIncarnation } from "../broker/process-incarnation";
-import { SessionIndex } from "../broker/session-index";
+import { resolveSessionLocator, SessionIndex } from "../broker/session-index";
 import {
 	CAP_GATED_FRAME_KINDS,
 	createSdkSurfaceFactory,
+	masterAttestationForEffectiveHost,
+	reattestMasterSessionIdentity,
 	type SessionSdkHost,
 	SessionSdkSessionRuntime,
 	shouldHostSdk,
 	TOOL_ACTIVITY_CAPABILITY,
+	verifyMasterCapabilityFrame,
 } from "../host";
 import { type AbortScope, type ControlSurface, dispatchControl, TypedControlError } from "../host/control";
 import { BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD } from "../host/control/runtime-gate";
@@ -4043,6 +4046,12 @@ export function createNotificationsExtension(
 		controller?: NotificationSessionController;
 		/** Whether this host mode can own the root SDK endpoint. Default: true. */
 		sdkHostModeSupported?: boolean;
+		/** In-memory master capability for private broker verification only. */
+		masterCapability?: string;
+		/** Opaque direct-role epoch this effective host may adopt. */
+		masterAttestationEpoch?: string;
+		/** Stable master lineage identity retained across session switches/branches. */
+		masterOwnerSessionId?: string;
 		onSdkRequest?: (kind: "control" | "query", connectionId: string, frame: Record<string, unknown>) => void;
 		runBtwTurn?: (question: string, signal: AbortSignal) => Promise<{ replyText: string }>;
 		/** Observes settlement of optional session-branch startup after reconciliation completes. */
@@ -4103,6 +4112,7 @@ export function createNotificationsExtension(
 		  }
 		| undefined;
 	let extensionShuttingDown = false;
+	const consumedMasterNonces = new Map<string, number>();
 
 	async function ensureTelegramOwner(settings: Settings): Promise<"ready" | "blocked_identity"> {
 		if (!telegramTopicsEnabled()) return "blocked_identity";
@@ -4489,12 +4499,14 @@ export function createNotificationsExtension(
 
 	async function startSession(ctx: ExtensionContext): Promise<SessionStartResult> {
 		const id = sessionId(ctx);
-		const lifecycleRequestId = safeLifecycleRequestId(process.env.GJC_LIFECYCLE_REQUEST_ID);
 		const { settings, cfg, settingsAvailable } = resolveSettings(options.settings);
 		const notificationsEnabledForSession = controller.query(ctx).genericSessionEnabled;
 		const sdkEnabledForSession =
 			(options.sdkHostModeSupported ?? true) && shouldHostSdk(settings, isNotificationEligibleContext(ctx));
 		const lifecycleRequired = lifecycleStartupCapability !== undefined;
+		const lifecycleRequestId = lifecycleRequired
+			? safeLifecycleRequestId(lifecycleStartupCapability.lifecycleRequestId)
+			: safeLifecycleRequestId(process.env.GJC_LIFECYCLE_REQUEST_ID);
 		/** The broker-issued readiness intent for this exact lifecycle-managed session. */
 		const lifecycleReadiness = lifecycleStartupCapability?.readiness ?? "immediate";
 		const failLifecycleStartup = (
@@ -6588,6 +6600,7 @@ export function createNotificationsExtension(
 		}
 
 		sdkRuntime = new SessionSdkSessionRuntime({
+			masterOwnerSessionId: options.masterOwnerSessionId,
 			transport: {
 				sessionId: id,
 				stateRoot,
@@ -6607,6 +6620,13 @@ export function createNotificationsExtension(
 			...(activationGate ? { activationGate } : {}),
 			...(settings ? { settings } : {}),
 			...(configOverrides ? { configOverrides } : {}),
+			masterCapabilityVerify: frame =>
+				verifyMasterCapabilityFrame({
+					frame,
+					expectedCapability: options.masterCapability,
+					expectedEpoch: options.masterAttestationEpoch,
+					replay: consumedMasterNonces,
+				}),
 			connectionCapabilities: connectionId => hostCapCache.get(connectionId),
 			installProviderDefinitions,
 			onProviderDefinitionsRemoved: removeProviderDefinitions,
@@ -7751,6 +7771,8 @@ export function createNotificationsExtension(
 			}
 			const agentDir = lifecycleAgentDir ?? settings?.getAgentDir?.();
 			if (lifecycleRequired && !agentDir) throw new Error("Lifecycle SDK host requires an agent directory.");
+			if (lifecycleRequired && !lifecycleRequestId)
+				throw new Error("Lifecycle SDK host requires a capability-bound request identity.");
 
 			if (agentDir) {
 				try {
@@ -7758,13 +7780,36 @@ export function createNotificationsExtension(
 					throwIfLifecycleStopped();
 					const index = await new SessionIndex(agentDir).open();
 					throwIfLifecycleStopped();
-					const locator = { repo: path.resolve(ctx.cwd), stateRoot: endpointStateRoot };
-					const endpointMtimeMs = fs.statSync(path.join(endpointStateRoot, "sdk", `${id}.json`)).mtimeMs;
+					const locator = await resolveSessionLocator(ctx.cwd, endpointStateRoot);
+					const endpointPath = path.join(endpointStateRoot, "sdk", `${id}.json`);
+					const endpointMtimeMs = fs.statSync(endpointPath).mtimeMs;
+					const endpointIdentity = fs.statSync(endpointPath, { bigint: true });
+					const endpointFileId = `${endpointIdentity.dev}:${endpointIdentity.ino}`;
 					const hostProcessIncarnation = processIncarnation(process.pid);
+					const direct = await reattestMasterSessionIdentity({
+						index,
+						locator,
+						masterCapability: options.masterCapability,
+						attestationEpoch: options.masterAttestationEpoch,
+						ownerSessionId: options.masterOwnerSessionId,
+						sessionId: id,
+						pid: process.pid,
+						processIncarnation: hostProcessIncarnation,
+					});
+					throwIfLifecycleStopped();
 					await host.registerWithBroker({
 						// The endpoint is written before registration. Its exact mtime
 						// binds this index generation to that discovery record.
 						register: async input => {
+							const masterRole = masterAttestationForEffectiveHost({
+								masterCapability: options.masterCapability,
+								attestationEpoch: options.masterAttestationEpoch,
+								ownerSessionId: options.masterOwnerSessionId,
+								sessionId: input.sessionId,
+								pid: process.pid,
+								processIncarnation: hostProcessIncarnation,
+								direct,
+							});
 							await index.append({
 								type: "host_registered",
 								...input,
@@ -7776,6 +7821,8 @@ export function createNotificationsExtension(
 								// teardown identity provable after that workspace is gone.
 								...(hostProcessIncarnation ? { processIncarnation: hostProcessIncarnation } : {}),
 								endpointMtimeMs,
+								endpointFileId,
+								...(masterRole ? { masterRole } : {}),
 								...(lifecycleRequestId ? { lifecycleRequestId } : {}),
 							});
 						},

package/src/sdk/bus/telegram-daemon-contract.ts

@@ -291,7 +291,7 @@ export const SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION = 1;
  * killing a session's mirroring after one transient rejection and must be
  * replaced across this upgrade.
  */
-export const DAEMON_GENERATION = 179;
+export const DAEMON_GENERATION = 180;
 
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 7

package/src/sdk/cli/index.ts

@@ -1 +1,2 @@
+export * from "./master-cli";
 export * from "./session-cli";

package/src/sdk/cli/master-cli.ts

@@ -0,0 +1,259 @@
+/**
+ * Local interactive-master CLI surface.
+ *
+ * `gjc sdk spawn` is legal only inside a live master session: the master's Bash
+ * tool threads the transient capability only through a strict direct spawn
+ * command, and the Broker still verifies it against the live effective host
+ * before any effect.
+ * No output path may echo the task or capability.
+ */
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { getAgentDir } from "@gajae-code/utils";
+import { type IndexedSession, isSessionAuthorityEligible, SessionIndex } from "../broker/session-index";
+import { SdkClientError } from "../client";
+import { dispatchSpawnGlobal } from "../lifecycle/broker-client";
+
+const MASTER_CAPABILITY_ENV = "GJC_MASTER_CAPABILITY";
+const MASTER_SESSION_ENV = "GJC_SESSION_ID";
+const SPAWN_TIMEOUT_MS = 120_000;
+
+export class SdkMasterCliError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly exitCode: 1 | 2 = 1,
+	) {
+		super(message);
+		this.name = "SdkMasterCliError";
+	}
+}
+
+export interface SdkSpawnArgs {
+	cwd?: string;
+	prompt?: string;
+	model?: string;
+	profile?: string;
+	agentDir?: string;
+	idempotencyKey?: string;
+	json?: boolean;
+}
+
+/** The allowlisted spawn result projection rendered to the operator. */
+export interface SdkSpawnRendered {
+	code: string;
+	claimId?: string;
+	sessionId?: string;
+	substrateKind?: string;
+	seed?: { phase?: string; clientRef?: string; commandId?: string; turnId?: string; status?: string };
+	idempotencyKey?: string;
+	error?: { code: string; message: string };
+}
+
+export interface SdkSpawnDependencies {
+	env: Record<string, string | undefined>;
+	dispatch: (agentDir: string, input: Record<string, unknown>, idempotencyKey: string) => Promise<unknown>;
+	resolveAttestationEpoch: (agentDir: string, ownerSessionId: string) => Promise<string | undefined>;
+}
+
+async function brokerSpawnDispatch(
+	agentDir: string,
+	input: Record<string, unknown>,
+	idempotencyKey: string,
+): Promise<unknown> {
+	return await dispatchSpawnGlobal(agentDir, input, idempotencyKey, SPAWN_TIMEOUT_MS);
+}
+
+/**
+ * Select the newest retained master attestation for an owner session.
+ *
+ * `listSessionIdentities()` can retain both the direct-role row and one or
+ * more endpoint generations. Its iteration order is a projection detail, not
+ * authority ordering, so selecting the first matching row can resurrect an
+ * older epoch after a master relaunch. The broker's monotonically increasing
+ * `indexSeq` is the authoritative retained ordering.
+ */
+export function selectNewestMasterAttestationEpoch(
+	rows: readonly IndexedSession[],
+	ownerSessionId: string,
+): string | undefined {
+	const processIdentity = (row: IndexedSession): string | undefined => row.hostIncarnation ?? row.processIncarnation;
+	const matchesAttestation = (
+		left: NonNullable<IndexedSession["masterRole"]>,
+		right: NonNullable<IndexedSession["masterRole"]>,
+	) =>
+		left.version === right.version &&
+		left.ownerSessionId === right.ownerSessionId &&
+		left.launchPid === right.launchPid &&
+		left.launchProcessIncarnation === right.launchProcessIncarnation &&
+		left.role === right.role &&
+		left.attestationEpoch === right.attestationEpoch;
+	const hasDirectAttestation = (effective: IndexedSession): boolean =>
+		rows.some(
+			row =>
+				row.sessionId === effective.sessionId &&
+				row.endpointGeneration === 0 &&
+				row.pid === effective.masterRole?.launchPid &&
+				processIdentity(row) === effective.masterRole?.launchProcessIncarnation &&
+				row.masterRole !== undefined &&
+				effective.masterRole !== undefined &&
+				matchesAttestation(row.masterRole, effective.masterRole),
+		);
+	let newest: { indexSeq: number; epoch: string } | undefined;
+	for (const row of rows) {
+		const attestation = row.masterRole;
+		if (
+			!Number.isSafeInteger(row.indexSeq) ||
+			attestation === undefined ||
+			attestation.version !== 2 ||
+			attestation.role !== "master" ||
+			attestation.ownerSessionId !== ownerSessionId ||
+			row.endpointGeneration <= 0 ||
+			row.live !== true ||
+			row.terminal ||
+			row.terminalUncertain ||
+			!isSessionAuthorityEligible(row) ||
+			attestation.launchPid !== row.pid ||
+			attestation.launchProcessIncarnation !== processIdentity(row) ||
+			!hasDirectAttestation(row) ||
+			typeof attestation.attestationEpoch !== "string" ||
+			attestation.attestationEpoch.length === 0 ||
+			attestation.attestationEpoch.length > 512 ||
+			!/^[A-Za-z0-9_-]+$/u.test(attestation.attestationEpoch)
+		)
+			continue;
+		if (newest === undefined || row.indexSeq > newest.indexSeq)
+			newest = { indexSeq: row.indexSeq, epoch: attestation.attestationEpoch };
+	}
+	return newest?.epoch;
+}
+
+async function indexAttestationEpoch(agentDir: string, ownerSessionId: string): Promise<string | undefined> {
+	const index = await new SessionIndex(agentDir).open();
+	return selectNewestMasterAttestationEpoch(index.listSessionIdentities(), ownerSessionId);
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+function opaque(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 && value.length <= 512 ? value : undefined;
+}
+
+/** Projects an arbitrary Broker response onto the allowlisted render shape. */
+export function safeSpawnRender(response: unknown): { rendered: SdkSpawnRendered; exitCode: 0 | 1 } {
+	const outer = record(response);
+	if (outer?.ok === true) {
+		const result = record(outer.result);
+		const seed = record(result?.seed);
+		return {
+			rendered: {
+				code: opaque(result?.code) ?? "spawn_accepted",
+				...(opaque(result?.claimId) === undefined ? {} : { claimId: opaque(result?.claimId) }),
+				...(opaque(result?.sessionId) === undefined ? {} : { sessionId: opaque(result?.sessionId) }),
+				...(opaque(result?.substrateKind) === undefined ? {} : { substrateKind: opaque(result?.substrateKind) }),
+				...(seed === undefined
+					? {}
+					: {
+							seed: {
+								...(opaque(seed.phase) === undefined ? {} : { phase: opaque(seed.phase) }),
+								...(opaque(seed.clientRef) === undefined ? {} : { clientRef: opaque(seed.clientRef) }),
+								...(opaque(seed.commandId) === undefined ? {} : { commandId: opaque(seed.commandId) }),
+								...(opaque(seed.turnId) === undefined ? {} : { turnId: opaque(seed.turnId) }),
+								...(opaque(seed.status) === undefined ? {} : { status: opaque(seed.status) }),
+							},
+						}),
+			},
+			exitCode: 0,
+		};
+	}
+	const error = record(outer?.error);
+	const code = opaque(error?.code) ?? "spawn_failed";
+	const retryIdempotencyKey = code === "uncertain_after_send" ? opaque(error?.idempotencyKey) : undefined;
+	// Error messages are Broker-typed and never quote request input; an uncertain
+	// post-send result may additionally expose its non-secret replay key.
+	const message =
+		typeof error?.message === "string" && error.message.length <= 512 ? error.message : "session.spawn failed";
+	return {
+		rendered: {
+			code,
+			...(retryIdempotencyKey === undefined ? {} : { idempotencyKey: retryIdempotencyKey }),
+			error: { code, message },
+		},
+		exitCode: 1,
+	};
+}
+
+export function renderSpawnTable(rendered: SdkSpawnRendered): string {
+	const lines = [`Result: ${rendered.code}`];
+	if (rendered.claimId) lines.push(`Claim: ${rendered.claimId}`);
+	if (rendered.sessionId) lines.push(`Child session: ${rendered.sessionId}`);
+	if (rendered.substrateKind) lines.push(`Substrate: ${rendered.substrateKind}`);
+	if (rendered.seed?.phase) lines.push(`Seed phase: ${rendered.seed.phase}`);
+	if (rendered.seed?.status) lines.push(`Seed status: ${rendered.seed.status}`);
+	if (rendered.error) lines.push(`Error: ${rendered.error.code}: ${rendered.error.message}`);
+	if (rendered.idempotencyKey) lines.push(`Retry idempotency key: ${rendered.idempotencyKey}`);
+
+	return lines.join("\n");
+}
+
+/**
+ * Runs one local master spawn. A caller-provided idempotency key replays the
+ * matching durable claim; otherwise each invocation receives a fresh key.
+ */
+export async function runSdkSpawn(
+	args: SdkSpawnArgs,
+	dependencies: Partial<SdkSpawnDependencies> = {},
+): Promise<{ rendered: SdkSpawnRendered; exitCode: 0 | 1 }> {
+	const deps: SdkSpawnDependencies = {
+		env: dependencies.env ?? process.env,
+		dispatch: dependencies.dispatch ?? brokerSpawnDispatch,
+		resolveAttestationEpoch: dependencies.resolveAttestationEpoch ?? indexAttestationEpoch,
+	};
+	if (!args.cwd) throw new SdkMasterCliError("invalid_input", "sdk spawn requires --cwd <dir>.", 2);
+	if (!args.prompt) throw new SdkMasterCliError("invalid_input", "sdk spawn requires --prompt <task>.", 2);
+	const capability = deps.env[MASTER_CAPABILITY_ENV];
+	const ownerSessionId = deps.env[MASTER_SESSION_ENV];
+	if (!capability || !ownerSessionId)
+		throw new SdkMasterCliError(
+			"master_context_required",
+			"sdk spawn is available only inside a live interactive master session.",
+			1,
+		);
+	const agentDir = args.agentDir ?? getAgentDir();
+	const attestationEpoch = await deps.resolveAttestationEpoch(agentDir, ownerSessionId);
+	if (!attestationEpoch)
+		throw new SdkMasterCliError(
+			"master_context_required",
+			"No master role attestation exists for this session; relaunch with gjc --master.",
+			1,
+		);
+	const idempotencyKey = args.idempotencyKey ?? randomUUID();
+	try {
+		const response = await deps.dispatch(
+			agentDir,
+			{
+				task: args.prompt,
+				masterCapability: capability,
+				ownerSessionId,
+				attestationEpoch,
+				cwd: args.cwd === undefined ? undefined : path.resolve(args.cwd),
+				...(args.model === undefined ? {} : { modelId: args.model }),
+				...(args.profile === undefined ? {} : { modelPreset: args.profile }),
+			},
+			idempotencyKey,
+		);
+		return safeSpawnRender(response);
+	} catch (error) {
+		if (error instanceof SdkClientError && error.code === "uncertain_after_send") {
+			return safeSpawnRender({
+				ok: false,
+				error: { code: error.code, message: error.message, idempotencyKey },
+			});
+		}
+		throw error;
+	}
+}

package/src/sdk/cli/rows.ts

@@ -1,5 +1,5 @@
 /**
- * Versioned DTO rows for `gjc sdk session` semantic verbs (row DTO v1, DR-12).
+ * Versioned DTO rows for `gjc sdk session` semantic verbs (row DTO v2, DR-12).
  *
  * Every semantic verb renders its output through these rows so machine
  * consumers get one deterministic, versioned envelope per verb. Credentials
@@ -8,7 +8,7 @@
  * rendering.
  */
 
-export const SESSION_ROWS_VERSION = 1;
+export const SESSION_ROWS_VERSION = 2;
 
 export type SdkSessionActivityState = "active" | "idle";
 
@@ -19,7 +19,7 @@ export interface SdkSessionActivityV1 {
 
 export interface SdkSessionRowV1 {
 	sessionId: string;
-	locator: { repo: string; stateRoot: string };
+	locator: { cwd: string; worktreeRoot: string | null; stateRoot: string };
 	endpointGeneration: number;
 	/** Process-bound incarnation of the hosting process (C1); absent for legacy-provenance rows. */
 	hostIncarnation?: string;
@@ -98,12 +98,15 @@ function optionalFiniteNumber(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
-function locatorOf(row: Record<string, unknown>): { repo: string; stateRoot: string } {
+function locatorOf(row: Record<string, unknown>): { cwd: string; worktreeRoot: string | null; stateRoot: string } {
 	const locator = isRecord(row.locator) ? row.locator : {};
-	return {
-		repo: optionalString(locator.repo) ?? "unknown",
-		stateRoot: optionalString(locator.stateRoot) ?? "unknown",
-	};
+	const cwd = optionalString(locator.cwd);
+	const stateRoot = optionalString(locator.stateRoot);
+	const worktreeRoot = locator.worktreeRoot;
+	if (!cwd || !stateRoot || (worktreeRoot !== null && optionalString(worktreeRoot) === undefined)) {
+		throw new Error("session row has an invalid locator v2");
+	}
+	return { cwd, worktreeRoot: worktreeRoot === null ? null : optionalString(worktreeRoot)!, stateRoot };
 }
 
 function activityOf(row: Record<string, unknown>): SdkSessionActivityV1 | undefined {