zigmini 0.9.0-beta.2 → 1.0.0-beta.1

package/src/agent/files.ts

@@ -0,0 +1,192 @@
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { runtimePaths, type Env } from "../runtime/paths.ts";
+import { say, type Text } from "../server-text.ts";
+import { parseAgentDefinition, AgentDefinitionError, serializeAgentDefinition, type AgentDefinition } from "./definition.ts";
+import { migrateLegacyAgentFiles } from "./legacy-files.ts";
+
+export function agentTrashEntry(id: string, timestamp: string): string {
+	return `${id}-${timestamp}`;
+}
+
+/** Trash names retain the UTC ISO timestamp used by the file store, including colons. */
+export function agentTrashTimestamp(entry: string): number | null {
+	const timestamp = /-(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)$/.exec(entry)?.[1];
+	return timestamp === undefined ? null : Date.parse(timestamp);
+}
+
+/** A broken entry must not prevent the other agents from being listed. */
+export function unreadableAgent(error: unknown): boolean {
+	return error instanceof AgentDefinitionError || error instanceof AgentFileError
+		|| (error instanceof Error && "code" in error
+			&& ["ENOENT", "EACCES", "EPERM", "ENOTDIR", "EISDIR", "ELOOP"].includes(String(error.code)));
+}
+
+const COPY_SUFFIX: Text = { en: " copy", ko: " 사본" };
+
+export class AgentFileError extends Error {
+	constructor(readonly code: "path" | "exists" | "id", message: string) {
+		super(message);
+		this.name = "AgentFileError";
+	}
+}
+
+/** Synchronous file operations keep each gateway mutation uninterrupted by another request. */
+export class AgentFileStore {
+	readonly root: string;
+	private lastTime = 0;
+
+	constructor(env: Env = process.env) {
+		const root = resolve(runtimePaths(env).agents);
+		mkdirSync(root, { recursive: true });
+		if (lstatSync(root).isSymbolicLink()) throw new AgentFileError("path", "Agent root cannot be a symlink");
+		this.root = realpathSync(root);
+		migrateLegacyAgentFiles(this.root);
+	}
+
+	/** Check existing ancestors too, so a missing child cannot bypass a symlink check. */
+	private checked(path: string): string {
+		const target = resolve(this.root, path);
+		const inside = (candidate: string): boolean => {
+			const rel = relative(this.root, candidate);
+			return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+		};
+		if (!inside(target)) throw new AgentFileError("path", "Path escapes agent root");
+		let existing = target;
+		while (!existsSync(existing)) {
+			// Dangling symlinks must not be mistaken for new files.
+			try {
+				if (lstatSync(existing).isSymbolicLink()) throw new AgentFileError("path", "Dangling agent symlink");
+			} catch (error) {
+				if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+			}
+			existing = dirname(existing);
+		}
+		if (!inside(realpathSync(existing))) throw new AgentFileError("path", "Symlink escapes agent root");
+		return target;
+	}
+
+	private folder(id: string): string {
+		if (!/^[a-f0-9]{8}$/.test(id)) throw new AgentFileError("id", "Invalid agent id");
+		return this.checked(id);
+	}
+
+	private timestamp(): string {
+		this.lastTime = Math.max(Date.now(), this.lastTime + 1);
+		return new Date(this.lastTime).toISOString();
+	}
+
+	create(source: string): string {
+		parseAgentDefinition(source);
+		const id = randomUUID().slice(0, 8);
+		const folder = this.folder(id);
+		mkdirSync(folder);
+		mkdirSync(join(folder, "knowledge/source"), { recursive: true });
+		mkdirSync(join(folder, "knowledge/notes/daily"), { recursive: true });
+		writeFileSync(join(folder, "knowledge/MEMORY.md"), "", { flag: "wx" });
+		writeFileSync(join(folder, "agent.md"), source, { flag: "wx" });
+		return id;
+	}
+
+	read(id: string): AgentDefinition {
+		return parseAgentDefinition(readFileSync(this.checked(join(this.folder(id), "agent.md")), "utf8"));
+	}
+
+	list(): readonly { readonly id: string; readonly definition: AgentDefinition }[] {
+		return readdirSync(this.root, { withFileTypes: true })
+			.filter((entry) => !entry.name.startsWith(".") && (entry.isDirectory() || entry.isSymbolicLink()))
+			.flatMap((entry) => {
+				try {
+					return [{ id: entry.name, definition: this.read(entry.name) }];
+				} catch (error) {
+					if (unreadableAgent(error)) return [];
+					throw error;
+				}
+			});
+	}
+
+	private saveFile(path: string, source: string): void {
+		const file = this.checked(path);
+		const history = this.checked(join(dirname(file), file === join(this.root, "defaults.md") ? ".history" : "history"));
+		if (existsSync(file)) {
+			mkdirSync(history, { recursive: true });
+			let previous = this.checked(join(history, `${this.timestamp()}.md`));
+			while (existsSync(previous)) previous = this.checked(join(history, `${this.timestamp()}.md`));
+			copyFileSync(file, previous);
+		}
+		writeFileSync(file, source);
+		if (existsSync(history)) {
+			const entries = readdirSync(history).filter((name) => /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z\.md$/.test(name)).sort().reverse();
+			for (const name of entries.slice(20)) unlinkSync(this.checked(join(history, name)));
+		}
+	}
+
+	save(id: string, source: string): void {
+		parseAgentDefinition(source);
+		this.saveFile(join(this.folder(id), "agent.md"), source);
+	}
+
+	readDefaults(): AgentDefinition | undefined {
+		const file = this.checked("defaults.md");
+		return existsSync(file) ? parseAgentDefinition(readFileSync(file, "utf8"), "defaults") : undefined;
+	}
+
+	saveDefaults(source: string): void {
+		parseAgentDefinition(source, "defaults");
+		this.saveFile(join(this.root, "defaults.md"), source);
+	}
+
+	/** Clone only regular source files and directories; never carry symlinks into the new agent. */
+	private copy(source: string, target: string): void {
+		const file = this.checked(source);
+		const destination = this.checked(target);
+		const stat = lstatSync(file);
+		if (stat.isSymbolicLink()) throw new AgentFileError("path", "Cannot clone a symlink");
+		if (stat.isDirectory()) {
+			mkdirSync(destination, { recursive: true });
+			for (const name of readdirSync(file)) this.copy(join(file, name), join(destination, name));
+		} else {
+			copyFileSync(file, destination);
+		}
+	}
+
+	clone(id: string): string {
+		const definition = this.read(id);
+		const original = this.folder(id);
+		// Validate the copy set before allocating the new agent.
+		const validate = (path: string): void => {
+			const stat = lstatSync(this.checked(path));
+			if (stat.isSymbolicLink()) throw new AgentFileError("path", "Cannot clone a symlink");
+			if (stat.isDirectory()) for (const name of readdirSync(path)) validate(join(path, name));
+		};
+		validate(join(original, "knowledge/source"));
+		validate(join(original, "knowledge/MEMORY.md"));
+		const cloned = this.create(serializeAgentDefinition({
+			...definition, fields: { ...definition.fields, name: `${definition.fields.name}${say(COPY_SUFFIX)}` },
+		}));
+		this.copy(join(original, "knowledge/source"), join(this.folder(cloned), "knowledge/source"));
+		this.copy(join(original, "knowledge/MEMORY.md"), join(this.folder(cloned), "knowledge/MEMORY.md"));
+		return cloned;
+	}
+
+	trash(id: string): string {
+		const source = this.folder(id);
+		const trash = this.checked(".trash");
+		mkdirSync(trash, { recursive: true });
+		let entry = agentTrashEntry(id, this.timestamp());
+		while (existsSync(this.checked(join(trash, entry)))) entry = agentTrashEntry(id, this.timestamp());
+		renameSync(source, this.checked(join(trash, entry)));
+		return entry;
+	}
+
+	restore(entry: string): string {
+		const match = /^([a-f0-9]{8})-\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.exec(entry);
+		const id = match?.[1];
+		if (!id) throw new AgentFileError("id", "Invalid trash entry");
+		const target = this.folder(id);
+		if (existsSync(target)) throw new AgentFileError("exists", "Agent id already exists");
+		renameSync(this.checked(join(".trash", entry)), target);
+		return id;
+	}
+}

package/src/agent/legacy-files.ts

@@ -0,0 +1,46 @@
+import { lstatSync, mkdirSync, readdirSync, renameSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/** Move only unclaimed legacy entries; keep collisions and all file bytes intact. */
+export function migrateLegacyAgentFiles(root: string): void {
+	const legacy = join(dirname(root), "personas");
+	if (!readdirSync(dirname(root)).includes("personas")) return;
+	if (!lstatSync(legacy).isDirectory()) {
+		console.warn("agent_legacy_files_skipped", { count: 1 });
+		return;
+	}
+	let collisions = 0;
+	const move = (source: string, target: string): void => {
+		if (readdirSync(dirname(target)).includes(basename(target))) {
+			collisions++;
+			return;
+		}
+		renameSync(source, target);
+		if (lstatSync(target).isDirectory()) {
+			const names = readdirSync(target);
+			if (names.includes("persona.md")) {
+				if (names.includes("agent.md")) collisions++;
+				else renameSync(join(target, "persona.md"), join(target, "agent.md"));
+			}
+		}
+	};
+	for (const entry of readdirSync(legacy, { withFileTypes: true })) {
+		const source = join(legacy, entry.name);
+		const target = join(root, entry.name);
+		if ((entry.name === ".history" || entry.name === ".trash") && entry.isDirectory()) {
+			if (readdirSync(root).includes(entry.name) && !lstatSync(target).isDirectory()) {
+				collisions++;
+				continue;
+			}
+			mkdirSync(target, { recursive: true });
+			for (const child of readdirSync(source, { withFileTypes: true })) {
+				if (child.isSymbolicLink()) { collisions++; continue; }
+				move(join(source, child.name), join(target, child.name));
+			}
+		} else if ((entry.name === "defaults.md" && entry.isFile())
+			|| (/^[a-f0-9]{8}$/.test(entry.name) && entry.isDirectory())) {
+			move(source, target);
+		} else collisions++;
+	}
+	if (collisions > 0) console.warn("agent_legacy_files_collisions", { count: collisions });
+}

package/src/agent/list.ts

@@ -0,0 +1,21 @@
+import type { AgentDefinition } from "./definition.ts";
+
+export interface AgentListEntry { readonly name: string; readonly description: string; readonly link: string }
+
+/**
+ * The read-only list main sees: name, one-line purpose and the gateway-relative web link of the conversation.
+ * `visible` holds only non-hidden conversations, so a trashed agent (hidden conversation) never appears.
+ * Definition body and knowledge are never part of the result.
+ */
+export function agentList(
+	agents: readonly { readonly id: string; readonly definition: AgentDefinition }[],
+	visible: readonly { readonly id: string; readonly agentId?: string | null }[],
+): AgentListEntry[] {
+	const entries: AgentListEntry[] = [];
+	for (const { id, definition } of agents) {
+		const conv = visible.find((row) => row.agentId === id);
+		if (!conv) continue;
+		entries.push({ name: String(definition.fields.name), description: String(definition.fields.description), link: `/#conv=${encodeURIComponent(conv.id)}` });
+	}
+	return entries;
+}

package/src/agent-rules.ts

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { type Env, runtimeHome } from "./runtime/paths.ts";
+import { type Env, runtimeHome, runtimePaths } from "./runtime/paths.ts";
+import { readVoiceSetting } from "./voice-setting.ts";
 
 /**
  * Improvement 117: the agent rules the bridge appends to the main and work session instructions. The package file
@@ -24,7 +25,15 @@ export const INSTALL_RULES_TEMPLATE = `<!--
 
 export type RulesStatus = "used" | "missing" | "empty" | "too_large" | "unreadable";
 
-export function readRulesFile(path: string): { status: RulesStatus; text: string } {
+/** Improvement 250: the package rule text between these markers is the repository security check duty. */
+export const REPO_SECURITY_SECTION = /<!--repo-security-check-->[\s\S]*?<!--\/repo-security-check-->/g;
+
+/** What to drop from the package rules: the repository security check duty while that switch is off. */
+export function packageRulesDrop(env: Env = process.env): RegExp | undefined {
+	return readVoiceSetting(runtimePaths(env).repoSecurityCheckFile) ? undefined : REPO_SECURITY_SECTION;
+}
+
+export function readRulesFile(path: string, drop?: RegExp): { status: RulesStatus; text: string } {
 	if (!existsSync(path)) return { status: "missing", text: "" };
 	let raw: string;
 	try {
@@ -33,20 +42,20 @@ export function readRulesFile(path: string): { status: RulesStatus; text: string
 	} catch {
 		return { status: "unreadable", text: "" };
 	}
-	const text = raw.replace(/<!--[\s\S]*?-->/g, "").trim();
+	const text = (drop ? raw.replace(drop, "") : raw).replace(/<!--[\s\S]*?-->/g, "").trim();
 	return text === "" ? { status: "empty", text } : { status: "used", text };
 }
 
 /** The text to append after the role instructions, and one log line that names the files but never their content. */
 export function agentRules(env: Env = process.env, packageFile: string = PACKAGE_RULES_FILE): { text: string; log: string } {
 	const sources = [
-		{ name: "package", path: packageFile, heading: PACKAGE_RULES_HEADING },
+		{ name: "package", path: packageFile, heading: PACKAGE_RULES_HEADING, drop: packageRulesDrop(env) },
 		{ name: "install", path: join(runtimeHome(env), INSTALL_RULES_FILE), heading: INSTALL_RULES_HEADING },
 	];
 	const parts: string[] = [];
 	const notes: string[] = [];
 	for (const source of sources) {
-		const read = readRulesFile(source.path);
+		const read = readRulesFile(source.path, "drop" in source ? source.drop : undefined);
 		if (read.status === "used") parts.push(`${source.heading}\n\n${read.text}`);
 		notes.push(`${source.name}=${read.status === "used" ? `used(${source.path})` : read.status}`);
 	}

package/src/approvals.ts

@@ -1,3 +1,8 @@
+import { say, type Text } from "./server-text.ts";
+
+/** Improvement 253: the cancel reason the web and app show on a dialog whose deadline passed. */
+export const DIALOG_TIMEOUT_REASON: Text = { en: "Cancelled automatically because the deadline passed.", ko: "기한이 지나 자동으로 취소했습니다." };
+
 export type DialogMethod = "select" | "confirm" | "input" | "editor";
 
 export interface DialogRequest {
@@ -41,7 +46,7 @@ export class DialogGate {
 		const createdAt = Date.now();
 		const full: DialogRequest = { ...request, createdAt, deadlineAt: createdAt + this.timeoutMs };
 		const timer = setTimeout(() => {
-			this.settle({ actionId: full.actionId, answer: { kind: "cancel", reason: "기한이 지나 자동으로 취소했습니다." }, by: "timeout" });
+			this.settle({ actionId: full.actionId, answer: { kind: "cancel", reason: say(DIALOG_TIMEOUT_REASON) }, by: "timeout" });
 		}, this.timeoutMs);
 		this.pending.set(full.actionId, { request: full, resolve: onResolved, timer });
 		return full;

package/src/cli/main.ts

@@ -13,6 +13,11 @@ import { handoffCommand } from "../update/handoff-system.ts";
 import { HANDOFF_COMMAND } from "../update/strategy.ts";
 import { ROTATE_COMMAND, ROTATE_RUN_COMMAND, rotateCommand } from "./rotate-main.ts";
 import { EXIT_USAGE, parseMigrateArgs, parseMigrateRunArgs, runMigrate, runMigrateRun, systemMigrateDeps, systemMigrateRunDeps } from "./migrate.ts";
+import { parseImportArgs, runImport, systemImportDeps } from "./security-import.ts";
+import { parseScanArgs, prepareScan, reportScan, resolveScanBaseline, runScan, scanBaselinePaths, scanRepository, syncHashes,
+	type ResolvedScanBaseline, type ScanResult } from "./scan.ts";
+import { SCAN_DISABLED_EXIT, scanDisabledNotice } from "../repo-security-setting.ts";
+import { probeRevision } from "../security/revision-probe.ts";
 
 export const HELP = message("ko", "help");
 
@@ -59,6 +64,34 @@ export async function runCommand(argv: readonly string[], deps: LaunchdDeps, ctx
 if (import.meta.main) {
 	const argv = process.argv.slice(2);
 	if (argv[0] === "setup") process.exit(await setupCommand(argv.slice(1), () => systemSetupDeps(packageVersion()), HELP));
+	if (argv[0] === "security") {
+		const options = argv[1] === "import-baseline" ? parseImportArgs(argv.slice(2)) : "zigmini security import-baseline [--from <file>] [--dry-run]";
+		if (typeof options === "string") {
+			process.stderr.write(`${options}\n\n${HELP}`);
+			process.exit(2);
+		}
+		process.exit(await runImport(options, systemImportDeps()));
+	}
+	if (argv[0] === "scan") {
+		const deps = systemDeps();
+		const ctx = systemContext();
+		const lang = resolveLanguage(ctx.paths.home, ctx.env);
+		const disabled = scanDisabledNotice(ctx.paths.repoSecurityCheckFile, argv.slice(1), lang);
+		if (disabled !== null) {
+			deps.err(`${disabled}\n`);
+			process.exit(SCAN_DISABLED_EXIT);
+		}
+		const options = parseScanArgs(argv.slice(1), process.cwd(), lang);
+		process.exit(await runScan<ResolvedScanBaseline, ScanResult>(options, {
+			lang, out: deps.out, err: deps.err,
+			prepare: (scanOptions) => prepareScan(scanOptions, scanBaselinePaths(scanOptions, ctx.env)),
+			baseline: (scanOptions) => resolveScanBaseline(scanOptions, { env: ctx.env, lang, err: deps.err }),
+			revision: (baseline) => probeRevision(baseline, { env: ctx.env }),
+			scan: scanRepository,
+			syncHashes,
+			report: (report, scanOptions, result) => reportScan(report, scanOptions, result, deps.out),
+		}));
+	}
 	if (argv[0] === "migrate" || argv[0] === "migrate-run") {
 		const home = process.env.HOME || "";
 		const options = argv[0] === "migrate" ? parseMigrateArgs(argv.slice(1), home) : parseMigrateRunArgs(argv.slice(1), home);

package/src/cli/messages.ts

@@ -7,8 +7,8 @@ export type Language = "en" | "ko";
 export const LANGUAGE_FILE = "language";
 export const LANGUAGE_QUESTION = "Language / 언어 [1] English [2] 한국어: ";
 
-export const MESSAGES = {
-	help: { en: "zigmini - personal AI agent gateway\n\nNew installation: run `zigmini setup` for permission consent, engine installation, configuration and startup.\n\nUsage: zigmini <command> [options]\n\nCommands:\n  setup                       Set up the install home, engine, configuration and launchd services\n  start                       Register and start the gateway and bridge with launchd\n  stop [--uninstall]          Stop services; --uninstall also removes this package's launchd plists\n  restart [gateway|bridge]    Restart services\n  status                      Show launchd, health and permission consent status\n  doctor [--json] [--fix]     Check the installation; --fix restarts only unhealthy launchd agents\n  pair [--apk]                Show a one-use phone enrollment QR, or an APK download QR (--apk); valid for 10 minutes\n  rotate-main [--restart] [--wait <seconds>] [--foreground]\n                              Replace the main conversation's engine session after its turn ends (default wait: 900s).\n                              Runs detached by default; results: <home>/logs/rotate-main.log.\n                              --restart restarts the gateway first; --foreground runs in this terminal.\n  consent                     Show and record full-access permission consent; stop on refusal\n  update [version] [--force]  Install a version (default: latest), back up the DB and restart; roll back on failure.\n                              --force allows active turns; the gateway must be running.\n  migrate [--from <old home>] [--checkout <repository>] [--accept-license] [--dry-run]\n                              Copy a Docker installation (~/" + LEGACY_HOME + "); keep the old directory unchanged.\n  migrate-run [--from <old home>] [--checkout <repository>] [--access ... --domain ...] [--dry-run]\n                              Wait for idle, stop, back up, migrate, set up and check; restore the old run on failure.\n\nSetup options:\n  --lang <en|ko>              Language (saved in <home>/language)\n  --non-interactive           Do not ask setup questions\n  --accept-license            Accept the engine license\n  --agent-dir <path>          Dedicated agent directory instead of shared ~/.omo/agent\n  --notion-token-file <path>  Notion token file; no token disables the calendar\n  --access <tailscale|lan|domain>, --domain <https://address>\n                              Choose external access\n  --engine-only               Run only the pinned engine installation step\n\nOptions:\n  --version, -v               Print the installed zigmini version\n  --help, -h                  Print this help\n", ko: "zigmini - 개인 AI 에이전트 게이트웨이\n\n처음 설치했으면 먼저 `zigmini setup`을 실행하세요. setup이 권한 동의, 엔진 설치, 설정, 시작을 합니다.\n\n사용법: zigmini <명령> [옵션]\n\n명령:\n  setup                       설치합니다: 홈 폴더, 엔진, 설정, launchd 등록과 시작\n  start                       게이트웨이와 브리지를 launchd에 등록하고 시작합니다\n  stop                        게이트웨이와 브리지를 멈춥니다\n  stop --uninstall            멈추고 이 패키지의 launchd plist를 모두 지웁니다\n  restart [gateway|bridge]    다시 시작합니다\n  status                      launchd 상태, health, 권한 동의 상태를 보여 줍니다\n  doctor [--json] [--fix]     전체 상태를 점검합니다(--fix: 이상 있는 launchd 에이전트만 다시 띄움)\n  pair                        폰 등록 QR(유효 10분, 한 번 사용)을 터미널에 그립니다. 게이트웨이가 실행 중이어야 합니다\n  pair --apk                  앱(APK) 내려받기 QR(유효 10분)을 터미널에 그립니다\n  rotate-main [--restart] [--wait <초>] [--foreground]\n                              main 대화를 새 엔진 세션으로 교체합니다. main 차례가 끝나길 기다린 뒤 보냅니다(기본 900초).\n                              기본은 분리 실행이고 결과는 <홈>/logs/rotate-main.log에 남깁니다\n                              (--restart: 먼저 게이트웨이를 멈추고 다시 켭니다. --foreground: 이 터미널에서 실행)\n  consent                     풀 액세스 권한 안내를 보이고 동의를 기록합니다(거부하면 멈춤)\n  update [버전] [--force]      새 버전으로 업데이트합니다(비우면 latest). DB 백업 뒤 설치·재시작하고, 실패하면 자동으로 되돌립니다\n                              (--force: 진행 중인 턴이 있어도 합니다. 게이트웨이가 실행 중이어야 합니다)\n  migrate [--from <옛 홈>] [--checkout <저장소>] [--accept-license] [--dry-run]\n                              Docker 설치(~/" + LEGACY_HOME + ")를 복사해 옮깁니다. 옛 폴더는 바꾸지 않습니다\n  migrate-run [--from <옛 홈>] [--checkout <저장소>] [--access ... --domain ...] [--dry-run]\n                              유휴 대기 → 옛 실행 정지 → 백업 → migrate → setup → 확인, 실패하면 옛 실행으로 되돌립니다\n\nsetup 옵션:\n  --lang <en|ko>              Language / 언어 (saved in <home>/language)\n  --non-interactive           묻지 않습니다\n  --accept-license            엔진 라이선스에 동의합니다\n  --agent-dir <경로>          공유 ~/.omo/agent 대신 쓸 전용 에이전트 폴더\n  --notion-token-file <경로>  Notion 토큰 파일(없으면 일정 기능 꺼짐)\n  --access <tailscale|lan|domain>, --domain <https://주소>\n                              외부 접속 선택\n  --engine-only               엔진 설치 단계만 실행합니다\n\n옵션:\n  --version, -v   설치된 zigmini 버전을 출력합니다\n  --help, -h      이 도움말을 출력합니다\n" },
+const BASE_MESSAGES = {
+	help: { en: "zigmini - personal AI agent gateway\n\nNew installation: run `zigmini setup` for permission consent, engine installation, configuration and startup.\n\nUsage: zigmini <command> [options]\n\nCommands:\n  security import-baseline [--from <file>] [--dry-run]  Import baseline terms through the running gateway; report counts only\n  setup                       Set up the install home, engine, configuration and launchd services\n  start                       Register and start the gateway and bridge with launchd\n  stop [--uninstall]          Stop services; --uninstall also removes this package's launchd plists\n  restart [gateway|bridge]    Restart services\n  status                      Show launchd, health and permission consent status\n  doctor [--json] [--fix]     Check the installation; --fix restarts only unhealthy launchd agents\n  pair [--apk]                Show a one-use phone enrollment QR, or an APK download QR (--apk); valid for 10 minutes\n  rotate-main [--restart] [--wait <seconds>] [--foreground]\n                              Replace the main conversation's engine session after its turn ends (default wait: 900s).\n                              Runs detached by default; results: <home>/logs/rotate-main.log.\n                              --restart restarts the gateway first; --foreground runs in this terminal.\n  consent                     Show and record full-access permission consent; stop on refusal\n  update [version] [--force]  Install a version (default: latest), back up the DB and restart; roll back on failure.\n                              --force allows active turns; the gateway must be running.\n  migrate [--from <old home>] [--checkout <repository>] [--accept-license] [--dry-run]\n                              Copy a Docker installation (~/" + LEGACY_HOME + "); keep the old directory unchanged.\n  migrate-run [--from <old home>] [--checkout <repository>] [--access ... --domain ...] [--dry-run]\n                              Wait for idle, stop, back up, migrate, set up and check; restore the old run on failure.\n\nSetup options:\n  --lang <en|ko>              Language (saved in <home>/language)\n  --non-interactive           Do not ask setup questions\n  --accept-license            Accept the engine license\n  --agent-dir <path>          Dedicated agent directory instead of shared ~/.omo/agent\n  --notion-token-file <path>  Notion token file; no token disables the calendar\n  --access <tailscale|lan|domain>, --domain <https://address>\n                              Choose external access\n  --engine-only               Run only the pinned engine installation step\n\nOptions:\n  --version, -v               Print the installed zigmini version\n  --help, -h                  Print this help\n", ko: "zigmini - 개인 AI 에이전트 게이트웨이\n\n처음 설치했으면 먼저 `zigmini setup`을 실행하세요. setup이 권한 동의, 엔진 설치, 설정, 시작을 합니다.\n\n사용법: zigmini <명령> [옵션]\n\n명령:\n  security import-baseline [--from <파일>] [--dry-run]  실행 중인 게이트웨이로 기준 용어를 가져오고 건수만 출력합니다\n  setup                       설치합니다: 홈 폴더, 엔진, 설정, launchd 등록과 시작\n  start                       게이트웨이와 브리지를 launchd에 등록하고 시작합니다\n  stop                        게이트웨이와 브리지를 멈춥니다\n  stop --uninstall            멈추고 이 패키지의 launchd plist를 모두 지웁니다\n  restart [gateway|bridge]    다시 시작합니다\n  status                      launchd 상태, health, 권한 동의 상태를 보여 줍니다\n  doctor [--json] [--fix]     전체 상태를 점검합니다(--fix: 이상 있는 launchd 에이전트만 다시 띄움)\n  pair                        폰 등록 QR(유효 10분, 한 번 사용)을 터미널에 그립니다. 게이트웨이가 실행 중이어야 합니다\n  pair --apk                  앱(APK) 내려받기 QR(유효 10분)을 터미널에 그립니다\n  rotate-main [--restart] [--wait <초>] [--foreground]\n                              main 대화를 새 엔진 세션으로 교체합니다. main 차례가 끝나길 기다린 뒤 보냅니다(기본 900초).\n                              기본은 분리 실행이고 결과는 <홈>/logs/rotate-main.log에 남깁니다\n                              (--restart: 먼저 게이트웨이를 멈추고 다시 켭니다. --foreground: 이 터미널에서 실행)\n  consent                     풀 액세스 권한 안내를 보이고 동의를 기록합니다(거부하면 멈춤)\n  update [버전] [--force]      새 버전으로 업데이트합니다(비우면 latest). DB 백업 뒤 설치·재시작하고, 실패하면 자동으로 되돌립니다\n                              (--force: 진행 중인 턴이 있어도 합니다. 게이트웨이가 실행 중이어야 합니다)\n  migrate [--from <옛 홈>] [--checkout <저장소>] [--accept-license] [--dry-run]\n                              Docker 설치(~/" + LEGACY_HOME + ")를 복사해 옮깁니다. 옛 폴더는 바꾸지 않습니다\n  migrate-run [--from <옛 홈>] [--checkout <저장소>] [--access ... --domain ...] [--dry-run]\n                              유휴 대기 → 옛 실행 정지 → 백업 → migrate → setup → 확인, 실패하면 옛 실행으로 되돌립니다\n\nsetup 옵션:\n  --lang <en|ko>              Language / 언어 (saved in <home>/language)\n  --non-interactive           묻지 않습니다\n  --accept-license            엔진 라이선스에 동의합니다\n  --agent-dir <경로>          공유 ~/.omo/agent 대신 쓸 전용 에이전트 폴더\n  --notion-token-file <경로>  Notion 토큰 파일(없으면 일정 기능 꺼짐)\n  --access <tailscale|lan|domain>, --domain <https://주소>\n                              외부 접속 선택\n  --engine-only               엔진 설치 단계만 실행합니다\n\n옵션:\n  --version, -v   설치된 zigmini 버전을 출력합니다\n  --help, -h      이 도움말을 출력합니다\n" },
 	permissionNotice: { en: "zigmini permission notice (notice version 1)\n\n1. The zigmini gateway runs the OMO agent with the full-access permission preset.\n2. The full-access preset allows every permission on every target. The agent does not ask for approval for each tool call.\n3. The agent has file read, write and edit tools, and a shell command (bash) tool.\n4. Shell commands run with this macOS account's permissions, without a sandbox or isolation.\n5. The agent uses the network for model API calls, web search (web_search) and web fetching (webfetch).\n6. The agent uses model accounts logged in through auth.json in the agent directory and consumes their usage allowance.\n7. The default agent directory is ~/.omo/agent. Other OMO instances using that directory share its login information (auth.json) and settings (settings.json).\n8. The gateway and bridge run as this macOS user's LaunchAgents. launchd restarts them after an error exit.\n9. Requests from enrolled phone apps run with the same full-access permissions.\n10. If you do not agree, zigmini installs nothing and does not start the gateway or bridge.", ko: "zigmini 권한 안내 (안내문 버전 1)\n\n1. zigmini 게이트웨이는 OMO 에이전트를 권한 프리셋 full-access로 실행합니다.\n2. full-access 프리셋은 모든 권한, 모든 대상에 '허용' 규칙 하나만 둡니다. 그래서 에이전트는 도구를 쓸 때마다 사용자 승인을 받지 않습니다.\n3. 에이전트에는 파일 읽기(read), 쓰기(write), 고치기(edit) 도구와 셸 명령(bash) 도구가 있습니다.\n4. 셸 명령은 샌드박스 없이 이 macOS 사용자 계정의 권한으로 실행됩니다. 격리는 없습니다.\n5. 에이전트는 네트워크를 씁니다: 모델 API 호출, 웹 검색(web_search), 웹 가져오기(webfetch).\n6. 에이전트는 에이전트 폴더의 auth.json에 로그인한 모델 계정을 쓰고, 그 계정의 사용량을 소비합니다.\n7. 기본 에이전트 폴더는 ~/.omo/agent입니다. 같은 폴더를 쓰는 다른 OMO와 로그인 정보(auth.json)와 설정(settings.json)을 같이 씁니다.\n8. 게이트웨이와 브리지는 이 macOS 사용자의 LaunchAgent로 실행되고, 오류로 끝나면 launchd가 다시 시작합니다.\n9. 등록한 폰 앱이 보낸 요청도 같은 full-access 권한으로 실행됩니다.\n10. 동의하지 않으면 zigmini는 아무것도 설치하지 않고, 게이트웨이와 브리지는 시작하지 않습니다." },
 	unknownOption: { en: "Unknown option: {flag}", ko: "알 수 없는 옵션: {flag}" },
 	missingValue: { en: "{flag} requires a value", ko: "{flag} 에 값이 필요합니다" },
@@ -117,6 +117,14 @@ export const MESSAGES = {
 	schemaRefused: { en: "The bridge was not started. Gateway health ({url}) reports omo=schema_too_new.\n", ko: "브리지를 시작하지 않았습니다. 게이트웨이 health({url})가 omo=schema_too_new를 보입니다.\n" },
 } as const satisfies Record<string, Readonly<Record<Language, string>>>;
 
+export const MESSAGES = {
+	...BASE_MESSAGES,
+	help: {
+		en: BASE_MESSAGES.help.en.replace("Commands:\n", "Commands:\n  scan [<repo>]               Scan a repository for security findings\n"),
+		ko: BASE_MESSAGES.help.ko.replace("명령:\n", "명령:\n  scan [<repo>]               저장소의 보안 발견 항목을 검사합니다\n"),
+	},
+} as const satisfies Record<string, Readonly<Record<Language, string>>>;
+
 export type MessageKey = keyof typeof MESSAGES;
 export function message(lang: Language, key: MessageKey, values: Readonly<Record<string, string | number>> = {}): string {
 	return MESSAGES[key][lang].replace(/\{(\w+)\}/g, (placeholder, name: string) => String(values[name] ?? placeholder));

package/src/cli/rotate-main.ts

@@ -3,6 +3,7 @@ import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from
 import { basename, dirname, join } from "node:path";
 import { agentDir } from "../model-accounts.ts";
 import { ROTATION_HELD_MESSAGE } from "../protocol.ts";
+import { isTextOf } from "../server-text.ts";
 import { type LaunchdContext, type LaunchdDeps, ownProcess, parseConfigEnv, startCommand, stopCommand } from "./launchd.ts";
 
 /**
@@ -297,7 +298,7 @@ export function socketRotate(url: string, timeoutMs: number): Promise<RotateOutc
 				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 });
+				end(isTextOf(text, ROTATION_HELD_MESSAGE) ? { kind: "held", message: text } : { kind: "error", message: text });
 			}
 		};
 		ws.onerror = () => end({ kind: "error", message: "WebSocket 연결 오류" });