The companion app

Status: Accepted · Audience: Both · Area: N — Companion

---

Purpose

A fourth surface, on the device the operator actually has on them.

The CLI, TUI and web UI all run on the machine the stack runs on. That is the right place to set a stack up and the wrong place to be when the downloads stop at eleven at night. The question this feature answers is not “can we have an app” but what a surface is allowed to be once it is no longer on the host — what it may assume, what it must prove, and what it must say when it cannot reach anything.

It is one application serving two people. Which one it is for is decided by the credential that signs in, never by which build was installed (D6).

This feature owns getting connected and staying honest about it. What the app then shows is N2 and N3; what it uses of the device is N4.

Behaviour

It is a surface, and parity binds it

The app renders the core’s answers and decides nothing the core does not already decide (ADR-0017). Every action reachable from a terminal is reachable here, with one stated exception below.

The app has one identity, and the build does not choose it

An application’s identity is what the operating system installs it as. Two builds carrying two identities are two applications: they install beside one another, each with its own storage, and neither can read the other’s.

That is why this cannot be left to whoever ran the build. The pairing and the pinned fingerprint N1-R45 refuses to discard live in that storage, so a build that arrives under a different identity does not update the operator’s app — it appears next to it, empty, while the pairing stays in the one now orphaned. The operator is told to pair again and is given no reason, because from inside either app nothing is wrong.

It is also the Purpose’s rule read at the layer beneath it. Which person the app serves is decided by the credential that signs in, never by which build was installed; an identity derived from the builder’s environment makes which build was installed a distinguishing fact about the app, which is the thing that sentence forbids being load-bearing.

So the identity is declared once, in the repository, where it is reviewable and cannot differ between two people who both ran the build. A configured identity that disagrees with the declared one is refused rather than built, and the refusal names both — an identity is not something an operator can be expected to notice the drift of by reading a screen.

Reaching a stack is the operator’s choice, not the app’s

lemonfiber’s admin surface binds to loopback and refuses to widen without authentication (C6). A phone therefore cannot reach a stack until the operator has chosen to let it, and the app must not present that choice as something it can make on their behalf.

What it does instead is explain the choice in the operator’s terms, and name what has to be true: a bound address, authentication configured, both devices on the same network.

Pairing carries an address and a credential, once

A person types as little as possible. The app is pointed at a stack by scanning a code the operator’s own surfaces can display, and falls back to typed entry where a camera is unavailable or declined.

Typed entry has no software comparison behind it, so the person makes one. The app shows a short code folded from the whole fingerprint, and the stack shows the same code beside the material it produced. Both sides fold it the same way (N1-R73), and the stack shows it wherever it shows the material (N1-R74): a code the app asks somebody to check against a screen that does not carry it is a confirmation nobody can give.

What the stack says beside the material, it says to every surface at once, so it is in words each of them can show (N1-R76). A terminal says how to replace the certificate as the command that does it, and any other surface in its own way. A sentence naming the command would have the app telling the operator to type something into a phone that has nowhere to type it.

Whatever the route, the app exchanges the credential once at /api/session for a session, and carries that session in X-Lemonfiber-Token afterwards. The credential is not kept to be re-sent: a secret held for one exchange is a smaller secret than one held for every request.

Re-pairing is the same machine, said again

The app asks an operator to pair again often enough that it is a routine rather than an edge: a certificate the stack announced it would replace (C6-R19), an address DHCP moved, retained state that could not be carried forward (N1-R34). Each time, what comes back has to land on the machine already held.

Nothing in the material says which machine that is. The address moves — that is one of the reasons for re-pairing. The fingerprint changes — that is another. Matching on either identifies a stack by the very thing that changed, and gets it wrong in exactly the cases the app itself asked for. N1-R22 already refuses that inference for pinning; it is no better as an answer to which of my machines is this.

So the material names the stack, with the stack’s own identifier, and the app matches on that. The alternative is a second row for a machine the operator paired once — the app disagreeing with itself about how many machines are in the house, on a screen whose entire job is to say.

The SDK is the only way out, and a gap in it is a question rather than a workaround

Every call to the stack goes through sdk-php. The app issues no HTTP request of its own, builds no URL, and parses no envelope the SDK did not hand it.

Where the SDK does not yet expose something the app needs, that is where the work stops. The gap is raised against the SDK and the contract, and the app waits. It does not reach past the SDK to the endpoint, re-implement the call beside it, or approximate the answer from something adjacent.

This is the rule that keeps a fourth client from quietly becoming a third source of truth. The failure it prevents is the ordinary one: a screen needs a field nobody generated yet, somebody fetches it directly “just this once”, and the contract now has a consumer it does not know about. A missing capability is information — it says the contract or the SDK is behind — and information is worth more than the screen it was blocking.

The first run is a route through, not a screen to work out

N1-R35 says a launch with no stack configured offers pairing rather than an empty operator surface. That is the floor, and a single screen with two buttons on it meets the floor while leaving the operator to work out what this application is, what it needs of them, and which of the two ways to pair is the one they can actually do right now.

Setup happens at the machine, and the app has to say so before it asks for anything. N1-R4 puts first-run setup on the host, and somebody who installed the app first has arrived in the wrong place — they need to be told that, once, in a sentence, rather than discovering it by pairing and finding nothing to do.

So the first run is a sequence with a stated end: what this is, what has to be true at the machine, and then the pairing itself. Each step says which one it is and how many there are, because a sequence whose length is unknown reads as a form that might not end. It is leavable at every step, and leaving lands on the pairing screen rather than on nothing — the operator who already knows all of this should not be made to read it.

Two people arrive at the first screen. Somebody who runs the server is there to pair it, and somebody who was invited is there to watch. The first screen asks which, in words that name no part of the system, and only the operator’s door leads to the sequence above (N1-R35). The invited door is the household’s own short way in (N3-R26), and an invitation opened before any house is on the phone goes straight to it.

It happens once and is not a setting. The sequence is shown while the device holds no pairing, which is the same condition N4-R22 reads for the lock, and it stops being shown the moment one is held. Neither an operator nor a screen can ask for it again: a wizard that can be re-entered is a place to get stuck, and everything it says is available afterwards in the surfaces that own it.

An unreachable stack is a state, not a missing feature

The app never hides an action because it cannot currently reach the stack. It offers the action and reports, in the words of G4, that the stack could not be reached and what to check.

This is the honest form of parity across a device boundary: the surface offers everything, and reachability is a condition it reports rather than a capability it lacks.

A frame reads once, and again only when it declared it would

A screen paints before it reaches the stack (N1-R25), and what it paints is built from values the frame goes on to read many times — a template asks for a count, then for the same count in a sentence beside it, then for the list the count came from. Each of those is a read of what the screen holds, and none of them is a reason to reach the machine a second time.

The failure this rules out is quiet, because it looks like nothing at all on the machine that suffers it. A screen that reaches the stack per value read, or per character typed into a filter, works perfectly in a test and on a desk. It is on the operator’s phone, over their own network, against a machine that is also serving the film somebody is watching, that one frame becomes thirty requests — and the cost lands on the thing the app exists to keep an eye on.

So the reading is an act the screen performs, once, and everything the frame asks afterwards is answered from what came back. Beyond that, a screen reaches a stack on the cadence it declares (N1-R27) or when the operator did something — never because a value was read, a key was pressed, or a screen was rebuilt (N1-R38).

A screen may hold the stream instead of reading

Some of what the core says is said only on its event stream. The health summary is the one that matters most: the core computes it once, into the dashboard, and publishes the dashboard nowhere else, so the one line every surface must say identically (G7) is on the stream or it is nowhere (ADR-0026).

A screen showing it holds a subscription rather than reading, and the subscription is that screen’s one read (N1-R67). Opening it is a call like any other, bounded like any other (N1-R68). Once it is open, what the core sends arrives on the core’s cadence, to every listener at once, and the screen takes what has already arrived on a cadence it declares. Taking it does not reach the stack, because nothing is sent (N1-R69).

A stream can go quiet without failing, so silence has a bound, and the bound is the contract’s: the core breaks silence with a heartbeat, and twice its interval with nothing heard is a broken stream (ARCH-R61). From then on the last value is a stale one, and a summary that was healthy is not healthy any more; it is unknown (N1-R70). A broken subscription is reopened on a declared cadence (N1-R71).

A subscription is held only while somebody is looking at what it carries. A phone in a pocket holding one open would wake its radio on every beat, all night, for a screen nobody can see (N1-R72).

Nothing is presented as current that is not

A value read four hours ago, shown without saying so, is the failure this product’s own dashboard rules exist to prevent. Anything the app shows from a previous connection is marked with when it was read, and is never mixed indistinguishably with a live reading.

A screen that refreshes on its own does not tell the operator how often. The cadence is declared by the screen, where a test holds it, and not printed: a line saying how often a screen looks is machinery, and it says nothing about whether what is shown is current. What does say that is the age a reading carries once it is no longer current (N1-R9), so that is what the operator is shown.

First-run setup does not cross the boundary

G1-R14 asks that setup be completable from every surface. It cannot be completed from a phone, and the reason is structural rather than a shortfall of effort: the thing that lets a phone reach the machine — a bound, authenticated admin surface — is created during setup. A phone cannot perform the act that makes a phone able to perform acts.

Reconfiguration (A4) is offered in full. First-run setup is declined with that reason stated, rather than absent.

More than one stack

An operator may run more than one. The app holds several, each with its own address and session, and never lets a reading from one appear under another. Switching is explicit.

Honest about the transport it got

C6’s deliberate position is that a LAN stack serves plain HTTP unless the operator has arranged otherwise, and that self-signed TLS is not on by default because it trains people to click through certificate warnings.

The app is the one client that cannot take that offer. A pin is compared against a certificate while the connection is being set up (ARCH-R99), and a plain HTTP address presents no certificate, so there is nothing for the pin to decide and ARCH-R60 refuses the address. Pairing a phone therefore requires TLS on the stack, and that is a cost stated here rather than discovered at the first pairing.

The warning-fatigue reasoning C6-R7 rests on does not apply to this surface. It is about a browser offering a human the choice to proceed. The app offers no such choice: it refuses, in software, against a value it was given out of band (ADR-0018). Self-signed is exactly what it expects, because no public authority will sign the name a stack is reachable under.

So what the app reports under N1-R12 is an encrypted connection whose certificate it pinned — not the platform trust store’s opinion of it, which it does not consult.

When remote access (I1) lands, the same session travels the overlay instead. The app’s conversation does not change.

States

Edge cases

Acceptance criteria

Related

• G1 — the surfaces this joins, and the parity rule it inherits
• C6 — the binding policy that decides whether a phone can reach anything
• D6 — who is signing in
• G4 — how a refusal is worded
• I1 — the transport this is built to move onto
• N2, N3, N4