zigmini 0.8.0-beta.2 → 0.8.0-beta.4

package/docs/manual.md

@@ -0,0 +1,382 @@
+English | [한국어](manual.ko.md)
+
+# zigmini user manual
+
+## 1. Introduction
+
+zigmini is a personal AI agent gateway that runs on your Mac. You talk with the agent, give it work, and get notifications. The default agent is called "Zig". You can change that name in the profile.
+
+zigmini has two surfaces.
+
+| Surface | Description |
+| --- | --- |
+| Web screen | Open it in a browser on the Mac. It has chat, the inbox (확인함), work status and settings. |
+| Android app | Use it on your phone. It has chat, the inbox, work status and notifications. Register the phone with the gateway first. |
+
+## 2. Web screen
+
+### 2.1 Layout
+
+The web screen has three parts.
+
+- Left sidebar: the conversation list, the new conversation button (+), the work status area, your profile and the agent profile. The "omo" badge at the top shows the agent engine connection.
+- Center chat: the header, the message list and the input box.
+- Right panels: the inbox, settings and the event panel open here.
+
+The header has these items. Labels are shown in Korean on screen.
+
+| Item | What it does |
+| --- | --- |
+| Zig face button | Shows work status. At phone width it switches to the work status view. |
+| Model picker | Picks the model the agent uses. If the switch can't happen right away, it happens after the conversation is compacted on your next message. |
+| 새 세션 (new session) | Starts a fresh agent session for this conversation. A confirmation comes first. The history on screen stays, and part of the recent conversation is handed to the new session. |
+| 음성 켜짐 / 음성 꺼짐 (voice on/off) | Turns the gateway's voice servers on or off. With voice off, the mic, wake word, clap detection and spoken answers are unavailable. |
+| 음성 설치 (install voice) | Shown only on an npm install without voice. It downloads and installs the voice servers. |
+| 박수 감지 (clap detection) | Two claps turn wake word listening on or off. |
+| 호출어 (wake word) | When it hears "Hey Zig", it writes down what you say into the input box. |
+| 음성 답변 (spoken answers) | Reads answers aloud. |
+| 확인함 (inbox) | Opens questions and approval requests waiting for you. The badge shows how many need you. |
+| 이벤트 (events) | Opens the event panel. Its 지우기 button clears the events shown. |
+| 설정 (settings) | Opens settings. |
+
+Notice lines can also show up in the header.
+
+- "모델 계정에 로그인하세요": you aren't logged in to a model account.
+- Schema notice: the agent engine's data format is newer than the gateway's.
+- New version notice: click it to open the update area in settings.
+- "세션 교체 중": a session switch is running. You can't send messages meanwhile.
+
+The ▲ button beside the message list jumps to your previous message. The ▼ button jumps to your next one. Double-click ▼ to jump to the bottom.
+
+### 2.2 Chat
+
+1. Type a message in the input box.
+2. Press Enter or click 전송 (send).
+
+Shift+Enter starts a new line. Enter pressed during Korean IME composition doesn't send.
+
+While the agent works, the 중단 (stop) button shows. Click it to stop the running work.
+
+To start a new conversation, click + in the sidebar. A prompt asks for its name.
+
+#### Slash command menu
+
+Type `/` in the input box to open the command and skill menu. Keep typing to narrow the list. The menu holds skills, commands, templates and web Zig commands.
+
+Web Zig commands:
+
+| Command | What it does |
+| --- | --- |
+| `/tts on`, `/tts off` | Turns spoken answers on or off. |
+| `/wake on`, `/wake off` | Turns wake word listening on or off. |
+| `/clap on`, `/clap off` | Turns clap detection on or off. |
+| `/voice on`, `/voice off` | Turns the voice feature (voice servers) on or off. |
+| `/옵션` | Shows the state of voice, spoken answers, wake word and clap detection. |
+| `/read` | Reads the whole last answer aloud. |
+| `/기기` | Lists registered devices. Mac only. |
+| `/기기 삭제 <number>` | Deletes the registered device with that number. Mac only. |
+
+With voice off, the voice commands leave the menu. Typed by hand, they get the reply "음성 기능이 꺼져 있습니다" (voice is off).
+
+The README's Commands section says that sending `/usage` in chat makes the gateway reply with the model account's usage.
+
+### 2.3 Attachments and references
+
+#### Images
+
+- Click 이미지 (image) to pick images.
+- Paste images into the input box.
+- Drop image files on the message list or the input area.
+
+You can send up to 4 images at once: PNG, JPEG, GIF or WebP. Images upload when you send.
+
+#### Referencing earlier messages
+
+Right-click a message to attach it as a reference tag above the input box. The message's 참조 (reference) button does the same. You can add up to 4 references. Images from referenced messages plus new attachments can't go over 4 in one send. To drop a tag, click its button, or focus it and press Delete or Backspace.
+
+#### Memo
+
+The 쪽지 (memo) button opens and closes the memo. Keep frequent prompts or notes there. It saves on its own. 이미지 보관 keeps up to 2 images in it.
+
+#### Auto copy
+
+Select text in the message list with the mouse and it's copied right away. A short "복사했습니다" (copied) notice appears. Text selected inside the input box isn't auto copied.
+
+### 2.4 Last sent strip
+
+A line under the header shows the last message you sent in this conversation. Image and reference counts show too. Click the line to expand the full text. Click again to collapse it.
+
+### 2.5 Recalling sent messages
+
+In the input box, ArrowUp brings back earlier messages you sent. ArrowDown walks forward again. Past the newest one, your unsent draft comes back.
+
+It only works under these rules.
+
+- ArrowUp works only with the caret on the first line.
+- ArrowDown works only while recalling, with the caret on the last line.
+- With Ctrl, Cmd, Alt or Shift held, it does nothing.
+- With text selected, or during IME composition, it does nothing.
+- While the slash menu is open, the arrows move in the menu.
+
+### 2.6 Inbox (확인함)
+
+The inbox collects the questions and approval requests the agent sends you. Open it with the header's 확인함 button or Ctrl+C. The badge counts items that need you.
+
+Each item shows some of these buttons, depending on its state.
+
+| Button | What it does |
+| --- | --- |
+| Primary button (e.g. 답변 보내기, send answer) | Sends the answer you picked. |
+| 다시 보내기 (send again) | Resends the same answer when delivery is uncertain. |
+| 현재 상황 확인 (check current status) | Rechecks where the asking work stands now. |
+| 최신 내용 확인 (review latest) | When the question changed, review the latest version so you can answer again. |
+| 삭제 (delete) | Removes the item from the inbox. A second confirm step follows. 그대로 두기 keeps it. |
+| 원문 보기 (view original) | Jumps to the original question card in chat. |
+
+Expand 대화 맥락 (conversation context) to see the related chat. Deleting a question that's still waiting sends a cancel to the work that asked it. With a long list, click 더 보기 (more).
+
+You can also answer from the question card in chat. Both places show the same state.
+
+### 2.7 Work status view
+
+The work status area sits in the sidebar. Zig is in the middle, and each work you gave out shows as a slot. A slot shows the work title, state and time. An empty slot reads "빈 칸".
+
+- Click a finished work's slot to clear it. With the keyboard, focus the slot and press Enter or Space.
+- The fold button hides and shows the work status area.
+- The gateway keeps the slots, so the web and the app show the same board.
+
+At phone width the sidebar is hidden. Click the Zig face in the header to switch to a view with only work status. The top left button, the browser's Back, or Esc returns to chat.
+
+### 2.8 Settings
+
+Open it with the header's 설정 button. Close it with Esc, the × button, or a click outside the card.
+
+#### Profile
+
+The profile sits at the bottom of the sidebar.
+
+| Target | How | Rules |
+| --- | --- | --- |
+| Your nickname | Double-click your profile. | Up to 20 characters. Blank becomes "나" (me). |
+| Agent name | Double-click the agent profile. | Up to 10 Korean or 20 Latin characters. Too long and it isn't changed. Blank becomes "지그" (Zig). |
+| Agent icon | Double-click the agent icon. | PNG, JPEG or WebP, 1 MB at most. The center is cropped to a square. You can go back to the default icon. |
+
+In a name field, Enter saves and Esc cancels. Leaving the field also saves. Names are stored on the gateway. If that fails, only this browser shows the new name.
+
+#### Update (업데이트)
+
+- The current and new versions are shown.
+- 지금 확인 (check now) looks for a new version right away. On failure it shows why and asks you to try again.
+- 변경 내용 보기 (view changes) shows when there's a new version.
+- The 업데이트 (update) button shows only when there's a new version and the install came from npm. A repository install doesn't get it.
+
+The update button is held, or asks for more, in these cases.
+
+| Condition | What you see |
+| --- | --- |
+| Inbox questions are waiting for you | The button is disabled. A line says N questions are waiting, with a 확인함 열기 (open inbox) button. Answer them, then update. |
+| The permission notice changed | The new notice shows. Type the consent word (동의) in the field to go on. |
+| Shared data format change | The changes are shown and you confirm them. |
+| Work is running | A notice says the gateway is busy. |
+
+An update restarts the gateway and the bridge. Connections and running chats may drop for a moment. Progress shows below. When it's done, reload the page.
+
+#### Device registration (기기 등록)
+
+- A phone registration QR shows. Each QR works once, for 10 minutes.
+- When it expires, click 새로 만들기 (make new).
+- The 등록된 기기 (registered devices) list shows each device's name, model and last connection.
+- To remove a device, click 등록 취소, then click again when it reads 다시 누르면 취소.
+
+When a phone asks to register, a request line appears above the chat with the device name and a check number. Make sure it matches the number on the phone, then click 승인 (approve). Without approval in 30 seconds it's denied. After repeated denials or expiries, registration locks. Click 잠금 해제 (unlock) then.
+
+#### External access (외부 접속)
+
+Pick how the phone reaches the gateway.
+
+| Choice | Meaning |
+| --- | --- |
+| 집 Wi-Fi만 (home Wi-Fi only) | Only on the same Wi-Fi. |
+| Tailscale | Install Tailscale on the Mac and the phone, logged in to the same account. |
+| 자기 도메인 (your own https domain) | Enter your https address. |
+
+Then click 바꾸기 (change).
+
+#### App download (앱 내려받기)
+
+A QR for the Android app (APK) shows. Scan it with the phone camera, get the APK and install it. The phone must allow installs from unknown sources. When the QR expires, click 새로 만들기.
+
+#### Cleanup (정리)
+
+The gateway lists things that are safe to delete: DB backups, OMO version folders, leftover update files, temp folders and old RPC daemons. Tick the ones to remove and click 선택한 항목 정리 (clean selected).
+
+#### Voice settings
+
+Voice settings live in the header buttons, not in the settings card. See the table in 2.1 and section 2.9.
+
+### 2.9 Voice on the web
+
+Voice features work only while voice is on (음성 켜짐).
+
+- Mic: click 마이크 and speak. Click again to send.
+- Spoken answers: when on, answers are read aloud.
+- Wake word: when on, it waits for "Hey Zig". What you say next fills the input box and is sent after a few seconds. The send button counts down. Press Esc or edit the input to cancel the auto send.
+- "Hey hey hey": stops the running work and waits for your next words.
+- "귀 닫아" (close your ears): turns wake word listening off.
+- Clap detection: when on, two claps turn wake word listening on or off.
+
+### 2.10 Viewing the manual
+
+- Web: click the 매뉴얼 (manual) button at the top of the settings dialog. The Korean version opens first. The "English" button or the link on the first line of the document switches to the English version. Esc, the close button (×) or a click outside the dialog closes it.
+- App: short press the header status tag (for example "작업 상태 확인 중") to open the gateway connection screen, then tap its 매뉴얼 button. The "English" button switches to the English version. 닫기 (close) or Back returns to the connection screen.
+- When the gateway does not serve the manual, the notice "이 게이트웨이 버전에는 매뉴얼이 없습니다" (this gateway version has no manual) shows. Update the gateway to read it.
+
+## 3. Keyboard shortcuts
+
+| Key | Where | What it does |
+| --- | --- | --- |
+| Ctrl+E | Anywhere | Opens or closes the event panel. |
+| Ctrl+C | Anywhere, with no text selected | Opens or closes the inbox. With text selected, it copies as usual. |
+| Enter | Input box | Sends the message. Not during IME composition. |
+| Shift+Enter | Input box | New line. |
+| Esc | Input box | Cancels the wake word auto send. |
+| ArrowUp | Input box, first line | Recalls an earlier sent message. |
+| ArrowDown | Input box, last line, while recalling | Goes to a newer message or back to your draft. |
+| ArrowUp / ArrowDown | Slash menu | Moves through items. |
+| Tab, Enter | Slash menu | Puts the chosen item in the input box. |
+| Esc | Slash menu | Closes the menu. |
+| Enter, Space | Last sent strip | Expands or collapses it. |
+| Delete, Backspace | Reference tag | Removes the reference. |
+| Enter, Space | Finished work slot in work status | Clears the slot. |
+| Esc | Work status view (phone width) | Returns to chat. |
+| Esc | Inbox | Closes the inbox. |
+| Tab, Shift+Tab | Inbox | Focus cycles inside the inbox. |
+| Esc | Settings | Closes settings. |
+| Tab, Shift+Tab | Settings | Focus cycles inside settings. |
+| Esc | Manual | Closes the manual and returns to settings. |
+| Tab, Shift+Tab | Manual | Focus cycles inside the manual. |
+| Enter | Nickname or agent name field | Saves. |
+| Esc | Nickname or agent name field | Closes without change. |
+| Esc | Agent icon editor | Closes without change. |
+
+Ctrl shortcuts do nothing with Cmd, Alt or Shift held. They match by key position, so a Korean layout works too.
+
+## 4. Android app
+
+### 4.1 Connections
+
+The app header shows the Zig face and a status tag on the left. The tag reads one of "게이트웨이 재연결 중" (reconnecting), "omo 끊김" (omo disconnected), "omo 연결됨" (omo connected) or "작업 상태 확인 중" (checking work status).
+
+| Action | What it does |
+| --- | --- |
+| Tap the Zig face | Switches between chat and the work status screen. |
+| Short press the status tag | Opens the gateway connection screen. It shows the app version, the gateway version and the 매뉴얼 (manual) button. |
+| Long press the status tag | Opens the app version dialog. |
+
+The connection screen manages registered gateways.
+
+- 선택 (select) switches to that gateway. The one in use shows "사용 중".
+- 삭제 (delete), then 삭제 확인 (confirm), removes the gateway from the phone.
+
+### 4.2 Device registration
+
+There are two ways to register.
+
+1. Tap QR로 등록 (register by QR) and scan the registration QR from web settings.
+2. Or paste the gateway address and the registration token, then tap 등록 (register).
+
+Then approve the request on the Mac's web screen within 30 seconds. Check that the numbers match.
+
+### 4.3 Inbox (확인함)
+
+Open it from the inbox icon in the header. The top shows counts for "확인 필요" (needs you) and "전달 중" (delivering). Required questions carry a 필수 tag. You must answer all required questions before you can send.
+
+- Pick an answer and send it.
+- 삭제 removes the item after a confirm step. For a question still waiting, the button reads 질문 취소하고 삭제 (cancel question and delete).
+- 원문 보기 jumps to the question card in chat.
+- While disconnected, the list is the last one received. Answers can be sent after reconnecting.
+
+### 4.4 Work status screen
+
+Tap the Zig face to open it. Slot states include running, waiting for input, waiting, waiting for subtasks, unresponsive, broken, completed, failed and cancelled.
+
+- Tap a finished slot to clear it.
+- Long press a slot to show the work's name.
+- ID 복사 copies the work ID.
+
+### 4.5 Update and download
+
+- New gateway version: a notice bar shows. On an npm install it has an 업데이트 button that asks for confirmation. If inbox questions are waiting, the button is disabled and 확인함 열기 shows. ✕ hides the bar until the next connection.
+- New app version: tap 내려받기 (download) in the "새 앱 버전" row to get the APK in the browser. The phone must allow installs from unknown sources.
+
+### 4.6 Notifications
+
+- Each registered gateway has its own notification connection.
+- Channels are "일정 알림" (reminders), "확인 요청" (requests) and "연결 유지" (keep connected).
+- Notifications vibrate with no sound.
+- Tapping a notification switches to the gateway that sent it.
+- The keep connected notification lists each gateway's state. If it says "인증 거부, 다시 등록하세요" (auth refused), register the phone again.
+
+### 4.7 Copying messages and references
+
+- Long press message text to select it, and the selection is copied right away. Below Android 13, a "복사했습니다" toast shows.
+- Swipe a message left to attach it as a reference. Up to 4 references.
+- The memo's 복사 button copies the memo text.
+
+### 4.8 Voice
+
+- Tap the mic button and speak. Tap again to send. 취소 discards the recording.
+- The speaker icon in the header turns spoken answers on or off. It's hidden while the gateway's voice feature is off.
+- Install voice and turn it on or off from the Mac's web screen.
+
+### 4.9 Manual button
+
+The 매뉴얼 button on the gateway connection screen opens this document. See 2.10, Viewing the manual.
+
+## 5. Common
+
+### 5.1 Giving work to Zig
+
+Tell Zig the work in chat. When Zig hands work out, a slot appears in the work status screen. When the work is done, tap or click the slot to clear it.
+
+### 5.2 Questions and approvals
+
+1. Zig or a work asks you a question or requests approval.
+2. The question shows both as a chat card and in the inbox. The app sends a "확인 요청" notification.
+3. You answer in either place.
+4. The gateway delivers the answer to whoever asked.
+
+The conversation may keep going while a question waits. If you can't tell whether an answer arrived, send the same answer again; it's handled only once. If the question changed, use 최신 내용 확인 and answer again.
+
+### 5.3 How to update
+
+- Web: click 업데이트 in settings (2.8).
+- Mac terminal: run `zigmini update`. For a given version, run `zigmini update <version>`.
+
+### 5.4 Common problems
+
+| Problem | Fix |
+| --- | --- |
+| The header says "모델 계정에 로그인하세요". | Run the login command from the README's Install section, then type `/login`. |
+| A schema notice shows in the header. | The agent engine uses a newer data format than the gateway. Follow the notice text. |
+| The connection dropped. | On the Mac, check with `zigmini status`. Run `zigmini doctor`, and `zigmini doctor --fix` to restart only what's broken. |
+| The update button is disabled. | Inbox questions are waiting. Click 확인함 열기 and answer them first. |
+| The gateway won't start and says consent is missing. | Run `zigmini consent` in the Mac terminal. |
+| The app can't connect. | Check 외부 접속 in web settings. Without a choice, the phone can't connect. If the app shows auth refused, register the phone again. |
+| Phone registration is locked. | Click 잠금 해제 on the request line in the web screen. |
+
+## 6. CLI
+
+Main commands for the Mac terminal:
+
+- `zigmini setup`: installs.
+- `zigmini start`: starts the gateway and the bridge.
+- `zigmini stop`: stops the gateway and the bridge. Running work stops too.
+- `zigmini restart [gateway|bridge]`: restarts.
+- `zigmini status`: shows status.
+- `zigmini doctor [--fix]`: checks everything.
+- `zigmini pair [--apk]`: shows the phone registration QR or the app download QR.
+- `zigmini consent`: shows the permission notice and records consent.
+- `zigmini update [version]`: updates.
+
+For the full list, see the README's Commands section.

package/host/omo-bridge/continuity-control.ts

@@ -41,28 +41,6 @@ function record(value: unknown): value is RecordValue {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-const retirementAccountedTools = new Set([
-	"read",
-	"grep",
-	"glob",
-	"todo",
-	"create_goal",
-	"get_goal",
-	"update_goal",
-	"zgw_work_start",
-	"zgw_work_send",
-	"zgw_work_list",
-	"zgw_work_get",
-	"zgw_work_cancel",
-	"zgw_work_report",
-	"zgw_work_publish",
-	"zgw_precomment",
-	// A settled question has its tool result; an open one is in pendingQuestions (age rotation waits for it) and a
-	// forced rotation turns it into an inbox item answered in the next session.
-	"ask_user_question",
-	"request_user_input",
-]);
-
 function durableReadiness(ctx: ContinuityContext): string | null {
 	if (!ctx.goalStoreFile) return "goal_store_unavailable";
 	try {
@@ -119,6 +97,9 @@ function durableReadiness(ctx: ContinuityContext): string | null {
 		}
 	}
 
+	// Bug 86: only a tool call without its result can still be running. Work that outlives its tool call (task children,
+	// detached eval cells, background terminals, monitors, open questions) is owned through wake_source_state, which
+	// readiness checks before this; a settled call of any tool name leaves nothing behind.
 	const entries = ctx.sessionManager.getEntries();
 	const results = new Set(
 		entries.flatMap((entry) =>
@@ -129,9 +110,6 @@ function durableReadiness(ctx: ContinuityContext): string | null {
 		if (entry.message?.role !== "assistant" || !Array.isArray(entry.message.content)) continue;
 		for (const part of entry.message.content) {
 			if (!record(part) || part.type !== "toolCall") continue;
-			if (typeof part.name !== "string" || !retirementAccountedTools.has(part.name)) {
-				return "async_tool_ownership_unverified";
-			}
 			if (typeof part.id !== "string" || !results.has(part.id)) return "tool_result_unresolved";
 		}
 	}

package/host/omo-bridge/task-control.ts

@@ -47,8 +47,11 @@ function commandEntry(entries: Entry[], workId: string, seq: unknown): Params {
 	throw new Error("report_command_not_received");
 }
 
-/** Main models have sent report details as a JSON string; only a string that parses to an object is unwrapped. */
-function mainReportDetails(details: unknown): unknown {
+/**
+ * Main and work models have sent report details as a JSON string (bugs 3 and 127); only a string that parses to an
+ * object is unwrapped.
+ */
+function reportDetails(details: unknown): unknown {
 	if (typeof details !== "string") return details;
 	try {
 		const parsed: unknown = JSON.parse(details);
@@ -204,7 +207,7 @@ export default function taskControl(pi: ExtensionApi): void {
 						Object.keys(params).some((key) => !["kind", "summary", "details"].includes(key)))) {
 						throw new Error("main_question_only");
 					}
-					const details = isMain ? mainReportDetails(params.details) : params.details;
+					const details = reportDetails(params.details);
 					const command = isMain
 						? mainDecisionEntry(ctx.sessionManager.getEntries(), details)
 						: commandEntry(ctx.sessionManager.getEntries(), workId as string, params.command_seq);
@@ -214,7 +217,7 @@ export default function taskControl(pi: ExtensionApi): void {
 						kind: "question", summary: params.summary, details,
 					} : {
 						report_id: requestKey, work_id: workId, command_id: command.command_id,
-						kind: params.kind, command_seq: params.command_seq, summary: params.summary, details: params.details,
+						kind: params.kind, command_seq: params.command_seq, summary: params.summary, details,
 					};
 					let entry = ctx.sessionManager.getEntries().find((e) => e.type === "custom" && e.customType === "zgw.work_report" && record(e.data) && e.data.report_id === requestKey);
 					if (entry && !isDeepStrictEqual(entry.data, data)) throw new Error("report_key_conflict");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zigmini",
-  "version": "0.8.0-beta.2",
+  "version": "0.8.0-beta.4",
   "type": "module",
   "bin": {
     "zigmini": "bin/zigmini"
@@ -21,9 +21,12 @@
     "!host/omo-check/*.ts",
     "!host/omo-check/patches/README.md",
     "assets/",
+    "docs/manual.md",
+    "docs/manual.ko.md",
     "LICENSE.md",
     "THIRD_PARTY_NOTICES.md",
-    "README.md"
+    "README.md",
+    "README.ko.md"
   ],
   "license": "SEE LICENSE IN LICENSE.md",
   "zigmini": {
@@ -53,7 +56,7 @@
     "test:e2e": "bun test test/e2e",
     "test:contract": "bun test test/contract",
     "test:all": "tsc --noEmit && bun test test/unit && bun test test/contract",
-    "test:mutation": "bun test test/mutation",
+    "test:mutation": "bun scripts/mutation-run.ts",
     "heavy": "bun host/heavy-slot.ts run"
   },
   "devDependencies": {

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,6 +15,8 @@ import { EXIT_USAGE, parseMigrateArgs, parseMigrateRunArgs, runMigrate, runMigra
 
 export const HELP = `zigmini - 개인 AI 에이전트 게이트웨이
 
+처음 설치했으면 먼저 \`zigmini setup\`을 실행하세요. setup이 권한 동의, 엔진 설치, 설정, 시작을 합니다.
+
 사용법: zigmini <명령> [옵션]
 
 명령:
@@ -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/client-topics.ts

@@ -0,0 +1,16 @@
+/**
+ * Bug 119: which chat socket gets which live event. Every chat socket joins both topics; the app (hello client "android",
+ * the same in every app version) leaves the thinking topic, since it never shows thinking and each delta costs it work on
+ * its main thread. The web page and devlog show thinking and stay on it.
+ */
+export const CHAT_TOPIC = "clients";
+export const THINKING_TOPIC = "thinking";
+export const APP_CLIENT = "android";
+
+export function topicOf(type: string): string {
+	return type === "thinking.delta" ? THINKING_TOPIC : CHAT_TOPIC;
+}
+
+export function showsThinking(client: unknown): boolean {
+	return client !== APP_CLIENT;
+}

package/src/decisions.ts

@@ -44,6 +44,16 @@ function unresolved(decision: Decision): boolean {
 	return decision.status !== "closed" && decision.status !== "delivered";
 }
 
+/**
+ * Bug 127: an unanswered ask_user_question with waitForAnswer false. Its tool call already returned, so its owner never
+ * waits on it; when its native wait ends (a generation drain, an owner release) the answer still reaches the owner as a
+ * follow-up command.
+ */
+function detachedQuestion(decision: Decision): boolean {
+	return decision.method === "question" && !decision.permission && decision.submissionId === null &&
+		record(decision.payload) && decision.payload.waitForAnswer === false;
+}
+
 /** Chat card footer for an item the user deleted from the inbox (web markResolved, Android resolvedLabel). */
 const DISMISSED_REASONS: Record<string, string> = {
 	user_cancelled: "확인함에서 삭제해 질문을 취소했습니다",
@@ -304,6 +314,8 @@ export class DecisionService {
 			...observation.payload, ...(workId === null ? { sourceEventSeq } : {}),
 			...(Array.isArray(sourceReferences) && sourceReferences.length ? { sourceReferences } : {}),
 		};
+		// A decision stored before bug 127 has no waitForAnswer mark; observing it again must not read as a changed question.
+		if (decision && record(decision.payload) && !Object.hasOwn(decision.payload, "waitForAnswer")) delete payload.waitForAnswer;
 		const bindingState = observation.permission && record(payload.nativePermission) &&
 			!this.store.hasNativePermissionAsked(owner.scope, owner.sessionPath, payload.nativePermission) ? "unknown" : "live";
 		if (!decision) {
@@ -358,7 +370,8 @@ export class DecisionService {
 		if (observation.method !== "question" || observation.permission || observation.required === false || typeof toolCallId !== "string" || !toolCallId) return null;
 		const siblings = this.store.allDecisions(owner.scope).filter((decision) => decision.sourceSessionPath === owner.sessionPath &&
 			decision.method === "question" && !decision.permission && record(decision.payload) && decision.payload.toolCallId === toolCallId && unresolved(decision));
-		const waiting = siblings.filter((decision) => decision.required && decision.bindingState === "unknown" && decision.reason === "owner_disconnected" &&
+		const waiting = siblings.filter((decision) => ((decision.required && decision.bindingState === "unknown" && decision.reason === "owner_disconnected") ||
+			decision.reason === "async_wait_closed") &&
 			decision.submissionId === null && decision.answer === null && record(decision.payload) &&
 			isDeepStrictEqual(decision.payload.questions, observation.payload.questions));
 		if (siblings.length !== 1 || waiting.length !== 1) return null;
@@ -413,15 +426,17 @@ export class DecisionService {
 			decision.submissionId !== null && record(answer) && record(answer.answers) && receiptOutcome &&
 			isDeepStrictEqual(event.answers, answer.answers) && (event.comment ?? "") === (answer.comment ?? "") &&
 			Array.isArray(event.unanswered) && event.unanswered.length === 0;
+		const detached = !received && event.outcome !== "timed_out" && detachedQuestion(decision);
 		decision = this.store.setDecisionBinding(decision.id, decision.revision, {
 			state: event.outcome === "timed_out" ? "expired" : "closed",
-			reason: event.outcome === "timed_out" ? "timeout" : "engine_wait_closed",
+			reason: event.outcome === "timed_out" ? "timeout" : detached ? "async_wait_closed" : "engine_wait_closed",
 		});
 		if (received) {
 			this.store.transitionDecision(decision.id, decision.revision, { status: "delivered", reason: "question_receipt" });
 		} else if (decision.submissionId !== null) {
 			this.review(decision.id, record(answer) && answer.cancelled === true ? "user_deferred" : "receipt_unknown");
-		} else if (event.outcome !== "timed_out") {
+		} else if (event.outcome !== "timed_out" && !detached) {
+			// A detached question stays pending: its answer goes by resume, as a follow-up command.
 			this.review(decision.id, "engine_wait_closed");
 		}
 		this.refresh();
@@ -446,7 +461,8 @@ export class DecisionService {
 		for (const decision of this.store.allDecisions(owner.scope)) {
 			if (decision.sourceSessionPath !== owner.sessionPath || decision.method !== "question" ||
 				decision.bindingState !== "live" || !unresolved(decision) || ids.has(decision.sourceRequestId)) continue;
-			this.store.setDecisionBinding(decision.id, decision.revision, { state: "unknown", reason: "request_missing" });
+			this.store.setDecisionBinding(decision.id, decision.revision, detachedQuestion(decision)
+				? { state: "closed", reason: "async_wait_closed" } : { state: "unknown", reason: "request_missing" });
 		}
 		this.refresh();
 	}
@@ -468,7 +484,8 @@ export class DecisionService {
 		if (this.stopped) return;
 		for (const decision of this.store.allDecisions(owner.scope)) {
 			if (decision.sourceSessionPath !== owner.sessionPath || decision.bindingState !== "live" || !unresolved(decision)) continue;
-			this.store.setDecisionBinding(decision.id, decision.revision, { state: "unknown", reason: "owner_disconnected" });
+			this.store.setDecisionBinding(decision.id, decision.revision, detachedQuestion(decision)
+				? { state: "closed", reason: "async_wait_closed" } : { state: "unknown", reason: "owner_disconnected" });
 		}
 		this.refresh();
 	}