[bug] One laptop still shows as three machines — nothing has claimed an id yet, the stale names can never be claimed, and the Terminals page does not fold by machine

[serge-ivo]

#379 shipped the right mechanism. Two things stop it clearing what is already on the owner's
account, and one of them will still be true after every machine upgrades.

Live state, measured on the owner's account today (post-#379 deploy)

GET /v1/terminals/nodes
  Mac                      connected=true   lastSeen=2026-08-07 23:23  v=0.4.35  16 instances  machineId=None
  RLs-MacBook-Air.local    connected=false  lastSeen=2026-08-07 09:20  v=0.4.35  16 instances  machineId=None
  RLs-MacBook-Air          connected=false  lastSeen=2026-07-16 22:28  v=0.4.18   2 instances  machineId=None
  Sergeys-Mac-mini.local   connected=true   lastSeen=2026-08-07 23:23  v=0.4.22   4 instances  machineId=None

The first three are one laptop. Every row has machine_id: NULL, so foldNodesByMachine has
nothing to fold and aliasNodesFor can prove nothing — which is exactly the fail-closed behaviour
#379 designed, working as intended.

1. Nothing has claimed an identity yet, because the machine is on an old CLI

Published: 0.4.40. Installed and running on that laptop: 0.4.35, which contains zero
occurrences of machineId in its bundle. So no registration has ever carried an id, and none will
until the CLI is upgraded and pags up restarted.

Not a bug — but worth stating plainly somewhere the user sees it, because from the console the fix
looks like it did nothing. A runner that predates the feature is indistinguishable, in the UI, from
one that has it and found nothing to merge.

2. After the upgrade, the two stale rows still will not merge — by construction

machine.ts's own docstring says it:

"on the first run the machine can only claim the hostname it already registered under, which
changes nothing. The moment the network renames it, the list holds BOTH names"

The name history starts at upgrade time. A fresh machine.json on that laptop will hold
{ id, names: ["Mac"] }, so claimMachineNames stamps the Mac row and nothing else.
RLs-MacBook-Air.local and RLs-MacBook-Air were minted before any id existed and no machine will
ever claim them — they are permanent residue, listed forever as offline machines the user
recognises as their own laptop.

That is the correct trade (guessing costs the guarantee), and it leaves the account needing a
manual escape that does not exist.

There is no way to forget a node. No route, no control. The only listed options are to leave
them or edit D1 by hand.

3. The picker folds; the Terminals page does not

GET /v1/instances/:id/runner-node folds correctly — instances.ts:421 calls
foldNodesByMachine, with the reasoning in a comment.

GET /v1/terminals/nodes does not: grep machine_id workers/api/src/routes/terminals.ts
returns nothing, and groupTerminalNodes groups by the runner_node string. That endpoint feeds
both the Terminals page and the "Runs on" tiles in RunnerPanel (machinesToShow ←
/v1/terminals/nodes), which is the surface the duplicates were reported on.

So once ids do exist, the two surfaces will disagree: the picker's dropdown shows one machine and
the tiles beside it still show three.

Do

• Fold /v1/terminals/nodes by machine_id — reuse foldNodesByMachine; the rows already
  carry the column. Without this the fix is invisible on the page it was reported from.
• "Forget this machine" — an explicit, confirmed user action (never a cron, never a
  delete-on-stale sweep: a laptop that is merely closed must not lose its pins). Needs a route
  and a control on the Terminals page. Guard the case where the node still holds pins or
  coding_sessions.runner_node rows — offer to repoint them, or refuse and say why.
• Say when a runner is too old to be identified. The node rows carry runner_version; a
  row whose version predates machine-id support could read "this machine's CLI is 0.4.35 —
  upgrade to merge it with its other names", which turns an invisible no-op into an
  instruction.

While we are here: "one pags up per machine" is not what is enforced

The 409 lives at the RelayDO and is keyed per (instance, node NAME) — a second runner on the
same hostname for the same instance is rejected unless --force. With three hostnames, the
platform sees three machines and nothing ever conflicted. Node rows are also never deleted on
disconnect, so each identity persists after its name stops being used. Both behaviours are correct
in isolation; together they are why one laptop can occupy three slots and no guard notices.

Follows #379 (the mechanism) and #380. Evidence gathered live via the MCP server + REST on the
owner's account, 2026-08-08.

[serge-ivo]

This is not cosmetic — six agents are broken by it right now

I checked what actually references the stale names before recommending any cleanup, and the answer changes the ticket.

RLs-MacBook-Air.local   connected=false   38 coding sessions
   pinned here (6): FWS platform · tmux Operator · Terminal Operator · kitty Operator · iTerm2 Operator · Heartfull
RLs-MacBook-Air         connected=false    0 sessions   0 pins
Mac                     connected=true      2 active sessions   3 pins

Six instances are still pinned to a machine name that no longer exists. getBoundRunnerConn treats a pin as authoritative and does not fall back, so every runner call on those six fails. Verified live just now on Terminal Operator (da39100b):

terminal_list_targets → "No runner is connected for this agent — run `pags up` …"

…while pags up is running on that exact laptop, as Mac, with sixteen live sockets. The original #379 symptom is still live for six agents; only the instances that were manually repinned recovered.

And the CLI upgrade alone will not fix them. aliasNodesFor resolves aliases of the pinned node — and the pinned row (RLs-MacBook-Air.local) has machine_id: NULL. A fresh machine.json claims only Mac, so the pinned row is never stamped and no alias is ever proven.

Do not delete the rows — claim them

Deleting is the intuitive cleanup and it is the wrong one: the pins live in agent_instances.config.runnerNode, not in the node row, so removing the row orphans six pins and 38 session rows (groupTerminalNodes already has a comment for "a session whose machine no longer has a registration row") and leaves the same six agents broken with less evidence on screen.

The mechanism already does this correctly if it is given the names. claimMachineNames stamps machine_id on every row whose runner_node is in the claimed list. So:

1. upgrade the CLI (0.4.35 → 0.4.40),
2. seed ~/.config/proagentstore/machine.json names with the hostnames this machine has used — ["Mac", "RLs-MacBook-Air.local", "RLs-MacBook-Air"],
3. restart pags up.

All three rows take one machine_id, aliasNodesFor proves they are one machine, the six pins route to the live socket, and foldNodesByMachine collapses them in the picker. No pin edits, no row deletes, no D1 surgery.

That step 2 is the product gap. A user should not hand-edit JSON to recover from a hostname change. On first run the CLI should ASK: "PAGS knows 3 machine names for this account — is this machine also RLs-MacBook-Air.local?" The server already knows the candidate list. It must be user-confirmed and never automatic: a wrong yes merges two genuinely different machines, which is the one thing the fail-closed design exists to prevent.

Three structural gaps, in the order I would fix them

1. A pin has no referential integrity. Nothing validates it on write, nothing revalidates it when its target stops being seen, and nothing surfaces the break — six agents have been silently unroutable and the only signal is a tool call failing. /runner-node already returns nodesDetail with connected/nodeOnline, so "this agent is pinned to a machine last seen 21h ago; Mac is connected — repoint?" is a read, not new plumbing. Cheapest fix on this list, biggest immediate return.
2. There is no node lifecycle. Rows are created on register and never expire, never merge, never get forgotten. Every mechanism added so far — the id, the aliasing, the fold, the proposed forget button — compensates for that absence. A lifecycle — active → dormant (unseen N days: hidden from pickers, retained) → forgettable (nothing references it any more) — makes this class self-clearing and is less code than another aliasing layer.
3. Identity is still second-class. The hostname remains the routing key, the DO name, the pin value and the session column; machine_id can only annotate after the fact. So a rename still mints a row, a DO and a possibly-stranded pin — the alias papers over it rather than preventing it. The endgame is id-as-identity with hostname as a display label, staged (write id → read id-or-name → pin by id → DO by id, with a dual-accept soak). Correctly deferred in [bug] A machine's identity is os.hostname(), so one laptop is three machines — and a pin to a name it no longer uses answers every call with "run pags up" while pags up is running #379; worth naming as the destination so the aliasing layer is understood as a bridge and not the answer.

[serge-ivo]

All three Do items are now delivered. One thing raised in the comment thread is not done — named below, and the reason I am leaving this open rather than closing it.

Shipped

1. Fold /v1/terminals/nodes by machine_id — fa0a24a, corrected by a5e2e8a.

The correction is the interesting half and it was found in production, not review: a machine id is not carried consistently across a hostname's rows. There is one row per (instance, hostname) and a pags up stamps the id only on the instances it registers, so an instance it did not attach keeps NULL under the same hostname. Reading the id off whichever row arrived first split one machine in two, and folded nothing when the NULL row led. Identity is now resolved across a name's rows before grouping — but only when the name is unambiguous, so two laptops both called Mac still never merge.

2. "Forget this machine" — 4c0c70a. DELETE /v1/terminals/nodes/{node} + a Forget control on each machine card.

• Addressed by one name, resolved to the whole machine — forgetting a single name of a folded laptop would leave its tile on screen minus some of its rows.
• Refuses while an agent is pinned there, while a coding session is open, or while it is connected — and the refusal names what to repoint. This is the invariant, not caution: the node row is also the proof aliasNodesFor uses to route a stranded pin onto the machine's current name, so deleting it can break an agent [bug] A machine's identity is os.hostname(), so one laptop is three machines — and a pin to a name it no longer uses answers every call with "run pags up" while pags up is running #379 had already healed. Ended sessions deliberately do not block (history, and a laptop with any history could otherwise never be forgotten).
• A name two machines share is refused, not guessed at.
• Only instance_runtime_nodes is touched. Nothing on the machine changes; pags up re-registers it.

3. "Say when a runner is too old to be identified" — 4c0c70a. Each node carries identityHint.

It deliberately does not tell a current CLI to upgrade — one with no id could not write its id file, and prescribing the upgrade there would repeat #379's own reported symptom, where the only remedy offered was the thing already done. An unparseable version says nothing.

Verified live, on this account

GET /v1/terminals/nodes
  Mac                     machineId=3901c9c4-…  aka=['RLs-MacBook-Air','RLs-MacBook-Air.local']  v=0.4.40  connected=True
     identityHint=None
  Sergeys-Mac-mini.local  machineId=None        aka=[]                                          v=0.4.22  connected=False
     identityHint="This machine's CLI is 0.4.22 — upgrade to 0.4.40 or newer and restart `pags up` so it can be merged with its other names."

Four rows are now two machines, the laptop's three names are folded, and the Mac-mini's silence is explained on screen instead of looking like a no-op. DELETE …/nodes/NoSuchMachine-pags393 → 404 {"error":"No machine is registered under that name."} (handler live, provably non-destructive).

Not verified in production: a successful forget and the pinned/session/connected refusals against real rows — that would mean deleting the owner's real Mac-mini registrations, which I am not doing unasked. All four paths are covered by unit tests.

A defect found while doing this, and fixed

The aka line this ticket added was truncate shrink-0. truncate needs a width to clamp to and shrink-0 promises never to have one, so at 320px in WebKit it drew straight out of the card and was painted over by the Forget button — two overlapping controls, one unreadable. Every horizontal-overflow guard in the repo measured zero for that page and always would: they compare scrollWidth to clientWidth, and text escaping its own box does not widen the document. Fixed, and there is now a source guard for the cause (gating at zero — shrink-0 with an explicit width is a legitimate fixed label column and stays legal).

Left open for

The comment's step 2 product gap: on first run the CLI should ask whether this machine is also the other names on the account, instead of the user hand-editing ~/.config/proagentstore/machine.json. The server already knows the candidate list; it must be user-confirmed and never automatic. That is a CLI change with its own release, and it is the thing that makes this class self-clearing for the next person — it should be split into its own issue rather than absorbed here.

The three structural gaps the comment lists (pin referential integrity, node lifecycle, id-as-identity) are direction, not scope, and are untouched.

[serge-ivo]

Re-verified live. All three items hold. Split the remaining gap out to #460 and closing.

Independent re-check against the deployed API today (fa0a24a, a5e2e8a and 4c0c70a are all
ancestors of b6f6c9f6, deployed 13:02 UTC).

Measured, 2026-08-08 13:13 UTC

GET /v1/terminals/nodes
  Mac                     machineId=3901c9c4-004f-435e-bfc5-0b87b7ac5173
                          aka=["RLs-MacBook-Air", "RLs-MacBook-Air.local"]
                          v=0.4.44  connected=true   18 instances   identityHint=null
  Sergeys-Mac-mini.local  machineId=null   aka=[]
                          v=0.4.22  connected=false   4 instances
                          identityHint="This machine's CLI is 0.4.22 — upgrade to 0.4.40 or newer
                                        and restart `pags up` so it can be merged with its other names."

Four rows read as two machines. The laptop's three names are one tile. The Mac-mini's silence is
explained on screen instead of looking like the fix did nothing.

• Fold /v1/terminals/nodes by machine_id — routes/terminals.ts:174-191, resolving identity
  across a name's rows before grouping (adoptableIdByName), which is the correction a5e2e8a
  found in production: one pags up stamps the id only on the instances it registers, so a NULL row
  under the same hostname was splitting one machine in two.
• "Forget this machine" — terminalRoutes.delete("/nodes/:node") (routes/terminals.ts:381)
  + the control at store/console/src/pages/Terminals.tsx:46-57, addressed by one name and resolved
  to the whole machine, refusing while a pin, an open session or a live connection still points at it.
• Say when a runner is too old to be identified — identityHint, applied at
  routes/terminals.ts:259, live above.

I did not re-exercise a successful forget: it would delete the owner's real Mac-mini registrations,
which is a live-data change I am not making unasked. The four paths are unit-tested and the handler is
provably reachable and non-destructive on a miss.

What was left open, and where it went

The comment thread's step-2 product gap — on first run the CLI should ask whether this machine is
also the other names on the account, instead of the user hand-editing
~/.config/proagentstore/machine.json — is filed as #460, with the constraints that make it safe
(user-confirmed only, unclaimed names only, no prompt without a TTY, a remembered decline) and the
alternatives already rejected.

It is a CLI change with its own release and it does not belong here: this ticket's mechanism is
delivered and verified, and keeping it open as a second home for #460's work is exactly the pattern
this audit exists to stop. The evidence that #460 is real is still on the machine — machine.json
carries the hand-written name list today.

The three structural gaps the thread lists (pin referential integrity, node lifecycle, id-as-identity)
remain direction rather than scope, and are untouched. Pin referential integrity in particular is
live right now on another instance — see #440.

Closed.