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

fix(terminal): don't let an un-echoed keystroke read as an empty prompt

Vyapak Goyal7ca70a1a2761
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0a1f2fdb..0d068f20 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,7 @@ delivering are both fixed, and fullscreen gets a proper agent roster.
### 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.
+- **Automation never destroys or closes what you own.** A draft block lasts half an hour rather than a minute, a picker block half an hour rather than three minutes, and when either 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.
diff --git a/docs/message-queue.md b/docs/message-queue.md
index c93d2611..5928aff2 100644
--- a/docs/message-queue.md
+++ b/docs/message-queue.md
@@ -19,9 +19,14 @@ 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.
+One place types automatic messages into a live agent's PTY: the **drain loop**,
+`useHive.ts` effect #4. Everything that wants to reach a running agent enqueues into
+the MD queue and lets the drain decide when.
+
+(The single exception is the god agent's boot sequence, `useHive.ts:284`, which
+writes its remote-control command and orientation prompt directly. That PTY was
+spawned milliseconds earlier and is covered by the boot-grace window, so there is no
+user draft it could land on.)
```
composer / Slack ingress ─┐
@@ -102,8 +107,17 @@ 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.
+The asymmetry is the point, because the two mistakes don't cost the same. A wrong
+"empty" opens the gate and fuses a queued message onto what you're writing. A wrong
+"has text" only parks that message until the draft expires. So the cheap mistake is
+the one we allow to happen.
+
+One case where the screen is not evidence at all: `inputDirty` is set the moment you
+press a key, but the character only reaches xterm's buffer after the PTY echoes it
+back. Inside that gap the buffer is still showing the previous state, so a read of a
+freshly started draft would return "empty" — the expensive direction. A read within
+`ECHO_GRACE_MS` (1 s) of the last keystroke therefore returns "don't know" and clears
+nothing.
## 5. Seeing why nothing is being delivered
@@ -113,8 +127,13 @@ on agent cards and in the fullscreen roster whenever `hasTerminalDraft(ptyId)` i
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.
+that field and would overwrite it. It is derived at render from the same draft
+detection the gate uses, so the badge is reporting the same draft the gate sees.
+
+It does **not** apply the 30-minute expiry the gate applies. Past that window the
+gate starts delivering while the badge still reads "your draft" — which is honest:
+your text really is still sitting on the prompt. The badge answers "is my text
+there", not "is the queue blocked".
## 6. Where the code lives
diff --git a/src/renderer/src/components/terminalPool.ts b/src/renderer/src/components/terminalPool.ts
index 1c5d8be0..de6b6600 100644
--- a/src/renderer/src/components/terminalPool.ts
+++ b/src/renderer/src/components/terminalPool.ts
@@ -259,13 +259,23 @@ export function acquireTerminal(ptyId: string, theme?: ThemeMap, fontSize = 14):
export function isTerminalAutomationSafe(ptyId: string, now = Date.now()): boolean {
const entry = pool.get(ptyId);
if (!entry) return true;
- return canAutomateTerminal(automationStateOf(entry), now);
+ return canAutomateTerminal(automationStateOf(entry, now), now);
}
/** Characters a TUI paints around its input line that are not the user's text:
* the box the prompt sits in and the prompt marker itself. */
const PROMPT_CHROME = /[─-╿\s>❯$#|]/g;
+/** How long after a keystroke the rendered screen is not yet evidence of anything.
+ *
+ * `inputDirty` is set the instant a key is pressed, but the character only
+ * reaches xterm's buffer once the PTY echoes it back — a round trip through the
+ * child process. Inside that gap the buffer still shows the OLD line, so a read
+ * of a freshly started draft returns "empty" and would hand the prompt to
+ * automation while the user is mid-word. The screen is only allowed to overrule
+ * the keystroke count once it has had time to catch up. */
+const ECHO_GRACE_MS = 1000;
+
/** Does the terminal's rendered prompt line actually hold text right now?
*
* `inputDirty` is inferred by counting keystrokes, and that model DRIFTS: a TUI
@@ -275,13 +285,19 @@ const PROMPT_CHROME = /[─-╿\s>❯$#|]/g;
* arrive" bug. xterm already holds the rendered screen, so read it instead of
* trusting the count.
*
- * Returns null when the screen cannot be read (the terminal has not been opened
- * yet, or the row is missing). Deliberately only ever used to CLEAR a phantom,
- * never to invent a draft: if this says "empty" we believe it, and if it says
- * "has text" or "don't know" we fall back to the keystroke model. Being wrong
- * the other way would type over something the user really did write. */
-function promptLineHasText(entry: TerminalEntry): boolean | null {
+ * Returns null when the screen is not evidence of anything: the terminal has not
+ * been opened, the row is missing, or the last keystroke is too recent for the
+ * echo to have landed. Deliberately only ever used to CLEAR a phantom, never to
+ * invent a draft: "empty" drops the block, while "has text" or "don't know"
+ * falls back to the keystroke model and keeps it. The asymmetry matters because
+ * the two mistakes do not cost the same — a wrong "empty" hands the prompt to
+ * automation and fuses a message onto what the user is writing, where a wrong
+ * "has text" only parks a queued message until the draft expires. */
+function promptLineHasText(entry: TerminalEntry, now = Date.now()): boolean | null {
if (!entry.opened || entry.exited) return null;
+ // Too soon after the last keystroke for the echo to have landed — the buffer
+ // is showing us the past, so it cannot clear anything.
+ if (entry.inputDirtyAt && now - entry.inputDirtyAt < ECHO_GRACE_MS) return null;
try {
const buf = entry.term.buffer.active;
const line = buf.getLine(buf.baseY + buf.cursorY);
@@ -294,13 +310,16 @@ function promptLineHasText(entry: TerminalEntry): boolean | null {
}
/** Whether the user has unsubmitted text sitting on this terminal's prompt.
- * Drives both the automation gate and the roster's "typing" badge, so the badge
- * can never disagree with the reason delivery is being held. */
-export function hasTerminalDraft(ptyId: string | undefined): boolean {
+ * Shares its draft detection with the automation gate, so the "typing" badge
+ * reports the same draft the gate is holding delivery for. It does NOT apply the
+ * staleness expiry the gate does: past STALE_INPUT_MS the gate starts delivering
+ * while this still reports the draft — which is the honest reading, because the
+ * text really is still on the prompt. */
+export function hasTerminalDraft(ptyId: string | undefined, now = Date.now()): boolean {
if (!ptyId) return false;
const entry = pool.get(ptyId);
if (!entry) return false;
- return entry.inputDirty && promptLineHasText(entry) !== false;
+ return entry.inputDirty && promptLineHasText(entry, now) !== false;
}
/** `hasTerminalDraft` as React state. The flag lives on a mutable pool entry
@@ -320,9 +339,9 @@ export function useHasTerminalDraft(ptyId: string | undefined): boolean {
return dirty;
}
-function automationStateOf(entry: TerminalEntry) {
+function automationStateOf(entry: TerminalEntry, now = Date.now()) {
// The screen wins over the keystroke count, but only when it says "empty".
- const inputDirty = entry.inputDirty && promptLineHasText(entry) !== false;
+ const inputDirty = entry.inputDirty && promptLineHasText(entry, now) !== false;
return {
exited: entry.exited,
pickerOpen: entry.automationBlocked,
@@ -349,7 +368,7 @@ export function terminalAutomationBlockFor(
if (!ptyId) return null;
const entry = pool.get(ptyId);
if (!entry) return null;
- return terminalAutomationBlock(automationStateOf(entry), now);
+ return terminalAutomationBlock(automationStateOf(entry, now), now);
}
/** Wipe the TUI prompt's current line and re-arm automation. Ctrl-U is the