tech-debt(acp-bridge): replace mapDomainErrorToErrorKind regex matching with typed errors

[doudouOUC]

Background

mapDomainErrorToErrorKind in packages/acp-bridge/src/status.ts (lifted from cli/src/serve/status.ts in PR #4298 / Wave 5 PR 22b/1) currently classifies two specific error variants by regex matching on error.message:

if (/agent channel closed/i.test(message)) {
  return 'init_timeout';
}
if (/Cannot determine CLI entry path/i.test(message)) {
  return 'missing_binary';
}

A TODO already calls this out as technical debt; PR 22b/1 review (github-actions Medium #4) asked for a tracked follow-up issue:

regex-based error classification can misclassify unrelated errors containing similar phrases.

Risk

Two real failure modes:

1. False positive misclassification: any future error whose .message happens to contain "agent channel closed" or "Cannot determine CLI entry path" gets routed to the wrong errorKind (and thus the wrong HTTP status code in the route layer). The substring check is broad enough that a wrapping error like RuntimeError: failed: <inner: agent channel closed> would also match.

2. Brittle to message wording changes: the throwing sites (BridgeTimeoutError at httpAcpBridge.ts:~1500 and defaultSpawnChannelFactory at ~4838) own these strings without a static guarantee that downstream classifiers stay aligned. A reasonable copy-edit (e.g. "ACP child closed unexpectedly" instead of "agent channel closed") silently degrades classification to a generic kind.

Proposed direction

Replace regex with typed error objects the bridge already throws:

• BridgeTimeoutError (already a class, already exported) → mapDomainErrorToErrorKind checks error instanceof BridgeTimeoutError and returns 'init_timeout' directly. No string matching.
• Cannot determine CLI entry path is currently a new Error(...) thrown inside defaultSpawnChannelFactory → introduce a new MissingCliEntryError class in acp-bridge/src/bridgeErrors.ts (parallel to the 11 existing error classes), throw it instead of a generic Error, and instanceof-branch the same way.

Existing structurally-distinct error classes (SessionNotFoundError, WorkspaceMismatchError, etc.) already follow this pattern; this issue extends the discipline to the last two regex holdouts.

Scope estimate

• ~50 LOC across bridgeErrors.ts (new class) + bridge.ts or spawnChannel.ts (throw site) + status.ts (mapDomainErrorToErrorKind body) once PR 22b/2 lands the bridge core.
• Suitable as a sub-PR alongside PR 22b/2 (which lifts defaultSpawnChannelFactory anyway), or a standalone post-22b/2 cleanup.

References

• PR refactor(acp-bridge): lift status, paths, errors, and bridge types (#4175 PR 22b/1) #4298 (PR 22b/1) where the lift carried this code into acp-bridge verbatim
• proposal(serve): Mode B feature-priority roadmap toward v0.16 production-ready #4175 Wave 5 PR 22b/2 — natural integration window since it also touches the throw sites
• github-actions review on refactor(acp-bridge): lift status, paths, errors, and bridge types (#4175 PR 22b/1) #4298 Medium Are you interested in AI Terminal? #4 — original suggestion

[qwen-code-ci-bot]

This is a well-documented technical debt issue. The proposed direction aligns with the existing error class pattern used throughout (e.g., , ).

Related context:

• PR refactor(acp-bridge): lift status, paths, errors, and bridge types (#4175 PR 22b/1) #4298 (Wave 5 PR 22b/1) lifted this code into with the existing comment
• proposal(serve): Mode B feature-priority roadmap toward v0.16 production-ready #4175 tracks the Wave 5 PR 22b/2 integration window, which touches the throw sites ( at and at /)
• The github-actions review on refactor(acp-bridge): lift status, paths, errors, and bridge types (#4175 PR 22b/1) #4298 (Medium Are you interested in AI Terminal? #4) originally flagged this regex-based classification concern

Suggested integration path:
This could land as a standalone post-22b/2 cleanup PR, or bundled with PR 22b/2 since that PR already touches the relevant throw sites. The ~50 LOC scope estimate makes it suitable for either approach.

[qwen-code-ci-bot]

This is a well-documented technical debt issue. The proposed direction aligns with the existing error class pattern used throughout acp-bridge (e.g., SessionNotFoundError, WorkspaceMismatchError).

Related context:

• PR refactor(acp-bridge): lift status, paths, errors, and bridge types (#4175 PR 22b/1) #4298 (Wave 5 PR 22b/1) lifted this code into acp-bridge with the existing TODO comment
• proposal(serve): Mode B feature-priority roadmap toward v0.16 production-ready #4175 tracks the Wave 5 PR 22b/2 integration window, which touches the throw sites (BridgeTimeoutError at httpAcpBridge.ts and defaultSpawnChannelFactory at bridge.ts/spawnChannel.ts)
• The github-actions review on refactor(acp-bridge): lift status, paths, errors, and bridge types (#4175 PR 22b/1) #4298 (Medium Are you interested in AI Terminal? #4) originally flagged this regex-based classification concern

Suggested integration path:
This could land as a standalone post-22b/2 cleanup PR, or bundled with PR 22b/2 since that PR already touches the relevant throw sites. The ~50 LOC scope estimate makes it suitable for either approach.