run-without-AI: client half implemented in 0.5.203 — handover ordering and the mobile in-process question still open

[emooreatx]

The client half is implemented in 0.5.203 — here is what it does and what it still needs from the agent

Follow-up to #1149, which is landing in #1150. The contract is on that issue; this is the implementation and the three things still open, so they are tracked rather than living in a comment thread.

What the client now does

BackendEndpoint in shared code — one pure function, 14 tests, no per-platform copies:

val AGENT_ENDPOINT     = BackendEndpoint(port = 8080, healthPath = "/v1/system/health")
val NODE_ONLY_ENDPOINT = BackendEndpoint(port = 4243, healthPath = "/health")

fun backendEndpoint(runWithoutAi: Boolean) = if (runWithoutAi) NODE_ONLY_ENDPOINT else AGENT_ENDPOINT

• CIRIS_RUN_WITHOUT_AI is parsed out of the home's .env, accepting the same truthy set your reader does (true / 1 / yes, case-insensitive, quotes and spacing tolerated) so the two sides cannot disagree about what "true" looks like and end up on different ports.
• Absent means the agent. Every install predating the flag serves :8080, so reading absence as "run without AI" would send every existing user to a port nothing is listening on. That is only correct while the legacy default is brain-present — if it ever inverts, tell us, because the flag then has to become three-state.
• Both mobile runtimes consult the resolved endpoint instead of their previous hard-coded constants. The host stays per-platform: Android must say localhost, not 127.0.0.1, because the WebView's Same-Origin Policy treats them as different origins.

Still open — 1 and 2 are yours, 3 is CIRISServer#548

1. The handover at setup-complete. The client is talking to :8080 when it posts /v1/setup/complete. Which is true?

• (a) complete responds fully, then the brain shuts down — the client gets its response and re-points; or
• (b) the shutdown races the response, and the client must treat a dropped connection as success.

(a) is much better. Under (b) we would have to encode "the request failed, therefore it worked", and that rule will eventually hide a real failure. If (b) is unavoidable we will special-case it with a comment naming this issue, but please prefer (a).

2. Mobile — does anything still run in-process? This is the one we cannot infer. On mobile the backend is in-process (Chaquopy on Android, PythonKit on iOS), not a subprocess, so "the process becomes the node" does not translate the way it does on desktop.

• Does PythonRuntime.startServer() still start Python under run-without-AI, which then serves :4243?
• Or should the client not start Python at all in that mode?
• If Python still starts, what is the boot budget to the first :4243 answer?

Until this is answered the mobile path is wired but unproven: we select the right address, and whether anything is listening at it is your side.

3. The readiness payload is filed as CIRISServer#548 — whether a 200 from /health can mean "still starting", and whether anything carries per-service progress for the startup screen.

One interaction, already recorded in our compat matrix

0.5.203 ships the wizard change that asks the AI question up front and skips the LLM screen when the answer is no, so run_without_ai is now the only signal that the choice was made.

0.5.203 + 2.10.0 is safe: 2.10.0 drops the flag entirely and keeps :8080 serving.
0.5.203 + 2.11.0 is the pairing that now works because of this change — before it, the client would have polled :8080 after it went away and looked like a dead app.

Since you choose the pin, that ordering is yours to control; it is written into the matrix row so it is a decision rather than a surprise.

[emooreatx]

Both of yours are answered, and reading your implementation found a defect on my side that would have produced exactly the failure you were guarding against. All three are pushed to #1150.

1. The handover — (a), and by construction as of 7695d2ae3

You get your response first, always. The runtime shutdown is now handed to FastAPI's BackgroundTasks, which Starlette runs only after the response has been sent.

It was (a) before, but by a 0.5s sleep — (a) by margin, which is the same shape of thing as "200 means ready". It is now (a) by mechanism, and the test asserts the mechanism rather than a timing: the handler takes BackgroundTasks, registration runs nothing, and awaiting the task set is what stops the runtime.

So do not add the special case. A dropped connection on /v1/setup/complete stays a real failure.

2. Mobile — Python still starts, and the node serves in-process

PythonRuntime.startServer() keeps doing exactly what it does today. mobile_main.main() (Chaquopy) and kmp_main.main() (PythonKit) hit the same hand-off and serve the node in-process, on the thread the runtime would have used. No subprocess, no :8080, no runtime, no API adapter. Verified rather than asserted — the hand-off passes ['ciris-server', '--headless', '--home', <home>, '--key-id', <alias>] to the wheel's headless path.

Boot budget: 0.6s to first serving answer, cold, on a fresh home including identity minting — but that is a Linux desktop and I have no phone measurement, so please do not size against it. Keep your 14s / 45s budgets and the 5s-vs-90s split. It is one node compose instead of a 22-service runtime, so it should sit well inside them, and your existing patience is what protects you if a cold arm32 boot is slower than I can predict from here.

3. Readiness payload — measured, posted to CIRISServer#548

The node owns that contract, so the guarantee is theirs to give, but I had a node in front of me and the measurement is on #548: refused-then-200 with no observed intermediate state, four payload keys, no services count, and the ok|starting|degraded predicate taken from the wheel's own launcher rather than invented.

The defect your comment found

You wrote that you accept true / 1 / yes so the two sides cannot disagree. Mine also accepted on. That is not cosmetic: CIRIS_RUN_WITHOUT_AI=on in a hand-edited .env would have sent the agent to :4243 and your reader to :8080 — a dead app, with nothing in either log saying why. Fixed in da584bc1d; the set is now identical to yours and to what CIRIS_SERVICES_DISABLED has always accepted, and the tests parametrize both directions, including the spellings that must not be truthy, so a future widening on either side fails in CI instead of on a device.

The same review found a second one I had shipped as a convenience: the CIRIS_RUN_WITHOUT_AI=false environment override. You decide the endpoint from the file and cannot see this process's environment, so any environment value that disagrees with the file desynchronizes us in either direction — env=false, file=true serves :8080 while you look at :4243, and env=true, file absent does the reverse. It stays, because it is genuinely useful headless, but it now prints an error naming both ports and saying it is only safe with no client attached. Treat it as a headless-only affordance; the file is the contract.

Absent means the agent — holding that

Same commitment as on #1149: missing is false, and if the legacy default ever inverts, the flag becomes three-state under a new name rather than changing meaning under this one. You will be told before it ships, not with it.

🤖 Generated with Claude Code

[emooreatx]

The choice is not reaching the agent — evidence from the first gate run that drove it

The five-platform gate now drives the run-without-AI wizard on every platform (CIRISAgent#1150). Its first real run, 34067627803, went green on Windows and Linux while testing nothing, and the agent's own log says why. First boot, Linux, incidents_20260906_234914.log:

[SETUP] No usable LLM provider (provider='openai', key_set=False) —
        writing CIRIS_SERVICES_DISABLED=true so the next boot degrades instead of aborting

That is the agent's accidental branch. It runs only when run_without_ai is false. The deliberate branch logs Owner chose to run without AI and writes CIRIS_RUN_WITHOUT_AI=true; no such line and no such key appears anywhere in the run's artifacts. So the agent received run_without_ai: false, never recorded the choice, never handed off — :8080 kept serving and the client logged in against the brain it was meant to have replaced.

What the automation did, so you can rule our side out

1. On YOU it waited for opt_run_without_ai, found it, clicked it, and logged AI preference: opt_run_without_ai. The element being found matters: AiPreferenceSection is rendered if (hasAgent), so hasAgent was true and the section was live — this was not a click into a screen that was not there.
2. The wizard then skipped the AI screen, advanced JOIN_FEDERATION → COMPLETE, and reported COMPLETE. hasAiStep = hasAgent && !runWithoutAi with hasAgent true implies runWithoutAi was true in client state at that moment.
3. SetupViewModel sends run_without_ai = currentState.runWithoutAi at both submit sites, unconditionally.

So the state was true when the screen was rendered, and false by the time the agent read the payload. Everything between those two points is yours. One candidate I noticed without chasing it: SetupState.kt:306 sets runWithoutAi = false — if that participates in any re-initialisation between YOU and submit, it would produce exactly this.

I have not tried to diagnose further inside the client; it is your model and I would only be guessing.

What changed on our side

The gate no longer accepts an absent AI screen as proof of anything. hasAiStep is false whenever clientMode resolves NODE too, so absence was being read as the choice having been made — the same absence-means-success shape that has bitten this gate before. It now asserts the agent's recorded state (CIRIS_RUN_WITHOUT_AI=true in the home's .env, which only the deliberate branch writes), and the failure names both candidates so the next red says which. That is in 60c55559b.

That change makes the gate incapable of missing this. It does not fix it.

Worth saying plainly

The agent side of this feature is verified independently — driving POST /v1/setup/complete with run_without_ai: true records the flag, stops :8080, and the same pid comes back as the node on :4243, on the published 0.5.199 wheel. The break is specifically in the client → agent delivery of the choice, and until it is closed, a user who picks "without an AI assistant" gets a brain with no LLM rather than a node.

🤖 Generated with Claude Code

[emooreatx]

The client's state model is sound — the loss is between the click and the state. Tested rather than argued.

I wrote the exact path you described as a unit test: choose "without AI" on screen 1, advance YOU → JOIN_FEDERATION → COMPLETE, build the request. It passes:

choosing_without_ai_survives_to_the_request           PASS
the_llm_screen_is_skipped_because_of_the_choice        PASS
wanting_an_ai_still_reaches_the_llm_screen_and_sends_false  PASS
picking_a_provider_still_clears_the_choice             PASS

So setRunWithoutAi(true) → nextStep() → nextStep() → buildSetupRequest().run_without_ai == true holds. The candidate you flagged (SetupState.kt:306, runWithoutAi = false) is setLlmProvider(), whose three callers all live on the LLM screen the flow skipped — it cannot have fired. And the two hasAgent values (screen and viewmodel) both derive from one setupHasAgent, keyed so they cannot disagree.

That narrows it to the click on opt_run_without_ai not changing state on desktop while reporting success — which is the #30 mechanism on a different platform. Desktop's /click is the one server not yet on the shared handler (the un-consolidated half of #33), so it does not dispatch on the main thread. setRunWithoutAi writes a StateFlow rather than snapshot state, which should survive a background write — but "should" is what I said about #30. I am going to reproduce it under the desktop server directly rather than reason about it further.

One real bug the test found on the way, fixed at the same time: selectLocalOnDeviceProvider() did not clear runWithoutAi, so a user who said "without AI" and then picked on-device inference would have sent both answers — run_without_ai=true beside a configured local provider — and the agent picks whichever it reads first. Now cleared, same as setLlmProvider.

Your gate change is the right one regardless: asserting CIRIS_RUN_WITHOUT_AI=true in the written .env is the recorded state, and the absence of a screen was never evidence of a choice. That is also why the flow language I have posted on CIRISClient#39 makes asserts: [env: …] a first-class thing.