Skip to content

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.

fix(grok): drop a compaction claim the capture contradicts, and stop StopFailure failing to a stuck badge

Xavi Guardia12af5f69de79
diff --git a/src/core/agents/hooks/grok.ts b/src/core/agents/hooks/grok.ts
index 23643b049..6a93f1198 100644
--- a/src/core/agents/hooks/grok.ts
+++ b/src/core/agents/hooks/grok.ts
@@ -3,10 +3,10 @@
// file outright and rewrites it. We still route through the shared install helper, because that is
// where the missing-script guard, the idempotent re-install and the "sweep events we no longer
// subscribe to" repair live.
-import path from "path"
-import type { ManagedHookEvent } from "../../../shared/agents/hook-events"
-import { GROK_HOOK_FILE, grokHomeDir } from "../grok-paths"
-import { installHooksInto, removeHooksFrom } from "./install-helper"
+import path from 'path'
+import type { ManagedHookEvent } from '../../../shared/agents/hook-events'
+import { GROK_HOOK_FILE, grokHomeDir } from '../grok-paths'
+import { installHooksInto, removeHooksFrom } from './install-helper'
const SCRIPT_FILE_NAME = "grok.sh"
@@ -14,8 +14,12 @@ const SCRIPT_FILE_NAME = "grok.sh"
* Complete Grok 1.0.13 hook set, measured against
* `~/.grok/docs/user-guide/10-hooks.md:84-106`. Keep all fifteen here: omitting an event makes its
* normalizer unreachable, which is how StopCancelled existed but Esc left RUNNING stuck.
- * PreCompact/PostCompact are identity-bearing even when they do not move the badge: Grok mints a
- * new session id during compaction, and both shells must observe it for continuity.
+ * PreCompact/PostCompact are subscribed for their own sake, not for session identity. An earlier
+ * version of this comment claimed grok mints a new session id during compaction and that both shells
+ * must observe it. It does not: in the captured pair (1.0.13, 2026-09-01) `pre_compact` and
+ * `post_compact` carry the SAME `sessionId`, and `docs/grok-agent.md`'s own dialect table already
+ * said there is no id to re-key an association with. The claim was never measured; it read like a
+ * measurement, and a branch was written against it.
*/
export const GROK_EVENTS: readonly ManagedHookEvent[] = [
'SessionStart',
diff --git a/src/core/grok-hook-session.test.ts b/src/core/grok-hook-session.test.ts
index 79256156b..23e9504b4 100644
--- a/src/core/grok-hook-session.test.ts
+++ b/src/core/grok-hook-session.test.ts
@@ -8,7 +8,7 @@ describe('planGrokHookSession', () => {
['SubagentStart', 'subagent_start', 'subagentstart', 'gs-before', undefined],
['SubagentStop', 'subagent_stop', 'subagentstop', 'gs-before', undefined],
['PreCompact', 'pre_compact', 'precompact', 'gs-before', undefined],
- ['PostCompact', 'post_compact', 'postcompact', 'gs-after', 'gs-before']
+ ['PostCompact', 'post_compact', 'postcompact', 'gs-after', undefined]
])(
'%s produces the shell-independent session transition',
(_name, hookEventName, event, sessionId, forgetSessionId) => {
@@ -23,18 +23,36 @@ describe('planGrokHookSession', () => {
}
)
- it('does not retire a session when PostCompact repeats its current id', () => {
+ it('NEVER retires a session on PostCompact, not even when the id differs', () => {
+ // There used to be a branch here retiring the previous id, written on the belief that grok mints
+ // a new one when it compacts. Measured on 1.0.13: it does not — the captured `pre_compact` and
+ // `post_compact` carry the same `sessionId`. So the branch could not fire, and the belief came
+ // from a comment rather than from data.
+ //
+ // This asserts the case that branch existed for — a DIFFERENT id — precisely because that is the
+ // input under which the old code did something. Restoring it turns this red.
+ expect(
+ planGrokHookSession(
+ { hook_event_name: 'post_compact', session_id: 'gs-after', cwd: '/w/project' },
+ 'gs-before'
+ ).forgetSessionId
+ ).toBeUndefined()
+ // And the ordinary case, where the id repeats, is unchanged.
expect(
planGrokHookSession(
{ hook_event_name: 'post_compact', session_id: 'gs-current', cwd: '/w/project' },
'gs-current'
- )
- ).toEqual({
- event: 'postcompact',
- sessionId: 'gs-current',
- cwd: '/w/project',
- forgetSessionId: undefined
- })
+ ).forgetSessionId
+ ).toBeUndefined()
+ })
+
+ it('SessionEnd is the only event that retires an id', () => {
+ expect(
+ planGrokHookSession(
+ { hook_event_name: 'session_end', session_id: 'gs-1', cwd: '/w/project' },
+ 'gs-1'
+ ).forgetSessionId
+ ).toBe('gs-1')
})
it.each(['desktop', 'server'])('%s applies all six new events through the same behavioral seam', (_shell) => {
@@ -44,7 +62,7 @@ describe('planGrokHookSession', () => {
['subagent_start', 'gs-before', undefined],
['subagent_stop', 'gs-before', undefined],
['pre_compact', 'gs-before', undefined],
- ['post_compact', 'gs-after', 'gs-before']
+ ['post_compact', 'gs-after', undefined]
] as const
for (const [hookEventName, sessionId, forgotten] of cases) {
diff --git a/src/core/grok-hook-session.ts b/src/core/grok-hook-session.ts
index 1f1b175eb..9131b04c9 100644
--- a/src/core/grok-hook-session.ts
+++ b/src/core/grok-hook-session.ts
@@ -25,12 +25,15 @@ export function planGrokHookSession(
previousSessionId: string | undefined
): GrokHookSessionPlan {
const { event, sessionId, cwd } = grokRawFields(payload)
- const forgetSessionId =
- event === 'postcompact' && sessionId && previousSessionId && previousSessionId !== sessionId
- ? previousSessionId
- : event === 'sessionend'
- ? sessionId
- : undefined
+ // SessionEnd is the only event that retires an id.
+ //
+ // There used to be a PostCompact branch here, retiring the PREVIOUS id on the belief that grok
+ // mints a new one when it compacts. Measured: it does not. The captured pair carries the same
+ // `sessionId` in `pre_compact` and `post_compact`, so the branch could not fire — and the belief
+ // came from a comment, not from data. Removed rather than kept as a defensive guard: a branch
+ // that cannot be exercised is one nobody can prove or disprove, and in six months it reads as a
+ // measurement again. This one already did — it was cited as evidence in a rebase decision.
+ const forgetSessionId = event === 'sessionend' ? sessionId : undefined
return { event, sessionId, cwd, forgetSessionId }
}
diff --git a/src/shared/agents/normalize.grok.test.ts b/src/shared/agents/normalize.grok.test.ts
index 1409f79dd..81016b36e 100644
--- a/src/shared/agents/normalize.grok.test.ts
+++ b/src/shared/agents/normalize.grok.test.ts
@@ -90,8 +90,22 @@ describe('normalizeGrok — Stop', () => {
).toMatchObject({ state: 'done', lastMessage: error })
})
- it('an unrecognized stop_failure error type is a no-op', () => {
- expect(normalizeGrok(env({ hookEventName: 'stop_failure', error: 'future_error' }))).toBeNull()
+ it.each([
+ ['a future dialect', 'future_error'],
+ ['an absent class', undefined],
+ ['an empty class', '']
+ ])('stop_failure with %s STILL ends the turn — the node must not stay RUNNING', (_name, error) => {
+ // This used to return null, on the closed-vocabulary discipline the rest of this file follows.
+ // That discipline is for values that DECIDE something; this one decides nothing — every class
+ // ends the turn. Gating on it left the node on RUNNING until the idle_prompt backstop, or
+ // forever if none arrived: the silent half of the failure, the one nobody reports because
+ // nothing looks broken.
+ //
+ // Asserted as `done` and NOT as "not null", because "not null" would also pass if some future
+ // edit returned `working` here — which is the very state this exists to prevent.
+ const out = normalizeGrok(env({ hookEventName: 'stop_failure', sessionId: 's1', error }))
+ expect(out).toMatchObject({ kind: 'state', state: 'done' })
+ expect(out?.state).not.toBe('working')
})
})
diff --git a/src/shared/agents/normalize.ts b/src/shared/agents/normalize.ts
index dc2e09cbe..45e3a14b4 100644
--- a/src/shared/agents/normalize.ts
+++ b/src/shared/agents/normalize.ts
@@ -627,15 +627,6 @@ interface GrokPayload {
*/
const grokCanonical = (v: string | undefined): string => (v ?? '').toLowerCase().replace(/[^a-z]/g, '')
-const GROK_STOP_FAILURE_TYPES = new Set([
- 'ratelimit',
- 'authenticationfailed',
- 'invalidrequest',
- 'servererror',
- 'maxoutputtokens',
- 'unknown'
-])
-
const GROK_CANCEL_REASONS: Record<string, NonNullable<NormalizedAgentEvent['cancelReason']>> = {
userinterrupt: 'user_interrupt',
permissionrejected: 'permission_rejected',
@@ -708,13 +699,24 @@ export function normalizeGrok(env: RawHookEnvelope): NormalizedAgentEvent | null
? { ...base, kind: 'state', state: 'done', lastMessage }
: { ...base, kind: 'state', state: 'done', interrupted: true }
}
- // The turn died on an API error — grok skips Stop entirely here, exactly as Claude does. The
- // matcher vocabulary is closed in grok 1.0.13; a future value is a no-op rather than a guessed
- // terminal state.
- if (ev === 'stopfailure') {
- if (!GROK_STOP_FAILURE_TYPES.has(grokCanonical(p.error))) return null
- return { ...base, kind: 'state', state: 'done', lastMessage }
- }
+ // The turn died on an API error — grok skips Stop entirely here, exactly as Claude does.
+ //
+ // THE EVENT IS THE TURN END, whatever its error class. This used to return null for a class
+ // outside the documented six, on the "closed vocabulary" reasoning applied everywhere else in this
+ // file. That reasoning is right for a value that DECIDES something and wrong here, because the
+ // class decides nothing: every branch of it ends the turn. Gating on it meant an absent or
+ // future-dialect `error` left the node stuck on RUNNING until the idle_prompt backstop, or forever
+ // if none came — the silent half of the failure, the one nobody reports because nothing looks
+ // broken. Grok's own docs make `unknown` the catch-all, so a value outside the set can only be a
+ // dialect we have not seen, and the turn has ended either way.
+ //
+ // The documented classes (1.0.13, `10-hooks.md:162`) are `rate_limit`, `authentication_failed`,
+ // `invalid_request`, `server_error`, `max_output_tokens` and `unknown` — recorded here because
+ // they are measured and worth keeping, and NOT kept as a Set, because nothing branches on them and
+ // a set nothing reads is the same dead weight the PostCompact branch was. The day one of them
+ // earns a distinct badge, that is where the set comes back — and it must still fall through to
+ // `done`, never to null.
+ if (ev === 'stopfailure') return { ...base, kind: 'state', state: 'done', lastMessage }
if (ev === 'permissiondenied') return { ...base, kind: 'state', state: 'working' }
if (ev === 'stopcancelled') {
const cancelReason = GROK_CANCEL_REASONS[grokCanonical(p.reason)]