Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

docs: record the terminal and message-queue work

Vyapak Goyal75df7044dfd2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2277c8ff..0a1f2fdb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,31 @@ All notable changes to this project are documented here. The format is based on
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [Unreleased]
+
+Terminal reliability: the blank pane and the message queue that silently stopped
+delivering are both fixed, and fullscreen gets a proper agent roster.
+
+### Added
+- **Fullscreen agent roster rail.** The horizontal tab bar ran out of room past a handful of agents and hid the operator controls; it's replaced by a left rail — `+ agent` pinned at the top, god agents ungrouped above everything, workers bucketed under repository headers, restore-team and its dismiss chips pinned at the bottom. An isolated agent's cwd is its own git worktree, so a new `mainRepoRoot` helper follows a linked worktree back to its main checkout (cached per cwd) and groups key on the absolute repo root, so two checkouts with the same name stay separate. Notes render on the row (one line per bullet) instead of behind a hover popover, the note editor becomes a textarea so Enter makes a new bullet instead of dropping every bullet but the first, pause/halt/steer come back in fullscreen, god agents render the full Command Center, and drag-to-reorder carries over (confined to an agent's own repository group). The destructive kill button is gone.
+- **`typing` badge — see why a queue is held.** A message queue held by your own unsent text on an agent's prompt used to look identical to an idle agent with nothing to do. Agent cards and the fullscreen roster now show a **"your draft"** badge whenever you have unsubmitted text on that agent's prompt. It's derived at render from the same check the delivery gate uses, so the badge can never disagree with the reason nothing is being delivered.
+- **[`docs/message-queue.md`](./docs/message-queue.md)** — the delivery contract: who may type into an agent's terminal, when, and what automation is never allowed to do to your text.
+
+### Changed
+- **One gate for every automatic writer.** The queue kept breaking because two loops each decided for themselves when it was safe to type into a terminal. The inbox-wake nudge now enqueues like scheduled `/compact` already did, so a single drain loop owns every "is this terminal free?" decision — idle, off cooldown, past boot grace, delivery not paused, no user draft in the way.
+- **Automation never destroys or closes what you own.** A draft or picker block lasts half an hour rather than a minute, and when it expires delivery simply types *after* whatever is on the line (the two fuse into one prompt). Wiping the line first, and sending Escape at an open picker, are both gone — deleting text is worse than garbling one prompt, and we can't verify that Escape closed anything. Both keys remain on the composer's own button, where you asked for them.
+- **Terminal zoom scales the whole pane.** Cmd +/- moved out of `PtyTerminalView` into a shared subscribable module, so it now scales the message composer and the roster along with the terminal instead of leaving them pinned at sizes tuned for a 14" display.
+- **Changing an agent's model within the same provider resumes its session** instead of starting fresh (best-effort — an agent with no recorded session still gets its model changed).
+- **Restore team runs in parallel** and the login-shell capture is memoised, so rebuilding a roster no longer serialises one shell probe per agent. Agents are added in roster order rather than completion order.
+
+### Fixed
+- **Blank terminal pane where typing does nothing.** Three causes, which is why every single-cause fix only half-worked. (a) WebGL is now a lease taken on attach and released on detach — a browser allows only ~16 live contexts and silently discards the oldest past that cap, so restoring a team blew the cap and Chromium killed a background terminal's renderer while its pty, buffer and subscription stayed healthy. (b) `requestInitialPtyRedraw` latches only once the redraw actually succeeds, instead of burning the terminal's one chance on a failed fire-and-forget IPC. (c) The needs-repaint marker is cleared only after the refresh returns, so a throw no longer discards the last record that the terminal needed repainting.
+- **Message queue silently stopped delivering to an agent.** (a) Only a *bare* command opens a picker — `/model` prompts you to choose, `/model sonnet` applies the argument and returns to the prompt; first-token matching latched the block on both and the submitting Enter couldn't clear it. (b) The picker block now expires like the draft block does, so a picker closed in a way we can't observe no longer wedges the queue for the rest of the session. (c) `lineBuf` moved onto the pool entry and is reset everywhere `inputDirty` is — as a closure variable it survived a draft clear, so the next keystroke recomputed the block from text that had just been deleted.
+- **Phantom drafts blocked delivery against text that didn't exist.** `inputDirty` is inferred by counting keystrokes, and a TUI that swallows keys for its own UI leaves it set while the prompt is visibly empty. The prompt is now read from xterm's rendered buffer (cursor row, prompt chrome stripped) — deliberately one-directional: the screen can only *clear* a phantom draft, never invent one, because being wrong the other way would type over something you really wrote.
+- **A queued message could be typed into an open picker and acked as delivered.** Clearing the input line no longer clears the picker latch — Ctrl-U kills the input line, it does not close a menu — so automation is no longer told the prompt is free while a picker still owns it.
+- **A model or command change died on reload.** `updateAgent` now persists when a durable field changes (volatile run-state fields — status, action, progress, context counters — still skip the write, so a burst of terminal output doesn't rewrite storage).
+- **The roster stopped spawning `git rev-parse` on every chunk of terminal output** — failed and in-flight repo lookups are cached, so an agent outside a repo is looked up once.
+
## [0.2.7] — 2026-06-13
A feature release: talk to your agents with your voice, an opt-in enterprise Knowledge
diff --git a/DESIGN.md b/DESIGN.md
index 54076a47..4c4bc4c7 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -85,9 +85,13 @@ Saturated and warm. Each avatar gets one — the strip badge, the agent's chat s
| `status-idle` | `#A899B5` | Agent at desk, awaiting |
| `status-thinking` | `#4ECDC4` | Reasoning + en route to a station |
| `status-working` | `#FFD93D` | At a station, using a tool |
+| `status-waiting` | `#6C8EF5` | Worker stalled on god or another agent |
| `status-blocked` | `#FF6B6B` | Notification fired, needs user |
| `status-success` | `#6BCF7F` | Just finished |
| `status-ghost` | `#D9CFE0` | Pane closed, fading out |
+| `status-compacting` | `#9B7EDE` | Boxing up context (PreCompact/PostCompact) |
+| `status-looping` | `#FF9F43` | Circuit breaker armed — runaway |
+| `status-typing` | `#E8A33D` | **Not an agent state.** *You* have unsent text on that agent's prompt, which is holding its message queue |
### 3.5 World (the floor itself)
@@ -271,7 +275,8 @@ Destructive: fill = coral, text = cream-50
```
Props:
- status 'idle' | 'thinking' | 'working' | 'blocked' | 'success' | 'ghost'
+ status 'idle' | 'thinking' | 'working' | 'waiting' | 'blocked' | 'success'
+ | 'ghost' | 'compacting' | 'looping' | 'typing'
label string
icon? IconName
@@ -279,6 +284,13 @@ Anatomy: 8 px tall pixel dot + space-1 + lowercase Pixelify Sans 14 px.
Color: status palette. Background: status-color at 20% opacity over cream-100.
```
+Labels are not the token names — they read from the *user's* side. `blocked` shows
+"needs you" (reserved for the god agent waiting on you), `waiting` stays "waiting"
+(honest about the worker being stalled on another agent), and `typing` shows
+**"your draft"** — it is your text on the prompt, not the agent's, and it is why
+that agent's message queue is not draining. See
+[`docs/message-queue.md`](./docs/message-queue.md).
+
### 7.4 `<AgentCard>` (bottom strip)
```
diff --git a/README.md b/README.md
index a8fe736a..21af37ce 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,7 @@ terminal/event plane, and [`DESIGN.md`](./DESIGN.md) for the visual system.
| **Task kanban** | Dependency-aware kanban board in the Command Center Tasks tab — assign tasks to agents, track status across todo/doing/blocked/done, wire dependencies so work starts in order. |
| **Scheduled missions & heartbeat** | Recurring auto-dispatch missions with label, interval, target agent, and body — plus a scheduler heartbeat that re-engages the floor when it goes quiet. Missions now live in their own Schedules tab with last/next-fired times. |
| **Terminal work-order handoff** | Providers without an inbox-drain hook receive hive mail as a `WORK ORDER FROM HIVE` typed into their terminal; if the renderer is unavailable, the message bounces to the GOD agent instead of disappearing. |
+| **Message queue that respects your prompt** | Park messages for a busy agent; one drain loop delivers them the moment it goes idle. Every automatic writer — queued messages, inbox wake-ups, scheduled `/compact` — goes through that one gate, so nothing ever lands on top of a line you're mid-way through writing. Unsent text of yours badges the agent **"your draft"** so a held queue never looks like an idle agent. See [`docs/message-queue.md`](./docs/message-queue.md). |
| **Slack/webhook ingress** | Slack and generic webhook ingress expose local endpoints through tunnelmole, so POSTs pass straight through and failed tunnels surface a real error instead of a silent broken URL. |
| **GitHub ingestion** | Pull open issues from any registered repo via the `gh` CLI and assign them to agents with one click from the Command Center. |
| **CI status watcher** | Live pass/fail/in-progress status for GitHub Actions runs, visible in the Activity tab for every registered repo. |
@@ -244,6 +245,7 @@ docs/ `logo.png`, `banner.png`, landing page (GitHub Page
docs/media/ `og.png` (social previews) + rendered Remotion clips
landing-remotion/ Remotion project that renders the landing page's "how it works" clips
HIVE.md · SPEC.md · DESIGN.md multi-agent · terminal/event · visual design
+docs/message-queue.md who may type into an agent's terminal, and when
```
## Design system
diff --git a/docs/message-queue.md b/docs/message-queue.md
new file mode 100644
index 00000000..c93d2611
--- /dev/null
+++ b/docs/message-queue.md
@@ -0,0 +1,126 @@
+# The message queue — how anything gets typed into an agent's terminal
+
+Every agent runs a real CLI in a real PTY. That CLI has exactly one input line, and
+you are not the only one who wants it: you type into the terminal directly, and the
+harness also has messages of its own to deliver. This document is the contract for
+who gets that line and when.
+
+Two different queues get called "the queue". They are not the same thing:
+
+| Name | Lives in | Holds |
+|---|---|---|
+| **MD queue** | the harness (zustand store, per agent) | messages parked by *Munder Difflin* until that agent's terminal is free |
+| **Claude queue** | inside Claude Code itself | text Claude Code has accepted but not started on yet |
+
+Everything below is about the **MD queue**. The harness cannot see the Claude queue
+and never reasons about it.
+
+---
+
+## 1. One gate
+
+There is exactly one place that types an automatic message into a PTY: the **drain
+loop**, `useHive.ts` effect #4. Everything that wants to reach an agent enqueues
+into the MD queue and lets the drain decide when.
+
+```
+composer / Slack ingress ─┐
+inbox nudge (effect #3) ──┼──▶ enqueueMessage(agentId, text) ──▶ MD queue ──▶ drain (#4) ──▶ PTY
+scheduled /compact (#6) ──┘
+```
+
+This is load-bearing. When the inbox nudge wrote straight into the terminal, it was
+a second writer with its own idea of when the prompt was free — and its text landed
+on top of a half-written line, so the nudge and the user's sentence were submitted
+together as one garbled prompt. Routing it through the queue means one loop owns
+every "is this terminal free?" decision, and the nudge needs no prompt logic of its
+own.
+
+The drain runs on every store change (debounced 200 ms, so a burst of PTY output
+coalesces) plus a 3 s backstop tick.
+
+## 2. What the drain checks
+
+The front of an agent's MD queue is delivered only when **all** of these hold:
+
+| Condition | Why |
+|---|---|
+| agent status is `idle` | don't interrupt a running turn |
+| auto-delivery not paused | per-agent control switch |
+| past the boot grace window | the CLI is still painting its banner |
+| `isTerminalAutomationSafe(ptyId)` | the user owns the prompt — see below |
+| 4.5 s since the last delivery to this agent | back-to-back sends jam the TUI |
+
+Delivery is acknowledged only after both PTY writes (the text, then the submit) have
+succeeded. A failure leaves the message visible in the queue and it retries.
+
+## 3. The user owns the prompt
+
+`isTerminalAutomationSafe` is the gate that protects your typing. It refuses
+delivery while any of these is true (`terminalAutomation.ts`):
+
+| Block | Set by | Cleared by |
+|---|---|---|
+| `exited` | the PTY died | respawn |
+| `picker` | you submitted a bare `/model`-style command that opens a menu | an Enter / Escape / Ctrl-C typed into that terminal, or expiry |
+| `draft` | you have unsubmitted text on the prompt | submitting or clearing it, or expiry |
+| `settling` | a short repaint window after the line was freed | time |
+
+Both `picker` and `draft` expire after **30 minutes** (`STALE_PICKER_MS`,
+`STALE_INPUT_MS`). The expiry exists because both flags are inferred, not reported —
+a picker closed some way we can't observe, or a draft flag left set by a TUI that
+swallowed keys, would otherwise wedge that agent's MD queue for the rest of the
+session.
+
+Two rules about what happens when a block expires:
+
+- **Automation never erases your text.** Expiry means the queued message is typed
+ *after* whatever is on the line; the two fuse into one prompt. An earlier version
+ sent Ctrl-U first, which silently destroyed real drafts that had merely been left
+ alone for a minute.
+- **Automation never closes your menu.** We do not send Escape at a picker. You may
+ have opened it deliberately and stepped away; taking it down to make room for a
+ queued message is not the harness's call, and we cannot verify that Escape worked
+ anyway. The composer has a button that does it — because then *you* asked.
+
+Both windows are long on purpose. Treating a live draft as abandoned is the
+expensive mistake; leaving a queued message parked a while longer is the cheap one.
+
+## 4. Reading the prompt instead of modelling it
+
+`inputDirty` is inferred by counting keystrokes in `term.onData`. That model drifts:
+a TUI that eats keys for its own UI leaves the count above zero while the prompt is
+visibly empty — a **phantom draft**, which blocks the MD queue against text that
+does not exist.
+
+xterm already holds the rendered screen, so `promptLineHasText` reads it directly
+(`term.buffer.active`, the row at `baseY + cursorY`, stripped of prompt chrome).
+
+It is deliberately **one-directional**: the buffer read can only *clear* a draft,
+never invent one.
+
+- screen says empty ⇒ believe it, drop the block
+- screen says text, or cannot be read ⇒ fall back to the keystroke count
+
+Wrong in the clearing direction costs a fused prompt. Wrong the other way would type
+over something you really wrote.
+
+## 5. Seeing why nothing is being delivered
+
+A held MD queue used to look exactly like an idle agent with nothing to do. The
+`typing` badge (`--cth-status-typing`, label **"your draft"**) fixes that: it renders
+on agent cards and in the fullscreen roster whenever `hasTerminalDraft(ptyId)` is
+true.
+
+It is not an agent status and is never stored on the agent — the PTY parser owns
+that field and would overwrite it. It is derived at render from the same function
+the gate uses, so the badge can never disagree with the reason delivery is held.
+
+## 6. Where the code lives
+
+| File | Role |
+|---|---|
+| `src/renderer/src/components/terminalAutomation.ts` | pure policy — blocks, expiry windows. No DOM, fully unit-tested (`test/terminal-automation.test.cjs`) |
+| `src/renderer/src/components/terminalPool.ts` | the pooled xterm per PTY; buffer reads, latches, `isTerminalAutomationSafe`, `hasTerminalDraft` |
+| `src/renderer/src/hooks/useHive.ts` | effect #3 inbox nudge (enqueues), effect #4 drain (the one writer), effect #6 scheduled `/compact` |
+| `src/renderer/src/store/store.ts` | the MD queues themselves + agent persistence |