zigmini 0.8.0-beta.5 → 0.8.0-beta.7

package/src/cli/pair.ts

@@ -1,7 +1,8 @@
 import type { QRCodeFactory } from "../../web/vendor/qrcode.js";
+import { type Language, message } from "./messages.ts";
 
 /**
- * `zigmini pair` and the last step of `zigmini setup` (plan Todo 15): the phone enrollment QR drawn in the terminal with
+ * `zigmini pair` (plan Todo 15): the phone enrollment QR drawn in the terminal with
  * the same vendored qrcode-generator the web settings use. The token stays inside the QR; no text here carries it.
  * The vendored library is loaded on demand so that `src/` keeps importing without `web/` (the mutation runs copy only `src/`).
  */
@@ -9,12 +10,12 @@ import type { QRCodeFactory } from "../../web/vendor/qrcode.js";
 export const PAIR_CREATED_BY = "cli";
 export const QR_MARGIN = 4;
 export const PAIR_ERRORS = {
-	gateway_down: "게이트웨이에 연결하지 못했습니다. `zigmini start`로 시작한 뒤 다시 하세요.",
-	access_url_unknown: "접속 주소를 알 수 없습니다. 맥이 Wi-Fi에 연결되어 있는지 확인하세요.",
-	bad_response: "게이트웨이가 알 수 없는 응답을 보냈습니다.",
-	apk_unavailable: "이 설치에는 내려받을 앱(APK)이 없습니다.",
+	gateway_down: message("ko", "gatewayDown"),
+	access_url_unknown: message("ko", "accessGuidance"),
+	bad_response: message("ko", "badResponse"),
+	apk_unavailable: message("ko", "apkUnavailable"),
 } as const;
-export const APK_INSTALL_HINT = "출처를 알 수 없는 앱 설치 허가가 필요합니다";
+export const APK_INSTALL_HINT = message("ko", "apkPermission");
 export type PairErrorReason = keyof typeof PAIR_ERRORS | `http_${number}`;
 
 export class PairError extends Error {
@@ -32,6 +33,7 @@ export interface Enrollment {
 export type FetchLike = (url: string, init: RequestInit) => Promise<{ readonly status: number; json(): Promise<unknown> }>;
 
 export interface PairDeps {
+	readonly lang?: Language;
 	readonly fetch: FetchLike;
 	readonly webPort: number;
 	readonly now: () => number;
@@ -78,22 +80,27 @@ export function minutesLeft(expiresAt: number, now: number): number {
 }
 
 /** The terminal text: caption, QR and the address. It never contains the token or the payload. */
-export function enrollmentText(qrcode: QRCodeFactory, enrollment: Enrollment, now: number): string {
-	return `폰 등록 QR (${minutesLeft(enrollment.expiresAt, now)}분 안에 한 번만 쓸 수 있음)\n${qrAnsi(qrcode, enrollment.payload)}`
-		+ `접속 주소: ${enrollment.url}\n폰의 지그미니 앱에서 QR을 찍으세요. 만료되면 \`zigmini pair\`로 새 QR을 만듭니다.\n`;
+export function enrollmentText(qrcode: QRCodeFactory, enrollment: Enrollment, now: number, lang: Language = "ko"): string {
+	return message(lang, "enrollmentText", { minutes: minutesLeft(enrollment.expiresAt, now), qr: qrAnsi(qrcode, enrollment.payload), url: enrollment.url });
 }
 
-function failureReason(error: unknown): string {
+function failureReason(error: unknown, lang: Language): string {
 	const reason = error instanceof PairError ? error.reason : error instanceof Error ? error.message : String(error);
-	return (PAIR_ERRORS as Record<string, string>)[reason] ?? `게이트웨이 응답 ${reason}`;
+	switch (reason) {
+		case "gateway_down": return message(lang, "gatewayDown");
+		case "access_url_unknown": return message(lang, "accessGuidance");
+		case "bad_response": return message(lang, "badResponse");
+		case "apk_unavailable": return message(lang, "apkUnavailable");
+		default: return message(lang, "gatewayResponse", { reason });
+	}
 }
 
-export function pairFailureLine(error: unknown): string {
-	return `폰 등록 QR을 만들지 못했습니다: ${failureReason(error)}`;
+export function pairFailureLine(error: unknown, lang: Language = "ko"): string {
+	return message(lang, "pairFailed", { reason: failureReason(error, lang) });
 }
 
-export function apkFailureLine(error: unknown): string {
-	return `앱 내려받기 QR을 만들지 못했습니다: ${failureReason(error)}`;
+export function apkFailureLine(error: unknown, lang: Language = "ko"): string {
+	return message(lang, "apkFailed", { reason: failureReason(error, lang) });
 }
 
 export interface ApkLink {
@@ -122,33 +129,33 @@ export async function mintApkLink(fetchFn: FetchLike, webPort: number): Promise<
 }
 
 /** The terminal text for the APK QR: caption, QR, the address without the link token, and the install permission hint. */
-export function apkLinkText(qrcode: QRCodeFactory, link: ApkLink, now: number): string {
-	return `앱 내려받기 QR (지그미니 ${link.versionName}, ${minutesLeft(link.expiresAt, now)}분 동안 쓸 수 있음)\n${qrAnsi(qrcode, link.url)}`
-		+ `접속 주소: ${new URL(link.url).origin}\n폰 카메라로 QR을 찍어 APK를 받으세요. ${APK_INSTALL_HINT}. 만료되면 \`zigmini pair --apk\`로 새 QR을 만듭니다.\n`;
+export function apkLinkText(qrcode: QRCodeFactory, link: ApkLink, now: number, lang: Language = "ko"): string {
+	return message(lang, "apkText", { version: link.versionName, minutes: minutesLeft(link.expiresAt, now), qr: qrAnsi(qrcode, link.url), url: new URL(link.url).origin, permission: message(lang, "apkPermission") });
 }
 
-export async function apkQr(fetchFn: FetchLike, webPort: number, now: () => number): Promise<string> {
+export async function apkQr(fetchFn: FetchLike, webPort: number, now: () => number, lang: Language = "ko"): Promise<string> {
 	const link = await mintApkLink(fetchFn, webPort);
-	return apkLinkText(await loadQrcode(), link, now());
+	return apkLinkText(await loadQrcode(), link, now(), lang);
 }
 
 async function loadQrcode(): Promise<QRCodeFactory> {
 	return (await import("../../web/vendor/qrcode.js")).default;
 }
 
-/** The QR text for setup's last step and `zigmini pair`; throws PairError when the gateway cannot give a token. */
-export async function enrollmentQr(fetchFn: FetchLike, webPort: number, now: () => number): Promise<string> {
+/** The QR text for `zigmini pair`; throws PairError when the gateway cannot give a token. */
+export async function enrollmentQr(fetchFn: FetchLike, webPort: number, now: () => number, lang: Language = "ko"): Promise<string> {
 	const enrollment = await mintEnrollment(fetchFn, webPort);
-	return enrollmentText(await loadQrcode(), enrollment, now());
+	return enrollmentText(await loadQrcode(), enrollment, now(), lang);
 }
 
 /** `zigmini pair` draws the enrollment QR; `zigmini pair --apk` draws the APK download QR instead. */
 export async function pairCommand(deps: PairDeps, apk = false): Promise<number> {
+	const lang = deps.lang ?? "ko";
 	try {
-		deps.out(apk ? await apkQr(deps.fetch, deps.webPort, deps.now) : await enrollmentQr(deps.fetch, deps.webPort, deps.now));
+		deps.out(apk ? await apkQr(deps.fetch, deps.webPort, deps.now, lang) : await enrollmentQr(deps.fetch, deps.webPort, deps.now, lang));
 		return 0;
 	} catch (error) {
-		deps.err(`${apk ? apkFailureLine(error) : pairFailureLine(error)}\n`);
+		deps.err(`${apk ? apkFailureLine(error, lang) : pairFailureLine(error, lang)}\n`);
 		return 1;
 	}
 }

package/src/cli/rotate-main.ts

@@ -0,0 +1,411 @@
+import { spawn } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { agentDir } from "../model-accounts.ts";
+import { ROTATION_HELD_MESSAGE } from "../protocol.ts";
+import { type LaunchdContext, type LaunchdDeps, ownProcess, parseConfigEnv, startCommand, stopCommand } from "./launchd.ts";
+
+/**
+ * Improvement 162: `zigmini rotate-main` moves the main conversation to a fresh engine session the same way the web
+ * "새 세션" button does (conversation.rotate), from a command that outlives the engine that asked for it.
+ *
+ * The command starts a detached runner (its own session, so stopping the engine does not kill it) and returns. The
+ * runner waits until no main turn holds the session, stops on any other holder, sends the rotation and checks the
+ * session.rotated event. With --restart it first stops the gateway, checks that every process is gone and that no
+ * main session is parked for the next engine, starts the gateway again and only then rotates. Every step is a line in
+ * <home>/logs/rotate-main.log.
+ */
+
+export const ROTATE_COMMAND = "rotate-main";
+export const ROTATE_RUN_COMMAND = "_rotate-main-run";
+export const LOG_FILE = "rotate-main.log";
+export const DEFAULT_WAIT_S = 900;
+export const MAX_WAIT_S = 86_400;
+export const POLL_MS = 5_000;
+export const ROTATED_WAIT_MS = 120_000;
+export const PROCESSES_GONE_MS = 60_000;
+export const CONV = "main";
+
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_BLOCKED = 3;
+export const EXIT_TIMEOUT = 4;
+
+export interface RotateOptions {
+	readonly restart: boolean;
+	readonly waitMs: number;
+	readonly foreground: boolean;
+}
+
+export const ROTATE_HELP = `사용법: zigmini rotate-main [--restart] [--wait <초>] [--foreground]
+  main 대화를 새 엔진 세션으로 교체합니다(웹의 "새 세션" 버튼과 같은 요청).
+  main 차례가 진행 중이면 끝날 때까지 기다립니다(--wait, 기본 ${DEFAULT_WAIT_S}초).
+  다른 원인이 교체를 막으면 그 원인을 로그에 쓰고 끝납니다.
+  --restart     먼저 게이트웨이를 멈추고(zigmini stop) 다시 켠 뒤(zigmini start) 교체합니다
+  --foreground  분리하지 않고 이 터미널에서 실행합니다(기본: 분리 실행, 결과는 로그에)
+  로그: <홈>/logs/${LOG_FILE}`;
+
+export function parseRotateArgs(args: readonly string[]): RotateOptions | string {
+	let restart = false;
+	let foreground = false;
+	let waitS = DEFAULT_WAIT_S;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--restart" && !restart) restart = true;
+		else if (arg === "--foreground" && !foreground) foreground = true;
+		else if (arg === "--wait" && i + 1 < args.length) {
+			const value = args[++i]!;
+			if (!/^\d+$/.test(value) || Number(value) < 1 || Number(value) > MAX_WAIT_S) return `--wait 값은 1~${MAX_WAIT_S} 사이의 초입니다: ${value}`;
+			waitS = Number(value);
+		} else return `잘못된 인자: ${arg}`;
+	}
+	return { restart, waitMs: waitS * 1000, foreground };
+}
+
+/** The arguments the detached runner gets: the parsed options again, always in the foreground. */
+export function runnerArgs(options: RotateOptions): string[] {
+	return [ROTATE_RUN_COMMAND, ...(options.restart ? ["--restart"] : []), "--wait", String(options.waitMs / 1000)];
+}
+
+export interface Blocker {
+	readonly kind: string;
+	readonly id?: string;
+	readonly workId?: string;
+	readonly state?: string;
+	readonly reason?: string;
+}
+
+export interface HealthView {
+	readonly ready: boolean;
+	readonly omo: string | null;
+	readonly maintenanceHeld: boolean;
+	/** main's rotation entry; null when main has no engine session yet. */
+	readonly blockers: readonly Blocker[] | null;
+	readonly active: string | null;
+}
+
+export function readHealth(body: unknown): HealthView | null {
+	if (typeof body !== "object" || body === null) return null;
+	const health = body as { ok?: unknown; omo?: unknown; maintenanceHeld?: unknown; rotation?: unknown; runtime?: unknown };
+	const omo = typeof health.omo === "string" ? health.omo : null;
+	const rotation = typeof health.rotation === "object" && health.rotation !== null ? (health.rotation as Record<string, unknown>)[CONV] : undefined;
+	const raw = typeof rotation === "object" && rotation !== null ? (rotation as { blockers?: unknown }).blockers : undefined;
+	const blockers = Array.isArray(raw)
+		? raw.filter((entry): entry is Blocker => typeof entry === "object" && entry !== null && typeof (entry as Blocker).kind === "string")
+		: null;
+	const runtime = health.runtime as { active?: unknown } | undefined;
+	return {
+		ready: health.ok === true && omo === "ready",
+		omo,
+		maintenanceHeld: health.maintenanceHeld === true,
+		blockers,
+		active: typeof runtime?.active === "string" ? runtime.active : null,
+	};
+}
+
+export function describeBlockers(blockers: readonly Blocker[]): string {
+	return blockers.map((b) => [b.kind, b.id, b.workId, b.state, b.reason].filter(Boolean).join(":")).join(", ");
+}
+
+export type Gate =
+	| { readonly kind: "ready" }
+	| { readonly kind: "wait"; readonly why: string }
+	| { readonly kind: "blocked"; readonly why: string };
+
+/** What the health says about rotating main now: a main turn, an update or a not-ready engine is waited for; anything else stops. */
+export function gate(health: HealthView | null): Gate {
+	if (health === null) return { kind: "wait", why: "health 응답 없음" };
+	if (!health.ready) return { kind: "wait", why: `엔진 준비 안 됨(omo=${health.omo ?? "?"})` };
+	if (health.maintenanceHeld) return { kind: "wait", why: "업데이트·유지보수 진행 중" };
+	if (health.blockers === null) return { kind: "blocked", why: "main 대화에 엔진 세션이 없습니다(교체할 세션 없음)" };
+	const other = health.blockers.filter((blocker) => blocker.kind !== "main_turn");
+	if (other.length > 0) return { kind: "blocked", why: `교체를 막는 원인: ${describeBlockers(health.blockers)}` };
+	if (health.blockers.length > 0) return { kind: "wait", why: `main 차례 진행 중: ${describeBlockers(health.blockers)}` };
+	return { kind: "ready" };
+}
+
+export type RotateOutcome =
+	| { readonly kind: "rotated"; readonly before: string | null; readonly from: string; readonly to: string }
+	| { readonly kind: "held"; readonly message: string }
+	| { readonly kind: "error"; readonly message: string }
+	| { readonly kind: "timeout" };
+
+/** What is wrong with a reported rotation: it must leave the session main had, for a new file in the same folder. */
+export function rotationProblems(outcome: { before: string | null; from: string; to: string }, exists: (path: string) => boolean): string[] {
+	const problems: string[] = [];
+	if (outcome.before !== null && outcome.from !== outcome.before) problems.push(`이전 세션이 다릅니다(교체 전 ${outcome.before})`);
+	if (outcome.to === outcome.from) problems.push("새 세션 파일이 이전과 같습니다");
+	if (dirname(outcome.to) !== dirname(outcome.from)) problems.push("새 세션 파일이 다른 폴더에 있습니다");
+	if (!basename(outcome.to).startsWith(`zgw-${CONV}-`)) problems.push("새 세션 파일 이름이 main 세션이 아닙니다");
+	if (!exists(outcome.from)) problems.push("이전 세션 파일이 디스크에 없습니다");
+	return problems;
+}
+
+export interface RotateDeps {
+	readonly health: () => Promise<unknown>;
+	readonly rotate: (timeoutMs: number) => Promise<RotateOutcome>;
+	readonly exists: (path: string) => boolean;
+	readonly now: () => number;
+	readonly sleep: (ms: number) => Promise<void>;
+	readonly log: (step: string, result: string) => void;
+	readonly out: (text: string) => void;
+	readonly stop: () => Promise<number>;
+	readonly start: () => Promise<number>;
+	/** This installation's gateway, bridge and engine processes still running ("pid command"). */
+	readonly processes: () => readonly string[];
+	/** Parked engine records of main sessions the next engine would reopen. */
+	readonly parkedMain: () => readonly string[];
+}
+
+type Waited = { readonly kind: "ready"; readonly health: HealthView } | { readonly kind: "blocked"; readonly why: string } | { readonly kind: "timeout"; readonly why: string };
+
+async function waitIdle(deps: RotateDeps, deadline: number): Promise<Waited> {
+	let last = "";
+	for (;;) {
+		const health = readHealth(await deps.health());
+		const state = gate(health);
+		if (state.kind === "ready") return { kind: "ready", health: health! };
+		if (state.kind === "blocked") return state;
+		if (state.why !== last) deps.log("wait", state.why);
+		last = state.why;
+		if (deps.now() >= deadline) return { kind: "timeout", why: state.why };
+		await deps.sleep(POLL_MS);
+	}
+}
+
+function finish(deps: RotateDeps, code: number, result: string): number {
+	deps.log("result", result);
+	deps.out(`${result}\n`);
+	return code;
+}
+
+function stopped(deps: RotateDeps, waited: Exclude<Waited, { kind: "ready" }>, waitMs: number): number {
+	if (waited.kind === "blocked") return finish(deps, EXIT_BLOCKED, `BLOCKED 교체하지 않았습니다. ${waited.why}`);
+	return finish(deps, EXIT_TIMEOUT, `TIMEOUT ${waitMs / 1000}초 안에 main 차례가 끝나지 않아 교체하지 않았습니다. 마지막 상태: ${waited.why}`);
+}
+
+/** Waits for main to be free and rotates it; a rotation refused because a turn started meanwhile waits again. */
+async function rotateWhenIdle(deps: RotateDeps, options: RotateOptions, deadline: number): Promise<number> {
+	for (;;) {
+		const waited = await waitIdle(deps, deadline);
+		if (waited.kind !== "ready") return stopped(deps, waited, options.waitMs);
+		deps.log("rotate", "conversation.rotate 보냄");
+		const outcome = await deps.rotate(ROTATED_WAIT_MS);
+		if (outcome.kind === "held") {
+			deps.log("rotate", `거절됨, 다시 기다림: ${outcome.message}`);
+			if (deps.now() >= deadline) return finish(deps, EXIT_TIMEOUT, `TIMEOUT 교체 요청이 계속 거절되었습니다: ${outcome.message}`);
+			await deps.sleep(POLL_MS);
+			continue;
+		}
+		if (outcome.kind === "timeout") return finish(deps, EXIT_FAILED, `FAILED ${ROTATED_WAIT_MS / 1000}초 안에 session.rotated 이벤트가 오지 않았습니다`);
+		if (outcome.kind === "error") return finish(deps, EXIT_FAILED, `FAILED 게이트웨이가 교체를 거절했습니다: ${outcome.message}`);
+		deps.log("rotated", `이전 ${outcome.from} → 새 ${outcome.to}`);
+		const problems = rotationProblems(outcome, deps.exists);
+		if (problems.length > 0) return finish(deps, EXIT_FAILED, `FAILED 교체 이벤트 확인 실패: ${problems.join("; ")}`);
+		return finish(deps, EXIT_OK, `ROTATED 이전 ${outcome.from} → 새 ${outcome.to}`);
+	}
+}
+
+async function waitProcessesGone(deps: RotateDeps): Promise<readonly string[]> {
+	const deadline = deps.now() + PROCESSES_GONE_MS;
+	for (;;) {
+		const left = deps.processes();
+		if (left.length === 0 || deps.now() >= deadline) return left;
+		await deps.sleep(1000);
+	}
+}
+
+/** After a failed step: start the gateway again so the Mac is not left without it, and never rotate. */
+async function recover(deps: RotateDeps, why: string): Promise<number> {
+	deps.log("recover", `${why}; 게이트웨이를 다시 켭니다`);
+	let code = await deps.start();
+	if (code !== 0) {
+		deps.log("recover", `zigmini start exit=${code}; 한 번 더 시도합니다`);
+		code = await deps.start();
+	}
+	return finish(deps, EXIT_FAILED, `FAILED ${why}. 교체 요청은 보내지 않았습니다. 다시 켜기 ${code === 0 ? "성공" : `실패(exit=${code}) - zigmini start를 직접 실행하세요`}`);
+}
+
+export async function runRotate(options: RotateOptions, deps: RotateDeps): Promise<number> {
+	deps.log("start", `mode=${options.restart ? "restart" : "rotate"} wait=${options.waitMs / 1000}s`);
+	const deadline = deps.now() + options.waitMs;
+	if (!options.restart) return await rotateWhenIdle(deps, options, deadline);
+
+	const waited = await waitIdle(deps, deadline);
+	if (waited.kind !== "ready") return stopped(deps, waited, options.waitMs);
+	const parkedBefore = deps.parkedMain();
+	if (parkedBefore.length > 0) {
+		return finish(deps, EXIT_BLOCKED, `BLOCKED 멈추기 전 확인: 다음 엔진이 다시 열 main 세션 기록이 있습니다(${parkedBefore.join(", ")}). 게이트웨이는 그대로 둡니다`);
+	}
+	deps.log("precheck", `active=${waited.health.active ?? "?"} parked-main=0`);
+	const stop = await deps.stop();
+	deps.log("stop", `zigmini stop exit=${stop}`);
+	if (stop !== 0) return await recover(deps, `zigmini stop 실패(exit=${stop})`);
+	const left = await waitProcessesGone(deps);
+	if (left.length > 0) return await recover(deps, `${PROCESSES_GONE_MS / 1000}초 뒤에도 남은 프로세스: ${left.join(" | ")}`);
+	deps.log("stop", "게이트웨이·브리지·엔진 프로세스 모두 꺼짐");
+	const parked = deps.parkedMain();
+	if (parked.length > 0) {
+		return finish(deps, EXIT_BLOCKED, `BLOCKED 멈춘 뒤 확인: 다음 엔진이 다시 열 main 세션 기록이 있습니다(${parked.join(", ")}). 게이트웨이를 다시 켜지 않았습니다. 확인 뒤 zigmini start를 실행하세요`);
+	}
+	deps.log("precheck", "멈춘 뒤 parked-main=0");
+	const start = await deps.start();
+	deps.log("start", `zigmini start exit=${start}`);
+	if (start !== 0) return await recover(deps, `zigmini start 실패(exit=${start})`);
+	const after = readHealth(await deps.health());
+	deps.log("ready", `omo=${after?.omo ?? "?"} active=${after?.active ?? "?"}`);
+	return await rotateWhenIdle(deps, options, Math.max(deadline, deps.now() + options.waitMs));
+}
+
+interface SnapshotConversation { readonly id?: unknown; readonly threadId?: unknown }
+
+/** One conversation.rotate over the gateway WebSocket, read like the web page: hello, the snapshot, then the request. */
+export function socketRotate(url: string, timeoutMs: number): Promise<RotateOutcome> {
+	return new Promise((resolve) => {
+		const ws = new WebSocket(url);
+		let before: string | null = null;
+		let sent = false;
+		let done = false;
+		const end = (outcome: RotateOutcome): void => {
+			if (done) return;
+			done = true;
+			clearTimeout(timer);
+			try { ws.close(); } catch { /* already closed */ }
+			resolve(outcome);
+		};
+		const timer = setTimeout(() => end({ kind: "timeout" }), timeoutMs);
+		ws.onopen = () => ws.send(JSON.stringify({ type: "hello", data: { client: "web-dev", version: "0.1.0" } }));
+		ws.onmessage = (event) => {
+			let message: { type?: unknown; conv?: unknown; data?: unknown };
+			try {
+				message = JSON.parse(String(event.data));
+			} catch {
+				return;
+			}
+			if (message.type === "state.snapshot" && !sent) {
+				const conversations = (message.data as { conversations?: unknown } | null)?.conversations;
+				const main = Array.isArray(conversations) ? (conversations as SnapshotConversation[]).find((conv) => conv?.id === CONV) : undefined;
+				before = typeof main?.threadId === "string" ? main.threadId : null;
+				sent = true;
+				ws.send(JSON.stringify({ type: "conversation.rotate", conv: CONV }));
+				return;
+			}
+			if (!sent || message.conv !== CONV) return;
+			const data = (message.data ?? {}) as { from?: unknown; to?: unknown; message?: unknown };
+			if (message.type === "session.rotated" && typeof data.from === "string" && typeof data.to === "string") {
+				end({ kind: "rotated", before, from: data.from, to: data.to });
+			} else if (message.type === "error") {
+				const text = typeof data.message === "string" ? data.message : JSON.stringify(data);
+				end(text === ROTATION_HELD_MESSAGE ? { kind: "held", message: text } : { kind: "error", message: text });
+			}
+		};
+		ws.onerror = () => end({ kind: "error", message: "WebSocket 연결 오류" });
+		ws.onclose = () => end({ kind: "error", message: "WebSocket 연결이 닫혔습니다" });
+	});
+}
+
+/** Main session records the engine parked for its successor: <agent dir>/rpc-host-daemon/<host>/handover-parked/*.json. */
+export function parkedMainSessions(dir: string): string[] {
+	const root = join(dir, "rpc-host-daemon");
+	if (!existsSync(root)) return [];
+	const found: string[] = [];
+	for (const host of readdirSync(root).sort()) {
+		const parked = join(root, host, "handover-parked");
+		if (!existsSync(parked)) continue;
+		for (const name of readdirSync(parked).sort()) {
+			if (!name.endsWith(".json")) continue;
+			try {
+				const entry = JSON.parse(readFileSync(join(parked, name), "utf8")) as { sessionPath?: unknown };
+				if (typeof entry.sessionPath === "string" && basename(entry.sessionPath).startsWith(`zgw-${CONV}-`)) found.push(entry.sessionPath);
+			} catch {
+				found.push(`${join(parked, name)} (읽을 수 없음)`);
+			}
+		}
+	}
+	return found;
+}
+
+/** This installation's gateway, bridge and engine processes: the package's two services, or anything run from the home folder. */
+export function leftoverProcesses(psOutput: string, ctx: LaunchdContext, self: readonly number[]): string[] {
+	const services = [join(ctx.packageRoot, "src/main.ts"), join(ctx.packageRoot, "host/omo-bridge/bridge.ts")];
+	const left: string[] = [];
+	for (const line of psOutput.split("\n")) {
+		const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+		if (!match) continue;
+		const pid = Number(match[1]);
+		const command = match[2]!;
+		if (self.includes(pid) || command.includes("/src/cli/main.ts") || !ownProcess(command, ctx)) continue;
+		if (!command.includes(`${ctx.paths.home}/`) && !services.some((service) => command.includes(service))) continue;
+		left.push(`${pid} ${command}`);
+	}
+	return left;
+}
+
+export function logLine(at: Date, pid: number, step: string, result: string): string {
+	return `${at.toISOString()} [${pid}] ${step}: ${result.replace(/\s+/g, " ")}\n`;
+}
+
+export function systemRotateDeps(launchd: LaunchdDeps, ctx: LaunchdContext): RotateDeps {
+	const logFile = join(ctx.paths.logs, LOG_FILE);
+	const config = (): Record<string, string> => {
+		const text = launchd.readText(join(ctx.paths.home, "config.env"));
+		return text === null ? {} : parseConfigEnv(text);
+	};
+	const quiet: LaunchdDeps = { ...launchd, out: () => {}, err: (text) => appendFileSync(logFile, logLine(new Date(), process.pid, "launchd", text)) };
+	return {
+		health: async () => {
+			try {
+				const response = await fetch(`http://127.0.0.1:${ctx.paths.ports.web}/api/health`, { signal: AbortSignal.timeout(15_000) });
+				return await response.json();
+			} catch {
+				return null;
+			}
+		},
+		rotate: (timeoutMs) => socketRotate(`ws://127.0.0.1:${ctx.paths.ports.web}/ws`, timeoutMs),
+		exists: existsSync,
+		now: Date.now,
+		sleep: (ms) => Bun.sleep(ms),
+		log: (step, result) => {
+			mkdirSync(ctx.paths.logs, { recursive: true });
+			appendFileSync(logFile, logLine(new Date(), process.pid, step, result));
+		},
+		out: (text) => { process.stdout.write(text); },
+		stop: () => stopCommand(quiet, ctx, false),
+		start: () => startCommand(quiet, ctx),
+		processes: () => {
+			const ps = Bun.spawnSync(["ps", "-axww", "-o", "pid=,command="]);
+			return leftoverProcesses(ps.stdout.toString(), ctx, [process.pid, process.ppid]);
+		},
+		parkedMain: () => parkedMainSessions(agentDir({ ...ctx.env, ...config() })),
+	};
+}
+
+/** Starts the runner in its own session (setsid) with no terminal, so it survives the engine or shell that called it. */
+export function launchDetached(ctx: LaunchdContext, options: RotateOptions): number {
+	mkdirSync(ctx.paths.logs, { recursive: true });
+	const child = spawn(ctx.bunPath, [join(ctx.packageRoot, "src/cli/main.ts"), ...runnerArgs(options)], {
+		detached: true,
+		stdio: "ignore",
+		env: { ...ctx.env },
+	});
+	child.unref();
+	if (child.pid === undefined) throw new Error("rotate_runner_spawn_failed");
+	return child.pid;
+}
+
+export async function rotateCommand(args: readonly string[], launchd: LaunchdDeps, ctx: LaunchdContext,
+	detach: (ctx: LaunchdContext, options: RotateOptions) => number = launchDetached): Promise<number> {
+	const options = parseRotateArgs(args);
+	if (typeof options === "string") {
+		launchd.err(`${options}\n\n${ROTATE_HELP}\n`);
+		return EXIT_USAGE;
+	}
+	const logFile = join(ctx.paths.logs, LOG_FILE);
+	if (!options.foreground) {
+		const pid = detach(ctx, options);
+		launchd.out(`분리 실행을 시작했습니다: pid ${pid}, 모드 ${options.restart ? "재시작 후 교체" : "교체"}. 결과: ${logFile}\n`);
+		return EXIT_OK;
+	}
+	return await runRotate(options, systemRotateDeps(launchd, ctx));
+}