fix(core): a trace that no gateway will take, written by three commands

[xizhuomengcontin]

Orca-Code-Review — push 1

Severity	Count
P0	0
P1	0
P2	0
P3	0

✅ no blocking findings

Spec §2.3: "run.start / run.end — Bracket the run. Exactly one of each." Nothing enforced
it, and three commands got it wrong three different ways.

command	what it wrote at seq 0	pushable
record --mcp-config	a note	no — fixed in #85
attach	model.request, and no run.end at all	no
replay --from N / compare	fork	no

All three produce a trace that orca show, orca replay and the viewer render happily:

$ orca push <fork>
info  push.packed run=run_7b977560a6de files=3 bytes=2816
error push.failed
      invalid orca-trace archive: orcatrace: invalid trace:
      0 run.start and 1 run.end events (exactly one of each)

The cost of finding out late is the whole recording — the user learns at orca push, after the
agent session is over, that there is nothing to push. It is worse for compare: forking one
checkpoint onto several models is what the tool is pitched on, and its output could not be
shared with anyone.

The guard

TraceWriter.append refuses the three a deliberate fragment cannot reach by accident:

• run.start anywhere but seq 0
• a second run.start
• a run.end with no run.start

"seq 0 must BE run.start" is deliberately not one of them. This writer also builds
fixtures and conformance vectors, and those are allowed to be a handful of events with no bracket
at all — the stronger rule would have meant editing 43 TraceWriter.create sites across the core
tests to say something none of them are about.

The flags are set after the write, so a bracket that failed to reach disk is not one, and a
refused append leaves no hole in the dense order (spec §2.1) — pinned by a test.

The two commands that were violating it

• attach writes run.start before createProxy, which is listening by the time it returns;
  after it, the first thing a remote agent sends wins seq 0. It writes run.end before sealing,
  which close does not do on its behalf. The proxy URL that record's run.start carries is
  not known that early and is read by nothing.
• a fork writes run.start before fork. The fork event keeps everything that makes it a
  fork; it just is not the first line any more.

Verification

Against the live gateway, three rounds of record → fork → attach, 9 of 9 push:

═══ round 1 ═══            ═══ round 2 ═══            ═══ round 3 ═══
  record  run.start…run.end  push.done    (same)                    (same)
  fork    run.start…run.end  push.done
  attach  run.start…run.end  push.done

All three then open in the gateway console with their layers intact — the fork shows
OTHER fork seq 1, its two Route rows, the LLM call rows and the request diff, Routes 2.

Suite: 10 failed / 2420 passed / 40 skipped — the same 10 pre-existing Windows platform failures
as main, six more passing tests. prettier --check, tsc --build, scripts/conformance.mjs
(61 events, 0 failures) and scripts/fidelity.mjs --check (1 recording, 0 regressions) all clean
locally this time.

How it went unnoticed

attach-command.test.ts opened the trace it produced and asserted the model exchange count —
nothing about the first or last event. That assertion is now there, and fails on main with
first event was model.request.

🤖 Generated with Claude Code

[orcacode-review]

🐳 OrcaCode Review

✅ No findings — nothing to flag in this PR. Great work!

_{OrcaCode Review — Route Smarter. Ship Safer. Spend Less.
Engine-reported: 693 calls · 73.2M tokens · 99% cached}

❤️ Share · Install OrcaCode Review

Free on GitHub — the review runs on your own OrcaRouter key. If it helped, a shout-out goes a long way.

Share: X · Reddit · LinkedIn
Follow: X · Discord · LinkedIn · OrcaRouter