zigmini 0.8.0-beta.3 → 0.8.0-beta.5

package/src/cli/main.ts

@@ -7,6 +7,7 @@ import { LEGACY_HOME } from "../runtime/paths.ts";
 import { doctorCommand, systemDoctorDeps } from "./doctor.ts";
 import { setupCommand, stdinPrompt, systemSetupDeps } from "./setup.ts";
 import { pairCommand } from "./pair.ts";
+import { setupHint } from "./setup-hint.ts";
 import { helperCommand, updateCommand } from "../update/cli.ts";
 import { handoffCommand } from "../update/handoff-system.ts";
 import { HANDOFF_COMMAND } from "../update/strategy.ts";
@@ -14,10 +15,12 @@ import { EXIT_USAGE, parseMigrateArgs, parseMigrateRunArgs, runMigrate, runMigra
 
 export const HELP = `zigmini - 개인 AI 에이전트 게이트웨이
 
+처음 설치했으면 먼저 \`zigmini setup\`을 실행하세요. setup이 권한 동의, 엔진 설치, 설정, 시작을 합니다.
+
 사용법: zigmini <명령> [옵션]
 
 명령:
-  setup                       설치합니다: 홈 폴더, 엔진(OMO), 설정, launchd 등록과 시작
+  setup                       설치합니다: 홈 폴더, 엔진, 설정, launchd 등록과 시작
   start                       게이트웨이와 브리지를 launchd에 등록하고 시작합니다
   stop                        게이트웨이와 브리지를 멈춥니다
   stop --uninstall            멈추고 이 패키지의 launchd plist를 모두 지웁니다
@@ -104,6 +107,8 @@ if (import.meta.main) {
 	const ctx = systemContext();
 	const kind = installKind();
 	const notice = () => loadNotice();
+	const hint = setupHint(argv[0], ctx.paths.home, kind);
+	if (hint !== null) deps.err(`${hint}\n\n`);
 	if (argv[0] === "consent") {
 		if (argv.length !== 1) {
 			deps.err(`잘못된 인자: ${argv.join(" ")}\n\n${HELP}`);

package/src/cli/setup-hint.ts

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readConsent } from "../consent/consent.ts";
+import type { InstallKind } from "../runtime/install-kind.ts";
+import { HANDOFF_COMMAND } from "../update/strategy.ts";
+import { UPDATER_COMMAND } from "./launchd.ts";
+
+/**
+ * Bun 1.4 blocks the postinstall of `bun add -g zigmini` and the package ships no install-time script, so the CLI tells
+ * the user to run `zigmini setup` until setup has written the consent record and config.env.
+ */
+export const SETUP_HINT = "아직 설치를 마치지 않았습니다. 먼저 `zigmini setup`을 실행하세요.";
+export const UNHINTED_COMMANDS: readonly string[] = [
+	"setup", "consent", "migrate", "migrate-run", "--version", "-v", "--help", "-h", UPDATER_COMMAND, HANDOFF_COMMAND,
+];
+
+export function setupDone(home: string): boolean {
+	return existsSync(join(home, "config.env")) && readConsent(home) !== null;
+}
+
+export function setupHint(command: string | undefined, home: string, kind: InstallKind): string | null {
+	if (kind === "checkout") return null;
+	if (command !== undefined && UNHINTED_COMMANDS.includes(command)) return null;
+	return setupDone(home) ? null : SETUP_HINT;
+}

package/src/engine/schema-guard.ts

@@ -17,7 +17,7 @@ export const STORE = join("gateway", "gateway.sqlite");
 export const GUARD_FILE = "schema-guard.json";
 export const GLOBAL_ENGINE_PACKAGE = join("install", "global", "node_modules", "omo-ai", "package.json");
 export const SCHEMA_TOO_NEW = "schema_too_new";
-export const NOTICE_TITLE = "OMO 스키마 충돌: 브리지를 멈췄습니다";
+export const NOTICE_TITLE = "엔진 스키마 충돌: 브리지를 멈췄습니다";
 
 export type StoreReading =
 	| { readonly state: "ok"; readonly version: number }

package/src/hub.ts

@@ -47,6 +47,14 @@ export interface HubOptions {
 	media?: { dir: string; hostDir?: string };
 	now?: () => number;
 	rotation?: { maxAgeMs?: number; idleMs?: number; forceMaxBytes?: number; forceUpdateCompactions?: number };
+	/** Bug 152: bounded native ownership reconciliation; timers are injectable for deterministic tests. */
+	closeRecovery?: {
+		intervalMs?: number;
+		maxAttempts?: number;
+		timeoutMs?: number;
+		setTimeout?: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+		clearTimeout?: (timer: ReturnType<typeof setTimeout>) => void;
+	};
 	/** Answers `/version` as a notice; the command never reaches omo. */
 	versionReport?: () => Promise<string>;
 	/** Answers `/usage` (model account usage) as a notice; the command never reaches omo. */
@@ -89,6 +97,7 @@ export interface RotationStatus {
 	/** First sweep that found it held in this gateway run; null when not held or not yet swept. */
 	readonly blockedSince: string | null;
 	readonly blockers: readonly RotationBlocker[];
+	readonly closeRecovery?: { readonly state: "recovering" | "exhausted"; readonly attempts: number; readonly maxAttempts: number };
 }
 
 /** omo writes a new session file with its first entry; until then the session has no size. */
@@ -120,6 +129,23 @@ interface OpenResult {
 	streaming: boolean;
 }
 
+interface CloseRecovery {
+	attempts: number;
+	exhausted: boolean;
+	timer?: ReturnType<typeof setTimeout>;
+	flight?: Promise<void>;
+	cancel?: () => void;
+}
+
+interface SessionRetirement {
+	sessionId: string;
+	sessionPath: string;
+	from: string | null;
+	reason: RotationReason;
+	handoff: string;
+	closeAcknowledged?: boolean;
+}
+
 export interface SlashCommand {
 	name: string;
 	description: string;
@@ -230,7 +256,7 @@ export const MAIN_QUESTION_RELEASED =
 const PERMISSION_PREFIX = "Permission required:";
 const AUTO_CONTINUE_LIMIT = 2;
 const CONTINUE_PROMPT =
-	"[게이트웨이 알림] 게이트웨이나 omo가 재시작되면서 이전 작업이 중간에 끊겼습니다. 세션 기록에서 마지막으로 한 일을 확인하고, 이미 끝난 단계는 반복하지 말고 끊긴 지점부터 이어서 마무리해 주세요.";
+	"[게이트웨이 알림] 게이트웨이나 엔진이 재시작되면서 이전 작업이 중간에 끊겼습니다. 세션 기록에서 마지막으로 한 일을 확인하고, 이미 끝난 단계는 반복하지 말고 끊긴 지점부터 이어서 마무리해 주세요.";
 
 /** A model as omo reports it (get_available_models / get_state); only the fields the gateway uses. */
 interface OmoModel {
@@ -274,6 +300,7 @@ export class Hub {
 	private readonly questions = new Map<string, QuestionCard>();
 	private readonly rotationHeld = new Map<string, { since: number; logged: boolean }>();
 	private readonly rotationFailures = new Map<string, { message: string; at: number }>();
+	private readonly closeRecoveries = new Map<string, CloseRecovery>();
 	private readonly legacyQuestionHistoryAliases = new Map<string, string>();
 	private readonly uiOwners = new Map<string, ScopedUiOwner>();
 	private readonly uiSessionScopes = new Map<string, string>();
@@ -668,6 +695,11 @@ export class Hub {
 		this.eventCount += 1;
 		if (status !== "ready") {
 			this.generation += 1;
+			for (const recovery of this.closeRecoveries.values()) {
+				if (recovery.timer !== undefined) this.clearCloseTimer(recovery.timer);
+				recovery.cancel?.();
+			}
+			this.closeRecoveries.clear();
 			this.sessionToConv.clear();
 			for (const owner of this.uiOwners.values()) this.decisions?.release(owner);
 			this.uiOwners.clear();
@@ -681,7 +713,7 @@ export class Hub {
 				rt.wake = null;
 				rt.notified.clear();
 				const scope = this.conversationScope(conv);
-				this.dialogs.cancelScope(scope, "omo 연결이 끊겼습니다.");
+				this.dialogs.cancelScope(scope, "엔진 연결이 끊겼습니다.");
 				for (const [id, card] of this.questions) {
 					if (card.scope !== scope) continue;
 					this.questions.delete(id);
@@ -709,17 +741,22 @@ export class Hub {
 		for (const conv of conversations) {
 			if (this.omoStatus !== "ready" || generation !== this.generation) return;
 			try {
+				if (this.closeUncertain(conv.id)) {
+					await this.reconcileClose(conv.id);
+					if (this.closeUncertain(conv.id) || generation !== this.generation) continue;
+				}
+				const current = this.store.getConversation(conv.id) ?? conv;
 				const pendingUsers = this.store.pendingMainUsers(conv.id);
 				if (pendingUsers.length > 0) {
-					await this.ensureSession(conv);
+					await this.ensureSession(current);
 					for (const user of pendingUsers) {
 						const data = user.data as { text: string; images?: string[]; references?: MessageReference[] };
 						const input = referencedInput(data.text, data.images ?? [], data.references);
 						await this.prompt(conv.id, input.text, input.images, user.seq, true);
 					}
-				} else if (this.hasUnfinishedTurn(conv.id)) await this.recoverConversation(conv);
-				else if (this.openQuestionCards(conv.id, this.conversationScope(conv.id)).size > 0) await this.ensureSession(conv);
-				else if (this.store.unreportedWorkUpdates(conv.id).length > 0 || this.workSummary(conv.id).length > 0) await this.ensureSession(conv);
+				} else if (this.hasUnfinishedTurn(conv.id)) await this.recoverConversation(current);
+				else if (this.openQuestionCards(conv.id, this.conversationScope(conv.id)).size > 0) await this.ensureSession(current);
+				else if (this.store.unreportedWorkUpdates(conv.id).length > 0 || this.workSummary(conv.id).length > 0) await this.ensureSession(current);
 				// Opening main comes first. A notification ACK or worker reconciliation cannot hold readiness.
 				void this.notifyWorkUpdates(conv.id);
 			} catch (error) {
@@ -763,7 +800,13 @@ export class Hub {
 		this.decisions?.refresh();
 		const rotationDone = this.rt(convId).rotationDone;
 		if (rotationDone) await rotationDone;
-		if (this.closeUncertain(convId)) throw new Error("session_close_unknown");
+		if (this.closeUncertain(convId)) {
+			if (this.closeRecoveries.get(convId)?.exhausted) throw new Error("session_close_recovery_exhausted");
+			this.scheduleCloseRecovery(convId);
+			this.emit(convId, "notice", { kind: "session-close-recovery", level: "info",
+				message: "세션 닫기 상태를 확인하고 있습니다. 메시지는 확인 후 전달합니다." });
+			return;
+		}
 		await this.prompt(convId, prompt.text, prompt.images, input.seq, true);
 	}
 
@@ -998,7 +1041,7 @@ export class Hub {
 						&& (event.data as { input_seq?: number }).input_seq === input.seq).at(-1);
 					if ((previous?.data as { kind?: string } | undefined)?.kind !== kind) this.emit(conv, "notice", {
 						kind, input_seq: input.seq, level: "warning",
-						message: queued ? "메시지가 OMO 대기열에 남아 있습니다. 자동 재전송하지 않습니다."
+						message: queued ? "메시지가 엔진 대기열에 남아 있습니다. 자동 재전송하지 않습니다."
 							: "메시지의 실행 소비를 확인하지 못했습니다. 기록을 보존하며 자동 재전송하지 않습니다.",
 					});
 					if (queued && data.native_identity && rt.atomicQueuedResume && state &&
@@ -1127,50 +1170,33 @@ export class Hub {
 			) {
 				throw new Error("turn_running");
 			}
-			if (forced) this.retireScopedQuestions(convId, sessionId);
+			// Any rotation hands main's open waits of the closed session to the next one (inbox resume); bug 72.
+			this.retireScopedQuestions(convId, sessionId);
+			const retirement: SessionRetirement = {
+				sessionId, sessionPath: source, from, reason,
+				handoff: this.buildHandoff(convId, reason, source, handoffThrough),
+			};
+			let closeAcknowledged = false;
 			try {
 				await this.requireOmo().command("close_session", { sessionId });
-				const listed = await this.requireOmo().command<{
-					sessions?: { sessionId?: string; sessionPath?: string }[];
-				}>("list_sessions", { include_all: true, include_workers: true });
+				closeAcknowledged = true;
+				const listed = await this.requireOmo().command("list_sessions", { include_all: true, include_workers: true });
 				if (
-					generation !== this.generation || this.omoStatus !== "ready" || !Array.isArray(listed.sessions) ||
-					listed.sessions.some(
-						(entry) =>
-							!entry ||
-							typeof entry.sessionId !== "string" ||
-							typeof entry.sessionPath !== "string" ||
-							entry.sessionId === sessionId ||
-							entry.sessionPath === source,
-					)
+					generation !== this.generation || this.omoStatus !== "ready" ||
+					this.targetSessionPresent(listed, sessionId, source)
 				) {
 					throw new Error("session_retirement_unconfirmed");
 				}
 			} catch (error) {
 				this.emit(convId, "session.close.unknown", {
-					sessionPath: source,
-					sessionId,
+					...retirement,
+					closeAcknowledged,
 					message: errorMessage(error),
 				});
+				this.scheduleCloseRecovery(convId);
 				throw error;
 			}
-			const owner = this.ownerForConversation(convId, sessionId);
-			this.sessionToConv.delete(sessionId);
-			if (owner) this.releaseScopedUiOwner(owner);
-			rt.sessionId = null;
-			rt.itemId = null;
-			rt.itemText = "";
-			rt.notified.clear();
-			const to = `${this.options.sessionDir.replace(/\/$/, "")}/zgw-${conv.id}-${fileStamp(this.now())}-${crypto.randomUUID().slice(0, 8)}.jsonl`;
-			const handoff = this.buildHandoff(convId, reason, source, handoffThrough);
-			this.store.rotateThread(convId, to, new Date(this.now()).toISOString(), handoff);
-			this.emit(convId, "conversation.thread", { threadId: to });
-			this.emit(convId, "session.rotated", { reason, from, to });
-			this.emit(convId, "notice", {
-				kind: "session-rotated",
-				level: "info",
-				message: `새 omo 세션으로 교체했습니다 (${this.reasonLabel(reason)}). 화면의 대화 기록은 그대로이고, 다음 메시지부터 새 세션에서 이어집니다.`,
-			});
+			this.finishRetirement(convId, retirement);
 			return this.store.getConversation(convId) ?? conv;
 		} finally {
 			rt.rotating = false;
@@ -1186,7 +1212,120 @@ export class Hub {
 	}
 
 	private closeUncertain(conv: string): boolean {
-		return this.store.lastSeq(conv, "session.close.unknown") > this.store.lastSeq(conv, "session.rotated");
+		return this.store.lastSeq(conv, "session.close.unknown") >
+			Math.max(this.store.lastSeq(conv, "session.rotated"), this.store.lastSeq(conv, "session.close.resolved"));
+	}
+
+	/** A valid native inventory proves absence by target identity, not by the shape of unrelated worker entries. */
+	private targetSessionPresent(listed: unknown, sessionId: string, sessionPath: string): boolean {
+		if (typeof listed !== "object" || listed === null || !("sessions" in listed) || !Array.isArray(listed.sessions)) {
+			throw new Error("session_list_invalid");
+		}
+		return listed.sessions.some((entry: unknown) => typeof entry === "object" && entry !== null &&
+			(("sessionId" in entry && entry.sessionId === sessionId) || ("sessionPath" in entry && entry.sessionPath === sessionPath)));
+	}
+
+	private finishRetirement(convId: string, retirement: SessionRetirement): void {
+		const rt = this.rt(convId);
+		const owner = this.ownerForConversation(convId, retirement.sessionId);
+		this.sessionToConv.delete(retirement.sessionId);
+		if (owner) this.releaseScopedUiOwner(owner);
+		rt.sessionId = null;
+		rt.itemId = null;
+		rt.itemText = "";
+		rt.notified.clear();
+		const to = `${this.options.sessionDir.replace(/\/$/, "")}/zgw-${convId}-${fileStamp(this.now())}-${crypto.randomUUID().slice(0, 8)}.jsonl`;
+		this.store.rotateThread(convId, to, new Date(this.now()).toISOString(), retirement.handoff);
+		this.emit(convId, "conversation.thread", { threadId: to });
+		this.emit(convId, "session.rotated", { reason: retirement.reason, from: retirement.from, to });
+		this.emit(convId, "notice", { kind: "session-rotated", level: "info",
+			message: `새 엔진 세션으로 교체했습니다 (${this.reasonLabel(retirement.reason)}). 화면의 대화 기록은 그대로이고, 다음 메시지부터 새 세션에서 이어집니다.` });
+	}
+
+	private closeTimer(callback: () => void, ms: number): ReturnType<typeof setTimeout> {
+		const schedule = this.options.closeRecovery?.setTimeout;
+		return schedule ? schedule(callback, ms) : setTimeout(callback, ms);
+	}
+
+	private clearCloseTimer(timer: ReturnType<typeof setTimeout>): void {
+		(this.options.closeRecovery?.clearTimeout ?? clearTimeout)(timer);
+	}
+
+	private scheduleCloseRecovery(convId: string): void {
+		if (this.omoStatus !== "ready" || !this.closeUncertain(convId)) return;
+		const recovery = this.closeRecoveries.get(convId) ?? { attempts: 0, exhausted: false };
+		this.closeRecoveries.set(convId, recovery);
+		if (recovery.exhausted || recovery.timer !== undefined || recovery.flight) return;
+		recovery.timer = this.closeTimer(() => {
+			recovery.timer = undefined;
+			return this.reconcileClose(convId).then(() => {
+				if (this.omoStatus === "ready" && !this.closeUncertain(convId)) return this.recover();
+			});
+		}, this.options.closeRecovery?.intervalMs ?? 5_000);
+	}
+
+	/** Never re-close an uncertain native or send to it before a fresh inventory establishes ownership. */
+	private reconcileClose(convId: string): Promise<void> {
+		const recovery = this.closeRecoveries.get(convId) ?? { attempts: 0, exhausted: false };
+		this.closeRecoveries.set(convId, recovery);
+		if (recovery.flight) return recovery.flight;
+		if (recovery.exhausted || this.omoStatus !== "ready" || this.rt(convId).rotating) return Promise.resolve();
+		if (recovery.timer !== undefined) this.clearCloseTimer(recovery.timer);
+		recovery.timer = undefined;
+		const generation = this.generation;
+		const event = this.store.getEvent(this.store.lastSeq(convId, "session.close.unknown"));
+		if (!event || !this.closeUncertain(convId)) return Promise.resolve();
+		recovery.attempts += 1;
+		recovery.flight = (async () => {
+			let timeout: ReturnType<typeof setTimeout> | undefined;
+			try {
+				const cancelled = new Promise<never>((_resolve, reject) => {
+					recovery.cancel = () => reject(new Error("session_close_recovery_disconnected"));
+					timeout = this.closeTimer(() => reject(new Error("session_close_verification_timeout")),
+						this.options.closeRecovery?.timeoutMs ?? 10_000);
+				});
+				const listed = await Promise.race([
+					this.requireOmo().command("list_sessions", { include_all: true, include_workers: true }), cancelled,
+				]);
+				if (generation !== this.generation || this.omoStatus !== "ready") return;
+				const data = event.data as Partial<SessionRetirement>;
+				if (typeof data.sessionId !== "string" || typeof data.sessionPath !== "string") throw new Error("session_close_identity_missing");
+				const present = this.targetSessionPresent(listed, data.sessionId, data.sessionPath);
+				const current = this.store.getConversation(convId);
+				if (current?.threadId === data.sessionPath && !present) {
+					const reason = data.reason ?? "manual";
+					this.finishRetirement(convId, { sessionId: data.sessionId, sessionPath: data.sessionPath, from: data.from ?? data.sessionPath,
+						reason, handoff: data.handoff ?? this.buildHandoff(convId, reason, data.sessionPath, event.seq - 1) });
+				} else {
+					// A successful close releases this connection even when another attachment keeps the native alive.
+					// Reopen that source before sending again; a rejected close must not duplicate a still-owned attachment.
+					if (present && data.closeAcknowledged && current?.threadId === data.sessionPath) {
+						this.sessionToConv.delete(data.sessionId);
+						this.rt(convId).sessionId = null;
+					} else if (present && this.rt(convId).sessionId === data.sessionId && current?.threadId === data.sessionPath) {
+						// The rejected close kept its trusted open_session attachment; restore the UI authority retired above.
+						this.bindScopedUiOwner({ conv: convId, scope: this.conversationScope(convId), sessionId: data.sessionId, sessionPath: data.sessionPath });
+					}
+					this.emit(convId, "session.close.resolved", { sessionId: data.sessionId, sessionPath: data.sessionPath,
+						outcome: present ? "retained" : "superseded", attempts: recovery.attempts });
+					this.emit(convId, "notice", { kind: "session-close-resolved", level: "info",
+						message: "세션 닫기 상태를 확인했습니다. 기존 대화에서 메시지 처리를 계속합니다." });
+				}
+				this.closeRecoveries.delete(convId);
+			} catch (error) {
+				if (generation !== this.generation) return;
+				if (recovery.attempts >= (this.options.closeRecovery?.maxAttempts ?? 3)) {
+					recovery.exhausted = true;
+					this.emit(convId, "error", { message: `session_close_recovery_exhausted: ${errorMessage(error)}. 메시지는 보관 중입니다. 엔진 연결과 세션 목록을 확인한 뒤 게이트웨이를 다시 시작하세요.` });
+				}
+			} finally {
+				if (timeout !== undefined) this.clearCloseTimer(timeout);
+				recovery.cancel = undefined;
+				recovery.flight = undefined;
+				if (generation === this.generation && this.closeUncertain(convId)) this.scheduleCloseRecovery(convId);
+			}
+		})();
+		return recovery.flight;
 	}
 
 	private rotationBlocked(conv: string, inboxDecisions = true): boolean {
@@ -1228,9 +1367,9 @@ export class Hub {
 		return owned;
 	}
 
-	/** What holds automatic rotation: the rotation blockers plus an unconfirmed session close. */
+	/** What holds automatic rotation: the age rotation holds plus an unconfirmed session close. */
 	private rotationHolds(conv: string): RotationBlocker[] {
-		const holds = this.rotationBlockers(conv);
+		const holds = this.rotationHoldsFor(conv, false);
 		return this.closeUncertain(conv) ? [{ kind: "session_close_unknown" }, ...holds] : holds;
 	}
 
@@ -1254,7 +1393,10 @@ export class Hub {
 			if (!conv.threadId?.startsWith("/")) continue;
 			const blockers = this.rotationHolds(conv.id);
 			const held = blockers.length > 0 ? this.rotationHeld.get(conv.id) : undefined;
-			status[conv.id] = { blocked: blockers.length > 0, blockedSince: held ? new Date(held.since).toISOString() : null, blockers };
+			const recovery = this.closeRecoveries.get(conv.id);
+			status[conv.id] = { blocked: blockers.length > 0, blockedSince: held ? new Date(held.since).toISOString() : null, blockers,
+				...(recovery ? { closeRecovery: { state: recovery.exhausted ? "exhausted" as const : "recovering" as const,
+					attempts: recovery.attempts, maxAttempts: this.options.closeRecovery?.maxAttempts ?? 3 } } : {}) };
 		}
 		return status;
 	}
@@ -1295,9 +1437,18 @@ export class Hub {
 		}
 	}
 
-	/** What holds a rotation now: every rotation blocker, or for a forced rotation only an unfinished main turn. */
 	private rotationHeldFor(conv: string, forced: boolean): boolean {
-		return forced ? this.rotationBlockers(conv, false).some((blocker) => blocker.kind === "main_turn") : this.rotationBlocked(conv);
+		return this.rotationHoldsFor(conv, forced).length > 0;
+	}
+
+	/**
+	 * Bugs 72 and 86: what holds a rotation now. A main turn always holds; an age or manual rotation also waits for an open
+	 * approval dialog or native question. Works, their unreported reports and inbox decisions belong to the conversation,
+	 * not the session file, so they carry over to the next session (handoff, ZGW_WORK_STATE, work update wake) and never hold.
+	 */
+	private rotationHoldsFor(conv: string, forced: boolean): RotationBlocker[] {
+		return this.rotationBlockers(conv, false).filter((blocker) =>
+			blocker.kind === "main_turn" || (!forced && (blocker.kind === "dialog" || blocker.kind === "question")));
 	}
 
 	/** Bug 72 proposal 4: the user-confirmed limit this conversation's session reached, if any. */
@@ -1335,10 +1486,10 @@ export class Hub {
 	}
 
 	/** Bug 72 proposal 4: what stays open across the rotation, so the next session owns it. */
-	private handoffOpenItems(conv: string, reason: RotationReason): string[] {
+	private handoffOpenItems(conv: string): string[] {
 		const open = this.ownedOpenDecisions(conv);
 		return [
-			reason === "size" || reason === "compactions"
+			this.workSummary(conv).length > 0
 				? "끝나지 않은 작업은 그대로 이어집니다. 목록은 ZGW_WORK_STATE와 zgw_work_list로 보고, 보고하지 않은 결과는 작업 알림으로 다시 받습니다."
 				: "",
 			...(open.length > 0
@@ -1348,7 +1499,7 @@ export class Hub {
 	}
 
 	private rotationEligible(conv: ConversationInfo): boolean {
-		if (!conv.threadId?.startsWith("/") || this.closeUncertain(conv.id) || this.rotationBlocked(conv.id)) return false;
+		if (!conv.threadId?.startsWith("/") || this.closeUncertain(conv.id) || this.rotationHeldFor(conv.id, false)) return false;
 		const started = Date.parse(this.store.getSessionMeta(conv.id).startedAt ?? conv.createdAt);
 		const used = this.store.lastSeq(conv.id, "message.user") > this.store.lastSeq(conv.id, "session.rotated");
 		if (!used) return false;
@@ -1386,9 +1537,9 @@ export class Hub {
 			lines.unshift(line);
 		}
 		return [
-			`[게이트웨이 알림] 이 대화는 새 omo 세션으로 교체됐습니다 (${this.reasonLabel(reason)}).`,
+			`[게이트웨이 알림] 이 대화는 새 엔진 세션으로 교체됐습니다 (${this.reasonLabel(reason)}).`,
 			from ? `이전 세션의 전체 기록은 ${from} 에 남아 있습니다. 파일이 크니 필요할 때 필요한 부분만 검색해서 보세요.` : "",
-			...this.handoffOpenItems(conv, reason),
+			...this.handoffOpenItems(conv),
 			"아래는 직전 대화의 최근 부분입니다. 맥락으로만 참고하세요.",
 			"---",
 			...lines,
@@ -1456,7 +1607,7 @@ export class Hub {
 		if (!CONTEXT_OVERFLOW.test(message)) return { message };
 		return {
 			kind: "continuity-protected",
-			message: `${message}. 같은 omo 세션을 유지합니다. 원인을 해결한 뒤 계속할 지시를 보내 주세요. 이전 입력은 자동 재전송하지 않습니다.`,
+			message: `${message}. 같은 엔진 세션을 유지합니다. 원인을 해결한 뒤 계속할 지시를 보내 주세요. 이전 입력은 자동 재전송하지 않습니다.`,
 		};
 	}
 

package/src/main.ts

@@ -39,7 +39,7 @@ import { Hub, type ScopedQuestionFrame } from "./hub.ts";
 import { parseSummaryModels, SpeechSummarizer } from "./speech-summary.ts";
 import { MEDIA_MAX_BYTES, saveUpload, serveMedia } from "./media.ts";
 import { OmoClient } from "./omo/client.ts";
-import { bridgeLiveness, GenerationRouter, type GenerationEndpoint } from "./omo/generations.ts";
+import { bridgeLiveness, GenerationRouter, startupGenerations } from "./omo/generations.ts";
 import { activeRecord, readRegistry, slotUrl } from "./runtime/slots.ts";
 import { NATIVE_LIFECYCLE_PREFIX } from "./omo/lifecycle.ts";
 import { RECOVERY_RECEIPT_PREFIX } from "./omo/recovery-receipt.ts";
@@ -66,6 +66,7 @@ import { acceptUpdateConsent, requestUpdate, type UpdateApiDeps } from "./update
 import { PHASE_LABELS, readState, UPDATE_CONSENT_PATH, UPDATE_PATH, UPDATE_STATE_PATH, updateDir, UpdateWatcher } from "./update/state.ts";
 import { resolveTarget, tarEntry } from "./update/target.ts";
 import { registryUrl, UPDATE_CHECK_PATH, UPDATE_STATUS_PATH, UpdateChecker, versionAvailableEnvelope } from "./update/check.ts";
+import { MANUAL_PATH, serveManual } from "./manual.ts";
 import { clean as gcClean, GC_CLEAN_PATH, GC_PATH, type GcRoots, parseSelection as parseGcSelection, report as gcReport, systemGcDeps } from "./gc.ts";
 
 // Exit 0 so launchd (KeepAlive SuccessfulExit=false) does not restart a gateway that has no consent.
@@ -189,14 +190,11 @@ function requesterId(slot: RuntimeSlot): string {
 	store.setSetting(key, id);
 	return id;
 }
-// Improvement 77: with run/runtime-slots.json the gateway connects to every listed generation; without it (or with an
-// explicit ZGW_OMO_URL, as in Docker and the tests) it has one generation, as before.
-const slotRegistry = process.env.ZGW_OMO_URL ? null : readRegistry(runtime.slotsFile);
-const endpoints: GenerationEndpoint[] = slotRegistry === null
-	? [{ slot: "a", url: config.omoUrl }]
-	: slotRegistry.slots.map((record) => ({ slot: record.slot, url: slotUrl(record) }));
+// Improvement 77: with run/runtime-slots.json the gateway connects to every listed generation; without it (or with a
+// ZGW_OMO_URL that names another OMO, as in Docker and the tests) it has one generation, as before (bug 134).
+const startup = startupGenerations(process.env.ZGW_OMO_URL, `ws://127.0.0.1:${runtime.ports.bridge}`, () => readRegistry(runtime.slotsFile));
 let connectionGeneration = 0;
-const omo = new GenerationRouter(endpoints, slotRegistry === null ? "a" : activeRecord(slotRegistry).slot, {
+const omo = new GenerationRouter(startup.endpoints, startup.active, {
 	connect: (endpoint, handlers) => new OmoClient(endpoint.url, omoToken, handlers, requesterId(endpoint.slot)),
 	liveness: (endpoint) => bridgeLiveness(endpoint.url, omoToken),
 	log: (line) => console.log(line),
@@ -629,6 +627,7 @@ async function handle(req: Request, srv: Server<Conn>, trusted: boolean): Promis
 		const response = await handleProfileIcon(req, url, trusted, { icon: profileIcon, profile: () => readProfile(store), publish: (e) => publish(e) });
 		if (response) return response;
 	}
+	if (url.pathname === MANUAL_PATH) return serveManual(req, url);
 	// Plan Todo 23: the update button. The app port may ask too, but never for an update that needs a new consent.
 	if (url.pathname === UPDATE_PATH && req.method === "POST") {
 		const body = await req.json().catch(() => null) as { origin?: unknown } | null;

package/src/manual.ts

@@ -0,0 +1,31 @@
+import { join } from "node:path";
+
+/**
+ * The user manual (docs/manual.md, docs/manual.ko.md) for the web 설정 "매뉴얼" button and the app's work status screen.
+ * Read only, on the web port and, behind the app device gate, on the app port. Korean is the default language.
+ */
+export const MANUAL_PATH = "/api/manual";
+export const MANUAL_DIR = join(import.meta.dir, "..", "docs");
+export type ManualLang = "ko" | "en";
+
+/** The `lang` query value as a language: missing or empty is Korean; anything but `ko` or `en` is null. */
+export function manualLang(value: string | null): ManualLang | null {
+	if (value === null || value === "" || value === "ko") return "ko";
+	return value === "en" ? "en" : null;
+}
+
+export function manualFile(lang: ManualLang): string {
+	return lang === "en" ? "manual.md" : "manual.ko.md";
+}
+
+/** `GET /api/manual?lang=ko|en`: the Markdown text; 400 for another language, 404 with a hint when the file is missing. */
+export async function serveManual(req: Request, url: URL, dir: string = MANUAL_DIR): Promise<Response> {
+	if (req.method !== "GET") return Response.json({ error: "method_not_allowed" }, { status: 405 });
+	const lang = manualLang(url.searchParams.get("lang"));
+	if (lang === null) return Response.json({ error: "unknown_lang", message: "lang은 ko 또는 en입니다." }, { status: 400 });
+	const file = Bun.file(join(dir, manualFile(lang)));
+	if (!(await file.exists())) {
+		return Response.json({ error: "manual_missing", message: "이 설치에는 매뉴얼 파일이 없습니다. 게이트웨이를 업데이트하세요." }, { status: 404 });
+	}
+	return new Response(file, { headers: { "content-type": "text/markdown; charset=utf-8", "cache-control": "no-cache", "content-language": lang } });
+}

package/src/omo/generations.ts

@@ -1,4 +1,5 @@
 import type { RuntimeSlot } from "../runtime/paths.ts";
+import { activeRecord, type SlotRegistry, slotUrl } from "../runtime/slots.ts";
 import type { OmoClientHandlers, OmoEvent, OmoStatus } from "./client.ts";
 
 /**
@@ -55,18 +56,43 @@ type Listed = { sessionId?: unknown; sessionPath?: unknown };
 
 const LIVENESS_TIMEOUT_MS = 5000;
 
+/**
+ * Bug 134: an installed gateway gets ZGW_OMO_URL from config.env, and it names this Mac's own slot a bridge. That value
+ * must not hide run/runtime-slots.json: when the update handoff restarts the gateway, the generation that still holds the
+ * sessions can be slot b. The registry is used unless ZGW_OMO_URL names another OMO (Docker, tests).
+ */
+export function startupGenerations(explicitUrl: string | undefined, localUrl: string, registry: () => SlotRegistry | null): { endpoints: GenerationEndpoint[]; active: RuntimeSlot } {
+	const url = explicitUrl || localUrl;
+	const listed = isLocalBridge(url, localUrl) ? registry() : null;
+	if (listed === null) return { endpoints: [{ slot: "a", url }], active: "a" };
+	return { endpoints: listed.slots.map((record) => ({ slot: record.slot, url: slotUrl(record) })), active: activeRecord(listed).slot };
+}
+
+function isLocalBridge(url: string, localUrl: string): boolean {
+	if (!URL.canParse(url)) return false;
+	const given = new URL(url);
+	const local = new URL(localUrl);
+	return given.protocol === local.protocol && given.port === local.port && given.pathname === "/" && given.search === "" &&
+		(given.hostname === "127.0.0.1" || given.hostname === "localhost");
+}
+
 /**
  * Bug 118: after a bridge restart the previous OMO host can still hold its claim on a session file for a moment (the
  * bridge's SIGTERM ends the host without waiting for it). The new host answers open_session with `session_path_in_use`
  * and `errorData.retry_after_ms` until that claim is gone; OMO documents the refusal as retryable. The open waits it out
  * for at most SESSION_PATH_WAIT_MS and never takes the path from the other host.
+ * Bug 134: `session_held` (a live holder outside this host's daemon family, e.g. a draining older generation) is waited
+ * out the same way; it carries no retry hint, so the open waits SESSION_PATH_RETRY_MS between tries.
  */
 export const SESSION_PATH_WAIT_MS = 60_000;
 export const SESSION_PATH_RETRY_MS = 2000;
 
-/** Milliseconds to wait before reopening after this error, or null when the error is not a held session path. */
+/** Milliseconds to wait before reopening after this error, or null when the error is not a held session. */
 export function sessionPathRetryMs(error: unknown): number | null {
-	if (typeof error !== "object" || error === null || (error as { code?: unknown }).code !== "session_path_in_use") return null;
+	if (typeof error !== "object" || error === null) return null;
+	const code = (error as { code?: unknown }).code;
+	if (code === "session_held") return SESSION_PATH_RETRY_MS;
+	if (code !== "session_path_in_use") return null;
 	const data = (error as { errorData?: unknown }).errorData;
 	const hint = typeof data === "object" && data !== null ? (data as { retry_after_ms?: unknown }).retry_after_ms : undefined;
 	return typeof hint === "number" && hint > 0 ? hint : SESSION_PATH_RETRY_MS;

package/src/omo-check.ts

@@ -45,8 +45,8 @@ export class OmoCheckScheduler {
 		const version = body.version;
 		const result = this.store.createOmoCheck(version, {
 			ownerConv: "main",
-			title: `OMO ${version} 검증`,
-			goal: `OMO ${version} 후보 패치와 교체 가능 여부 검증 (운영 교체 금지)`,
+			title: `엔진 ${version} 검증`,
+			goal: `엔진 ${version} 후보 패치와 교체 가능 여부 검증 (운영 교체 금지)`,
 			cwd: this.options.cwd,
 			sessionPath: join(this.options.sessionDir, `zgw-omo-check-${version}.jsonl`),
 			requestKey: `omo-check:${version}`,

package/src/transcript.ts

@@ -62,7 +62,7 @@ export function toRecord(type: string, data: unknown, base: { ts: string; conv:
 	if (type === "message.user" && typeof d.text === "string") return { ...base, role: "user", text: d.text, src: d.src, trust: d.trust };
 	if (type === "message.final" && typeof d.text === "string") return { ...base, role: "assistant", text: d.text };
 	if (type === "session.rotated") {
-		return { ...base, role: "system", event: "session.rotated", text: `omo 세션 교체 (${String(d.reason)}): ${String(d.from)} -> ${String(d.to)}` };
+		return { ...base, role: "system", event: "session.rotated", text: `엔진 세션 교체 (${String(d.reason)}): ${String(d.from)} -> ${String(d.to)}` };
 	}
 	return null;
 }

package/src/update/handoff.ts

@@ -59,7 +59,7 @@ export const POLL_MS = 1000;
 
 export type HandoffResult = "promoted" | "untouched_failure" | "failure";
 
-const NOT_UP = `${BRIDGE_START_WAIT_MS / 1000}초 안에 OMO가 뜨지 않았습니다`;
+const NOT_UP = `${BRIDGE_START_WAIT_MS / 1000}초 안에 엔진이 뜨지 않았습니다`;
 
 function legacyRegistry(port: number, version: string, now: number): SlotRegistry {
 	return { schema: 1, slots: [{ slot: "a", state: "active", port, version, snapshot: null, engine: null, since: new Date(now).toISOString() }] };

package/src/usage.ts

@@ -279,7 +279,7 @@ function stamp(ms: number, timeZone: string | undefined): string {
 	return `${part("month")}/${part("day")} ${part("hour")}:${part("minute")}`;
 }
 
-const STATUS_TEXT = { expired: "토큰 만료 (OMO가 다음 사용 때 갱신)", unsupported: "사용량 API 없음" } as const;
+const STATUS_TEXT = { expired: "토큰 만료 (엔진이 다음 사용 때 갱신)", unsupported: "사용량 API 없음" } as const;
 
 export function formatUsageReport(rows: readonly UsageRow[], timeZone?: string): string {
 	if (rows.length === 0) return "계정 사용량\n로그인한 모델 계정이 없습니다.";