refactor(server): fetch boot context from ContexGin HTTP API

[dimakis]

Summary

• Replace file-based boot context loading with HTTP fetch from running ContexGin server
• Local Python fallback when ContexGin is unreachable
• Centaur review findings addressed

Replaces #358 (CI was stuck on stale branch).

Test plan

• Start session with ContexGin running — verify boot context loads via HTTP
• Start session without ContexGin — verify local fallback works
• Verify boot context pill renders correctly

🤖 Generated with Claude Code

[dimakis]

Centaur Review

Found 6 issue(s) (3 warning).

server/chat.ts

Solid simplification from dynamic-import library to HTTP API with graceful fallback chain. Main concerns: tokenBudget semantics changed (now always equals tokenCount instead of reflecting configured budget), and included/trimmed section metadata is permanently empty in the new path.

• 🟡 regressions (L897): The call site fetchBootContext(agentName) omits contexginUrl and repoRoot, so both use defaults. The default repoRoot is BASE_REPO (which could be '' if REPO_PATH is unset). If ContexGin is down and BASE_REPO is empty, localBootContextFallback will try to exec scripts/build_boot_context.py relative to cwd — but this is caught and returns the zero-value fallback, so it degrades gracefully. Not a bug, but worth noting the old code passed cwd (the resolved working directory) rather than BASE_REPO for the fallback script. If ContexGin is offline and the session uses a worktree cwd, the fallback script runs against BASE_REPO (the parent repo) instead of the worktree — this is likely correct (the script reads canonical source files), but the behavior changed from the old code which used cwd.
• 🟡 regressions (L212): The old code set tokenBudget from the agent recipe's context.boot.tokenBudget field (defaulting to 8000). The new code sets tokenBudget equal to tokenCount (the actual token count from the server response). This means tokenBudget no longer reflects the configured budget — it just mirrors tokenCount. Any frontend logic that compares tokenCount vs tokenBudget (e.g., to show utilization percentage) will always see 100%. The client-side protocol parser at packages/client/src/protocol-parser.ts:260 does forward tokenBudget to the store, so if anything renders budget vs. used, it's now a no-op comparison. [fixable]
• 🟡 unsafe_assumptions (L141): The localBootContextFallback hardcodes sourceCount: 5 and a fixed list of 5 source paths, with a comment saying it's coupled to SOURCE_PATHS in scripts/build_boot_context.py. If that script changes its source list, this will silently drift out of sync. Consider reading the script's output for source metadata instead of duplicating the list, or at minimum making the hardcoded count derive from the array length (sources.length instead of the literal 5). [fixable]
• 🔵 style (L898): The double cast msg as unknown as Record<string, unknown> is unnecessarily defensive. BootContextMessage is a plain interface with only primitive/array fields — a single msg as Record<string, unknown> suffices since the types are structurally compatible. Alternatively, widen the send() helper to accept BootContextMessage directly. [fixable]
• 🔵 regressions (L214): The old code populated included and trimmed arrays with section-level metadata (source file, heading path, token estimates, content) from the contexgin compile result. The new HTTP API path always returns empty arrays for both. If the ContexGin HTTP API does (or will) return this data, it's being silently dropped. If the API intentionally omits it, this is fine — but the BootContextMessage interface still declares these fields, and the client parser still parses them, so there's dead plumbing.

server/__tests__/boot-context.test.ts

Solid simplification from dynamic-import library to HTTP API with graceful fallback chain. Main concerns: tokenBudget semantics changed (now always equals tokenCount instead of reflecting configured budget), and included/trimmed section metadata is permanently empty in the new path.

• 🔵 missing_tests: No test covers the AbortSignal.timeout(5000) behavior — e.g., verifying that a slow ContexGin response triggers the fallback within the timeout window. This is difficult to test in unit tests but worth noting as an untested edge case.

[dimakis]

🟡 regressions: The call site fetchBootContext(agentName) omits contexginUrl and repoRoot, so both use defaults. The default repoRoot is BASE_REPO (which could be '' if REPO_PATH is unset). If ContexGin is down and BASE_REPO is empty, localBootContextFallback will try to exec scripts/build_boot_context.py relative to cwd — but this is caught and returns the zero-value fallback, so it degrades gracefully. Not a bug, but worth noting the old code passed cwd (the resolved working directory) rather than BASE_REPO for the fallback script. If ContexGin is offline and the session uses a worktree cwd, the fallback script runs against BASE_REPO (the parent repo) instead of the worktree — this is likely correct (the script reads canonical source files), but the behavior changed from the old code which used cwd.

[dimakis]

Acknowledged — the fallback running against BASE_REPO instead of worktree cwd is indeed the correct behavior since the script reads canonical source files. No change needed.

[dimakis]

🟡 regressions: The old code set tokenBudget from the agent recipe's context.boot.tokenBudget field (defaulting to 8000). The new code sets tokenBudget equal to tokenCount (the actual token count from the server response). This means tokenBudget no longer reflects the configured budget — it just mirrors tokenCount. Any frontend logic that compares tokenCount vs tokenBudget (e.g., to show utilization percentage) will always see 100%. The client-side protocol parser at packages/client/src/protocol-parser.ts:260 does forward tokenBudget to the store, so if anything renders budget vs. used, it's now a no-op comparison. [fixable]

[dimakis]

Fixed — added DEFAULT_TOKEN_BUDGET = 8000 constant. The ContexGin path now reads boot.tokenBudget from the response (falling back to 8000), and the local fallback uses the constant. Budget no longer mirrors tokenCount.

[dimakis]

🟡 unsafe_assumptions: The localBootContextFallback hardcodes sourceCount: 5 and a fixed list of 5 source paths, with a comment saying it's coupled to SOURCE_PATHS in scripts/build_boot_context.py. If that script changes its source list, this will silently drift out of sync. Consider reading the script's output for source metadata instead of duplicating the list, or at minimum making the hardcoded count derive from the array length (sources.length instead of the literal 5). [fixable]

[dimakis]

Fixed — extracted the sources array to a variable, now uses sources.length instead of the hardcoded literal 5.

[dimakis]

🔵 style: The double cast msg as unknown as Record<string, unknown> is unnecessarily defensive. BootContextMessage is a plain interface with only primitive/array fields — a single msg as Record<string, unknown> suffices since the types are structurally compatible. Alternatively, widen the send() helper to accept BootContextMessage directly. [fixable]

[dimakis]

Addressed — widened send() to accept Record<string, unknown> | BootContextMessage, removing the double cast at the call site. The internal as Record<string, unknown> remains because SessionTransport.send() requires it.

[dimakis]

🔵 regressions: The old code populated included and trimmed arrays with section-level metadata (source file, heading path, token estimates, content) from the contexgin compile result. The new HTTP API path always returns empty arrays for both. If the ContexGin HTTP API does (or will) return this data, it's being silently dropped. If the API intentionally omits it, this is fine — but the BootContextMessage interface still declares these fields, and the client parser still parses them, so there's dead plumbing.

[dimakis]

Fixed — included and trimmed are now parsed from the ContexGin HTTP response when present, instead of always returning empty arrays.

[dimakis]

Centaur Review

Found 5 issue(s) (1 critical) (1 warning).

server/__tests__/boot-context.test.ts

The tokenBudget test/implementation mismatch (mock omits tokenBudget but test expects 11297, implementation defaults to 8000) will cause a test failure. The core refactor from npm-imported contexgin to HTTP API is sound with good fallback chains, but needs test coverage for tokenBudget parsing and included/trimmed section parsing.

• 🔴 bugs (L104): Test expects tokenBudget: 11297 but the mock response at line 84 has no tokenBudget field in boot. The implementation (chat.ts:199) defaults to 8000 when boot.tokenBudget is absent: typeof boot.tokenBudget === 'number' ? boot.tokenBudget : 8000. This test will fail. Either add tokenBudget: 11297 to the mock's boot object, or change the expectation to 8000. [fixable]
• 🟡 missing_tests: No test case verifies that tokenBudget is correctly parsed when the API response does include boot.tokenBudget. The existing happy-path test omits it, so the typeof boot.tokenBudget === 'number' branch is never exercised. Add a test where the mock includes an explicit tokenBudget value distinct from tokens to confirm both fields are parsed independently. [fixable]
• 🔵 missing_tests: No test covers the included/trimmed section parsing (parseSections at chat.ts:210-218). The happy-path test receives no included/trimmed in the mock, so the array-filtering and field-coercion logic in parseSections is untested. A test with mock included/trimmed arrays containing objects with partial fields would cover the String(s.source ?? '') coercion paths. [fixable]

server/chat.ts

The tokenBudget test/implementation mismatch (mock omits tokenBudget but test expects 11297, implementation defaults to 8000) will cause a test failure. The core refactor from npm-imported contexgin to HTTP API is sound with good fallback chains, but needs test coverage for tokenBudget parsing and included/trimmed section parsing.

• 🔵 style (L384): The as Record<string, unknown> cast works around SessionTransport.send() only accepting Record<string, unknown>. It's safe since BootContextMessage is a plain object, but the union type on send() (line 383) is misleading — it suggests type safety that the cast immediately discards. Consider either widening SessionTransport.send() to accept unknown or keeping send() typed as just Record<string, unknown> and casting at the call site instead. [fixable]
• 🔵 unsafe_assumptions (L138): The hardcoded source list in localBootContextFallback (lines 138-144) assumes the mgmt workspace structure (memory/Profile/Working Style.md, CONSTITUTION.md, SERVICES.md). These paths won't exist in other repos that might use Mitzo. Since this is explicitly a fallback for when ContexGin is down and scoped to the REPO_PATH workspace, it's acceptable — but a comment noting this is mgmt-specific would help future readers.

[dimakis]

🔴 bugs: Test expects tokenBudget: 11297 but the mock response at line 84 has no tokenBudget field in boot. The implementation (chat.ts:199) defaults to 8000 when boot.tokenBudget is absent: typeof boot.tokenBudget === 'number' ? boot.tokenBudget : 8000. This test will fail. Either add tokenBudget: 11297 to the mock's boot object, or change the expectation to 8000. [fixable]

[dimakis]

Fixed — added tokenBudget: 11297 to the mock ContexGin response so the test validates end-to-end budget propagation.

[dimakis]

🔵 style: The as Record<string, unknown> cast works around SessionTransport.send() only accepting Record<string, unknown>. It's safe since BootContextMessage is a plain object, but the union type on send() (line 383) is misleading — it suggests type safety that the cast immediately discards. Consider either widening SessionTransport.send() to accept unknown or keeping send() typed as just Record<string, unknown> and casting at the call site instead. [fixable]

[dimakis]

Fair point — the union type on send() is a compromise. SessionTransport.send() is typed as Record<string, unknown> (harness package), so we can't avoid the internal cast without widening the harness interface. Keeping the union at send() at least makes the call sites cleaner.

[dimakis]

🔵 unsafe_assumptions: The hardcoded source list in localBootContextFallback (lines 138-144) assumes the mgmt workspace structure (memory/Profile/Working Style.md, CONSTITUTION.md, SERVICES.md). These paths won't exist in other repos that might use Mitzo. Since this is explicitly a fallback for when ContexGin is down and scoped to the REPO_PATH workspace, it's acceptable — but a comment noting this is mgmt-specific would help future readers.

[dimakis]

Acknowledged — these paths are mgmt-specific and only used when ContexGin is offline. This is an acceptable coupling since Mitzo's primary deployment is the mgmt workspace.