[bug] A pinned-to-an-offline-machine agent is told to run `pags up --force` — describeFacts drops the two fields the pinned-machine diagnosis needs, so the branch is dead on every surface but one

[serge-ivo]

The one diagnosis that names a pin is unreachable from the surface that needs it — so a pinned agent is told to run pags up --force

diagnoseAttachment has a pinned-machine-offline branch that says the right thing. describeFacts,
which is how three call sites reach it, does not pass the two fields that branch depends on. So every
one of those call sites falls through to machine-online-agent-detached and prescribes
pags up --force — the remedy the pinned case's own code comment says must not be offered.

Measured, production, 2026-08-08 13:2x UTC

One instance, 12ebf1f0-… ("Coder Home"), pinned to a machine that is switched off:

GET /v1/instances/12ebf1f0-…/runner-node
 runnerNode: "Sergeys-Mac-mini.local"
 nodesDetail: Mac connected=true nodeOnline=true
 Sergeys-Mac-mini.local connected=false nodeOnline=false
 resolvedNode: null

Two surfaces, same instance, same second:

GET /v1/instances/12ebf1f0-…/runtime/status ← pin-aware
 runtime.status "online" runnerNode "Mac" runnerVersion 0.4.44 health.ok true

GET /v1/instances/12ebf1f0-…/coding/repos ← pin-blind
 recheck.reason "The machine is online but this agent isn't attached — another runner on it may
 already hold this agent. Try: `pags up --force`"

Both sentences are produced by the same function, from the same facts, about the same instance. The
second is wrong in both halves: nothing else holds this agent, and --force cannot fix it. pags up
is already running on Mac with a live socket for this very instance. What the user needs to do is
change one dropdown.

Where it is

lib/runtime-attachment.ts:38-52 — the diagnosis takes the pin:

pinnedNode?: string | null;
liveNodeExcludedByPin?: string | null;

and :63-73 uses it, before the heartbeat check, with the reasoning already written down:

// BEFORE the heartbeat check, deliberately (#380). … a pin onto a dead machine reads as "fresh"
// and diagnoses `machine-online-agent-detached`, prescribing `pags up --force` for a machine that
// is switched off.

That comment describes, exactly, the output measured above.

lib/runner-availability.ts:110-116 — the adapter that drops them:

export function describeFacts(facts: RuntimeFacts): AttachmentDiagnosis {
	return diagnoseAttachment({
		hasRuntimeRow: facts.hasRuntimeRow,
		relayConnected: facts.relayConnected,
		lastSeenAt: facts.lastSeenAt,
	});
}

RuntimeFacts (lib/instance-connectivity.ts:12-20) carries no pin at all, so the adapter has nothing
to forward even if it wanted to. Grepping the whole tree, pinnedNode is supplied by exactly one
caller — routes/instances.ts:793-806, the /runtime/status route — which is why that surface gets it
right and no other does.

The three call sites that inherit the wrong answer

1. routes/coding-repos.ts:176 (noRunnerReason) → the recheck.reason above. This is the one that
   matters most, because it is the sentence [bug] A repo has been marked broken for five days by a dropped WebSocket — a transport failure is stored as the repo's state, and no verdict is ever re-taken #440 added specifically so a stuck repo would explain
   itself, on the very instance [bug] A repo has been marked broken for five days by a dropped WebSocket — a transport failure is stored as the repo's state, and no verdict is ever re-taken #440 was filed about.
2. lib/runner-availability.ts:161 (pauseMessage) → what a Workflow announces into the owner's
   thread when it pauses for an unreachable runner. A pinned instance is told to --force a machine
   that is off, for up to 30 minutes of waiting.
3. lib/runner-availability.ts:175 → the same, on the terminal path.

Two decisions composing into the bug

Neither half is wrong on its own, which is why it shipped. diagnoseAttachment was given the pin
because #380 proved it was needed. describeFacts was written as a thin adapter over RuntimeFacts,
which is a connectivity record and has no business knowing about instance config. The defect is that
the second is the only path the first is reached by, outside one route — so the branch exists, is
correct, is tested, and is dead everywhere it is needed.

What to do — cheapest first

1. Carry the pin on the facts. Add pinnedNode and liveNodeExcludedByPin to RuntimeFacts and
   populate them in runtimeConnectivity (which already reads the instance row to resolve routing, so
   the pin is in hand), then forward both in describeFacts. One field each, and all three call sites
   are fixed at once because they all go through it.
2. Make the reason assertable. routes/coding-repos.test.ts:377 currently asserts only
   expect(String(body.recheck.reason)).toMatch(/\S/) — that the reason is non-empty. That is why a
   wrong reason shipped green. Assert the pinned case names the pinned machine and the live one, and
   does not contain --force.
3. Pin the invariant where it can be stated once: no diagnosis whose state is
   pinned-machine-offline may carry a remedy, and no diagnosis produced for an instance with a live
   socket on a pin-excluded node may be machine-online-agent-detached.

Alternatives considered and rejected

• Have coding-repos.ts call diagnoseAttachment directly with the pin. Rejected: it fixes one of
  three call sites and leaves the workflow pause messages wrong, which is the harder failure to notice
  because it appears mid-run in a chat thread rather than in an API response.
• Drop the pinned-machine-offline branch and let the pin surface only in /runtime/status.
  Rejected — the branch is correct and [bug] /runtime/status answers "attached · Connected." for an instance whose pin points at a dead machine — the pin-blind fallback overrides the pin-aware resolution (#238) #380 built it for a reported symptom. The problem is reach, not
  design.
• Make getBoundRunnerConn fall back to a live node when the pin is offline. Firmly rejected, and
  out of scope: the pin is authoritative by design ([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/[bug] /runtime/status answers "attached · Connected." for an instance whose pin points at a dead machine — the pin-blind fallback overrides the pin-aware resolution (#238) #380), and a silent fallback would run an
  agent's coding session on a machine the owner did not choose. The fix is to explain the pin, not to
  ignore it.
• Widen RuntimeFacts into a general "everything about this instance" record. Rejected as scope
  creep; two named fields with a comment saying why connectivity has to know about the pin.

Acceptance criteria

• With an instance pinned to an offline machine while another machine holds a live socket for it,
  GET /coding/repos returns a recheck.reason that names both machines and tells the user to
  change "Runs on" — and does not contain pags up --force.
• The same holds for a Workflow pause announcement on that instance.
• A test asserts the content of the pinned-case reason, not merely that it is non-empty.
• The unpinned machine-online-agent-detached case still says pags up --force, unchanged.

Regression risk

• describeFacts feeds user-facing copy on three surfaces; changing what it returns changes three
  messages. The existing runtime-attachment.test.ts covers the branch logic and should catch a
  mis-ordering, but the adapter is what is untested — add a case there specifically.
• Populating the pin in runtimeConnectivity adds an instance-config read to a function used in a
  batched path (MAX_RELAY_PROBES, subordinate_status). Resolve it from the row already being read
  rather than adding a query per instance.

Files: workers/api/src/lib/runner-availability.ts:110-116,161,175,
workers/api/src/lib/instance-connectivity.ts:12-20, workers/api/src/lib/runtime-attachment.ts:38-73,
workers/api/src/routes/coding-repos.ts:176-195, workers/api/src/routes/instances.ts:793-806,
workers/api/src/routes/coding-repos.test.ts:377.
Found while auditing #440, whose fourth item this defeats. Related: #379, #380, #237.

[serge-ivo]

Shipped in 07ec7af, deployed — item 1, which fixes all three call sites at once

RuntimeFacts now carries pinnedNode and liveNodeExcludedByPin, runtimeConnectivity populates
them, and describeFacts forwards both. Because all three call sites reach diagnoseAttachment
through that adapter, routes/coding-repos.ts's recheck.reason and both Workflow pause messages
are fixed by the same two lines.

The batched-path regression risk was real, and is handled

The issue warned that populating the pin adds an instance-config read to a function used under
MAX_RELAY_PROBES / subordinate_status. runtimeConnectivityMany reads every instance's
config.runnerNode in one batched statement, and calls liveNodeIgnoringPin only where a
pin exists AND nothing resolved. The unprobed tail gets its pin but never an invented live node, so
it degrades to its previous answer rather than to half a diagnosis.

The assertion has teeth now

coding-repos.test.ts:377 asserted toMatch(/\S/) — that the reason was non-empty. That is why a
wrong reason shipped green. It now asserts the pinned case names both machines and does not
contain --force, and the unpinned machine-online-agent-detached case still says pags up --force
unchanged. Sensitivity was verified the honest way: reverting the two forwarded lines in
describeFacts makes the new coding-repos.test.ts case and both new runner-availability.test.ts
cases fail; restoring them makes the suite green again.

The two invariants from item 3 are recorded on the pinned-machine-offline state.

What I could NOT verify live, and why — stated plainly

The live reproduction needs one machine connected while the instance is pinned to a different,
offline one. Right now that state does not exist on the reported instance:

GET /v1/instances/12ebf1f0-…/runner-node (production, after this deploy)
 runnerNode: "Sergeys-Mac-mini.local"
 nodesDetail: Mac connected=false nodeOnline=false
 Sergeys-Mac-mini.local connected=false nodeOnline=false

GET /v1/instances/12ebf1f0-…/coding/repos
 recheck.reason: "The runner for this agent isn't running. Try: `pags up`"

With nothing connected, no-runner is the correct diagnosis and the correct remedy — so this
output neither confirms nor refutes the fix. Reproducing #461 requires starting pags up on Mac
while the pin stays on the Mac mini, and starting a runner on the owner's machine is not mine to do.

So: the pinned branch is proven by test, not in production. If you bring a runner up on Mac, this
same GET …/coding/repos should name both machines and point at the "Runs on" dropdown instead of
offering --force. That is the one thing left to eyeball.

Left as a follow-up, not done

routes/instances.ts:793-806 still assembles pinnedNode/liveNodeExcludedByPin by hand and could
now go through describeFacts. Untouched here — a concurrent lane owned that file, and it is
duplication rather than a defect (that route was always correct). Worth a ticket; not filing one
unprompted.

Full bar green (416 files / 6944 tests at the time of the lane's run, 7052 in the integrated tree);
pnpm test:e2e skipped deliberately — the change is three API-worker source files and touches no
store/, console, or agents/coder/web. CI and both deploy workflows green.