# Known Issues with OmniRoute v3.8.50: Critical Bugs in Issue-Agent and Type-Check Core

> Discover critical bugs in OmniRoute v3.8.50, including Issue-Agent workflow failures, unenforced routing policies, and CI blocking type-check errors. Learn about known issues.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: known-issues
- Published: 2026-07-29

---

**OmniRoute v3.8.50 contains five open P1/P2 issues affecting the Issue-Agent workflow, including unenforced routing policies, incomplete audit trails, raw API responses, and type-check failures blocking CI.**

The OmniRoute repository (diegosouzapw/OmniRoute) currently tracks several documented defects that impact the Issue-Agent executable workflow and core type-check validation. These known issues range from silently ignored routing headers to missing post-execution audit data, limiting the reliability of automated issue triage until the next maintenance release.

## Critical Issue-Agent Workflow Bugs (P1)

### Routing Policy Headers Ignored in Chat Flow (KI-001)

In [`src/lib/issueAgent/execution.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/issueAgent/execution.ts), the code writes the configured routing policy to the `X-OmniRoute-Mode` header. However, [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) never consumes this header, meaning combo rules and budget configurations have no effect on actual model selection via `handleComboChat`. The routing policy effectively becomes a no-op, breaking acceptance criteria AC-1 expectations.

### Terminal Error Semantics Missing (KI-002)

When provider failures, timeouts, or budget stops occur, [`src/app/api/issue-agent/runs/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/issue-agent/runs/route.ts) returns a raw `{ error }` object with HTTP 400. The implementation lacks terminal semantics and persistent error records, preventing users from debugging failed triages reliably (AC-2/AC-4). Currently, only pre-execution states are captured; failures disappear without audit trails.

### Pre-Execution Only Audit Records (KI-003)

The [`audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/audit.ts) module at [`src/lib/issueAgent/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/issueAgent/audit.ts) records only run context and steps before execution begins. It omits lifecycle data including the prompt sent, the output received, token usage, runtime duration, and error payloads. Without extending the audit to post-execution phases, full audit trails remain impossible (AC-2).

## API Contract and Type-System Defects

### Unstable Response Contracts (KI-004)

The Issue-Agent API returns the raw upstream `completion.body` directly from the provider. There is no stable, actionable triage-result schema (AC-3), meaning downstream tools cannot rely on a consistent JSON shape. Consumers receive provider-specific payloads rather than normalized OmniRoute responses.

### Type-Check Core Failures (KI-005)

Running `npm run typecheck:core` fails due to unresolved `omniglyph` symbols in `open-sse/services/compression/*`. These missing type definitions block the CI gate, preventing automated validation of the Issue-Agent implementation during release builds. The symbols are not exported anywhere in the codebase, causing the TypeScript compiler to abort.

## Security and Access Limitations

### Local-Only Route Restriction

[`src/server/authz/routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts) explicitly lists `/api/issue-agent/` in the local-only array. This intentional restriction prevents public exposure of the endpoint until the workflow hardening is complete. The route is only reachable from LAN or loopback interfaces, requiring the environment variable `OMNIROUTE_ISSUE_AGENT_ENABLED=true` for local testing.

## Verified Mitigations

While five issues remain open, two are verified as resolved:

- **KI-R001**: Test `fa2c1d7c6` adds an isolated success-path test that mocks only provider HTTP, confirming the happy path works.
- **KI-R002**: Test `e6a63eb33` adds shared request-body validation to the Issue-Agent route, confirming the validation gate passes.

## Working Around Current Limitations

Invoke the recorded-triage mode (currently the only enabled mode):

```javascript
await fetch('http://localhost/api/issue-agent/runs', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mode: 'recorded-triage',
    title: 'Example triage',
    description: 'Run through normal chat routing',
    repository: 'owner/repo',
    issueNumber: 123
  })
})
.then(r => r.json())
.then(console.log);

```

On success, this returns a `runId`, `auditPath`, and raw completion. On failure, it returns `{ error: "...", status: 400 }` without post-execution audit data due to KI-002.

Inspect pre-execution audit data:

```bash
cat "$DATA_DIR/issue-agent/audit.jsonl"

```

Enable local Issue-Agent access:

```bash
export OMNIROUTE_ISSUE_AGENT_ENABLED=true
npm run dev

```

Verify type-check failures (expected to fail):

```bash
npm run typecheck:core

# Error: Cannot find name 'omniglyph'

```

## Key Source File References

| File | Purpose |
|------|---------|
| [`src/app/api/issue-agent/runs/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/issue-agent/runs/route.ts) | Main Issue-Agent adapter; handles validation and response forwarding |
| [`src/lib/issueAgent/execution.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/issueAgent/execution.ts) | Constructs `X-OmniRoute-Mode` header |
| [`src/lib/issueAgent/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/issueAgent/audit.ts) | Pre-execution audit writer (lacks post-execution data) |
| [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) | Chat endpoint that ignores the routing policy header |
| [`src/server/authz/routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts) | Enforces local-only access to Issue-Agent routes |
| `open-sse/services/compression/*` | Contains unresolved `omniglyph` type symbols |
| [`docs/sessions/20260714-issue-agent-executable-triage/05_KNOWN_ISSUES.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/sessions/20260714-issue-agent-executable-triage/05_KNOWN_ISSUES.md) | Authoritative issue list |

## Summary

- **KI-001**: Routing policies written to `X-OmniRoute-Mode` in [`execution.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/execution.ts) are never read by the chat completion route, breaking policy enforcement.
- **KI-002**: Provider failures return raw 400 errors without persistent audit trails, complicating debugging.
- **KI-003**: Audit records capture only pre-execution context; post-execution metrics and errors are not persisted.
- **KI-004**: The API returns raw upstream completions instead of a normalized triage-result schema.
- **KI-005**: Unresolved `omniglyph` symbols in compression services block `npm run typecheck:core`.
- **Workaround**: The Issue-Agent route is restricted to local access via [`routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/routeGuard.ts) and requires `OMNIROUTE_ISSUE_AGENT_ENABLED=true` to function.

## Frequently Asked Questions

### Is it safe to use the Issue-Agent endpoint in production?

No. According to [`src/server/authz/routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts), the `/api/issue-agent/` route is explicitly restricted to local-only access. Do not expose this endpoint publicly until the audit hardening (KI-003) and error persistence (KI-002) issues are resolved.

### Why does `npm run typecheck:core` fail with "Cannot find name 'omniglyph'"?

This occurs because `open-sse/services/compression/*` references `omniglyph` symbols that are not exported anywhere in the codebase (KI-005). This prevents the TypeScript compiler from completing validation and blocks CI pipelines. You must either provide the missing type definitions or exclude those files from the core type-check until the maintainers fix the symbol resolution.

### Can I work around the routing policy header issue (KI-001)?

Currently, no. The `X-OmniRoute-Mode` header is set in [`src/lib/issueAgent/execution.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/issueAgent/execution.ts), but [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) does not read it, so combo and budget rules have no effect. You must wait for the downstream consumption to be implemented or manually configure routing outside the Issue-Agent workflow.

### What data is actually persisted in the current audit files?

As of v3.8.50, [`src/lib/issueAgent/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/issueAgent/audit.ts) only writes pre-execution context including run steps and metadata. It does not record the prompt, output, token usage, runtime, or errors (KI-003). The audit file therefore cannot be used for post-hoc debugging of failed runs or usage analysis.