Fix Electron startup and duplicate agent output

[khaliqgant]

Summary

• bundle Zod in Electron main so bundled Relay dependencies resolve the expected Zod major
• fix the startup crash from z.iso.datetime() resolving against top-level Zod 3
• send integration state only after a real broker start, not when ensureBroker() reuses an existing session
• dedupe repeated PTY worker_stream chunks from overlapping/rebound dashboard event streams while preserving distinct broker sequences

Verification

• npx vitest run src/main/broker.test.ts
• npm run build

[codeant-ai]

CodeAnt AI is reviewing your PR.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds zod to Vite externalize exclusions; changes BrokerManager.start(...) to return Promise<boolean> indicating whether a broker/session was newly established; adds PTY chunk deduplication with a TTL cache and early-drop in the worker_stream path; IPC handler and tests updated to follow the new semantics.

Changes

Vite Build Configuration

Layer / File(s)	Summary
Zod package externalization exclusion electron.vite.config.ts	The externalizeDepsPlugin in main.plugins now includes zod in its exclude list, preventing the package from being externalized during the build process.

BrokerManager start flow and IPC

Layer / File(s)	Summary
BrokerManager.start signature and completion path src/main/broker.ts	BrokerManager.start(...) now returns Promise<boolean> and callers receive a boolean indicating whether the broker/session was newly established.
In‑flight gate type and existing-session handling src/main/broker.ts	The in-flight startPromises map value type was changed to Promise<boolean>; when a normalized session already exists the start path updates window/cwd/name/state and returns false; awaiting a deduped in‑flight start also returns false after reattaching.
IPC notify gating src/main/ipc-handlers.ts	The broker:start handler captures the boolean result from brokerManager.start(...) and only calls integrationsManager.notifyAgentState(projectId) when the result is truthy.
Local reuse test src/main/broker.test.ts	Adds a test asserting repeated local starts reuse the session: first call reports reused (true), second reports false, spawn happens only once, and the local client is not shut down until manager.shutdown().

PTY deduplication and tests

Layer / File(s)	Summary
PTY dedupe constants and cache src/main/broker.ts	Adds TTL and max-entry constants and a recentPtyChunks Map to bound how long PTY chunks are considered duplicates.
PTY dedupe guard and implementation src/main/broker.ts	Adds isDuplicatePtyChunk(...) (eviction by TTL, max-size enforcement, identity from event_id/seq/id) and an early return guard in the worker_stream PTY fast-path to drop duplicates.
PTY publishing tests src/main/broker.test.ts	Adds tests that verify identical overlapping worker_stream PTY chunks are deduped (single broker:pty-chunk IPC message), identical chunks with different seq produce separate messages, and events lacking identity (seq) are not deduped.

Duplicate-event hardening docs

Layer / File(s)	Summary
Hardening memory and docs .claude/projects/.../MEMORY.md, .claude/projects/.../duplicate-event-hardening.md, AGENTS.md	Adds a memory bullet, a new Duplicate Event Hardening document, and updates AGENTS.md with a checklist and requirements for idempotent lifecycle operations, in‑flight coalescing, stable event identity, generation-scoped listeners, PTY duplicate guarding, and required regression tests.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I nudged a zod into the bundle, snug and neat,
Broker starts now answer true or false — concise and sweet,
Reused sessions linger till shutdown's call,
PTY echoes trimmed so duplicates fall,
A little rabbit hop for tidy code and feat!

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request updates the Electron Vite configuration to exclude the 'zod' package from being externalized by the externalizeDepsPlugin in the main process build. There are no review comments, and I have no feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[codeant-ai]

CodeAnt AI finished reviewing your PR.

[agent-relay-code]

Reviewed PR #89 and found no additional breakage to fix. The config change correctly excludes zod from Electron main dependency externalization so it is bundled into out/main/index.js.

Verified:

• npm ci completed successfully.
• npm test passed: 34 tests, 0 failures.
• npm run build passed.
• Inspected out/main/index.js: zod code is bundled and no require('zod') runtime dependency was found.
• Removed generated ignored artifacts after verification (node_modules, out, relayfile mount binary/version).

[agent-relay-code]

Fixed the validated PR breakage in src/main/broker.ts: startPromises now accepts both local start() promises returning boolean and cloud attach gate promises returning void.

Verified:

• npx vitest run src/main/broker.test.ts passed
• npx vitest run passed, 7 files / 69 tests
• npm test passed, 34 tests
• npm run build passed

A full ad hoc tsc -p tsconfig.node.json --noEmit still reports many unrelated baseline type errors, but the PR-caused startPromises boolean-promise errors are gone.

[agent-relay-code]

✅ pr-reviewer applied fixes — committed and pushed a9a61ff to this PR. The notes below describe what changed.

Fixed the validated PR breakage in src/main/broker.ts: startPromises now accepts both local start() promises returning boolean and cloud attach gate promises returning void.

Verified:

• npx vitest run src/main/broker.test.ts passed
• npx vitest run passed, 7 files / 69 tests
• npm test passed, 34 tests
• npm run build passed

A full ad hoc tsc -p tsconfig.node.json --noEmit still reports many unrelated baseline type errors, but the PR-caused startPromises boolean-promise errors are gone.

[agent-relay-code]

⚠️ pr-reviewer push failed (exit 1) — fixes were not applied to the PR. The notes below are advisory and were not pushed.

Fixed one PR breakage in src/main/broker.ts: startPromises now accepts both startup promises returning boolean and cloud attach gates returning void.

Validation run:

• npm run build passed
• npx --yes vitest run src/main/broker.test.ts passed, 20 tests
• npm test passed, 34 tests

[agent-relay-code]

Fixed one PR regression in PTY dedupe: identity-less worker_stream chunks are no longer deduped by raw content, so valid repeated output is preserved. Identity-based dedupe still suppresses overlapping event-stream duplicates with the same seq/event id.

Added a focused regression test in src/main/broker.test.ts.

Local verification passed:
npm run verify:mcp-resources-drift
npm test
npx vitest run src/main/broker.test.ts
npm run build

[agent-relay-code]

✅ pr-reviewer applied fixes — committed and pushed ff297c6 to this PR. The notes below describe what changed.

Fixed one PR regression in PTY dedupe: identity-less worker_stream chunks are no longer deduped by raw content, so valid repeated output is preserved. Identity-based dedupe still suppresses overlapping event-stream duplicates with the same seq/event id.

Added a focused regression test in src/main/broker.test.ts.

Local verification passed:
npm run verify:mcp-resources-drift
npm test
npx vitest run src/main/broker.test.ts
npm run build

[agent-relay-code]

Fixed one verified PR breakage in src/main/broker.ts: startPromises now accepts both local start promises and the existing cloud attach gate promise, restoring TypeScript compatibility without changing runtime behavior.

Validated locally:

• npx vitest run src/main/broker.test.ts
• npm test
• npm run build
• npm run verify:mcp-resources-drift

[agent-relay-code]

✅ pr-reviewer applied fixes — committed and pushed 4710710 to this PR. The notes below describe what changed.

Fixed one verified PR breakage in src/main/broker.ts: startPromises now accepts both local start promises and the existing cloud attach gate promise, restoring TypeScript compatibility without changing runtime behavior.

Validated locally:

• npx vitest run src/main/broker.test.ts
• npm test
• npm run build
• npm run verify:mcp-resources-drift

[agent-relay-code]

⚠️ pr-reviewer push failed (exit 1) — fixes were not applied to the PR. The notes below are advisory and were not pushed.

Fixed one lifecycle issue I found in the PR: PTY chunk dedupe state is now cleared when a broker session is dropped, so a restarted broker can reuse the same agent name/sequence without having its first real output suppressed. See src/main/broker.ts.

Added a regression test covering the restart case in src/main/broker.test.ts.

Verified locally:

• npx vitest run src/main/broker.test.ts
• npm run verify:mcp-resources-drift
• npm test
• npm run build

[agent-relay-code]

Reviewed PR #89 against .workforce/pr.diff, changed files, context, current checkout, and PR bot comments. No additional validated breakage remained to fix in the current tree.

Local validation passed:

• npx vitest run src/main/broker.test.ts passed, 21 tests
• npx vitest run passed, 72 tests
• npm test passed, 34 tests
• npm run verify:mcp-resources-drift passed
• npm run build passed
• Confirmed built main bundle contains bundled zod code and no direct require("zod")

Removed generated verification artifacts afterward: node_modules, out, bin/relayfile-mount, and bin/.relayfile-mount-version.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #89 against .workforce/pr.diff, changed files, context, current checkout, and PR bot comments. No additional validated breakage remained to fix in the current tree.

Local validation passed:

• npx vitest run src/main/broker.test.ts passed, 21 tests
• npx vitest run passed, 72 tests
• npm test passed, 34 tests
• npm run verify:mcp-resources-drift passed
• npm run build passed
• Confirmed built main bundle contains bundled zod code and no direct require("zod")

Removed generated verification artifacts afterward: node_modules, out, bin/relayfile-mount, and bin/.relayfile-mount-version.

[agent-relay-code]

Reviewed PR #89 against .workforce/pr.diff, changed files, and current checkout. I did not find a current breakage that needed a source edit.

Local validation run:

• npx vitest run src/main/broker.test.ts passed
• npx vitest run passed
• npm test passed
• npm run verify:mcp-resources-drift passed
• npm run build passed

npm run verify:mcp-spawn was not applicable in this checkout because it requires a packaged app under dist/; the normal build produced out/.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #89 against .workforce/pr.diff, changed files, and current checkout. I did not find a current breakage that needed a source edit.

Local validation run:

• npx vitest run src/main/broker.test.ts passed
• npx vitest run passed
• npm test passed
• npm run verify:mcp-resources-drift passed
• npm run build passed

npm run verify:mcp-spawn was not applicable in this checkout because it requires a packaged app under dist/; the normal build produced out/.

[agent-relay-code]

Reviewed PR #89 against .workforce/pr.diff, changed files, and the affected broker/IPCs/build paths. I did not find a current checkout breakage requiring code changes, so I left the PR code unchanged.

Validated locally:

• npm ci
• npm run verify:mcp-resources-drift
• npm test
• npx vitest run src/main/broker.test.ts
• npm run build

I also checked the built main bundle and confirmed zod is bundled rather than left as an external require('zod').

[agent-relay-code]

Reviewed PR #89 against the current checkout. I did not find a reproducible defect that required code changes, and there were no bot-review artifacts present under .workforce to validate.

Local verification run:

• npx vitest run src/main/broker.test.ts passed
• npx vitest run passed
• npm run test passed
• npm run build passed after installing dependencies
• npm run verify:mcp-resources-drift passed

I restored possible dependency/build side effects on tracked generated metadata before the final checks.

[agent-relay-code]

Reviewed PR #89 against the current checkout. I didn’t find any reproducible breakage or stale bot-review items to fix; .workforce only contained the PR diff, changed files, and context.

Local validation passed:

• npx vitest run src/main/broker.test.ts
• npm test
• npx tsc --noEmit
• npm run build

The build output includes bundled zod in out/main/index.js, exercising the Electron main bundling change.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #89 against the current checkout. I didn’t find any reproducible breakage or stale bot-review items to fix; .workforce only contained the PR diff, changed files, and context.

Local validation passed:

• npx vitest run src/main/broker.test.ts
• npm test
• npx tsc --noEmit
• npm run build

The build output includes bundled zod in out/main/index.js, exercising the Electron main bundling change.

[agent-relay-code]

Fixed one validated issue in the PR: PTY chunk dedupe state now clears when a broker session is dropped, so a restarted broker can reuse sequence numbers without suppressing fresh output.

Added regression coverage in src/main/broker.test.ts for restart-with-same-seq, and implemented cleanup in src/main/broker.ts.

Validated locally:

• npm exec vitest -- run src/main/broker.test.ts
• npm exec vitest -- run src/main
• npm run build

[agent-relay-code]

✅ pr-reviewer applied fixes — committed and pushed 7c243f1 to this PR. The notes below describe what changed.

Fixed one validated issue in the PR: PTY chunk dedupe state now clears when a broker session is dropped, so a restarted broker can reuse sequence numbers without suppressing fresh output.

Added regression coverage in src/main/broker.test.ts for restart-with-same-seq, and implemented cleanup in src/main/broker.ts.

Validated locally:

• npm exec vitest -- run src/main/broker.test.ts
• npm exec vitest -- run src/main
• npm run build

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #89 against the current checkout. I did not find any validated breakage requiring code changes.

Validated:

• BrokerManager.start boolean reuse semantics across callers
• IPC integration notification suppression on reused starts
• PTY duplicate suppression behavior
• zod is bundled into out/main/index.js after build

Checks run:

• npx vitest run src/main/broker.test.ts passed
• npx vitest run src/main passed
• npm test passed
• npm run build passed

[agent-relay-code]

Reviewed PR #89 against .workforce/pr.diff, changed files, and current checkout. I didn’t find a reproducible breakage that required edits.

Local validation run:

• npm ci
• npx vitest run src/main/broker.test.ts
• npm run build
• npm test
• bundle sanity check confirmed out/main/index.js does not retain a runtime require("zod")

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #89 against .workforce/pr.diff, changed files, and current checkout. I didn’t find a reproducible breakage that required edits.

Local validation run:

• npm ci
• npx vitest run src/main/broker.test.ts
• npm run build
• npm test
• bundle sanity check confirmed out/main/index.js does not retain a runtime require("zod")

[agent-relay-code]

Fixed a validated PTY dedupe issue in src/main/broker.ts: dedupe entries are now cleared when a broker session is dropped, so restarted brokers can reuse sequence numbers without suppressing fresh terminal output.

Added a regression in src/main/broker.test.ts covering same-seq PTY chunks before and after restart.

Local verification passed:

• npx vitest run src/main/broker.test.ts
• npx vitest run
• npm test
• npm run build
• node scripts/generate-mcp-extraResources.mjs --check

[agent-relay-code]

⚠️ pr-reviewer push failed (exit 1) — fixes were not applied to the PR. The notes below are advisory and were not pushed.

Fixed a validated PTY dedupe issue in src/main/broker.ts: dedupe entries are now cleared when a broker session is dropped, so restarted brokers can reuse sequence numbers without suppressing fresh terminal output.

Added a regression in src/main/broker.test.ts covering same-seq PTY chunks before and after restart.

Local verification passed:

• npx vitest run src/main/broker.test.ts
• npx vitest run
• npm test
• npm run build
• node scripts/generate-mcp-extraResources.mjs --check

[agent-relay-code]

Reviewed PR #89 and fixed one validated issue in the current checkout.

I found that PTY chunk dedupe state survived broker shutdown/restart because keys were scoped only by reusable sessionKey. A restarted broker could emit the same seq and have a legitimate first chunk suppressed. I fixed this by clearing PTY dedupe entries in dropSession() and using a non-colliding key delimiter. Added a regression test covering restart with the same agent/sequence/chunk.

Validated locally:

• npx vitest run src/main/broker.test.ts
• npm test
• npx tsc --noEmit
• npm run build

[agent-relay-code]

⚠️ pr-reviewer push failed (exit 1) — fixes were not applied to the PR. The notes below are advisory and were not pushed.

Reviewed PR #89 and fixed one validated issue in the current checkout.

I found that PTY chunk dedupe state survived broker shutdown/restart because keys were scoped only by reusable sessionKey. A restarted broker could emit the same seq and have a legitimate first chunk suppressed. I fixed this by clearing PTY dedupe entries in dropSession() and using a non-colliding key delimiter. Added a regression test covering restart with the same agent/sequence/chunk.

Validated locally:

• npx vitest run src/main/broker.test.ts
• npm test
• npx tsc --noEmit
• npm run build

[agent-relay-code]

Fixed one PR issue: broker:start IPC now returns the real BrokerManager.start() boolean, so reused broker sessions return false instead of being masked as true, while integration notifications still only run on actual starts.

Local verification passed:

• npx tsc --noEmit
• npx vitest run src/main/broker.test.ts
• npm test
• npm run build

[agent-relay-code]

✅ pr-reviewer applied fixes — committed and pushed 39b4406 to this PR. The notes below describe what changed.

Fixed one PR issue: broker:start IPC now returns the real BrokerManager.start() boolean, so reused broker sessions return false instead of being masked as true, while integration notifications still only run on actual starts.

Local verification passed:

• npx tsc --noEmit
• npx vitest run src/main/broker.test.ts
• npm test
• npm run build

[agent-relay-code]

⚠️ pr-reviewer push failed (exit 1) — fixes were not applied to the PR. The notes below are advisory and were not pushed.

Fixed two validated PR issues:

• broker:start IPC now returns the actual BrokerManager.start() boolean, so reused sessions return false while integration notifications still only fire on real starts.
• PTY chunk dedupe state is now cleared when a broker session is dropped, and dedupe keys are collision-resistant. Added a regression for restart with the same agent/sequence/chunk.

Validated locally:

• npx vitest run src/main/broker.test.ts
• npx tsc --noEmit
• npm test
• npx vitest run
• npm run build
• node scripts/generate-mcp-extraResources.mjs --check
• Confirmed out/main/index.js has no retained runtime require("zod") / from "zod" import.

No current GitHub review threads were open.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #89 against the current checkout. I did not find a validated breakage that required code changes.

Local validation run:

• npx vitest run src/main/broker.test.ts passed: 21 tests
• npm run test passed: 34 tests
• npm run build passed
• npm run verify:mcp-resources-drift passed

Note: npm ci was needed because dependencies were not installed.

[agent-relay-code]

Reviewed PR #89 against the current checkout. I did not find a validated breakage requiring code changes.

Local verification run:

• npx vitest run src/main/broker.test.ts passed
• npx vitest run passed
• npm run build passed
• npm test passed

I also tried raw npx tsc -p tsconfig.node.json --noEmit; it reports broad existing project config/type issues outside this PR path, while the repo’s actual build succeeds.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #89 against the current checkout. I did not find a validated breakage requiring code changes.

Local verification run:

• npx vitest run src/main/broker.test.ts passed
• npx vitest run passed
• npm run build passed
• npm test passed

I also tried raw npx tsc -p tsconfig.node.json --noEmit; it reports broad existing project config/type issues outside this PR path, while the repo’s actual build succeeds.

[agent-relay-code]

Reviewed PR #89 against the current checkout. I didn’t find a current breakage that needed code edits.

Validated locally:

• npx vitest run src/main/broker.test.ts
• npx vitest run
• npm test
• npm run build

Also confirmed the built main bundle includes bundled Zod code, matching the Electron main bundling change.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #89 against the current checkout. I didn’t find a current breakage that needed code edits.

Validated locally:

• npx vitest run src/main/broker.test.ts
• npx vitest run
• npm test
• npm run build

Also confirmed the built main bundle includes bundled Zod code, matching the Electron main bundling change.

[agent-relay-code]

⚠️ pr-reviewer push failed (exit 1) — fixes were not applied to the PR. The notes below are advisory and were not pushed.

Fixed one validated issue in the PR’s PTY dedupe hardening: recentPtyChunks is now cleared when a broker session is dropped, so a restarted session with the same project key and broker sequence cannot have its first PTY chunk incorrectly suppressed. Added a regression test for that restart case in src/main/broker.test.ts.

Verification run:

• npx vitest run src/main/broker.test.ts --reporter=dot
• npm run test
• npx tsc --noEmit
• npm run build
• npm run verify:mcp-resources-drift

[agent-relay-code]

⚠️ pr-reviewer did not push — the PR branch advanced during the review, so fixes were withheld to avoid overwriting newer commits. Re-trigger the review once the branch settles. The notes below are advisory and were not pushed.

Added a focused regression test in src/main/integrations.test.ts covering the PR’s integration changes:

• listOptions uses the account workspace API with the account bearer token.
• updateScope persists and emits immediately while mount/event/agent sync continues in the background.

Validation run:

• npm run verify:mcp-resources-drift
• npm test
• npx vitest run src/main/integrations.test.ts
• npx vitest run src/main/broker.test.ts
• npx vitest run src/main/broker.test.ts src/main/integration-mounts.test.ts src/main/integration-symlinks.test.ts src/main/cloud-agent.test.ts
• npm run build

Note: .workforce/context.json identifies the checked-out PR as #90, while the prompt said #89; I reviewed and fixed the checked-out PR artifacts.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #89 against the current checkout. I found no reproducible defects to fix and made no code edits.

Validated locally:

• npx vitest run src/main/broker.test.ts passed, 21 tests
• npm test passed, 34 tests
• npm run build passed

No bot/reviewer comment artifacts were present under .workforce, so there were no external findings to validate.