[antoinetoussaint-byte]

Follow-up to #1178, closing the minors from review r129 (no blockers or majors).

f1/f4: refusals name both addresses and give the right remedy

Take a routed module that is ordered after the hop and whose Init accepts a different address from the one the snapshot froze. It was told "stop and restart", which never helps. The frozen address is the one its Init was proposed, and that address is derived from the workspace, the service and the naming scope, so a restart derives it again and is refused again. The refusal now reads:

hop route platform/second/web::http is routed at [container http://host.docker.internal:13001, native http://localhost:13001], the address platform/second was proposed, but its Init accepted [native http://moved.native]: the proposed address is derived from the workspace, the service and the naming scope, so restarting this run derives it again and is refused the same way; have platform/second's agent serve the proposed address, or order platform/second before the hop

The three real restart cases keep the restart boundary, and each now prints both addresses:

• an initialized module offers a different address on reload;
• a record lands between the hop's derivation and its freeze ("was resolved at …, but … initialized at … while the routes were being resolved");
• a route moved ("moved from X, the address this run's hop snapshot holds, to Y").

The garbled "is not the address … initialized with" wording is gone.

f2: the fence's three guards are pinned

New tests:

• TestHopFreezeRefusesARecordBetweenDerivationAndFreeze
• TestHopFrozenRouteRefusesADuplicateEndpointAtAnotherAddress (covers both orders, plus carriesMapping directly)
• TestHopFreezeRefusesARouteThatMovedBeforeItsOwnerInitialized

Each one was sabotage-checked:

Sabotage	Failing test
S2: derive-then-record check in the freeze forced off	…RecordBetweenDerivationAndFreeze
S3: carriesMapping changed to any-match	…DuplicateEndpointAtAnotherAddress
S3': carriesMapping changed to first-match	…DuplicateEndpointAtAnotherAddress
S4: moved compare disabled	…MovedBeforeItsOwnerInitialized
S1: first-record check skipped (from #1178)	…InitializesAfterTheHop and …DuplicateEndpoint…

f3 / r141-f1: the first-Init port guard actually probes, and the docs say what it guarantees

r141 found that checkInitialPortAvailability probed runner.networkMappings. That field is assigned only after the agent's Init is accepted, so on a first Init the guard probed nothing, and it has done nothing there since cbcbafc. The guard now:

• runs after the Init inputs are gathered;
• probes the mappings this Init proposes, before the agent's Init;
• dials each native port on the instance's own host and on 127.0.0.1 and ::1 explicitly. On macOS, a squatter on 127.0.0.1:P and a service listening on the wildcard :P both bind, so only probing both families before the service binds catches either squatter.

Tests:

• TestFirstInitRefusesAProposedPortAnotherProcessHolds builds the Runner the way a run does (NewRunner, a real agent process) and holds the proposed port on each family.
• TestBoundNativePortsProbesBothLoopbackFamilies holds the family the instance does not name.

Sabotage: probing the accepted set fails the first test, and dialling only the instance's host fails the second.

docs/orchestration.md and the freezeHopAddresses comment now say exactly what holds. The routed module's first Init refuses a held proposed port and names its holder, so the run never comes up with the hop routing to a squatter. Not covered:

• traffic the hop forwarded before that Init;
• a process that binds the port after the probe;
• a routed module that crashes or is withdrawn mid-run.

r150-b1: the service's own kept container is not a squatter

A Docker store with keep-running leaves its container up so that the next run's agent adopts it by name. That container keeps publishing the service's deterministic port, and the guard refused it ("held by OrbStack Helper") on every run after the first. The remedy it printed, codefly clear, would have deleted the very container the setting keeps.

The guard now attributes each listener before refusing it. An address is let through only when the container listening there is the one the agent will adopt. It must:

• carry the name every Core agent gives it (dockerrun.ContainerName over the service's unique name in the run's workspace and naming scope);
• be codefly-owned;
• carry this flow's exact recovery scope and, when it has one, the same namespace (dockerrun's own reuse rule);
• be running and not ephemeral;
• publish that port on that loopback family: 127.0.0.1/0.0.0.0 covers 127.0.0.1, ::1/:: covers ::1.

Without a recovery identity or a Docker engine, nothing is excused. A loopback instance host is now probed per family only, so every holder is attributed to one family. A refusal names the holder on the address that answered, so a squatter on ::1 beside a kept 127.0.0.1 container is named, not Docker's forwarder.

Tests: TestFirstInitAdoptsItsOwnKeptContainerAndRefusesAnyOtherHolder uses a real Runner from NewRunner with a real agent. The kept container is adopted. Each of these is refused:

• a holder on ::1 beside it;
• a container from another recovery scope;
• one from another namespace;
• one with another service's name;
• an ephemeral container;
• a stopped container;
• one published on another port.

TestPublishesAddressIsPerLoopbackFamily and TestHolderPIDNamesTheListenerOnTheAddressThatAnswered pin the family and attribution rules. Each of these sabotages turns a case red: no excuse, any family, no scope check, no name check, the identity's (empty) workspace instead of the run's, and dialling a loopback host directly.

Live, on OrbStack with postgres agent 0.0.144, keep-running, container runtime, scope hfkr:

• Run 1 comes up and leaves its container on 127.0.0.1:35830.
• Run 2 with e0a9aa0 is refused, naming OrbStack Helper.
• Run 2 with this change reattaches in 1.2s.
• With a squatter on [::1]:35830 beside the kept container, the run is refused, naming the squatter's pid and executable.

r150-m1: the stale test comment now says what the test covers, a re-Init before the first Start.

r141-f2: a record that lands between the hop's derivation and its freeze, when it is the module's first record, now gets the non-restart refusal. To tell the cases apart, the shared state counts records per service. Only a re-record inside the window keeps the restart boundary.

r141-f3: "order X before the hop" is now offered only "if X does not call through the hop".

r141-f4: the reload refusal ("now offers") is asserted with both address lists.

Checks

go test -race ./pkg/orchestration/ ./cmd/run/, go vet and golangci-lint run ./pkg/orchestration/ are clean. Classification: a fix, made at the places that own the fence and the port guard. About 110 hand-written lines plus tests.

Behaviour change worth knowing: now that the first-Init guard probes, a stale process from an earlier run in the same naming scope that still holds a deterministic port fails that service's first Init, naming the holder. That was the guard's stated purpose; before this change it never fired on a first Init.

🤖 Generated with Claude Code