Skip to main content

firstpass_proxy/
onboard.rs

1//! `firstpass onboard` — fully agentic onboarding (SPEC §0.2: the primary user is an agent, and
2//! the human deserves the same one-command experience). Detect the environment, plan the exact
3//! steps, execute them under `--apply`, and verify end-to-end — so "install firstpass and route
4//! my agent through it" is one command, not a doc to follow.
5//!
6//! Structure: [`detect`] and [`plan`] are pure (injected lookups, no I/O) so the decision logic is
7//! unit-tested offline; [`execute`] performs the side effects (spawn proxy, append one marked line
8//! to the shell rc, probe `/healthz`) and is deliberately thin. Without `--apply` the command is a
9//! dry run that prints the plan — agentic, but never surprising.
10
11use std::io::Write as _;
12use std::path::PathBuf;
13
14/// Marker comment appended with the env line so re-running onboard is idempotent and offboarding
15/// is greppable.
16pub const RC_MARKER: &str = "# added by `firstpass onboard`";
17
18/// What onboarding discovered about this machine. Everything is injected-lookup driven so tests
19/// construct arbitrary environments without touching the real one.
20#[derive(Debug, Clone, PartialEq, Eq)]
21pub struct Environment {
22    /// User's login shell binary name (`zsh` / `bash` / `fish` / other).
23    pub shell: String,
24    /// The proxy is already answering `/healthz` on the target port.
25    pub proxy_running: bool,
26    /// `ANTHROPIC_BASE_URL` already points at the target proxy.
27    pub already_routed: bool,
28    /// `ANTHROPIC_API_KEY` is set (needed for enforce-mode upstream calls; observe passes BYOK).
29    pub has_api_key: bool,
30    /// The `claude` CLI (Claude Code) is on PATH — we can offer MCP wiring.
31    pub has_claude_cli: bool,
32    /// Target bind, e.g. `127.0.0.1:8080`.
33    pub bind: String,
34}
35
36/// Which provider the ladder opens on. Of these four, `anthropic` and `openai` are built into the
37/// provider registry; Google (Gemini dialect) and a local server must carry a `[[provider]]` block
38/// or the config will not resolve.
39#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40pub enum Provider {
41    /// Built in.
42    Anthropic,
43    /// Built in.
44    OpenAi,
45    /// Gemini dialect; needs a `[[provider]]` block and `GEMINI_API_KEY`.
46    Google,
47    /// A local OpenAI-compatible server (Ollama), escalating to a frontier rung.
48    Local,
49}
50
51impl Provider {
52    /// Every choice, in prompt order.
53    pub const ALL: [Self; 4] = [Self::Anthropic, Self::OpenAi, Self::Google, Self::Local];
54
55    /// Stable id accepted by `--provider`.
56    #[must_use]
57    pub const fn id(self) -> &'static str {
58        match self {
59            Self::Anthropic => "anthropic",
60            Self::OpenAi => "openai",
61            Self::Google => "google",
62            Self::Local => "local",
63        }
64    }
65
66    /// One-line description shown next to the option when prompting.
67    #[must_use]
68    pub const fn blurb(self) -> &'static str {
69        match self {
70            Self::Anthropic => "Claude — haiku opens, sonnet catches (built in)",
71            Self::OpenAi => "GPT — 4.1-mini opens, 5.5 catches (built in)",
72            Self::Google => "Gemini — flash opens, pro catches (needs GEMINI_API_KEY)",
73            Self::Local => "Ollama on localhost, escalating to Claude sonnet",
74        }
75    }
76
77    /// Cheapest-first ladder. Every id here is priced by the built-in table, so `firstpass savings`
78    /// is meaningful out of the box (the local rung is the exception — it is free to run).
79    #[must_use]
80    pub const fn ladder(self) -> [&'static str; 2] {
81        match self {
82            Self::Anthropic => ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-5"],
83            Self::OpenAi => ["openai/gpt-4.1-mini", "openai/gpt-5.5"],
84            // Flash-Lite → Flash, not Flash → Pro: Google prices Flash at $1.50/$7.50 and Pro at
85            // $1.25/$10.00, so a Flash→Pro ladder has a ~8% gradient and escalation buys nothing.
86            // Lite→Flash is 5x on input, 3x on output — a ladder worth climbing.
87            Self::Google => ["google/gemini-3.5-flash-lite", "google/gemini-3.6-flash"],
88            Self::Local => ["ollama/qwen2.5-coder:7b", "anthropic/claude-sonnet-5"],
89        }
90    }
91
92    /// A model for the judge gate that is deliberately NOT on the ladder — the runner enforces
93    /// maker != checker, so a judge drawn from the ladder would be rejected.
94    #[must_use]
95    pub const fn judge_model(self) -> &'static str {
96        match self {
97            Self::Anthropic | Self::Local => "anthropic/claude-opus-4-8",
98            Self::OpenAi | Self::Google => "anthropic/claude-haiku-4-5",
99        }
100    }
101
102    /// The `[[provider]]` block this choice requires, if it is not built in.
103    #[must_use]
104    pub const fn provider_block(self) -> Option<&'static str> {
105        match self {
106            Self::Anthropic | Self::OpenAi => None,
107            Self::Google => Some(
108                "[[provider]]                # only anthropic + openai are built in\n\
109                 id          = \"google\"\n\
110                 dialect     = \"gemini\"\n\
111                 base_url    = \"https://generativelanguage.googleapis.com\"\n\
112                 api_key_env = \"GEMINI_API_KEY\"\n",
113            ),
114            Self::Local => Some(
115                "[[provider]]                # local rung; escalates to a frontier model\n\
116                 id       = \"ollama\"\n\
117                 dialect  = \"openai\"\n\
118                 base_url = \"http://localhost:11434\"   # keyless\n\
119                 \n\
120                 [[price]]                   # you host it, so the tokens really are free —\n\
121                 model          = \"ollama/qwen2.5-coder:7b\"   # but the receipt has to SAY so,\n\
122                 input_per_mtok  = 0.0       # rather than infer $0.00 from a missing price\n\
123                 output_per_mtok = 0.0\n",
124            ),
125        }
126    }
127}
128
129/// What the model is being asked to produce. This is what actually picks the gate — the whole
130/// product rests on gating the real output, so it is the one question worth asking carefully.
131#[derive(Debug, Clone, Copy, PartialEq, Eq)]
132pub enum Shape {
133    /// Structured output — checked against a schema.
134    Json,
135    /// Code — checked by running the caller's tests.
136    Code,
137    /// Prose — graded by a judge on a different model.
138    Prose,
139    /// Mixed traffic — scored by k-sample self-consistency.
140    Mixed,
141}
142
143impl Shape {
144    /// Every choice, in prompt order.
145    pub const ALL: [Self; 4] = [Self::Json, Self::Code, Self::Prose, Self::Mixed];
146
147    /// Stable id accepted by `--shape`.
148    #[must_use]
149    pub const fn id(self) -> &'static str {
150        match self {
151            Self::Json => "json",
152            Self::Code => "code",
153            Self::Prose => "prose",
154            Self::Mixed => "mixed",
155        }
156    }
157
158    /// One-line description shown next to the option when prompting.
159    #[must_use]
160    pub const fn blurb(self) -> &'static str {
161        match self {
162            Self::Json => "JSON / API responses — schema gate, cheapest proof there is",
163            Self::Code => "Code — your own test suite is the gate",
164            Self::Prose => "Prose — an LLM judge grades it (maker != checker)",
165            Self::Mixed => "Mixed — k-sample self-consistency scores agreement",
166        }
167    }
168
169    /// Gate ids the route names. `non-empty` and `json-valid` are built in; the rest are declared
170    /// by [`Self::gate_block`] below, because a route naming an undeclared gate will not resolve.
171    #[must_use]
172    pub const fn gates(self) -> [&'static str; 2] {
173        match self {
174            Self::Json => ["json-valid", "extract-shape"],
175            Self::Code => ["json-valid", "unit-tests"],
176            Self::Prose => ["non-empty", "judge"],
177            Self::Mixed => ["non-empty", "uncertainty"],
178        }
179    }
180
181    /// The `[[gate]]` block defining this shape's non-built-in gate.
182    #[must_use]
183    pub fn gate_block(self, provider: Provider) -> String {
184        match self {
185            Self::Json => "[[gate]]\n\
186                 id         = \"extract-shape\"\n\
187                 schema     = { type = \"object\", required = [\"id\", \"total\"] }\n\
188                 on_abstain = \"fail_closed\"\n"
189                .to_owned(),
190            // A gate is not just any command: it must read the candidate as JSON on stdin and
191            // print {"verdict":...} on stdout, so a bare `pytest` here would look wired up while
192            // silently abstaining on every call.
193            //
194            // This used to emit a REPLACE-ME placeholder for exactly that reason. Correct, but it
195            // left every new user to implement the contract by hand, which is the single biggest
196            // piece of onboarding friction for a code workload. `scripts/gates/run-tests.py` now
197            // implements the contract, so what is emitted is a WORKING gate with only the user's
198            // own test command left to substitute.
199            Self::Code => {
200                "[[gate]]\n\
201                 # A working gate. `run-tests.py` implements the stdin/stdout contract: it pulls\n\
202                 # the code out of the model's reply, runs your command, and reports the pass\n\
203                 # FRACTION as the score (a graded score is what the conformal bound calibrates\n\
204                 # on; a bare pass/fail gives it only two operating points).\n\
205                 # Swap the command after `--` for yours:\n\
206                 #   jest:  \"--write\", \"solution.js\", \"--\", \"npx\", \"jest\", \"--silent\"\n\
207                 #   cargo: \"--write\", \"src/lib.rs\", \"--\", \"cargo\", \"test\", \"--quiet\"\n\
208                 # Add \"--copy\", \"tests/\" to bring your test files into the run directory, and\n\
209                 # \"--docker\", \"python:3.12-alpine\" to run untrusted code with no network.\n\
210                 id  = \"unit-tests\"\n\
211                 cmd = [\"python3\", \"scripts/gates/run-tests.py\",\n\
212                        \"--write\", \"solution.py\", \"--copy\", \"tests/\",\n\
213                        \"--\", \"python3\", \"-m\", \"pytest\", \"-q\"]\n"
214                    .to_owned()
215            }
216            Self::Prose => format!(
217                "[[gate]]                    # judge sits OUTSIDE the ladder: maker != checker\n\
218                 id    = \"judge\"\n\
219                 judge = {{ model = \"{}\", threshold = 0.7, rubric = \"The response fully and \
220                 correctly resolves the request, with no errors.\" }}\n",
221                provider.judge_model()
222            ),
223            Self::Mixed => format!(
224                "[[gate]]                    # k samples; agreement becomes the score\n\
225                 id          = \"uncertainty\"\n\
226                 consistency = {{ model = \"{}\", k = 3, threshold = 0.6 }}\n",
227                provider.ladder()[0]
228            ),
229        }
230    }
231}
232
233/// The three answers that decide a starting ladder. Everything else in the generated file follows
234/// from these, which is why onboarding asks exactly three questions and not a wizard's worth.
235#[derive(Debug, Clone, Copy, PartialEq, Eq)]
236pub struct LadderChoice {
237    /// Which provider the ladder opens on.
238    pub provider: Provider,
239    /// What the output is, which picks the gate.
240    pub shape: Shape,
241    /// `observe` forwards unchanged; `enforce` serves from the cheap rung once a gate passes.
242    pub mode: firstpass_core::Mode,
243}
244
245impl Default for LadderChoice {
246    /// The answer set used when nothing is on a terminal to ask: Claude, JSON, and observe — the
247    /// combination that changes no behavior at all.
248    fn default() -> Self {
249        Self {
250            provider: Provider::Anthropic,
251            shape: Shape::Json,
252            mode: firstpass_core::Mode::Observe,
253        }
254    }
255}
256
257/// Render a complete, runnable `firstpass.toml` for these answers — including the `[[provider]]`
258/// and `[[gate]]` blocks the choice requires. Emitting a fragment would be worse than emitting
259/// nothing: only `anthropic`/`openai` are built-in providers and only `non-empty`/`json-valid`
260/// are built-in gates, so anything else must be declared here or the file will not resolve.
261#[must_use]
262pub fn render_config(choice: &LadderChoice) -> String {
263    let enforce = choice.mode == firstpass_core::Mode::Enforce;
264    let mode = if enforce { "enforce" } else { "observe" };
265    let quoted = |xs: [&str; 2]| -> String { format!("\"{}\", \"{}\"", xs[0], xs[1]) };
266    let mut out = format!(
267        "# firstpass.toml — written by `firstpass onboard`. Re-run onboard to regenerate.\n\
268         #   FIRSTPASS_MODE={mode} FIRSTPASS_CONFIG=./firstpass.toml firstpass up\n\n"
269    );
270    if let Some(block) = choice.provider.provider_block() {
271        out.push_str(block);
272        out.push('\n');
273    }
274    out.push_str(&format!(
275        "[[route]]                   # routes match top to bottom; first match wins\n\
276         match  = {{}}                 # everything\n\
277         mode   = \"{mode}\"\n\
278         ladder = [{}]\n\
279         gates  = [{}]\n\n",
280        quoted(choice.provider.ladder()),
281        quoted(choice.shape.gates()),
282    ));
283    out.push_str(&choice.shape.gate_block(choice.provider));
284    if enforce {
285        out.push_str(
286            "\n[escalation]\nmax_rungs_per_request = 2   # one rung up, never a runaway\n",
287        );
288    } else {
289        out.push_str(
290            "\n# observe: every request is forwarded unchanged and a receipt is written off\n\
291             # the hot path. Nothing routes differently until mode = \"enforce\".\n",
292        );
293    }
294    out
295}
296
297/// Render every answer combination as a JavaScript asset for the documentation site.
298///
299/// The docs used to carry their own copy of this template in `docs/assets/docs.js`. Two
300/// implementations of the same config format drift silently — and a docs page that emits config
301/// the binary would reject is worse than a page with no builder at all. So Rust owns the format
302/// and the site consumes what Rust produced; `docs_presets_are_current` fails CI if this output
303/// and the committed asset disagree.
304#[must_use]
305pub fn presets_js() -> String {
306    use firstpass_core::Mode;
307    let mut out = String::from(
308        "// GENERATED by `cargo test -p firstpass-proxy presets` — do not edit by hand.\n\
309         // Source of truth: crates/firstpass-proxy/src/onboard.rs (render_config).\n\
310         // Regenerate: FIRSTPASS_WRITE_PRESETS=1 cargo test -p firstpass-proxy presets\n\
311         window.FP_LADDER_PRESETS = {\n",
312    );
313    for provider in Provider::ALL {
314        out.push_str(&format!("  {:?}: {{\n", provider.id()));
315        for shape in Shape::ALL {
316            out.push_str(&format!("    {:?}: {{\n", shape.id()));
317            for (mode, key) in [(Mode::Observe, "observe"), (Mode::Enforce, "enforce")] {
318                let toml = render_config(&LadderChoice {
319                    provider,
320                    shape,
321                    mode,
322                });
323                out.push_str(&format!("      {key:?}: {},\n", js_string(&toml)));
324            }
325            out.push_str("    },\n");
326        }
327        out.push_str("  },\n");
328    }
329    out.push_str("};\n");
330    out
331}
332
333/// Encode a string as a JS double-quoted literal. Hand-rolled rather than pulling in a
334/// serialiser: the payload is our own generated TOML, and the escape set is small and fixed.
335fn js_string(s: &str) -> String {
336    let mut out = String::with_capacity(s.len() + 16);
337    out.push('"');
338    for c in s.chars() {
339        match c {
340            '"' => out.push_str("\\\""),
341            '\\' => out.push_str("\\\\"),
342            '\n' => out.push_str("\\n"),
343            '\r' => {}
344            c => out.push(c),
345        }
346    }
347    out.push('"');
348    out
349}
350
351/// One onboarding step: what it is, and whether it's already satisfied.
352#[derive(Debug, Clone, PartialEq, Eq)]
353pub enum Step {
354    /// Write the generated routing config. Never overwrites an existing file — the caller checks.
355    WriteConfig {
356        /// Where the file goes (`./firstpass.toml`).
357        path: PathBuf,
358        /// Full rendered contents.
359        toml: String,
360    },
361    /// Spawn `firstpass up` detached (observe mode), logging to `firstpass-proxy.log`.
362    StartProxy {
363        /// Config to hand the child via `FIRSTPASS_CONFIG`. The proxy has no default config path,
364        /// so a written file is inert unless it is passed explicitly.
365        config: Option<PathBuf>,
366    },
367    /// Append the marked `ANTHROPIC_BASE_URL` export to the shell rc file.
368    WireShell {
369        /// Rc file the line goes into.
370        rc: PathBuf,
371        /// The exact line (shell-dialect aware).
372        line: String,
373    },
374    /// Print the `claude mcp add` command so Claude Code can query traces/savings as tools.
375    /// (Printed, not executed — mutating another tool's config uninvited isn't onboarding.)
376    SuggestClaudeMcp,
377    /// Probe `/healthz` and `/v1/capabilities` and report what's routed.
378    Verify,
379    /// Nothing to do — with the reason shown to the user.
380    AlreadyDone(&'static str),
381}
382
383/// Detect the environment via injected lookups: `env(key)` for env vars, `on_path(bin)` for PATH
384/// probes, `healthz()` for a live proxy probe. Pure decision logic; all I/O behind the closures.
385pub fn detect(
386    env: impl Fn(&str) -> Option<String>,
387    on_path: impl Fn(&str) -> bool,
388    healthz: impl Fn() -> bool,
389) -> Environment {
390    let bind = env("FIRSTPASS_BIND").unwrap_or_else(|| "127.0.0.1:8080".to_owned());
391    let base_url = format!("http://{bind}");
392    let shell = env("SHELL")
393        .and_then(|s| s.rsplit('/').next().map(str::to_owned))
394        .unwrap_or_else(|| "sh".to_owned());
395    Environment {
396        shell,
397        proxy_running: healthz(),
398        already_routed: env("ANTHROPIC_BASE_URL").is_some_and(|v| v == base_url),
399        has_api_key: env("ANTHROPIC_API_KEY").is_some(),
400        has_claude_cli: on_path("claude"),
401        bind,
402    }
403}
404
405/// The shell-dialect line that routes agents through the proxy, plus the rc file it belongs in.
406/// `home` is injected so tests never touch a real home directory.
407#[must_use]
408pub fn shell_wiring(shell: &str, home: &std::path::Path, bind: &str) -> (PathBuf, String) {
409    let url = format!("http://{bind}");
410    match shell {
411        "fish" => (
412            home.join(".config/fish/config.fish"),
413            format!("set -gx ANTHROPIC_BASE_URL {url}  {RC_MARKER}"),
414        ),
415        "bash" => (
416            home.join(".bashrc"),
417            format!("export ANTHROPIC_BASE_URL={url}  {RC_MARKER}"),
418        ),
419        // zsh and anything else POSIX-ish: default to ~/.zshrc only for zsh, else ~/.profile.
420        "zsh" => (
421            home.join(".zshrc"),
422            format!("export ANTHROPIC_BASE_URL={url}  {RC_MARKER}"),
423        ),
424        _ => (
425            home.join(".profile"),
426            format!("export ANTHROPIC_BASE_URL={url}  {RC_MARKER}"),
427        ),
428    }
429}
430
431/// A config the caller wants written: where it goes and the answers behind it. `None` means the
432/// step is skipped — either a `firstpass.toml` is already there or the user opted out.
433#[derive(Debug, Clone)]
434pub struct ConfigPlan {
435    /// Destination, normally `./firstpass.toml`.
436    pub path: PathBuf,
437    /// The three answers.
438    pub choice: LadderChoice,
439}
440
441/// Build the ordered plan for this environment. `rc_already_wired` is whether the rc file already
442/// carries the marker line (checked by the caller, injected here to stay pure). `config` is the
443/// routing file to generate, if any — it is written *before* the proxy starts so the child can be
444/// handed it, since a config the proxy never loads is worse than no config at all.
445#[must_use]
446pub fn plan(
447    env: &Environment,
448    home: &std::path::Path,
449    rc_already_wired: bool,
450    config: Option<&ConfigPlan>,
451) -> Vec<Step> {
452    let mut steps = Vec::new();
453    if let Some(c) = config {
454        steps.push(Step::WriteConfig {
455            path: c.path.clone(),
456            toml: render_config(&c.choice),
457        });
458    }
459    if env.proxy_running {
460        steps.push(Step::AlreadyDone("proxy already answering /healthz"));
461    } else {
462        steps.push(Step::StartProxy {
463            config: config.map(|c| c.path.clone()),
464        });
465    }
466    if env.already_routed || rc_already_wired {
467        steps.push(Step::AlreadyDone("ANTHROPIC_BASE_URL already wired"));
468    } else {
469        let (rc, line) = shell_wiring(&env.shell, home, &env.bind);
470        steps.push(Step::WireShell { rc, line });
471    }
472    if env.has_claude_cli {
473        steps.push(Step::SuggestClaudeMcp);
474    }
475    steps.push(Step::Verify);
476    steps
477}
478
479/// Render the plan for the dry run (default) or as the running commentary under `--apply`.
480#[must_use]
481pub fn render(env: &Environment, steps: &[Step], apply: bool) -> String {
482    let mut out = String::new();
483    out.push_str(&format!(
484        "detected: shell={} · proxy_running={} · routed={} · api_key={} · claude_cli={}\n\n",
485        env.shell, env.proxy_running, env.already_routed, env.has_api_key, env.has_claude_cli
486    ));
487    for (i, s) in steps.iter().enumerate() {
488        let n = i + 1;
489        match s {
490            Step::WriteConfig { path, toml } => {
491                out.push_str(&format!("{n}. write {} —\n", path.display()));
492                for line in toml.lines() {
493                    out.push_str(&format!("     {line}\n"));
494                }
495            }
496            Step::StartProxy { config } => {
497                out.push_str(&format!(
498                    "{n}. start the proxy — `firstpass up` (observe mode: watches, changes nothing), log → firstpass-proxy.log\n"
499                ));
500                if let Some(c) = config {
501                    out.push_str(&format!(
502                        "     with FIRSTPASS_CONFIG={} — the proxy has no default config path\n",
503                        c.display()
504                    ));
505                }
506            }
507            Step::WireShell { rc, line } => out.push_str(&format!(
508                "{n}. route your agents — append to {}:\n     {line}\n",
509                rc.display()
510            )),
511            Step::SuggestClaudeMcp => out.push_str(&format!(
512                "{n}. (optional) let Claude Code query receipts as tools:\n     claude mcp add firstpass -- firstpass mcp\n"
513            )),
514            Step::Verify => out.push_str(&format!(
515                "{n}. verify — probe /healthz and /v1/capabilities, report what's routed\n"
516            )),
517            Step::AlreadyDone(why) => out.push_str(&format!("{n}. ✓ {why}\n")),
518        }
519    }
520    if !env.has_api_key {
521        out.push_str(
522            "\nnote: ANTHROPIC_API_KEY is not set — observe mode passes your agent's own key \
523             through (BYOK), so this only matters for enforce mode.\n",
524        );
525    }
526    if !apply {
527        out.push_str(
528            "\ndry run — nothing changed. Re-run with `firstpass onboard --apply` to execute.\n",
529        );
530    }
531    out
532}
533
534/// Execute the side-effectful steps. Returns a human report. Failures are reported per step —
535/// onboarding never half-dies silently.
536///
537/// # Errors
538/// Only on I/O failures writing the rc file; every other issue is reported in the returned text.
539pub fn execute(env: &Environment, steps: &[Step]) -> Result<String, std::io::Error> {
540    let mut out = String::new();
541    for s in steps {
542        match s {
543            Step::WriteConfig { path, toml } => {
544                // Never clobber a config the operator already has; the caller only plans this
545                // step when the path is free, but re-check rather than trust the gap between.
546                if path.exists() {
547                    out.push_str(&format!(
548                        "✓ {} already present — left untouched\n",
549                        path.display()
550                    ));
551                } else {
552                    std::fs::write(path, toml)?;
553                    out.push_str(&format!("✓ wrote {}\n", path.display()));
554                }
555            }
556            Step::StartProxy { config } => {
557                let log = std::fs::File::create("firstpass-proxy.log")?;
558                let exe = std::env::current_exe()?;
559                let mut cmd = std::process::Command::new(exe);
560                cmd.arg("up");
561                if let Some(c) = config {
562                    // A written config is inert unless it is named: `ProxyConfig::from_env` reads
563                    // `FIRSTPASS_CONFIG` and has no default path to fall back on.
564                    cmd.env("FIRSTPASS_CONFIG", c);
565                }
566                let child = cmd
567                    .stdin(std::process::Stdio::null())
568                    .stdout(std::process::Stdio::from(log.try_clone()?))
569                    .stderr(std::process::Stdio::from(log))
570                    .spawn();
571                match child {
572                    Ok(c) => {
573                        // Pidfile makes `firstpass offboard` able to stop what onboard started.
574                        let _ = std::fs::write("firstpass-proxy.pid", c.id().to_string());
575                        out.push_str(&format!(
576                            "✓ proxy started (pid {}, observe mode) — log: firstpass-proxy.log\n",
577                            c.id()
578                        ));
579                    }
580                    Err(e) => out.push_str(&format!("✗ could not start proxy: {e}\n")),
581                }
582            }
583            Step::WireShell { rc, line } => {
584                if let Some(parent) = rc.parent() {
585                    std::fs::create_dir_all(parent)?;
586                }
587                let mut f = std::fs::OpenOptions::new()
588                    .create(true)
589                    .append(true)
590                    .open(rc)?;
591                writeln!(f, "{line}")?;
592                out.push_str(&format!(
593                    "✓ wired {} — takes effect in new shells; for this one:\n     {}\n",
594                    rc.display(),
595                    line.trim_end_matches(RC_MARKER).trim_end()
596                ));
597            }
598            Step::SuggestClaudeMcp => {
599                out.push_str("→ optional: claude mcp add firstpass -- firstpass mcp\n");
600            }
601            Step::Verify => {
602                let url = format!("http://{}/healthz", env.bind);
603                let ok = wait_healthz(&url, std::time::Duration::from_secs(6));
604                if ok {
605                    out.push_str(&format!(
606                        "✓ verified — proxy healthy at http://{} · capabilities: http://{}/v1/capabilities\n",
607                        env.bind, env.bind
608                    ));
609                } else {
610                    out.push_str(&format!(
611                        "✗ proxy not answering http://{} after 6s — check firstpass-proxy.log\n",
612                        env.bind
613                    ));
614                }
615            }
616            Step::AlreadyDone(why) => out.push_str(&format!("✓ {why}\n")),
617        }
618    }
619    out.push_str("\noffboard any time: unset ANTHROPIC_BASE_URL (and remove the marked rc line)\n");
620    Ok(out)
621}
622
623/// Whether a `/healthz` response says **Firstpass** is on the other end.
624///
625/// A 200 alone proves only that *something* holds the port. That is not good enough here: onboard
626/// writes `ANTHROPIC_BASE_URL` into the user's shell rc, so accepting a stranger points the agent's
627/// credentialed traffic at an unrelated process, records no receipts, and still reports success.
628/// Found by running this for real — an unrelated dev server on `:8080` answered `/healthz 200` with
629/// its own JSON and onboard reported "verified — proxy healthy".
630///
631/// The proxy names itself in the body for exactly this reason (see `proxy::healthz`), which is the
632/// same discriminator `launch` uses before handing an agent a base url.
633#[must_use]
634pub fn healthz_is_firstpass(status_ok: bool, body: &str) -> bool {
635    if !status_ok {
636        return false;
637    }
638    serde_json::from_str::<serde_json::Value>(body)
639        .ok()
640        .and_then(|v| {
641            v.get("service")
642                .and_then(serde_json::Value::as_str)
643                .map(|s| s == "firstpass")
644        })
645        .unwrap_or(false)
646}
647
648/// One blocking `GET /healthz`, returning `(status_is_200, body)`. Std-only (the CLI calls this off
649/// the async runtime): a plain TCP connect + minimal HTTP/1.1 GET, no client dependency.
650///
651/// Reads to EOF rather than into a small fixed buffer — the identity marker lives in the body, and
652/// the previous 64-byte read could not reach past the status line.
653fn get_healthz(addr: &str) -> Option<(bool, String)> {
654    let mut s = std::net::TcpStream::connect(addr).ok()?;
655    let _ = s.set_read_timeout(Some(std::time::Duration::from_millis(500)));
656    let req = format!("GET /healthz HTTP/1.1\r\nHost: {addr}\r\nConnection: close\r\n\r\n");
657    s.write_all(req.as_bytes()).ok()?;
658    use std::io::Read as _;
659    let mut raw = Vec::new();
660    // Cap the read so a chatty or hostile listener cannot make this hang on unbounded output.
661    let _ = s.take(64 * 1024).read_to_end(&mut raw);
662    let text = String::from_utf8_lossy(&raw).into_owned();
663    let status_ok = text.lines().next().is_some_and(|l| l.contains(" 200"));
664    let body = text
665        .split_once("\r\n\r\n")
666        .map_or("", |(_, b)| b)
667        .to_owned();
668    Some((status_ok, body))
669}
670
671/// Whether **Firstpass** is answering at `addr` (`host:port`) right now. One probe, no waiting.
672///
673/// This is what the `onboard` environment detector must use: a bare TCP connect cannot tell a
674/// running proxy from any other process holding the port.
675#[must_use]
676pub fn firstpass_listening(addr: &str) -> bool {
677    get_healthz(addr).is_some_and(|(ok, body)| healthz_is_firstpass(ok, &body))
678}
679
680/// Poll until **Firstpass** answers `/healthz` or the deadline passes.
681fn wait_healthz(url: &str, deadline: std::time::Duration) -> bool {
682    let Some(addr) = url
683        .strip_prefix("http://")
684        .and_then(|r| r.split('/').next())
685        .map(str::to_owned)
686    else {
687        return false;
688    };
689    let start = std::time::Instant::now();
690    while start.elapsed() < deadline {
691        if firstpass_listening(&addr) {
692            return true;
693        }
694        std::thread::sleep(std::time::Duration::from_millis(200));
695    }
696    false
697}
698
699/// Whether the rc file already carries the onboard marker (idempotence check for [`plan`]).
700#[must_use]
701pub fn rc_wired(rc: &std::path::Path) -> bool {
702    std::fs::read_to_string(rc).is_ok_and(|s| s.contains(RC_MARKER))
703}
704
705/// Remove every marked onboard line from `rc`. Returns whether anything was removed. Only lines
706/// carrying [`RC_MARKER`] are touched — nothing else in the user's rc is ever rewritten.
707///
708/// # Errors
709/// Only on I/O failures reading/writing the rc file.
710pub fn offboard_rc(rc: &std::path::Path) -> Result<bool, std::io::Error> {
711    let Ok(content) = std::fs::read_to_string(rc) else {
712        return Ok(false); // no file → nothing to offboard
713    };
714    if !content.contains(RC_MARKER) {
715        return Ok(false);
716    }
717    let kept: Vec<&str> = content.lines().filter(|l| !l.contains(RC_MARKER)).collect();
718    std::fs::write(rc, kept.join("\n") + "\n")?;
719    Ok(true)
720}
721
722/// `firstpass offboard` — the exact mirror of onboard: strip the marked line from every candidate
723/// rc file, stop the proxy onboard started (pidfile), and print the one command for this shell.
724/// Fully idempotent; reports what it found either way.
725///
726/// # Errors
727/// Only on rc-file I/O failures.
728pub fn offboard(home: &std::path::Path) -> Result<String, std::io::Error> {
729    let mut out = String::new();
730    for rc in [
731        home.join(".zshrc"),
732        home.join(".bashrc"),
733        home.join(".profile"),
734        home.join(".config/fish/config.fish"),
735    ] {
736        if offboard_rc(&rc)? {
737            out.push_str(&format!("✓ removed firstpass line from {}\n", rc.display()));
738        }
739    }
740    // Stop the proxy onboard spawned, if its pidfile is present.
741    if let Ok(pid) = std::fs::read_to_string("firstpass-proxy.pid") {
742        let pid = pid.trim().to_owned();
743        #[cfg(unix)]
744        {
745            let killed = std::process::Command::new("kill")
746                .arg(&pid)
747                .status()
748                .is_ok_and(|s| s.success());
749            if killed {
750                out.push_str(&format!("✓ stopped proxy (pid {pid})\n"));
751            } else {
752                out.push_str(&format!(
753                    "→ proxy pid {pid} not running (already stopped)\n"
754                ));
755            }
756        }
757        let _ = std::fs::remove_file("firstpass-proxy.pid");
758    }
759    if out.is_empty() {
760        out.push_str("nothing to offboard — no marked rc lines, no pidfile.\n");
761    }
762    out.push_str("for this shell: unset ANTHROPIC_BASE_URL\n");
763    Ok(out)
764}
765
766#[cfg(test)]
767mod tests {
768    #![allow(clippy::unwrap_used)]
769    use super::*;
770
771    fn env_of<'a>(pairs: &'a [(&'a str, &'a str)]) -> impl Fn(&str) -> Option<String> + 'a {
772        move |k| {
773            pairs
774                .iter()
775                .find(|(a, _)| *a == k)
776                .map(|(_, v)| (*v).to_owned())
777        }
778    }
779
780    #[test]
781    fn detect_reads_shell_routing_and_tools() {
782        let e = detect(
783            env_of(&[
784                ("SHELL", "/bin/zsh"),
785                ("ANTHROPIC_BASE_URL", "http://127.0.0.1:8080"),
786                ("ANTHROPIC_API_KEY", "sk-x"),
787            ]),
788            |bin| bin == "claude",
789            || true,
790        );
791        assert_eq!(e.shell, "zsh");
792        assert!(e.proxy_running && e.already_routed && e.has_api_key && e.has_claude_cli);
793        assert_eq!(e.bind, "127.0.0.1:8080");
794    }
795
796    #[test]
797    fn detect_respects_custom_bind_and_mismatched_base_url() {
798        let e = detect(
799            env_of(&[
800                ("FIRSTPASS_BIND", "127.0.0.1:9999"),
801                ("ANTHROPIC_BASE_URL", "http://127.0.0.1:8080"), // points elsewhere
802            ]),
803            |_| false,
804            || false,
805        );
806        assert_eq!(e.bind, "127.0.0.1:9999");
807        assert!(
808            !e.already_routed,
809            "routed to a different port is not routed"
810        );
811    }
812
813    #[test]
814    fn shell_wiring_speaks_each_dialect() {
815        let home = std::path::Path::new("/home/u");
816        let (rc, line) = shell_wiring("fish", home, "127.0.0.1:8080");
817        assert!(rc.ends_with(".config/fish/config.fish"));
818        assert!(line.starts_with("set -gx ANTHROPIC_BASE_URL http://127.0.0.1:8080"));
819
820        let (rc, line) = shell_wiring("zsh", home, "127.0.0.1:8080");
821        assert!(rc.ends_with(".zshrc"));
822        assert!(line.starts_with("export ANTHROPIC_BASE_URL="));
823
824        let (rc, _) = shell_wiring("dash", home, "127.0.0.1:8080");
825        assert!(
826            rc.ends_with(".profile"),
827            "unknown shells fall back to .profile"
828        );
829    }
830
831    #[test]
832    fn plan_covers_fresh_machine_and_is_idempotent_when_done() {
833        let home = std::path::Path::new("/home/u");
834        let fresh = Environment {
835            shell: "zsh".into(),
836            proxy_running: false,
837            already_routed: false,
838            has_api_key: false,
839            has_claude_cli: true,
840            bind: "127.0.0.1:8080".into(),
841        };
842        let steps = plan(&fresh, home, false, None);
843        assert!(matches!(steps[0], Step::StartProxy { .. }));
844        assert!(matches!(steps[1], Step::WireShell { .. }));
845        assert!(matches!(steps[2], Step::SuggestClaudeMcp));
846        assert!(matches!(steps.last(), Some(Step::Verify)));
847
848        // Everything already set up → only AlreadyDone + Verify, nothing mutating.
849        let done = Environment {
850            proxy_running: true,
851            already_routed: true,
852            has_claude_cli: false,
853            ..fresh
854        };
855        let steps = plan(&done, home, true, None);
856        assert!(
857            steps
858                .iter()
859                .all(|s| matches!(s, Step::AlreadyDone(_) | Step::Verify))
860        );
861    }
862
863    #[test]
864    fn render_dry_run_says_nothing_changed_and_flags_missing_key() {
865        let home = std::path::Path::new("/home/u");
866        let e = Environment {
867            shell: "bash".into(),
868            proxy_running: false,
869            already_routed: false,
870            has_api_key: false,
871            has_claude_cli: false,
872            bind: "127.0.0.1:8080".into(),
873        };
874        let text = render(&e, &plan(&e, home, false, None), false);
875        assert!(text.contains("dry run — nothing changed"));
876        assert!(text.contains("ANTHROPIC_API_KEY is not set"));
877        assert!(text.contains(".bashrc"));
878    }
879
880    #[test]
881    fn rc_wired_detects_the_marker_and_execute_appends_it_once() {
882        let dir = std::env::temp_dir().join(format!("fp-onboard-{}", uuid::Uuid::now_v7()));
883        std::fs::create_dir_all(&dir).unwrap();
884        let rc = dir.join(".zshrc");
885        assert!(!rc_wired(&rc), "missing file is not wired");
886
887        let e = Environment {
888            shell: "zsh".into(),
889            proxy_running: true, // no spawn in this test
890            already_routed: false,
891            has_api_key: true,
892            has_claude_cli: false,
893            bind: "127.0.0.1:1".into(), // verify step will fail fast — that's fine, we assert wiring
894        };
895        let (rc_path, line) = shell_wiring("zsh", &dir, &e.bind);
896        let steps = vec![Step::WireShell {
897            rc: rc_path.clone(),
898            line,
899        }];
900        let report = execute(&e, &steps).unwrap();
901        assert!(report.contains("✓ wired"));
902        assert!(rc_wired(&rc_path), "marker written");
903        // Re-planning with the marker present must not wire again (idempotent onboarding).
904        let steps = plan(&e, &dir, rc_wired(&rc_path), None);
905        assert!(!steps.iter().any(|s| matches!(s, Step::WireShell { .. })));
906
907        let _ = std::fs::remove_dir_all(&dir);
908    }
909
910    #[test]
911    fn offboard_removes_only_the_marked_line_and_is_idempotent() {
912        let dir = std::env::temp_dir().join(format!("fp-offboard-{}", uuid::Uuid::now_v7()));
913        std::fs::create_dir_all(&dir).unwrap();
914        let rc = dir.join(".zshrc");
915        std::fs::write(
916            &rc,
917            format!("alias ll='ls -l'\nexport ANTHROPIC_BASE_URL=http://127.0.0.1:8080  {RC_MARKER}\nexport EDITOR=vim\n"),
918        )
919        .unwrap();
920
921        assert!(offboard_rc(&rc).unwrap(), "marked line removed");
922        let after = std::fs::read_to_string(&rc).unwrap();
923        assert!(!after.contains(RC_MARKER));
924        assert!(
925            after.contains("alias ll") && after.contains("EDITOR=vim"),
926            "user lines untouched"
927        );
928        assert!(!offboard_rc(&rc).unwrap(), "second offboard is a no-op");
929
930        // The full offboard reports the rc removal and the unset line.
931        std::fs::write(&rc, format!("x  {RC_MARKER}\n")).unwrap();
932        let report = offboard(&dir).unwrap();
933        assert!(report.contains("removed firstpass line"));
934        assert!(report.contains("unset ANTHROPIC_BASE_URL"));
935
936        let _ = std::fs::remove_dir_all(&dir);
937    }
938
939    /// The whole point of generating a config is that it runs. Every answer combination must
940    /// survive the real parser — including the `[[provider]]`/`[[gate]]` blocks each one implies,
941    /// since only `anthropic`/`openai` and `non-empty`/`json-valid` are built in.
942    #[test]
943    fn every_generated_config_parses_and_resolves() {
944        use firstpass_core::Mode;
945        let mut n = 0;
946        for provider in Provider::ALL {
947            for shape in Shape::ALL {
948                for mode in [Mode::Observe, Mode::Enforce] {
949                    n += 1;
950                    let choice = LadderChoice {
951                        provider,
952                        shape,
953                        mode,
954                    };
955                    let toml = render_config(&choice);
956                    let cfg = firstpass_core::Config::parse(&toml).unwrap_or_else(|e| {
957                        panic!(
958                            "{}/{}/{mode:?} did not parse: {e}\n{toml}",
959                            provider.id(),
960                            shape.id()
961                        )
962                    });
963                    let route = &cfg.routes[0];
964                    assert_eq!(
965                        route.mode, mode,
966                        "route mode is what actually gates enforcement"
967                    );
968                    assert_eq!(
969                        route.ladder.len(),
970                        2,
971                        "a ladder needs somewhere to escalate to"
972                    );
973
974                    // Every gate the route names must be built in or declared here.
975                    for g in &route.gates {
976                        let builtin = g == "non-empty" || g == "json-valid";
977                        assert!(
978                            builtin || cfg.gate_defs.iter().any(|d| &d.id == g),
979                            "{}/{}: gate {g:?} is neither built in nor declared",
980                            provider.id(),
981                            shape.id()
982                        );
983                    }
984                    // Same for every provider a rung names.
985                    for rung in &route.ladder {
986                        let pid = rung.split('/').next().unwrap();
987                        let builtin = pid == "anthropic" || pid == "openai";
988                        assert!(
989                            builtin || cfg.providers.iter().any(|d| d.id == pid),
990                            "{}/{}: provider {pid:?} is neither built in nor declared",
991                            provider.id(),
992                            shape.id()
993                        );
994                    }
995                    // maker != checker: a judge drawn from the ladder would be rejected at runtime.
996                    if let Some(j) = cfg.gate_defs.iter().find_map(|d| d.judge.as_ref()) {
997                        assert!(
998                            !route.ladder.contains(&j.model),
999                            "{}: judge {} is on its own ladder",
1000                            provider.id(),
1001                            j.model
1002                        );
1003                    }
1004                    // Observe must stay inert — an escalation cap implies enforcement.
1005                    assert_eq!(
1006                        toml.contains("[escalation]"),
1007                        mode == Mode::Enforce,
1008                        "escalation block should track enforce only"
1009                    );
1010                }
1011            }
1012        }
1013        assert_eq!(n, 32, "4 providers x 4 shapes x 2 modes");
1014    }
1015
1016    /// A written config the proxy never loads is worse than no config: `ProxyConfig::from_env`
1017    /// reads `FIRSTPASS_CONFIG` and has no default path, so the plan must carry it to the child.
1018    #[test]
1019    fn planned_config_is_written_before_the_proxy_starts_and_is_handed_to_it() {
1020        let home = std::path::Path::new("/home/u");
1021        let env = Environment {
1022            shell: "zsh".into(),
1023            proxy_running: false,
1024            already_routed: false,
1025            has_api_key: true,
1026            has_claude_cli: false,
1027            bind: "127.0.0.1:8080".into(),
1028        };
1029        let cfg = ConfigPlan {
1030            path: PathBuf::from("firstpass.toml"),
1031            choice: LadderChoice::default(),
1032        };
1033        let steps = plan(&env, home, false, Some(&cfg));
1034        assert!(
1035            matches!(&steps[0], Step::WriteConfig { path, .. } if path == &cfg.path),
1036            "config is written first, before anything reads it"
1037        );
1038        assert!(
1039            matches!(&steps[1], Step::StartProxy { config: Some(p) } if p == &cfg.path),
1040            "the spawned proxy is handed the config explicitly"
1041        );
1042
1043        // Without a config the plan is exactly what it always was.
1044        let steps = plan(&env, home, false, None);
1045        assert!(matches!(steps[0], Step::StartProxy { config: None }));
1046        assert!(!steps.iter().any(|s| matches!(s, Step::WriteConfig { .. })));
1047    }
1048
1049    /// Re-running onboard must never clobber a routing file the operator already edited.
1050    #[test]
1051    fn write_config_refuses_to_overwrite_an_existing_file() {
1052        let dir = std::env::temp_dir().join(format!("fp-cfg-{}", uuid::Uuid::now_v7()));
1053        std::fs::create_dir_all(&dir).unwrap();
1054        let path = dir.join("firstpass.toml");
1055        std::fs::write(&path, "# hand-tuned, do not touch\n").unwrap();
1056        let env = Environment {
1057            shell: "zsh".into(),
1058            proxy_running: true, // no spawn
1059            already_routed: true,
1060            has_api_key: true,
1061            has_claude_cli: false,
1062            bind: "127.0.0.1:1".into(),
1063        };
1064        let steps = vec![Step::WriteConfig {
1065            path: path.clone(),
1066            toml: render_config(&LadderChoice::default()),
1067        }];
1068        let report = execute(&env, &steps).unwrap();
1069        assert!(report.contains("already present"));
1070        assert_eq!(
1071            std::fs::read_to_string(&path).unwrap(),
1072            "# hand-tuned, do not touch\n",
1073            "existing config survived untouched"
1074        );
1075        let _ = std::fs::remove_dir_all(&dir);
1076    }
1077
1078    /// The dry run has to show the actual file, or "onboard asks then writes" is unverifiable
1079    /// before the fact.
1080    #[test]
1081    fn dry_run_shows_the_config_it_would_write() {
1082        let home = std::path::Path::new("/home/u");
1083        let env = Environment {
1084            shell: "bash".into(),
1085            proxy_running: false,
1086            already_routed: false,
1087            has_api_key: true,
1088            has_claude_cli: false,
1089            bind: "127.0.0.1:8080".into(),
1090        };
1091        let cfg = ConfigPlan {
1092            path: PathBuf::from("firstpass.toml"),
1093            choice: LadderChoice {
1094                provider: Provider::Local,
1095                shape: Shape::Code,
1096                mode: firstpass_core::Mode::Enforce,
1097            },
1098        };
1099        let text = render(&env, &plan(&env, home, false, Some(&cfg)), false);
1100        assert!(text.contains("write firstpass.toml"));
1101        assert!(text.contains("ollama"), "provider block is shown");
1102        assert!(text.contains("unit-tests"), "gate block is shown");
1103        assert!(
1104            text.contains("FIRSTPASS_CONFIG="),
1105            "explains how the proxy finds it"
1106        );
1107        assert!(text.contains("dry run — nothing changed"));
1108    }
1109
1110    /// The documentation site must not carry a second implementation of the config format.
1111    /// This pins the committed asset to what Rust generates; if they diverge, CI fails here
1112    /// rather than the site quietly shipping config the binary would reject.
1113    #[test]
1114    fn docs_presets_are_current() {
1115        let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
1116            .join("../../docs/assets/ladder-presets.js");
1117        let generated = presets_js();
1118
1119        // Regeneration is an explicit opt-in so a normal test run can never rewrite the repo.
1120        if std::env::var("FIRSTPASS_WRITE_PRESETS").is_ok() {
1121            std::fs::write(&path, &generated).expect("write presets");
1122            return;
1123        }
1124
1125        let committed = std::fs::read_to_string(&path).unwrap_or_else(|e| {
1126            panic!(
1127                "{}: {e}\nregenerate with:\n  \
1128                 FIRSTPASS_WRITE_PRESETS=1 cargo test -p firstpass-proxy presets",
1129                path.display()
1130            )
1131        });
1132        assert_eq!(
1133            committed.replace("\r\n", "\n"),
1134            generated,
1135            "docs/assets/ladder-presets.js is stale — the docs builder and `firstpass onboard` \
1136             would emit different config.\nregenerate with:\n  \
1137             FIRSTPASS_WRITE_PRESETS=1 cargo test -p firstpass-proxy presets"
1138        );
1139    }
1140
1141    /// Every preset the site can hand a user has to parse, for the same reason onboard's output
1142    /// does — the builder's whole value is that its output runs.
1143    #[test]
1144    fn every_docs_preset_parses() {
1145        let js = presets_js();
1146        let mut n = 0;
1147        for raw in js.split("\": \"").skip(1) {
1148            let lit = &raw[..raw.find("\",\n").unwrap_or(raw.len())];
1149            let toml = lit
1150                .replace("\\n", "\n")
1151                .replace("\\\"", "\"")
1152                .replace("\\\\", "\\");
1153            if !toml.contains("[[route]]") {
1154                continue;
1155            }
1156            n += 1;
1157            firstpass_core::Config::parse(&toml)
1158                .unwrap_or_else(|e| panic!("preset #{n} does not parse: {e}\n{toml}"));
1159        }
1160        assert_eq!(n, 32, "expected all 32 presets to be checked, saw {n}");
1161    }
1162
1163    /// A foreign listener on the bind port must never be mistaken for the proxy.
1164    ///
1165    /// This is a regression test for a real incident, not a hypothetical: an unrelated dev server
1166    /// held `:8080`, answered `GET /healthz` with `200` and the body below, and `firstpass onboard`
1167    /// reported "proxy already answering /healthz" and "verified — proxy healthy" — while writing
1168    /// `ANTHROPIC_BASE_URL=http://127.0.0.1:8080` into the shell rc. That points the agent's
1169    /// credentialed traffic at a stranger and records no receipts, which is strictly worse than
1170    /// nothing listening, because it looks like it worked.
1171    #[test]
1172    fn a_foreign_listener_answering_healthz_is_not_accepted_as_the_proxy() {
1173        // Verbatim from the process that caused this.
1174        let foreign = r#"{"status":"ok","llmMode":"api","rlsEnforce":false,"appPoolActive":false}"#;
1175        assert!(
1176            !healthz_is_firstpass(true, foreign),
1177            "a 200 from a stranger must not read as Firstpass"
1178        );
1179
1180        // The real proxy names itself (see proxy::healthz), which is the discriminator.
1181        let ours = r#"{"status":"ok","service":"firstpass","version":"0.6.0"}"#;
1182        assert!(
1183            healthz_is_firstpass(true, ours),
1184            "the real proxy must still be recognised"
1185        );
1186
1187        // A non-200 is never Firstpass regardless of body, and neither is unparseable output.
1188        assert!(!healthz_is_firstpass(false, ours));
1189        assert!(!healthz_is_firstpass(true, "not json at all"));
1190        // A bare ok-status body — the shape the old check accepted — is still not enough.
1191        assert!(!healthz_is_firstpass(true, r#"{"status":"ok"}"#));
1192    }
1193}