Fix type safety, async I/O blocking, and error handling across core modules

[Copilot]

Addressed code quality issues flagged in PR review: blocking synchronous I/O, loose type annotations, insufficient error handling, and ambiguous boolean checks.

Type Safety Improvements

mcp-bridge.ts

• Added MCPBridgeStatus interface; replaced any return type on getStatus()
• Created EndpointResolutionError class for endpoint resolution failures

tui/app.tsx

• Replaced any types in InkBindings with Ink v5-compatible interface shapes
• Added proper Key type definition with explicit boolean properties

cli/index.ts

• Replaced any with unknown in error handling; added type narrowing

// Before
getStatus(): any { ... }

// After
export interface MCPBridgeStatus {
  isRunning: boolean;
  connectedEndpoints: Array<{ name: string; url: string }>;
  retryAttempts: number;
  timeoutMs: number;
}
getStatus(): MCPBridgeStatus { ... }

Non-blocking Async Operations

daemon-runner.ts

• Converted persistSnapshot from writeFileSync to async fs/promises.writeFile
• Updated call sites: await for critical paths, fire-and-forget for background updates

cli/index.ts

• Replaced spawnSync with promisified execFile in codex-register command
• Added execCodexCommand helper with timeout support, ENOENT detection, and exit code handling

// Before: blocks event loop, no timeout, poor error handling
const add = spawnSync('codex', ['mcp', 'add', name, '--url', url]);

// After: async, 10s timeout, explicit error handling
const add = await execCodexCommand(['mcp', 'add', name, '--url', url]);

Error Handling & Logic Fixes

service-manager.ts

• Created ServiceManagerError class for config validation failures
• Fixed probeService diagnostic: only reports failure when explicitly false, not null (no probe configured)

tui/app.tsx

• Wrapped fetchSnapshot() in try/catch; replaced console with structured Logger
• Ensured onExit called in both success and error paths via finally block

Documentation

• Capitalized "Mac" in README.md user-facing text for consistency

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

Codex PR Review

Findings

• P1: persistSnapshot now resolves asynchronously but several call sites fire-and-forget it (void persistSnapshot()). If two writes overlap, a slower, older write can finish last and overwrite a newer snapshot, leaving ~/.codex-synaptic/runtime.json stale (e.g., timer write vs. mode change). The synchronous version could not race this way. See src/cli/daemon-runner.ts:159, src/cli/daemon-runner.ts:213, src/cli/daemon-runner.ts:378.
• P2: The new fallback logging passes the caught Error as the logger’s data argument instead of the error argument, so the stack/message are dropped (logged as {}) when snapshot retrieval fails. See src/tui/app.tsx:288.

Suggested Fixes

1. Queue or await snapshot writes so they complete in order—e.g., keep a pending promise and chain new writes onto it, or await the promise before returning where correctness matters.
2. Call logger.error('tui', 'Failed to fetch snapshot in fallback mode', undefined, error as Error); (or equivalent) so the error is recorded with full context.

MCP Usage

• deepwiki: attempted for architectural context (failed – missing DEEPWIKI_API_KEY).
• context7: consulted Node.js execFile docs for async CLI command behavior.
• brave: attempted for change awareness (failed – connection closed during handshake).
• jina: attempted for citation enrichment (failed – missing JINA_API_KEY).
• firecrawl: attempted for deeper crawl (failed – connection closed during handshake).