FE-735: Mode shell and fixture driver (M1) by lunelson · Pull Request #144 · hashintel/brunch

lunelson · 2026-05-21T10:10:51Z

FE-735: Add print snapshot transport shell

FE-735: Add named JSON-RPC stdio skeleton

FE-735: Project elicitation exchanges from JSONL

FE-735: Project real Pi JSONL exchanges

FE-735: Scope session exchange RPC to current session

FE-735: Add RPC print snapshot parity smoke

FE-735: Add fixture capture bundle skeleton

FE-735: Seed deterministic fixture briefs

FE-735: Scope capture seam review fixes

FE-735: Stabilize current session capture

FE-735: Reconcile fixture brief format docs

FE-735: Use Pi session entry types for exchange projection

FE-735: Report Brunch-owned fixture metadata version

FE-735: Capture scripted brief runs

lunelson · 2026-05-21T10:11:08Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

This stack of pull requests is managed by Graphite. Learn more about stacking.

cursor · 2026-05-27T16:31:06Z

PR Summary

Medium Risk
Touches core boot/session selection and new stdio RPC surface; risk is mitigated by coordinator seam, tests, and runbook, but wrong session reopen or projection drift would break fixtures and headless clients.

Overview
Delivers M1 (mode shell + fixture driver): the Brunch CLI now dispatches --mode print (workspace snapshot, no agent turn) and --mode rpc (newline JSON-RPC over stdio) through the same host and WorkspaceSessionCoordinator, with named workspace.snapshot and session.elicitationExchanges handlers that project product state from Pi JSONL—not raw file paths.

Adds elicitation exchange projection from transcript entries (prompt/response spans, open-prompt detection), fixture brief loading (JSON under .brunch-fixtures/briefs/), and capture that copies the coordinator-selected session JSONL plus .meta.json (driver mode, projection summary, deferred graph/coherence). Coordinator changes persist currentSessionFile in .brunch/state.json, reopen the selected session on headless paths, and support createNewSpec for scripted brief runs.

Golden fixtures: three curated briefs and scripted-001 replay bundles; docs/plan/spec updated (YAML→JSON briefs, transport vs agent mode, M1 complete → jsonl-session-viability active). runbooks/verify-m1.sh and broad unit/integration tests cover RPC contracts, print/RPC parity, capture, and replay projection parity.

^{Reviewed by Cursor Bugbot for commit e32eb02. Bugbot is set up for automated code reviews on this repo. Configure here.}

augmentcode · 2026-05-27T16:34:50Z

🤖 Augment PR Summary

Summary: This PR delivers M1 “mode shell + fixture driver” support by adding headless transport modes and the first deterministic fixture capture loop.

Changes:

Adds runBrunchCli() with --mode print (snapshot-only) and --mode rpc (newline JSON-RPC over stdio), while keeping TUI mode intact.
Introduces a product-shaped WorkspaceSnapshot projection and a human-readable print renderer.
Adds a minimal JSON-RPC adapter with named methods (workspace.snapshot, session.elicitationExchanges) scoped to the coordinator-selected session.
Implements elicitation-exchange projection over Pi JSONL transcripts and disk loader utilities.
Adds fixture brief library loading (JSON briefs) and a fixture capture path that writes .jsonl + .meta.json bundles.
Seeds three deterministic briefs and commits scripted capture bundles under .brunch-fixtures/.
Extends the workspace session coordinator to persist/reopen the selected session file via .brunch/state.json.
Adds a runbook (runbooks/verify-m1.sh) plus unit tests covering print/RPC parity and fixture replay/projection parity.

Technical notes: The RPC surface is intentionally thin (named method families over projections), and print mode is treated as a transport proof-of-life rather than an agent turn.

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

augmentcode · 2026-05-27T16:35:15Z

+): Promise<WorkspaceSessionReadyState["session"]> {
+  await ensureWorkspaceDirs(cwd)
+  const files = await listSessionFiles(cwd)
+  const manager = currentSessionFile


currentSessionFile is read from .brunch/state.json, so a stale/tampered path here can throw (breaking print/RPC) and also cause bindSessionToSpec to rewrite an unexpected file. Consider guarding that it exists and is within .brunch/sessions/ (and falling back when invalid) before calling SessionManager.open().

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode · 2026-05-27T16:35:15Z

+}
+
+function isPromptSideEntry(entry: SessionEntry): boolean {
+  if (isCustomTranscriptEntry(entry) && entry.customType.includes("prompt")) {


isPromptSideEntry() only treats custom(_message) entries as prompt-side when customType contains "prompt", so other model-visible injected custom_message entries (e.g. brunch/world_update/v1) would be omitted from promptEntryIds/ranges. If those injections are meant to be part of the prompt span between user turns, the current projection will silently drop them.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e32eb02. Configure here.}

cursor · 2026-05-27T16:38:02Z

+
+  const role = roleOf(entry)
+  return role === "assistant" || role === "toolResult"
+}


Prompt-side classification uses fragile substring match

Medium Severity

isPromptSideEntry uses customType.includes("prompt") as a substring match, while isResponseSideEntry uses an explicit Set (STRUCTURED_RESPONSE_TYPES). This asymmetry means any future custom entry type containing "prompt" anywhere in its name (e.g. brunch.prompt_history, brunch.user_prompt_feedback) would silently be classified as prompt-side, potentially corrupting exchange projections. The response side is already guarded against this with an allowlist pattern.

Additional Locations (1)

src/elicitation-exchange.ts#L10-L15

^{Reviewed by Cursor Bugbot for commit e32eb02. Configure here.}

cursor · 2026-05-27T16:38:03Z

+)
+workspace.session.manager.appendMessage({ role: "user", content: "Runbook response" })
+await coordinator.bindCurrentSpecToSession(workspace.session.manager)
+NODE


Runbook setup failure silently skipped without error check

Low Severity

The workspace setup block (the node heredoc that creates a temp workspace, appends entries, and binds the spec) runs outside run_check and without set -e. If this step fails, the exit code is silently ignored and subsequent run_check blocks (print-mode smoke, RPC smoke) run against a broken or empty workspace, producing misleading failure messages instead of attributing the root cause.

^{Reviewed by Cursor Bugbot for commit e32eb02. Configure here.}

lunelson added 14 commits May 21, 2026 10:51

FE-735: Add print snapshot transport shell

b68326b

FE-735: Add named JSON-RPC stdio skeleton

3fb6ad2

FE-735: Project elicitation exchanges from JSONL

593e0d7

FE-735: Project real Pi JSONL exchanges

3f3f12b

FE-735: Scope session exchange RPC to current session

678f988

FE-735: Add RPC print snapshot parity smoke

130c165

FE-735: Add fixture capture bundle skeleton

10fd250

FE-735: Seed deterministic fixture briefs

49f8fc5

FE-735: Scope capture seam review fixes

a302a20

FE-735: Stabilize current session capture

0d756f2

FE-735: Reconcile fixture brief format docs

77b2899

FE-735: Use Pi session entry types for exchange projection

100cb70

FE-735: Report Brunch-owned fixture metadata version

7c42152

FE-735: Capture scripted brief runs

d6054ec

lunelson mentioned this pull request May 21, 2026

FE-702: Walking skeleton — brunch binary + TUI over pi (M0) #142

Open

lunelson added 4 commits May 21, 2026 12:27

FE-735: Bind scripted captures per brief

a1f63ca

FE-735: Project tool results as prompt entries

3ac5ccd

FE-735: Add M1 verification runbook

436db26

FE-735: Reconcile M1 fixture verification

e32eb02

This was referenced May 21, 2026

FE-736: JSONL session viability proof (M2) #146

Open

FE-737: Web shell over the same host (M3) #147

Open

FE-744: Document Pi command containment evidence #150

Draft

lunelson changed the title ~~FE-735: Add print snapshot transport shell~~ FE-735: Mode shell and fixture driver (M1) May 27, 2026

lunelson marked this pull request as ready for review May 27, 2026 16:31

augmentcode Bot reviewed May 27, 2026

View reviewed changes

cursor Bot reviewed May 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FE-735: Mode shell and fixture driver (M1)#144

FE-735: Mode shell and fixture driver (M1)#144
lunelson wants to merge 18 commits into
ln/fe-729-walking-skeletonfrom
ln/fe-735-mode-shell-fixture-driver

lunelson commented May 21, 2026

Uh oh!

lunelson commented May 21, 2026 •

edited

Loading

Uh oh!

cursor Bot commented May 27, 2026 •

edited

Loading

Uh oh!

augmentcode Bot commented May 27, 2026

Uh oh!

augmentcode Bot left a comment

Uh oh!

augmentcode Bot May 27, 2026 •

edited

Loading

Uh oh!

augmentcode Bot May 27, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot May 27, 2026

Uh oh!

cursor Bot May 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

lunelson commented May 21, 2026

Uh oh!

lunelson commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

augmentcode Bot commented May 27, 2026

Uh oh!

augmentcode Bot left a comment

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot May 27, 2026

Choose a reason for hiding this comment

Prompt-side classification uses fragile substring match

Uh oh!

cursor Bot May 27, 2026

Choose a reason for hiding this comment

Runbook setup failure silently skipped without error check

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

lunelson commented May 21, 2026 •

edited

Loading

cursor Bot commented May 27, 2026 •

edited

Loading

augmentcode Bot May 27, 2026 •

edited

Loading

augmentcode Bot May 27, 2026 •

edited

Loading