fix(cli): let push take the --fs the help offers and the code reads

[xizhuomengcontin]

Orca-Code-Review — push 1

Severity	Count
P0	0
P1	0
P2	0
P3	0

✅ no blocking findings

pushCommand reads args.bool('fs') (sync.ts:739) and orca push --help lists --fs
(main.ts:66), but push's entry in BY_COMMAND listed only gateway and force. So
assertKnownFlags refused the flag before the implementation ever saw it:

$ orca push run_04a70a423850 --fs
error push.failed
  unknown flag --fs for "orca push"
  flags for this command: --gateway --force

It did not degrade to ignoring the flag — it made the command fail, and the error named only the
two flags that were listed, so nothing pointed at what had actually gone wrong.

What it cost

There was no way to ship the workspace snapshots. Every run on a gateway therefore came back with
integrity.blob_count: 0 and an empty shadow store, and forking a pulled run died inside git:

git read-tree failed (128): fatal: failed to unpack tree object f7aa6aa59754fb5950b20fab0dfe46debbe73c56

That is the path the OrcaRouter console documents on its "Compare from step" panel, under
"fork from this step with the same files and conversation prefix":

orca pull '<run>'
orca compare last --from 2

replay.ts:903 already anticipated the failure mode — "Pointing a fresh store at the tree id
fails to unpack it" — and guards against restoring from the wrong store. It could not guard
against a run whose own store is legitimately empty, because until now no invocation could fill it.

Verification

Against a spec-conformant receiver (spec/orca-trace-v0.md §1 lists fs/ as an optional archive
member), same run, same command, only the flag differs:

	push	pull	orca compare last --from 2
without --fs	files=3 fs=withheld	0 git objects, blob_count: 0	fail — git read-tree failed (128)
with --fs	files=26 fs=included	4 git objects	pass, pass (two models)

Full suite on Windows: 10 failed / 2408 passed / 40 skipped — the same 10 pre-existing platform
failures as main, and one more passing test, which is the one added here.

Why the existing tests missed it

flags.test.ts already reads the source and holds the allowlist to it, but the check flattens
every command's flags into one set and asks whether someone allows the name. record and
replay both allow fs, so push's hole satisfied it.

sync.test.ts:797 covers --fs thoroughly — and calls pushCommand with a ParsedArgs it builds
itself, which never passes through the gate that was rejecting it.

The test added here holds the allowlist to the help text, per command: a flag the help offers
under orca <cmd> has to be accepted for that command. It fails without this change with
expected [ 'orca push --fs' ] to deeply equal [], and finds no other holes.

This is necessary but not sufficient

With the flag reachable, https://orcarouter.eape.mobi then refuses the archive:

warn push.fs_included note="workspace file contents travel raw: ..."
error push.failed
  not a valid orca-trace archive: orcatrace: invalid trace:
  "run_04a70a423850/fs/HEAD" is not part of a trace archive

spec/orca-trace-v0.md §1 lists fs/ as part of the layout, so that looks like a gap in the
gateway's validator rather than something to fix here — but until it is resolved, the console's
"fork it locally" instructions still cannot work end to end. Filing this separately on the gateway
side; noting it here so this PR is not mistaken for closing that loop.

🤖 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: 630 calls · 56.1M 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