# Zerus reference [Product overview](../README.md) | [Installation](installation.md) This reference covers session lifecycle, desktop workflows and native integration limits. Run `hgs -h` for the complete command syntax. ## CLI sessions `hgs` starts a command in a named project tmux session and attaches locally or through SSH. The session survives a closed terminal, an SSH interruption or a sleeping client while its host remains running. Terminal windows, tabs and splits belong to your terminal emulator; tmux provides the persistent session. ```sh hgs claude sample-project # attach if present; otherwise start Claude hgs @mac claude sample-project # the same operation over SSH hgs ls # local and peer sessions hgs status # version, sessions and services here and on peers hgs version # this hgs version (also hgs --version) hgs a claude/sample-project/review # attach by full name hgs kill claude/sample-project # remove the hgs binding; keep native history hgs pause --all # pause verified idle sessions hgs resume --all # restore saved sessions in the background hgs project ls # legacy local folder aliases hgs claude sample-project -c # continue the latest conversation in the folder hgs --dry-run claude sample-project # show the tmux/SSH command ``` Pass an absolute folder path when no alias is configured. `--new` generates a fresh session name; `--new -n review` uses your label and rejects an occupied name. Arguments after `--` go to the agent or project wrapper. Arbitrary terminal commands can run through `hgs`; native lifecycle and Activity functions require an adapter. Inside a session's own terminal (tmux on Linux and macOS, the session host on Windows), `hgs` never attaches or switches that terminal, so an agent starts other sessions detached. `hgs claude /path/to/project --new -n review -d` starts the new session beside the current one and prints `hgs: started NAME`, as `fork -d` and `resume -d` do; `hgs guide launch` gives agents the full form with `--launch-id`. A launch without `-d` and `hgs a` are refused there with exit 2 (`already inside tmux session NAME; use --new -d or open a new tab`; Windows names no tmux). The new session gets its own session and run identity, never the caller's. Its account comes from the launch (`--account ID` or the computer's default for that agent); the account profile that the calling session runs under is not passed on. Neither is the calling agent's command context (`AGENT_COMMAND_CONTEXT` in `src/state/backend/mod.rs`): Claude Code's and Codex's session, process and tool call markers, DeepSeek and OpenCode native session IDs, and `NO_COLOR`. A tmux server that a launch starts keeps none of them, nor the caller's session variables, in the environment it gives every later pane, and an agent starts without them even when a server already holds them. `hgs send` reads the agent's styled prompt; under `NO_COLOR` Claude Code's placeholder looks like a draft and every send is refused while it shows. Existing agents keep their launch environment. When a send refuses an unstyled Claude composer and the same verified agent process's readable environment contains `NO_COLOR`, the refusal explains that the session needs a restart. Unreadable or changed process evidence keeps the generic refusal. Zerus never restarts the session automatically or accepts unstyled hint text as an empty input. ### Session references **Copy session reference** in the desktop session window's **Session actions** menu copies a `zerus://session?...` URI. Android offers the same action in the session toolbar and menu. It contains the stable computer UUID, a native machine name for routing, the session name and exact conversation identity; child and archive references include their explicit identities. It contains no credentials. Paste the reference into another conversation to identify its source. An agent can run `hgs inspect ''` to read its Activity and recorded messages. The CLI verifies the computer UUID, follows a renamed session by its conversation ID, and rejects cleared, forgotten or ambiguous bindings. A conversation reference survives resume into a new run; an unconfirmed first-message reference requires the original run. A configured peer matching the machine name routes through SSH; use `hgs @configured-alias inspect ''` when its alias differs. A reference identifies a session; it authorizes nothing. Reading it with `hgs inspect` never acts on the session. Any other session command does with it exactly what it does with the session's name: `hgs send` sends input, and `hgs a` may resume a saved session. A reference never launches a new session and never addresses a session other than the one it names. Every other command whose first argument is a session also accepts a reference there, for example `hgs pause ''` or `hgs send '' --json`. It resolves the session the reference names, following a rename, and then acts under the same checks as `--session-id`. Every record the command reads under that name must still carry the reference's conversation (or its run, when it names no conversation), and `kill` and `a` bind the terminal to the verified run. An archived conversation's reference reaches the commands that take `--archive` (`processes`, `reference`, `fork`, `kill`, `rename` and `resume`). A child agent's reference stays read-only, for `hgs inspect`. A reference and `--session-id` cannot be combined. A reference to another computer routes to its configured host, or to `@host`, only after that peer's `hgs --help` lists `session-reference-selector-v1`. It takes exactly one verified hop: the peer runs the command guarded by the reference's computer UUID (`--expect-machine`), so a peer that is another computer refuses it (`the selected SSH alias does not match`), and no peer forwards it again. A guarded call itself never routes a reference to another computer. A reference may also carry a `session` field, the session ID, which is then checked as well. `hgs reference`, `hgs self` and message envelopes do not add that field yet, because an older hgs refuses an unknown reference field. `hgs [@host] reference --json [--archive ID] [--agent ID]` returns the same URI and readable identity fields. Optional `--run ID --conversation ID` guards ensure a copy action still addresses the selected conversation. An agent obtains its own reference with `hgs self [--json]`. Terminal agents are identified through their native process ancestry, never `HGS_SESSION` alone. DeepSeek and OpenCode tool shells already receive their native conversation ID as [`DSH_SESSION_ID`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/shell/shell-env/README.md) or [`OPENCODE_SESSION_ID`](https://github.com/anomalyco/opencode/blob/v2.2.7/packages/core/src/tool/plugin/shell.ts). Without a proven terminal caller, `self` resolves that claim against the native home and a live local binding. Its JSON reply distinguishes `identity_source` `process` from `claimed`, includes the durable `session_id`, and supplies `parent_identity` with the exact session, run and conversation for parent commands. The native lookup uses a derived index with authoritative rereads; its cold metadata scan is bounded to 5000 entries, 64 MiB and two seconds, and incomplete or ambiguous coverage refuses. A missing, stale, archived or unavailable native session refuses too. Current names follow renames. Native hosts need access to the same Zerus state/config paths; new OpenCode services retain only those two HGS path variables, never HGS session/run identity. `self` never routes to a peer and refuses `--dry-run`. Claimed identity never enters send/graph attribution, task ownership or permission proof. `hgs [@host] guide [send|wait|launch|stop]` prints compact instructions for agents that read, message, wait for, launch or stop other sessions. The text is compiled into hgs and stays small because agents read it into their context; topics are read only when needed. `@host` returns that peer's guide after probing its installed help, so an older peer fails without launching anything. Native conversation IDs appear only in **Details** on desktop and **Session details → Overview** on Android, labeled **Session ID** with a dedicated copy icon immediately after the exact identifier. The desktop icon uses the same borderless style as header actions. The ID stays on one line whenever the pane has room. The icon copies the ID as plain text, as does the **Copy session ID** icon in the desktop session header, which copies without showing the ID; **Copy session reference** is in the desktop session window's **Session actions** menu and copies the portable URI. Successful text copies use the window's status confirmation without a system notification on Linux or macOS. Before that ID is reported, **Run ID** identifies the current process run; it can change on resume. Child details also show their agent ID. Search accepts complete IDs or parts of conversation, run, archive and reported child IDs; a child match identifies its parent conversation. Machine, project and state filters still apply. Desktop ID results show the matched identifier and expose its complete value in the tooltip. The desktop session header keeps frequent actions as icons: open the session folder, open a shell there, **Copy session ID** and **Clear session**. Its **Session actions** menu shares the same checked handlers. A stopped session hides the Clear session icon and offers **Start fresh…** in the menu; an archived session shows **Restore session** in its place. **Restore session** follows the computer's restore decision, as batch Restore does; a computer that reports no actions keeps the earlier rule. A Claude or Codex session that exited before its first message reported a conversation ID but wrote no transcript. Its archive therefore does not offer Restore, and gives the reason "This session ended before its first message" (zerus-wyrqg). The archive summary checks this with one metadata read of the saved transcript (Claude's transcript, Codex's rollout): it must be a non-empty regular file. The restore's own check stays the authority. The session list context menu offers **Clear session…** for a live session where a stopped one offers **Start fresh…**. For a session that is not open, it becomes available once that session's own inspection confirms the conversation listed for it; choosing it opens the session and asks the same confirmation. ### Session row and window menus A session row's right-click menu keeps Mark needs attention, Mute, Compact/Expand row, Open terminal, Copy connect command, Copy session ID, Clear, Rename, Move to project and Terminate. Paused and archived rows keep the corresponding available actions, such as Start fresh, Copy restore command and Forget. Multi-selection keeps its batch menu. Open terminal connects to the selected existing run in the external terminal configured for this computer, including connections to remote computers. It uses `hgs [@computer] a NAME --existing --run-id ID`, so a delayed terminal cannot resume a stopped agent or connect to a replacement run under the same name. An original live startup run can connect before its first native conversation binding, including while it waits for startup trust. This does not resume it or answer trust prompts. If its identity changes while the menu is open, reopen the menu to use the current row. Offline, paused, unidentified and unsupported adapters show a disabled reason; DeepSeek's Native UI remains in Session actions. Copy session ID copies the native conversation ID shown as Session ID in the header and Details, rather than its name or run ID. Rows without this identity show a disabled reason. The session window's top-right Session actions menu retains Expand all collapsed, Open folder, Open shell in session folder, Pause, Fork, Set parent (and Detach), Copy session name, Copy session reference and Copy folder path. Show running commands is there when available. Their existing checks and confirmations apply. Identifiers such as `zerus-ab12` are Beads task numbers, not session IDs. Desktop message search finds their public mentions; Android session search finds mentions in the available session metadata and previews. A task mention alone does not establish a unique session identity. ### Static agent guidance The static hint source covers tracked Claude Code, Codex, Kimi Code and DeepSeek main conversations. Its native delivery is verified on reviewed versions. OpenCode 2.2.7 uses the native instruction entry described below; older hgs peers inject nothing. The hint points to `hgs guide` with fixed English text, independent of session name, computer and hgs version. Claude Code and Codex use the existing SessionStart hook context. Kimi uses one UserPromptSubmit JSON `message` per conversation, verified on interactive Kimi 2.5.3 launches, not the separate `--prompt` mode. DeepSeek hosts started by hgs register the same sentence for hgs-owned main agents; native subagents and sessions opened in the host's own UI receive no hint. An already-running host keeps its bridge until its next start and is never hot-reloaded. One effective copy means the latest prompt, not every hint retained in history: opting out does not remove old hint-bearing system messages, and re-enabling can retain them beside a new one. No channel changes user instruction flags, project launchers or saved native arguments, and none is sent as a person's Activity message. New conversations and previously unmarked conversations receive an attempt; repeated resumes suppress another attempt when the provider retains the context. Clear and compaction replace context for Claude Code and Codex and request a new copy. Kimi retains the existing hook part on resume and compaction, so those paths do not add another copy; clear creates a new conversation and emits once. A fork inherits suppression only from the exact marked context it forks. Renaming does not change the text or hint revision. Arbitrary commands and native subagents receive no hint. For OpenCode, new-session creation and a verified existing-session launch whose single-message native history read is empty write `PUT /api/experimental/session/{id}/instructions/entries/zerus.agent-hint` with `{"value": HINT}`. The exact conversation and hint revision are marked before the request; the mark is suppression metadata, not a delivery receipt. A failed or uncertain request does not block creation or resume and is not replayed, because another PUT could duplicate the retained entry. OpenCode retains the entry as effective prompt context across resume and compaction, without a durable `Instructions updated` history row on the pinned version. A clear/new session gets its own entry. Inspection and background polling never attach it. A resume with a marked entry does not write again. A reconciled pending creation follows the same emptiness check. An existing conversation with any native message receives no instruction-entry attachment; an unreadable or malformed history answer is not proof of emptiness. OpenCode persists a noninitial instruction delta as an `Instructions updated` system message. That makes the channel a durable transcript update rather than a history-free instruction entry. Previously unmarked conversations with turns instead use a context-only V2 plugin on OpenCode 2.2.7 or newer. Zerus loads its own plugin through a launch-only configuration overlay when starting a service; it never writes a plugin into the person's global configuration or project. Existing plugins and settings stay intact. A service already running is never restarted or changed to install the plugin. If the exact plugin source is not active, launch/resume reports that the optional hint is unavailable and inspection exposes `agent_hint_status.state` and its reason. Cold starts reclaim at most 16 verified Zerus plugin folders using a 100 ms maintenance deadline. Each unique launch folder records the exact service PID and birth after a matching launch environment is verified. Cleanup inspects only that service and keeps a folder while it is alive or uncertain, plus the latest service marker's folder. Unrelated protected processes and host churn do not block reclamation. A durable intent is written before spawn; abandoned prepared folders are unused, while unresolved starts and legacy unpinned folders stay retained. Unknown files and links also stay retained. The 256-folder limit remains an allocation backstop and never grants deletion authority or changes the person's OpenCode config. Forgetting a binding also retires its private hint route. Ambiguous routes stay blocked until a complete check finds no remaining binding; the check examines at most 64 entries and 1 MiB in 25 ms, retaining the route on any uncertainty. Each primary model request gets a bounded, read-only lookup of one exact saved run/conversation/workspace/service binding. Its decided policy, rather than the shared service's environment, controls injection. A stale, malformed, absent or busy binding supplies no hint. Native subagents are excluded. The plugin appends one system part without editing user messages, receipts or instruction history; it does not run for compaction, title or transient generation. The next primary request receives the hint again after compaction. A Zerus-managed service restart loads the overlay again and resume verifies readiness for that new service. Opting out on resume suppresses this context channel. Existing revision-one entry-backed conversations keep their entry and never enable the plugin channel. Configure optional injection in the hgs config file or caller environment: ```sh HGS_AGENT_HINT=0 # disable new hint injection globally HGS_AGENT_HINT_OFF="native-codex work" # exclude exact account IDs ``` Injection defaults to enabled. The global value accepts `0` or `1`; the exclusion list is whitespace-separated and uses `native-claude`, `native-codex`, `native-kimi`, `native-dsh` or `native-opencode` for the provider's own login. Environment values take precedence, including an explicitly empty exclusion list. Invalid or unreadable hint policy disables only optional injection with a bounded diagnostic; unrelated configuration validation is unchanged. `hgs guide` and `hgs self` remain available when injection is disabled. Opt-out does not remove context already retained by the provider. Each fresh start, resume, recovery, archive restore and fork resolves the current caller's effective hint policy again. Only those effective hint values enter the new process environment, after login-shell startup on Unix. The hgs config path is unchanged and policy is not stored in the saved launch recipe or binding. This is a process snapshot: editing the file does not live-reload a running native process. An `hgs` invocation inside that agent inherits the snapshot as ordinary environment overrides, which can continue to shadow later file edits. On Windows, an absent exclusion variable alongside the resolved global value means an empty list; the hook does not supplement it from another default file. The private conversation/revision mark suppresses retries; it does not prove stdout delivery or native acceptance. An output failure reports unknown delivery and is not automatically retried. There is no crash-atomic exactly-once promise. ## Pause, resume and reboot ```sh hgs pause claude/sample-project/review hgs pause --all # Reboot the machine running the agents after checking the pause result. hgs ls hgs resume claude/sample-project/review hgs resume --all hgs a claude/sample-project/review hgs @mac pause --all ``` Pause preserves an exact native conversation binding. It does not preserve open network connections, child processes or an unsent native terminal draft. Supported integrations include Claude Code, Codex, Kimi Code, the official DeepSeek Harness and OpenCode. DeepSeek and OpenCode use their native engines instead of a terminal-agent process. OpenCode sessions have no separate process to pause ([OpenCode controls and limits](opencode.md#controls-and-limits)). For terminal agents, pause verifies the live pane, run and conversation identity, native history, supported resume arguments and an idle state. It sends SIGTERM only to the verified agent process, checking its PID and start time, and waits up to ten seconds. It never kills the tmux server or escalates a failed pause to SIGKILL. `pause --all` preflights every live session on the host: an untracked agent, busy session or ordinary shell blocks the operation before the first signal. Once stopping begins, some sessions can fail independently; inspect the nonzero result before rebooting. On Linux and macOS, **Terminate** also ends the agent's verified descendant processes, including background jobs in separate Unix sessions. It temporarily suspends the agent and its descendants while collecting a bounded, fresh tree, pins every process to its birth identity, and confirms the complete stopped tree before closing the exact terminal. After the terminal accepts teardown, it kills the pinned agent and descendants and confirms their exit. The agent stays suspended until it is killed, so shutdown handlers cannot fork new jobs after verification. An incomplete check keeps the terminal; failed teardown restores only processes suspended by this operation. A failed or unconfirmed stop does not start worktree cleanup. Pause and native Stop keep their existing behavior. Process names, shared process groups and the working folder never authorize termination of other programs. Already orphaned processes whose session ownership cannot be verified stay untouched; a surviving process using the checkout still prevents its removal. Run Terminate from outside the target's own process tree. The dormant [Linux descendant-custody resource](linux-descendant-custody.md) is qualified separately. It has no installed caller and does not enable graceful Terminate or change the verified tree and cleanup rules above. The [dormant original supervisor bridge](original-supervisor-owner.md) retains source-bound ownership behind a const-false gate. Its read-only observations grant no graceful, signal or cleanup authority; owned-mode records refuse the legacy root-only finalizer. Restore uses `claude --resume ID`, `codex resume ID`, `kimi --session ID` or the supported native DeepSeek operation. It preserves the original folder, account and project wrapper. There is no fallback to the latest conversation or a new conversation when exact restore fails. `resume -d` and `resume --all` run in the background; use `hgs a ...` when native startup needs input. A normal launch with a saved name restores it; `--fresh` explicitly replaces its binding. `hgs resume SESSION --fresh [-d] [--expected-run-id RUN]` starts a stopped Claude, Codex or Kimi session with a new conversation from its own folder, account, safe launch options and model, like `/clear` in a live agent. The replaced conversation stays in native history and readable in Activity above a **Session cleared** boundary; a running agent uses **Clear session** instead. You can also resume native history created outside `hgs`: ```sh hgs codex -c 01a0e955-b037-73f0-bc6c-36622a8c27b7 hgs codex /path/to/project --resume=01a0e955-b037-73f0-bc6c-36622a8c27b7 -n review ``` After `-c`, IDs are recognized as UUIDs; Kimi also accepts `session_UUID`. Without an ID, `-c` continues the latest conversation in the project. An already tracked conversation keeps its session name; another gets `resume-ID` unless `-n` is set. An occupied name bound to another conversation is an error. Native history must remain on the selected host: project synchronization does not move conversations. Before the agent confirms its conversation and creates native history, pause is unavailable. Codex and Kimi may defer creation until the first message. Codex can also defer `SessionStart` after resume; Activity may send the first resumed message, pause or clear only after verifying the exact process, matching history and empty native input. Codex reports such a clear with the next message's `SessionStart`, which then names the new conversation instead of the restored one. A sent first message or an archive restore still waits for that confirmation. Unknown flags or noninteractive modes such as `codex exec` are not guessed. The original positional prompt is never replayed during resume. For Kimi Code whose help advertises a non-interactive `--prompt`, Zerus removes the initial message from native arguments and the saved resume recipe, then submits it through the ordinary guarded send path for the exact launched run. Folder trust and setup remain manual. `inspect` includes `launch_prompt` with a preview of at most 200 characters plus an ellipsis, request ID and status. The full text stays only in the launching supervisor until ordinary guarded submission stores its input receipt. Errors are limited to 512 characters plus an ellipsis. An undelivered message is cancelled when its child exits or shuts down. After an attempted submission there is no automatic retry, including on refusal or an uncertain delivery. Review the preview and ordinary input receipt before sending it manually. Capability detection and native spawn use the same resolved executable after account environment setup. A custom `run_kimi.sh` keeps its own argument contract and is never invoked a second time for help; `--bare` selects the native Kimi launch behavior described here. A launch interrupted before conversation confirmation is not a Saved session. Repeat the same command without `--fresh`; the diagnostic attempt is preserved in `attempts/`, and native history is retained. Old untracked sessions cannot be safely paused: launch the intended conversation with its explicit native ID to bind it. ### Tracking and durable state Every session record has a durable `session_id`, a UUID assigned when the session is first created. Every write of this hgs keeps it: resume, Clear and fresh starts, rename, pause, archive and restore. A fork is another session with its own. A record written by an older hgs gains one the next time this hgs writes any of its records, including archives. The ID is stable across writes of this hgs version and later ones. An older hgs, after a rollback or in a mixed fleet, rebuilds a record on resume without this field; the next write here then assigns a new ID, once. Consumers therefore treat `session_id` as a hint and fall back to the run and conversation identities. The agent's environment carries it as `HGS_SESSION_ID`, beside `HGS_SESSION` (the name at launch) and `HGS_RUN_ID`, and `hgs ls --json` rows and inspections include it. A hook first resolves the agent's `HGS_SESSION_ID` through the ID index, under whatever label the session carries now. Failing that, it prefers the record that carries the ID; when none does, for example after an older hgs rewrote the record, the run identity alone decides, as before. A session this hgs creates keeps its history under its durable ID. Its Activity, read marks and notification preferences are keyed by `journal_name`, which is `session:`, and `launch_label` keeps the label it was launched with. Rename, resume, Clear, Start fresh and restore keep both. A later write here can give the session a new ID after an older hgs dropped it; the journal stays where it is. A `--fresh` launch over a saved, confirmed conversation of the label is a new session with its own journal; only a retry of an unconfirmed attempt continues that attempt's journal. A session created before keeps the history of its label, pinned at its first rename. hgs v0.47.0 and later read `journal_name` and keep it on every one of those paths. A command whose first argument is a session also accepts `--session-id ID` instead, for example `hgs inspect --session-id ID` or `hgs rename --session-id ID NEW-NAME`. A name given before the flag must be that session's current name; arguments after it are the command's own. The value must be the lowercase UUID shown by `hgs ls --json`, given once. Resolution reads the verified index `ids/.json` under the state directory, which names the session's current label. A missing or stale entry costs one scan of the records, which repairs it when the state lock is free. Hooks never repair, and an index this process cannot write is left alone. An older hgs ignores the index. Resolution only finds the session's name: every record the command then reads under that name, live or archived, must still carry the ID, so a name another session took meanwhile fails with "Session ID ID no longer names NAME" instead of acting on it. `kill` and `a` bind the terminal before their first effect: the name's immutable terminal session must run the run that the verified record carries, and they then act on that terminal session, never on the name. A `--run-id` given to `a --existing` must name that same run. An OpenCode session's attach goes to its own adapter, which checks its binding and run the same way. `hgs task` keeps its own `--session-id`, `notify` and `paste` stay the tray's and tmux's own entry points, and an agent's own flag after `--` is untouched. With `@host` the flag reaches a peer only once its `hgs --help` lists `session-id-selector-v1` and every marker the call needs already, including a guarded `--expect-machine` call that wraps the command and `native-ui`, whose peer resolves the ID itself; an older peer is refused with "update the selected computer". Names stay unique for now. When several sessions later share a name, commands exit with status 5 and list the candidates; see `docs/superpowers/specs/2026-11-04-session-names-as-labels.md`. Because an older hgs can change a session's ID once, a client whose `--session-id` is no longer found treats the session as changed and never retries the call: its next action uses the refreshed listing, with the name and its expected run and conversation identities when the row lists no ID. A session's terminal has its own name, kept in the record as `terminal_name` (zerus-ucck P3b). A launch gives the terminal the session's label when no terminal session has that name, so `tmux attach -t LABEL` reaches the session as before. A record an older hgs wrote has no `terminal_name`; its terminal is its label. A tmux session that hgs never started, such as one opened by hand, may already hold the label of a saved session. A resume or Start fresh then names the session's terminal `LABEL~`, or `LABEL~` when that is taken too, and refuses when both are. Earlier hgs skipped such a resume as already live. In that case `tmux attach -t LABEL` reaches the other tmux session, while `hgs LABEL`, `hgs a LABEL`, `hgs kill LABEL`, pause, terminate and every other command act on the session's own terminal, after checking its pane and run as before; none of them touches the other tmux session. `hgs ls` lists the session under its label. A rename moves a live session's terminal to the new name and records it; when the move fails, nothing changes. A rename of a stopped or paused session clears its terminal name, so its next launch names one anew. A session is live only in its own terminal, with its pane and run, or while a launch of its own label holds that terminal; a tmux session another launch started under its terminal name never makes it live and never hides it from `hgs ls`. When hgs cannot read a terminal's environment to tell whose launch it is, it refuses and starts nothing. A new launch, fork, rename or restore still refuses a label that any tmux session holds. A build older than this one finds no pane for a session whose terminal is named otherwise, shows it as not live and drops `terminal_name` when it rewrites the record. New session tags (launch, rename and fork) refuse shell metacharacters, curly quotes U+2018–U+201E and invisible Unicode formatting characters (category Cf). Letters and digits from any script and internal spaces remain valid. This is an additional check on newly chosen tags: existing labels remain valid selectors, and an old label can be renamed to a safe tag. Always quote names in shell commands; older peers and retained labels may still contain shell syntax. When several sessions share a label (zerus-ucck P3c), a command picks one by the identities it carries. These come from its command line (`--expected-run-id`, `--run`, `--run-id`, `--expected-conversation-id`, `--conversation`) or from its JSON request (`expected_run_id` and `expected_conversation_id`; `run_id` and `conversation_id` for `hgs read` and `hgs notifications`). - Exactly one session carrying them is the one, and every later read in that command still checks both identities against it. - None carrying them is refused as a changed session (exit status 1). The command then reads none of the sessions under that label. - With several, or with no identities at all, the command exits with status 5 and lists the candidates (as JSON under `--json`). This holds for `inspect`, `pause`, `rename`, `archive`, `kill` and others that take no identities. - `--session-id` and references always select exactly. - `pause --all` and `resume --all` refuse a label that several sessions share; act on each with `--session-id`. When a session leaves, hgs releases its own Git worktree lock. A session leaves by an archive, by `terminate` with or without `--forget`, or by forgetting its archive. Its own lock is one whose reason is exactly `zerus:`, on the checkout Zerus created for that session. - hgs never touches a person's own lock, another session's, or any lock on a folder Zerus did not create. - The lock stays in three cases: - another live or saved session uses the checkout; - the checkout's Zerus ownership cannot be verified; - the sessions that might use it cannot all be read. hgs then says on standard error why it kept the lock, and the archive stands. - The release never forces Git. It sets the lock aside and checks its text, and removes it only when the text is exactly that session's. Anything else is put back, never over a lock that appeared meanwhile. A lock left aside by a crash is put back by the next hgs command. Nothing in this version creates such a lock. The desktop client adds `--session-id` only to explicit actions: send, send now, answer, queued-message removal, clear and compact, interrupt, model settings, pause, resume, start fresh, rename and fork. It does so when the listed row for the action's exact run carries a session ID and that computer's `hgs --help` lists `session-id-selector-v1`; the answer is kept for ten minutes. Reads, polls, history, status, watch, terminal input and read marks keep the name until a label index exists. Confirmed delayed and worktree-cleanup end actions keep their scoped envelope, which already names the exact run and conversation. Archive, Terminate, Kill and Forget run only that way: without their undo window's capture (or a confirmed worktree cleanup) the desktop runs none of them, and it never sends a name-only `hgs archive` or `hgs kill` or a run-only `hgs terminate` (zerus-sa9qn.25). Clear archive's Forget stays bound to each entry's archive ID. A refused ID shows as a changed session, but only when the CLI refused it while resolving it: another name, no session or several sessions. A later read's "no longer names", which can follow an effect, keeps the action's own result. `hgs session-action-status SESSION --json` reads one original lifecycle receipt. Supply the original `session-action` JSON unchanged, including its `request_id`, `action`, `expected_run_id`, `expected_conversation_id` and any original action arguments. The request is limited to 8 KiB; the existing private receipt is limited to 64 KiB. Its request digest, identities and result target must match. The reader opens no writer or lock, initializes no missing state, and leaves the receipt unchanged. It omits private native diagnostics. A stored `claimed` receipt is reported as `uncertain`; a later fresh read can observe the original writer's completed receipt. Missing evidence reports `unavailable`. Neither result proves that nothing ran or authorizes a retry. Malformed, unsupported or unsafe receipts are refused. This API covers only `session-action`, including Archive, Terminate and Forget; `clear-context` has separate receipts and is not accepted here. For a peer, use `hgs @example-peer --expect-machine MACHINE_UUID session-action-status SESSION --json`. The selected executable must advertise `lifecycle-receipt-status-v1` and the existing machine guard before JSON is forwarded. Its existing private Swarm catalog supplies the machine identity without initialization, locking or saving. An unguarded remote receipt read is refused. This reader is a recovery prerequisite; it does not enable durable delivery of pending Undo actions when Zerus quits. The independently reviewable [pure shared journal model](desktop-quit-journal.md) also leaves current Quit behavior unchanged; the actual store and detached delivery remain separately gated. The proposed [native quit-store design](desktop-quit-store-design.md) uses a persistent per-OS-user location derived from the effective UID's passwd home, never from `$HOME`: `/.local/state/hgs/quit-v1/` on Linux and `/Library/Application Support/hgs/quit-v1/` on macOS. Before any production anchor open, create or stat, an isolated launch must refuse durable delivery: HOME differs from that OS home, XDG state/data/config points away from its default, HGS_STATE_DIR or HGS_CONFIG_DIR was explicitly set, an install prefix is explicit, CLI selection (`ZERUS_CLIENT_HGS` or `--hgs`) or fleet routing (`HGS_SELF`, `HGS_PEERS`, `HGS_SSH`) is explicit, or a test/replay/headless marker is present. Empty, non-UTF8 and default-looking explicit selectors also refuse. Native origin evidence must precede Config::load's default HGS_STATE_DIR injection and the GUI's `--hgs` conversion; later mutations cannot erase an original override. Such launches keep drop-on-Quit. The proposed future caller uses a freshly selected, translated note in the group's existing Undo toast at registration; a refusal first discovered at Quit is diagnostic only, with closed codes and counts. The initial strict fence also excludes the maintained Mac LaunchAgent's `--hgs` launch and Linux launches passing it. Exact selected executable/configuration origin must be qualified on both maintained launch paths before delivery is enabled anywhere; this is tracked separately as `zerus-5wmh.66.2.34.3.5`. Tests use typed fixture scopes and decoy anchors; they never probe the owner's real anchor. Missing or tampered existing state requires explicit operator recovery, with unresolved charges retained. These are design requirements; the current runtime has no durable quit-store caller. Windows stays fenced. The proposed cleanup restriction also needs a native Git worktree lock before either version-2 ownership write: private legacy CLI controls showed that version-2 refusal alone does not fence fresh old manual removal. Worktrees retains the existing Blocked/locked reason. Exact new review/release semantics and the full legacy caller, partial-cut and crash/restart matrix remain separate gates; no runtime hold or unlock is implemented. Hold installation and delivery must not ship before the reviewed release surface is available in the same or an earlier build. A private actual V1-hgs/native-Git race also showed that Git 2.56 can remove a checkout, its V2 marker and a newly installed native lock after its already-issued remover passed the absent-lock check. A Git lock therefore supplies no drain proof. The proposed hold now requires verified native quiescence **and exclusion through publication before any hold write**, across old configurations and paused callers. Kernel birth/cwd/open-file evidence must be complete; hidden/unreadable or omitted observations are UNVERIFIED. Existing process helpers and repeated empty snapshots do not provide atomic exclusion, and no qualifying mechanism is available yet. If that proof cannot be established, publish no hold or durable delivery for the worktree and keep today's drop-on-Quit with the registration-time Undo note and Quit-time diagnostic boundary above. Today's Tauri client has no visible Quit notice; current toasts and the bounded local stderr drop line remain unchanged until the qualified caller lands. No new confirmation, exit delay or next-start notice is introduced for pre-hold refusal. After any partial hold, retain denial/manual recovery instead of rolling it back. No signals, restarts, process-name assumptions, old consent or unlock/downgrade repairs close the race. See the design's exact negative evidence and still-unprotectable legacy windows; R3, the full matrix and the shipped release-surface gate remain unchanged. This is documentation only. The proposed store and capture spool are excluded from all exports, diagnostics bundles and Private analytics aggregate export and are never uploaded. Logging and operator recovery output contain bounded counts, reason codes and digests, never stored session names, paths or targets. Installers and updater flows must preserve admitted helpers/children without signals or indefinite waits, and a replacement GUI must respect their still-charged global generation. `hgs hooks --account native-claude --json` inspects the account's hook registration without running the agent. Use another exact account ID for an isolated profile. The report contains provider/account identifiers, configuration and path fingerprints, expected/present/missing/duplicate event names and cached version compatibility, never settings, commands, prompts or credentials. `unrecognised_tracking` is true when an entry runs `PROGRAM __state hook` or `PROGRAM __state answer-channel` for an unrecorded program whose basename contains `hgs` (case insensitive), but is neither an hgs basename nor the current runner. The name is ambiguity evidence only, never ownership. Unrelated programs using these arguments remain personal hooks and do not block repair; the report never names them. This flag is only in the account report; `hgs hooks SESSION --json` keeps its hooks-health-v1 fields. DeepSeek and OpenCode report `not_applicable`: they use their native APIs instead of tracking hooks. An unavailable or changed executable-version cache means compatibility `unknown`; inspection never runs `--version` or refreshes that cache. `hgs hooks SESSION --json` accepts a JSON object on stdin containing `request_id`, `expected_run_id` and `expected_conversation_id`. Only that exact bound conversation is inspected. Its `observed` field counts known main-agent callbacks recorded after this feature was enabled in that run/conversation; older bindings or silence report `unknown`, not broken hooks. The summary is bounded by the known event names and never scans native history. Registration, observed callbacks and provider-effective settings/trust are different evidence: `effective` and `trust` remain explicitly `unknown` in a file inspection. Project settings, policy, native trust or a running agent's already-loaded settings can make its effective hooks differ. Attaching does not retrofit them. On Linux and macOS, a Claude hook's `HGS_SESSION` and `HGS_RUN_ID` select a record; they do not prove its caller. A pinned record also requires a stable native process ancestry from the hook to its recorded Claude PID and start time, outside any resident DeepSeek host. A held Claude background job uses its own proven ancestry and the matching window/job hold in the window's recorded account registry; a missing account directory refuses background routing. Caller-selected config and home directories grant no authority. New Claude launches record the effective registry directory separately from `agent_home`, preserving an unset native config directory and its macOS Keychain namespace. Older records without either directory retain foreground hooks; their separate background jobs cannot be proven and receive a diagnostic. Unproven callers receive a bounded diagnostic on stderr before any hook or continuation update, or answer-channel registration. The Claude answer channel only binds Claude records and refuses a later provider change. Channels recheck their proof before claiming and emitting an offer; losing proof after a claim leaves its result uncertain and never authorizes another delivery. Older, unversioned records without a complete PID/start pin retain their existing hook behavior with a visible legacy diagnostic. A record carrying a pin never uses this exception, and a versioned native launch with a missing pin is refused. An unavailable ancestry walk refuses pinned records visibly; it does not silently discard their hooks. Windows retains its existing hook path pending native qualification. Hooks outside Zerus, without the session and run markers, remain no-ops. Explicit configuration repair is native-only: `hgs hooks --account ID --repair --json`. Its stdin must contain a fresh UUID `request_id`, `expected_provider`, `expected_account_id`, `expected_config_sha256` and `expected_path_id` copied from the inspected account report. Repair refuses changed content, account/path/symlink identity, malformed or oversized files and unknown/incompatible native-version evidence. It also refuses, without writing, while `unrecognised_tracking` is true: run it with `HGS_EXECUTABLE` set to that wrapper, or use a supervised launch with that runner to record it. Otherwise review or remove the ambiguous entry manually. Repair migrates recorded tracking/channel entries to the current runner and merges missing HGS tracking registrations under the existing hook lock and atomic backup rules, preserving personal settings/hooks and trusted legacy commands. It never trusts hooks, enables/widens answer channels, changes permissions, restarts a provider or retrofits running agents. If compatibility is unknown, explicit repair is unavailable. The current cache is normally populated for Claude's version-qualified hooks; Codex and Kimi can remain unknown even after launch. Their normal supervised launch retains the existing hook installer, but this diagnostic never invents version evidence. Review the returned configuration and any conditional matchers rather than treating a successful file edit as proof that hooks are effective. Existing partial Kimi blocks require manual review or a supervised launch: explicit repair refuses to rewrite them lossily. Complete account-wide Kimi tracking registrations, including legacy Python compatibility commands, are reused without adding another managed block. If that block was already added and contains only the same HGS callbacks and options, launch or compatible explicit repair removes the redundant block while retaining the original commands and personal settings/hooks. Different options or personal entries prevent removal. This edits registration only; a running provider's already-loaded settings are not retrofitted. Activity recognizes duplicate Kimi callbacks by their native turn ID within the same run and conversation. Equal captions in separate native turns or cleared conversations remain separate messages. For Kimi releases that omit the Stop hook, inspection and listing can settle the exact current main turn from a bounded, stable main-wire `turn.ended` or `prompt.completed` event. A matching TurnStarted identity is required; a newer prompt, incomplete wire, outstanding tool or changed run/conversation prevents settlement. Reply text never proves completion. Stop and wire evidence share one durable completion and reply ID; background jobs and subagents remain active until their own work finishes. For older attachment callbacks that lack that ID, a complete bounded native history and a unique exact staged-file input can associate their rich file card with the one native turn. The confirmed local delivery can supply the receipt before its durable inspection metadata arrives; both copies share one delivery ID. Incomplete or ambiguous evidence never authorizes this native-turn association. The original journal is retained. The additive mobile operation `hooks_status` exposes only the exact-session read, and only when the selected CLI advertises `hooks-health-v1`. Both outbound connectors preserve the request/run/conversation identity. The relay and gateway refuse account-wide, repair, archive and child extensions; no mobile hook write operation or client repair UI is advertised. Diagnostic receipts have short read-only retention and never authorize replay of a mutation. At launch, `hgs` adds handlers to Claude `settings.json`, Codex `hooks.json` and Kimi `config.toml`, preserving other hooks and making a `.pre-hgs` backup before the first edit. It respects `CLAUDE_CONFIG_DIR`, `CODEX_HOME` and `KIMI_CODE_HOME`. Handlers do nothing outside an `hgs` run. `HGS_TRACKING=0` disables registration for new launches. Native hook trust still requires an explicit user choice in Codex. Claude Code's `PostModelSwitch` is registered only once `claude --version` reports 2.1.296 or later: older versions stop every start at a settings warning for a hook event they do not know. Until then each launch reads the version again; a version that cannot be read gets no such event. A launch through a project `run_claude.sh` never reads it, because a launcher runs only under supervision. Once registered, the version is read again only when the `claude` executable changes; a version older than 2.1.296 then has hgs remove its own `PostModelSwitch` entries before a tracked start, dropping the event only when nothing else is left in it; started outside hgs or with `HGS_TRACKING=0` first, it still warns until then. The user's own hooks for that event stay, and older versions still warn about those. An unreadable version or a launcher keeps the entry, as does a wrapper script that starts another Claude Code without itself changing: delete the entry from its `settings.json` by hand there. `PreModelSwitch` is never registered. Claude Code can offer once, at startup or under a finished reply, to make auto mode the default permission mode when the user settings name another default. Activity shows the offer with both native choices; Zerus never answers or hides it, and only the choice made in Activity or Terminal changes that setting. Claude Code reports its context window only to a status line command. For a tracked Unix start of the `claude` CLI that reports 2.1.296 or later (the version read as for `PostModelSwitch`), `hgs` adds `--settings` with its own `statusLine`, `hgs __state statusline`, to the agent's command line; no settings file changes and the saved launch arguments stay as typed. The command keeps the run's latest `session_id`, `model.id` and `context_window.context_window_size` from Claude's input in `context-telemetry/` of the state folder, one file per run; a new run removes those not updated for 30 days. It then runs the status line Claude would otherwise use: the `statusLine` of the user settings file (`CLAUDE_CONFIG_DIR` or `~/.claude`), then the session folder's `.claude/settings.json` and `.claude/settings.local.json`, each later file's fields over the earlier ones. It runs that command with `/bin/sh -c`, Claude's input, environment and folder, prints its output and exits with its status, so Claude shows the user's status line as before and a change to it applies at once. Its `padding`, `refreshInterval` and `hideVimModeIndicator` are copied at launch. Without a user status line nothing is printed; Claude 2.1.296 then keeps one empty row below the prompt. Claude keeps its own status line, and the session reports no window, on Windows, through a project launcher, with an older or unreadable version, when the launch passes `--settings`, `--setting-sources`, `--project-config-root`, `--managed-settings` or `--worktree` (`-w`), when managed settings exist (`/etc/claude-code` or `/Library/Application Support/ClaudeCode`, or `CLAUDE_CODE_MANAGED_SETTINGS_PATH`), when a settings file cannot be read or its status line is not a command, and when the session folder lies below another repository root (an enclosing repository, or the repository of a linked worktree such as a generated one) and the local settings of that root or of the folder set one: Claude reads one of the two by ownership checks. Tracked Codex needs `--no-daemon`; the integration has been verified with 0.160.0, while 0.155.1 lacks that required flag. New hooks call `hgs __state hook`. Existing trusted Python commands are retained: `hgs_state.py` forwards them to the Rust CLI, so keep Python for legacy hooks. hgs recognises its own entries by the program they run: a path named `hgs` or `hgs.exe`, a legacy `hgs_state.py`, exactly the current `HGS_EXECUTABLE`, which a wrapper may name differently, or a program hgs recorded for that settings file. A later launch therefore adds no duplicate registrations. After a launch or explicit repair leaves an hgs entry that runs the current program, hgs records that exact program for the resolved settings file in private state (`hook-owners/` below the state directory, up to 8 programs of up to 4 KiB each, written atomically under the settings lock). Health and repair from a shell without that `HGS_EXECUTABLE` therefore still recognise the entries a wrapper wrote. When the current runner changes (including a different `HGS_EXECUTABLE`), the next install or compatible explicit repair rewrites those exact recorded tracking/channel entries to the current runner and records it. Shell migration accepts only the exact standalone form hgs writes; composed commands, comments and alternative quoting remain byte-for-byte unchanged. Other entry fields, personal hooks and trusted legacy commands are preserved. An unrecorded old wrapper is never silently claimed or deleted: use the exact wrapper as `HGS_EXECUTABLE` for a repair or supervised launch to record it first. Nothing is recorded for a program hgs did not write. Earlier versions added another group for a wrapper at each launch. Exact copies of such a group are removed once, and Codex may ask to review that change. A group that holds any personal hook is kept as it is, and a command for another program is never treated as hgs's. Codex can request **Hooks need review** before both a new session and a saved conversation's resume or archive restore. Activity shows that exact native decision; messages remain blocked while it is open. Only the person's choice trusts or skips hooks: in Zerus, or through an agent's `hgs answer` at the person's request in that agent's own conversation (a standing request counts until the person withdraws it) or for a member of a team whose `confirm_trust` setting is on. Codex persists that choice. A pending message receipt is never retried by recognizing or answering the card. Normal supervised startup preserves existing tracking definitions; an unchanged registration does not require trust again merely because the Zerus binary was updated. New or changed definitions can require a new native review. The CLI and session core are Rust; SQLite is bundled and requires a C compiler at build time. Existing session bindings and provider history remain compatible. Session records live in `${XDG_STATE_HOME:-~/.local/state}/hgs/sessions`, or `HGS_STATE_DIR`. Writes are atomic and synchronized to disk. Records contain the command and arguments, folder, conversation ID and run identity; environment secrets are not saved. A secret passed directly as an argument is still an argument and can appear in the private record. Native agents retain their full history. Late events from a previous run and child-agent events cannot rebind the parent. `runtime_state`, `process_state` and `conversation_state` distinguish the tmux terminal, agent process and native conversation. `SessionEnd` alone does not prove process exit. A live process without verified activity shows **Status unknown**; **Agent exited** means the process ended while its tmux terminal still exists. Archive listings and `inspect --archive ID` report `activity` and `phase` as `ended`. The immutable archive retains its last hook state and native conversation identity for history and restore; those saved hooks do not establish current work. ### Child sessions A new session that a live tracked agent launches on the same computer is that agent's child. Terminal-agent forks also record their launching caller. The launching `hgs` proves its caller by native process ancestry, as the process-proven mode of `hgs self` does, and passes it to the new session as `HGS_PARENT`; it always sets the variable, empty when no live agent owns the launch, so an inherited or typed value never reaches the record. The new session's first record keeps it as `parent`: the parent's machine UUID and durable `session_id`, its name, conversation and run as hints, `source` (`launch`, `adopt`, `manual`, `claimed` or `forwarded`) and the time. A resume never adopts its launcher. Resume, Clear, fresh starts, rename, pause, archive and restore keep the link, as they keep `session_id`; an older `hgs` that rebuilds the record drops it. Claude, Codex, Kimi, DeepSeek and OpenCode sessions can be children and manually chosen parents. New DeepSeek and OpenCode bindings record the proven launcher directly, before native creation; they never trust an inherited `HGS_PARENT` value. DeepSeek and OpenCode agents cannot prove process ownership from their shared host. They can explicitly claim a parent identity: `adopt` may also name `parent` with an exact `session_id`, `run_id` and `conversation_id` (optional name hint). The parent must freshly match a live session on this computer; the recorded source is `claimed`, distinct from process-proven `adopt`. The same choice is accepted by new `hgs claude/codex/kimi/dsh/opencode` launches as `--parent JSON`, for example `--parent "$(hgs self --json | jq -c .parent_identity)"`. This explicit choice overrides automatic launcher detection, must still match at launch, and never reparents an existing/resumed session. Use `hgs parent` for an existing session. The installed help marker is `claimed-parent-v1`; explicit peer launches require it. The selected computer checks the claim against its own sessions, so the claimed parent must be live there: a claim copied from an agent on another computer (`hgs @peer dsh … --parent "$(hgs self …)"`) is refused and nothing is recorded. `hgs self` never routes to a peer. A DeepSeek or OpenCode parent must confirm it is live within 2 seconds; a host that has not answered by then is refused as busy, never counted as live. Claimed links are presentation/attention metadata like manual links and grant no operation or permission authority. A launch or fork on another computer (`hgs @peer claude …`, `hgs @peer fork …`) run by a proven agent passes that agent's link to the peer as `--parent-link`, hex-encoded JSON, only when the peer's `hgs --help` lists `launch-parent-v1`; an older peer launches without it. The peer accepts only a well-formed launch link naming another computer, records it with the `forwarded` source and uses it only when no local agent owns the launch. It cannot verify a parent on another computer, so its listing always shows a forwarded parent as `missing`, even when its IDs match a session there, and the child is never supervised. A cycle check stops at a forwarded parent. `hgs [@host] parent SESSION --json` reads JSON stdin with `expected_run_id`, `expected_conversation_id` and `action`: `read`, `adopt`, `set` or `clear`, plus optional `replace`. `set` names `parent` with the chosen session's `session_id` and, as the desktop listed them, its `name`, `conversation_id` and `run_id`; the host reads that session on its own computer the same bounded way, and refuses an archived, changed or missing parent, the session itself and a cycle. `hgs --help` lists `session-parent-v1`; a call to a peer without it is refused before it reaches the peer. `adopt` makes the calling agent, proven the same way, the session's parent. It refuses a caller that no live agent owns, a session adopting itself, archived sessions, a target that already leads the caller on this computer (a cycle), and a session with another parent unless `replace` is true. The cycle check follows at most eight of the caller's parents through the session ID index, reading each record bounded, as a regular file only, never following a final link or waiting on a FIFO; a longer chain or an unreadable parent is refused rather than assumed acyclic. Coordinators use it for workers they direct but did not launch. The answer names the link now in effect and the previous one. Links are presentation and attention routing only: they never authorize a send, answer, approval, stop or removal, and never change project membership. `hgs wait` dependencies, native subagents, names and folders never create one. On the desktop the session menu offers **Set parent…** (a searchable list of the computer's other Claude, Codex, Kimi, DeepSeek and OpenCode sessions, never the session's own descendants) and, for a child, **Detach from PARENT…**. Dragging a session card onto the middle of another card on the same computer frames it and asks to make the dragged session its child; the upper and lower parts of a card still reorder. Every change is confirmed in a dialog, which names a parent it replaces, before the desktop calls `hgs parent`. Ending a parent never ends its children by itself (zerus-sa9qn.17). `hgs [@host] terminate SESSION --with-children` and `hgs [@host] archive SESSION --with-children` are the explicit choice to end them too. The parent runs first with its own command and rules; only when it succeeds does each live (non-archived) descendant on that computer get the same command, one at a time, every child before any grandchild and at most eight levels deep. A link names a parent by its session ID; only a link without a session ID names a parent listed without one, by conversation. This is stricter than the listing's nesting, which also falls back to the conversation for a link with a session ID. A link another computer forwarded never matches. Each child call is bound to the session ID, run and conversation the listing showed, so a session that took the label meanwhile, or the child restarted into another run or given another conversation, is refused, and Terminate also passes `--expected-run-id`. Each child keeps its own rules: Archive takes only stopped or paused sessions, Terminate stops a running child and also moves a stopped or paused child to Archive (as `hgs terminate` does for any such session; the desktop's Terminate leaves those children as they are), a DeepSeek or OpenCode child refuses an action it does not support, and no working folder removal is implied; the configured worktree maintenance treats an archived child as any archived session. A child that is not ended is reported on standard error and never retried, and the command exits 1 with how many were not ended. With `--dry-run` it validates the parent and lists the children it would end. A parent refused or unknown ends no child. An older peer without the flag refuses it as a usage error before acting. On the desktop, the Terminate confirmation of a session with live child sessions on its computer, and a Move to archive confirmation shown only for such a session, list them and offer **Also end N child sessions** (Archive: **Also archive N child sessions**), off by default. Children the action does not apply to now (Terminate takes running sessions, Archive stopped or paused ones; an offline computer or a write in flight leaves one out too) are listed as staying. The count and the list cover every level, not only the direct children, and the confirmation says so. As on the command line, a session whose link its own listing marks `missing` (a link another computer forwarded is always `missing`) is never offered, although the list may still nest it. One deliberate difference remains: when a child's link falls back to its parent's conversation ID because the parent was listed without a session ID, the desktop still offers that child, by name, but `hgs terminate --with-children` does not end it. At most 50 are named; the rest are counted. When chosen, the children run after the parent's own outcome is done as one preconfirmed selection batch: each through its own guarded action, rechecked as the same instance, one at a time and never retried, without the parent's Remove working folder choice. Like every end action started in the desktop, each child's call passes the undo window and runs the scoped `hgs session-action` envelope with the run and conversation the confirmation listed, so a child restarted or given another conversation meanwhile is refused and kept. A Terminate child without an HGS archive is killed, as its own Terminate and a selection's Terminate kill it: it leaves the list and any native conversation history is kept. The confirmation marks each such child and counts them. Terminate lists a stopped or paused child as staying and notes that `hgs terminate --with-children` would move it to Archive. A parent that failed or whose outcome is unknown keeps every child. One notice counts the children ended, failed or changed, and unknown. `hgs ls --json` rows carry `parent` with `state` from the same listing: `live` (running, its agent not exited), `saved` (paused, stopped or exited), `archived`, or `missing` when this computer lists no such session (gone, or on another computer). Neither the listing nor the launch waits on the shared catalog: the link's machine identity is read once a caller is proven, without the catalog lock, and a launch without a readable identity records no parent. The live session context menu offers **Add to favorites** and **Remove from favorites**, including independent child sessions. A small star marks a favorite. Favorites stay in their existing project and parent hierarchy through collapsed groups, retaining only necessary ancestor context; unrelated siblings stay collapsed. A favorite's own child toggle independently shows or hides its native subagents and child sessions, even below a collapsed ancestor or project. Favorites also keep the necessary ancestor rows visible. These context rows start collapsed, but their own toggle can explicitly open their branch without opening the higher ancestor or its other branches. Favorites never override state, search, machine, project, account or folder filters or change status and filter counts. The local `sessions/favorites` preference uses canonical machine UUID plus durable session ID, surviving rename and restart without transferring to a reused name or row key. It keeps at most 2048 identities, oldest first; a row without those IDs cannot be favorited. Native internal subagents have no independent favorite preference in this version. The desktop session list nests a child under its parent when both are shown in the same project group, 26 px per level up to three levels, with a connector from the parent above. The parent's footer shows **Team** with working and all child sessions and native subagents together, working of all (`2 of 5`); this one toggle shows or hides both (owner, 2026-11-07, zerus-sa9qn.16), and Left and Right do the same from the keyboard, Left then moving from a child to its parent. A native subagent row looks like a compact session row (the agent's tile, its parent's account mark, its name and status, the summary as its tooltip) and never expands; the expand button's place stays empty, so its status lines up with the rows around it (owner, 2026-11-08). This device remembers a collapsed parent across relaunches by its computer's machine UUID and session ID (`sessions/collapsedTeams`). Explicit expansion is remembered in `sessions/expandedTeams`, including on retained ancestors of favorites. Each list keeps at most 2048 parents, the oldest forgotten first, so a rename, resume or restart keeps the choice; a parent without those IDs keeps it for this window only. A child row's compact or full form is remembered like any row's. Nesting stops after eight levels; a deeper child starts at top level again. A child whose parent is not shown above it stays at top level with **from PARENT**, which opens the parent when it is listed. A parent is matched by its computer's machine UUID and session ID, or by conversation for a parent an older `hgs` listed without one; names never match. A loop never hides a card. An ended parent with live child sessions stays in the live list as their container (zerus-sa9qn.17): a dimmed compact row with the parent's tile, title, **Ended** or **Archived** state and its children's line, the children nested under it. A stopped or paused parent that the filters hide is shown this way from its own row; a terminated or archived parent, or one no longer listed on the child's own computer, from its children's recorded link. The container is presentational: it counts as no session, takes no keyboard step, drag target, selection range or attention, and its menu offers only **Open**, **Resume** or **Restore** and **Move to archive** of its own listed row, or **Open in Archive** for a parent known only from the link. It leaves the list by itself once no live (non-archived) child remains, and it is shown only for children the filters show. A parent that still runs, is listed in another project, or is missing on another computer keeps its children at top level with **from PARENT**, as before. The containers come from the same one-pass resolution and hash maps as the nesting; there is no extra read per row. Cards show a large agent tile at the left: the agent's mark from the owner's design prototype (Claude, Codex, DeepSeek, Kimi and the shell; OpenCode keeps its glyph) on a bordered tile, 34 px on cards and 22 px on compact rows. The tile uses the skin tokens `list.agent-tile` and `list.agent-tile-border`: the prototype's near-black tile with a thin outline in the dark skin, and a white tile with a firmer outline in the light skin, where it gives the colored marks their best contrast. The artwork loads lazily, outside the entry bundle; until it arrives the tile shows the provider glyph. A compact parent row takes a second line that sums up its child sessions: working of all, **Needs you**, **Asking** and **Errors** counts, with the same collapse toggle; childless compact rows stay one line. On rows narrower than about 340 px the counters show their numbers only and the toggle keeps its place; the toggle's label and the row's accessible description keep every count in words. Rows stay transparent and paint a surface only on hover and selection. A selected card uses the skin's green-tinted card surface and an accent border, as in the owner's prototype, with attention, unread, draft and error edges drawn on top; while the list has keyboard focus the selected card also gets an accent ring. Supervised children draw no attention for requests their parent can handle. A child is supervised when its own computer lists its parent as `live`; rows with a parent then also carry `human_request`, true while the child holds a request only the person can answer: a tool or permission approval, its own or a native subagent's, a folder or Codex hooks trust prompt, or signing in (an authentication failure or **Sign in required**). DeepSeek and OpenCode rows carry it as well; their tool and permission approvals, listed as pending questions, count as approvals. A supervised child is quiet only when its host reports `human_request: false` and the row itself shows no such approval or sign-in; a host that does not report it keeps every request visible. A quiet child behaves like a muted session: no system notification or attention contribution to the rail, tray, menu bar or project header counts, and gray badges and edge, while its status, Activity, unread reply, questions and approvals stay as they are. Nothing is marked read. Unlike a muted session, it leaves the **Needs attention** filter, and **Active** unless it is working, in Background, Scheduled or has a draft: its unread reply, retry or provider limit waits for the parent (zerus-sa9qn.18), on desktop, Android and iOS alike (zerus-sa9qn.19). Review later, the person's own mark, still counts and lists it. A person-only request notifies as for any session. When the parent is paused, stopped, exited, archived, not listed on the child's computer (including a parent on another computer) or gone, the child is ordinary again: a pending request that waited quietly is announced once, while replies seen meanwhile are not replayed. A supervised child shows a dim arrow turning down and right before its title, meaning its parent above handles it (its tooltip and accessible name say which session supervises it; owner, 2026-11-07, zerus-sa9qn.16, replacing the crossed bell); the parent's **Team** toggle adds **Asking** (quiet requests waiting for it) and **Needs you** (person-only requests), which never raise the parent's own attention. `client/core/tests/fixtures/supervised-attention.json` lists the cases the desktop projects and Android and iOS check. A supervised child's blocking question also goes to its parent session, once (zerus-sa9qn.8, owner approval of 2026-11-12). This is an owner-approved, service-originated route, not the person's consent: the durable desktop service on the child's own computer originates one guarded `hgs send` to the live parent with no per-message confirmation, and nothing else. It never answers, selects or approves anything, never builds a UI permit and never changes who is alerted: the child stays quiet exactly as above, and every person-only request still notifies. The service watches its own computer's rows on every catalog event, whatever the notification settings. A row is an edge when it is a running Claude, Kimi or DeepSeek child waiting for input (`phase: input`) whose parent is `live`, not forwarded, and whose host reports `human_request: false`; a new `attention_signature` is a new edge, and a question already pending at startup counts once. After about 3 seconds the service reads the child with one bounded `hgs inspect NAME --after 9223372036854775807 --skip-processes` and its `hgs reference`, at most one read per child and two in all, each with a 5-second timeout, from a deduplicated queue of at most 64 edges; it reads again immediately before sending. Qualified ordinary AskUserQuestion cards route: Claude's `hook`, Kimi's `kimi_wire`, DeepSeek's `dsh_native` ordinary requests, and OpenCode's `opencode_native` API-verified question tools, paired with that child's provider. They must name the main agent, be blocking and unanswered, carry `can_answer: true` and a full identity; Kimi also requires its qualified `kimi_tui` answer transport and positive `blocking` evidence from the exact native tool call, turn and questions. A background call or missing/changed tool-call history never establishes that proof. Its single-choice, multiple-choice, multi-part and Other-text answers retain the existing native request, terminal identity and original answer receipt guards. Routing delivers the question; the parent explicitly calls `hgs answer` under its own permissions. OpenCode qualifies only an active exact native session's pending form whose referenced assistant message contains the same running `question` tool call and whose complete fields match that tool's question input. It uses at most eight native message point reads in one 250 ms budget, without scanning history. Missing, changed, completed, foreign or ambiguous tool/form evidence stays unqualified; public form metadata alone never establishes authority. Generic forms and all permissions remain manual. Exact duplicate OpenCode answers return the original durable answered receipt before reading live native state, including after the form disappears or the run changes. Changed content or target under the same UUID is refused; legacy unbound, pending, unknown or unavailable receipts never permit another delivery. Claude Code's own prompts (`claude_native_question`), every synthetic native card, approvals (including Kimi plan and goal approvals), cache choices, trust and sign-in never route, even if answerable. Codex async questions are optional, so a Codex child has nothing to route. DeepSeek additionally requires its `native_dsh` transport and positive `blocking` evidence from the exact owned root's ordinary forever-waiting request. Timed waits, typed approval or plan intents and older resident bridges without this proof remain unrouted. Its existing durable answer UUID journal, host generation and consume-once request checks still govern every answer (zerus-fb9ky). The parent's own current row on the same computer, matched by the link's session ID, must be running a terminal agent (Claude, Codex or Kimi); the send names its current run and conversation. The deferred-send actor runs the one fixed `hgs send PARENT --json` as its `route_question` kind, with the usual guarded checks (exact run and conversation, native input state; a draft or busy layout refuses). Its request ID is a name-based UUID of the question identity (RFC 9562 version 8 from SHA-256: machine, child session, run, conversation, question ID and hash), so it is idempotent across restarts. The route ledger reserves each identity in the same transaction as the actor's original and settles it from the actor's receipt only: `submitted` (the CLI's own receipt), `refused` (before any child ran, an invalid text, or more than 20 routed questions for that parent in the last hour) or `unknown` (everything else, including an `hgs send` refusal, which leaves no receipt). Nothing is retried; an unknown result is never replayed, and a routed or refused identity never routes again. The ledger keeps at most 65,536 rows with rolling retention (zerus-sa9qn.36): when it is full, one bounded pass reads at most 1,024 settled (`submitted` or `refused`) rows older than a day, oldest first from a rolling cursor, and deletes at most 256 whose question can never be read again, because this computer's complete catalog no longer lists the child at that row's run (a run ID is never reused, and a question routes only from its listed run). Reserved and unknown rows, a row of a run still listed, a row from an older ledger without a run while its session is listed, and every row while the catalog is incomplete are kept, so nothing is replayed or routed twice. A question that finds the ledger still full after that pass is not routed then; Activity shows retained routes only. The text is a fixed English template of at most 2 KiB: the header `[Zerus child question]`, the child's name and reference (the name single-quoted; a child whose name holds anything but ASCII letters, digits, `.`, `_` and `-` in three segments is never routed and is recorded `refused` as `question_route_invalid`, as is a question whose run, conversation, question ID or hash holds anything but ASCII letters, digits, `:`, `_`, `.` and `-`), the question kind and option count, at most 300 characters of the first question as one quoted line labelled as the child's data, `hgs inspect ''` for the full question, the exact `hgs answer CHILD --json` fields (run, conversation, question ID and hash) and "If only the person can decide, say so in your reply." It carries no ticket, wait or other authority. v1 routes on Linux only; macOS follows the deferred-send actor's macOS child seam and Windows keeps today's behaviour. The service advertises `Desktop question route: route-questions-v1` in `hgs --help`; an older service does not route. A submitted route shows one line in the child's and in the parent's desktop Activity (zerus-sa9qn.33): **Question sent to the parent session** with the parent's name, or **Question from a child session** with the child's name, then the route's own preview of at most 300 characters as plain text and the child's reference with Copy. The parent's own message of exactly the routed text folds into its line, behind **Show the received message**; any other line is placed by its time. A refused or unknown route shows a line only in the child's Activity on desktop, Android and iOS (zerus-sa9qn.52): **Question not sent to PARENT** or **Question delivery to PARENT uncertain**, with the parent's display name, the literal preview and the child's reference. Reserved routes stay pending until settled or recovered. A settled refusal (including invalid text, the per-parent bound and not started) or unknown result immediately makes that exact still-pending question a human request: **Needs you**, with the existing question notification. The person can still answer it. There is no F3 retry and an unknown result is never replayed. Turning either switch off or changing the person-only latch does not retry, cancel or erase an outcome. The shared fixture is `question-route-outcome-contract.json` beside the Android test resources; every client tests the same outcomes and wording. The local listing and inspection read the service ledger without creating or migrating it, using the exact machine/session/run/conversation/question/hash ledger key, independently of the Activity window. A later question never inherits escalation. A constant-size failure revision makes watch refresh the listing, without reacting to unrelated service writes. Store schema 41 retains immutable metadata even for a refusal before send admission; upgrades recover existing originals' metadata. A historical refusal with no saved original has no recoverable Activity metadata; its exact still-pending question can nevertheless escalate by the ledger key. Inspection carries at most 20 lines in `question_route_activity` for the phones and remote desktop views; local desktop polling and inspection lines deduplicate by the immutable route request ID. The desktop lines come from the background service's read-only `question_route_activity` request (`request_id` and the session's durable `session_id`, exactly): at most the 20 newest outcomes for the child or submitted routes for the parent, read by partial indexes of the route ledger. Submitted routes still require their exact saved send original; failed routes never claim that the parent received their text. The read sends, settles and grants nothing. The desktop reads it for a local session in background service mode: once when the session is shown, then at most every 3 s while its Activity changes, and a shown child every 15 s. The person has two switches, both on by default (zerus-sa9qn.32): - **Settings > Sessions > Send child questions to the parent session** is kept by the background service (Store schema 37) and changed only through the person's native frontend request (`question_routes`), never by a command an agent can run. It is shown only where the service routes (Linux). - **Send questions to PARENT** in a qualified child's Session actions is kept on the child's computer beside its notification preference (`question-routing.json`, keyed by the child's durable session ID, so a rename or a new conversation keeps it) and shared with every desktop and phone. `hgs [@host] question-routing --json` changes it by compare-and-swap (stdin `expected_run_id`, `expected_conversation_id`, `expected_revision`, `send_to_parent`; marker `session-question-routing-v1`) and refuses a change from an agent's own process tree (`agent_refused`), on the switch's own computer and, for `hgs @host question-routing`, in the local CLI before forwarding (also in the guarded `--expect-machine ID [--client C] [__state]` forms and `__state question-routing`, zerus-sa9qn.51). That refusal stops accidental agent use only; it is not a security boundary, because a same-user agent can clear its session variables, leave its process tree or write `question-routing.json` directly. The person-only control is the global switch above (zerus-sa9qn.49). Listing rows and `hgs inspect` carry `question_routing` (`send_to_parent`, `revision`), null when the setting is unreadable or the session has no durable ID. Android and iOS show the same entry in a live Claude child's Session actions and change it through the mobile relay's Rust-only `session_question_routing` operation and the Rust connector (zerus-sa9qn.33); the legacy Python connector refuses it. Phones see the switch only once both the relay and the computer advertise it: the relay lists the operation, and the connector offers it only when the computer's `hgs --help` shows the `session-question-routing-v1` marker. `mobile/android/app/src/test/resources/question-routing-contract.json` is the shared contract of the desktop, the connector, the relay, Android and iOS. - **The person's latch** (zerus-sa9qn.50): the background service on the child's computer keeps a latch per durable session ID (Store schema 39). While it is set, the child's questions never route, whatever its host file says. The latch is the authority. After each change the service writes the child's host file to follow it (`send_to_parent` the latch's opposite), with a display-only mirror `person_off`. Listing rows, `hgs inspect` and switch replies then carry `question_routing` {`send_to_parent`, `revision`, `person_off`} (help marker `session-question-routing-v2`). Older clients that know only the two-key shape show the switch as unknown and fail closed. `hgs question-routing` changes only `send_to_parent` and keeps the mirror. On a child of this computer the desktop's **Send questions to PARENT** goes through the latch: the person's native frontend request (`question_route_child`, compare-and-swap at the child's exact run, conversation and latch revision; closed refusals `conflict`, `stale_identity`, `not_found`, `capacity`). The entry shows "You turned this child's questions off" while latched. A remote child keeps its host switch; while its mirror says a person latched it, the desktop shows it off and offers no "on", which only its own computer or a phone can give. The request lane an agent can reach only reads the latch (`question_route_child_status`, `question_route_child_result`). Boundary: the latch is person-only against an agent using commands (the CLI, `hgs desktop request`, the connector), not against the same user editing the service Store or the connector's files directly, the same as the global switch. A phone on an encrypted workspace sets the latch too, where its relay and the computer both offer `session_question_route_person` (help marker `question-route-person-v1`). The phone signs a statement with its workspace Ed25519 key: domain `zerus-question-route-person-v1`, with the workspace, phone, gateway, child session, run, conversation, value and request ID, valid at most 5 minutes. The connector forwards it as one `hgs desktop request` (`question_route_person`). The service runs this computer's connector itself, pinned: the desktop's absolute selection or the installed sibling of `hgs` (never a PATH lookup). Its directory must be owned by this user or root and not writable by group or others. The binary, opened relative to that directory without following a final symlink, must be a regular file under the same rule: a packaged one, such as the AUR's root-owned `/usr/bin/zerus-mobile-connector`, qualifies (zerus-sa9qn.56). It must answer `--version` as `zerus-mobile-connector X.Y.Z`, and the path must still name it after the run. On Linux the service executes the descriptor it checked (`execveat` with `AT_EMPTY_PATH`), so a file put at the path after the check never runs (zerus-sa9qn.54). macOS has no descriptor exec and runs the path. There, only this same user or root could swap the file between the check and the run and back before the recheck; that is outside this threat model. The run is bounded to 0.4 s and 1.2 s and 64 KiB of output, with a cleared environment: `zerus-mobile-connector --workspace verify-question-route-person`. The verifier checks that a current phone of this workspace signed exactly that statement for this gateway, and must reply exactly `{ok, verifier: "question-route-person-v1", verified}`. Any failure, timeout or other output is the closed refusal `not_verified`. The service then sets the latch once per request ID, and the host file follows. With `question-route-person-v2`, the Rust connector additionally offers the read-only `session_question_route_person_status` operation. Its exact payload is `{session_id, expected_run_id, expected_conversation_id}`; it reads the service's latch at that visible local child's identity, returning the request ID, session/run/conversation, `person_off` and `revision`. It grants no write authority. It is an additive API v1 operation, counted and retained as a bounded read without changing the connector journal's existing schema or frozen predicates. A phone uses it only when both relay and computer advertise it, then signs `expected_revision` in domain `zerus-question-route-person-v2`. There is no fallback to v1 if that read or the v2 request fails or is uncertain. Desktop and v2 phone decisions compare-and-swap the computer-issued, durable per-latch revision (zerus-sa9qn.55). Every accepted new decision advances it, including a decision that keeps the same value. A replay returns its original receipt. A stale phone revision is the closed `stale_decision` refusal; cross-device wall clocks never order v2 decisions. Signed issue/expiry timestamps still limit signature lifetime. The first verified v2 statement for a child durably fences that entire latch against v1, even when its compare-and-swap conflicts or its child is temporarily absent or on another run. Refusals keep the latch value and revision; a new fence keeps their defaults and shares the latch cap. This fence survives restart, is never removed and applies to every phone. A new v1 request on a fenced latch is `upgrade_required`; the updated connector returns an ordinary failed receipt telling even an old app to update before changing this switch. Looking up an already accepted request remains read-only and returns its original receipt. Compatibility: never-upgraded latches and computers/connectors without the v2 capability retain the legacy v1 statement shape and time ordering (zerus-sa9qn.53). The latch keeps `decided_at`; a phone statement's signed `issued_at` must be later, and desktop decisions retain the maximum of their local time and the stored time. This legacy path trusts device clocks: a fast phone's delayed statement can override a newer choice, and a computer clock corrected after running ahead can block legacy phone decisions until time catches up. Those clock risks remain only on latches that have not been fenced by v2. Peers and Windows gateways do not offer the signed latch operations; a legacy connection keeps the host switch. Shared vectors cover both domains in `services/mobile/crypto/tests/vectors/question-route-person-v1.json` and `question-route-person-v2.json`. The router reads nothing while the global switch is off. Every reservation reads both switches and the latch again in its own transaction, so a switch turned off before it stops the send and writes nothing; off never cancels or replays a question already reserved, sent or unknown. Turning routing on again reads the catalog from a new baseline: a question still pending and supervised then is routed once, also when it was first read, or its reservation found a switch or the latch off, while routing was off (zerus-sa9qn.45). One asked and answered while routing was off is never sent, and a question already in the route ledger never routes again. Android (zerus-sa9qn.4) and iOS (zerus-sa9qn.5) apply the same contract, iOS in ZerusKit `ChildSessions` and the session card: child cards nest under a parent shown in the same project group, 16 dp per level up to three levels with a connector, and a child without a shown parent stays at top level with **from PARENT**. A parent's counter is the same single toggle for its shown subagents and child sessions (`2 of 5`, gray **Asking**, amber **Needs you**), expanded by default; the phone remembers a collapsed parent across relaunches by machine UUID and session ID, at most 2048 (iOS keeps them in its sealed `collapsed_teams` store). A quiet child gets the mute treatment on the phone: no system notification, gray badges and reply count, and the same arrow before its title; a request that waited quietly notifies once when the parent is gone, and a completion seen meanwhile is not replayed. Cards show the account mark (circle, letter and label) resolved by the row's computer and recorded `account_id` against that computer's account catalog, in the color that computer keeps for the account (the row's `account_mark`), else the label's default palette color. See `docs/superpowers/specs/2026-11-07-account-labels-child-sessions-design.md`. ### Rename, Saved and Archive **Rename…** changes the label after the project name without replacing the process or working folder. Tracking and journal history follow the new name; attached terminals receive updated titles. Archive renaming targets only the selected ID. ```sh hgs rename codex/project-docs/review codex/project-docs/database-review hgs @mac rename claude/sample-project/review claude/sample-project/deploy hgs rename codex/project-docs/review codex/project-docs/database-review --archive ID ``` Live and Saved names must be free. Archive names may repeat. Labels accept Unicode and internal spaces, but reject `/`, `:`, `.`, control characters and surrounding whitespace. `--dry-run` validates without mutation; `HGS_TAB=0` disables title updates. **Saved sessions** are unfinished conversations paused explicitly or left after process interruption, tmux loss or reboot. **Archive** contains completed conversations. For automatic archiving, a tracked run needs both native main conversation completion and a successful process exit without evidence of pause or an external signal. `SessionEnd`, an SSH disconnect or a completed reply alone is insufficient. Older ambiguous records are not reclassified automatically. ```sh hgs archive codex/my-project/review # stopped sessions only hgs terminate codex/my-project/lead --with-children # then its live child sessions hgs ls --local --json hgs inspect codex/my-project/review --archive ID hgs resume codex/my-project/review --archive ID -d hgs kill codex/my-project/review --archive ID # forget only this binding ``` Terminal archives live in `archives/`, each with an independent ID. A new launch with the same name preserves the archive. Restore refuses an occupied live or Saved name and removes an archive binding only after the native agent confirms the expected conversation. Failed restore keeps it. **Forget archive** preserves native history; `resume --all` excludes archives. For native DeepSeek sessions, `terminate` stops the selected session on its resident host and archives it. `archive` requires a stopped or paused session. DeepSeek archives use a separate local store so earlier CLIs can still use terminal archives after a rollback. Retirement requires the resident host to confirm the session is stopped. Restore resumes the archived conversation on that host. When the first restore result is unclear, Restore checks the original outcome without sending a second resume. Other sessions on the host stay available throughout. Desktop Restore keeps the opened conversation and its message draft when the resumed row confirms the archived conversation ID. Text, attachments and editor selection move to the live draft key; machine/project/search scopes stay in place. An existing live draft is never overwritten: the archive draft remains in Saved drafts. A later user selection is not replaced when Restore completes. ### Browse Archive by date Desktop and Android filter **Archived date**, the time a conversation moved into Archive, independently of its creation or last message. Choose All dates, Today, 7/30 calendar days, or an inclusive From/Through range. Days use the viewing device's local time zone, including daylight-saving changes. Pages request the most recently archived instances first; the desktop retains saved row order within each project. **Refresh** starts a fresh view. **Older sessions** and **Newer sessions** replace the current page, retaining at most 50 rows per selected online computer. Only two cursor anchors per computer are kept, without a growing page or cursor history; every matching record remains reachable in either direction. The compact period button opens quick ranges and a custom From/Through picker. Quick ranges fill the From/Through draft and keep the picker open, so either date can be adjusted before **Apply range**. Only Apply changes the active date filter; opening a picker, choosing a preset, Cancel, Escape or dismissing the panel never fetches a page. **All dates** shows **Any date** for both bounds and applies no date limits. Calendar inputs follow the app's desktop theme. The navigation row shows the current range for one computer or the loaded/matching count across computers. Hover the desktop count or expand the mobile count for each computer's exact page range. Older/Newer arrows sit beside this summary; their accessible labels describe the direction. Refresh uses the adjacent icon. The Archive badge counts rows in the current project/machine scope, with `+` when the current window does not contain the whole archive. An unavailable computer keeps its own error and retry state; changing dates, search or machines discards responses belonging to the previous view. Upgraded desktop and connector polls use `hgs ls --json --local --no-archives`. For older Android clients, the connector attaches a cached recent window of at most 50 archived rows/128 KiB and explicit `mobile_archive` loaded/total/partial metadata. It refreshes that window only when the native directory revision changes or five minutes expire. Native identity checks and the existing fresh snapshot gate remain in force for that window. Updated Android ignores this compatibility window when page operations are supported; an old relay can still show it while the system updates. Full Archive browsing needs the updated client. Archive rows carry the current host-owned `notification_preferences`, using the original journal and native conversation identity. Both connectors retain the complete preference or explicit unknown value in their bounded previews; a known relay conversation never silently loses its preference revision when it is archived. Corrupt host preferences remain unknown. Native pages keep their 250,000-byte summary budget; one larger row is returned alone if it fits 768 KiB, within the 1 MiB response bound, so a valid 384 KiB preference can still be read. The compatibility preview remains capped at 128 KiB and omits an oversized row. Plain `ls --json` retains archived rows with the same session fields, including `archive_id`, `archived_at` and native action availability, but includes only a recent preview: at most 50 archives in `(archived_at, archive_id)` descending order, subject to the archive page's byte budget. Live and Saved rows remain complete. The additive host-level `archive_page` describes this preview without duplicating its rows: `total`, `total_capped`, `next_cursor`, `previous_cursor`, `position`, `from`, `until`, `query`, and `command: ["archives","--json","--bounded"]`. Its total counts at most 50 archives; `total_capped: true` means a lower bound. For a ready catalog an empty `next_cursor` means there are no older rows. While catalog coverage is unavailable, the preview has `partial: true`, `total_capped: true`, `catalog_complete: false` and an `error`; its empty window and cursor do not prove there are no archives. To continue, pass `next_cursor` as `cursor` with the same range/query to the command in the descriptor. New completions appear on Refresh; additions do not shift a continuation's date/ID keyset. Agents must follow this cursor to enumerate the whole archive. `--no-archives` continues to omit archives and the preview descriptor, retaining `archive_paging` and `archive_revision` for client discovery. Only the preview's rows open summaries or check transcript metadata for actions; ordinary indexed polls do the same bounded work with 50 or 20,000 archives. Initial index creation and refresh run in the bounded background worker described below; a poll never rebuilds the archive catalog inline. `hgs status` forwards the preview's count as `sessions.archived`, with additive `archived_total_capped` when a preview is present; its text shows `50+ archived` for a capped count. The native, read-only archive ABI is: ```sh printf '%s' '{"from":0,"until":253402300800,"limit":50,"cursor":"","query":""}' | hgs archives --json ``` `from` is inclusive and `until` exclusive Unix seconds (integers, nonnegative); `limit` is 1–50. All fields are optional. `query` is literal case-insensitive archive metadata search (names, IDs, provider, folder and title), at most 256 characters; this is distinct from the desktop's global public-message search. The result contains `version:1`, `sessions`, `total`, `next_cursor`, the additive `previous_cursor` and zero-based `position`, and the echoed range/query. A host that counts only up to a cap may add `total_capped: true`; the desktop then shows the total as "N+" and accepts a window that starts past it. `hgs archives --json --bounded` (help marker `archive-bounded-pages-v1`) asks for such bounded pages: the total and the position count at most 10,000 matches (`total_capped`, `position_capped`), the empty query included, and each scan looks at most at 25,000 catalog rows in date order. A page whose scan reaches that budget before its limit of matches is `partial`: it may be short or empty, `searched` gives the rows it looked at, and its cursor continues from the last row it looked at, in either direction. Without `--bounded` a page is exactly as before; the desktop sends the flag only when its CLI lists the marker, and a peer whose CLI does not list it answers the exact page. Pass either opaque cursor with the same range/query to move older or newer. Both directions use date/ID keysets; no offset scan or retained client cursor stack is required. Ordering uses `(archived_at, archive_id)` descending, avoiding offset duplicates when an earlier page changes. Newer completions appear after Refresh. Deleted or restored instances disappear; all actions still recheck exact native identity. Cursors belong to one computer/catalog and cannot be reused after rebuilding it. A rebuildable `archive-catalog-v1.sqlite3` indexes metadata beside the durable state. Archive JSON files remain authoritative. A cold or stale page reports incomplete coverage and requests one coalesced detached metadata worker; retry the read after that worker publishes complete coverage. The worker keeps its directory iterator between slices of at most 64 entries, 32 MiB of bounded native input and a cooperative 25 ms budget. It reads each new, changed or damaged entry once for the search, identity and folder-reference projections. Unchanged entries use device/inode/size/mtime/ctime versions and validated compact rows without rereading archive bodies; removed files retire only derived rows. Each helper is bounded to 60 seconds, 16 GiB of charged native input and 8192 steps. A later request resumes from committed per-file progress; an interrupted walk never publishes a complete roster. The worker also bounds its inventory to 100,000 directory entries and compact bookkeeping to 32 MiB. An over-limit or unreadable inventory remains explicitly unavailable. Unchanged polls/pages reuse the catalog; atomic archive writes, rename, restore or forget invalidate its directory generation. In-place changes are discovered by the next background version walk. Selected positives still read and verify the exact native archive. A negative identity lookup needs a fresh complete native filename/version census and a validated identity manifest independent of search omissions. Partial or stale coverage is never absence, and current bindings are retained while coverage is unavailable. Cleanup keeps its separate fresh canonical reference proof and its existing smaller budgets. Only requested rows open conversation summaries, outside the state writer lock. Browsing never starts an agent or changes read marks. New archive pages use the additive mobile `archive_list` capability; older computers retain their previously loaded archive view and need an updated CLI/connector/relay for paging. Archive IDs are admitted from validated pages for one hour (bounded to 2,000 recently paged instances), while native inspection and lifecycle actions still verify name/archive/run. Archive metadata decoding uses the same 16 MiB byte bound as live session records. Inputs must be regular files, opened without following a final symbolic link or waiting on a FIFO. The opened file's native version and the object still named by its path must agree after the bounded read. Selected reads, legacy enumeration and preliminary catalog decoding share these checks without changing normalized archive identities or label selection. Ordinary legacy enumeration warns and skips unreadable unrelated archives, so resume, search and reference lookup can still use other exact names. A partial list never authorizes removal or replacement. Termination checks require a complete inventory. Global reconciliation retains every binding if the inventory is incomplete. An indexed archive match must also pass a fresh body/identity check before it can replace the current binding; a failed read keeps that binding available for review. Catalog search omission never makes missing or stale cleanup-reference coverage empty. Warm catalog pages retain their indexed path without new full scans; reference count, aggregate byte and deadline bounds remain unchanged. An already-open older archive also survives a connector restart or cache expiry: `hgs archives lookup --json` accepts only `name` and `archive_id`, reads that one authoritative record without scanning the catalog or transcript, and returns its name/archive/run/conversation identity. The connector verifies this response and any requested run/conversation before admitting an uncached target. Failed or mismatched lookups grant no admission; lifecycle operations keep their native fresh checks. This internal read ABI adds no relay mutation or phone operation. Desktop bulk removal is explicitly **Remove loaded archived sessions** when paging is enabled. Its confirmation names/counts those loaded instances in the current date/machine scope; unloaded entries are kept. Local user grouping follows the exact observed run even when its reusable session label later changes owner. ## Project wrappers On Linux and macOS an executable `run_COMMAND.sh` in the project folder runs inside the tmux session. On Windows `run_COMMAND.ps1` runs through the Windows session host, with the existing PowerShell selection: a canonical native `pwsh.exe`, then Windows PowerShell. A Store alias that cannot be resolved to a native executable is not selected. `--bare` bypasses the wrapper. Use the script to prepare the environment and launch the native agent. Unix keeps its existing `.sh` behavior and does not automatically select `.ps1`. A project can provide both platform-specific wrappers. No PowerShell dependency is introduced on Linux or macOS. The Windows wrapper runs with `-NoLogo`, `-NoProfile` and process-scoped `-ExecutionPolicy Bypass`. Zerus does not change machine policy or load a user profile. Saved recipes retain the wrapper and its arguments across resume, fork, recovery and Start fresh. At spawn, a fixed encoded bootstrap transfers the script path and argument array as data, then clears that private data before invoking the script. This avoids PowerShell `-File` splitting a literal argument such as `-name:value`; empty, quoted and Unicode strings reach `$args` intact. The wrapper remains responsible for forwarding those arguments to its agent and returning its exit code. A new Claude profile whose tracking-hook form is not known must first initialize native tracking with `--bare`, or explicitly run untracked with `HGS_TRACKING=0`. Zerus does not probe the PowerShell interpreter as Claude or invoke a project script a second time for its version. Windows PowerShell 5.1 has [native argument forwarding limitations](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-5.1) for empty strings and embedded quotes. [PowerShell 7.3+ improves native argument passing](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.6); its Windows mode still uses legacy rules for batch/npm shims. Prefer a native agent executable when forwarding complex arguments. PowerShell stays the supervised process while its native agent is a child. Existing native process/confirmation guards still apply. In particular, a Codex resume/fork may need its first message in Terminal until native startup confirms the conversation; a wrapper is not evidence of that confirmation. For a plain PowerShell shell on Windows use `hgs sh PROJECT --new -d`; this is already supported and is untracked, like an ordinary Unix shell session. ```sh hgs codex sample-project # run_codex.sh starts a new conversation hgs codex sample-project -c # run_codex.sh resume --last hgs codex sample-project -- resume ID # continue this exact conversation hgs codex sample-project --bare # bypass the wrapper ``` Explicit arguments after `--` suppress automatic Codex `resume --last` insertion, even with `-c`. Use `-- resume --last --model MODEL` when needed. Claude and Kimi forward `-c` to their wrapper. Existing sessions attach without rerunning the wrapper. Interactive setup needs an attached launch; detached mode assumes the required environment is already available. Never put private keys in wrappers. Tracking never runs `run_codex.sh` to detect Codex capabilities; it runs only as the launch and always receives `--no-daemon`, so it must start a Codex release with that flag. `--bare` checks the native Codex and omits the flag for an older release. ## Desktop workspace The tray's **Open Zerus**, a left click or `hgs-tray --sessions` opens the workspace. On macOS, use `~/Applications/hgs-tray.app/Contents/MacOS/hgs-tray --sessions`. On Windows, starting `hgs-tray.exe` without options opens it too; `--background` starts in the tray only ([Windows](#windows)). Repeated launch raises the existing window. Closing it leaves the tray and agents running. The executable, bundle path, bundle ID and service names remain `hgs-tray` for compatibility. Windows, notifications, the tray, `--version` and the Linux launcher show Zerus. On macOS, a localized display name shows Zerus in the Dock, Finder, Spotlight and System Settings for the unchanged `hgs-tray.app` bundle. Settings → Mobile connection also lists and pairs [phones](#machines-and-accounts). Settings → Mobile connection → Phone notifications sets when the phone notifies: immediately, as soon as you are away from every Zerus computer, or after 5, 10, 15 or 30 minutes away. The choice is shared through the swarm catalog; computers this one synchronizes with directly whose hgs is too old to receive it are named there. The tray has two counters: **active** sessions (the session list's Active filter: working or Background, Scheduled or Waiting, needing attention, or a local draft) and **Needs attention**. A quiet supervised child's attention waits for its parent; its work, schedules, waits, drafts and the person's Review later mark still count as Active. Attention includes input, approvals, errors and unread main-agent replies. An offline host adds its Review later sessions to either counter and its local drafts to Active; a dot marks incomplete data. The tooltip keeps the total number of sessions. Linux application badges and the macOS Dock show the attention count, hiding zero. Zerus Next's tray menu (on Linux, macOS and Windows) has: - **Open Zerus**, and an update's entries when there is one; - one line per computer: how many sessions it has (`12 here`, `5 on mac`), or that it is unreachable or still polling; - **Quit**. It lists no sessions: open them from the workspace. It has no **Open in** either. New sessions and folder shells still open the way `open-mode=` in `tray.conf`, or a mode chosen earlier, says ([external terminal modes](#external-terminal-modes)). The session menu's **Mute** disables notifications for that conversation on all devices and removes it from their notification counters and bells. The session's host stores the preference; other desktops and phones receive it in their next host snapshot. A crossed-out bell and neutral gray or white attention and unread badges identify a muted session. The preference survives restart, rename and resume of the same conversation. Muting preserves the agent's actual state, unread replies, questions, approvals and review reminders. The menu requires an online host with shared notification preferences and a configured local `hgs` that advertises `session-notifications-v1`; older hosts show an explanation instead of a separate local-only preference. A pending or failed change never replaces the last confirmed host value. If a host later becomes unavailable or stops reporting this feature, its last confirmed muted display is retained and labelled as such; it does not enable a new change. Concurrent changes use the host's revision and require a fresh snapshot after a conflict. Unmute records the host's current notification identities, so a device that missed the muted interval does not announce those old events when it reconnects. This does not mark the underlying work as read. **Unmute** restores future notifications without replaying events seen while muted or acknowledging pending work. Muted sessions remain available in the Needs attention filter, and its tab count includes them. The desktop service accepts notification clicks only for a live, unblocked attention request on Linux, macOS and Windows. After a read, mute or resolution retires that request, a later click is ignored even if the operating system has not yet removed the banner. Notifications open Activity for the exact requesting run and conversation, including remote or renamed sessions. Polling and restarts do not repeat the same request; resolved notifications are removed. Main-agent reply banners wait until the session is idle and has no reported active children. While native agent work, live background commands or active subagents continue, intermediate replies remain unread in Activity but show no new-reply badge or reply-only attention count on desktop or Android. The pending reply becomes visible when work finishes; this never marks it as read. Explicit questions, approvals, errors and review reminders remain actionable. Optional Codex questions, which the agent continues without, are not attention: on the desktop, Android and iOS they change neither the session's status nor the Needs attention filter, counters or badges. Listings report them separately as [`optional_questions`](#optional-questions-in-listings). Settings → Sessions → **Notify about optional questions**, off by default, adds an *Optional question* banner once for each new question. Questions already pending when it is turned on, or first seen while Zerus is focused or the session needs action, are only recorded; a stop, resume or temporarily unknown count announces nothing again. The banner opens the conversation's Activity. It is withdrawn when its questions are answered or skipped, the session is marked as read here or on another device, or the setting is turned off; delivered Windows messages remain but no longer open a session. Routine replies from a turn the agent scheduled itself (Kimi `CronCreate`) are not new replies while a recurring job remains: they appear in Activity without an unread mark, badge or banner. The reply after the last job ends, a one-shot reminder and any reply to the person's prompt notify as usual. Explicit input and approval requests still notify immediately. Ordinary child results and errors stay with the parent. While Zerus has application focus, session banners are suppressed and are not replayed when focus leaves. Unread replies and attention requests remain visible in the interface, including requests from other sessions and machines. Delivery failures show a reason and retry after a minute while still relevant. macOS uses Notification Center and needs its system permission; Focus and OS notification settings still apply. Notification Center looks up the icon by bundle ID, so a stale per-user IconServices entry can keep an earlier icon after updates while Finder and the Dock show the current one. Remove `$(getconf DARWIN_USER_CACHE_DIR)com.apple.iconservices/store.index`, then run `killall iconservicesagent NotificationCenter`; both restart on demand. While Zerus runs, even with its window closed, it records keyboard/mouse idle time and screen lock for phone notifications. macOS uses CoreGraphics without a permission prompt. Linux uses the desktop's screen-saver and idle interfaces (KDE Plasma, GNOME and other compositors with Wayland idle notifications). When none is available only input in Zerus windows counts, which can only cause extra phone notifications. **Sessions**, **Projects**, **Machines** and **Accounts** share the navigation rail; click the logo for **Overview**. Overview shows attention, work in progress, online machines, CPU, memory and load, plus account limits. Counts open the matching filter, sessions open Activity, and machine settings lead to Machines. Native account quotas are grouped by verified identity instead of adding machine usage. **About** is the final Settings section, after **Voice input**. **Settings → Voice input** selects the speech computer, its recognition profile and the local microphone. The speech computer is independent of the agent's computer: a laptop can record locally and use a configured GPU peer over SSH. The provider manager creates, edits, tests and removes profiles on the selected processing computer. Choose **Local GigaAM** (model and CPU/GPU) or an **OpenAI-compatible server** (API base URL, model, language and optional API key). An empty language lets the server detect it; an explicit language uses a two-letter code such as `ru`. Keys remain on the processing computer and are never shown again; Keep, Replace and Remove are explicit choices. Test checks the saved profile with synthetic audio and cannot send input to an agent. Removing a profile requires confirmation. Choosing a default is separate from browsing or editing profiles. Configuration is available even when inference is not running. See [provider management](speech-providers.md) and [host installation](../services/speech/README.md). Local GigaAM starts with the Russian `v3_e2e_rnnt` profile. Saving or selecting a profile does not install or download a model and never falls back to another provider. On desktop, click **Voice** in the message toolbar to start recording. The icon immediately to its right switches voice/video mode without starting capture; it stays disabled while opening, recording or retaining a preview. Recording continues after the click. Click **Send** to send, or **Stop and preview** to review it with **Play**, **Discard** or **Send**. Enable **Preview before sending** in Voice input settings to show **Stop** instead of **Send** while recording audio or video. The setting is local to this device and applies to the next recording; existing drafts and deliveries are unchanged. Audio recordings are limited to two minutes and remain separate from the typed draft. Capture opens the local microphone without waiting for speech computers or providers. Provider discovery runs in the background. If it fails, the recording remains available for playback; refresh providers in the preview before sending. An unavailable selected provider stays selected until you explicitly change it. A retained recording also pins a versioned provider's configuration revision; editing that profile requires explicit reselection before sending the recording. During capture, the typed draft is preserved and read-only, and ordinary message submission and attachment changes are blocked. History remains readable. **Space** or **Escape** stops recording into the retained preview; neither sends nor discards it. Recording takes priority over Escape's agent-interruption action. Holding either key stops capture only once, and editing resumes after capture ends unless another delivery lock applies. Android supports the same controls with a hardware keyboard; its touch Stop control remains available. On Android, an empty editor with no attachments shows a microphone in the Send position. Tap to switch voice/video, hold to record, release to send, slide left to cancel or up to lock. Stop a locked recording to keep a preview. The recording row overlays the retained editor and shows a red indicator, elapsed time and **Slide to cancel**; the hint moves and fades as you slide left. Short haptic feedback accompanies confirmed capture start and explicit stop/cancel, respecting Android settings. Text or attachments restore the ordinary Send button. Sending requires a confirmed provider for the exact conversation; delayed discovery keeps a preview until an explicit Send. After granting microphone permission, press again to start recording. The preview lists speech profiles reachable from the conversation computer. Explicit Send stores the original there, starts recognition and delivers recognized text to the pinned agent conversation. Video is limited to 60 seconds and 10 MiB. Its MP4 and extracted WAV share one message identity; the agent receives recognized speech. A tap starts circular video playback. One history card retains the playable original, expandable transcript and processing or delivery errors across devices. Its circular play/pause control sits beside the recording's amplitude waveform; the played portion is highlighted, and selecting a point on the waveform seeks within the recording and keeps paused audio paused. The time display follows playback. Older recordings gain their waveform in the background without recognition or delivery being repeated. Clients recover interrupted requests by the original message UUID without blindly uploading or sending again. Hiding the composer stops unsubmitted capture. See [persistent voice messages](voice-messages.md) for storage and delivery details. Voice settings also show the selected computer's 90-day counters. Desktop Settings > Private analytics and Android Settings > Computer analytics show bounded per-computer and fleet summaries with explicit coverage. Agent collection starts disabled; local desktop controls distinguish enablement, retention and purge. See [analytics](analytics.md) for the private storage and read contracts. If microphone access is denied, Voice shows a permission explanation with **Open microphone settings** on macOS and Windows. On macOS this opens **System Settings → Privacy & Security → Microphone**. Allow Zerus, return to the conversation and press **Voice** again; opening settings does not start a recording. If settings cannot open, the dialog keeps the manual navigation path. Session rows show provider, machine, current action, model, effort and Git context. Double-click a session row to toggle between the full card and a compact row showing only its name, status and agent type. Right-click **Compact session row** is also available. Compact rows keep their expand icon; it or the Right key restores the full row. The row remains selectable and keeps its normal context actions. This device remembers the preference for that conversation across restarts. **Expand all collapsed** in the Sessions menu restores every compact row, including sessions hidden by the current filters. Row density never compacts the agent's context or changes its runtime state. Settings > Sessions > **Start new child sessions as compact rows** (on by default) makes the row of a session that another session launches or adopts start compact. "New" means a parent link recorded after this desktop last looked: the device remembers, for each computer whose clock stamped the links, the latest link time it handled and the children handled in that second (`sessions/childRowsSeen`). A computer seen for the first time only records its current children, so existing rows never change, and a row the person expands afterwards stays expanded across restarts. Turned off, new child rows keep the full card. A muted session keeps its mute icon in either size, right after its name; a supervised child shows its arrow before the name whether muted or not (owner, 2026-11-08). The folder/branch line also shows native outline Git badges: a diff with the number of changed/new files, upload/download with outgoing/incoming commit counts, and a green cloud check for a clean checkout matching its verified upstream. Changes include staged, unstaged and untracked paths, counting each path once. Merge conflicts use a red diff badge. Local changes and outgoing commits can appear together; counts above 99 show `99+`, with exact values on hover. Hover over the badges for the checkout, branch, upstream, counts and remote check time. These describe the current checkout shared by sessions in the same folder, not ownership of an individual feature or an archived conversation. Git reads run separately from agent/fleet polling, with at most two concurrent requests. Local evidence refreshes about every 15 seconds and expires after 30; read-only remote verification is cached for at most 60 seconds. A changed tracking OID or remote endpoint invalidates that verification. Nothing fetches, commits or pushes automatically. A muted cloud question mark means verification is unavailable, expired, detached or lacks a remote upstream. Outgoing/incoming counts become muted when only the local tracking ref is known; a changed remote asks you to fetch. Ordinary non-Git folders show no badge. Offline and changed checkout evidence cannot show a green check. **Ready** means a reply ended, not that a long-running task is complete. An idle agent with confirmed live shell commands shows **Background** in muted blue, with the command preview and elapsed time. Open **Processes** to follow output or inspect the running commands. The session remains in **Active** and still accepts new messages. Green **Working** indicates native agent work. Input/approval requests take precedence; ordinary agent work takes precedence over background work, followed by Scheduled and Ready. Offline and historical/unconfirmed process records never establish background work. The CLI's additive `process_work` summary uses current owned OS trees (one process-table sample per fleet listing) or the native DeepSeek job registry; it does not scan native transcripts on each fleet poll. Saved session records retain unresolved shell-job identities and at most 16 explicitly settled jobs within a 64 KiB history budget, with 1 KiB output tails. Existing live and archived records are compacted on their next ordinary write; reading a record does not rewrite it. Unknown jobs and calls still awaiting hook settlement keep their evidence, including prior-run identities. This storage limit does not change Background status, reply deferral or process ownership. Pause/Resume carries this evidence with its original job/run identities and retention bounds; it does not make recorded jobs current or grant control of them. Process output reads use the provider's native log when available. Otherwise they return retained text, marking shortened tails as truncated. A pruned job or missing native log returns an explicit unavailable result. Earlier history can be read from the provider's existing logs where available, rather than accumulating in every session record. Native completion metadata alone does not establish an empty output. A native result that explicitly records empty text remains a valid empty result. Subagent rows and the Inspector use **Recorded** for offline, archived, paused, stopped or unverifiable parent sessions. Recorded children contribute no current work to the displayed counts; their saved states are retained. A current child's explicit input or approval request still takes precedence over Working. Working and compacting timers use native start evidence and update locally without extra host requests. An idle agent with pending jobs it scheduled for itself (Kimi `CronCreate`) is **Scheduled**: its badge and detail show the next run time instead of a timer, or "due" once that time has passed. A question, approval or error still takes precedence, and work shows as Working. Theme, density, animation and machine/project label appearance are local preferences. **Settings → Appearance → Content scale** adjusts Activity, questions, the message field and Terminal from 75% to 200% in 5% steps, with 100% as the default; the session list, the side panel, the session header and its tabs keep their size. Drag the small handle above the message toolbar upward to enlarge the message field, or downward to shrink it. Double-click the handle to restore the default height. The height is a local preference shared by sessions and retained across restarts; smaller windows temporarily limit it so the conversation stays visible. With the handle focused, Up/Down resize it and Home restores the default. Settings and dialog selection fields use the same themed dropdown. The list uses Zerus menu colors in light and dark skins, marks the current value and scrolls within the window. Arrows skip disabled choices; Enter or Space opens the list and confirms a choice, Escape closes it without changing the value, and typing finds choices by prefix. Closed arrows change the value directly, as with the former native selection fields. Tab confirms the highlighted choice and continues to the next control. The popup returns focus to its trigger on selection or Escape, including inside modal dialogs. **Settings → Appearance → Activity width** keeps Activity readable in a wide or fullscreen window: the transcript, its queued input, questions and the message field share one centered column of at most 900 px by default (480–2400 px). The width is measured at 100% and grows with content scale, so lines keep their length. The scroll bar stays at the pane edge and the side margins scroll the transcript. Drag either column edge in Activity to resize the column symmetrically, or double-click an edge to restore 900 px. **Full-width Activity**, in Settings and in Activity's context menu, fills the whole pane; **Reset Activity width** in the same menu restores the default column. Narrower panes use their full width, and Terminal, Processes and Native UI are not affected. A reset icon appears beside an Appearance slider's value once it differs from the default and restores that default. **Settings → Appearance → Usage limit indicator** sets how the account usage in the status bar and on Overview account cards shows each limit window. The default, **Usage and elapsed time bars**, draws usage above a gray bar for the elapsed part of the window; a longer usage bar means a faster than even pace. **Pace marker** shows elapsed time as a mark on the usage bar, and usage beyond the mark takes the warning color. **Pace marker and reset countdown** adds an hourglass with the time until reset, such as `26h` or `6d`; compact Overview cards omit the countdown. Colors follow the average pace since the window started: green when the limit lasts until reset, orange when it would run out in the second half of the remaining time or 90% is used, and red when it would run out sooner or is exhausted. The first 8% of a window, and windows without a reported length or reset time, keep the fixed 70%/90% thresholds. The tooltip adds the time until reset and the pace forecast. **Settings → Appearance → Keep Zerus above other windows** keeps the Zerus window over other applications on X11, macOS and KDE Plasma 6 on Wayland. On KDE Wayland, Zerus uses temporary KWin scripts scoped to its own window and confirms the compositor's state; it installs no window rules. The pin above Settings on the left rail switches the same option, and both controls follow changes made in KDE's window menu. The unpinned icon is a muted tilted outline; the pinned icon is upright, filled and gold, with a small line beneath it. The icon follows the confirmed window state and retains its color across theme changes. Hover only highlights the button background; its tooltip names the next action. KWin rules can override the preference; Zerus explains a refused change. Other Wayland desktops require their own integration and show the option disabled with a window-menu/rules workaround. Files and terminals opened from Zerus may appear behind it. Missing Git metadata does not turn a folder into a repository. The project button beside the machine chooser focuses Sessions on one or more logical projects. Check projects to apply changes immediately; selected projects appear as removable chips. **All projects** clears this restriction. Right-click a project band for **Filter this project**, which replaces the selection with that project alone. Clear it using its chip or **All projects** in the chooser. Multiple projects selected in the chooser form a union, narrowed by the machine, state, folder and search filters. Selection stays local to the open workspace while navigating sections; an explicit session link or Overview scope opens its requested context. Renaming a project retains selection, and new projects do not join an explicit selection automatically. The project chooser shows parent-session counts for the current state, machine and folder scope before project selection or text search, including zero counts. Its open checkboxes and selection stay in place during polling. A removed selected project remains as **Unavailable project** until removed from the filter. The account button beside the project chooser selects one or more specific accounts, rather than agent types. Its names and verified identity groups follow Accounts: one verified account on several machines is one choice, and the machine filter remains independent. Different accounts with the same label remain separate. Choices retain the exact machine-local profile bindings selected at that moment. A later catalog refresh or a newly discovered binding never expands that selection silently. Selected accounts appear as removable chips; **All accounts** clears the account restriction. Account selection intersects the project, machine, state, folder and search scopes, including message search and loaded archives. Chooser counts use the other scopes before account selection or text search. An unavailable selected account stays selected until explicitly removed. The chooser uses the same published, current profile catalog as Accounts; removed profiles and historical session-only bindings do not create extra choices. Sessions without a recorded account remain distinguishable from known accounts and shell sessions; they never borrow the current default account. **Details** shows the session's bound account, its profile ID and recorded agent home when available. Account catalogs and identities are warmed at startup and shared with Accounts. Opening the chooser refreshes the catalogs, reusing cached identity checks. Newly loaded choices appear without reopening an empty chooser. These reads do not sign in or change any running session. Changing the state, machine, project or account filter only changes the session list. The open conversation and its draft stay in place even when no row matches; its row is selected again when it returns to the list. Click another session to open it. **Show in session list**, beside the conversation title, opens the Sessions panel, expands the row's groups and centers it without changing the open conversation. Hiding filters are adjusted with a brief notice. The row pulses twice, or uses a static highlight with reduced motion. Archived conversations open in Archive; an already-known selection outside its loaded page is shown with an explicit notice. When the open session is terminated or removed, the conversation pane returns to **Select a session**. Polling, new sessions and filter changes keep this selection empty until you choose a session. Unsent drafts remain in **Saved drafts**. A desktop draft belongs to its session, not to the session's name. Since zerus-ucck P2c, a live or saved session that lists a durable session ID keeps its message, subagent, question-answer and voice drafts under that ID, so a draft stays with its session across a rename. A draft saved under the name before moves to the ID once, when its session opens, and never over a draft already there. Archived sessions and sessions without an ID keep their drafts under their names. **Saved drafts** shows such a draft by the name its session had when the draft was saved, and **Go to session** finds the session by its ID. After a downgrade to a desktop build that reads only names, that build opens the session with an empty message editor. The draft stays under the session ID, because the older build writes only the names it uses itself and never deletes it. That build lists it in **Saved drafts** as `id:`, without a draft mark on the card. A draft typed in the older build stays under the name. Back on this build, the composer shows the draft kept under the session ID, and the one written under the name stays in **Saved drafts**. Read marks waiting for a host follow the same rule. A mark is queued under the session ID the listing reports for its run, so two sessions that share a name keep separate marks; it is still delivered with `hgs read NAME`, guarded by run and conversation. A **Needs attention** or review-later mark of a session without a conversation is kept under its session ID, and one kept under the name moves to it. The **Active** filter combines sessions currently working or Scheduled, those in **Needs attention**, and sessions with unsent text or attachment drafts, counting each session once. Each status filter's tab count is the number of sessions it lists before the text search, scoped like the list, and a parent or child that fails the filter is never listed for its relative. Archive counts and lists the same loaded date window. Desktop, Android and iOS use the same filter IDs and membership rules, pinned by one shared case table (`mobile/android/app/src/test/resources/session-filter-contract.json`); drafts remain local to each device. Drafts for visible subagents also keep their parent session active. Drafts and explicit review-later reminders remain active offline; stale work alone does not. Archives stay in Archive. Active also applies to desktop content search, and the Dashboard's Active counter opens this same filter. Creating, clearing or sending a draft updates the filter and count. Cards with an unsent draft have a blue edge in the Draft color, including the open conversation, offline sessions and Saved drafts inspection. Collapsed tiles use the same color around their frame. Attention and errors retain their warning colors; working indicators and unread identity remain unchanged. The **+** in the session list header opens **New session**, like the one in the side rail. The button beside **⋯** collapses the list into a strip. Every project band and session row keeps its height, so each session becomes a square tile: status and provider icons, the session name on up to two lines and a short state such as the working time. Instead of the attention edge, a tile's frame takes the color of its state (working, needing an answer, error, paused, draft or a new reply) with a faint glow inward. Each band shows the project name and its most urgent counter. Above the tiles and as wide as them, the strip keeps a search button and two filters: the active one and the most urgent other one (sessions needing an answer, otherwise active sessions, otherwise all). Rows open on click and name their session in a tooltip; tiles do not open a session's subagents. Expanding grows the same rows back into cards. The strip's search button opens the full list over the conversation without resizing it; Escape or a click outside returns to the strip, and the pin docks the list again. While the pointer rests on the strip, the full list opens over the conversation; turn this off with **Settings → Sessions → Expand the collapsed session list on hover**. The collapsed state and the docked width are local preferences. Search names, IDs, folders, branches and models immediately. From two characters, content search also reads public Codex, Claude and Kimi messages and saved tool events on each host, and DeepSeek messages through a running native host ([DeepSeek](#deepseek)). Project, machine and state filters narrow results; the all-sessions view includes archives. Results open the recorded message; **Back to latest activity** returns to the live timeline. **Limited history searched**, **Some history unavailable** and excerpt labels describe incomplete coverage. Internal reasoning and system instructions are excluded. The unindexed `hgs search --query TEXT` scan and the indexed search's fallback bound discovery before loading histories: at most 2,000 directory entries, 500 record reads and 4 MiB of raw record bytes, with a 500 ms discovery deadline. Large shell-job payloads count against that byte budget but are discarded while decoding search metadata. Directory enumeration rotates across current bindings, ID-layout sessions, archives and DeepSeek bindings instead of collecting an entire inventory. Results prefer recent records within the admitted subset; they do not imply the globally newest matches when discovery is incomplete. The reply then has `truncated: true` and `discovery.complete: false`, so the UI keeps **Limited history searched**. `--indexed` retains its separate paged index coverage and cursor contract. Discovery bytes also reduce the existing total history-read budget. This display-only scan never replaces a complete canonical inventory used for lifecycle, cleanup, caller proof or other authority decisions. **New reply** stays unread until its latest result is visible in an active window or an attached Terminal at the bottom. Background windows and old search results do not clear it. Read state is kept on the session's host: a reply or request read on any desktop or phone is read everywhere after the next poll and its notification is withdrawn; it survives rename and resume. Hosts with an older `hgs` keep read state on each device. Viewing never answers an approval. **Mark as read** clears the current reminder without answering the agent; **Mark needs attention** creates a local review reminder. Opening the conversation does not clear an explicit review reminder. **Mark all as read** (right-click the Sessions icon in the rail, the icon beside Saved drafts, or the project and machine action menus) marks current replies on every machine as read, including hidden sessions. Sessions marked as needing attention keep their reply unread; pending approvals, questions and errors stay highlighted. Ctrl/Command-click selects multiple sessions while preserving the open conversation and draft. Shift-click selects the visible range from the last selection anchor; Ctrl/Command+Shift-click adds that range to the selection. Shift with Up/Down or Home/End selects ranges by keyboard, using the current filtered row order and skipping hidden rows, project headers, subagents and pending launches. Anchors follow session identities across refreshes; a hidden or removed anchor falls back to the visible open row, or to the clicked row when none is visible. Batch actions include local **Compact session rows** and **Expand session rows** icons, read/review later, pause, resume, archive, project move, termination and forgetting. Both density actions are available for a mixed selection and apply only to rows needing that change, including offline rows. Applicability is shown per selection. Escape or the selection close button clears selection. Context menus and shortcuts preserve the target identity. **Clear archive…** requires confirmation, preserves offline records and excludes new records created after the confirmation snapshot; native history remains. Enter opens the selected live session and Escape closes the current transient UI; it never closes the workspace. An archive needs explicit **Restore**; Enter does not start it. The other keyboard commands are listed below. ### Keyboard **Mod** is Ctrl on Linux and Windows and Command (⌘) on macOS. **Control** is the physical Control key everywhere; macOS keeps Command-Tab and Command-` for its application and window switchers. | Command | Linux / Windows | macOS | |---|---|---| | Overview, Sessions, Projects, Machines, Accounts | Ctrl+1 … Ctrl+5 | ⌘1 … ⌘5 | | Settings | Ctrl+, | ⌘, | | Go to… (sessions, projects, accounts, machines, commands) | Ctrl+K | ⌘K | | Keyboard shortcuts | F1, Ctrl+/ | F1, ⌘/ | | Next / previous session | Alt+↓ / Alt+↑, Ctrl+PgDn / Ctrl+PgUp | ⌥↓ / ⌥↑, ⌘⌥↓ / ⌘⌥↑ | | Next / previous session that needs attention | Alt+Shift+↓ / ↑ | ⌥⇧↓ / ↑ | | New session | Ctrl+N | ⌘N | | Rename session | F2 | F2 | | Search sessions | Ctrl+F | ⌘F | | Refresh | Ctrl+R, F5 | ⌘R, F5 | | Next / previous tab (Activity, Terminal, Native UI, Processes, Task View) | Ctrl+Tab / Ctrl+Shift+Tab | ⌃Tab / ⌃⇧Tab | | Switch between Activity and Terminal | Ctrl+` | ⌃` | | Show or hide the side panel | Ctrl+I | ⌘I | | Next / previous area (list, conversation, message field, side panel) | F6 / Shift+F6 | F6 / ⇧F6 | | Send message (also Enter) | Ctrl+Enter | ⌘↩ | | Send queued messages now | Ctrl+Shift+Enter | ⌘⇧↩ | | Send and push now | Ctrl+X, Ctrl+S | ⌃X, ⌃S | | Increase, decrease, reset content scale | Ctrl+= / Ctrl+- / Ctrl+0 | ⌘= / ⌘- / ⌘0 | Session navigation moves through the visible list, or the search results while they are shown, and skips project headers and subagents; it does not wrap. Attention navigation moves among the sessions of the same list that match the **Needs attention** filter, wraps around and opens a collapsed project. Tab cycling skips hidden tabs. From Terminal, Ctrl+` returns to Activity with the cursor in the message field. **Send queued messages now** runs the agent's own send-now action for the queue shown in Activity, exactly like its **Send now** button; it never sends the text being typed. If the earlier queue is no longer visible, nothing is sent: Activity refreshes and a transient error asks you to check Terminal or the current queue before retrying. **Send and push now** sends the typed message and, once the agent shows it in its queue, sends that queue now. With an empty message field it is the same as Send queued messages now. If the message does not appear in the queue within 20 seconds, for example because the agent took it directly or a dialog such as the cold cache warning is still open, or the session's run or conversation changes, the push is dropped with a notice; the message is never resent. Selecting another session drops the push at once, and a new push replaces one that is still waiting. A message with attachments but no text is sent without a push, because the queue cannot be matched without text. Without a selection, Ctrl+X starts this sequence; with a selection it still cuts. As in every Qt key sequence, a key other than Ctrl+S after Ctrl+X cancels the sequence and is not typed. **Terminal keeps the agent's keys.** While Terminal has focus on Linux and Windows, a key reaches Zerus only when a command uses it and it is Ctrl or Ctrl+Shift with a digit, Tab, PgUp, PgDn, ` or comma, or Ctrl+Shift+Enter. Ctrl+letters (Ctrl+C, Ctrl+R, the agent's own Ctrl+X Ctrl+S), Alt chords, Escape, Enter and function keys go to the agent. On macOS every Command chord except ⌘C and ⌘V reaches Zerus, and of the Control chords only ⌃Tab, ⌃⇧Tab, ⌃` and ⌃⇧`. **Text fields keep their editing keys.** In the message field and search, a command's key wins over the field except for copy, cut, paste, undo, redo, select all, word and line movement and deletion (Ctrl, Command or Alt with arrows, Home, End, Backspace or Delete), and keys without Ctrl, Command or Alt. Function keys are not editing keys: F1, F2, F5 and F6 reach Zerus without a modifier. So Alt+↑/↓ switches sessions even while typing, and on Linux Ctrl+K opens Go to instead of deleting to the end of the line. A focused drop-down list keeps Alt+↑/↓ and F4 to open it, and the project list on the Projects page keeps Alt+↑/↓ to reorder projects. **Go to** (Ctrl+K) searches sessions (not archived), projects, accounts, machines, sections and commands by name; start the query with `>` to list only sections and commands. With an empty query, sessions opened recently come first, then the others in the order of the session list. Enter opens the result; Escape or the Go to chord again closes the popup. A session opens under the current filter when it is visible there; otherwise the filter changes to All sessions. A project selects its first session, or opens Projects with that project selected when it has none. **Settings → Keyboard** changes any command's chords (up to two per command, each a key or a two-key sequence), marks the chords that also work in Terminal, and resets one command or all of them. Keys used for typing, navigation, text editing, context menus and Terminal copy/paste cannot be assigned. A chord already used by another command can be reassigned after confirmation. Changes apply at once and are stored on this device. **Keyboard shortcuts** (F1) lists the current chords and these fixed keys: Enter and Shift+Enter in the message field, Escape, Tab and Shift+Tab, Tab to take a suggestion, list navigation keys, Menu and Shift+F10, Ctrl/Command-click, Space and Escape during voice capture, Ctrl+Shift+C/V (⌘C/⌘V on macOS) and Shift+PgUp/PgDn in Terminal, and Alt+↑/↓ in the project list on the Projects page. ## Activity, messages and native controls Activity shows recorded public messages and tool events rather than a full copy of native history. User messages preserve literal text, Markdown markers and line breaks; agent replies render Markdown. New main-session prompt hooks retain up to 32,000 characters for Activity separately from their short list previews. Larger displayed messages have **Show more** and **Show less** controls. If only part of a message is available, Activity says so and points to Terminal. Older clipped previews can recover their body only through an existing exact native message, request or typed Kimi-turn binding in the same conversation. A shared prefix, nearby timestamp or one available candidate does not establish identity. Unbound pre-upgrade previews stay explicitly partial. Attached-message receipts remain reserved to their already bound row, including complete or local rows. This display repair adds no row, sends no input and never confirms delivery or native acceptance. The copy button at the right of a reply's header puts its Markdown source on the clipboard; a text selection still copies the visible text. Claude's recorded thinking appears in full as a quieter **Thinking** card: the same Markdown at the same size, without the card fill and with dimmer text. Adjacent tool events collapse into groups. Reading older history preserves scroll and selection; **Jump to latest** returns to live events without resizing the timeline. Its double-down-arrow icon sits beside Voice in the composer toolbar, outside the messages; the tooltip includes the number of new events. Subagents use the same icon in their own toolbar. The adjacent up/down buttons jump between this session's messages from you, including phone text and recordings, and briefly outline the destination. They skip agent replies, tools, system notices, peer messages and inherited history. Previous reads older pages one at a time until it finds your message or reaches the end, showing a spinner while reading. A direction is disabled when no matching message remains. The default shortcuts are **Ctrl+Alt+Shift+Up/Down** (**Command+Option+Shift+Up/Down** on macOS); Settings > Keyboard shortcuts can change them without changing composer keys. Pressing Enter on a session or subagent row opens Activity and performs the same jump. Double-clicking a subagent row also jumps to latest; double-clicking a session row toggles its compact presentation. Connect commands remain available through **Copy connect command** in the session menu. Claude hands finished background work and other sessions' messages back as a new turn. Activity never shows them as your message: a background task becomes a violet **Background task** notice, a subagent's final report a **Subagent report** with one summary line and **Show report** for the full Markdown, and a message from another Claude session a **Message from** notice with its full text. Search and the session's last request ignore all three. The owner-only `events.sqlite3` journal sits with session records on the agent host and retains about 50,000 events per machine. Excerpts can contain project data. Pause/resume continues the same conversation journal. Selected Activity normally polls every 2.5 seconds while visible; host lists poll every five seconds, and the tray keeps its background polling when the workspace is closed. Kimi replies and intermediate public messages come from the exact conversation's `agents/main/wire.jsonl` when Stop lacks text. Transcript reads are bounded to an 8 MiB tail, 50 replies and 32,000 characters per reply. Late copies do not duplicate cards. Nested `codex exec` reviews register as separate children, including `--ephemeral` runs without a transcript. Detection uses the rollout's `source: exec` or the native caller's ancestry to the verified live parent process. Child events preserve the parent's conversation, model and history; ephemeral children show their recorded request, tools and result. Unknown inherited SessionStart events cannot replace an established parent. `/new` and `/clear` still change the main native conversation. Claude's background service runs jobs in processes that inherited the run token of whichever session started the service. A hook names its Claude process and conversation (`CLAUDE_PID`, `CLAUDE_CODE_SESSION_ID`); an event from a Claude process that is neither the session's agent nor runs under it never changes that session by its token. A background job belongs to the live session whose agent window moved it there, as Claude's session registry records (`jobId`, `parkedJobId` in `sessions/.json`). The session follows the job's conversation without a clear when its transcript ends with Claude's `continued-in` mark for it; a new conversation in the job clears it as `/clear` does. Events of jobs that no live session holds are not recorded. A command such a job runs, such as `hgs task` or `hgs self`, acts as that session while the job is on its conversation. ### Sending and attachments Enter sends, Shift-Enter inserts a line and Escape releases focus while keeping the draft, unless a turn is working. Paste images, drag local files or use the attachment button. Attachments collect in one chip in the fixed-height toolbar above the message field, next to session notices (cache, account limit, recovery) and the context counter; its popover previews, opens and removes them. Labels such as `[Image #1]` and `[File #2]` preserve attachment placement within the text; removing one does not renumber the rest. Text, cursor/selection and attachment bytes are saved locally as they change, separately for each machine, session and subagent. They survive GUI crashes, restarts, unavailable machines and ended sessions, even if the original attachment file is gone. Storage is a private directory next to the desktop's Qt settings file (`.drafts`), outside P2P configuration sync. Pasting an image in Terminal uses the same draft attachment path and opens Activity so you can review it and send your message. It never sends automatically or writes image data to the terminal. If the message field is not ready to accept attachments, Terminal shows an Open Activity action and asks you to paste again when it is ready. Text-only terminal pastes keep their normal behavior. In Terminal, Ctrl+Shift+C (⌘C on macOS) copies the selection exactly as shown, and Ctrl+Shift+V or Shift+Insert (⌘V) pastes; Ctrl+C and Ctrl+V stay the agent's keys. Right-click opens **Copy selection** and **Paste**. While the agent reads the mouse, a right-click goes to the agent; hold Shift for the menu. Use **Reference an existing file** (the link button beside Attach, or its Files menu in a narrow column) when the file already exists on the agent's computer, including very large files. Locally, choose a file or enter its absolute path (or a `~/` path); Zerus checks that it names an existing file. If that check cannot answer within a few seconds, for example on an unresponsive network mount, the dialog says so and offers Retry. For a remote session, enter an absolute path (including Windows drive or UNC paths on a Windows computer) or `~/` path on the named remote computer. When that computer's hgs has `path-info`, Insert asks it whether a file is there (one metadata read, no content) and refuses a folder or a missing path; if it does not answer in time, the dialog offers Retry, and closing the dialog ends the call. On a computer with an older hgs, only the path's form is checked, as the dialog then says. A file on your desktop is not uploaded or made accessible to that computer. Zerus inserts an editable, quoted path into the draft and saves it as ordinary message text. Review it and press Send when ready. This action does not read, copy or Base64-encode the file and has no file size limit. It refers to the existing file, whose contents may change; the agent decides how to use it. Ordinary attachment uploads retain their existing limits. Session refresh, connection and recovery errors appear on one line beside the attachment button, with the complete diagnostic in its tooltip and an explicit session refresh action. They do not move the Activity or Terminal tabs. A blocking session error makes the message field read-only and muted while preserving its draft, focus and selection; informational notices leave editing available. When the composer is hidden, the same diagnostic uses the existing workspace footer. Other operation notices retain their priority there. An uncertain draft holding a deferred-input identity shows a quiet **This text may already have been delivered** hint when its exact text appears in the loaded history of that run and conversation. The hint is derived from the existing bounded history window and disappears when it no longer matches, including on edit or Allow retry. It changes no draft, checkpoint or uncertainty state: text equality is never request-ID receipt evidence and never clears or retries input. `hgs [@host] delivery receipt ORIGINAL_NAME --json` reads one original send receipt, including text-only sends, without sending or checking a native agent. Its input is an object containing `request_id` (the read transport UUID), `message_request_id` (the original send UUID), `expected_machine_id`, `expected_session_id`, `expected_run_id`, `expected_conversation_id`, `provider`, `native_digest`, and an optional `agent_id`. Here `provider` is the agent kind: `claude`, `codex`, `kimi`, `dsh` or `opencode`. The name is the original recorded label, not a route to its current holder; this command never follows a rename. The request's machine and durable session binding must match the original. The native digest is the unchanged producer digest: SHA-256 of the exact stdin bytes for terminal sends, or of the compact JSON `[original_name, request]` for DeepSeek and OpenCode. It is distinct from a phone's canonical intent digest. OpenCode proof requires the original provider-valid `msg_` message ID; missing, malformed or unsupported native IDs remain unknown and are never exposed as delivery evidence. A verified submitted original returns body-free metadata, its submission time, queue flag and an exact native message ID only when the original records one. This proves admission to the original input path, not completion of agent work. In the default schema 1, every other readable outcome is `status: unknown` with a bounded reason. Missing, corrupt, oversized, pending, unbound or mismatched evidence never means Not sent and never authorizes replay. New sends record their immutable machine/session binding before delivery; older receipts without that binding stay unknown even when their digest matches. No lookup retrofits or rewrites receipt history. The lookup reads one UUID-named original of at most 256 KiB through pinned directories whose entries only their owner can change. It does not open the derived receipt database, enumerate receipts, run migration, resolve a live session or contact a provider. Missing state stays missing. Its existing computer-identity check is read-only too. The `delivery-receipt-v1` capability marker gates remote forwarding to prevent an older CLI from treating the command as a launch. This CLI operation is the first part of mobile ordinary-send recovery; connector and phone support ship separately. The `native-send-outcome-v2` capability advertises an opt-in terminal refusal for ordinary Claude, Codex and Kimi sends: `hgs send SESSION --delivery-outcome-v2 --json`. A live `NotOffered` witness under the original native input lock, before any settings key, input marker or payload, can publish `refusal_schema: 2`, `status: not_offered` in the same private input receipt store. Its machine, durable session and provider binding comes from the exact selected record under that lock. A missing binding leaves an unknown outcome and a spent UUID. No other error or receipt absence establishes this proof. An exact positively bound refusal prints a schema-2 JSON outcome on stdout while retaining exit status 1. It carries `proof: native_input_lock`, `request_id`, `name`, `machine_id`, `session_id`, `run_id`, `conversation_id`, `provider`, the unchanged raw-stdin SHA-256 as `native_digest`, and a bounded `reason`. Submitted sends retain their existing successful receipt shape. Exit codes and stderr sentences carry no negative proof. This opt-in terminal negative spends its UUID: an exact opt-in duplicate returns the original outcome without keys or writes, and an ordinary legacy send cannot re-admit it. A person can edit or discard the kept message and make a separate explicit send with a new UUID. Ordinary sends without the option retain today's retryable `refused_before_input` schema. The same read-only delivery lookup accepts optional `schema: 2`. An exact terminal negative returns schema 2 and `status: not_offered` with its closed proof and original bindings; `request_id` identifies the read and `message_request_id` identifies the send. It reads at most 8 KiB for the negative form and never upgrades an old retryable refusal. Unsupported, corrupt, missing, unbound, changed or possibly offered evidence stays unknown. The default schema-1 lookup remains unchanged. Connector and phone adoption of this mode ships in separate compatible slices; this CLI contract alone changes no mobile state. Recent attachment delivery projection uses the private, rebuildable `delivery-receipts-v1.sqlite3` locator in the state directory. A refresh reads at most 100 original receipts for the selected provider, conversation and child; older receipts use an opaque cursor bound to that scope and an index snapshot. New receipts cannot displace rows in an existing page chain. The locator stores identities and bindings, not message bodies or attachment bytes. Original JSON receipts remain authoritative for delivery, attachment access and no-replay checks; a missing locator never permits another send. The inspection's `receipt_projection` reports index coverage, its next cursor and explicit missing, corrupt or changed-original gaps. An unavailable or still building index is unknown coverage, not evidence that no message was sent. Legacy discovery runs in one coalesced background worker per state directory. Each transaction processes at most 64 original reads or 1,024 unchanged metadata checks, or runs for 25 ms, with a pause between batches. An explicit answer holds foreground priority across its nested checks and publication; the worker hands off between batches. SQLite writer custody is acquired before reading the transaction's snapshot; a transient busy worker retains its walk instead of exiting and starting over. A genuinely unavailable index stays unknown, with a 60-second worker failure backoff. An interrupted worker retains committed locators, their sequence numbers and a bounded continuation fenced by source directory, epoch, schema and row count. Discovery reopens with metadata checks; a retained row-count cursor resumes its count. An invalid continuation is discarded. It never deletes or rewrites receipt history. New sends retain the original atomic receipt write and update the locator on a best-effort basis afterward. Older caches remain unverified until the worker reconciles their originals. Removing a locator or changing its indexed identity invalidates coverage and snapshot cursors. A healthy unchanged family needs no new directory walk. Periodic verification checks original metadata in bounded slices and parses only new or changed receipts; recently modified originals are re-read for coarse filesystem clocks. Invalidated projections and schema tokens require fresh original checks. Inspection never does that walk. Before clearing a cache discrepancy, the worker verifies every projection field against its validated original and repairs compatible metadata. A conflicting original fingerprint or pinned conversation remains an explicit gap. A first-message receipt may acquire its original's resolved conversation while keeping its page chain. The writer re-reads and validates the original before this exact update. Other cached conversation changes immediately invalidate coverage and report `binding_changed`. Legacy guards must upgrade before a cache can serve verified coverage. The worker also checks indexed bindings not encountered in that walk, counting retained bindings within the same bounded pass. Finishing a source does not rescan its rows. It publishes that count only if the source stamp, epoch and trigger-maintained count stayed unchanged during counting; a racing walk keeps the live count and incomplete coverage. A missing original keeps its binding and becomes an explicit gap with a history change sequence. Discovery can finish with a gap; question recovery still refuses unverifiable evidence. Restoring the same original clears its gap, while a replacement with another binding remains untrusted. The same locator exposes exact name, run and conversation pages for question recovery. Deadline-bounded inspection never walks the question receipt directory; incomplete coverage keeps recovery unknown. An explicit answer authority read can reconcile that family synchronously, then must validate every original and drain a complete snapshot before treating recovery as complete. A cursor from an incomplete snapshot requires a fresh chain after migration finishes. Locator coverage alone never proves an answer's submission. A question-family witness is checked independently of unrelated terminal or provider backfills; a broken question witness still makes that recovery unknown. Codex terminal availability uses the same completed inspection snapshot and rechecks the live terminal identity without starting another receipt migration. Receipt readers open SQLite read-only with a bounded lock wait; a question inspection caps that wait at its remaining deadline. Actual answer input still requires fresh receipt recovery and the terminal's exact pending-question check. An explicit answer shares one 750 ms receipt-write waiting budget across its nested checks and connections. Its first reconciliation parses the complete original question family. Later checks in that same answer still enumerate every original, check stamps and count retained bindings, while reusing only unchanged old originals. Changed, unknown and recently modified originals are parsed again; the coarse-clock window remains anchored to the first check. This bounded request-local optimization ends with the answer and establishes no delivery proof. On Linux and macOS, reuse also requires the native file object and change-time stamp; other platforms retain full original reconciliation. Processing time does not consume or reset that waiting budget. Exhaustion before admission refuses without input; it never certifies stale coverage. Inspection retains its separate short read budget. Reads from the selected remote machine show a yellow loading circle beside the session name only after two seconds. It remains visible while an actual read is pending and clears when that read completes or fails. Switching sessions shows only reads belonging to the newly selected session or machine. Local reads do not show this indicator, and its appearance does not change the header layout. Ordinary text, cursor and question-form edits save through one ordered background writer. Waiting edits coalesce to the latest snapshot per draft, so typing does not wait for disk commits. The editor shows **Saving draft** until its latest checkpoint completes; a crash before that checkpoint can lose pending edits. Graceful close drains outstanding writes. Sending, renaming and delivery-state changes use durable barriers, and an older queued save cannot replace a later checkpoint or resurrect a confirmed sent message. Attachment snapshots remain immutable. Save failures remain visible and block sending until persistence succeeds. **Settings → Automatic approvals** provides a separate dangerous opt-in, off by default. Enabling it explicitly allows reachable sessions to run tools without individual review, including destructive commands and paid usage. It works while this Zerus process is running, including with its window hidden, and does not change another desktop's preference or the agents' permanent permissions. Resuming after an expired cache may process the full conversation again. While enabled, the normal peer polling interval is capped at five seconds so remote permission prompts need not wait for the ordinary minute-long refresh. Only verified, answerable one-time Claude, native OpenCode and native DeepSeek tool permissions qualify. Ordinary questions, startup trust, incomplete panels and persistent permission changes remain manual. Existing native identity and delivery guards still apply. Below the switch, **Categories** choose which of those requests are approved automatically; a request in a category that is off waits for the person. The categories apply only while the switch is on and are stored per computer as `automaticApprovals/category/`, beside the switch. Every category except Paid usage is on by default, and an enabled switch from before categories keeps that default. A request's category comes only from the tool name in its verified native question: Claude's permission hook `tool_name` (the card's header), OpenCode 2's permission `action` (the card's `permission_action`) and the DeepSeek tool in Zerus's own `Allow ?` approval. Matching is exact; commands, paths and other text are never parsed to choose a category. | Category (ID) | Claude | OpenCode 2 | DeepSeek | |---|---|---|---| | Read files and search (`read`) | Read, Glob, Grep, LS, LSP, NotebookRead | read, glob, grep, list, lsp | read, read_image, glob, grep, terminal_list, terminal_read, job_list, job_output | | Edit files (`edit`) | Edit, Write, MultiEdit, NotebookEdit, EnterWorktree | edit | edit, write, apply_patch, str_replace_editor | | Shell commands (`shell`) | Bash, PowerShell, Monitor | shell, execute | bash, pwsh, terminal_open, terminal_send, terminal_signal, terminal_close, job_kill | | Web pages (`web`) | WebFetch | webfetch | web_fetch | | MCP tools (`mcp`) | `mcp____`, ListMcpResourcesTool, ReadMcpResourceTool | none | `mcp____` | | Subagents and skills (`agents`) | Agent, Task, Skill, Workflow | subagent, skill | skill, subagent, workflow, spawn_teammate, send_message, interrupt_agent, wait_agent | | Other tools (`other`) | any other tool | any other action | any other tool | | Paid usage (`paid`) | WebSearch | websearch | web_search | Shell commands are one category: Zerus does not tell safe commands from destructive ones. OpenCode names MCP tools `_` without a prefix, so any underscored OpenCode action (such as `external_directory`) is Other, as is a card from an older CLI without `permission_action`. Other tools also covers a tool name that cannot be read; it may include paid tools. Paid usage always wins: a paid tool, OpenCode's image generation (`experimental_image_generate`, Other by name) and any request while the prompt cache is cold, which the agent reports or whose estimated lifetime has ended, also need Paid usage, whatever else they match. Answering after the cache expired processes the whole conversation again; an unknown cache state is not treated as cold. Usage-limit, extra-usage and credit prompts are not one-time tool permissions and are never answered automatically. The worker checks the categories when it selects a request, again just before the journal reservation, which records them, and again before delivery. Each check uses the current time with the cache state of the selecting inspection, so a warm cache that expires meanwhile needs Paid usage too. A category turned off or a cache expired before delivery finishes the reserved attempt as cancelled without sending anything. With `ZERUS_CLIENT_DESKTOP_SERVICE=1` the background service owns the categories with the switch, in its durable policy (all except Paid usage for an existing policy). The page then changes them only through the service's authenticated route: a category change names the complete set and the switch's committed value, so it never turns approvals on or off. Like turning the switch off, a change that approves nothing more (removing a category, or any change while approvals are off) is accepted while the background workers are unavailable; adding a category while approvals are on needs them ready. Each change is an exact, idempotent receipt and cancels approvals in flight. Zerus Next uses its live event-stream catalog for the same bounded discovery; it does not add a peer poller. Its opt-in is device-local and is never seeded from Qt or imported by migration. Confirm it separately in Next. Cached, offline or unidentified computers cannot admit an approval; each candidate is freshly inspected, and its exact identities are checked again before the existing native Answer lane runs under the journal's original request UUID. The same Settings page contains this computer's private approval journal, naming the computer, session, time, question, approval categories, selected answer and confirmed outcome. Each attempt is durably reserved before native input. Failed, cancelled and unconfirmed attempts remain visible; an unconfirmed delivery is never retried automatically, including after a restart. If the journal cannot be saved, automatic approvals pause without sending new answers. Turning the option off stops new approvals; requests already sent may still finish. The journal stores full questions only in the private local `approval-audit/journal.sqlite3` below the existing `HGS_STATE_DIR`. It is not part of P2P settings sync. Pages contain at most 50 summaries; exact computer and session filters use indexes, and Older/Newer navigation uses stable record-ID cursors rather than offsets or complete-table counts. Full question text loads only for the selected entry. Background discovery scans at most 512 sessions per tick, admits at most two concurrent targets and bounds its cooldown cache to 4096 entries, independent of total session or journal counts. `hgs approval-log begin|finish|list|detail` is the local desktop journal API (JSON stdin). `begin` selects only a supported one-time grant and returns a durable request UUID; an existing reservation never permits another delivery. `list` supports exact `host`/`session` filters and `before` or `after` record IDs. `detail` reads one entry. The command itself never sends native input. **Saved drafts** below the session list lets you preview, copy or restore drafts from ended or missing sessions into the current session. It lists the most recently edited drafts first; each row names the draft's session and computer (and whether it is a subagent message, question answer or voice message), with its time and first line. **Go to session** opens the session that owns the selected draft, or its subagent, while that session is in the session list. Double-clicking a draft opens the same owning session; unavailable sessions remain in the draft browser for preview, copying or explicit restoration. Rows reuse the Sessions cards, including provider and computer badges, with the last-edited date beside the model footer. Long fields stay within the card; rows have no hover tooltip because the selected draft's full text appears in the preview below. Both desktop themes use the workspace colors. Metadata uses separate fields or slashes, without dot separators. Copying keeps the dialog open; restoring never sends anything and replacing an existing draft requires confirmation. A source draft remains available after copying it to another session. Independent sessions can explicitly declare **Waiting for acceptance** and **Waiting for result** through `hgs wait`. The idle card names the producer and computer and shows elapsed time; the session stays in Active. Native work and attention take precedence, while reply-only completion badges wait. Settlement requires the scoped reply ticket and, for a result, a confirmed delivery receipt in the exact waiting conversation. The durable journal has bounded previews and stable pages. See [Agent coordination](agent-coordination.md). Confirmed sends clear the outgoing draft; failures retain it. After an interrupted or uncertain send, check Activity or Terminal before explicitly allowing another send. Saving failures are shown in the editor and retried locally; sending starts only after its recovery snapshot has been saved. Delivery verifies the exact run, process, conversation and native input state. A busy Claude or Codex session can accept a message through its native queue when its empty composer is recognized. An unknown busy layout or a draft refuses with `agent busy` before submission; wait or inspect Terminal rather than typing through that refusal. Diagnostic screen samples keep only the latest private `input_diagnostics/codex.json` or `claude.json` under the session state directory. Each sample is at most 16 KiB: cursor coordinates, bounded cursor-row text and structural metadata for at most eight nearby rows. Text from other rows and the attempted message is omitted. Listing sessions does not create samples. For a desktop service deferred send, a completed nonzero `hgs send` exit also retains its exit code and at most 1024 UTF-8 bytes of the first stderr line in the original receipt, without control characters. The failed Activity row shows that diagnostic. It never proves that nothing was sent: a missing input receipt stays Unknown, with the existing check-Terminal caution and no automatic retry. An ordinary public terminal send with a live `NotOffered` witness also retains an additive `refusal_schema: 1`, `status: refused_before_input` record in `input_receipts/.json`, under the original input lock and before any settings or message input. It binds the exact request ID, session, run, conversation, stdin digest and terminal transport. The record is at most 8 KiB; its reason keeps only the first 1024 UTF-8 bytes of the first line, without control characters, and no message or attachment body. This exact negative evidence does not spend the request UUID. A deliberate public send with the same UUID and exactly matching session, run, conversation, stdin digest and terminal transport checks the ordinary guards again. Under the same input lock, a renewed refusal atomically replaces the matching negative; reaching input atomically replaces it with the ordinary input receipt before typing. A different digest remains a content conflict; different identities, malformed or unreadable evidence and any non-refusal record keep their existing refusal or submitted-receipt behavior. After the child drains, the desktop retains this exact refusal as a bounded diagnostic on its Unknown receipt and shows its reason in Activity, including after read-only recovery. Known native reasons are translated in the English and Russian interfaces; other native diagnostics remain verbatim. This negative record never counts as submission, authorizes no automatic desktop retry and never clears the draft. Missing, mismatched or unreadable evidence and possible prior input remain Unknown. Only exact `submitted` evidence can mark the message delivered. For Claude and Kimi messages ending in a literal backslash, the paste includes a final newline so the single Enter submits the unchanged message instead of activating the agent's backslash-Enter line continuation. This is verified against native history; no second Enter is sent as an automatic retry. Claude's composer rules live in `src/state/input/settle.rs`: its module documentation, and tests that read real captured screens (`tests/fixtures/claude-composer-*`). `src/state/input.rs` applies them in the send gate and in the read made right before the paste. The single Enter follows only a composer that shows this paste settled, with Claude's closing rule or `↓ N more` bar on the screen. A view with rows out of view never proves. Right before the paste the composer must read empty once more. When it does not, that frame's bounded text becomes the receipt's composer evidence. A pane too short to show the closing rule is refused by the send gate before any receipt or input, with "Claude's pane is too short to show its whole composer; nothing was sent; make the pane taller and send again". With Claude Code 2.1.327 that is seven rows or fewer; eight rows still send. If the pane shrinks after the gate, the read right before the paste refuses the message as delivery uncertain, with nothing pasted. If it shrinks during the settle, the message stays in the composer, uncertain, and Enter is not pressed. On Unix, a public send to an existing-ID Claude, Codex or Kimi session can apply one exact scheduled Settings change before its message. The same custodian keeps the original SID exclusion, pinned Root object and one original 25-second deadline across both steps. Claude releases only the Root exclusion while its composer settles and its native transcript confirms the message. The same pinned Root object must be reacquired within the original budget before the single Enter and before receipt publication. The request-bound typing marker blocks other input and Clear input meanwhile. Both waits share one eight-second window after paste, clamped to the original deadline; neither renews it. Only a new typed user row or queue enqueue with exactly the significant message lines, stamped no earlier than paste, proves submission. Missing proof keeps the original receipt uncertain, with a bounded composer preview when its source still permits publication. No key or message is replayed. This path keeps the normal 64 KiB text limit and admits at most one attachment with at most 1 MiB decoded data. These exact count and byte decisions precede selection, receipts and terminal input; larger attachment requests use their existing send path, including the normal 20 MiB total attachment limit. Its outer input receipt precedes the first Settings key; `input_pending_at` and `input_pending_request` bind the outer request immediately before the message paste. After input is offered to that custodian, a refusal or lost acknowledgement means delivery is uncertain and never authorizes retry. These observations omit the best-effort diagnostic screen sample. Zero-pending sends, Background or busy sends and internal submissions retain their ordinary routing. Codex sends whose native conversation ID is still empty also keep their ordinary path; its startup dialog checks and Settings walk exceed this path's measured budget margin. Unprimed Kimi sends remain eligible. If another Settings custodian already owns the slot, the send keeps its ordinary blocking path. An expired or refused staged message gets one pre-reserved, UUID-specific tmux buffer discard after Stage physically settles, within two seconds of the original deadline. If Stage remains unsettled beyond that lease, cleanup is uncertain and its buffer may remain; original custody lasts until its helpers physically settle. This narrow path does not enable general native continuity. The deadline is minted once before the keeper handoff; nested Settings borrows it. Standalone Settings and Effort retain their 15-second keeper budgets. The desktop waits up to 30 seconds for a local Send and 45 seconds for a peer. The longer local caller lifetime also applies to ordinary and legacy local sends; their command arguments, input, routing and native checks are unchanged. The composer keeps its single-send guard until the original call settles. A connector operator's `subprocess_timeout` below about 27 seconds would cut a pending-Settings Send short; the connector default remains unchanged. Codex messages ending in an `@mention` likewise include a final pasted newline to move the cursor outside file/mention completion before the single Enter. Codex trims that newline on submission; the message and receipt retain the literal mention, including a recipient that matches an existing filename. Confirmed receipts are idempotent by request ID. An uncertain result is never retried automatically; inspect the native UI before submitting again. A session change or stale request cannot send into another conversation. Busy-session queue controls follow the native agent's capabilities; unsupported operations remain in Terminal or Native UI. Codex ordinary deferred follow-ups remain read-only unless its native UI offers the supported promotion operation. **Stop** interrupts the current turn and cancels recovery without terminating the session; Escape anywhere in the workspace except Terminal does the same while the selected session's turn is working, after first clearing a search being typed. While recording voice, Escape stops the recording instead and preserves its preview. Once the turn is interrupted, its prompt returns to an empty message field for editing; a started draft is kept. Claude, Codex and Kimi use verified native Escape; Claude sends no event for it, so HGS records the interruption once Claude shows it. Stopped before its first reply, Claude rewinds the turn and puts the prompt back into its own input instead; HGS then moves exactly that text from Terminal to the message field (Ctrl+Y in Terminal brings it back) and leaves any other input untouched. Supported DeepSeek hosts use native cancel. Native queue behavior still applies. When Codex lists pending steers ("press esc to interrupt and send immediately"), Escape submits them at once and any queued follow-ups after that turn. Ordinary Codex follow-ups queued alone are not sent: Codex interrupts the turn and returns them to its input in Terminal as one unsent draft. Activity can send again once that input is empty, so submit, edit or clear the draft in Terminal first. HGS notes the follow-ups the Codex panel lists when Stop sends Escape; while Codex reports that turn interrupted and its input holds exactly them, Activity says the queued follow-ups are back in Codex's input. An edited draft, any other draft and follow-ups Stop did not see listed keep the general notice to return Terminal to an empty prompt. Uncertain interruption is not repeated. Stop notices name the original session and computer even if you navigate away. If the turn has already ended or is waiting for input, no interruption is sent and no action is needed; Zerus refreshes the status and briefly shows that outcome. Other failures retain the diagnostic and ask you to refresh status or check Terminal before trying again. The status bar's **Dismiss notification** button clears a notice without changing the session. When Claude suggests your next message after a turn, Activity shows it as the empty message field's placeholder, as Claude's terminal does; Tab inserts it. Sending a message, a new turn or a new conversation removes the suggestion. Claude writes it with an internal agent, which is neither listed as a subagent nor shown in Activity. Claude's other internal agents, such as the ones that summarise a running subagent's progress, report without starting as a subagent or naming an agent type; they are not listed either and never keep a finished session Working. File links retain their visible path and source position. Relative references resolve against that session's folder. On Windows, references may also name a drive path (`C:\work\a.cpp:12`, `C:/work/a.cpp` or `file:///C:/work/a.cpp`); a share (`\\server\share\…`) never opens. The file dialog shows and copies a path on this Windows computer with backslashes (`C:\work\a.cpp`); remote machines keep their `/` separators. Local references can open the file or its parent folder; remote references identify the host and offer **Download…**, **Download and open** and an SSH terminal. **Download…** asks where to save. **Download and open** saves automatically in the local Downloads folder under `Zerus Files`, then opens that copy. A completed, unchanged copy recorded for that exact machine and remote path is reused without another transfer, including after restarting Zerus. The dialog then offers **Open local copy** and **Show file** (selected in Finder or the file manager), even when the remote machine is offline. **Download again** explicitly fetches an updated copy; opening a saved copy does not check whether the remote original has changed. Missing or edited cached files are not reused. Files saved by older versions without a recorded source are not guessed from their names. Fresh downloads preserve existing names with numbered suffixes such as `report (1).pdf`; simultaneous requests for the same source in one window share one transfer. Downloads use that machine's configured SSH profile and SFTP, stream directly to disk and publish the destination only after a successful transfer. Errors remain in the dialog; a saved copy can be opened with **Open local copy**. Offline or unresolved relative references explain why downloading is unavailable. The download continues if its dialog is closed, with a completion or error notice; an explicitly requested open still happens after successful saving. The 120-second transfer deadline leaves an existing destination unchanged on failure. **Settings → Files** controls the local downloaded-copy cache. **Never clear** is the default. An optional size limit removes the least recently used completed copies created by **Download and open**, without touching manual downloads, unrelated files or copies whose contents were edited. An internal index tracks ownership; files that have been moved or whose contents changed are no longer cleanup candidates. Transfers in progress and recently used or completed copies are protected for one minute so the default application can consume them. Usage may briefly exceed the limit, including a single oversized file; periodic cleanup runs while Zerus is open and on its next start. Enabling or reducing a limit requires confirmation. Cleanup and inventory run outside the UI thread. `hgs @host download --path REMOTE_PATH --output LOCAL_FILE` provides the same transfer from the CLI, including empty files and paths starting with `~/`. Display alone downloads or launches nothing. Copying the path keeps the dialog open so you can copy first and then choose an opening action. Desktop dispatch happens after the reference dialog is destroyed so Wayland activation does not depend on a disappearing window. Zerus opens files the way a browser treats downloads. Conversation attachments, draft attachments, downloaded copies, local file references and their folders open in their default application. Anything that would run a program is selected in the file manager instead, with a notice that says why. That includes: - file types that run programs, scripts or installers, such as `.exe`, `.bat`, `.ps1`, `.url`, `.app`, `.command`, `.pkg`, `.dmg`, `.desktop`, `.sh`, `.jar` and `.py`, plus types Windows itself rates as dangerous; - macOS bundles; - on Windows, names without an extension; - on Linux and macOS, executable files without one, and programs or `#!/…` scripts recognized by their content. A link is judged by its target. On Linux, when no file manager answers, Zerus opens the folder instead of selecting the file. Files from other machines carry the system's downloaded-file marker. These are attachment copies opened from Activity, and every completed download as soon as it is saved. The marker is Mark of the Web for the Internet zone on Windows and quarantine on macOS, which keeps an earlier approval. SmartScreen, Office Protected View and Gatekeeper therefore still apply when such a file is opened later. Windows skips the marker when policy disables zone information. Linux has no such marker, and cached attachment copies there are never executable. ### Questions and approvals Activity exposes supported native questions with their full visible disclosure, options, queue position and request time. It never submits a highlighted option without a user action. Answers are scoped to the unchanged run, process, conversation and request hash; uncertain input is not automatically retried. Unsent freeform answers, choices and the current question page are also saved locally. They restore only for the same machine/session, run, conversation and question hash. Interrupted submissions remain locked until reviewed; confirmed queued answers keep their submitted state after a GUI restart. Questions the agent wrote render its Markdown like replies in Activity: the prompt, details and option descriptions, at the card's text sizes. A link opens only when clicked: web links in the default browser and file references in the file dialog. Other link targets, raw HTML and images remain text. Approval and trust disclosures and panels read from Terminal, such as folder trust and resume prompts, are shown exactly as reported. Question cards fit the current question's content, up to 600 px or 60% of the Activity area's height, whichever is smaller. Longer prompts and options scroll inside the card; freeform answer fields and actions stay visible. Short questions remain compact, and resizing preserves answers and space to read Activity. Explicit **Submit** on a supported Claude question replaces its native Other draft with the form answer, including clearing it for a preset-only answer. Polling and inspection never edit native drafts. The exact form payload and matching native acknowledgement determine delivery; uncertain attempts are never replayed automatically. With Claude Code 2.1.296 or later on Linux, macOS and Windows, hgs also registers its own `PermissionRequest` hook for AskUserQuestion and tool approvals, `hgs __state answer-channel`, beside its usual hooks. The entry an earlier hgs registered for AskUserQuestion alone is widened in place. - It waits next to Claude's question panel and is bound to the one exact pending question. **Submit** hands the answer to Claude through this hook instead of the terminal, so the question can be answered at any terminal size. `hgs answer` receipts then report `transport` `claude_hook`. - It answers only for the saved conversation, and one hook process owns each question. - If the hook does not take an answer within three seconds, delivery falls back to the verified Terminal path (`claude_tui`). - Once the hook has taken an answer, that answer is never sent another way. If Claude does not confirm it, delivery is uncertain, the card stays locked and further answers are refused until the question is resolved in Terminal. - An answer, decline or cancellation in Terminal ends the hook, and so do a run change and its one-day deadline. - Sessions started before the hook was registered and other agents keep Terminal delivery. On Windows the hook runs only in Claude Code's exec form; settings that still use the shell form, written for an older Claude Code, keep Terminal delivery. Tool approvals through this hook are described below. A disabled **Submit** always shows why, including while a saved answer is still loading. Desktop question submissions, including skips and approval choices, require **Submit with full context** confirmation when the prompt cache is cold or its estimated lifetime has expired. Resuming with the full conversation can increase token usage, cost or subscription usage. **Cancel** keeps the form answers. Compaction or clearing can invalidate the pending question, so this confirmation offers neither action. A changed question, session or draft cancels consent. Kimi's native cold-cache chooser already provides the explicit cost and context choices. Its selected row is submitted directly, without a second full-context confirmation; the same identity and durable delivery checks still apply. While that complete chooser holds a submitted message, the session shows **Needs you**, with the four native options and **Open terminal**. Recognition requires the exact title, explanation, navigation hint, descriptions, selection and complete frame, bound to the pending input request, process, pane, run and conversation. Inspection never selects, presses Enter or retypes the held input; its original submitted or uncertain receipt is retained. A newer native input acceptance or the chooser disappearing clears this observation; an earlier turn ending does not accept the held message. The person's existing answer path stays available only with verified writable terminal mode; otherwise the options are read-only. A verified agent caller of this child's exact recorded launch parent (`source=launch`) may explicitly answer **Compact and continue** only. This proof applies on the child's computer. The local machine, parent session/run/conversation and original child question hash/run/conversation must all match; a link or environment markers alone do not prove the caller. Siblings, grandparents, unrelated agents and adopted/manual/claimed/forwarded parent links cannot answer; assigning a parent grants no such authority. The exception never selects Start a new session, Continue as-is or Don't ask me again, and never retypes the held message. Each navigation step rechecks the parent; the existing durable receipt prevents a second input on replay or an uncertain result. The person's choices in Zerus or Terminal stay unchanged. Automatic approvals and question routing still exclude this chooser. Remote CLI answers retain their existing generic authority; a person-only remote boundary remains separate follow-up work. App-owned desktop and Android dialog action rows place **Cancel**, **Close** or the equivalent dismissal at the far right, after the available actions. Long Android rows wrap, keeping dismissal last and visible with larger text. Destructive and full-context desktop confirmations default to Cancel; Android dialogs focus their dismissal after the dialog window gains focus. Enter on a valid desktop editing form may save or create; Escape/Back dismisses without submitting. Accepted operations that cannot safely be abandoned keep their existing pending locks; closing a review never repeats an uncertain command. Destructive buttons name their action and the dialog identifies its original target. System file, permission and installation prompts follow the operating system's own layout. Unsupported or truncated native prompts remain in Terminal. Claude wraps prompts, options, review answers, key hints and Bash commands to the terminal width and splits words longer than a row. Zerus matches the wrapped rows against the exact request at any width; only a clipped panel needs a larger Terminal. Claude keeps no scrollback for a question or approval panel taller than its pane, so a long question or command can lose its title and beginning everywhere. Kimi question dialogs and Kimi 2.1's startup folder trust prompt can lose their title the same way when their disclosure is long. Kimi 2.2 pages its trust disclosure, or asks for a larger terminal, when its pane is short; Zerus offers the trust choice only once the whole disclosure shows on one page, and never chooses for you. A session no client views keeps tmux's default 80x24 size, and so does a pane of the Windows session host. While a recorded question or permission request waits and such a pane shows a clipped panel, Zerus makes that pane taller, doubling its height up to 192 rows without changing its width, until the agent redraws the complete panel. The exact request match still decides; the next client that attaches sets the size again. A pane a client views keeps that client's size, so its clipped panel stays in Terminal, as it does under a Windows session host older than this behavior. Only a question listing, such as `hgs inspect`, grows a pane, and never while an answer to that run drives it: both hold the run's answer lock. Claude tool approvals keep the session at **Needs approval** and appear in Activity while Claude shows its chooser. When the complete panel matches the agent's request, such as the Bash command, file name or fetched host, Activity lists Claude's options verbatim after a short review delay. Options that reach beyond this request, such as always allowing, blocking, session-wide grants or mode switches, are marked and need a second **Confirm** click. Choosing a **No** option ends Claude's turn as in Terminal; the composer reopens after Claude's prompt is verified. A clipped or unrecognized panel, a mismatched request and plan approval stay visible with **Open Terminal**. Claude reports no answer given in Terminal, so Zerus settles it from the screen alone whenever a status listing, `hgs inspect` or `hgs read` looks at the session: Claude's interruption ending the turn records **No** or Esc, and the approved Bash command shown running with its elapsed time records **Yes**. Until Terminal shows either, and for an approved tool that is not a Bash command, the session stays at **Needs approval** until Claude's next event. Only a session waiting for such a request reads its terminal for this. While hgs's `PermissionRequest` hook waits beside a main-agent approval, the card answers through it, so a clipped panel no longer needs a larger Terminal. - The hook is bound to one exact request: the saved conversation, and the one active tool call whose tool and input equal the request when the hook starts. Without exactly one such call, the request is answered on screen as above; a later identical call is another request. - A paused session, a provider error, or a terminal that no longer belongs to the agent never lets a decision go through the hook. - Claude sends the hook no signal for an answer in Terminal, so the card and the hook act only while Terminal still shows a chooser. A complete panel must be this request. - The card always shows the whole request the hook answers: the Bash command, its description and any other field, or the whole input of another tool. - Claude's own options appear only when a complete panel shows exactly that operation. That means the main agent's Bash command, with its description if any and no other field, and no other active Bash call. A file name or host proves too little. For example, a Read of another file with the same name may be queued in front of this one. - Any other complete panel is answered on the screen as above, acting on what it shows. A clipped panel gives **Yes** and **No**. An unreadable terminal gives no hook card. - A visible safety warning of any kind must belong to this request's command, through a proven panel or the visible end of the command in a clipped one. Otherwise there is no hook card. - **Yes** allows this one tool call without changing any permission setting. **No** ends Claude's turn as in Terminal. **Tell Claude what to do instead** denies the call with your message, and Claude continues without it. - Options that reach beyond this request go only through the verified panel, with the second **Confirm**. A **Yes** or **No** that the hook does not take within three seconds also goes through a verified panel; feedback it does not take is not sent. - A decision the hook has taken is never sent again. Until Claude confirms it, the card stays locked and is answered in Terminal. - `hgs answer` receipts report `transport` `claude_hook` or `claude_tui`. - Automatic approvals use the hook only for a card whose complete Bash panel shows exactly that operation, with the same one-time choice. - Subagent and workflow requests keep the screen path. Claude 2.1.296 runs subagents in the background and shows their requests outside the main screen. Claude's Bash safety confirmations, including warnings about possibly empty paths in `rm` commands, also appear in Activity with the native warning text. A visible safety confirmation makes the session **Needs approval** even if its permission hook was not recorded, and ordinary message sending waits for the decision. Without a matching permission request, or when the full command stays clipped and no permission hook waits for it, the card offers **Open Terminal**. With a complete matching request, Activity can submit the native **Yes** or **No** choice. Claude's unattended denial countdown stays visible without replacing the request as it ticks. Desktop keeps the card's scroll, chosen option and review delay through these countdown updates. A changed command, warning or set of choices requires a new review. Bash approvals from Claude's subagents and workflows use the same Activity choices when one recorded child permission request matches the complete visible command. The answer is bound to that child request as well as the parent run and conversation; a repeated command is a new request. Identical pending requests from multiple children, missing hook evidence and clipped commands remain read-only. Other child tool approvals still require Terminal. A child's answer never interrupts the parent or clears a sibling's request; completion follows that child's own native events. Parent progress alone does not settle child permissions. Pending evidence is bounded without evicting an ambiguous request; if its limit is exceeded, approvals remain in Terminal until the next native session starts. Read-only native choices are visibly disabled, with **Open Terminal** as their action. Kimi plan approval (ExitPlanMode) keeps the session at **Needs approval** and shows the complete plan from Kimi's own request in Activity, rendered as Markdown, with Kimi's choices: **Approve** (or the two or three approaches the agent proposed), **Reject** and **Revise** with a one-line feedback field. A plan longer than 8,000 characters is shortened and names its saved plan file. Zerus answers only while Terminal shows exactly that chooser, using its number key and, for Revise, pasting the feedback before Enter; Kimi's recorded decision, including the exact feedback, confirms delivery. A clipped or different chooser, or one already in Revise feedback mode, stays read-only with **Open Terminal**. Kimi Code 2.6.3 hands the agent an approved plan's ExitPlanMode result marked as a tool error ("ERROR: Tool execution failed." before its "Exited plan mode." text and the approved plan), whoever approved it, in Terminal or in Activity; plan mode does end, and Kimi records the decision as approved. Kimi CreateGoal approval shows the full objective and completion criterion literally, with Kimi's own mode choices for Always Ask or Ask When Needed. **Switch to Never Ask and start** and a switch between Always Ask and Ask When Needed require a separate confirmation because they change permissions beyond this request. **Do not start** cancels the tool without creating a goal or changing the mode. Zerus answers only the exact native goal panel after the same complete wire and process checks as other Kimi approvals; Kimi's recorded decision and mode label confirm delivery. In the fullscreen Goal panel, animated foreground RGB colours on the exact `Using tools` status row above it may change between observations; all other screen bytes and the complete validated panel must match. A different, clipped or unverifiable panel stays read-only. Other Kimi tool approvals also appear in Activity, with the complete request from Kimi's wire. Kimi's hooks cannot approve, so Zerus answers only in Kimi's own panel, and only for a Bash command: the panel must draw that exact command, working directory, description and danger warning row by row, wrapped as Kimi wraps it, and the complete history of every agent of the conversation may hold no other unresolved Kimi request, however old: nothing proves that Kimi no longer shows one. A history longer than 8 MiB (4 MiB for another agent), a record Kimi is still writing, a line that is not a JSON object with one string type, an interaction record without its ID or of a kind Kimi does not write, or a repeated request ID keeps the approval read-only. Types and IDs are compared as decoded JSON. Every key and pasted feedback line first finds the same unresolved request, with its active tool call, in the same run, process and pane. The choices are Kimi's: **Approve once**, **Approve for this session**, **Reject** and **Reject with feedback**. The session choice asks for confirmation: Kimi then stops asking about that exact command and also approves every other request already waiting with the same action, which shows only a command's first 50 characters. Kimi's recorded decision confirms delivery. Other tools, commands Zerus cannot draw exactly, a narrow or clipped panel, and an unverifiable history stay read-only with **Open Terminal**. Automatic approvals never answer Kimi. Claude Code can also ask its own questions without an agent tool call, such as whether to switch models after a safeguard stop. Activity shows the question and its options verbatim with **Open Terminal** while Terminal still shows them: no tool result can acknowledge an answer, so Zerus never chooses one of these options. When Claude waits for input and no request explains it, Activity shows the chooser visible at the bottom of Terminal, such as **Session paused**, in the same read-only way. A new prompt ends any earlier request. Supported startup prompts include Claude workspace trust and auto-mode consent, Codex folder access, **Hooks need review** and **Update available**, and Kimi folder/MCP trust. These can appear before a conversation exists, but only with verified startup identity. A recognized panel must show its native title, folder, exact choices and key hint. Its explanation is shown verbatim and pinned to the answer, so changed native wording stays answerable: Claude workspace trust preserves its full permissions warning, Kimi includes the visible MCP commands, and Claude's auto-mode and resume panels keep their explanation and cost warning. Zerus adds descriptions only for reviewed text. In a Git subdirectory or worktree, Codex folder access names the repository root that Codex will trust. Claude wraps a long workspace path across rows; the joined rows must still equal the launch folder exactly. Codex 0.167 can offer **Back to Agent Command Center** instead of **Quit**. Back cancels opening the folder without saving trust and keeps Codex running; Quit exits the original Codex process. Both require an explicit user choice. Trust persistence belongs to the native agent. For a new Claude run on Linux or macOS, the original `hgs` supervisor confirms the complete first-run text-style panel automatically when both the native focus and current-selection mark name **Auto (match terminal)** or **Dark mode**. It preserves that selection and sends Enter once after checking the stable panel and the original process. An uncertain result never causes another Enter. Recognized manual theme choices, including Light mode and Dark mode with ANSI colors, appear in Activity with **Open Terminal**. Windows and runs whose original supervisor predates this feature keep the read-only theme card. Login, workspace trust, auto-mode consent and permission questions still require an explicit choice. Already-running Claude and Kimi sessions can retain the exact Bitwarden launcher notices above the complete workspace-trust panel; Claude also accepts its Keychain notice. These notices do not change the request identity or appear in its disclosure. Any other chooser before a conversation exists, such as a renamed option, an unreviewed update command, a panel for another folder or unrelated output above it, appears read-only with its visible text and **Open Terminal**. Zerus never answers it, and messages wait until it is answered in Terminal. Before the first turn, Claude's auto-mode prompt accepts absolute workspace paths and native `~/…` abbreviations that match the verified launch directory, also after the initial conversation is bound. Under a finished or stopped reply, the bound conversation and that turn identify it instead. The offer must be the complete panel at the bottom of Terminal: panel text quoted in the conversation is never answered, and messages wait until the offer is answered. Claude's **Resume this conversation?** chooser also appears in Activity when a long conversation has gone cold, including between turns in a resident session. The card preserves the inactivity, context size and five-hour usage warning. **Resume** and **Start a new conversation** require an explicit choice; Zerus never dismisses this warning automatically. If the native unsent draft has focus, pick a row in Terminal first. Replies verify the exact run, conversation and full panel before each key, and uncertain delivery is never replayed. For Codex hooks, **Review hooks** opens the native browser in Terminal; **Trust all and continue** and **Continue without trusting** are explicit choices. Review input with an uncertain result is never retried automatically. Codex's **Update available** picker shows both versions and the exact update command. **Update now** switches to Terminal while Codex runs that command; Codex then exits and the session needs an explicit resume. Codex leaves the picker and input mode at once and prints `Updating Codex via` with the command before running it. That announcement for the exact command, or Codex exiting, confirms the choice within 15 seconds, however long the installer takes. Zerus does not wait for the installer: the `hgs answer` receipt's `codex_update` is `installing` while Codex runs it, or `exited`. Without either confirmation, delivery stays uncertain and Enter is never sent again. **Skip** and **Skip until next version** continue startup, and Codex records the dismissal itself. Only reviewed npm, Bun, Vite+, pnpm, Homebrew and standalone Unix commands are recognized; other or clipped commands stay in Terminal. After **Update now**, the desktop shows a notice for that state: Codex is still installing its update, or it has exited and the session needs a resume. An older host's receipt has no `codex_update`; the desktop then only switches to Terminal. Codex's **Approaching rate limits** chooser also appears in Activity and on the phone after a turn. Its reviewed **Switch to gpt-6-luna**, **Keep current model** and **Keep current model (never show again)** choices use the exact guarded native answer path. Zerus never selects one automatically. A changed or incomplete chooser stays **Needs input** with an **Open Terminal** hint; it never authorizes a model change or an ordinary message. Each answer pins the process, run, conversation and complete panel before every key, and uncertain delivery is never replayed. After a resume, Codex asks **Resume paused goal?** when the conversation's goal is paused, stalled or limited by usage. Activity shows the goal from Codex's goal database once the centered dialog over the transcript shows the same goal and both choices; the session waits for this choice instead of Restoring conversation. **Resume goal** marks the goal active, and Codex continues it by itself when idle. **Leave paused** keeps it paused and the conversation waits for your message. A dialog too narrow to read, or for another goal, stays in Terminal. Optional Codex questions preserve the regular composer and support **Skip**. Codex closes unanswered optional questions when their native turn completes, is interrupted, or accepts an ordinary follow-up. Zerus removes those cards and their question badge without recording a user answer. Continued tool work alone does not close a question. Questions belonging to a native child remain with that child's parent; they are not requests for the person. When Codex's own question panel is open, Zerus answers or skips there. Codex's animated working status above the panel does not block an answer; any change to the panel itself does. An open panel taller than its pane keeps its title and scrolls the answers, naming the visible row in its key hints (`option 1/6`). In a pane no client views, a question listing grows the pane as it does for Claude until the whole list shows; a title taller than the pane stays in Terminal. A long answer wraps in Codex's Other field, and Zerus compares that field, wrapped rows joined, with the text it pasted. Queue arrows navigate optional requests from newest to oldest while retaining answers and the current multipart section. A required approval temporarily takes priority. Confirmed answers appear as **You (answer)** in Activity. Codex optional question replies show the question and your answer in separate sections, preserving the literal answer text. If an optional answer enters Codex's native queue, the question stays visible as **Submitted / Awaiting agent** with the original answer locked. Submission means the verified terminal received the answer; it does not mean Codex has recorded it yet. This state survives polling and GUI restarts. The card disappears after the exact native question reply appears in the conversation. If Codex closes the question first, this exact submitted answer stays as a read-only delivery receipt until acknowledgement; it is not an outstanding request for input. Zerus never resends the answer or promotes the queue automatically; **Send now** remains an explicit native queue action. Delivery without confirmed submission still requires checking Terminal before retrying. ### Models, effort, context, goals and subagents The Activity model selector changes supported per-session model/effort settings, leaving account defaults intact. Codex/Kimi options come from the selected account's native catalog. Before the first message, verified empty native input can allow selection without creating a conversation. Startup prompts, drafts, unconfirmed resume and an already submitted first message block that operation. Unverified states fall back to Terminal with an explanation. A choice that the agent's status line already shows is confirmed without typing anything into Terminal. A change that fails after the agent visibly read every typed key and returned to its empty prompt leaves nothing unconfirmed, so another change or a message can follow, including a new session's first message. When the agent has not reacted to a typed key, further changes and messages wait for its next native event: finish or cancel the change in Terminal and send a message there. Codex Ultra's double-chevron composer remains an ordinary input field: a confirmed session-only change permits another effort choice, messaging and context clearing with the same identity and draft checks. Earlier unconfirmed attempts retain their original receipts and are never replayed automatically. Codex model choices use the selected account's `models_cache.json` and sort by ascending signed 32-bit `priority`, preserving source order for ties, as in [Codex's native picker catalog](https://github.com/openai/codex/blob/rust-v0.162.0/codex-rs/models-manager/src/manager.rs#L170). Missing or invalid priorities follow ranked entries in their original order; a legacy catalog without priorities keeps its source order. This shared catalog order applies to both desktop and Android without changing the current model. Claude options are the models its `/model` picker lists, including **More models**, from the catalog Claude Code caches in the account's profile. Zerus expands a section only when the native picker advertises that action, selects the model and effort, and applies them with its session-only choice (`s`). Enter on a model row saves new defaults; Zerus never uses that action or the typed `/model NAME` and `/effort LEVEL` shortcuts for a session change. Zerus recognizes the picker by its **Select model** title below Claude's panel rule and by the keys it presses in the legend (`s to use this session only`, `Esc to cancel`, and `←/→ to adjust` for effort), not by its prose, which Claude Code rewords between releases; the `/effort` panel shares that legend under another title. An unconfirmed selection closes the recognized model picker with Escape while its original input authority is still valid. The change is confirmed by Claude's receipt in the exact conversation transcript and by its effort indicator when shown. In a conversation that already has replies, Claude warns that the next message re-reads the full history and uses more tokens: the selector states this before **Apply**, and Zerus then accepts only that built-in notice. A confirmation requested by a `PreModelSwitch` hook is declined and reported, as is a picker without the session-only choice; use Terminal for those. With Claude Code 2.1.296 or later, its `PostModelSwitch` hook names the exact model of every switch at once: `/model` in Terminal, a change from Zerus, an automatic switch or a resume. The selector shows that model until the transcript records a later turn or `/model` receipt; the switch itself adds no Activity entry. A stopped Claude session resumes with a choice made in Zerus through `--model` and `--effort`; otherwise it starts with the account's settings. Busy-session choices, and choices made while the terminal shows a chooser, remain **Pending** until the agent is ready, including after navigation away. If a chooser appears while the desktop applies a choice, the choice stays **Pending** and the desktop tries once each time the session becomes ready again. A failed or refused application, a new run and a new conversation end these attempts. A message sent before application uses the current model. **Save for resume** stores a stopped session's choice without starting it. A stale queued setting cannot replace a newer choice from another device. If a message or another client already consumed or replaced it, Zerus refreshes the current settings without retrying the stale request or showing a failure. `hgs [@host] settings SESSION --json` exposes the same scoped operation. Native clear/compact operations are capability-gated and require exact identity. When they are unavailable, `hgs inspect` reports why in `clear_context_reason` and `compact_context_reason`, empty while the action is available. A busy session names what keeps it from Ready: the main agent's turn and tools, and each working subagent with its current tool, up to three, then a count. The actions follow the status the session list shows, so Kimi profile groups still working after the main turn ended keep them unavailable and are named by profile, such as `2 “code” subagents`. Applying settings and forking a running session wait for the same Ready, and a profile hook entry that Kimi's native subagent catalog has replaced holds back none of them. A chooser recognized only on the terminal, such as Kimi's context choice after an idle period, keeps clearing, compaction, forks and effort changes unavailable until it is answered; `fork_reason` and `effort_change_reason` give the same reason as `clear_context_reason`. A model settings change made meanwhile is saved as **Pending** (`settings_apply_when` is `ready`), and no key reaches the chooser. The desktop shows the reason as the tooltip of the disabled **Clear context**, **Clear session** and **Compact and continue** actions, and as a line in the cold-cache confirmation. Hosts from before these fields leave the actions disabled without a reason. **Clear session** requires confirmation naming the session and host, preserves unsent drafts and rechecks identity. While Claude shows an approval, question or another chooser, **Clear session** asks for a separate **Dismiss and clear** confirmation: Zerus presses Esc once, as in Terminal, so an approval is denied and a question stays unanswered. It runs `/clear` only after the chooser closed and the empty native prompt is verified, and never repeats an uncertain attempt. Startup choices such as resume, permission mode and folder trust are answered in Activity instead. Claude reports no hook when **Stop** ends its turn, so the session stays **Interrupted** until its next message. **Clear session** is available there once no tool or subagent still works and the empty native prompt is verified, as for that message; a native draft keeps it unavailable and is named as the reason. Compaction still waits for Ready. DeepSeek context reset is unavailable until its native Session Controller provides the supported operation. A confirmed clear adds an amber **Session cleared** boundary to Activity and keeps the earlier local timeline above it: the agent no longer sees that history, but you can still read and search it. Resuming or opening another conversation starts a new timeline. Codex can defer its new-session hook until the next message; its verified empty native reset panel also confirms the clear, including `/clear` in Terminal. Only the header directly above the empty composer counts: the same header above an earlier message and its answer does not. Old context and prompt-cache values are hidden until the new conversation reports native usage. The saved native identity changes only on the real hook, and an unconfirmed command does not reset counters. A resumed Codex session can also confirm a Terminal clear when its main end precedes that hook; the end alone never confirms a reset. Zerus keeps the process and run and observes the real successor without replaying the clear or message. A stopped session offers **Start fresh…** instead, with the same confirmation, and keeps **Send** available: it offers **Resume and send** with the full saved context, **Resume, compact and send**, or **Start fresh and send**. Zerus Next names the same choices **Resume**, **Compact and resume** and **Start fresh** under its "Start the session to send?" title, with **Cancel** last as the default; its dialog actions wrap onto further rows rather than leaving a narrow dialog. The compact option waits for the restored conversation to accept input, then runs native compaction and delivers the unchanged message only after confirmed success. A failed start, an unexpected conversation or three minutes without readiness cancel that send and keep the draft. **Compact and continue** sends only after confirmed successful compaction with the same unedited draft; errors, cancellation or identity/draft changes cancel submission. While awaiting startup or compaction, **Waiting to send…** keeps the accepted text and attachments visible and locks edits. The field still supports selection and copy. **Cancel send** restores editing and keeps the complete draft; it cancels the automatic message, while startup or compaction continues. **Stop** interrupts the agent. A GUI restart keeps the draft without resuming automatic submission. Switching dialogs, changing filters or closing the workspace keeps accepted sends pending on their original sessions. They continue in the background, verify the same run/conversation and compaction request, and never submit a second copy. Context metrics use native telemetry, without guessing a capacity from a model name. Claude's window comes from its status line (see [Tracking and durable state](#tracking-and-durable-state)): `session_usage.context` gains `limit`, `limit_source` `native_statusline`, `limit_model` and `limit_observed_at` only while the latest report belongs to the session's run and conversation and names the model that the inspection reports. After a model change the window stays hidden until Claude reports the new model; after a clear Claude 2.1.296 reports at its next update, usually the next reply, and a resumed run reports when it starts. Compaction changes the used context, not the window. Claude's recorded compaction boundary replaces the earlier context size with its reported summary size. It invalidates the earlier prompt cache estimate; a new warm countdown requires fresh native usage with a reported TTL. **Tasks**, **Plan & agents**, **Details** and **Worktrees** occupy the resizable inspector. Its width, tab and open state are local; toggling it preserves Activity, drafts and Terminal attachment. Plan & agents shows the agent's own plan, not the project's Zerus tasks. Successful native task/plan tools supply recorded pending, in-progress and completed items. Tool failures and Stop do not complete tasks. There are up to 100 items per list and 65 lists, with truncation disclosed. Old data shows **Last recorded**; unavailable history is not reconstructed. Goals remain independent of turn state. Codex uses `goals_1.sqlite`, Claude uses `goal_status` in the exact transcript, and Kimi uses native `goal.create/update/clear` wire events. DeepSeek exposes its native phase and continuation permission. Only recorded usage and budgets are shown; missing data is never inferred from a prompt. Ready does not complete a goal. Subagents open their own Activity and return through **Main activity**, preserving the parent's draft. Individual child IDs and profile groups are distinguished; unknown counts remain unknown. An unknown child never keeps its parent from Ready. A Claude child that stops on a provider error, such as a usage limit, gets no SubagentStop: its StopFailure, or a `failed` entry for its current start in the workflow journal with no newer child event, settles it as **Error** with that message, and any later event of the same child but its Start resumes it. Ordinary child results/errors stay out of the attention count, while explicit input/approval requests remain visible. DeepSeek continuable children can receive messages through the native API with parent verification; other adapters and one-shot children may expose history only. The expanded session tree hides children whose latest reported turn is finished or failed by default. Session and Overview cards then show only the active count, omitting an empty indicator when no active or uncertain children remain. **Settings → Sessions → Show completed subagents** restores completed rows and active/total card counts. Unknown states, paused agents and input/approval requests remain visible. The **Plan & agents** inspector counts the full reported roster (active/total) but keeps only working agents, those waiting for an answer and the one open in Activity in view; the others fold behind **Finished: N** and unfold 50 at a time, so a session with many subagents renders and scrolls a bounded list (owner, 2026-11-08, T-ug5hxx). Each session starts folded. `client/scripts/inspector-scroll-smoke.html` measures that scroll in WebKitGTK under a private Xvfb. An open child's Activity and draft stay in place when its turn finishes. A child's draft keeps its row visible after returning to main Activity. Finished turns are not proof that the agent's task or process has ended. Cross-provider children (for example, Codex launched from Claude) bind their original PID and native birth identity to the parent's run and conversation at the verified hook caller. If that original exits without a completion event, the child shows **Ended** or **Unknown**, never **Working**. Missing or unreadable process identity remains unknown. Explicit pending input/approval stays visible: process uncertainty suppresses Working, not attention. Neither a recycled PID nor an old journal start establishes current work. Recorded native jobs of such a child become unknown unless their own separately verified original process is still live. Other confirmed live jobs keep their ordinary **Background** status. Offline and historical rows establish no current work. Process observations do not invent a Stop, successful result, unread reply, or native execution permission. `hgs [@host] subagent retire SESSION --json` explicitly retires one stale child record without starting, stopping or messaging its agent. Inspect the current parent and child first, then submit an exact-generation request: ```sh hgs subagent retire claude/example/review --json <<'JSON' {"request_id":"11111111-1111-4111-8111-111111111111","expected_run_id":"22222222-2222-4222-8222-222222222222","expected_conversation_id":"33333333-3333-4333-8333-333333333333","agent_id":"external:codex:44444444-4444-4444-8444-444444444444","expected_updated":1700000000.5} JSON ``` The command refuses a verified live original, current native-child work, changed run/conversation/child timestamp, or a profile group. An unbound legacy or unavailable identity can be retired explicitly as record housekeeping, not as proof of process exit or successful completion. Requests are at most 8 KiB, the selected manifest read is capped at 16 MiB, the writer-lock admission waits at most two seconds, and the parent keeps at most 64 immutable retirement receipts. Repeating the same UUID and payload reads its original receipt; it never retires a later start. A fresh verified SessionStart may resume that child. An intermediate hook can also recover a mistaken retirement when its native caller verifies the same original process, or binds a previously unbound legacy record. A different recorded birth still requires a fresh SessionStart. Process checking admits at most 64 external identities per read; excess or unverifiable entries remain unknown. Older peers require the `subagent-retire-v1` help capability and refuse this command until updated. Claude child tracking reconciles hooks with exact native history, including workflow children. A final assistant `end_turn`, a successful `toolEndsTurn` result bound to its exact owned tool call, or a final **Request interrupted by user** row can settle a turn even when `SubagentStop` is missing. Its **for tool use** variant settles only when it follows the owned error results of the stopped calls; an unbound marker changes nothing. A tool-use interruption that an earlier hgs version recorded as new child work settles from the same native row unless a newer hook arrived. Matching workflow `started`/`result` attempts independently confirm the same reply. Later native child activity can recover a missing start; newer hooks take precedence. Silence and a completed parent never prove child completion. Reconciliation preserves existing reply and read identities. `hgs inspect` reports each child's `tracking_evidence`: source, event kind, event time, native row identity and, when verified, workflow result confirmation. Missing, partial or ambiguous native evidence leaves the last reported state intact. Codex child tracking verifies the child and parent IDs in the account-owned rollout, then reconciles typed turn starts, successful completions and explicit interruptions. An interruption without a turn ID requires a matching start in the bounded native history. Kimi's version 2 session catalog identifies direct children individually, including several children using the same profile; their own wire turn events establish current work or completion. Older, delayed or ambiguous catalogs retain profile-hook counts. A removed catalog entry becomes unknown rather than a fabricated completed result. DeepSeek uses each child's exact native API entry within one host generation. A child never inherits its parent's running status. Missing, contradictory or cross-generation observations remain unknown; desktop and Android counters retain the `+` uncertainty marker. OpenCode child sessions are not shown in this version ([OpenCode controls](opencode.md#controls-and-limits)). Inspection reports native tracking evidence without changing reply/read identities or restarting agents. **Fork session…** creates an independent native conversation in the same folder, next to the original session in its group. Files remain shared. The CLI is `hgs [@host] fork SESSION [-n NAME] [-d] [--archive ID]`; support depends on the agent. Kimi's external Fork requires its source instance to be closed, even when the session is Ready. Live Kimi sessions show Fork disabled with a reason to pause or close the source first. Pause is a separate explicit action; Fork never pauses the source automatically. Confirmed paused, saved and archived Kimi sources can still fork their saved context. DeepSeek uses the native fork of a supported resident host ([DeepSeek](#deepseek)). A session name is a label: an archived session never blocks a new session or a fork from its name. Without `-n` the fork is named `TAG-fork`; a name a live or saved session already uses gets the first free `-2`, `-3`… instead of failing, with or without `-n`. The fork dialog shows the name the fork will get, and the new session is recognized by its fork parent, never by a name another session took meanwhile. Inspection reports `fork_parent_id` and `fork_source_name` as null for a session that is not a fork; only an hgs that predates these fields is trusted for the exact name. A failed inspection never adopts a session and is retried, at most three times, as the list changes. A fork the desktop has not recognized within two minutes is reported as not confirmed and Fork is available again; the session may still be starting. An hgs older than this behaviour still refuses a name that only an archived session holds; update that computer or choose another name. A fork starts in its source session's project, including a fork of an archived session. Once the fork's binding exists, the CLI writes that membership through the same catalog owner as other project changes, for the desktop action, `hgs fork` and DeepSeek forks alike, and never moves other rows. A source in Inbox, in a project that no longer exists or with an unresolved project choice gives the fork an explicit Inbox membership. A source without a membership leaves the fork without one, so both follow the same default project. A fork name that already has a membership keeps it. Without a catalog, or if the catalog stays busy for 3 seconds, the fork still starts in the default project. That wait happens after the fork's binding is saved, without holding the session state or DeepSeek binding locks, and the membership is written only while the fork's binding is still the same run and conversation. The desktop then places the fork right after its original and opens it, once its inspection names the source conversation as its parent, even before a Codex fork has a conversation ID of its own. With an hgs that predates the parent field it waits for that ID. A fork's Activity first shows the history it began from, read-only: each source session's rows up to the moment of the fork, under an "Inherited from" label naming that session, then a "Forked here" marker and the fork's own activity. A fork records its sources when it starts (up to four forks back, so a fork of a fork shows both); a fork made before this records nothing, so its first inspection finds its source's rows up to its creation time and before its own first row, and saves that. Each Activity page reads at most one page from each of these ranges, however long a source is. Inherited rows are muted and never act as the fork's own: they open no attachments, and search finds them only in their source. A provider that copies the history into the fork's own transcript adds nothing twice, because the fork's messages dated before its creation are not shown. The source session is never changed. Rows the journal no longer keeps are not shown. The phone history (`hgs history`) shows the same inherited rows as additive `Inherited` rows that never count as unread; see `services/mobile/README.md`. Codex may defer `SessionStart` until the fork's first message. Activity enables Send once Zerus verifies that the supervised process owns an independent child history linked to the source conversation and its native composer is ready. The child ID is confirmed by the agent's own event; the source session stays intact. On Windows, verification searches only the selected account's history and requires the same supervised process to hold exactly one matching child history open. Incomplete, unreadable, ambiguous or exhausted verification keeps Send unavailable. ### Keep cache warm A session can keep its agent's provider prompt cache warm for 1 to 7 hours or always, so the next message after a pause reads the cached conversation instead of rebuilding it. It is off by default and lives with the session on the computer that runs the agent, so every desktop and phone sees the same setting. While it is on, the [recovery worker](#automatic-recovery) on that computer sends the idle agent one short message, exactly `[Zerus keep-warm] Reply with exactly OK and do nothing else.`, at 80% of the cache lifetime after the last turn ended: 48 minutes for a 1-hour cache and 24 minutes for a 30-minute cache. The margin keeps pings ahead of Claude Code's own idle compaction at 90% of the TTL. A ping only extends a warm cache: when a window was missed (the computer slept, the agent stayed busy until expiry) or the cache is within 30 seconds of its estimated expiry, nothing is sent and keep-warm resumes after the next real turn. The cache clock belongs to the current conversation: after **Clear** the setting stays on, and the first ping waits for a finished turn of the new conversation. The deadline is on the agent computer's clock; at the deadline the worker turns the setting off. A rename, including a legacy-label rename, keeps the setting. | Agent | Lifetime used | Offered | |---|---|---| | Claude Code | the TTL its last request wrote in native usage: 1 hour on a subscription within its usage, 5 minutes on an API key or usage credits | 1 hour only | | Codex | OpenAI's 30-minute default for GPT-5.6 and later; Codex sends no TTL | GPT-5.6 and later | | Kimi Code | Kimi Code's own `estimated_cache_duration` (60 minutes for `kimi-for-coding`, 30 minutes for `k3` models), read from its home | models with at least 15 minutes | | DeepSeek, OpenCode | DeepSeek's disk cache lasts hours without pings; others report none | no | Shorter caches are not offered: a 5-minute cache would need about 15 pings an hour, each a cached read of the whole context, costing about as much as rebuilding the cache once. Claude Code's `CLAUDE_CODE_PROMPT_CACHE_TTL=1h` or `promptCacheTtl` setting requests the 1-hour cache on API-key accounts at a 2x write price. Each ping uses the account's usage: a cached read of the whole context plus about 40 new tokens, which stay in the conversation. A ping goes only to the exact verified, live agent process with the expected run and conversation when it is settled: no turn, tool or child is running, no live background or scheduled job, no automatic recovery episode, no unconfirmed or queued input, no pending launch message, question, approval, trust, resume, usage-limit or cache-expiry choice, no pending model or effort setting, an empty recognized composer, no terminal input in the last two minutes (a terminal that cannot report input times must have no attached client; unknown activity never admits a ping), and the session is not paused, archived or terminated. The last check before the first typed byte repeats these rules and the 30-second cache margin, so a slow stage never types into a cold cache. It uses the guarded send path with its own origin and request ID, bound to the setting revision it was decided for (a change in between cancels it): a refusal before any input waits for the next round, and an unknown delivery is never sent again; keep-warm then waits for the next real turn. Rounds run every 15 seconds and never overlap, so two desktops or a manual `hgs recovery tick` cannot send two pings for one window. A ping is not the person's message. Its prompt is journaled with `origin: "keep_warm"` and every event of its turn with `turn_origin: "keep_warm"`. Its Stop is never the session's reply, so it adds no unread badge, notification or read-mark change; listings and search keep the previous prompt, last message and last event time. A message the person sends or queues while a ping is being typed or running makes that turn theirs; the ping's own prompt arriving later is then shown as ordinary text. A ping turn that fails, for example on a usage limit, never starts automatic recovery, even when an earlier finished recovery episode is kept: keep-warm stops until the next real turn, and the provider failure stays visible as usual. In the desktop app, **Details** shows **Keep cache warm** in the **Session** card of every live, paused or stopped session. Its switch (accessible name "Keep cache warm") turns it on for the chosen duration; while it is on, a slider picks 1 to 7 hours or Always (its last position, shown as an infinity sign in a fixed-width value so the slider never moves; its accessible value is "Always") and the row shows the remaining time, such as **2 h 14 m left**, and what keep-warm is doing: the next ping, **Warming the cache now**, a cold cache or the host's reason. Its tooltip states the cache lifetime and its source, the ping interval, the pings per hour and that each ping is a cached read of the whole context. A change shows at once and the controls stay enabled and in place while the computer confirms it; a choice made meanwhile is sent next with the confirmed revision (the newest one wins), and a refusal returns the row to the confirmed state. The slider rounds the time left up to whole hours but ignores the first five minutes past an hour, so a fresh choice keeps its position although the host's clock may run slightly ahead. When the agent or account is not eligible the switch is disabled and the host's reason is shown under it; a computer whose `hgs` lacks `session-keep-warm-v1` shows an update hint. While it is on, the session header also shows it on its chip row beside the model: a bolt with the time left, such as **2 h 14 m**, or an infinity sign for Always, at the chip row's height so the header never grows. Its tooltip gives the same state and lines as the Details row, and a click opens **Details** at the control. It reads only the listing, the followed session's Details summary and a change confirmed in this window. While a ping runs, the session reads **Ready** with **Warming cache** and counts in neither Active nor Working. Activity folds the ping, its reply and its Stop into one dim **Cache kept warm** row that expands to show both. Android follows the same status rule: while a ping runs the session reads **Warming cache**, is neither Working nor Active, and holds no reply in progress, so an earlier unread reply keeps its badge. The shared session-filter contract (`mobile/android/app/src/test/resources/session-filter-contract.json`) pins this for desktop core, the desktop frontend and Android. The phone's session Details show **Keep cache warm** read only (Off, On always, or the remaining time) and one status line: the next ping, **Warming the cache now**, a cold cache or the computer's reason, including why an agent is not eligible. Changing the setting from the phone needs a relay operation and is not available yet. ```sh hgs [@host] keep-warm SESSION --json ``` The request on standard input carries `expected_run_id`, `expected_conversation_id`, `expected_revision`, `enabled` and, when enabling, `hours` (1 to 7) or `always: true`. A stale identity, an older revision (`conflict`), more than 64 enabled sessions on one computer (`capacity`) or an ineligible agent (`unsupported`, with `reason`) are refused. Enabling starts the recovery worker as a policy change does. `hgs --help` lists `session-keep-warm-v1`; an older peer refuses the command. Listing rows carry `keep_warm: {enabled, until, revision, state, next_at, reason, turn_active}`; `until` is null for Always and `state` is `off`, `waiting`, `warming`, `cold`, `uncertain`, `stopped`, `paused` or `unsupported`. `inspect` and the command response add `supported`, `reason_code`, `ttl_seconds`, `ttl_source` (`native_usage`, `provider_default`, `kimi_config`, `kimi_table`), `interval_seconds` and `cache_expires_at`. The setting is `keep-warm.json` in the state directory, keyed only by session IDs or label keys; the worker's state of each session is under `recovery/keep-warm/`. Both are read as bounded regular files: a special file is refused without blocking, and a worker state that is unreadable or not one the worker writes holds keep-warm as uncertain until the next real turn. A legacy-label rename carries the worker state before the setting, stops when it cannot tell whether a state exists (permission denied is not absence), and repairs an interrupted move when the rename resumes. A session record that exists but cannot be read skips the round; only a session that is gone turns the setting off, and turning it off keeps an uncertain-delivery fence. See the [design note](superpowers/specs/2026-11-07-keep-cache-warm-design.md). ## Projects and P2P synchronization A project has a stable ID, name, color, folders on multiple computers and session membership. Drag sessions between projects without moving folders or replacing agent processes. Drag headers, use the context menu or Alt-Up/Down to reorder projects. The project order is shared: every computer in the swarm and the Android app show the same order, and the latest change from any desktop replaces the others without a review. Until someone reorders, each desktop keeps its own order and Android lists projects by ID. Empty-project visibility, collapse state, session order within a project and default project are local. **All swarm projects** explicitly shows the full shared catalog. A newly discovered session appears in the local default project until a shared assignment arrives. Discovery alone does not publish that fallback as a project assignment, so another desktop can launch the session into its chosen project without racing an automatic Inbox assignment. Launching or explicitly moving a session publishes its project choice, including a deliberate move to Inbox. Update the desktops that observe sessions to receive this behavior; existing catalog assignments and unresolved conflicts remain available for review. When ID grouping is available, it uses a separate bounded causal membership record for each computer and session ID. Explicit unassignment and conflicting project choices are records, not permission to fall back to a shared label. Distinct concurrent project choices stay reviewable; a later explicit choice consumes the observed heads. Only peers advertising `session_id_memberships_v1` exchange these records. Older builds preserve the separate file and keep their existing name/twin protocol, but cannot change ID grouping. Folder entries contain a machine, path and optional label. Browse works for local and remote folders, including ordinary non-Git directories. The desktop folder browser offers **New folder** on the selected remote computer. Enter only the child folder name directly in the list and press **Create** or Enter; Escape cancels the inline entry. The list context menu and Ctrl+Shift+N (Command+Shift+N on macOS) open the same entry. The **Dialog…** button beside **New folder** opens a separate name-only dialog with the parent shown above it. A missing path entered in the browser supplies that form's parent and initial name; the parent must already exist. Once creation is confirmed, choose **Use this folder** to select it for the project or session. Browsing and cancelling the creation form do not create anything, and existing paths are never replaced. This requires an updated `hgs` on the selected computer; older peers can still browse existing folders. If creation cannot be confirmed, the browser checks that exact path without repeating creation. An available folder can be selected immediately, including an empty folder or one that already existed; an unsuccessful check retains the creation error and **Go** remains available. Creating a folder does not initialize Git or start an agent. The CLI equivalent is `hgs [@host] dirs --create [--request-id UUID]`. It creates one directory and returns the canonical path plus the exact request identity as JSON. It never creates missing parents or repeats an uncertain operation. Local creation rejects `--dry-run`; remote dry runs only print the transport command. `hgs [@host] path-info --path ` answers whether a path exists on that computer, with one metadata read: no content is read and nothing changes. The path is absolute (a Windows drive or UNC path on Windows) or starts with `~/` for the home folder. The reply is one line of JSON, versioned and closed: `{"schema": 1, "exists": true, "kind": "file", "size": 1234}`, where `kind` is `file`, `directory` or `other` and `size` is given for a file only. A path that does not exist reads `exists: false`; one this account cannot inspect reads `exists: null`, with `kind` and `size` null. A relative path or one with control characters exits 1; a malformed call exits 2. A peer call runs only when the peer's `hgs --help` names the command, as an older hgs would read an unknown command as a session launch; the path's `~` reaches the peer's hgs as written. The desktop folder list starts in alphabetical name order, ignoring case; column headings change the sort. Sorting preserves the selected folder and does not reorder the shared catalog. The divider below the list adjusts the folder/worktree heights and remembers that choice locally; additional window height goes to the folders. Worktree actions share its heading row, leaving more space for the folder list. Right-click a folder and choose **Move to** or **Copy to**, then the destination project. Move transfers its catalog link; Copy keeps the original and adds a link to the other project. The computer, path and label are preserved, including for offline computers. If the destination already has that folder, its existing link is reused. Files and session project assignments stay in place. These catalog changes use the normal Swarm synchronization. An untouched **Inbox** selection in New session follows an unambiguous project whose folder is confirmed on the selected computer. Desktop, Android and iOS use exact canonical folder membership or a complete, current worktree catalog; folder names and path prefixes do not assign projects. Explicit project choices, including explicitly choosing Inbox, win. Multiple matching projects or missing verification keep the current selection. An untouched Inbox stays a local fallback, so later native project discovery cannot be overwritten by launch bookkeeping. Older saved desktop launch intents retain their original placement semantics. Desktop also checks existing saved folders on that exact computer against the CLI-confirmed canonical path, including local Windows drive and UNC folders that remain outside the POSIX shared catalog. It does not resolve saved aliases or infer from a parent folder. A native project hint must name the same known Swarm catalog; a foreign hint never selects a same-ID local project. A new tracked CLI session also infers its initial project from that computer's existing catalog; resume, adoption, manual assignments and explicit unassignment are never reassigned. A fork takes its source's project instead ([Fork session…](#fork-session)). This optional metadata step does not initialize a catalog, join a swarm or create a repository. A new session that a live tracked agent on the same computer launches (its parent link proven from process ancestry) starts in that parent's project, for Claude, Codex, Kimi, DeepSeek and OpenCode alike. The parent's project wins over folder inference, so a session tree stays together. A parent whose project no longer exists gives the child an explicit Inbox membership. A parent in Inbox, without a membership or with an unresolved project choice leaves the child to folder inference, as does a claimed, adopted or forwarded parent. The membership is first attempted after the child's binding is saved, retrying a busy catalog for up to 3 seconds without holding the session state or provider binding locks. Creation also durably records an initial-placement intent, including the session ID, run and original parent link. If that first attempt cannot finish, this computer's catalog worker retries the pending queue in bounded batches. Folder inference for a new session uses the same queue. Only the exact unchanged creation binding can complete its intent; an ended or replaced run is retired. Any ID or label membership written meanwhile, including an explicit unassignment, wins and cancels the intent. Existing sessions, including children placed before this rule, are never backfilled by listing, adoption or the worker. If the intent cannot be recorded, launch continues with one warning and the ordinary first placement attempt. A placement queue error never stops catalog sync, task cutover or label refresh in the worker. The general **New session** action inherits the selected session's project, computer and matching project folder. For a linked worktree, a verified catalog selects the main checkout instead. Choosing another folder, project or computer cancels this automatic selection; explicit folder and worktree launch actions keep their requested path. Project switches in **New session** keep the machine and select that project's folder. Only a path explicitly chosen through **Browse…** stays pinned per machine within that dialog; closing it clears this temporary choice. Selecting a listed folder unpins it. A folder outside the project shows a warning and is added only after a successful launch with the matching launch ID. Cancellation and launch failure add nothing. A worktree of a project folder on that computer is not outside the project, so starting there adds no folder; **Choose existing…** offers it again. When an automatic worktree is generated from an outside folder, the session starts in the worktree and the outside folder, not the worktree, joins the project. New launches immediately show **Starting…** until the matching session appears. Controls stay disabled before confirmation. Errors remove the placeholder and show a reason; **Hide launch status** hides it while preserving a late session's project placement. A session that ends before it appears and leaves no record, such as an agent that cannot start after the launch reported it started, also removes the placeholder: a notice shows its exit code and last lines, as its computer reports them in `ended_launches` ([JSON and external clients](#json-and-external-clients)), and stays when the launch command reports afterwards; a hidden launch status ends silently but still shows a later launch error. Existing names and unrelated sessions are never repurposed. On Unix, agent launch and resume use explicit POSIX or fish argument syntax for known login shells. Other configured shell types use `/bin/sh -lc`, with the inherited environment and POSIX login profile; their own rc files are not loaded or interpreted as another language. tmux executes the argument vector directly, including on computers whose default shell is not POSIX. Account selection and agent hints are reapplied after shell startup. **Open terminal window** is off by default and remembered separately from the tray open mode; DeepSeek uses its embedded native interface. To join a swarm, configure SSH access and open Zerus on the initial machines so existing projects import once. Projects shows **Connect project catalogs…** when an accessible computer has no project-sync connection. Session access over SSH alone does not connect project catalogs: the guide opens **Connect computer** with the missing computer selected. Choose **Preview connection**, review project mapping and **Join and merge projects**. Nothing is paired or joined by opening the page. The same flow remains under **Projects → Swarm… → Connect computer**. Names alone do not merge projects. Existing swarm membership wins by default; turn off that preference to compare conflicting assignments. HGS backs up the catalog before a merge. **Connect this member** adds a route to an existing member. There is no permanent leader: each member stores the shared catalog and can relay changes. One configured SSH connection is enough for exchange in both directions; the other side needs no reverse SSH connection. Learning a machine ID through the catalog does not create local transport access to it. Shared fields are machine IDs/names, project IDs/names/colors, folder locations, session membership and the phone notification timing. SSH hosts, users, ports, keys, proxies, credentials, transport bindings, local order, filters, collapse/appearance and the default project stay local. File contents and agent history are not copied. Offline hosts do not hide projects with locally configured access. The catalog and local bindings live in `~/.config/hgs/swarm/catalog.json`; do not copy that complete file between machines because it contains node identity and local transport bindings. `hgs swarm export` exports only shared fields. Original Zerus settings stay in `workspace/organizationBeforeSwarm`; import/merge backups use `~/.config/hgs/swarm/backup-*.json`. A session's project is shared by its label and, since zerus-ucck P2c, also by its durable session ID. Every writer of a membership on the session's own computer, `swarm apply` included, adds an ID twin: the session ID and the exact label membership operation it mirrors. Twins live beside the catalog in `swarm/session-id-twins.json`, never in `catalog.json`, so an older hgs on the same computer, and every peer that does not list the `session_id` kind, never reads one; only members that list the kind exchange them. `swarm get` lists the ID form as `projects[].session_ids` ("machine\nsession ID") only while the operation a twin mirrors is still the selected label membership, so any later move by label, from any hgs or desktop, hides it. `swarm get` also reports `membership_by_id {ready, missing}`. It is ready when primary data is available and every machine of the catalog is this computer or a peer whose last verified hello listed `session_id_memberships_v1`. The older `session_id` twins capability alone is insufficient. Primary-capability observations are node-bound and kept separately in the bounded `swarm/session-id-membership-peers.json`; existing twins observations never initialize that evidence. Desktops and the Rust mobile connector read the ID form only when it is ready. The connector keeps sessions with the same label separate by ID; a missing or invalid session ID never falls back to that label's project. With a legacy catalog, only unique labels receive label-based membership; twins stay unassigned rather than sharing a guessed project. The label form is still written for compatibility. `swarm export --kinds` takes the kinds its requester parses on stdin; without them it exports only the kinds hgs v0.47.0 parses. Primary project placement is stored separately in the bounded causal `swarm/session-id-memberships.json`, exchanged only with peers advertising `session_id_memberships_v1`. It preserves concurrent concrete placements for review; a concrete project beats concurrent default placement, and a later explicit Inbox/unassignment wins. Valid twins are migrated under the catalog lock without replacing an existing ID record. An exact primary null/conflict means unassigned; only an absent ID record allows name membership fallback. Unreadable primary data stays unavailable and is not repaired automatically. Older builds preserve this file but cannot edit its ID grouping. Native project queries and assignments for a verified legacy record without a session ID continue through the name catalog when primary data is unavailable. An ID-bearing native record still requires primary evidence, including when a request omits its session ID. Missing, null and empty ID fields retain legacy behavior; malformed native IDs refuse. Legacy operations leave unavailable primary data untouched. The `session-labels-v1` transition gate requires fresh positives from this computer, every configured peer and every catalog machine. An unaddressed, unknown or unreachable member keeps it closed. `hgs swarm session-labels-gate --json` reads the bounded ten-minute cache without starting a worker or making connections. Each hello retires the previous observation; ordinary hello never waits for a connector, and the existing sync worker performs that bounded query separately. The answering CLI must report both ID membership readiness and its complete ID routing capability; the earlier observation-only build cannot open the gate. Configuration, route, membership or connector changes invalidate the answer. The cache grants no native authority and never weakens exact selector, original receipt or no-replay checks. While the gate is open, `hgs reference`, `hgs self` and sender envelopes include the stored canonical session ID. Older parsers continue to receive the earlier reference form while it is closed. This capability leaf does not yet enable new duplicate-label writers. The session-label transition gate's supported connector inventory consists of the maintained installer's connector using the canonical mobile configuration (`core::mobile::config_path()`). On Linux its user unit is `zerus-mobile-connector.service`; other platforms include an equivalent only where their installer creates one. An existing configuration or installer unit requires a fresh positive capability reply from the actual running connector, bound to its generation, configuration and machine. An installed executable's help cannot substitute for that reply; an old or absent responder keeps the gate closed. With neither the canonical configuration nor an installer unit, the node has no supported connector. Hand-started connectors with custom configuration paths and legacy services outside the installer must be stopped or upgraded before labels repeat. They are not inferred from process names. Deploying a live connector remains an explicit owner-approved operation. On a computer without a Qt settings store, the first `hgs swarm get` or initial `organization` watch subscription may initialize an empty catalog. It derives no projects, folder links or session assignments from names. The client still sends only explicit edits; placement and concurrent field versions stay in hgs and the replica. An existing uninitialized catalog may also bootstrap; every existing operation, peer, binding and machine-name entry is preserved. Steady-state organization watch reads remain lock-free and do not save. Only the first read of an explicit organization subscription may try the bootstrap; a present or undecidable Qt probe is retried only on a new subscription. The presence check is conservative and never parses Qt settings. Any existing, malformed, unreadable or unexpected store counts as possibly holding an organization, as does a probe error. The locations are `$XDG_CONFIG_HOME/hgdev/hgs-tray.conf` (default `~/.config`) on Linux, `%APPDATA%/hgdev/hgs-tray.ini` on Windows, and `~/Library/Preferences/com.hgdev.hgs-tray.plist` on macOS. Zerus.app retains that macOS preferences domain after switching clients. A computer with such a store keeps the existing Qt import path; neither trigger bootstraps it or writes a pending-import marker. Watch hello still obtains its stable machine identity and may create an uninitialized catalog before the organization subscription. `hgs swarm get` keeps its ordinary locked load and save, including self bindings, the machine-name refresh and a stable persisted node identity even when a Qt store exists and the catalog is still uninitialized. The bootstrap is the only new behavior, evaluated under that same lock when `imported` is false and Qt settings are definitely absent. Get and the initial organization subscription share this idempotent operation, so concurrent first reads initialize once. An automatic bootstrap writes a node-bound `gui-import-pending.json` beside the catalog before saving the legacy `imported` flag. A later Qt first start, using the current hgs, can still call `swarm initialize` to import its local organization. While that marker is pending, initialize fills only missing fields, preserving existing values, deletions and concurrent versions. It saves the catalog before clearing the marker, so a crash can safely retry that missing-field import. An already imported catalog without a matching marker keeps the existing initialize no-op. The catalog and peer wire formats are unchanged; older hgs versions can read the catalog but do not perform the pending GUI import. Qt's settings store is never changed by the bootstrap or import. A desktop whose saved Qt organization cannot be read, while Qt's store is present, runs the same bootstrap through `hgs swarm initialize --g3-bootstrap --json` with stdin `{"version":1,"expected_node_id":NODE}`. It refuses another node and a foreign or unreadable marker, leaves an initialized catalog as it is, and reports `g3_bootstrap` in the returned snapshot. Projects are then usable, the desktop keeps showing the refusal, and a later readable organization still fills only missing fields. A Qt store read completely without a saved organization is a first use instead: the desktop imports the default project through `--g3`, as for an absent store. An unreadable, malformed or unsupported pending marker prevents bootstrap but does not fail get or the initial organization read: they return the existing uninitialized state and leave the marker untouched. A stderr note is emitted once per process. Explicit initialize still refuses that unknown import state. The independent `hgs-swarm` service (`com.hgdev.hgs-swarm` on macOS) makes no network requests without members. Local changes normally trigger exchange within three seconds; unchanged peers are checked every 30 seconds, backing off to five minutes on failure. Zerus reads the local catalog every five seconds without SSH. Offline members catch up later. Independent fields merge; conflicts remain in the Swarm review UI. A session's missing/Inbox placement is a fallback: a concurrent choice of one known live concrete project wins without review, and identical concrete choices coalesce. A newer explicit move to Inbox or unassignment still wins by causal identity. Different concrete projects and unknown/deleted project targets remain reviewable; project mappings are applied before join comparisons. Local passive observations never publish membership, including during import. All underlying versions are retained, so the next explicit choice consumes every observed candidate. Project/folder deletion records still prevent resurrection; this version does not prune old journal records. The worker records its version and process in `~/.config/hgs/swarm/worker.json` and exits when an upgrade replaces its executable, so `Restart=always` or launchd `KeepAlive` starts the new version. A worker started before this mechanism keeps running after an upgrade and cannot read a catalog that holds the phone notification timing. `hgs swarm get`, `preference`, `sync`, `join` and inbound `exchange` restart such a worker, or one from an older version: `systemctl --user try-restart hgs-swarm.service`, or `launchctl kickstart -k gui/$UID/com.hgdev.hgs-swarm` on macOS. They try at most once every ten minutes and only for the default configuration directory, never under `HGS_CONFIG_DIR`, and never touch agents, tmux servers, DeepSeek hosts or `hgs-recovery`. `hgs swarm get` reports `worker: {running, current}`; when a running worker stays outdated, Settings → Mobile connection asks you to restart the sync service. Windows has no service manager for the worker; the desktop app runs it there ([Windows](#windows)). **Swarm → Conflicts** explains the affected session, archived session, project or folder. Compare the values and the computers that saved them: projects, project names and colors appear as the project labels and computers as the machine badges used elsewhere, with **this computer** beside this desktop's badge. A computer the catalog does not list stays text with its identifier. **Shown now** marks the temporary display choice; it does not mean the conflict has been resolved. Select a row to preview the result, then use **Keep this project** or the matching action. Project assignments change catalog placement without restarting agents or removing conversations. Folder/project removals affect the shared catalog, leave files and sessions intact, and require confirmation. The decision is shared with connected computers and reaches offline members when they reconnect. Closing the window postpones the decision. New conflicting versions clear the selection and require another review, including if they arrive during a confirmation. ```sh hgs swarm get hgs swarm preview mac hgs swarm sync hgs swarm disconnect mac ``` Disconnect stops outbound exchange through that connection while retaining the catalog and session access. It does not deny inbound exchange from an existing member; SSH controls transport access. `HGS_SWARM_SERVICE=0 ./install.sh` skips worker installation. ### Empty-peer adoption `hgs swarm adoption-preview PEER --json` checks whether the configured empty computer can adopt the local catalog without opening its desktop UI. The destination accepts either an untouched store (`imported=false`, no operations or pending marker) or the narrow first-read bootstrap: a valid same-node v1 `gui-import-pending.json`, only the current self machine-name operation, the initial empty-peer membership and empty/missing sidecars. Peers, other product history, foreign or unreadable data, an existing drive store, or a present/unreadable Qt store refuses. The pending marker is preserved byte for byte, and the later missing-only GUI import retains adopted values, tombstones and concurrent heads. `hgs swarm adopt PEER --json` performs the explicitly previewed original request. It copies the complete catalog, primary session memberships and twins, including every raw operation and parent. Canonical full-body hashes are bound to raw file presence (`missing`, `valid_empty` or `nonempty`), swarm identity and pre/post receipts. An absent file's zero bytes are not a valid empty JSON component. The aggregate request is at most 32 MiB including every component; preview, status and mutation receipts are at most 64 KiB. Disk read ceilings do not widen wire limits. Journals and the registry are bounded and directly indexed by original UUID; one adoption is active per catalog. The destination keeps its own node and self bindings and gets no reverse peer or source-local binding. Only the source adds the configured destination peer and calls `sync_peer` for that peer, preserving existing peers and unrelated synchronization. Without real reverse enrollment, drive-folder import remains unsupported and the drive component stays `Uninitialized`; preview and settlement disclose this rather than claiming every component is shared. `hgs swarm adoption-status PEER --json` returns the bounded original phase and receipts without repairing anything. Main, primary and twins commit separately under the destination catalog lock, with write-ahead phases and fresh-read receipts. The durable `adoption-pending.json` guard blocks capable ordinary loaders and savers after every partial phase, including before directory/lock creation. It is removed with a parent barrier only after all components verify; `remote_committed` follows that removal. Ordinary loaders and savers also refuse a bounded registry whose role/phase pairs are invalid, whose unfinished request is not the active one, whose active entry is not in an active phase, or whose active request has no matching durable journal (one direct read by UUID). A crash or unknown result before the terminal receipt remains partial/unknown and read-only. The lock-free organization read and its watch keep showing the main catalog but add `adoption` (`state` `partial`, `pending` or `unknown`, `ordinary_writes`, original `request_id`, `role` and `phase`) whenever a guard exists or a request is active, and follow the guard and registry files; with neither, the projection is unchanged. Older binaries are not claimed to honor the guard. Exactly two continuations exist, and only within the original live CLI call: a durable original `refused_not_started` with zero product effects plus fresh identical proof, or a terminal `remote_committed` with an explicitly unstarted local source-membership phase. Both require the original native owner, request/body, configuration, source preimages, per-UUID lease, and actual child exit plus both physical pipe EOFs within the original 25-second deadline. A receipt, idle output, byte count, or serialized drain claim is not drain proof. A distinct or restarted CLI has only original-status and fully validated committed-receipt lookup; it cannot continue mutation. A lost reply, changed context, active or unknown writer, restarted owner, missing receipt, or stranded guard is `Partial`/`Unknown` and status-only. No new UUID, remote replay after an unknown result, duplicate cleanup, or third destination repair is permitted. The native dialog binds the original to independently observed Live machine cards for this computer and the destination (computer, host and machine UUID equal to the preview node) and refuses a stopped hub. It rechecks those cards, the original generation, configuration, ticket and resource custody at the queued invocation barrier, at each preflight result, at the mutation's drained result and before native settlement. A refusal is sticky: a restored card or configuration never revives that original. Its later review action is read-only, not another adoption call. Each original remote call keeps the same ssh child (and its Windows job), request writer and both pipe readers until they physically settle. After any failure the child may exit by itself until the original deadline; then only that owned child is stopped and its exit confirmed by wait. No process group, descendant or name-based kill is used, and a PID whose status is no longer trusted is never signalled. The CLI then waits for the writer and both pipe EOFs before it reports the call as unknown, so a descendant that still holds a pipe keeps the call, and its native accounting, retained. A call whose exit cannot be confirmed stays pinned and admits no other call in that process. The adoption ssh passes `-o ControlPath=none` ahead of the configured connection options, so a user's `ControlMaster`/`ControlPersist` setting cannot start a background mux master that inherits stderr. Its uncached remote-shell discovery probe does the same. Every other remote operation's discovery probe keeps the configured connection sharing unchanged. The desktop runs the call beside its organization worker: other organization work continues, the dialog can be closed and reopened onto the same original, and after the original deadline it reports that the original is still settling with an unknown result. Only new adoption actions wait, and no failure or timeout settles or replays it. The desktop runs only its three fixed adoption calls (`adoption-preview`, `adopt` and `adoption-status`) with the CLI as the leader of a private process group it creates for that one call; its local reads keep the ordinary runner. It observes the leader's exit with `waitid(WNOWAIT)`, so the unreaped leader pins the group, and only then, or on its own timeout, sends `SIGKILL` to that exact group and reaps the leader. It never signals after reaping, and a shared group, a process scan or a name or path match is never an authority to signal. So when anything kills the CLI, the original ssh and its in-group descendants (such as a ProxyCommand) are stopped and reaped before the dialog settles. The accounted resources stay held until the leader is reaped and both of its pipes reach EOF. The result stays unknown and status-only, the ticket stays held, and nothing is retried or continued. Windows keeps its per-child kill-on-close jobs. Processes that leave the group (setsid or a process group of their own) stay outside it and are never signalled by it. Two boundaries remain: if the desktop has crashed, a later kill of the CLI is not accounted by anyone; and after a desktop restart the dialog cannot reopen the original. It can still review it read-only: when the organization read discloses an adoption request and the dialog holds no original of its own, **Review original status** reads this computer's journal for that request (`hgs swarm adoption-status --json`) and, for a source original whose recorded peer is configured here, the destination's status. Nothing creates a ticket, continues the original or sends a mutation, and a mismatched request or an unconfigured peer refuses before any remote call. Adoption-specific raw JSON rejects duplicate object keys recursively before a typed map is constructed. The source catalog and sidecars must match their declared source and source-node machine operation. The original destination is validated independently against its own empty preimage, whose swarm may differ from the source. The complete main/primary/twins candidate, cross-component closure, aggregate operations, parent edges and encoded wire size are checked before any journal, guard or product effect. Primary counts come from the membership view validated with the main catalog's machine redirects, so a valid causal edge from an old machine key to its canonical child is accepted. Terminal and settlement receipts must match the full original request and all component preimages and postimages; a same-UUID or hash-shaped response is insufficient. `guard_cleared` is durable before `remote_committed`; a crash between them remains manual/status-only. ### Phone notification timing `hgs swarm preference get --json` prints `{"mobile_delivery": "away"}`; `hgs swarm preference set mobile_delivery away_10 --json` changes it for every member. Values are `immediate`, `away` (default), `away_5`, `away_10`, `away_15` and `away_30`. Concurrent changes settle on one value without a review; the next change from any computer or the phone replaces them. A machine joining a swarm adopts the swarm's existing choice. Without a swarm the local catalog keeps it the same way. Members running an older hgs keep synchronizing projects, folders and sessions but do not receive this choice or the shared project order (they keep their own order); Settings → Mobile connection names the computers this one synchronizes with directly until they are updated. A member reached only through another computer is named in Settings on the computer that connects to it. An older machine cannot preview or join a swarm whose catalog already contains the choice; update it first. An older member does not relay the choice either: a machine that synchronizes only through it receives the choice after that member is updated. Each synchronization with an older member exchanges the full inventory, because its catalog never matches a catalog that holds the choice. Once a delivery choice exists, an older hgs on the same machine cannot read the swarm catalog, and leaves it untouched, until hgs is updated again. ### Legacy CLI folder aliases `~/.config/hgs/projects.local` retains `NAME=FOLDER` aliases for CLI compatibility. The old infrastructure-owned `~/.config/hgs/projects` is no longer read. Aliases import into Zerus once per machine; later project edits belong in Projects. An alias whose folder that machine cannot take (not an absolute path in its form) starts no project. Projects names it, and the machine imports again at the next start of Zerus. ```sh hgs project ls --json hgs project add infra ~/work/infra hgs project set infra ~/work/other hgs project rm infra ``` Alias names reject spaces, `/` and `=`; logical project names are not restricted that way. Absolute paths remain available directly from the CLI. ### Cloning a repository In desktop **New session**, choose **Working folder** for an existing checkout or ordinary folder, or **Git repository** to prepare a new checkout. Project, computer, agent, account and session name stay in this one form. The Git source accepts an SSH or HTTPS URL from GitHub or another Git server. **Clone to** shows the suggested complete destination; edit it to rename the target folder or use **Browse…** to choose its parent. A manual destination stays when the URL changes. Parent folders are remembered separately for each computer. Switching sources keeps the shared controls and action buttons in place. Select an existing logical project, Inbox, or **New project…**, then use the single **Clone and start** action. Progress, access errors and recovery controls move to a selectable creation card in Sessions as soon as the form closes. Switching source modes or opening the form never starts a clone. **Projects → Clone repository…** offers standalone preparation without starting an agent. **Clone and start** checks the selected computer's installed CLI, Git, parent folder, destination and repository access before cloning. Access uses that computer's existing SSH configuration and Git credential helpers; passwords and tokens embedded in repository addresses are refused. Configure missing access on that computer, then try again. These checks run in the background and create no checkout. Cloning begins only after explicit confirmation. Existing destinations, including empty folders and symlinks, are preserved: choose another name or use **Browse…** to select an existing checkout. A confirmed clone joins the selected project even if the agent cannot start. Its confirmed project choice, including Inbox, takes precedence over automatic folder-based project detection. The normal **Auto** / **None** worktree choice applies to the new checkout. Failed launches retain the checkout for another session. Ordinary folders remain supported without Git initialization. Cloning has a ten-minute Git deadline and never automatically retries an uncertain operation. Private native receipts and local pending-request metadata retain the original identity across dialog or application restarts. **Check result** reads that original receipt; a recovered checkout requires explicit **Continue setup** on its creation card. Standalone preparation retains its **Use checkout** action. Failed or partial checkouts are kept for inspection. A timeout or lost connection is not permission to remove files or run the clone again. **Choose another destination…** leaves the original checkout and native receipt in place and lets you prepare a different clone. The CLI is `hgs [@host] repository check --url URL --parent PATH --name NAME --json`, followed by `repository clone` with the same fields and an explicit `--request-id UUID`. `hgs [@host] repository status --request-id UUID --json` reads its durable receipt. Reusing a request ID with identical fields returns the original result without repeating Git; different fields are refused. Remote acquisition requires the exact selected CLI's `repository-clone-v1` capability. Older peers continue to support ordinary folder selection. ### Session creation progress The final **Start session** / **Clone and start** action immediately publishes a selectable creation card and closes the form. An ordered background writer saves the captured choices before any clone, worktree or agent starts. The initial **Saving request…** stage is visible even while storage or the selected computer is slow. A save failure keeps the card and dispatches no next step. Select the card to see its current stage, elapsed time, bounded diagnostics and retained checkout/branch. Stages distinguish folder and repository checks, cloning, worktree creation, checkout verification, agent startup and confirmation of the real session. After 30 seconds without a stage update, the detail view explains that preparation is taking longer than usual. It never invents a percentage. Failed and uncertain creations remain available for review. Creation cards appear in All and Active, with separate creation counts and the same project, machine, account, folder and text scopes. The newly submitted card is temporarily revealed without changing those scopes; **Return to filters** ends that reveal. The clock button opens bounded pages of creation history, including hidden cards. **Hide status** changes presentation only. Moving to another conversation leaves preparation running and preserves its draft. **Stop creating** fences later preparation and launch. Modern worktree receipts can cancel only their own Git process group/job. Clone operations and older worktree helpers offer **Stop after preparation**. Files and branches are always kept. Once launch dispatch is reserved, check its result; use normal confirmed session termination after an actual session appears. When a worktree admission is refused, the card shows that refusal and its reason rather than treating it as a transport failure. A fresh attempt may reuse the creation's scheduling slot only after its exact predecessor failed without effects and all original resources drained; the old receipt remains available under its original request ID. For an older missing worktree request, **Stop creating** can durably fence further starts while leaving the earlier outcome unknown. The card says both facts, retains the original request and destination for review, and never offers **Continue setup** for that UUID. **Recreate…** opens separately reviewed choices for a new creation and new request; **Hide status** dismisses the card without erasing its retained result. Missing, replaced or unverifiable receipt storage still refuses a fence. A fence alone never proves that an earlier worker, checkout or native resource has settled. **Check result** observes the original clone/worktree request, reads the original service launch receipt, or refreshes session evidence. An unknown outcome never permits another creation command. After a restart, unfinished cards require explicit **Continue setup**; recovered preparation is revalidated before startup. A definitely ended startup can retry only startup with a new launch identity. **Edit choices** opens a reviewed new request while preserving the original attempt and resources. A failed repository verification after a successful worktree receipt keeps the already-created checkout, branch and original receipt. Its message distinguishes that read failure from creation failure. One bounded private `last_catalog_failure` records the read stage, sanitized state/detail and typed staleness, completeness and sample time (null means unavailable), and remains after later continuation. A catalog timeout does not establish repository corruption. **Continue setup** revalidates the retained checkout and can then start the session; it is not a read-only check and never repeats an unknown original effect. A matching service receipt with a fully drained, unsuccessful launch-command exit shows **Creation failed** and its reason. Its dispatched launch identity is kept: **Continue setup** never repeats it. **Edit choices** opens a separate, reviewed creation with a new identity. Missing, unreadable, mismatched or Unknown receipts stay **Creation result unknown**, with **Check result** and **Hide status**. Failure and unknown-result notices close on the normal toast timer; their full details remain on the creation card. A failure first read after opening the window stays quiet only if its last recorded state change predates this window's start, even when the creation itself is much older. Older cards without that timestamp use their creation time. Only the exact native launch identity, computer, name and agent replace a card with a real session. Command success alone remains **Confirming session…**; a late transport error cannot downgrade a proven session. Native early-exit evidence keeps its reason and bounded output in the creation card. Project placement still follows its existing acquisition/launch success boundary. When supported by the selected CLI, `dirs --creation` confirms its stable computer UUID. Subsequent preparation and launch commands use `--expect-machine UUID`; an SSH alias that now points to another computer fails before mutation. Older helpers keep one-shot preparation with conservative recovery. Creation has at most four active preparations and 32 unfinished requests; hidden resolved history is pruned locally, never unresolved requests. The private versioned journal is bounded to 128 records / 8 MiB. API v1 and mobile action journals retain their existing contracts. The native operation pins the parent and new destination through Git and checks their identities before accepting the result. Unix Git starts in the held destination directory, so replacing its pathname cannot redirect checkout writes. An unpredictable private staging folder is pinned before atomic publication of the destination name; its fallback `staging_path` is reserved in the receipt before creation. A failed publication can leave that staging folder for inspection. Windows creates and holds the new directory atomically and retains its ancestors without write/delete sharing; a conflicting handle or reparse point fails closed. Zerus never removes a replaced or partially populated directory. On Unix, a separate native worker owns Git's deadline and watches a wrapper-owned pipe. Ending the GUI/SSH wrapper closes that pipe and cancels the worker's own Git process group, including its descendants. The original receipt remains unconfirmed after abrupt wrapper termination; status and duplicate requests never restart the clone. Windows retains the existing kill-on-close job containment. The complete encoded receipt is limited to 16 KiB; large Git errors are truncated within that envelope, and status and duplicate requests return the same saved result. Local paths, including Windows drive, UNC and device paths, are refused. A single-letter SSH alias must use an explicit address such as `ssh://c/repo`. ### Worktrees and ordinary folders New session keeps **Auto** available when the selected computer confirms the working checkout, even if the repository has more checkouts than its bounded catalog can list. Missing, bare, stale or unconfirmed folders remain ineligible. Opening the form or choosing a folder creates no worktree; creation starts only after **Start session**. Session cards show a checkout line of the form `folder / branch`, such as `zerus / work-1a2b`, preceded by a small Git branch icon; **detached HEAD** replaces a missing branch. A linked worktree names its main checkout folder rather than its own generated folder. Ordinary folders without Git metadata show only their name, preceded by a folder icon. The opened session's header and **Details** show the same line, marked `· worktree` for a linked worktree; the full folder path stays in the header tooltip and **Details**. A running Codex session with pending optional questions, ones the agent keeps working without, shows an amber question-mark chip with their count (`99+` above 99) right after its status badge, or after a separate new-reply badge, on its Sessions and Overview cards; a collapsed strip tile shows a small amber `?` mark. Its tooltip and the card's accessible description say how many are waiting. The chip shares the amber of attention but never changes the session's status, the Needs attention filter, counters or badges, and it is hidden for paused, stopped, archived or offline sessions and while the count is unknown. Open the session to answer or skip the question in Activity. Existing Git worktrees appear in Projects and the session inspector. Clicking a checkout filters Sessions while preserving the open conversation and draft. In **New session**, **Auto** creates a generated `work-…` branch from `HEAD` and a sibling worktree when **Start session** is pressed, then starts there. Its path is shown before launch. Opening the form and checking folders never create anything. **None** starts directly in the selected working folder; ordinary non-Git folders use this mode and never initialize Git. The adjacent options menu offers **Choose existing…** and **Create manually…**. Choosing an existing checkout keeps its path, machine, project and account. Explicit worktree launch actions also use that checkout directly. Bare or unavailable copies cannot launch; ordinary Browse remains available even without Git or after metadata errors. The project gear opens folder configuration, and each agent choice includes its provider icon. The folder status area stays empty unless it has a warning or an error. **Create manually…** in this form, or **New worktree…** in Projects, lets you choose a new branch, base ref (default `HEAD`) and unused destination under an existing parent directory. The CLI is `hgs [@host] worktrees create --path /repo --branch feature/task --destination /repo-task --base HEAD --json`. Zerus also verifies `--common-dir` and a request ID. Creation uses normal `git worktree add -b`, including configured checkout hooks, with no force, fetch or deletion. The ref is resolved before creation. When the base is a local branch with a remote upstream, such as `HEAD` on `main` tracking `origin/main`, the new branch inherits that upstream so its session card can verify publication; Git's default `simple` push mode still refuses a bare `git push` to the differently named branch. Commits, tags, detached `HEAD`, local upstreams and `push.default=upstream` or `tracking` leave the new branch without an upstream. The five-minute operation can leave partial results after failure; inspect the destination before retrying. Stopping session preparation preserves the created folder and branch. Closing or archiving a session never removes them. Automatic creation requires a fresh verified repository on the selected computer. The creation card starts the agent only after its matching result and fresh checkout checks, and never repeats an unconfirmed request. Its destination remains available for inspection or an explicit direct-folder launch. The opt-in `worktrees create --receipt --request-id UUID` contract reserves a private original request before Git. Identical duplicates return that result; different arguments refuse. `worktrees status --request-id UUID --json` reads it, including fresh ownership verification for a created checkout. An interrupted reservation becomes unconfirmed and is never replayed. `worktrees cancel --request-id UUID --json` requests shutdown of that operation alone; a running receipt is not proof of exit. A final failed receipt with `effects_started:false` permits an explicit new attempt after checks. Failures after checkout begins keep the request and resources for inspection. Existing calls without `--receipt` and mobile API v1 remain compatible. Catalog reads are on demand, with a 30-second repository cache; `--refresh` bypasses it. Identity is machine plus canonical Git common directory, not equal paths or repository names. Limits are three seconds, 1 MiB of Git output and 512 worktrees. Errors distinguish `not_repo`, `git_unavailable`, `metadata_error`, `timeout`, `too_large` and `folder_unavailable`; previous data is explicitly stale. The UI caches at most 64 snapshots and 8 MiB. Cleanup is described in [the cleanup design](superpowers/specs/2026-10-10-worktree-cleanup-design.md). ### Cleaning up worktrees **Worktrees…** in the Projects heading opens a cleanup workspace across visible projects and computers. Repositories linked from several projects or subfolders appear once per computer; filters preserve exact project and machine identities. Four groups separate **Cleanup candidates**, **Review work**, **In use** and **Not checked**. Main checkouts and ordinary folders are hidden by default. Search, sort and refresh share one compact toolbar. **Filters** opens project, computer and state controls and the main-checkout toggle; its count shows active filters without taking height from the workspace. Folder names are emphasized, while a separate muted row with a Git branch icon identifies the branch. For a single-computer scope, the coverage line names that computer and the redundant computer column is hidden. Search matches folder, branch, project and related session names; sorting offers largest folders, oldest Git activity or folder names. Sizes are apparent file sizes, not a promise of physical disk space reclaimed; incomplete measurements are marked as lower bounds. Catalog reads run two at a time, and repository reviews run sequentially in the background. Coverage reports checked/known worktrees and incomplete catalogs. After the first bounded repository review, unchecked known rows are checked individually, including rows beyond the native 64-row review limit. Catalogs remain bounded at 512 entries; this is not a scan of every folder on a computer. Offline snapshots remain readable and selectable for review; removal stays unavailable until the owning computer supplies a fresh check. Browsing data is retained for one hour, across closing and reopening the manager. The coverage line shows when catalogs were updated; **Refresh** rereads them and clears the selected cleanup candidates. The open manager refreshes hourly, and worktree creation/removal invalidates the affected computer/repository cache. External Git changes can be picked up with **Refresh**. **Select candidates** uses checks less than five minutes old. Selecting rows is independent of deletion eligibility: Ctrl/Cmd-click, Shift-click and checkboxes select multiple folders in any group. **Review cleanup** always checks the selected targets afresh; native removal repeats those checks under the repository and session locks. A cached browsing verdict never authorizes deletion. Selecting a folder loads its files and commits after a short navigation debounce. The inspector distinguishes loading, an empty list and a failed read with retry. Its refresh button rereads the selected folder, including cached file previews. Changed/untracked file names, tracked diffs and up to 30 original commits absent from the base history are available. Inspection and file previews are cached in bounded application memory for an hour, never written to the settings file. The base comparison is a two-way diff and can include later changes on the base. **Local files** previews ignored entries and their contents; **Sessions** opens the exact related conversation on its owning computer. Reads are bounded (200 changed files or directory entries per page and 128 KiB per text preview), with truncation shown. **Browse all files** and **Next** continue beyond the largest ignored entries or the first directory page. Binary files are identified, and symlinks are not followed. Git refs are local snapshots; inspection never fetches. No-base and failed checks are reported explicitly. The inspector keeps its longer metadata under **Details**. Local file names use the available column width; browsing and pagination share one small navigation row. The empty text preview stays hidden until a file is opened, and both the file list and the opened preview keep usable, resizable space. Related sessions have session icons and retain their exact conversation targets. **Select candidates** selects only currently visible, verified cleanup candidates. Folders with local files outside Git require individual selection, even when Git reports them clean and merged. **Review cleanup** shows the exact selected folders across repositories and computers, branch handling and why any folder must stay. Folders outside the candidates group can be selected and removed too. Local data needs a separate explicit checkbox; deletion checks its reviewed metadata fingerprint again. A missing folder only loses its Git registration. After complete success the dialog closes and the overview shows the result. Partial results and errors remain open; uncertain replies are not replayed. **Stop after this folder** lets the current operation finish and leaves the remaining folders untouched. Folders a removal left behind (see partial removal below) appear first, in a separate **Partially removed** group shown only when there are any. A repository with partial-removal records is reviewed even when no linked worktree remains, and each computer's vanished-repository leftovers come from one bounded `hgs worktrees leftovers` call; there is no per-row call. These rows never join a cleanup selection. The panel shows the remaining size (a lower bound when the listing was incomplete), whether the branch is kept, moved or unchecked, why the removal stopped, and the sessions and programs that use the folder. It offers no file browsing. **Keep folder…** asks for a simple confirmation and forgets only the record. **Delete remaining files…** opens an explicit confirmation whose default focus is Cancel: it states that the files cannot be restored and that the branch is kept, and shows the unchecked **Delete even if some running programs cannot be checked** box only when the review offered that acceptance. Each confirmation sends the fingerprint of the review on screen exactly once. The outcome stays on the row until a fresh review: **Files deleted**, **Folder kept**, **Record already gone** (another action may have resolved it, so the row asks for a fresh review instead of claiming the files stayed), **Nothing changed** with the reason, or **Result unknown** with **Review again**. Nothing is retried automatically. A row whose repository is gone shows **Repository missing** and offers Keep folder only. Integration evidence distinguishes ancestor commits, identical file trees and cherry-pick-equivalent patches. Equivalent content is useful when reviewing squash/cherry-pick workflows, but only Git ancestry permits optional branch removal. Original branches otherwise remain available. Manual removal is explicit and is reviewed on the computer that owns the checkout. **Clean up…** in Projects or the session inspector lists the linked worktrees of the repository as **Ready** (preselected), **Review** (removable but with notes such as local ignored files, unmerged commits, archived sessions or activity in the last 24 hours), **Missing** (the folder is gone; only Git's record is forgotten) or **Blocked**. The button shows the number of ready and missing worktrees; that review runs at most every five minutes while the panel is visible and never removes anything. A worktree row's menu offers **Remove worktree…** or **Forget missing worktree…** for that checkout alone. A worktree is protected when it is the main checkout or bare, is locked, contains another worktree or Git repository, has initialized submodules, has a detached commit that no branch, tag or remote branch contains, or is used by a process of this user or by a running, paused or saved Zerus session (archive the sessions first). Git's own removal would silently delete a nested worktree inside an ignored folder; Zerus refuses it. An incomplete local file inventory, unreadable session bindings or special files also block removal. Uncommitted and untracked files require a separate **Permanently discard** confirmation in the manager. That consent is bound to the exact file contents and staged Git blobs (bounded to 64 MiB and two seconds), and does not override any other protection. A changed or incomplete proof requires a new review. Linux can deny access to a protected process's current folder or executable, including desktop services. A complete inventory containing only access denials allows explicit manual acceptance: **Remove even if some running programs cannot be checked**. This accepts uncertainty; it does not prove those programs are unrelated. The acceptance lasts five minutes on the owning computer and is bound to the exact checkout review, repository and ownership. Unrelated protected processes starting, exiting or changing PID do not invalidate it. Removal still requires a fresh complete inventory and refuses known programs or sessions using the folder, changed files or ownership, and all other protections. An incomplete inventory remains blocked. Automatic cleanup never uses this exception. Process names, PIDs and access details remain available under **Details**. The original native **Terminate** with **Remove working folder** also ignores actual permission-denied cwd or open-file reads after that exact termination succeeds, for its verified generated checkout and unchanged launch ownership. Those unreadable programs are neither listed nor signalled by that cleanup. Linux and macOS inspect open files as well as current folders; a readable path inside the checkout still keeps it, even if another read on the same process is denied. The owning CLI repeats the complete bounded classification before removal. Other errors, incomplete coverage, changed identities or ownership, known use, sessions and file protections still refuse removal. Generic background maintenance remains conservative; retained results never reconstruct this original confirmation or retry an unknown removal. For a local Linux or macOS native confirmation, a selected CLI that supports `worktree-program-stop-v1` and `worktree-program-cleanup-v1` can also stop the programs proven to use that generated checkout. Before **Stop and remove folder** is confirmed, the dialog shows a count and warning for other programs, with an expandable list, including editors and terminals the person opened there. Only the selected session's own agent and wrapper can be omitted from this initial display, when their exact record binding, native birth identities and direct parent relationship remain verified across discovery; uncertain rows stay visible. This presentation never filters the complete native execution manifest. The separate Force confirmation always shows its complete freshly checked survivor list expanded. Only the original process identities are eligible: immediately before each signal, Zerus checks their native birth/pin and current cwd or open-file membership in the same held checkout. Newly discovered or replaced programs require fresh review. Programs needed to verify and settle the operation, and their protected ancestors, are never signalled. Pause, native Stop, manual cleanup and background maintenance retain their existing scope. These native helpers resolve the existing configured session-state root once at command configuration load, including aliases selected through `HGS_STATE_DIR`, `XDG_STATE_HOME`, or a symlinked home or `~/.local`. All phase reads use that same physical root. The configuration identity is unchanged; registrations and their original argv keep their existing spelling. Journal descendants and the checkout walk still refuse symlinks. A missing, unreadable or non-directory state root is refused with its configured path; inspection does not create it or choose a fallback profile. The original Terminate UUID and exact successful archive receipt precede a separate, durably reserved program-stop UUID. Normal stop sends TERM with a 15-second phase bound and never escalates automatically. If process metadata is temporarily unavailable after signalling, read-only exit observation stays within that original phase; only a later exact native pin observation establishes exit. Uncertainty at the bound remains Unknown. If verified original programs survive, **Force stop…** opens a new native confirmation listing the currently surviving originals, with a new UUID. It becomes available only after the previous mutating helper, descendants, pipes and loans physically settle. Missing or uncertain outcomes cannot create a Force offer. The original selected CLI, configuration, environment, Actions claim and checkout/ancestor handles remain held across both confirmations, within one original five-minute custody bound. Neither a deadline nor a returned status proves drain. After a known Complete stop and actual mutation retirement, that same live Remove continuation may open one final cleanup phase, with its own UUID. It reuses the guarded cleanup engine: fresh file, ownership, session and known-use checks still apply; the branch and archive restore identity stay. Only the original read-only holder's one proven root descriptor is omitted from process use accounting. Another descriptor, cwd use or any other process still counts. The holder remains charged independently; it has no stop or deletion verb. Cleanup returns Removed, Kept or Unknown once. A lost or partial deletion stays Unknown, with original-ID status lookup only; a restart, reconnect or a new UUID cannot reconstruct the continuation or repeat it. The new fixed stdio helper commands accept only their current canonical native parent's original-child proof, never renderer, manual or background requests. If the selected route cannot support this pipeline, removal remains available through the existing separately guarded folder review rather than an alternate CLI selection. A checkout with uncommitted or untracked files can also have such access denials. Its review then offers both consents (`discardable_with_process_consent` beside the discard and process fingerprints, while `discardable` stays false for older clients). Removal needs both: **Permanently discard** and **Remove even if some running programs cannot be checked**. Each consent alone is refused, and every other protection still wins. A refusal before deletion shows **Folder kept**. **Check again** refreshes only remaining folders and clears the prior local-file, discard and process choices; removal needs a new explicit confirmation. File inspection remains available. Successfully removed targets are never resubmitted. A lost response, an older CLI without a verified outcome, or an error after Git may have started shows **Result unknown** and never enables another removal in that operation. Files can still be inspected. The CLI preserves nonzero failure exits and stderr while adding a request-bound JSON outcome for clients that request `--json`. Git stops tracking a worktree before it deletes the files, so a removal can fail halfway, for example on a readonly ignored folder: Git forgets the worktree while some files remain. Before every `git worktree remove`, the owning computer reserves a private removal record. A confirmed outcome drops it, and an interruption or failure keeps it. A folder that Git no longer tracks but that still exists then appears in the repository review (and in a review targeted at that worktree, such as the cleanup after Terminate) as a **leftover** (`worktree-leftovers-v1`), with a fresh bounded listing of the remaining files, the retained branch and current processes or sessions. Size, manifest and deletion blockers share one no-follow walk, bounded by two seconds and 200,000 entries, including queued children. Unreadable or protected subtrees and exhausted bounds leave `size_complete` false and refuse deletion. The cleanup after Terminate keeps such a folder with "Git no longer tracks this folder, but files remain" instead of an unverified-folder error. A targeted review matches the worktree's whole path, as given or resolved through links, never a prefix. The targeted reviews behind `hgs worktrees inspect` and `remove` therefore also resolve that worktree's own record under the rules below, so inspection, otherwise read-only, may drop a record whose folder is gone or that Git tracks again. A missing Git registration is never treated as proof of deletion, and the removal is never retried. **Keep folder, forget record** (`hgs worktrees keep-folder`) checks the reviewed leftover again under the repository lock and drops only its record; the folder, its files and the branch stay. With `--json`, a failure prints a request-bound outcome (`worktree-leftover-keep-v1`): `kept` before the record is touched, `unconfirmed` once forgetting it may have started. A client reports **Nothing changed** only for `kept`; an unreachable computer, a crash or any other reply is **Result unknown**. **Delete remaining files** (`hgs worktrees delete-leftover`, `worktree-leftover-delete-v1`) is disabled on macOS pending a verified native guard: XNU may unlink ordinary `._*` files while retrying directory removal after an unreviewed folder replaces the checked name. A fresh `._*` listing cannot close that race. Review and **Keep folder** remain available. The desktop explains the refusal and offers **Open in Finder** for a local folder; for a remote Mac, open the displayed folder in Finder on that Mac. The CLI refuses before changing permissions, unlinking files or reserving an attempt and returns the existing request-bound `kept` / outcome-version 1 reply. The shared directory-removal wrapper also refuses both nested and root removals on macOS. A future authorized native window must run the ignored `state::worktree_cleanup::tests::macos_late_swap_preserves_appledouble_payload_at_root_and_nested_names` probe with `--exact --ignored` before re-enablement is considered. It is a containment probe: it requires an `Unsupported` refusal and intact payloads, and does not call raw XNU directory removal. The separate ignored `state::worktree_cleanup::tests::macos_raw_appledouble_observations_do_not_qualify_deletion` probe observes raw syscalls on fresh synthetic directories; its passing result does not authorize deletion. The [native qualification](native-macos-leftover-qualification.md) records the verified late-swap data loss and the unsuccessful held-fd candidates. On Linux, deleting the remaining files needs an explicit confirmation and the fingerprint of the fresh review the owner saw. It checks everything again under the repository and session locks and refuses saved or running sessions, other running programs, nested Git repositories, special files, folders on another filesystem or owned by another user, and an incomplete listing. A failed saved-session inventory (including an unreadable or malformed binding) is an explicit blocker, never evidence that no session uses the folder. The process-only manual exception cannot override it. The narrow manual exception for programs whose folders cannot be read works as it does for worktree removal: it is bound to the exact leftover path and its fresh-review fingerprint and expires after five minutes, the known-use, session, ownership and file protections still apply, and automatic cleanup never uses it. Deletion never follows links and never leaves the reviewed mount. Each folder is opened without following links and checked through its open descriptor for owner, device and mount (the Linux mount ID, or the macOS filesystem ID and mount point), so a link, a mount or a same-device bind mount that appears after the review stops the deletion before anything in it changes. A filesystem whose mount cannot be identified is refused. The reviewed folder itself is part of the confirmed fingerprint (device, inode and mount): it is reopened through its parent without following links (folders above it need only search permission: Linux opens them as paths and macOS for search), and completion is confirmed through that parent. The reviewed root stays open and its name is checked against that inode again immediately before final removal. This rejects an observable replacement and prevents reuse of its inode number. The check and removal are separate: neither [Linux `unlinkat`](https://man7.org/linux/man-pages/man2/unlink.2.html) nor [macOS `unlinkat`](https://github.com/apple-oss-distributions/xnu/blob/main/bsd/vfs/vfs_syscalls.c) provides an expected-inode argument or directory removal through the open root itself. An empty directory swapped into the name between the check and removal can still be removed. No userspace traversal enters that replacement. On Linux, directory removal refuses a nonempty replacement. On macOS, [XNU may clean up AppleDouble entries and retry directory removal](https://github.com/apple-oss-distributions/xnu/blob/f6217f891ac0bb64f3d375211650a4c1ff8ca1ea/bsd/vfs/vfs_syscalls.c#L10670) after `ENOTEMPTY`: its cleanup can unlink ordinary files whose names start with `._`, such as `._payload`. A late macOS replacement therefore has no empty-only guarantee; its unreviewed `._*` files may be removed by the kernel. Renaming the path into quarantine would instead move an unreviewed folder and cannot guarantee race-free restoration, so it does not supply the missing inode-bound primitive. Only after those checks does deletion grant the owner write access to their own folders inside the reviewed tree, which is what blocked Git; it never touches the branch. If it stops partway, the record stays with the reason and the deletion is never retried; review the folder again. Each confirmation is consumed by a durable, unique attempt reference before filesystem changes begin. If that reference cannot be saved, deletion refuses without changing files. Even if no file changed and saving the stopped outcome fails, the old confirmation is no longer valid; another attempt needs a fresh review. Deleting leftover files is currently available on Linux only. A record resolves by itself once its folder is gone, or once a fresh worktree list taken under the repository lock shows that Git tracks the worktree again. On Linux and macOS the Git that removes a worktree inherits the repository lock (an flock belongs to the open file, and only that Git receives it), and hgs releases the lock by closing it, never by an explicit unlock. The lock therefore stays taken while that Git, or anything it started, still runs, even after hgs is killed, and no review resolves the record in that time. On Windows the lock ends with hgs. If worktree operations keep reporting that another one is running (for example because a custom `git` wrapper left a helper behind), `fuser -v` or `lsof` on the repository's `worktree-cache/repo-*.lock` file in the hgs state folder shows which process still holds it. A leftover whose repository is gone is listed by `hgs worktrees leftovers` and can still be kept; a record whose repository and folder are both gone resolves. A missing folder or repository counts as gone only on the filesystem that held it. Each reservation records that filesystem in a separate private table that older CLIs never read: on Linux the device and the `statfs` filesystem ID (derived from the filesystem UUID on ext4, btrfs and xfs), on macOS the filesystem ID and mount point. A missing path is gone only when the nearest existing folder above it is on that same filesystem. A volume that is unmounted, replaced by another one at the same place, or that cannot be identified (for example a zero filesystem ID, as on some tmpfs and network filesystems) leaves the record uncertain: it stays visible and can be kept by hand, and it never resolves by itself. So does a folder or repository that was already missing when its removal was reserved, since no filesystem could be recorded for it. On btrfs the device is a per-subvolume number that can change across remounts and reboots; such records also stay uncertain until kept. A block-level clone of a filesystem shares its ID, but mounted at the same place it normally has another device, so it is not taken for the original. A bind mount whose source is on the same filesystem as the folder above it is the exception: once it is unmounted, the missing path is on that same filesystem and counts as gone. Records written by an older CLI have no volume row and keep the plain missing-path check, as does every record on Windows. One review or listing reports at most 32 leftovers within 1 MiB and marks the rest with `leftovers_partial` (review) or `partial` (listing); they stay recorded for a later review. Verified resolutions of vanished records stay committed even if the remaining unresolved records still prevent a new removal at the 512-record bound. The folder catalog (`hgs worktrees --path`) reports a repository's record count as `leftovers`, read through its index on every call, so a reader reviews that repository even when no linked worktree is left. At most 512 unresolved records are kept per computer; at that bound new removals are refused with a visible reason, and no record is evicted. Automatic cleanup never acts on these records. Confirmation lists the folders, the ignored data deleted with them (such as build output) and any branches that will be deleted. Each removal then repeats the review under the repository lock used by creation, compares the reviewed fingerprint and runs `git worktree remove`, one worktree at a time. It uses `--force` only for that explicit content-bound discard, never automatically. **Also delete merged branches** (off by default, remembered locally) uses `git branch -d` only for branches merged into the main checkout's branch or `origin/HEAD`; other branches are kept. A failure is reported for that worktree and never retried automatically. After **Terminate**, explicit **Move to archive**, or a confirmed clean native exit, the owning CLI automatically removes only verified Zerus-created checkouts that are clean, have no local ignored data, have no remaining session or process, and are proven integrated by ancestry, identical tree or equivalent patches. It never fetches or deletes the branch. Ownership requires both a private creation receipt and the matching nonce in Git's per-worktree metadata; older or externally created worktrees remain manual. Folder/branch naming is not ownership evidence. Automatic cleanup has bounded checks and never changes a successful archive into a failed termination. A lost removal acknowledgement is reported as unconfirmed, with no automatic replay. **Settings > Worktrees** controls cleanup on the selected computer across all its projects. Each computer keeps its own policy. The master switch and the three independent rules default to on: - Clean an integrated managed worktree after its last session is archived or terminated. - Periodically clean unused integrated managed worktrees after **24 hours** of Git inactivity by default (configurable from 1 to 8760 hours). This also covers work integrated after archival and worktrees created without a session. - Forget a missing managed checkout only after verifying its retained Git registration, ownership nonce and absence of session references. Periodic maintenance runs with the existing host recovery service, independently of whether automatic provider-error recovery is enabled or the GUI is open. It imports at most 64 old ownership receipts and checks at most one queued worktree per 30-second round. An indexed private queue schedules retained worktrees for a later hourly check; it does not rescan project disks or journals. Archive metadata checks verify compact reference metadata against the complete native archive-file roster and exact file versions, at most 5000 entries and 32 MiB within their deadline. Ordinary archive catalog migration/reconciliation builds this metadata; archive writes, rewrites and removals maintain it. Its ordinary reconciliation stamp is separate from the search stamp, so an older CLI's search refresh cannot hide pending reference maintenance. Warm pages still use only these stamps. Missing, stale or corrupt coverage keeps the folder; cleanup never rebuilds it or interprets an omitted row as no reference. Before deletion, an indexed checkout query reads the relevant authoritative archive bodies within the same bounds and durably prepares Restore for every compatible reference, including older archives without an ownership field. Unrelated archive bodies and conversation journals do not consume this check's byte budget. Reference coverage is independent of search/label filtering, and an interrupted initial migration cannot publish complete coverage. Branch, head and ownership checks remain independent. Old removed receipts do not repopulate the queue once their Git metadata is gone. Reference reads bind a regular native catalog object before SQLite runs; its private read-only reader never reopens mutable paths or accesses SQLite sidecars. Unexpected sidecars or replacement refuse coverage within the original budget. Archive write hooks publish bounded per-ID native metadata updates without opening SQLite. Reads verify those updates against the current archive objects; ordinary catalog reconciliation absorbs them. Missing or corrupt updates never substitute for a stale base row. All automatic rules use fresh native checks under the repository/session locks. They preserve branches, changed/untracked files and **all ignored local data**, including build caches. Running executables inside the checkout protect it even when their current directory is elsewhere. An incomplete or inaccessible process inventory also keeps the checkout. These checks cover the owning user's processes; Windows currently retains automatic candidates because process folders cannot be verified there. Cleanup reserves its removal intent durably before invoking Git. An interrupted or unconfirmed attempt stays for manual review across worker restarts; a periodic sweep cannot replay an uncertain archive-triggered deletion. External or old worktrees without matching ownership receipts require explicit review in Projects. Recent activity or a folder/branch name alone never establishes that a worktree is disposable. Archive cleanup reports also carry a versioned exact archive identity and the launch-ownership verdict. When it fits the bounded report, `review` retains the structured row from the original removal check, including the total process count before sample limits. Missing rows stay missing. This evidence supports counts-only notices and retained review; displaying it never starts another check or removal. Restore still requires the existing fresh exact-archive guards. Read the host policy with `hgs [@host] worktrees policy get --json`; save the full reviewed policy from JSON stdin with `worktrees policy set --json`. The revision must still match. Existing policy files and writes require every versioned field; incomplete or invalid policies keep folders instead of enabling defaults. `hgs [@host] worktrees sweep --json` performs one bounded automatic step and respects the same policy and protections. Reads never start a sweep; creation, removal, sweep and policy writes reject `--dry-run`. The desktop reports successful automatic cleanup, or keeps **Folder kept: ** after Terminate/Archive (**Cleanup unconfirmed:** when the outcome is unconfirmed). This global reminder names the retained checkout; its tooltip and accessible description identify the source session, computer, full folder and reason. It can remain while another session is selected and does not expire after a minute. The action is hidden while another known session or a new run uses the folder. Review still checks the current files and requires explicit confirmation before removal. Archives keep the exact branch/head needed to recreate an automatically removed checkout on explicit **Restore**; a changed branch or occupied destination is refused. Browsing and dry runs never recreate a folder. Plain Pause never cleans up. Desktop **Terminate** also offers **Remove the unused worktree after stopping**, including for a selection of sessions. The choice is remembered on this desktop. The choice is bound to the checkout ownership recorded at that session's launch. A replacement checkout at the same path or branch is kept for manual review; older sessions without a launch ownership record also require review. For a retained **Not created by Zerus** linked worktree, **Remove anyway…** opens a separate explicit manual confirmation. It shows the native-selected path, computer, kept branch, size, changed/untracked counts and local data, and requires its matching discard consents. Fresh session and program checks still apply; known occupants must stop first (use the existing Force flow when offered). Unreadable program paths retain the existing five-minute manual acceptance. This action never removes the primary checkout or an ordinary folder, never makes an unowned folder eligible for automatic cleanup, and never retries an unknown removal. The branch and archive identities remain; recreating an unowned working folder for Restore remains an explicit manual step. Fresh removal fingerprints include the ownership nonce, so replacing a checkout after review cannot inherit its removal consent. On Linux and macOS, `worktrees programs --json` provides read-only native discovery for an original live session and its verified launch-owned checkout. Its closed stdin object contains `capture`; the bounded reply binds the exact capture, configuration, boot and checkout directory object to the complete list of observed program PIDs and native birth identities. This is data, never a stop permit. The command sends no signals and changes no cleanup or Force authority. It refuses an incomplete or changing census, changed ownership, ambiguous hard links, nested mounts, or a custodian using the checkout. The discovery budget is five seconds, 64 programs, 65,536 filesystem objects and 8 MiB of retained relative names; the wire reply is capped at 64 KiB and expires after five minutes. Actual permission denials are omitted only from this explicit-Remove discovery; a readable cwd or open file still establishes membership. The existing generic worktree review and background cleanup keep their conservative process policy. On macOS these reads include each thread's own working directory, not just the process directory. The native thread-path API selects by user TSD value (`cthread_self`), not a stable thread ID, and returns the first match. Every unique value, including zero, is read. Any repeated value, zero or nonzero, leaves the observation unsettled: at most four attempts within the existing deadline, then incomplete coverage, never an empty census. Raw Mach threads can share zero while holding different working directories; the thread-ID64 API supplies no path to resolve that ambiguity. No TSD mutation, suspension or elevated task port is used. The accepted residual is a live thread changing its TSD between listing and read: an ESRCH can be taken as an exited thread, or a reused value can address a different thread. Process birth checks do not close that per-thread window. This follows the pinned [XNU thread-path implementation](https://github.com/apple-oss-distributions/xnu/blob/f6217f891ac0bb64f3d375211650a4c1ff8ca1ea/bsd/kern/proc_info.c) and the coordinator's zerus-q0cd5 addressability ruling. Private fixture PID tests qualify their own processes only; a full-host diagnostic reporting a limit remains incomplete and does not qualify full-host Remove. Native vnode evidence is retained independently of its pathname: XNU may return a filled vnode while path reconstruction fails. Exact object membership still applies, while the generic sampler refuses an empty or relative path. A path without interpretable native vnode metadata is unsettled. The native zeroed reported-no-vnode response is accepted only as that observation: XNU uses it both for no own cwd and for a failed vnode acquisition during churn, which the API cannot distinguish. This additional kernel-acquisition residual does not prove perpetual absence or exempt aliased thread handles. After the original confirmation closes, cleanup runs in the background only following exact successful termination. A compact workspace notice shows progress, then **Working folder removed**, **Working folder kept** with a short reason, or an unknown result. **Check again**, **View files**, **Details** and **Keep** provide explicit next actions. Review opens only when requested and does not block the rest of Zerus. Pending work and retained results are bounded to 64 folders, and background batches run sequentially. Closing the review does not cancel an accepted removal. The notice remains visible through the confirmed action and the actual folder-checking/removal phases. Result notices use the normal notice timeout; dismissing one does not discard the retained result. The status bar's working-folder entry still opens its review. While a folder is being checked, removed or restored, the status bar also shows **Background tasks** with a count. Its list names each folder and its current state, and offers the same review. It adds no cancel or retry, and goes away only when the work has really ended. A kept or unknown result stays on the working-folder entry while other folders run. Review groups results for the same folder and lists their original sessions. Blockers name the current sessions (with **Open session**) and programs with PIDs; full reasons remain readable. **Clear settled results** clears settled kept folders, including folders retained for another session or external program. **Dismiss** removes one folder from this review; unknown results must be dismissed individually and retain their native no-replay fence. Busy folders, live Force offers and unfinished program stops cannot be cleared or dismissed. Closing the review only closes it; it never clears results or releases an action. The original folder is checked on its owning computer. A verified Zerus-created, clean, integrated checkout can be removed with tool-declared generated caches without another confirmation. Supported cache proofs include Cargo's cache-directory tag, source-backed Python bytecode, package-manager metadata, Gradle build metadata and a CMake build bound to this checkout. A directory name alone does not establish disposable data. Other local files, source changes, external checkouts and uncertain process use keep the folder for explicit review. The branch and conversation are retained, and managed archive restoration records the exact retained head before removal. An already completed native cleanup is reported directly; an uncertain native cleanup is never restarted by the desktop. Cancellation, failed termination and unconfirmed removal never trigger a retry. Background maintenance keeps its existing policy and preserves all ignored data. The cleanup review always shows integration evidence, even when local files remain. Git integration uses local refs, not a fresh remote check. The selected folder explains unsaved changes, local data loss and why automatic cleanup kept it. **Inspect files and commits…** opens the bounded file browser, including ignored files; a cache-like filename alone is not proof that data is disposable. **Keep folders** makes no removal. Local-data and unsaved-work deletion require separate consent. Manual removal keeps conversations and keeps branches by default; restoring an archive may require recreating its working folder. The CLI is `hgs [@host] worktrees review --path PATH [--worktree WORKTREE] --json` and `hgs [@host] worktrees remove --path WORKTREE --common-dir DIR --fingerprint HASH [--ignored-fingerprint HASH] [--discard-fingerprint HASH] [--process-fingerprint HASH] [--preserve-archive-restore] [--delete-branch] --json`. Explicit inspection is `hgs [@host] worktrees inspect --path WORKTREE --common-dir DIR [--file RELATIVE_PATH [--offset N]] --json`. Machines with an older `hgs` must be updated before cleanup is available there. ## Project tasks `hgs task` keeps a project's task list: prompts that wait in Backlog or To do until someone sends them to a session. Every computer of the swarm holds every task and works with them offline. Every command prints JSON. Tasks belong to a catalog project, named by its ID or name; a task is `T-` plus six characters, and `PROJECT/T-xxxxxx` names it anywhere. On Linux and macOS, ordinary task commands use a refusal-only interim check before acting as the person or accepting a forwarded `--agent`: at most 64 same-user processes from the caller upward, with each readable environment bounded to 1 MiB. An ancestor carrying `HGS_SESSION` or `HGS_RUN_ID`, even an empty value, refuses person actions; no ancestor's session identity is adopted. The DeepSeek host refusal runs first. An unreadable or macOS-withheld environment is no evidence of an agent: Terminal.app's system shell keeps working, while a readable agent above it still causes refusal. Windows keeps its existing caller path. The check reads no session inventory and runs only where the task state lives; `hgs @host` carries no `HGS_*` to that computer. This is an interim guard within one user's process tree, not verified Person authority. An agent started without markers and a process reparented out of its agent's tree, such as a detached `setsid` helper whose parent exits, are not detected. The bounded walk also cannot see beyond an unreadable process table or its 64-process limit. A reverse process index (zerus-j43fm) and verified Person authority (zerus-cg5h.4.11) are separate work. Team commands keep their existing stricter proof, including its unreadable-environment refusal. With the Agent Teams preview on, a task's `team` key identifies its team and home computer. Agents cannot send, hand off, retarget, cancel, reorder, edit, rename or change the stage of a live team's task. Its delivered holder may acknowledge its own attempt or legacy dispatch, register a worker and report; comments and messages that only add text remain available. The person can override these restrictions. A person's retarget away from the team clears the key and releases its live node under the same project lock; a refused release keeps the task unchanged. Turning the preview off makes a local team's marked tasks dormant: ordinary task commands do not open the team store or apply its guards. A foreign-home or invalid key still refuses agent control without opening the store, whether the preview is on or off. The refusal points the person to `hgs task target REF any` to clear the key. When a key is cleared or replaced on another computer, the home service releases the node at its next observation; that sync and observation window is accepted. An accepted team result is the team's only while its task still shows the execution the node took in. If the task comes back In review under the person's own ended run, with conflicting attempts, or Done with conflicting attempts under a branch integration, the accepted result is superseded: the node ends without merging, its integration and held-step cards close, the lead gets one item naming the task, and the task document is left unchanged. A Git write that was already admitted keeps its integration fact; the item says the accepted result had already been merged, with the commit when known. A merge also waits until the home service has applied the task's current state, and a task that cannot be read is not merged. From that final check until the Git ref update returns, the task's own writes wait: a task command that cannot wait that long refuses as busy without writing anything and can be retried. ```sh hgs task add --project orchard [--backlog] [--target codex/api|any [--host ALIAS]] [--position N] < prompt.txt hgs task add --project orchard --title "Task title" --request-id UUID < description.txt hgs task rename orchard/T-a1b2c3 < title.txt hgs task list --project orchard [--stage todo] hgs task list --project orchard --stage todo --limit 50 [--after CURSOR|--before CURSOR] [--if-revision REVISION] [--session ID [--host ALIAS]] hgs task get orchard/T-a1b2c3 hgs task get TASK_UUID --project orchard --history-limit 80 [--history-before CURSOR] [--attachments metadata] hgs task attachment TASK_UUID --project orchard --file 1 [--entry ENTRY_ID] hgs task send orchard/T-a1b2c3 [--session codex/api [--host ALIAS]] hgs task handoff orchard/T-a1b2c3 --session codex/worker [--host ALIAS] hgs task start orchard/T-a1b2c3 hgs task begin-attempt orchard/T-a1b2c3 --attempt ORIGINAL_UUID [--json] hgs task control plan|execute|status --json hgs task report orchard/T-a1b2c3 [--progress|--ready] [--considered REV] < summary.txt hgs task report-attempt orchard/T-a1b2c3 --attempt 00000000-0000-4000-8000-000000000001 [--progress|--ready] [--considered REV] < summary.txt hgs task cancel orchard/T-a1b2c3 [--reason "Wrong approach"] hgs task stage orchard/T-a1b2c3 backlog|todo|done hgs task move orchard/T-a1b2c3 --top|--before REF|--after REF hgs task edit orchard/T-a1b2c3 < prompt.txt hgs task comment orchard/T-a1b2c3 [--content-json] < comment.txt hgs task target orchard/T-a1b2c3 codex/api|any [--host ALIAS] hgs task target orchard/T-a1b2c3 new-session|subagent --parent codex/api [--host ALIAS] [--session-id ID] hgs task worker orchard/T-a1b2c3 --subagent CHILD_ID --request-id SENT_REQUEST_ID hgs task settings --project orchard [--set < settings.json] hgs task cutover --project orchard [--hold on|off [--confirm]] ``` `begin-attempt` and `task control plan|execute|status` are currently inactive source interfaces (`zerus-cg5h.4.7`). Valid requests return exit 1, `code: task_controls_inactive` and `attempted: false`, before opening task or desktop stores. The `task-control-v1` help marker is absent while the gate is off. Existing prompts, send/handoff/reopen/direct-start/report behavior and plain `start` are unchanged. Native wiring and queue activation are later reviewed steps; a new CLI on disk does not qualify a resident adapter. The control interface takes strict schema-1 JSON on stdin, at most 16 KiB. Plan names the original task/attempt or, for Stop release, the exact executor and explicitly observed Stop IDs. Execute accepts the original plan, with exact task version, slot revision, caller scope, configuration/store/image and loaded adapter guards; these labels are data, not authority. The owning runtime must prove them again before any effect. Status names an original request UUID or uses an executor sequence cursor with a limit of 1–128. Unknown fields, duplicate fields/options, noncanonical IDs and oversized requests refuse. After activation, a fresh managed send/handoff/reopen supplies exactly one pinned `begin-attempt REF --attempt UUID` acknowledgement, replacing plain start. Feedback carries the existing report origin and requests no second acknowledgement. A semantic begin requires the immutable attempt to be current, delivered and owned by the exact executor; it cannot acknowledge a newer generation, clear a Pause or bind a native turn by itself. Legacy and direct start policy, structured report authority and considered revisions stay intact. The existing desktop Start plan is unchanged in this wire leaf; its final managed/legacy acknowledgement mode and startup-run reservation belong to the native-wiring check-in before activation. Plain `task get` retains the complete journal for existing clients. The optional `--history-limit` (1–80) returns only one chronological history page, the canonical task document, `log_total`, `start_confirmed`, `history_schema: 1` and `history_next`. Pass that opaque cursor as `--history-before` for the previous page; a null cursor marks the beginning. Use the task UUID from the list to avoid a project-wide short-ID lookup. Cursors bind the project, task and immutable history entry, so new records and receipt refinements preserve an older page. Omit the cursor to return to the latest page. Pages come from the project's local task index, which keeps the histories of the 16 most recently read tasks and reads a task's history again only after that task changes. The requested task is held to the same rules as a page's rows: a suspect one is read from its document first. The index is never replicated and does not change the task document format. A task whose history the index cannot give is read from its document, with the same page. `--attachments metadata` returns each attachment of the task and of its entries as `name`, `mime`, `reference`, `size` and the `sha256` of its bytes instead of the file, and gives each entry an opaque `id`. `hgs task attachment` returns one file with its bytes (`data_base64`): `--file N` counts from 1 among the task's own attachments, or among an entry's with `--entry` and that entry's `id`. Task list rows also include a bounded `history_revision` token. A journal-only note or delivery receipt changes it, so the existing task stream can refresh the selected inspector without transferring the journal or adding a polling loop. Task views (`task get`, history pages and list rows) include an `execution` object for a task that is In progress or recorded execution attempts: `requirement` (the task's requirement revision, from 1; each edit of its prompt or attachments counts the next one, a rename or comment does not), `attempts`, `current` and, when two attempts claim the same generation, `conflict: true`, which nothing resolves automatically. `current` is the attempt the task's execution is about: its `id` and `generation`, `origin` (`send`, `start`, `handoff` or `reopen`), `executor`, `request_id`, the `requirement` it executes, `phase` (`submitted`, `unknown`, `running`, `paused`, `ready`, `cancelled`, or `unconfirmed` when nothing shows who executes it), `at`, and `began_at` and `progress_at` when known. History written before attempts were recorded reads as `legacy: true` with generation 0, from its latest boundary alone: a send, handoff, reopen or direct start. A start by that boundary's session before the execution ends (a result report that moved it, a cancellation or a stage move) acknowledges it; a stale report or progress ends nothing. Any other start is a boundary of its own, and an earlier execution never lends its origin, time or receipt to a later one. A boundary written for a name-only session (older history) names the session holding the task only through the binding Zerus records when it binds that exact key to the holder's verified run, on the same computer, before any change; the task keeps it until its next send or start. Only that run is then the executor: a name alone never names one, so another run that holds the name is not, and a holder an older build bound without recording it reads as a conflict. When merged replicas leave the latest boundary with another session than the one holding the task, `conflict` is set. Each attempt freezes the history entries of the task's executions so far (`sent`, `resumed`); a send or reopen it settles names its request. An execution entry neither frozen nor named, such as a send an older build recorded concurrently, is listed in `unexplained`, sets `conflict` and holds any new delivery until the person reviews that exact entry. No start, child or result is invented. A resume settles only the pauses it observed, so a pause that no resume observed keeps the attempt paused. A session's Stop, idle time, pause or elapsed time is never an attempt event and never moves a task. Attempts are kept beside the history under task schema 7, which a reader that does not know them shows read-only: that includes the builds that already read schema 6 but know no floor. The stored schema is one merged value, so an older replica's concurrent upgrade can leave a lower one; this version raises it again for a task with attempts in every write and every live import, and before a task is read for an inventory, so the raised value is what other replicas receive. That repair is a new change, not proof that an older replica did nothing before it. A task can also take a floor before its first attempt: a cutover record that keeps schema 7 the same way, so a reader that does not know attempts or the floor refuses to write it, while every path that would start it without an attempt refuses it as cutting over. A floor this version cannot read still counts. This version reads attempts, guards reports against the current execution, and records attempts and floors through the attempt writer (below). The attempt writer (zerus-cg5h.4 S2b.2 C3 activation) is how every native task input now begins: the desktop's Start (`start-plan`/`start-deliver`), `task send`, `task handoff` and a reopen (`task message --mode reopen`). It runs on the computer whose session executes the task, which holds the input's receipts, within one 15-second budget counted from the command's entry: 1. The request is frozen first: ONE request ID and the exact native request. 2. With no lock held, the fence admits it: the task's certificate with no network; otherwise, for a task with no floor yet, its first floor, which is written only when the project's bootstrap gate is positively satisfied (every eligible direct member recorded current, with a complete exchange, the phase known, and the hold off); then a fresh proof. 3. In the fence's final admission, and only there, the frozen request is checked again against the task as admitted (its prompt, attachments, queued messages, requirement, target, executor and settings): any change refuses it, and nothing is reserved. Otherwise its attempt is reserved under that ID and saved. 4. Only then, with every lock released, the input is submitted once. Its own submitted receipt settles the attempt, and the settlement never overwrites a later stage or assignment. The outcome is explicit: `submitted`; `refused` (the request changed, or the input was refused before anything was offered to the terminal, which settles the attempt as not admitted; a new action with a new ID may send it); `cutting_over` (the fence, the hold or unknown bootstrap evidence; nothing was reserved or sent); or `uncertain` (the input may have arrived; it is never sent again). For a team's hand-out, `cutting_over` settles the effect as not delivered (`refused`) and frees both task and member. After the normal refusal backoff the service may create a new hand-out with a new effect ID; it never replays the old effect. No `delivery_uncertain` item is opened for this proof of non-delivery. Older such effects are reconciled in bounded passes, closing only the false item identified by the original outcome receipt. Unknown or uncertain effects remain occupied and their items remain open. Repeating a request ID, a restart or `--recover-only` only reads that request's receipt and never submits, even when no receipt exists. Managed native starts require the current causal cutover even when the older bootstrap would have selected a legacy route. Missing/unproven migration history stays a task-specific refusal; it never authorizes a legacy offer. For `unroutable`, `unverified` and `deadline`, the refusal includes a catalog computer label marked diagnostic beside the exact UUID when available, explains that absent computers do not block reachable ones and this computer must finish its own automatic cutover, and points to `hgs task cutover --project P --json`. A catalog label grants no identity or route. Desktop Start shows the complete executor reason as its primary notice. A reopen of a managed task keeps the person's text as a discussion note bound to its attempt's ID, saved together with that attempt; the note is not queued feedback and is never delivered by itself, and only the receipt moves the task back to In progress. Feedback to a task In progress (`--mode send`) stays an ordinary message. When recovery cannot settle an unknown delivery, the person can use `hgs task cancel-attempt REF --attempt UUID [--reason TEXT]`. This abandons only that exact unknown attempt, records a `Cancelled` fact and an `attempt_cancelled` audit entry, and releases its hold. Delivery remains unknown: the original request and evidence stay, the task keeps its stage, and no cancel notice or other native input is sent. An exact repeat observes the original disposition without another write; wrong or already-settled attempts refuse. Other unknown attempts still hold the task. A later send uses a new attempt, and an old request is never replayed. The reply contains one task row; read its audit through the bounded task history command. The task inspector's **Saved execution** section shows the saved attempt, generation, requirement revisions, executor and recorded events. Submitted does not mean begun, and recorded begin does not prove the agent is still working. Unknown, conflicting or unexplained evidence remains visible; failed refreshes mark the retained record as stale. Missing or unsupported execution details, live execution state and the executor queue remain unavailable. The project's To do order is separate from an executor queue. This section adds no controls. The task view shows each unknown attempt with **Abandon attempt…**, followed by a separate confirmation. A team-owned task requires the person's command on the team's home computer. Running, Paused, Draft and Planning teams refuse; Stopped, Finished, Archived or a missing home team allow the disposition. The team writer admission is retained across the task save. With preview off, an existing store is read without migration or Team data writes under the same admission; an absent store stays absent, and a schema needing migration refuses. The team key and its facts stay intact. Plain `task list` still returns every task for existing clients. With `--stage` and `--limit` (1–200) it returns one page of that stage in the same order and with the same rows, except that a prompt longer than 2 KiB is cut at a character boundary and marked `text_truncated: true` (`task get` returns all of it). The reply adds `page` (`schema: 1`, `stage`, `limit`, the zero-based `position` of its first row, the stage's `total`, and the opaque `next` and `previous` cursors), `counts` for every stage, `damaged` (at most 20) with `damaged_total`, and a `revision`. Pass a cursor as `--after` or `--before`; it binds the project and stage and names a row, so tasks added or moved elsewhere never shift the page after it. A page past either end returns the nearest whole page, and only an empty stage has no rows. `--if-revision` with the last `revision` answers `{"unchanged": true, "revision": ...}` without rows when nothing changed, after checking that page's rows against their files. Task lists check the caller before discovering session bindings. Only session references in the selected rows need routing metadata; an empty or unchanged page, or one containing only remote references, reads no session bodies for routing. The caller's own record is still checked for agent proof. The disposable `task-routing-v1` cache keeps routing fields without command output and verifies the canonical binding namespaces and file versions on each lookup. Cold or changed metadata is refreshed in bounded slices, with a finite background helper when needed. While coverage is incomplete, the command returns `Task session routing is incomplete` and asks the caller to retry; unreadable canonical evidence returns an unavailable error. Neither case reports a referenced session as missing. This cache supplies task-list labels only; caller proof and task changes still verify canonical session records. `--session ID` (`launch_id:...` or `run_id:...`, with `--host` for a session on another computer) pages one session's view of the stage: the tasks its identity owns, the session of a task in progress, in review or done, or the target of a queued one (a sub-agent or new-session target counts for its parent), plus To do and Backlog tasks for any session. A session's name never matches: two sessions with the same name keep separate views. Rows, order, cursors and `revision` are those of the unfiltered stage; `position`, `total` and `counts` count the view, `damaged` stays the project's, and the reply adds `session` (`host`, `session_id`). A cursor names a row, so tasks added to the view before it never shift the page after it. The view reads two bounded ranges of the index (the owner's rows and the unassigned rows), never every row of the stage. `--query TEXT` with `--stage` and `--limit` searches literal substrings of the short task reference, title and full prompt, ignoring letter case. A reference may include the project's name (`orchard/T-xxxxxx`). Queries are at most 1024 UTF-8 bytes and contain no control characters. The reply echoes `query`; `position`, `total` and every stage's `counts` describe matching tasks. Search combines with `--session`, and its cursors bind the query and session scope as well as the project and stage. The session side panel uses these pages, with the same stage filters and Show more controls, rather than searching only the loaded window. The index keeps full search text separately from the capped preview and applies the query before the page limit. With **Only this session** on, a session without a stable launch or run identity cannot search: no project-wide request is sent, results and counts stay empty, and the panel explains how to turn off the session filter explicitly. Pages come from a local index of task headers in the project's replica folder (`task-index-v3.sqlite3`): a disposable cache, never replicated, rebuilt silently from the task documents when it is missing, damaged or of another version, and never a reason for a read to fail. An older hgs that shares the state folder keeps its own `task-index-v1.sqlite3` or `task-index-v2.sqlite3`, which this one never opens, migrates or removes, so they never rebuild each other's index. Each save notes the task in the project's change journal (`changes`, a bounded hint that is only ever replaced, never written through), so a read decodes only changed tasks. Every task file's stamp (length, modification time, inode) is also checked at least every 30 seconds for writers without the journal: one listing of the task folder gives the files to stamp (a file it does not list is missing, and a file written after it is found by the next check), and only a task whose stamps changed is read again. A row is suspect when it was read from files modified within the last 2 seconds, before the journal last became unknown, more than 10 minutes ago, or at a time after now (a clock set back). A page reads its suspect rows from their documents again before it returns them, and each read of the index reads up to 256 others again, those read longest ago first, so every row, and with it every stage count, is read again within 10 minutes plus ceil(tasks / 256) reads. The index holds at most 256 MiB whatever its page size; a larger one is built again. Short-ID lookups, list places and the agent start limit use the same index. Adding, moving and staging a task place it from the index too, without reading every task, while the index is certified current (no row change by another build pending under the repair epoch) and holds no damaged task: every task file's stamp is checked first, as the periodic full check does (so a task a writer without the journal added or moved is read again), and the two neighbouring tasks are read from their documents to confirm their stage and rank. Otherwise, or when the stage needs its ranks renumbered, the whole write reads the documents as before. Send pastes the task prompt into its session through the same input path as `hgs send`; the task becomes In progress, and Zerus does not check that the agent received it. A managed dispatch pins its exact `hgs task report-attempt REF --attempt UUID` command before the native request is hashed. Its result can move that execution to In review; an explicitly legacy execution uses ordinary `hgs task report`. Cancel moves a task In progress to In review and pastes the cancel message without stopping the turn; its reason is kept as a comment and never pasted. A task this computer already shows In progress is not sent again. Both report commands add the report to history. For a managed execution an agent uses `hgs task report-attempt REF --attempt UUID`, with the UUID supplied by its original dispatch or start acknowledgement. The named immutable attempt must be current, its generation and verified executor must match, and the existing conflict, phase and unknown-delivery guards still apply. A result (default or `--ready`) can then move In progress to In review; `--progress` records progress without moving the task. The report retains its declared origin as optional `reported_attempt` log metadata. A stale origin records `stale: "other_attempt"` and creates no Ready/Progress fact for the current attempt. A different executor, a conflicting execution and unconfirmed delivery retain their existing guards. Explicit human reports retain their existing rules. `--considered REV` still only records the positive requirement revision; this change does not gate actionable-clarification acknowledgement. A plain report by a managed agent has no origin proof. It succeeds as a history write (exit 0) with `history_saved: true`, `outcome: "not_applied"` and `moved_to_review: false`. Text and JSON say that the task did not move and refer to the command in the original task prompt or a person's acceptance/resend. They do not supply the current attempt UUID or a newly retargeted command. Never replace an original UUID with one from a later task lookup or retry the history write as a duplicate. The new action is deliberate: older CLIs reject `report-attempt`, while older `report` parsers can ignore an unknown option. The CLI help marker `report-attempt-v1` lets coordinators check support. Direct `add --start`, `start REF` and an active task's start acknowledgement return `reporting`, `report_command` and, for an actual managed attempt, `report_attempt` in JSON. The text prints the same pinned command. A positively unfloored legacy direct start creates no attempt: it explicitly reports `reporting: "legacy"`, prints the ordinary command and invents no UUID. Creating managed attempts for every first direct start is separate work; this change activates no new C3 admission or floor path. Legacy plain reports keep the documented pinned-agent rule for never-sent queued work. A floor or a recorded attempt never authorizes an implicit legacy start. If managed history remains but the current execution falls back to legacy (for example, after its first managed handoff is refused), a successful start acknowledgement returns `reporting: "history_only"` and an explicit `report_hint`, without `report_command` or `report_attempt`. It creates no attempt UUID and explains that reports stay in history without moving the task. The person can accept the result or resend the task as a new attempt. This is an updated-writer boundary, with no task/exchange schema, event shape, C3 or floor change. Older writer binaries still apply their older unscoped policy. Prompts for attempts started before this change have no pinned command; explicit human acceptance or a resend creating a new attempt covers them. There is no silent upgrade or latest-attempt inference. Older readers may ignore the optional report metadata while retaining it in the Loro document. Run inside a session (`HGS_SESSION` and `HGS_RUN_ID`), `hgs task` acts as that session's agent: `add` files the task for that session, and the project settings can keep agents to their own session or limit how many tasks they start per hour. `settings --set` reads a JSON object and changes only the fields it names. A DeepSeek host's tool call (`HGS_AGENT=dsh`) never acts as the person: it acts as its hosted session when the hosted caller proof holds, and `hgs task` refuses it otherwise (see Session markers of hosted tool calls). Another computer's hgs, reached as `hgs @host …`, sees no marker of the agent that calls it and takes the caller for the person. So an agent's process never forwards a command whose handler tells the person from an agent that way (zerus-ppd26.9). Those commands are `task`, `team` and `question-routing` (`PERSON_ONLY_FORWARDED` in `src/cli.rs`); a newer peer's `team` or `question-routing` is covered too. - **Where the check runs:** on this computer before any ssh, `--dry-run` included, on every route: plain `@host`, `@host --expect-machine ID [--client C]`, the private `__state` entry and a session reference's verified hop. - **Who counts as an agent:** a process that claims a session (`HGS_SESSION` and `HGS_RUN_ID`, proven or not), a resident DeepSeek tool call (`HGS_AGENT=dsh`), or a process a live session proves as its caller, a Claude background job included. On Linux and macOS, the same readable marked-ancestor refusal as local task commands runs before forwarding: clearing the child's own session markers does not hide that ancestor. This keeps the local interim ancestry check's bounds and limitations; reparenting can sever the chain and grants no verified Person authority. - **What the agent does instead:** it runs `hgs task` on its own computer, which reaches every computer's copy. A person's shell outside the agent's process tree can unset inherited agent variables. - **Unchanged:** tasks' own forwarding of `send` and `cancel` to the executor's computer (`--agent NODE/SESSION`). - **Still forwarded for an agent:** ordinary `answer` payloads, `interrupt` and terminal input; the answer-source exceptions are below. `wait` acts on its ticket; `parent` and `wait begin` refuse a caller the other computer cannot see; `desktop` and `approval-log` refuse every other computer. An agent cannot forward an `answer` whose outer `question_id` starts with `codex-sandbox:` or `kimi-cache:`. The check runs locally before any SSH or peer capability probe, through the same routes listed above. Agent answer input is bounded to 128 KiB; other answer sources retain their exact original bytes. Person and GUI answers keep their existing forwarding path. Any permission for a verified launch parent to choose **Compact and continue** in Kimi's Cache expired chooser is local to that exact child. This proof does not cross computers, so every agent-originated remote answer to this chooser refuses, including that parent's Compact choice. Ask the person to answer in Zerus or Terminal instead. This does not change other answer sources. This guards against accidental agent use, not against an agent that clears its own environment. Forwarding a verified caller instead is future work. The desktop cancellation dialog uses `hgs task cancel-execution REF --project P --json`, with schema 1 JSON on stdin: `dispatch_id`, `stage_at`, executor `machine` and `session_id`, and `reason`. It checks the exact active execution while holding the project lock, including after forwarding or offline fallback, and returns a compact task plus `cancel_message`. Peers without this command refuse it; no legacy cancellation fallback is attempted. `hgs task cancel` retains its existing full response. The desktop's explicit Start for an existing executor uses two schema 1 JSON commands: `hgs task start-plan REF --project P --json` prepares an immutable native request without sending it, and `hgs task start-deliver REF --project P --json` delivers that exact plan. Preparation binds a fresh request UUID, the task's `stage_at` and target, and the selected host, session name, stable session ID, run ID and conversation ID. Delivery goes through the attempt writer: it rechecks the plan against the task and executor in the fence's final admission before entering the existing native input path. Peers without these commands refuse them; there is no fallback to an unguarded send. Before delivery, the client checkpoints the complete original plan in its private task outbox, separate from discussion-message recovery. A restored or uncertain Start is never delivered again. **Review task start** reads that local record; its explicit release first calls `start-deliver --recover-only` with the original plan. This only reads the native receipt and settles an acknowledged dispatch. A found receipt keeps the task started; otherwise the reviewed record can be released so a later, separate Start has a fresh request UUID. A changed record or failed check keeps the record. Release never stops an executor or sends any input, and there is no additional polling loop. Task links retain the computer and immutable launch identity (a run identity for older bindings). The session name is a display and routing hint: renaming changes the shown label and keeps current-session emphasis and filtering. A different session reusing the old name does not inherit the task. Name-only older tasks can use a uniquely retained rename alias; an unresolved identity cannot receive input. An agent recording a direct request it is already doing uses `add --start`, or `start REF` for a queued task. This records In progress without sending the same instruction into its conversation again. For a dispatched active task, its exact current agent can acknowledge `start` once without a resend or a new attempt. Plain `add` remains a queue operation. A report by the exact pinned agent also moves its unsent queued task to In review; a report from another session remains a history note. `handoff` is explicit: only the current agent owner (or the person) can transfer an active task, and both its pinned target and working session change only after confirmed native submission. Failed or uncertain delivery never authorizes an automatic retry. The central Task View shows a canonical description document followed by Activity-style discussion. The task menu opens the result and audit history; Review foregrounds the result on the main page. Explicit **Edit description** uses Save/Cancel; ordinary messages never rewrite the document. Task input uses Activity's centered column, composer skin, attachments, voice preview and private durable drafts keyed by project and task UUID. Lifecycle controls are separate from message submission. The compact executor field distinguishes planned, current and last execution. Clicking planned assignment changes only that field. Its choices are the main session, a subagent, a new session, searchable existing sessions and Any session. Choosing an executor plan stores intent without starting anything. **Start task** for a new session opens the standard session dialog; after its explicit launch, delivery requires that exact new launch ID, computer, project, and unchanged parent computer/session identity. A private record is reserved before task delivery; restored reserved or uncertain deliveries are never retried automatically. Use **Review executor launch** to inspect a failed or uncertain launch. Explicitly releasing a reviewed record neither stops an agent nor sends the task again. `hgs task message REF --request-id UUID --mode queue|send|reopen|note --expect-dispatch ID --content-json` is a distinct discussion operation. `get` returns the current `dispatch_id` (a native send receipt or an explicit direct-work acknowledgement). Queue messages wait for the next explicit Start; their original IDs, text and files are included in that dispatch, within the native text/media limits. Exceeding those limits refuses the dispatch rather than dropping context. Notes remain saved without delivery. In-progress feedback addresses the immutable owner and captures its current run/conversation before transport. A native dispatch receipt, when present, must match that live run and any recorded conversation. Review/Done feedback explicitly uses reopen; only a confirmed submission returns the task to In progress. Submission does not establish model consumption. The replicated schema-five outbox is reserved durably before native input. A repeated request verifies the original content, mode and execution and reads the receipt; it never retries a reserved native send, even if no receipt survived. SSH failures retain the desktop's original request for **Recover saved comment**. That check uses `--recover-only` and cannot initiate a missing send. If no reservation can be found, it retains the original comment in the discussion with an unconfirmed outcome and no native submission authority. A different new comment first completes that read-only recovery, then reserves its own identity. An executor precondition refusal saves the comment with a failed delivery, leaves the task's stage unchanged, and does not submit native input. Original payloads are private per-task files read and written off the UI thread; settings contain only small markers. Explicitly releasing a local recovery record neither cancels nor resends native input. Handoff cannot retarget a reserved message. Failed and unknown outcomes remain visible in the same discussion. This is transport attribution, not a distributed lease, per-task pause or a revision scheduler. Legacy direct-work acknowledgements have an immutable owner and acknowledgement anchor, but no historical native-run receipt; a message captures that owner's current verified run explicitly. A subagent plan dispatches a creation request to its coordinator only on Start. The coordinator creates the native child and records `task worker` with the current durable `sent` request ID. Registration verifies its live parent run and conversation and the child's presence in that native roster. The card displays “child unconfirmed” until registration; the parent remains coordinator and task reporter. This is explicit attribution, not the full per-worker scheduler or an implementation of per-task Pause. Descriptions and immutable comments support up to eight attachments per message, 10 MiB per file, with a cumulative 20 MiB across the task's current description and its comment history. Bytes replicate with the document. Description files travel through the ordinary native attachment path when the task is sent; comments remain in task history and are not automatically delivered as new native input. CLI `add`, `edit` and `comment` accept `--content-json` with `{"text":"Inspect [Image #1]","attachments":[{"name":"screen.png","mime":"image/png","reference":"[Image #1]","data_base64":"..."}]}` on stdin. Omit `attachments` to keep description files while editing, or pass an empty array to remove them. Listings contain file metadata and omit history; `get` includes the retained bytes. The desktop right-hand Tasks board has a New task (+) button. Enter a title and confirm it to create a shared To do card (Backlog in that list), then fill its description in the central Task View. Subsequent input adds comments; Edit description explicitly returns the same composer to the description draft. Rename changes only the title. Creation and discussion never start an executor. Task View retains separate drafts from Activity, supports description and comment attachments, and offers voice recording with preview and transcription into the draft before the person sends it. Task comments remain history-only. Named cards use `--title`; description stdin may be empty. `--request-id` reserves the card UUID and binds the original creation input. Repeating that input recovers the existing card without reverting later edits or lifecycle changes. Reusing the UUID for a different creation is refused. A title is one nonblank line, at most 512 UTF-8 bytes. Legacy cards keep their first description line as the displayed title until an explicit Rename gives them an independent one. Immutable session identities and description media use task schema 2. Comment media, executor plans and native worker bindings require task schema 3. Independent titles and title-only creation require task schema 4. Durable discussion identities and delivery reservations require task schema 5. A later edit never downgrades that schema. Older readers and the current mobile ABI show tasks newer than schema two read-only; named cards keep a visible title in the existing text field. Project documents and the paged exchange protocol remain schema 1. Mobile picker/preview and executor-plan presentation are separate work; host-side mobile sends keep the complete description attachment payload. `--host ALIAS` names a session on another computer of the swarm that this computer verified itself. A send or cancel for such a session runs on that computer: it gets the project's tasks first, refuses a task its own copy shows In progress, pastes and records there, and its copy comes back (`synced` is false when it could not; the next sync brings it). When it cannot be reached, or its Zerus is too old to share tasks, a send is refused with the reason and nothing changes, while a cancel goes through here: the task moves to In review, its session gets no cancel message, and that computer's copy follows when it syncs. Listings name the computer of every session reference (the target, the session, the author and each history entry's session and actor) as `host`: empty for this one, the alias of a verified member, or null. Windows keeps no verified bindings yet, so there `--host` is refused and other computers read null. Tasks are Loro documents below `HGS_STATE_DIR/replica`, one directory per project; a task file that fails to load is listed under `damaged` and left in place until another computer of the swarm sends its copy, which replaces it; a copy of the damaged file stays beside it as `.damaged-