Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs(grok): drop the gap entries this branch closes, so §8 stops contradicting itself
Xavi Guardiaa838a813055b
diff --git a/docs/grok-agent.md b/docs/grok-agent.mdindex 2686f1c17..19e5ee801 100644--- a/docs/grok-agent.md+++ b/docs/grok-agent.md@@ -389,7 +389,12 @@ ai-name / comments).**Verified corrections to the original assumptions:**-1. **The `Notification` vocabulary is published and closed.** Grok 1.0.13 names `idle_prompt`,+1. **The `Notification` vocabulary is published and closed** — it was previously written up here as+ UNVERIFIED and able to fail in BOTH directions: silence (NEEDS YOU never lighting, since grok+ documents no counterpart to claude's `PermissionRequest`) or over-firing (orca reports a+ notification before *every* tool call, which the first mapping turned into an unread dot, a+ chime, an OS notification and a phone card **per call**). Neither was a guess worth keeping:+ the spec answers it. Grok 1.0.13 names `idle_prompt`,`permission_prompt`, and `task_complete` in `~/.grok/docs/user-guide/10-hooks.md:99`; `:162`explicitly says `permission_prompt` fires only while a permission UI is actually waiting. Thenormalizer therefore maps that exact type to `blocked`, maps exact `idle_prompt` through the@@ -407,22 +412,7 @@ ai-name / comments).**Remaining gaps — state these, do not paper over them:**-1. **The `Notification` vocabulary is unverified, and it can fail in BOTH directions.** Grok documents- no hook for "a permission prompt is on screen" — claude's `PermissionRequest` has no counterpart, and- `PermissionDenied` is a post-decision event — so NEEDS YOU may never light. But the opposite is just- as live: orca (a shipping integration) reports that grok fires a `permission_prompt` Notification- before **every** tool call, even under `bypassPermissions`, and our first mapping turned each of- those into `blocked`, i.e. an unread dot + chime + OS notification + phone inbox card **per tool- call**. That routine case is now suppressed exactly as orca suppresses it, and both spellings of a- genuine ask (`*permission*` and grok's own `approval_required`) still light the badge. Which of the- two failures is real is unknown until checklist **10** records the vocabulary — so watch for- **over**-firing as carefully as for silence.-2. **An interrupted turn (Esc) fires no hook at all**, by grok's design, so a node can sit on RUNNING- until the next `UserPromptSubmit` re-syncs it. The only thing that can rescue it early is an idle- `Notification`, if grok emits one — detected from its **message** text (orca's four phrases), since- nothing in either source names an idle *type*. No watchdog was built; checklist **9** measures how- bad it feels, which is the input to deciding whether one is worth it.-3. ~~The phone's per-node "what it's doing now" activity line does not work for grok.~~ **CLOSED,+1. ~~The phone's per-node "what it's doing now" activity line does not work for grok.~~ **CLOSED,and the stated cause was wrong.** This said grok's file hooks "never send `PreToolUse`", so the`recordRawToolEvent` call was a no-op and was deleted. Measured on 1.0.13 (2026-09-02): grok DOESpublish the event — it spells it **`pre_tool_use`**, its own snake_case, in both field dialects —@@ -437,15 +427,15 @@ ai-name / comments).honest; one built on a guessed key renders wrong forever. Note grok's names collide with claude'sby CASE alone in two places (`grep`/`Grep`, `write`/`Write`), so that switch must staycase-sensitive.-4. **A remote (SSH) grok node's session name never resolves.** The shells build the session directory+2. **A remote (SSH) grok node's session name never resolves.** The shells build the session directoryfrom the **local** `grokSessionsDir()` while the payload's `cwd` came from the host. It degradessafely — a wrong name is never produced, only no name — but it is a real asymmetry: claude's legright below handles remote via `setRemoteTranscriptReader`.-5. **The `sessionId → dir` map is in-memory,** so after an app restart a grok name does not resolve+3. **The `sessionId → dir` map is in-memory,** so after an app restart a grok name does not resolveuntil that session's next hook. This is the deliberate "derive, never search" trade (clauderesolves immediately *because* it scans, which is the behaviour that made nodes adopt each other'snames); the checklist records how it feels.-6. **No live session-name poll in the browser** — see §7.+4. **No live session-name poll in the browser** — see §7.6b. **The FIRST grok node in a cwd mints without checking the disk.** The taken-id set is warmedper cwd on demand (`renderer/state/grokSessionIds.ts`), so the first mint in a directorynobody has opened yet answers "nothing taken" and the fetch it triggers only helps the NEXT@@ -454,7 +444,7 @@ ai-name / comments).leaves is a v4 UUID colliding with an existing session directory, which is not the failurethis guard exists for — the real one is a node reusing an id from an earlier session, andthat one IS caught once the cwd is warm.-7. ~~Canvas-control discovery is unverified.~~ **MEASURED, and the premise holds.** `grok inspect+5. ~~Canvas-control discovery is unverified.~~ **MEASURED, and the premise holds.** `grok inspect--json` on grok 1.0.13 lists `get-linked-context` with `vendor: claude` and`compatibilityStatus: enabled`, and `externalCompat.cells` reports`{surface: 'skills', enabled: true, source: 'default'}` — `source: 'default'` is the part that@@ -467,7 +457,7 @@ ai-name / comments).while the skill is undiscoverable. **If grok does not list our skills, this changes shape** (amarker block into grok's own instruction file, as codex/gemini/opencode get) and should bere-planned, not forced.-8. ~~The brand logo is a placeholder.~~ **CLOSED.** The official xAI mark now ships, inlined in+6. ~~The brand logo is a placeholder.~~ **CLOSED.** The official xAI mark now ships, inlined in`agentIcons.tsx` as `GrokMark` (`fill="currentColor"`, the mark's own non-square 512×492 viewBoxso it is never stretched). Inlining is what makes it theme-correct: the mark is a singlemonochrome path and the vendor's own usage is one ink that flips with the background, which@@ -475,7 +465,7 @@ ai-name / comments).isolated document, so `currentColor` resolves against nothing and paints black, invisible on thedefault dark theme. That is also why the other four marks, which are multi-colour and carry theirown fills, remain assets.-9. **The local `$GROK_HOME` is read from an environment a GUI app does not have.** `grokHomeDir()`+7. **The local `$GROK_HOME` is read from an environment a GUI app does not have.** `grokHomeDir()`defaults from `process.env`, but a desktop app launched from Finder/Dock/a `.desktop` entry neversourced the user's shell rc — while the grok CLI, started by the shell inside a tmux pane, did. Fora user whose `export GROK_HOME=…` lives in `.zshrc`, we write the hook file under `~/.grok` and grok@@ -581,44 +571,44 @@ State machine edgesleaves the session working. Record whether `idle_prompt` follows as the bounded fallback. Alsotry cancel-and-send: it emits no stop hook and the replacement turn must stay RUNNING. Nowatchdog is needed because the session-level terminal event exists.-10. Capture one real payload for each published `Notification` type and record which key carries the+8. Capture one real payload for each published `Notification` type and record which key carries thekind (`notificationType`, `notification_type`, or `type`). The type vocabulary and semantics arealready published in `10-hooks.md:99,162`; this capture is only to replace the remainingdefensive key aliases with measured envelope shapes. Message prose and severity do not classifystate.-11. Force an API error (e.g. an invalid model). Does StopFailure clear the RUNNING badge?-12. Quit with `/quit`. Does the session-close Stop stay silent (no "agent finished" notification)?+9. Force an API error (e.g. an invalid model). Does StopFailure clear the RUNNING badge?+10. Quit with `/quit`. Does the session-close Stop stay silent (no "agent finished" notification)?Session identity + restore-13. Does the session chip fill in? The chip has exactly ONE source: the terminal-title OSC+11. Does the session chip fill in? The chip has exactly ONE source: the terminal-title OSC(`term.onTitleChange`, path/prompt-looking titles ignored). The summary.json poll feeds the nodeTITLE instead — that is item 14 — so a blank chip with a correct title is not a bug.-14. `/rename Something` in grok, then check the node title adopts it — and record WHICH+12. `/rename Something` in grok, then check the node title adopts it — and record WHICHsummary.json key held it. TITLE_KEYS[0] = 'title' is a GUESS; correct it if it differs, andreplace __fixtures__/grok/summary.json with the real file while you are there.-15. Rename the NODE by hand: does grok's own title change (the `/rename` write leg)?-16. Reboot (or `tmux kill-server`) and reopen the project: does the node cold-restore with+13. Rename the NODE by hand: does grok's own title change (the `/rename` write leg)?+14. Reboot (or `tmux kill-server`) and reopen the project: does the node cold-restore with`grok --resume <id>` and land in the SAME conversation, in the right cwd? Note that afteran app restart the session NAME will not resolve until that session's next hook (§8.5).Fixtures the unbuilt features need, modes, restart-17. ~~CAPTURE `signals.json` from a live session.~~ **DONE, 22 sessions (1.0.13, 2026-09-02).** The+15. ~~CAPTURE `signals.json` from a live session.~~ **DONE, 22 sessions (1.0.13, 2026-09-02).** Thekeys are `contextTokensUsed`, `contextWindowTokens` and `contextWindowUsage`; a total DOESappear, in all 22. Fixture at `core/__fixtures__/grok/signals.json`, survey in`evidence/grok-signals.txt`. What a NEW device should still check is the opposite case this itemwas written for: a session whose signals.json lacks `contextWindowTokens` (a future grok, aninterrupted write). The meter must then vanish, not fall back to a guessed window.-18. Settings → Agents → Auto: does the launched command carry `--permission-mode auto`, on a+16. Settings → Agents → Auto: does the launched command carry `--permission-mode auto`, on amachine WITHOUT claude installed? (The claude gate must not touch grok.)-19. Does `--permission-mode acceptEdits` launch cleanly, and what does grok actually do with it+17. Does `--permission-mode acceptEdits` launch cleanly, and what does grok actually do with it(its hook payload only ever reports default/auto/plan/bypassPermissions)? Check aprompt-carrying launch too (transfer / open-agent / spawn-team): the flag must appearBEFORE the `--`.-20. "Restart agent (resume)" on an idle grok node: does it `/quit`, wait for the shell, and+18. "Restart agent (resume)" on an idle grok node: does it `/quit`, wait for the shell, andresume the same session? Is it refused while the node is RUNNING?Skills-21. ~~`grok inspect --json`: are `manage-nodeterm-canvas` and `get-linked-context` listed?~~+19. ~~`grok inspect --json`: are `manage-nodeterm-canvas` and `get-linked-context` listed?~~**ANSWERED on this machine, grok 1.0.13 (2026-09-02): yes.** `get-linked-context` comes back with`vendor: claude` and `compatibilityStatus: enabled`, and `externalCompat.cells` reports`{surface: 'skills', enabled: true, source: 'default'}`. Recorded in@@ -627,10 +617,10 @@ Skills`[compat.claude] skills = false` in `~/.grok/config.toml`, and separately export`GROK_CLAUDE_SKILLS_ENABLED=false`. In each case `NODETERM_CANVAS_CONTROL=1` is still set whilethe skill is undiscoverable — i.e. the shim is armed and mute. Nobody has seen that state.-22. From a grok session, run the canvas shim: does a node appear on the canvas? The path differs+20. From a grok session, run the canvas shim: does a node appear on the canvas? The path differsper surface — LOCAL sessions get `<userData>/canvas-control/nodeterm.sh` (the path writteninto the skill's own SKILL.md), remote SSH sessions get `$HOME/.nodeterm/nodeterm.sh`.-23. CAPTURE the `spawn_subagent` PreToolUse/PostToolUse payloads (Task 11 Step 1). ~~And+21. CAPTURE the `spawn_subagent` PreToolUse/PostToolUse payloads (Task 11 Step 1). ~~And`updates.jsonl` (Task 10 Step 1).~~ **That half is done, and the file was the wrong one:** thereadable conversation is `chat_history.jsonl`, its sibling; `updates.jsonl` is what the hookpayloads advertise, and following the advertisement fails silently. The fixture cut from a real@@ -639,44 +629,44 @@ Skillslinked to a grok node **should both read**. On a new device, check exactly that.SSH-24. Connect an SSH project, then on the host: `cat $HOME/.grok/hooks/nodeterm-status.json`.+22. Connect an SSH project, then on the host: `cat $HOME/.grok/hooks/nodeterm-status.json`.Present, with the `.*` matcher?-25. Does a REMOTE grok node show badges? (Reverse tunnel + remote script.) Its session NAME will+23. Does a REMOTE grok node show badges? (Reverse tunnel + remote script.) Its session NAME willnot resolve — that is the known asymmetry in §8.4, not a new bug.-26. If the host sets GROK_HOME, did the file land there and not in `$HOME/.grok`? NOTE the+24. If the host sets GROK_HOME, did the file land there and not in `$HOME/.grok`? NOTE thetrap: we probe it with `printf %s "${GROK_HOME:-}"` over a NON-LOGIN ssh exec, so a host thatexports GROK_HOME only from `.bashrc` reports EMPTY and silently gets `~/.grok` — the wrongdirectory, with no symptom at all. If it bites, give the probe the login-shell + PATHtreatment `SshProjectManager.connect` uses for the remote `claude --version`.Surfaces-27. Server Edition in a browser: grok badges, unread dot, notch N/A — and now a context meter too+25. Server Edition in a browser: grok badges, unread dot, notch N/A — and now a context meter too(both shells create the signals.json tail). Also confirm the node title does NOT adopt grok'ssession name there (readSessionName is stubbed).-28. Phone: does a grok node appear in the inbox with the right state, AND does its "what it's doing+26. Phone: does a grok node appear in the inbox with the right state, AND does its "what it's doingnow" line now read grok's own phrases ("Reading fichero.txt", "Searching the code")? That linewas absent until the `pre_tool_use` spelling was translated at the shells (§8.3). A claude phraseor a bare tool name appearing there means the vocabulary was bypassed.-29. macOS notch: does the grok mark pulse and bloom while it works, on the black capsule, next to+27. macOS notch: does the grok mark pulse and bloom while it works, on the black capsule, next toclaude's walking critter without looking out of place?-30. Kanban board + card modal: badges, the 💬 comments panel, and the meter row — which now HAS+28. Kanban board + card modal: badges, the 💬 comments panel, and the meter row — which now HASsomething to show on a grok card.Two traps with no code fix — appended so the numbering above stays stable-31. `echo $GROK_HOME` in a nodeterm terminal, then check where the hook file actually went. The app+29. `echo $GROK_HOME` in a nodeterm terminal, then check where the hook file actually went. The appresolves it from the APP's environment, and a GUI launch (Finder/Dock/`.desktop`) never sourcedyour shell rc — so an `export GROK_HOME=…` in `.zshrc`/`.bashrc` splits the two sides andEVERYTHING silently stops working: no badge, no unread, no notification, no session name, noerror (§8.9). Compare a shell launch (`npm start`) with a GUI launch (`open -a nodeterm`): adifference between them IS the trap. Report whether you set the variable at all — that answerdecides whether a login-shell probe gets built.-32. **Shift+Enter in a grok node.** nodeterm remaps it universally to `\x1b\r` (ESC+CR / M-Enter,+30. **Shift+Enter in a grok node.** nodeterm remaps it universally to `\x1b\r` (ESC+CR / M-Enter,`terminalKeyAction` / `SHIFT_ENTER_SEQ`), which is what claude and codex want for "insert anewline, don't submit". Grok's own key handling is unverified here — orca records a`ctrlEnterEncoding: 'csi-u'` for it, i.e. a different encoding family — so check both: doesShift+Enter insert a newline (not submit), and does plain Enter still submit? If the remap fightsgrok, the fix is a per-agent encoding in `terminal-config.ts`, not a global change.-33. **Does a grok elicitation survive its turn end?** Open an ask (whatever produces+31. **Does a grok elicitation survive its turn end?** Open an ask (whatever produces`elicitation_dialog` / `agent_needs_input`) and watch what the node does when the turn finishes.Codex has exactly this shape — its `request_user_input` ends the turn with the question stillopen, the answer arriving as a fresh `UserPromptSubmit` — so `normalizeCodex` marks the ask@@ -685,7 +675,7 @@ Two traps with no code fix — appended so the numbering above stays stablelike codex, a grok node goes green while it is still waiting on you; if it does not, setting theflag would pin NEEDS YOU on a node that genuinely finished. Report which happens — a green nodeover an open question means grok joins the `awaitingInput` path, one line in `normalizeGrok`.-34. **The Grok mark, at 16 px, in BOTH themes.** It is the official mark inlined with+32. **The Grok mark, at 16 px, in BOTH themes.** It is the official mark inlined with`fill="currentColor"` (§8.8), so readability is guaranteed by construction — it takes the labelcolour, black-on-light and white-on-dark, the way xAI uses it. What is *not* guaranteed islegibility at that size: it is a fine diagonal glyph, and thin strokes can turn to mush where the