@gajae-code/coding-agent 0.11.1 → 0.11.3

package/src/commands/harness.ts

@@ -25,16 +25,25 @@ import {
 	classifyCgroup,
 	isExactScopedBootstrapSuccessReceipt,
 	isOwnerGenerationBaselineCurrentSync,
+	isSafeServerProof,
 	type OwnerGenerationBaseline,
 	type OwnerIsolationProbe,
 	observeOwnerTerminal,
 	ownerProcessStartTime,
 	planTmuxOwnerIsolation,
 	replaceOwnerGenerationSync,
+	sameServerIdentity,
 	type TmuxServerProof,
 } from "../gjc-runtime/tmux-owner-isolation";
 import { classifyRecovery } from "../harness-control-plane/classifier";
 import { callEndpoint, EndpointUnreachableError } from "../harness-control-plane/control-endpoint";
+import {
+	type CompletedTerminalEvent,
+	isOwnerLivenessBlocker,
+	needsVanishedOwnerBlock,
+	OWNER_STARTUP_BLOCKER,
+	reconcileOwnerLifecycle,
+} from "../harness-control-plane/lifecycle-reconciliation";
 import { type ResolvedOwner, RuntimeOwner, resolveOwner, resolveOwnerLive } from "../harness-control-plane/owner";
 import { preserveDirtyWorktree } from "../harness-control-plane/preserve";
 import { RECEIPT_SPOOL_DIR_ENV } from "../harness-control-plane/receipt-spool";
@@ -252,12 +261,6 @@ function pushUnique(out: string[], value: unknown): void {
 	if (typeof value === "string" && !out.includes(value)) out.push(value);
 }
 
-interface CompletedTerminalEvent {
-	cursor: number;
-	createdAt: string;
-	kind: string;
-}
-
 function completedTerminalEvent(events: EventEnvelope[]): CompletedTerminalEvent | null {
 	for (const event of [...events].reverse()) {
 		const signal = (event.evidence as { signal?: unknown } | undefined)?.signal;
@@ -461,73 +464,21 @@ function updateStateWithRestoredOwner(state: SessionState, leasePath: string, re
 	state.updatedAt = nowIso();
 }
 
-function isOwnerLivenessBlocker(blocker: string): boolean {
-	return blocker === "detached-owner-not-live" || blocker.startsWith("owner-vanished:");
-}
-
-async function reconcileCompletedOwnerExited(
+async function reconcileLifecycle(
 	root: string,
 	state: SessionState,
 	observation: Observation,
 	completedTerminal: CompletedTerminalEvent | null,
+	startupBlocked = false,
 ): Promise<SessionState> {
-	if (!completedTerminal || observation.ownerLive || observation.gitDelta !== "clean") return state;
-	if (state.lifecycle === "completed" || state.lifecycle === "retired") return state;
-	state.lifecycle = "completed";
-	state.blockers = state.blockers.filter(blocker => !isOwnerLivenessBlocker(blocker));
-	state.updatedAt = nowIso();
-	await writeSessionState(root, state);
-	return state;
-}
-
-function needsVanishedOwnerBlock(
-	state: SessionState,
-	observation: Observation,
-	completedTerminal: CompletedTerminalEvent | null,
-): boolean {
-	if (observation.ownerLive || state.lifecycle !== "observing") return false;
-	if (completedTerminal || observation.observedSignals.includes("completed")) return false;
-	return observation.observedSignals.some(
-		signal => signal === "prompt-accepted" || signal === "tool-call" || signal === "streaming",
-	);
-}
-
-async function markVanishedOwnerBlocked(
-	root: string,
-	state: SessionState,
-	observation: Observation,
-	completedTerminal: CompletedTerminalEvent | null,
-): Promise<SessionState> {
-	if (!needsVanishedOwnerBlock(state, observation, completedTerminal)) return state;
-	const blocker = `owner-vanished:${observation.gitDelta}`;
-	state.lifecycle = "blocked";
-	state.blockers = state.blockers.includes(blocker) ? state.blockers : [...state.blockers, blocker];
-	state.updatedAt = nowIso();
-	await writeSessionState(root, state);
-	return state;
-}
-
-const OWNER_STARTUP_BLOCKER = "owner-died-before-first-prompt";
-
-/**
- * Persist an explicit startup blocker when an owner started, reported live, but died before
- * accepting the first prompt. This makes the failure an actionable lifecycle state instead of a
- * silent `owner-not-live` gate, so observe/recover surface it and recover can respawn the owner.
- */
-async function markStartupOwnerBlocked(
-	root: string,
-	state: SessionState,
-	ownerExit: OwnerExitEvidence,
-): Promise<SessionState> {
-	if (!ownerExit.startupBlocker) return state;
-	if (state.lifecycle === "completed" || state.lifecycle === "retired") return state;
-	state.lifecycle = "blocked";
-	state.blockers = state.blockers.includes(OWNER_STARTUP_BLOCKER)
-		? state.blockers
-		: [...state.blockers, OWNER_STARTUP_BLOCKER];
-	state.updatedAt = nowIso();
-	await writeSessionState(root, state);
-	return state;
+	return reconcileOwnerLifecycle({
+		state,
+		observation,
+		completedTerminal,
+		startupBlocked,
+		persist: async nextState => writeSessionState(root, nextState),
+		nowIso,
+	});
 }
 
 function resolveRetryBudget(input: Record<string, unknown>): RetryBudget {
@@ -562,29 +513,6 @@ function isBoundedNoServerDiagnostic(stderr: Uint8Array): boolean {
 	);
 }
 
-function sameServerIdentity(left: TmuxServerProof, right: TmuxServerProof): boolean {
-	return (
-		left.pid === right.pid &&
-		left.startTime === right.startTime &&
-		left.cgroup?.classification === right.cgroup?.classification &&
-		left.cgroup?.scope === right.cgroup?.scope &&
-		left.cgroup?.diagnostic === right.cgroup?.diagnostic
-	);
-}
-
-function isSafeServerProof(proof: TmuxServerProof): boolean {
-	return (
-		proof.state === "safe" &&
-		typeof proof.pid === "number" &&
-		Number.isSafeInteger(proof.pid) &&
-		proof.pid > 0 &&
-		typeof proof.startTime === "string" &&
-		proof.startTime.length > 0 &&
-		(proof.cgroup?.classification === "safe" ||
-			(process.platform !== "linux" && proof.cgroup?.classification === "not_applicable"))
-	);
-}
-
 function exactNativeTmuxSessionId(stdout: Uint8Array): string | null {
 	const value = new TextDecoder().decode(stdout);
 	const line = value.endsWith("\n") ? value.slice(0, -1) : value;
@@ -985,7 +913,9 @@ export default class Harness extends Command {
 		proof: TmuxServerProof | null,
 		probeServer: OwnerIsolationProbe["probeServer"],
 	): Promise<void> {
-		if (!nativeSessionId || !proof || !isSafeServerProof(proof)) throw new Error("tmux-owner-cleanup_uncertain");
+		if (!nativeSessionId || !proof || !isSafeServerProof(proof, ownerIsolationPlatform()))
+			throw new Error("tmux-owner-cleanup_uncertain");
+
 		if (!(await this.#nativeSessionBoundToName(tmuxCommand, socketKey, nativeSessionId, sessionName)))
 			throw new Error("tmux-owner-cleanup_uncertain");
 		const current = await probeServer(socketKey, [tmuxCommand, "-L", socketKey]);
@@ -1141,7 +1071,7 @@ export default class Harness extends Command {
 		const postSpawnServer = await probeServer(socketKey, [tmuxCommand, "-L", socketKey]);
 		cleanupProof = postSpawnServer;
 		if (postSpawnServer.state === "unsafe") return fail("tmux-owner-server_unsafe");
-		if (!isSafeServerProof(postSpawnServer)) return fail("tmux-owner-server_unverifiable");
+		if (!isSafeServerProof(postSpawnServer, ownerIsolationPlatform())) return fail("tmux-owner-server_unverifiable");
 		if (
 			scopedReceipt &&
 			(scopedReceipt.sessionName !== sessionName ||
@@ -1441,14 +1371,10 @@ export default class Harness extends Command {
 		let state = await loadState(root, sessionId);
 		const ownerLive = ownerLiveFor(state);
 		const { observation, completedTerminalEvent } = await buildObservation(root, state, ownerLive);
-		state = await reconcileCompletedOwnerExited(root, state, observation, completedTerminalEvent);
 		const vanishedOwnerBlock = needsVanishedOwnerBlock(state, observation, completedTerminalEvent);
-		state = await markVanishedOwnerBlocked(root, state, observation, completedTerminalEvent);
-		// Build owner-exit evidence whenever the owner is gone so a startup death (owner started,
-		// reported live, then died before the first prompt) is detectable, not just vanish/completion.
 		const ownerExit = !ownerLive ? await buildOwnerExitEvidence(root, state) : null;
 		const startupBlocked = ownerExit?.startupBlocker ?? false;
-		if (ownerExit && startupBlocked) state = await markStartupOwnerBlocked(root, state, ownerExit);
+		state = await reconcileLifecycle(root, state, observation, completedTerminalEvent, startupBlocked);
 		const includeOwnerExit = Boolean(ownerExit && (vanishedOwnerBlock || completedTerminalEvent || startupBlocked));
 		writeJson(
 			buildResponse(state, ownerLive, {
@@ -1482,12 +1408,7 @@ export default class Harness extends Command {
 			if (!observation) {
 				const built = await buildObservation(root, stateView, ownerLive);
 				observation = built.observation;
-				stateView = await markVanishedOwnerBlocked(
-					root,
-					stateView,
-					built.observation,
-					built.completedTerminalEvent,
-				);
+				stateView = await reconcileLifecycle(root, stateView, built.observation, built.completedTerminalEvent);
 			}
 		}
 		if (!observation) throw new Error("classify_requires_observation_or_session");
@@ -1548,7 +1469,14 @@ export default class Harness extends Command {
 		const ownerExit = await buildOwnerExitEvidence(root, state);
 		// An owner that started, reported live, then died before accepting the first prompt is a
 		// startup blocker, not a healthy `owner-not-live` gate — persist it and report it as such.
-		if (ownerExit.startupBlocker) state = await markStartupOwnerBlocked(root, state, ownerExit);
+		const built = await buildObservation(root, state, false);
+		state = await reconcileLifecycle(
+			root,
+			state,
+			built.observation,
+			built.completedTerminalEvent,
+			ownerExit.startupBlocker,
+		);
 		const reason = ownerExit.startupBlocker ? ownerExit.reason : "owner-not-live";
 		writeJson(
 			buildResponse(
@@ -1614,7 +1542,7 @@ export default class Harness extends Command {
 		let state = await loadState(root, sessionId);
 		const beforeExit = await buildOwnerExitEvidence(root, state);
 		const { observation, completedTerminalEvent } = await buildObservation(root, state, false);
-		state = await markVanishedOwnerBlocked(root, state, observation, completedTerminalEvent);
+		state = await reconcileLifecycle(root, state, observation, completedTerminalEvent);
 		const decision = classifyRecovery({
 			observation: { ...observation, lifecycle: state.lifecycle },
 			retryBudget: budget,

package/src/commands/launch.ts

@@ -9,7 +9,7 @@ import { APP_NAME, setProjectDir } from "@gajae-code/utils";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import { parseArgs } from "../cli/args";
 import { launchDefaultTmuxIfNeeded } from "../gjc-runtime/launch-tmux";
-import { prepareLaunchWorktree } from "../gjc-runtime/launch-worktree";
+import { type PreparedLaunchWorktree, prepareLaunchWorktree } from "../gjc-runtime/launch-worktree";
 import {
 	GJC_COORDINATOR_SESSION_ID_ENV,
 	GJC_COORDINATOR_SESSION_STATE_FILE_ENV,
@@ -128,7 +128,8 @@ export default class Index extends Command {
 			description: "Resume a session (by ID prefix, path, or picker if omitted)",
 		}),
 		"session-dir": Flags.string({
-			description: "Directory for session storage and lookup",
+			description:
+				"Explicit session storage directory and lookup override (default uses managed v2 workspace scope)",
 		}),
 		"no-session": Flags.boolean({
 			description: "Don't save session (ephemeral)",
@@ -199,7 +200,8 @@ export default class Index extends Command {
 		`# Pin a stored credential for this session\n  ${APP_NAME} --credential email:me@example.com`,
 		`# Activate a model profile for this session\n  ${APP_NAME} --mpreset codex-medium`,
 		`# Persist a model profile as the default\n  ${APP_NAME} --mpreset opencodego --default`,
-		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.gjc/agent/sessions/--path--/session.jsonl`,
+		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.gjc/agent/sessions/v2-<scope>/session.jsonl`,
+		`# Use an explicit session storage directory\n  ${APP_NAME} --session-dir ./sessions`,
 	];
 
 	static strict = false;
@@ -212,7 +214,7 @@ export default class Index extends Command {
 			return;
 		}
 
-		let launch: ReturnType<typeof prepareLaunchWorktree>;
+		let launch: PreparedLaunchWorktree;
 		try {
 			launch = prepareLaunchWorktree(process.cwd(), args);
 		} catch (error) {

package/src/commands/mcp-serve.ts

@@ -1,3 +1,4 @@
+import { getAgentDir } from "@gajae-code/utils";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import {
 	COORDINATOR_MCP_PROTOCOL_VERSION,
@@ -5,12 +6,88 @@ import {
 	COORDINATOR_MCP_TOOL_NAMES,
 } from "../coordinator/contract";
 import { runCoordinatorMcpStdio } from "../coordinator-mcp/server";
+import { type BrokerDiscovery, readBrokerDiscovery } from "../sdk/broker/discovery";
+import { UnsupportedStateVersionError } from "../sdk/broker/state-version";
 import { runSdkMcpStdio, SDK_MCP_TOOL_NAMES } from "../sdk/mcp/server";
 
 function writeJson(value: unknown): void {
 	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 
+export type CoordinatorBrokerDiscoveryStatus = "ready" | "unavailable" | "error";
+export type CoordinatorBrokerDiscoveryReason =
+	| null
+	| "absent_or_invalid"
+	| "unsupported_state_version"
+	| "discovery_access_denied"
+	| "discovery_read_failed";
+
+export interface CoordinatorBrokerObservation {
+	discovery_status: CoordinatorBrokerDiscoveryStatus;
+	reason: CoordinatorBrokerDiscoveryReason;
+}
+
+export interface CoordinatorCheckProbe {
+	agentDir?: string;
+	readBrokerDiscovery?: (agentDir: string) => Promise<BrokerDiscovery | null>;
+}
+
+export interface CoordinatorCheckPayload {
+	ok: true;
+	server: { name: typeof COORDINATOR_MCP_SERVER_NAME; protocolVersion: typeof COORDINATOR_MCP_PROTOCOL_VERSION };
+	readOnly: true;
+	tools: readonly string[];
+	catalog: { ready: true; reason: null };
+	broker: CoordinatorBrokerObservation & {
+		operational_ready: null;
+		bootstrap_supported: true;
+		bootstrap_attempted: false;
+	};
+}
+
+function discoveryErrorCode(error: unknown): unknown {
+	if (typeof error !== "object" || error === null || !("code" in error)) return undefined;
+	return error.code;
+}
+
+export async function probeCoordinatorBrokerCheck(
+	probe: CoordinatorCheckProbe = {},
+): Promise<CoordinatorBrokerObservation> {
+	try {
+		const discovery = await (probe.readBrokerDiscovery ?? readBrokerDiscovery)(probe.agentDir ?? getAgentDir());
+		return discovery
+			? { discovery_status: "ready", reason: null }
+			: { discovery_status: "unavailable", reason: "absent_or_invalid" };
+	} catch (error) {
+		if (error instanceof UnsupportedStateVersionError)
+			return { discovery_status: "error", reason: "unsupported_state_version" };
+		const code = discoveryErrorCode(error);
+		if (code === "EACCES" || code === "EPERM")
+			return { discovery_status: "error", reason: "discovery_access_denied" };
+		return { discovery_status: "error", reason: "discovery_read_failed" };
+	}
+}
+
+export function formatCoordinatorCheckPayload(observation: CoordinatorBrokerObservation): CoordinatorCheckPayload {
+	return {
+		ok: true,
+		server: { name: COORDINATOR_MCP_SERVER_NAME, protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION },
+		readOnly: true,
+		tools: [...COORDINATOR_MCP_TOOL_NAMES],
+		catalog: { ready: true, reason: null },
+		broker: {
+			...observation,
+			operational_ready: null,
+			bootstrap_supported: true,
+			bootstrap_attempted: false,
+		},
+	};
+}
+
+export async function buildCoordinatorCheckPayload(probe?: CoordinatorCheckProbe): Promise<CoordinatorCheckPayload> {
+	return formatCoordinatorCheckPayload(await probeCoordinatorBrokerCheck(probe));
+}
+
 export function validateMcpServeSubcommandForTest(server: string | undefined): void {
 	if (server !== "coordinator" && server !== "hermes" && server !== "sdk")
 		throw new Error(`unknown_mcp_serve_subcommand:${server ?? ""}`);
@@ -46,17 +123,17 @@ export default class McpServe extends Command {
 		}
 
 		if (flags.check) {
+			if (!flags.json) {
+				const serverName = server === "sdk" ? "gjc-sdk-mcp" : COORDINATOR_MCP_SERVER_NAME;
+				const toolCount = server === "sdk" ? SDK_MCP_TOOL_NAMES.length : COORDINATOR_MCP_TOOL_NAMES.length;
+				process.stdout.write(`server: ${serverName}\ntools: ${toolCount}\n`);
+				return;
+			}
 			const payload =
 				server === "sdk"
 					? { ok: true, server: { name: "gjc-sdk-mcp" }, readOnly: false, tools: [...SDK_MCP_TOOL_NAMES] }
-					: {
-							ok: true,
-							server: { name: COORDINATOR_MCP_SERVER_NAME, protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION },
-							readOnly: true,
-							tools: [...COORDINATOR_MCP_TOOL_NAMES],
-						};
-			if (flags.json) writeJson(payload);
-			else process.stdout.write(`server: ${payload.server.name}\ntools: ${payload.tools.length}\n`);
+					: await buildCoordinatorCheckPayload();
+			writeJson(payload);
 			return;
 		}
 

package/src/commands/mcp.ts

@@ -53,7 +53,7 @@ export default class MCP extends Command {
 
 	async run(): Promise<void> {
 		if (this.argv.includes("--help") || this.argv.includes("-h")) {
-			this.printHelp();
+			this.#printHelp();
 			return;
 		}
 
@@ -80,7 +80,7 @@ export default class MCP extends Command {
 		await runMCPCommand(cmd);
 	}
 
-	private printHelp(): void {
+	#printHelp(): void {
 		process.stdout.write(`Store standalone MCP server definitions in GJC config without loading them at runtime
 
 USAGE

package/src/commands/notify.ts

@@ -12,9 +12,8 @@ export default class Notify extends Command {
 
 	static args = {
 		action: Args.string({
-			description: "Notify action",
+			description: "Notify action (setup|status|health|test|recovery|daemon-internal)",
 			required: false,
-			options: ACTIONS,
 		}),
 		extra: Args.string({
 			description: "Provider or additional internal args",
@@ -49,7 +48,12 @@ export default class Notify extends Command {
 
 	async run(): Promise<void> {
 		const { args, flags } = await this.parse(Notify);
-		const action = (args.action ?? "status") as NotifyAction;
+		const action = args.action ?? "status";
+		if (!ACTIONS.includes(action as NotifyAction)) {
+			console.error(`Unknown notify action: ${action}`);
+			console.error(`Valid actions: ${ACTIONS.join(", ")}`);
+			process.exit(1);
+		}
 		const extra = Array.isArray(args.extra) ? args.extra : args.extra ? [args.extra] : [];
 		const flagRec = flags as Record<string, unknown>;
 		const ownerId = flagRec["owner-id"] as string | undefined;
@@ -72,7 +76,7 @@ export default class Notify extends Command {
 		}
 
 		const cmd: NotifyCommandArgs = {
-			action,
+			action: action as NotifyAction,
 			smoke: flags.smoke,
 			rawArgs,
 			provider: provider === "telegram" || provider === "discord" || provider === "slack" ? provider : undefined,

package/src/commands/sdk.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import type { Args as ParsedArgs } from "../cli/args";
+import { Settings } from "../config/settings";
 import { applyStartupModelProfiles, createSessionManager } from "../main";
 import { initializeExtensions } from "../modes/runtime-init";
 import { Broker } from "../sdk/broker/broker";
@@ -16,20 +17,28 @@ import {
 } from "../sdk/broker/lifecycle";
 import { processIncarnation } from "../sdk/broker/process-incarnation";
 import { type CreateLifecycleAgentSessionResult, createLifecycleAgentSession } from "../sdk/lifecycle-session";
+import { listManagedSessionCandidates, resolveManagedSessionScope } from "../sdk/session-directory";
 import {
 	normalizeSdkStartupFailure,
 	type SdkStartupFailure,
 	type SdkStartupRollbackResult,
 	SdkStartupRollbackTracker,
 } from "../sdk/startup-capability";
-
 import {
 	type CapturedSessionTranscriptSnapshot,
 	type ResumeSessionIdentity,
 	SessionManager,
 } from "../session/session-manager";
 
-export function lifecycleArgs(request: SessionLifecycleLaunchRequest, cwd: string, agentDir: string): ParsedArgs {
+export async function lifecycleArgs(
+	request: SessionLifecycleLaunchRequest,
+	cwd: string,
+	agentDir: string,
+): Promise<ParsedArgs> {
+	const targetScope = await resolveManagedSessionScope({ cwd, agentDir });
+	if (targetScope.kind !== "resolved") throw new Error(`Lifecycle session scope is invalid: ${targetScope.message}`);
+	const forkSessionDir =
+		request.operation === "session.fork" ? SessionManager.getDefaultSessionDir(cwd, agentDir) : undefined;
 	return {
 		messages: [],
 		fileArgs: [],
@@ -39,7 +48,7 @@ export function lifecycleArgs(request: SessionLifecycleLaunchRequest, cwd: strin
 		...(request.operation === "session.fork"
 			? {
 					fork: request.sourceSessionPath ?? request.sourceSessionId,
-					sessionDir: SessionManager.getDefaultSessionDirReadOnly(cwd, agentDir),
+					sessionDir: forkSessionDir,
 				}
 			: {}),
 	};
@@ -53,7 +62,7 @@ type LifecycleTranscriptSource = {
 };
 
 function sameTranscriptIdentity(
-	actual: { dev: bigint; ino: bigint; size: number; mtimeMs: number; mtimeNs: bigint },
+	actual: { dev: bigint; ino: bigint; size: number; mtimeMs: number; mtimeNs: bigint; sha256: string },
 	expected: SessionLifecycleTranscriptIdentity,
 ): boolean {
 	return (
@@ -61,7 +70,8 @@ function sameTranscriptIdentity(
 		actual.ino.toString() === expected.ino &&
 		actual.size === expected.size &&
 		actual.mtimeMs === expected.mtimeMs &&
-		actual.mtimeNs.toString() === expected.mtimeNs
+		actual.mtimeNs.toString() === expected.mtimeNs &&
+		actual.sha256 === expected.sha256
 	);
 }
 
@@ -85,26 +95,38 @@ function lifecycleTranscriptSource(request: SessionLifecycleLaunchRequest, cwd:
 	throw new Error("A new lifecycle session has no persisted transcript authority.");
 }
 
-function verifyLifecycleTranscript(
+async function captureLifecycleTranscript(
 	request: SessionLifecycleLaunchRequest,
 	cwd: string,
 	agentDir: string,
-): LifecycleTranscriptSource {
+	migrationPolicy: "copy-retain" | "disabled",
+): Promise<CapturedSessionTranscriptSnapshot> {
 	const source = lifecycleTranscriptSource(request, cwd);
-	const inventory = SessionManager.inventorySessionsStrict(source.cwd, {
-		sessionDir: SessionManager.getDefaultSessionDir(source.cwd, agentDir),
-	});
+	const scope = await resolveManagedSessionScope({ cwd: source.cwd, agentDir });
+	if (scope.kind !== "resolved")
+		throw new Error("Lifecycle saved session storage could not be verified for the requested workspace.");
+	const inventory = await listManagedSessionCandidates({ scope: scope.scope });
 	if (inventory.kind !== "complete")
 		throw new Error("Lifecycle saved session storage could not be verified for the requested workspace.");
-	const matches = inventory.candidates.filter(
+	const captured = SessionManager.captureTranscriptStrict(source.path);
+	if (
+		captured.kind !== "captured" ||
+		captured.snapshot.sourcePath !== path.resolve(source.path) ||
+		captured.snapshot.identity.sessionId !== source.id ||
+		!sameTranscriptIdentity(captured.snapshot.identity, source.identity)
+	)
+		throw new Error("Lifecycle saved session authority changed before the session host consumed it.");
+	const matches = inventory.owned.filter(
 		candidate =>
-			candidate.path === path.resolve(source.path) &&
-			candidate.id === source.id &&
-			sameTranscriptIdentity(candidate.identity, source.identity),
+			candidate.path === captured.snapshot.sourcePath &&
+			candidate.sessionId === source.id &&
+			sameLifecycleTranscriptSnapshot(candidate.identity, captured.snapshot.identity),
 	);
 	if (matches.length !== 1)
 		throw new Error("Lifecycle saved session authority changed before the session host started.");
-	return source;
+	if (matches[0]!.provenance === "legacy" && migrationPolicy === "disabled")
+		throw new Error("Lifecycle legacy session migration is disabled by policy.");
+	return captured.snapshot;
 }
 
 function sameLifecycleTranscriptSnapshot(left: ResumeSessionIdentity, right: ResumeSessionIdentity): boolean {
@@ -120,23 +142,6 @@ function sameLifecycleTranscriptSnapshot(left: ResumeSessionIdentity, right: Res
 	);
 }
 
-function captureLifecycleTranscript(
-	request: SessionLifecycleLaunchRequest,
-	cwd: string,
-	agentDir: string,
-): CapturedSessionTranscriptSnapshot {
-	const source = verifyLifecycleTranscript(request, cwd, agentDir);
-	const captured = SessionManager.captureTranscriptStrict(source.path);
-	if (
-		captured.kind !== "captured" ||
-		captured.snapshot.sourcePath !== path.resolve(source.path) ||
-		captured.snapshot.identity.sessionId !== source.id ||
-		!sameTranscriptIdentity(captured.snapshot.identity, source.identity)
-	)
-		throw new Error("Lifecycle saved session authority changed before the session host consumed it.");
-	return captured.snapshot;
-}
-
 async function revalidateLifecycleTranscript(snapshot: ResumeSessionIdentity): Promise<void> {
 	const inspected = await SessionManager.inspectSessionTailReadOnly(snapshot.canonicalPath);
 	if (inspected.kind === "error" || !sameLifecycleTranscriptSnapshot(snapshot, inspected.identity))
@@ -149,14 +154,22 @@ export async function openLifecycleSessionManager(
 	cwd: string,
 	agentDir: string,
 ): Promise<{ parsed: ParsedArgs; sessionManager: SessionManager | undefined }> {
-	const parsed = lifecycleArgs(request, cwd, agentDir);
+	const parsed = await lifecycleArgs(request, cwd, agentDir);
+	const lifecycleSettings = await Settings.loadForScope({ cwd, agentDir });
+	const migrationPolicy =
+		lifecycleSettings.get("session.directoryMigration") === "disabled" ? "disabled" : "copy-retain";
 	if (request.operation === "session.create") {
-		return { parsed, sessionManager: await createSessionManager(parsed, cwd) };
+		return { parsed, sessionManager: await createSessionManager(parsed, cwd, lifecycleSettings) };
 	}
-	const snapshot = captureLifecycleTranscript(request, cwd, agentDir);
+	const snapshot = await captureLifecycleTranscript(request, cwd, agentDir, migrationPolicy);
 	let sessionManager: SessionManager | undefined;
 	if (request.operation === "session.resume") {
-		const opened = await SessionManager.openExistingStrict(snapshot.identity, parsed.sessionDir);
+		const opened = await SessionManager.openExistingStrict(
+			snapshot.identity,
+			parsed.sessionDir,
+			undefined,
+			migrationPolicy,
+		);
 		if (opened.kind === "error")
 			throw new Error("Lifecycle saved session authority changed while the session host opened it.");
 		sessionManager = opened.manager;
@@ -167,7 +180,7 @@ export async function openLifecycleSessionManager(
 			throw error;
 		}
 	} else {
-		const forked = await SessionManager.forkFromCaptured(snapshot, cwd, parsed.sessionDir);
+		const forked = await SessionManager.forkFromCaptured(snapshot, cwd, parsed.sessionDir, migrationPolicy);
 		if (forked.kind === "error")
 			throw new Error("Lifecycle saved session authority changed while the session host forked it.");
 		sessionManager = forked.manager;
@@ -302,21 +315,23 @@ export async function runSessionHost(
 					fs.readFile(transcriptPath),
 					fs.stat(transcriptPath, { bigint: true }),
 				]);
+				const digest = createHash("sha256").update(bytes).digest("hex");
 				return {
-					digest: createHash("sha256").update(bytes).digest("hex"),
+					digest,
 					identity: {
 						dev: stat.dev.toString(),
 						ino: stat.ino.toString(),
 						size: Number(stat.size),
 						mtimeMs: Number(stat.mtimeMs),
 						mtimeNs: stat.mtimeNs.toString(),
+						sha256: digest,
 					},
 				};
 			} catch {
 				return undefined;
 			}
 		})();
-		return disposal;
+		return disposal ?? Promise.resolve(undefined);
 	};
 	let failureRollback: Promise<void> | undefined;
 	const failAfterRollback = (failure: SdkStartupFailure): Promise<void> => {
@@ -415,7 +430,13 @@ export default class Sdk extends Command {
 		}
 		const agentDir = flags["agent-dir"] as string | undefined;
 		if (!agentDir) throw new Error("--agent-dir is required for sdk broker-internal.");
-		const broker = new Broker({ agentDir });
+		const broker = new Broker({
+			agentDir,
+			resolveDirectoryMigration: async cwd => {
+				const policy = (await Settings.loadForScope({ cwd, agentDir })).get("session.directoryMigration");
+				return policy === "disabled" ? "disabled" : "copy-retain";
+			},
+		});
 		await broker.start();
 		if (!broker.ownsDiscovery) return;
 		const stop = () => void broker.stop().finally(() => process.exit(0));

package/src/commands/ultragoal.ts

@@ -26,15 +26,18 @@ export default class Ultragoal extends Command {
 		if (isReviewStart && !result.createdReviewPlan && (result.reviewBlockerGoalIds?.length ?? 0) === 0) return;
 
 		const cwd = process.cwd();
-		const { objective, goalsPath } = await readUltragoalGjcObjective(cwd);
+		const { objective, goalsPath, provenance } = await readUltragoalGjcObjective(cwd);
+
 		await writeCurrentSessionGoalModeState({
 			sessionFile: process.env[GJC_SESSION_FILE_ENV],
 			objective,
+			provenance,
 		});
 		await writePendingGoalModeRequest({
 			cwd,
 			objective,
 			goalsPath,
+			provenance,
 			sessionId: process.env[GJC_SESSION_ID_ENV],
 		});
 	}