@gajae-code/coding-agent 0.11.1 → 0.11.2

package/src/cli/config-cli.ts

@@ -5,7 +5,10 @@
  * Uses the settings schema as the source of truth for available settings.
  */
 
+import * as fs from "node:fs/promises";
+import type * as path from "node:path";
 import { APP_NAME, getAgentDir } from "@gajae-code/utils";
+import { YAML } from "bun";
 import chalk from "chalk";
 import {
 	getDefault,
@@ -25,7 +28,7 @@ import { initXdg } from "./commands/init-xdg";
 // Types
 // =============================================================================
 
-export type ConfigAction = "list" | "get" | "set" | "reset" | "path" | "init-xdg";
+export type ConfigAction = "list" | "get" | "set" | "reset" | "path" | "doctor" | "init-xdg";
 
 export interface ConfigCommandArgs {
 	action: ConfigAction;
@@ -111,7 +114,7 @@ function getSettingValues(def: CliSettingDef): readonly string[] | undefined {
 // Argument Parser
 // =============================================================================
 
-const VALID_ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path", "init-xdg"];
+const VALID_ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path", "doctor", "init-xdg"];
 
 /**
  * Parse config subcommand arguments.
@@ -299,6 +302,9 @@ export async function runConfigCommand(cmd: ConfigCommandArgs): Promise<void> {
 		case "path":
 			handlePath();
 			break;
+		case "doctor":
+			handleDoctor(cmd.flags);
+			break;
 		case "init-xdg":
 			await initXdg();
 			break;
@@ -443,6 +449,70 @@ function handlePath(): void {
 	console.log(getAgentDir());
 }
 
+function handleDoctor(flags: { json?: boolean }): void {
+	const report = settings.getSchemaReport();
+	if (flags.json) {
+		console.log(JSON.stringify(report, null, 2));
+		return;
+	}
+	if (report.issues.length === 0) {
+		console.log(chalk.green("Settings schema is healthy."));
+		return;
+	}
+	for (const issue of report.issues) console.log(`${issue.kind}\t${issue.path}\t${issue.detail}`);
+}
+
+type ConfigDoctorReport = {
+	unknownKeys: string[];
+	invalidValues: Array<{ path: string; value: unknown }>;
+	legacyShapes: string[];
+};
+
+function flattenConfig(value: unknown, prefix = ""): Array<[string, unknown]> {
+	if (prefix && ALL_SETTING_PATHS.includes(prefix as SettingPath)) return [[prefix, value]];
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return prefix ? [[prefix, value]] : [];
+	return Object.entries(value).flatMap(([key, child]) => flattenConfig(child, prefix ? `${prefix}.${key}` : key));
+}
+
+function matchesSettingType(path: SettingPath, value: unknown): boolean {
+	const definition = SETTINGS_SCHEMA[path];
+	switch (definition.type) {
+		case "string":
+		case "enum":
+			return (
+				typeof value === "string" && (definition.type !== "enum" || getEnumValues(path)?.includes(value) === true)
+			);
+		case "number":
+			return typeof value === "number" && Number.isFinite(value);
+		case "boolean":
+			return typeof value === "boolean";
+		case "array":
+			return Array.isArray(value);
+		case "record":
+			return value !== null && typeof value === "object" && !Array.isArray(value);
+	}
+}
+
+export async function inspectConfigFile(configPath: string): Promise<ConfigDoctorReport> {
+	const report: ConfigDoctorReport = { unknownKeys: [], invalidValues: [], legacyShapes: [] };
+	try {
+		const raw = YAML.parse(await fs.readFile(configPath, "utf8"));
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+			report.legacyShapes.push("config root is not a mapping");
+			return report;
+		}
+		for (const [settingPath, value] of flattenConfig(raw)) {
+			if (!ALL_SETTING_PATHS.includes(settingPath as SettingPath)) report.unknownKeys.push(settingPath);
+			else if (!matchesSettingType(settingPath as SettingPath, value))
+				report.invalidValues.push({ path: settingPath, value: redactConfigValue(settingPath, value) });
+		}
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT")
+			report.legacyShapes.push(`unable to parse config: ${String(error)}`);
+	}
+	return report;
+}
+
 // =============================================================================
 // Help
 // =============================================================================
@@ -455,8 +525,10 @@ ${chalk.bold("Commands:")}
   get <key>          Get a specific setting value
   set <key> <value>  Set a setting value
   reset <key>        Reset a setting to its default value
+  doctor             Report unknown, invalid, and pending settings migrations
   path               Print the config directory path
   init-xdg           Initialize XDG Base Directory structure
+  doctor             Report unknown, invalid, and legacy config entries
 
 ${chalk.bold("Options:")}
   --json             Output as JSON
@@ -472,6 +544,7 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} config list --json
   ${APP_NAME} config get auth.broker.token --show-secrets
   ${APP_NAME} config init-xdg
+  ${APP_NAME} config doctor --json
 
 ${chalk.bold("Boolean Values:")}
   true, false, yes, no, on, off, 1, 0

package/src/cli/notify-cli.ts

@@ -75,6 +75,7 @@ export interface NotifyCommandDeps {
 	tokenPrompt?: () => Promise<string>;
 	setExitCode?: (code: number) => void;
 	exitProcess?: (code: number) => void;
+	valuePrompt?: (label: string, masked: boolean) => Promise<string>;
 	/** Optional daemon ownership facts collected by an embedding host. */
 	setupPreflight?: TelegramSetupPreflight;
 	/** Injectable timers and cancellation for setup pairing. */
@@ -99,6 +100,27 @@ export function parseNotifyArgs(args: string[]): NotifyCommandArgs | undefined {
 			const i = rest.indexOf(name);
 			return i >= 0 ? rest[i + 1] : undefined;
 		};
+		const valueFlags = [
+			"--token",
+			"--chat-id",
+			"--discord-bot-token",
+			"--discord-application-id",
+			"--discord-guild-id",
+			"--discord-parent-channel-id",
+			"--slack-bot-token",
+			"--slack-app-token",
+			"--slack-workspace-id",
+			"--slack-channel-id",
+			"--slack-authorized-user-id",
+		];
+		if (
+			valueFlags.some(name => {
+				const index = rest.indexOf(name);
+				const value = index >= 0 ? rest[index + 1] : undefined;
+				return index >= 0 && (!value || value.startsWith("--"));
+			})
+		)
+			return undefined;
 		const provider = rest[0]?.startsWith("--") ? undefined : rest[0];
 		if (provider !== undefined && provider !== "telegram" && provider !== "discord" && provider !== "slack") {
 			return undefined;
@@ -144,7 +166,7 @@ export function parseNotifyArgs(args: string[]): NotifyCommandArgs | undefined {
 		};
 	}
 
-	return { action: "status", rawArgs: args.slice(1) };
+	return undefined;
 }
 
 export async function runNotifyCommand(cmd: NotifyCommandArgs, deps: NotifyCommandDeps = {}): Promise<void> {
@@ -221,22 +243,41 @@ async function runSetup(cmd: NotifyCommandArgs, deps: NotifyCommandDeps): Promis
 
 function requiredSetupValue(value: string | undefined, flag: string): string {
 	if (!value?.trim()) throw new Error(`${flag} is required for non-interactive setup.`);
+	if (value.trim().startsWith("--")) throw new Error(`${flag} must not start with --.`);
 	return value.trim();
 }
 
+async function promptSetupValue(
+	value: string | undefined,
+	flag: string,
+	masked: boolean,
+	deps: NotifyCommandDeps,
+): Promise<string> {
+	if (value?.trim()) return requiredSetupValue(value, flag);
+	if (!resolveSetupInteractive(deps)) return requiredSetupValue(value, flag);
+	return requiredSetupValue(await (deps.valuePrompt ?? promptForValue)(`${flag.slice(2)}: `, masked), flag);
+}
+
 async function runDiscordSetup(cmd: NotifyCommandArgs, deps: NotifyCommandDeps): Promise<void> {
-	const botToken = requiredSetupValue(cmd.discordBotToken, "--discord-bot-token");
-	const applicationId = requiredSetupValue(cmd.discordApplicationId, "--discord-application-id");
-	const guildId = requiredSetupValue(cmd.discordGuildId, "--discord-guild-id");
-	const parentChannelId = requiredSetupValue(cmd.discordParentChannelId, "--discord-parent-channel-id");
+	const botToken = await promptSetupValue(cmd.discordBotToken, "--discord-bot-token", true, deps);
+	const applicationId = await promptSetupValue(cmd.discordApplicationId, "--discord-application-id", false, deps);
+	const guildId = await promptSetupValue(cmd.discordGuildId, "--discord-guild-id", false, deps);
+	const parentChannelId = await promptSetupValue(
+		cmd.discordParentChannelId,
+		"--discord-parent-channel-id",
+		false,
+		deps,
+	);
 	const settings = await getSettings(deps);
-	settings.set("notifications.discord.botToken", botToken);
-	settings.set("notifications.discord.applicationId", applicationId);
-	settings.set("notifications.discord.guildId", guildId);
-	settings.set("notifications.discord.parentChannelId", parentChannelId);
-	settings.set("notifications.enabled", true);
-	if (cmd.redact) settings.set("notifications.redact", true);
-	await settings.flushOrThrow();
+	const patches: SettingsAtomicPatch[] = [
+		{ path: "notifications.discord.botToken", op: "set", value: botToken },
+		{ path: "notifications.discord.applicationId", op: "set", value: applicationId },
+		{ path: "notifications.discord.guildId", op: "set", value: guildId },
+		{ path: "notifications.discord.parentChannelId", op: "set", value: parentChannelId },
+		{ path: "notifications.enabled", op: "set", value: true },
+	];
+	if (cmd.redact) patches.push({ path: "notifications.redact", op: "set", value: true });
+	await settings.commitAtomicBatch(patches);
 	const daemon = await ensureConfiguredProviderDaemon("discord", settings, deps);
 	process.stdout.write(
 		`Discord notifications enabled. botToken=${maskToken(botToken)} applicationId=${applicationId} guildId=${guildId} parentChannelId=${parentChannelId} daemon=${daemon}\n`,
@@ -244,20 +285,24 @@ async function runDiscordSetup(cmd: NotifyCommandArgs, deps: NotifyCommandDeps):
 }
 
 async function runSlackSetup(cmd: NotifyCommandArgs, deps: NotifyCommandDeps): Promise<void> {
-	const botToken = requiredSetupValue(cmd.slackBotToken, "--slack-bot-token");
-	const appToken = requiredSetupValue(cmd.slackAppToken, "--slack-app-token");
-	const workspaceId = requiredSetupValue(cmd.slackWorkspaceId, "--slack-workspace-id");
-	const channelId = requiredSetupValue(cmd.slackChannelId, "--slack-channel-id");
+	const botToken = await promptSetupValue(cmd.slackBotToken, "--slack-bot-token", true, deps);
+	const appToken = await promptSetupValue(cmd.slackAppToken, "--slack-app-token", true, deps);
+	const workspaceId = await promptSetupValue(cmd.slackWorkspaceId, "--slack-workspace-id", false, deps);
+	const channelId = await promptSetupValue(cmd.slackChannelId, "--slack-channel-id", false, deps);
 	const authorizedUserId = cmd.slackAuthorizedUserId?.trim() || undefined;
 	const settings = await getSettings(deps);
-	settings.set("notifications.slack.botToken", botToken);
-	settings.set("notifications.slack.appToken", appToken);
-	settings.set("notifications.slack.workspaceId", workspaceId);
-	settings.set("notifications.slack.channelId", channelId);
-	settings.set("notifications.slack.authorizedUserId", authorizedUserId);
-	settings.set("notifications.enabled", true);
-	if (cmd.redact) settings.set("notifications.redact", true);
-	await settings.flushOrThrow();
+	const patches: SettingsAtomicPatch[] = [
+		{ path: "notifications.slack.botToken", op: "set", value: botToken },
+		{ path: "notifications.slack.appToken", op: "set", value: appToken },
+		{ path: "notifications.slack.workspaceId", op: "set", value: workspaceId },
+		{ path: "notifications.slack.channelId", op: "set", value: channelId },
+		authorizedUserId === undefined
+			? { path: "notifications.slack.authorizedUserId", op: "unset" }
+			: { path: "notifications.slack.authorizedUserId", op: "set", value: authorizedUserId },
+		{ path: "notifications.enabled", op: "set", value: true },
+	];
+	if (cmd.redact) patches.push({ path: "notifications.redact", op: "set", value: true });
+	await settings.commitAtomicBatch(patches);
 	const daemon = await ensureConfiguredProviderDaemon("slack", settings, deps);
 	process.stdout.write(
 		`Slack notifications enabled. botToken=${maskToken(botToken)} appToken=${maskToken(appToken)} workspaceId=${workspaceId} channelId=${channelId} authorizedUserId=${authorizedUserId ?? "(unset; inbound denied)"} daemon=${daemon}\n`,
@@ -437,7 +482,8 @@ type TokenPromptInput = NodeJS.ReadStream & {
 
 type TokenPromptOutput = Pick<NodeJS.WriteStream, "write">;
 
-export async function promptForToken(
+async function promptForMaskedValue(
+	label: string,
 	input: TokenPromptInput = process.stdin,
 	output: TokenPromptOutput = process.stdout,
 ): Promise<string> {
@@ -448,7 +494,7 @@ export async function promptForToken(
 		throw new Error("notify setup requires a TTY with raw input support unless setupToken is injected.");
 	}
 
-	output.write("Telegram BotFather token: ");
+	output.write(label);
 	const wasRaw = input.isRaw === true;
 	input.setRawMode(true);
 
@@ -503,6 +549,26 @@ export async function promptForToken(
 	});
 }
 
+export async function promptForToken(
+	input: TokenPromptInput = process.stdin,
+	output: TokenPromptOutput = process.stdout,
+): Promise<string> {
+	return await promptForMaskedValue("Telegram BotFather token: ", input, output);
+}
+
+async function promptForValue(label: string, masked: boolean): Promise<string> {
+	if (masked) return await promptForMaskedValue(label);
+	if (!process.stdin.isTTY) {
+		throw new Error("notify setup requires an interactive TTY unless all setup values are supplied as flags.");
+	}
+	const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+	try {
+		return (await rl.question(label)).trim();
+	} finally {
+		rl.close();
+	}
+}
+
 function resolveSetupInteractive(deps: NotifyCommandDeps): boolean {
 	if (deps.setupInteractive !== undefined) return deps.setupInteractive;
 	return Boolean(process.stdin.isTTY) && !deps.setupChatId?.trim();

package/src/cli/session-picker.ts

@@ -1,13 +1,30 @@
+import * as path from "node:path";
 import { ProcessTerminal, TUI } from "@gajae-code/tui";
+import { pathIsWithin } from "@gajae-code/utils";
 import { type SessionSelectionResult, SessionSelectorComponent } from "../modes/components/session-selector";
 import { type SessionInfo, SessionManager } from "../session/session-manager";
 import { FileSessionStorage } from "../session/session-storage";
 
+export async function deleteSessionPickerCandidate(sessionPath: string, explicitSessionDir?: string): Promise<void> {
+	if (!explicitSessionDir) {
+		await SessionManager.deleteManagedCandidate(sessionPath);
+		return;
+	}
+	const root = path.resolve(explicitSessionDir);
+	const target = path.resolve(sessionPath);
+	if (!pathIsWithin(root, target))
+		throw new Error("Explicit session deletion escaped the configured session directory.");
+	await new FileSessionStorage().deleteSessionWithArtifacts(target);
+}
+
 /** Show the read-only TUI session picker and return the user's consent intent. */
-export async function selectSession(sessions: SessionInfo[]): Promise<SessionSelectionResult> {
+export async function selectSession(
+	sessions: SessionInfo[],
+	explicitSessionDir?: string,
+): Promise<SessionSelectionResult> {
 	const { promise, resolve } = Promise.withResolvers<SessionSelectionResult>();
 	const ui = new TUI(new ProcessTerminal());
-	const storage = new FileSessionStorage();
+
 	let settled = false;
 	const settle = (selection: SessionSelectionResult): void => {
 		if (settled) return;
@@ -21,7 +38,7 @@ export async function selectSession(sessions: SessionInfo[]): Promise<SessionSel
 		() => settle({ kind: "cancelled" }),
 		() => settle({ kind: "cancelled" }),
 		async session => {
-			await storage.deleteSessionWithArtifacts(session.path);
+			await deleteSessionPickerCandidate(session.path, explicitSessionDir);
 			return true;
 		},
 		SessionManager.inspectSessionTailReadOnly,

package/src/cli/setup-cli.ts

@@ -564,7 +564,7 @@ async function confirmImport(count: number): Promise<boolean> {
  */
 export interface CredentialsSetupDependencies {
 	openStore?: typeof SqliteAuthCredentialStore.open;
-	createAuthStorage?: (store: Awaited<ReturnType<typeof SqliteAuthCredentialStore.open>>) => AuthStorage;
+	createAuthStorage?: (store: SqliteAuthCredentialStore) => AuthStorage;
 	discover?: Parameters<typeof runExternalCredentialAutoImport>[0]["discover"];
 }
 

package/src/cli.ts

@@ -9,7 +9,6 @@ import { Args, type CliConfig, Command, type CommandEntry, Flags, run } from "@g
 import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@gajae-code/utils/dirs";
 import { runFixtureReport } from "./cli/fixture-report";
 import { isTmuxOwnerIsolationCliArgv, runTmuxOwnerIsolationCliFromStdin } from "./gjc-runtime/tmux-owner-isolation-cli";
-import { runChatDaemonInternal } from "./sdk/bus/chat-daemon-cli";
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 	process.stderr.write(
@@ -134,6 +133,7 @@ async function runChatDaemonInternalFastPath(argv: string[]): Promise<void> {
 	if (action !== "discord-internal" && action !== "slack-internal") {
 		throw new Error("invalid chat daemon internal fast path");
 	}
+	const { runChatDaemonInternal } = await import("./sdk/bus/chat-daemon-cli");
 	await runChatDaemonInternal(action === "discord-internal" ? "discord" : "slack", argv.slice(2));
 }
 

package/src/commands/config.ts

@@ -5,7 +5,7 @@ import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import { type ConfigAction, type ConfigCommandArgs, runConfigCommand } from "../cli/config-cli";
 import { initTheme } from "../modes/theme/theme";
 
-const ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path", "init-xdg"];
+const ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path", "init-xdg", "doctor"];
 
 export default class Config extends Command {
 	static description = "Manage configuration settings";

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) {