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

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, the code writes the configured routing policy to the X-OmniRoute-Mode header. However, 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 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 module at 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 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):

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:

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

Enable local Issue-Agent access:

export OMNIROUTE_ISSUE_AGENT_ENABLED=true
npm run dev

Verify type-check failures (expected to fail):

npm run typecheck:core

# Error: Cannot find name 'omniglyph'

Key Source File References

File	Purpose
src/app/api/issue-agent/runs/route.ts	Main Issue-Agent adapter; handles validation and response forwarding
src/lib/issueAgent/execution.ts	Constructs X-OmniRoute-Mode header
src/lib/issueAgent/audit.ts	Pre-execution audit writer (lacks post-execution data)
src/app/api/v1/chat/completions/route.ts	Chat endpoint that ignores the routing policy header
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	Authoritative issue list

Summary

• KI-001: Routing policies written to X-OmniRoute-Mode in 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 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, 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, but 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}