spec(SERVE-RECIPE-ARGS): a published recipe command must reach model load (#606)

[localai-bot]

Closes the spec-before-code gate for #606. Adds .agents/specs/serve-recipe-args.md,
the new SERVE-RECIPE-ARGS row at SPIKE, and its claim file.

The defect

vllm-serve rejects any argument it does not recognise
(src/vllm/entrypoints/openai/server_main.cpp:440). That is the right default —
and it is why two flags that mean nothing to us stop the server before it loads a
model:

Flag	Recipes passing it	Why inert here
--enable-auto-tool-choice	89 / 157	tool parsing is already unconditional once --tool-call-parser resolves
--trust-remote-code	82 / 157	no Python runtime, so no remote code to trust

The reproducer is a recipe's own copy-paste block, for a model we ship token-exact
and gated:

vllm serve Qwen/Qwen3.5-27B-FP8 --enable-auto-tool-choice --tool-call-parser qwen3_coder
#                               ^ server: unknown argument '--enable-auto-tool-choice'

What the spec commits to

An enumerated accepted-and-inert table, one entry per flag carrying the reason
it is inert — not a catch-all. Three rules:

1. Unlisted flags still abort. Silently swallowing --tensor-parallel-size
   would let a user believe they got TP. That the table is enumerated is the whole
   value of the seam.
2. Accepting is announced, so a log reader learns the flag did nothing rather
   than inferring it worked.
3. Mirrored validation still fires — cli_args.py:395 makes
   --enable-auto-tool-choice without a parser a TypeError upstream. Inert is
   not unvalidated.

Explicitly excluded: flags inert because we lack the capability (TP, EP,
--mm-encoder-tp-mode) keep aborting, and --language-model-only (#607) is a real
capability gap that must not be quietly absorbed here.

Recorded, not papered over

Upstream defaults --tool-call-parser to None; we default it to hermes
(docs/USAGE.md:878). Upstream's flag therefore gates something ours cannot. That
is pre-existing and out of scope, and the spec says so, so the notice text cannot
overclaim parity.

Tests named in the spec

RED-first, with the load-bearing case being "an unlisted unknown flag still
aborts" — a mutation turning the table into a catch-all must turn it RED, proven
in a scratch copy with the tree restored byte-for-byte.

Row accounting

ENGINE_ROWS 152 → 153 with the justification check-agent-record.py's own
comment ledger asks for. No checker semantics change: the row claims no seam, no
test, no docs/USAGE.md entry — none exists yet.

Spec and records only, no product code. scripts/agent-preflight.sh --staged: exit 0.

🤖 Generated with Claude Code

[localai-bot]

windows-msvc-cpu / windows-msvc-vulkan red here are pre-existing, not this diff.

Tracked by #503 and #603. Recording the attribution so a reviewer does not
re-derive it:

• The baseline cannot be subtracted the usual way. windows-msvc-* are
  skipped on push to main — verified across the last three main runs
  (31687057089, 31681004124, 31680082813: windows-msvc-cpu = skipped,
  windows-msvc-vulkan = skipped). So main never establishes green for them and
  they only ever run on a PR. That is exactly the structural trap main does not compile under MSVC, and main-baseline.py reports GREEN because windows-msvc-* are PR-only jobs it never runs #503 names:
  "main does not compile under MSVC, and main-baseline.py reports GREEN because
  windows-msvc- are PR-only jobs it never runs."*
• The control is spec(SAMPLE-REASONING): W3 runs before W2, on measured recipe demand (#605) #616, which changes exactly one markdown file
  (.agents/specs/reasoning-parsers.md) and fails the same two jobs at the same
  step, "Build and execute the native Windows CPU focused gate". A one-file
  documentation diff cannot break an MSVC C++ build, so the failure is upstream of
  every PR currently open.
• windows-msvc CI is RED on main: test_backend_cross_device.cpp uses POSIX setenv/unsetenv, which MSVC does not provide #603 names one instance of the class (POSIX setenv/unsetenv, which MSVC
  does not provide). That file has since moved, but grep -rl setenv tests/ still
  returns eight test translation units on main, so the class is not closed.

Neither this PR nor #616 touches src/, include/, tests/*.cpp, or CMake.

Not claimed as green, and not waived: the jobs are genuinely failing, the cause is
recorded elsewhere, and closing it belongs to #503/#603 rather than to a records
change.

[localai-bot]

Correction to my earlier comment: the specific cause is #584, not #503/#603.

I attributed the red Windows lanes to #503 / #603 — a compile break (POSIX
setenv, absent in MSVC). I inferred that from issue titles because the run logs
were not retrievable while the run was in progress. That inference was wrong about
the mechanism.

The observed failure is a runtime crash, not a compile error:
test_openai_api_server.exe exits -1073740791 = 0xC0000409
(STATUS_STACK_BUFFER_OVERRUN) — which is
#584, "test_openai_api_server
crashes on Windows with STATUS_STACK_BUFFER_OVERRUN (0xC0000409), unmasked by the
#512 fix". The failing CI step is "Build and execute the native Windows CPU
focused gate", which does both, so a crash at the execute half presents the same
way as a build failure from the outside.

What does not change: the failure is still not attributable to this PR.

• windows-msvc-* are skipped on push to main (verified across runs
  31687057089, 31681004124, 31680082813), so no main baseline exists to
  subtract — the structural trap main does not compile under MSVC, and main-baseline.py reports GREEN because windows-msvc-* are PR-only jobs it never runs #503 names.
• The control still holds, and is now stronger: record(MODEL-MATRIX): row the 7 recipe architectures that had none (#609, #610) #625 is records-only — it
  touches no src/, include/, or product test — and fails the same job with the
  byte-identical exit status.
• test_openai_api_server is not a consumer of anything in this PR.

Recording the correction rather than editing the original comment, so the wrong
attribution does not silently disappear from the thread. My apologies to whoever
would have chased setenv.

[localai-bot]

Closing as superseded by #624, which contains this branch's spec commit
(0d8274ac3) plus the implementation.

Verified rather than assumed:

• File superset. Every path this PR touches is also touched by feat(SERVE-RECIPE-ARGS): accept two inert recipe flags so a published vllm serve line reaches model load (#606) #624
  (comm -23 over both name-only diffs is empty), and
  .agents/claims/CLAIM-SERVE-RECIPE-ARGS.md is present there.
• The spec is strictly better there. feat(SERVE-RECIPE-ARGS): accept two inert recipe flags so a published vllm serve line reaches model load (#606) #624 extends it with ## Scope (an
  explicit exclusion table), ## Upstream chain at the pinned oracle, ## Our baseline, a ## Port map — including the deliberate non-port of
  api_server.py:426,441,529,544, recorded as a decision rather than an omission
  — ## Tests to port (naming tests/entrypoints/openai/test_cli_args.py:149,157
  and explaining why :169 does NOT carry over), ## Dependencies, a W1–W5
  breakdown, and a ## Now carrying the RED/GREEN/mutation evidence.
• The evidence test is duplicated, not lost. This branch added
  test_recipe_args_row_is_inside_the_engine_ratchet; feat(SERVE-RECIPE-ARGS): accept two inert recipe flags so a published vllm serve line reaches model load (#606) #624 independently added
  test_serve_recipe_args_row_is_inside_the_engine_ratchet — the same pin under a
  name that matches the row ID. Landing both would put two functionally identical
  tests in the file, which is the reason to close one rather than merge both.

The one thing this branch had that #624 initially lacked was that test commit,
because #624 branched before it was pushed. #624 then wrote its own, so nothing is
carried over.

row/serve-recipe-args stays until #624 merges, since #624 is based on it.

Closed per AGENTS.md: obsolete PRs are closed with the reason recorded, never left
open alongside their successor.