feat(grok): add Grok Build adapter (hooks, settings, session parse/tail, upstream pin)

[darko-mijic]

What this adds

Grok Build becomes a second supported agent harness, attach-only, next to Claude.

You get hook envelopes and settings validation, session discovery under GROK_HOME, parsers for updates.jsonl and events.jsonl, and a checkpointed two-source tail with rewind. The public surface is @libar-dev/agent-harness-kit/grok and @libar-dev/agent-harness-kit/grok/processing. Claude exports stay byte-identical.

It does not start or drive Grok. There is no Claude-to-Grok translator and no shared session-block model.

Use it

const grok = await import('@libar-dev/agent-harness-kit/grok')
const processing = await import('@libar-dev/agent-harness-kit/grok/processing')

Cockpit currently pins 3c914e4 for the adapter code. This branch tip also archives the finished plan to .plans/01-grok-adapter.md.

Workspace state

.omo/ is live-only. Finished plans go to .plans/NN-slug.md. Boulder, drafts, senpi-task, and evidence dumps stay out of the public tree. A fresh /start-work copies the archived plan back to .omo/plans/ with boxes unchecked and deletes runtime first.

Follow-up after first review

These landed after Greptile last reviewed 4322a93:

• Rewind keeps unlabeled later chunks on the kept prompt (currentPromptIndex = targetPromptIndex).
• fromStart after a reset advances generation so the marker can commit.
• Unknown tags stay in the tail as unknown native records instead of being dropped.
• Discovery returns the real IO error instead of a synthetic Zod "Required".
• Stale marker lock dirs older than 30s are recovered once.

Verification

• pnpm run test:run — 1730 tests / 56 files
• pnpm run type-check, pnpm run lint, pnpm run build — exit 0
• Real-machine QA: all 15 hook-envelope fixtures validate; tailing a copy of a real ~/.grok session (11,682 records) is byte-identical across runs with 0 invalid lines; sync-upstream-grok.mjs --check exit 0
• Note: tsx 4.21.0 → 4.23.12 (dev-only) clears 7 pre-existing Node 26 DEP0205 failures that also exist at base 6a08ff3

Decisions to sanity-check

• Rewind semantics: the reducer implements strict-after deletes (> target_prompt_index) per the approved plan; upstream replay.rs implements rewind-before-N (>= N). Documented in docs/reference/grok-adapter.md.
• Cardinality: 14 wire events + 1 legacy alias = 15 accepted wire values (GrokHookEventName.length === 15, drift-test pinned).
• blake3 via @noble/hashes for >255-byte cwd slugs — recorded in docs/upstream/grok/pin.json.

Greptile Summary

Adds the Grok Build adapter for hooks and persisted session processing, including discovery, JSONL tailing, normalized blocks, checkpoints, package exports, documentation, and examples.

The previously reported tool-status issue in src/grok/processing/blocks.ts is resolved: an executed reducer check showed that a status-only completed update changes the existing tool-use block to completed and produces its completed result.

Confidence Score: 5/5

No blocking failure remains.

No accepted blocking findings remain. The reducer correctly propagates terminal tool status, and checkpointed session tailing preserves accumulated assistant content without replaying unrelated changes.

T-Rex Logs

What T-Rex did

• Ran an authored TypeScript reproduction through the real Grok update parser and block reducer, first with an in-progress tool call and then with a status-only completed update.
• Observed the in-progress tool-use block transition to completed for the same tool-use ID, preserving its title and kind and emitting a completed non-error tool-result.
• Ran the focused Vitest coverage for this exact behavior to validate test coverage and expectations.
• Executed a filesystem-backed session-tail reproduction using persisted Grok JSONL files and automatic checkpoints, and confirmed that appending an assistant chunk yields a single accumulated upsert containing Hello World without replaying past user changes.
• Ran focused tail and block tests for the filesystem-tail scenario, and they passed as part of the verification.

_{Ran code and verified through T-Rex}

_{Reviews (5): Last reviewed commit: "docs: make AGENTS.md the single agent fi..." | Re-trigger Greptile}