Skip to content

Document the desktop orchestrator's shell contract - #1686

Open
phantomic12 wants to merge 3 commits into
CodebuffAI:mainfrom
phantomic12:docs/desktop-shell-contract
Open

phantomic12 wants to merge 3 commits into
CodebuffAI:mainfrom
phantomic12:docs/desktop-shell-contract

Conversation

@phantomic12

@phantomic12 phantomic12 commented Nov 17, 2026 •

Copy link
Copy Markdown

What this changes

Adds docs/desktop-shell-contract.md: the boundary between the desktop shell and the
orchestrator it starts, written down once instead of re-derived per client.

It covers:

  • the two-process shape (free port, 127.0.0.1, cwd, stdout as the progress channel);
  • the nine boot-phase names and the ready line, with the shell's two budgets (30 s spawn → ready,
    60 s ready → /healthz);
  • the stdin bootstrap line, and why secrets are not in the environment;
  • the HMAC lifetime socket — challenge/response, 3 s pings, 10 s tolerance — which is how a
    killed shell takes its server down instead of orphaning it;
  • the x-freebuff-launch-id (or freebuff_launch_<port> cookie) gate that answers
    401 unauthorized on every /api/* path;
  • the environment variables a shell sets, including the profile path and the lock-wait that fails
    with exit 75.

Why

Everything above is observable from a shipped install but undocumented, and the observations are
easy to get subtly wrong — the phase whitelist, the two different timeouts, and the fact that the
launch id travels on stdin rather than in the environment are all things a second implementer
would otherwise rediscover by trial and error. This is the documentation half of an experiment
that replaced the shell with a native UI; the shell code is not part of this PR, and the issue
linked below asks whether it should be.

No product behaviour changes: documentation only. It touches no path outside docs/.

Companion issue: #1685 (area: Desktop app). A native shell is a direction question, not a docs
question, so it is asked there rather than shipped here — if the answer is "not the direction",
this page is still true and still useful.

The experiment itself — a reference implementation of this contract in Rust on Rune, with the
same panes, tokens and geometry — is public at https://github.com/phantomic12/freebuff-rune,
so the claims above can be checked against running code rather than prose.

A desktop shell has to start the orchestrator, keep it alive and talk to it,
and none of that boundary is written down anywhere public: the boot phase
names, the readiness budgets, the stdin bootstrap line, the HMAC lifetime
socket and the x-freebuff-launch-id gate on /api/* are all re-derived by
reading a shipped install.

This documents the boundary as observed from one, so a client, a test harness
or a native shell can drive the same server. No user data, no server code.
@codebuff-team

Copy link
Copy Markdown
Contributor

The instinct here is good — a written contract for the shell↔orchestrator boundary (phases, timeouts, stdin bootstrap, HMAC lifetime socket, /api/* gate, env vars) is exactly the kind of thing that should exist once instead of being re-derived by every integrator. The writing is clear and the structure (two-process diagram, phase list, budgets, env table) is good documentation style.

The problem is provenance. This is stated to be "recovered from a shipped install," but the PR gives no pointer to how each claim was derived — no reference to specific binary strings, no version/build it was checked against, no indication of what happens if the orchestrator changes behavior across releases. The level of precision (exactly nine phase names, 30s/60s budgets, 3s ping / 10s tolerance, the exact JSON shape of the bootstrap line, exit code 75) is the kind of detail that's either exactly right or subtly wrong in a way a maintainer can't check by reading this diff alone — there's no source reference, no test, and no versioning note ("as of build X"). Baking unverified specifics into a permanent doc is worse than no doc if any of it is stale or mis-observed.

Separately: the companion issue (#1685) is explicitly framed as "should a native shell exist," and this PR ships 100 lines treating that shell's exact protocol as settled fact ahead of that discussion. That's a minor sequencing issue, not a blocker, but it means this doc is coupled to a product direction that hasn't been decided.

Before this is portable: add a note on what build/version this was checked against, and ideally point to the specific observed artifacts (strings in the binary, captured traffic, etc.) so a maintainer can spot-check the nine phase names and the two timeouts against the real source quickly rather than having to re-derive the whole thing themselves.

@codebuff-team codebuff-team added bot:triaged Classified by the community triage bot pr:needs-work Right idea, not mergeable as written labels Nov 18, 2026
The review asked for provenance: which build this was checked against, and
what to grep to spot-check a claim without re-deriving it. Adds the desktop
version (0.0.203), the SHA-256 of each artifact read, and a table of the
literal behind every constant in the document; the bundle keeps its source
paths, so src/server/boot-phase.ts and src/server/services/orchestrator-lock.ts
are named as the places to look.

Also states the staleness risk plainly: no handshake carries a protocol
version, so a build that renames a phase or moves a budget breaks a client
silently. The shape is what to rely on; the constants are what to re-read per
release. And scopes the page away from the direction question in the companion
issue -- a harness or a diagnostics client needs these facts regardless.
@phantomic12

Copy link
Copy Markdown
Author

Fair on both counts. Pushed a provenance section (c1d1b35); here is what it says and what I chose not to do.

Build and artifacts. Written against installed Freebuff Desktop 0.0.203. The doc now records the SHA-256 of each file a claim was read from — resources/app.asar, app/electron/orchestrator-startup.cjs, shell-lifetime.cjs, launch-bootstrap.cjs, resources/orchestrator/orchestrator.js — so a diff of the doc against a newer install is a hash comparison first, then a grep.

Per-claim pointers. A table maps every constant to a file and line and quotes the literal, so the spot-check is mechanical rather than a re-derivation:

claim literal
nine phases, in order orchestrator-startup.cjs:22, const BOOT_PHASES = new Set([
30 s spawn → ready orchestrator-startup.cjs:35, const READY_LINE_BUDGET_MS = 30_000
60 s ready → /healthz orchestrator-startup.cjs:37, const HEALTH_BUDGET_MS = 60_000
exit 75 orchestrator.js, var PROFILE_BUSY_EXIT = 75 … process.exit(PROFILE_BUSY_EXIT)
/api/* gate orchestrator.js, pathname.startsWith("/api/"), LAUNCH_TOKEN_HEADER = "x-freebuff-launch-id"

The bundle still carries its source paths, which is the better pointer for your side: the phase list is src/server/boot-phase.ts and the lock and exit code are src/server/services/orchestrator-lock.ts — the shell's own comment says the caller's copy and boot-phase.ts are held equal by a test, so a mismatch there is a real finding, not a doc bug.

Nothing needs a build to check. Two greps, both in the doc:

npx @electron/asar extract "<install>/resources/app.asar" app
grep -n "READY_LINE_BUDGET_MS\|HEALTH_BUDGET_MS" app/electron/orchestrator-startup.cjs
grep -n "PROFILE_BUSY_EXIT\|invalid launch id\|LAUNCH_TOKEN_HEADER" \
  "<install>/resources/orchestrator/orchestrator.js"

On staleness. I agree these are exactly the details that are either right or subtly wrong, so the doc now says out loud that nothing is negotiated — no handshake carries a protocol version, so a build that renames a phase or moves a budget breaks a client silently. It separates the durable shape (phase line on stdout, ready line with a launch id, stdin bootstrap, HMAC lifetime socket, launch-id header) from the constants that should be re-read per release, and it states that where the page disagrees with a newer build, the build wins.

If you would rather not carry versioned specifics in a permanent doc at all, the alternative is to cut the constants and keep only the shape — say so and I will trim it; I kept them because a harness that does not know the budgets cannot fail a slow boot.

On sequencing, taken: the page no longer leans on the native-shell question. The new Scope section says the facts are useful to a test harness or a diagnostics client whether or not a native shell is ever built, and that nothing in it argues for a shell. The companion issue stays the place where that direction is decided — it is now referenced as context only, not as justification.

… from

An update landed while this page was under review: orchestrator.js moved from
6a34e09a2722c87b to c0267ead585538d3 (the shell's app.asar hash did not change).
Re-read every literal against the newer bundle -- the phases, both budgets, the
launch-id header, PROFILE_BUSY_EXIT = 75 and its stderr line are all still there,
unchanged -- so the page still describes the current build, and the hash pair
records that it was checked rather than assumed.
@phantomic12

Copy link
Copy Markdown
Author

One thing to flag on the provenance table, since it is the part you asked about: the orchestrator
bundle was replaced under us while this was open. resources/orchestrator/orchestrator.js moved
from 6a34e09a2722c87b to c0267ead585538d3, while app.asar kept its hash. I re-read every
literal in the table against the newer bundle before updating it — the nine phases, both budgets,
x-freebuff-launch-id, PROFILE_BUSY_EXIT = 75 and its stderr line are all still there unchanged —
so the page still describes the current build, and the table now carries both hashes as the record
of that check. c3239f2.

That is also the argument for the "across versions" paragraph at the bottom of the page: the
bundle is the piece an update replaces on its own, so a client that hard-codes these constants
learns about a rename only by breaking.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bot:triaged Classified by the community triage bot pr:needs-work Right idea, not mergeable as written

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants