Skip to content

T22 — Publish a permitted port when a process listens and withdraw it when it closes - #1856

Merged
norrietaylor merged 30 commits into
mainfrom
agent/1663-publish-a-permitted-port-when-a-process-listens
Oct 3, 2026
Merged

norrietaylor merged 30 commits into
mainfrom
agent/1663-publish-a-permitted-port-when-a-process-listens

Conversation

@minimal-foundry

@minimal-foundry minimal-foundry Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

T22 — Publish a permitted port when a process listens and withdraw it when it closes

slice: S5
kind: task
covers: NET-016, NET-017
size: L
est: 380 code, 240 tests
executor: agent
difficulty: needs care
model: strongest
diagnostics: the bundle's daemon log tail names each publication and withdrawal with the port, the box and whether the rules permitted it
observability: one info log line per publication and withdrawal naming the port, the box and the verdict
layers:
- core:
- crates/sessions/src/core/egress.rs: the ingress permit decision joins the frame verdict under the shared harness
- crates/sessions/src/lib.rs: the permit range on IngressPolicy is enforced rather than documented as not yet enforced
test (deferred: kani): cargo nextest run -p sessions kani_frame_verdict_admits_nothing_undeclared
- daemon:
- crates/minimald/src/net/listeners.rs (new): reads the box's listening sockets through its leader's process entry, polls and diffs them
- crates/minimald/src/net/mod.rs: declares the listeners module
- crates/minimald/src/net/switch.rs: the ingress gate calls the shared decision
- crates/minimald/src/net/policy.rs: exposes and unexposes one mapping
- crates/minimald/src/session_host.rs: starts and stops the watcher with the host
test: cargo nextest run -p minimald listen_publishes_permitted_port
test: cargo nextest run -p minimald listen_on_undeclared_port_not_published
test: cargo nextest run -p minimald listener_close_withdraws_publication
produces: none
consumes:
- crates/sessions/src/core/egress.rs
proof: A server started on a permitted port inside a box is reachable at the box's address without any ingress flag, a server on a port the rules do not permit stays unreachable, and closing the server withdraws the port.
depends on:
- blocked by #1629
- blocked by #1657

Proof

A process inside an own-IP box that starts a server on a port the box's dynamic permit range names — with dynamic_ingress = allow and no ingress flag at all — gets that port published on the box's own address at the port it listens on, and connections to it are admitted by the gate and forwarded to the box; a server on a port the rules do not permit stays unpublished (its connections are refused at the box's address, NET-014); and closing the server withdraws the publication — the gate refuses the port first, terminating the connections the publication held, then the forward comes down — with the same withdrawal for the whole surface at session end. The three named tests demonstrate each half end to end against the real gate, the real /proc socket-table reader and the real forwarder verbs (a fake gvproxy answers them); the sessions-side decision the whole surface rides is the pure listen_verdict the Kani harness exhausts, committed with the core layer.

Notes from the agent: Deferred (lane kani): the core-layer test line 'cargo nextest run -p sessions kani_frame_verdict_admits_nothing_undeclared' is written — the harness in crates/sessions/src/core/egress.rs now also exhausts listen_verdict over a symbolic port, a zero/two-port declaration, a symbolic range and all four stances at the unchanged unwind bound 6 — but no kani toolchain runs on this box, so it was not run. Handoff shape: the launcher-to-host plan travels through a stage/take table keyed by SessionId rather than a field on Launched, because Launched is also constructed in crates/minimald/src/session_host/tests.rs, which is outside this task's layers; the table follows the existing LIVE_GATES pattern and a mock launch that stages nothing starts no watcher, so no out-of-scope test needed touching. Everything else stayed inside the named layers: no file outside them changed, and the daemon's unit tests cover the watcher against a fake gvproxy control channel — the real-box end-to-end (just e2e /…[truncated]

Tests

line exit tail
cargo nextest run -p minimald listen_publishes_permitted_port 0 Applying loadouts: default Running task runtime-implement-test-0 in session task-runtime-implement-test-0-05c5... Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/aa09e/tree/crates/ot) Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/aa09e/tree/crates/args) C
cargo nextest run -p minimald listen_on_undeclared_port_not_published 0 Applying loadouts: default Running task runtime-implement-test-1 in session task-runtime-implement-test-1-16ff... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/cbef9/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/cbef9/tree/crate
cargo nextest run -p minimald listener_close_withdraws_publication 0 Applying loadouts: default Running task runtime-implement-test-2 in session task-runtime-implement-test-2-cf86... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/2b61e/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/2b61e/tree/crate

Verify

min task run agent-verify passed ([tasks.verify]).

Base

The base branch moved while the coder worked; it was merged in before the tests ran.

Known limits

  • Runtime min net expose and listen-publish don't yet see each other's ports. Expose after listen fails with a bind error; listen after expose leaves the watcher retrying under backoff. T83 #1896 owns the fix: one publication owner per box port.
  • a_published_listener_is_reachable_and_refused_on_the_real_switch (#[ignore], needs GVPROXY_BIN) shows gvproxy's host-side bind, not bytes reaching the listener. It has not been run.
  • Reachability from a peer isn't proven here: no CLI path creates a dynamic-ingress allow box until T82 #1895, whose e2e block now carries the listen-publish leg (in-range listener reachable from a peer, refused after it closes; out-of-range listener never reachable). This PR proves the verdict, the publish and withdraw against the forwarder's control channel, and the gate admit and withdraw. The plan's proof line says so.

After round 6

  • Main merged in (f7f7487). The T77 reply-flow types and the listen-publish gate methods sit side by side in net/switch.rs and core/egress.rs.
  • cb5880a: on a deny-all box, the gate admitted a connection to a listen-published port but dropped the box's replies, because reply flows were recorded only for declared ports. record_delivered_inbound now records on admits_tcp. withdraw_published also ends that port's reply-flow records (ReplyFlows::end_port), so a reply on a withdrawn port is new traffic the box's rules decide. gate_admits_and_withdraws_a_listen_published_port asserts no record before publication, a recorded flow whose reply passes after it, and after withdrawal no record and the reply no longer admitted.
  • Round 6 changed the stage/take table: entries carry the spawn PID, a failed launch clears them through StagedPlanGuard, and a respawn never reads the previous spawn's plan.

Deferred

The plan marked these test lines deferred: the executor lacks the lane, so nothing here ran them and they still owe evidence.

line lane
cargo nextest run -p sessions kani_frame_verdict_admits_nothing_undeclared kani

Closes #1663

NET-016/NET-017's permit decision joins the frame verdict under the shared
harness: IngressRules compiles the ingress half of a box's policy (the
declared internal ports with their transports, the permit range, the dynamic
stance) and answers listen_verdict — a listening port is published only when
the box's stance is allow, the port falls inside the range and no declaration
names it; a declared port is the declaration's, held until the box stops
(NET-121), so listening never publishes or withdraws it.

The Kani harness exhausts the same iff it exhausts the frame verdict over:
one more port, a declaration of zero or two named ports, a symbolic range
and all four stances, at the unchanged unwind bound 6. The permit range's
doc on IngressPolicy stops saying the range is not yet enforced.
NET-016/NET-017: a box whose ingress stance is allow and whose permit
range names a port gets the port published on its own address the
moment a process inside it listens, at the port the process listens on
(no translation), and the publication is withdrawn the moment the
listener closes — with no ingress declaration involved anywhere.

- net/listeners.rs (new): the watcher. It reads the box's listening
  sockets through its leader's /proc entry — the kernel's socket tables
  are per-network-namespace, so one process's entry names every
  listener in the box, whichever of its processes holds it — polls and
  diffs them, and publishes each new permitted port with the switch's
  expose verb: the forward binds first and the gate admits after, the
  order a declaration's own apply holds, so a port is never admitted
  while nothing answers for it. A listener that closes withdraws its
  publication — the gate refuses the port first, terminating the
  connections the publication held at both ends, and the forward comes
  down after. One info line per publication and per withdrawal, each
  naming the port, the box and the verdict.
- switch.rs: the gate keeps the runtime-published set apart from the
  declared one and asks the shared decision — sessions' IngressRules,
  the same listen_verdict the Kani harness exhausts — what a listening
  port is worth. Admissions and refusals across the relay read the
  union of the two sets, a withdrawal terminates only the
  runtime-published set (NET-081's sub-requirement), and
  admits_direct_tcp stays declared-only: the proxy's NET-069 gate is
  another surface.
- policy.rs: expose_mapping and unexpose_mapping — one forward bound at
  the box's published address, delivered to the box's lease at the same
  port number, and its unexpose twin.
- session_host.rs: the launcher stages the plan — lease, published
  address, gvproxy control channel, and the gate the attach registered
  — as its last act; the host that takes the box starts the watcher
  from it, resolving the box's leader (a read the nsenter module
  documents as race-free against a just-returned spawn), and stops it
  at session end before the network attachment tears down, so no
  runtime-published forward outlives the tap it delivers through.

Boxes with no lease, no published address or no live gate stage no plan
and run no watcher: nothing is published by listening.
@coderabbitai

coderabbitai Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: d1edffd9-3996-4a6c-b743-2bb1dc994544

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@minimal-foundry

minimal-foundry Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor Author

Approved: no findings at 9a39047601ad.

Nothing to do.

Verdict APPROVE, posted as a comment: the App cannot review its own pull request; the check and the label carry it.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 3 findings, 3 inline.

Comment thread crates/minimald/src/net/listeners.rs Resolved
Comment thread crates/minimald/src/net/listeners.rs Resolved
Comment thread crates/minimald/src/net/listeners.rs Resolved
The listener watcher's poll consumed a listening port's appearance
whether its publication bound or not, and the stop's withdrawal made
one pass over the forwards, so the two retry promises its comments and
the `expose_mapping`/`unexpose_mapping` docs made were never kept:

- a permitted listener whose expose failed once — a forwarder
  mid-restart, a bind not free yet — was never retried, leaving the
  port unpublished until its server restarted. The poll now keeps a
  failed publication's port out of its book, so the next poll reads
  it as appeared again and retries the bind;
- a withdrawal whose unexpose failed once was re-inserted into a set
  nothing ever revisited, so the forward stayed bound past its box,
  holding the box's published address:port. The stop's withdrawal now
  makes bounded retry passes and names what it cannot bring down;
- a listener that returns while its withdrawal had failed is
  re-admitted on the forward it never lost, rather than asking the
  switch to bind a second forward onto the bind the first still holds.

Also, `listen_port` published any listening socket regardless of the
address it bound: a process bound to the box's loopback alone — the
shape a dev server binds by default — got a forward that dials the
box's lease, where nothing answers, so the box's address accepted a
connection only to have it refused at the lease. Only a bind on the
any address or the box's lease is a publication now; anything else is
left to NET-014's refusal.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 1 finding, 1 inline.

Comment thread crates/minimald/src/net/listeners.rs Resolved
@minimal-foundry

Copy link
Copy Markdown
Contributor Author

Round 1 of 10 on the runtime's review findings, pushed as 09f2f3068956.

line exit tail
cargo nextest run -p minimald listen_publishes_permitted_port 0 Applying loadouts: default Running task runtime-implement-test-0 in session task-runtime-implement-test-0-fc93... Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/a4671/tree/crates/ot) Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/a4671/tree/crates/args) C
cargo nextest run -p minimald listen_on_undeclared_port_not_published 0 Applying loadouts: default Running task runtime-implement-test-1 in session task-runtime-implement-test-1-9740... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/d199a/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/d199a/tree/crate
cargo nextest run -p minimald listener_close_withdraws_publication 0 Applying loadouts: default Running task runtime-implement-test-2 in session task-runtime-implement-test-2-8318... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/4a9ff/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/4a9ff/tree/crate

Verify min task run agent-verify passed.

Review threads the coder judged:

  • 👍 valid — crates/minimald/src/net/listeners.rs: poll now keeps a failed bind's port out of its listening book, so every later poll reads it as appeared again and retries the expose; proved by a_failed_publish_is_retried_on_the_next_poll, and a listener returning while its withdrawal had failed is re-admitted on the forward it never lost instead o
  • 👍 valid — crates/minimald/src/net/listeners.rs: withdraw_all now makes bounded retry passes (WITHDRAW_PASSES, one poll-interval apart) before stop returns and warns naming any forward it could not bring down, so the re-insert is live and no runtime-published forward outlives its box; proved by a_failed_withdrawal_is_retried_before_the_stop_return
  • 👍 valid — crates/minimald/src/net/listeners.rs:484: listen_port now keeps only rows bound on the any address or the box's lease (the v4 word byte-swapped out of the kernel's little-endian print; the v6 dual-stack any or a mapped any/lease), so a loopback-bound listener is left to NET-014's refusal instead of published as a phantom; proved end to end

A server started on a permitted port inside a box is published at the box's address with no ingress flag, and a publication whose bind was refused is retried on the next poll rather than lost until the server restarts; a server on a port the rules do not permit — or bound to an address the forward's dial cannot reach, like the box's loopback — stays unpublished, so a connection to it is refused at the box's address and never forwarded to nothing; and closing the server withdraws the port, with a withdrawal whose unexpose failed retried before the box's stop returns, so no forward published by listening outlives its box.

Notes from the agent: Revise round 1: all three review findings held and were fixed in crates/minimald/src/net/listeners.rs (one commit, c426d32). policy.rs, a named layer, got a doc-only correction: unexpose_mapping's '# Errors' now states the retry shape the watcher actually keeps instead of the 'retried while the watcher lives' promise the code did not deliver. The module's tests bind the any address now, not 127.0.0.1, because the new bind filter excludes loopback-bound rows. Deferred (lane: kani): 'cargo nextest run -p sessions kani_frame_verdict_admits_nothing_undeclared' was not run on this box; its harness in crates/sessions/src/core/egress.rs is unchanged this round. just clippy-strict (local-only gate, revise-round rule: report, don't fix) has one remaining hit on branch-changed lines, pre-existing from round 1's commit and untouched this round: crates/minimald/src/net/listeners.rs:213 clippy::let_underscore_must_use on 'let _ = self.stop.send(true);' in ListenWatcher::stop. Full -p minimald suite also reports 1 leaky (passed) test, present before this round.

@norrietaylor

Copy link
Copy Markdown
Member

/revise Round 2.

Scope: change only crates/minimald/src/net/listeners.rs, plus crates/minimald/src/net/policy.rs if the expose/unexpose warn wording moves, plus crates/minimald/src/session_host.rs for ask 5 only. No other files.

  1. Retry a failed withdrawal during the box's life, not only at the stop. In WatchState::poll, after the appeared/disappeared diff, call close again for every port held in forwards that is not in the freshly read listening set, so a forward whose unexpose failed is retried on each later poll. Acceptance: with a fake forwarder that refuses the first unexpose only, a listener that closes while the watcher keeps running gets a second unexpose for the same local within a few poll intervals and before stop is called. Add a test named a_failed_withdrawal_is_retried_while_the_box_runs that asserts this without calling stop first. The module header's retry promise must hold for both halves.

  2. Stop a persistent expose failure from flooding the log. Keep retrying a permitted port whose expose fails, but back off per port (for example doubling from the poll interval up to a cap of about 30 s), and log the failure once per failure streak, not once per attempt; log one line when a backed-off port is finally published. Acceptance: with a fake forwarder that refuses every expose for one port, the watcher makes far fewer than one expose attempt per poll after the first few failures (assert at most about 6 attempts across 3 s), and the port is published once the forwarder starts accepting. Add a test named a_persistently_refused_publish_backs_off.

  3. Make the withdrawal info line name the verdict, as the publication line does (for example verdict = "permitted"), and log one line naming the box and port when a withdrawal's unexpose fails. Acceptance: the withdrawal line and the failed-withdrawal line both carry session, port and verdict fields.

  4. In withdraw_all, log the "could not withdraw" warning only when forwards is still non-empty after the last pass. Acceptance: a run where the final pass succeeds logs no such warning; extend a_failed_withdrawal_is_retried_before_the_stop_returns or add a case where the first two unexposes are refused and the third succeeds.

  5. When a launch stages no listen plan for a session, remove any plan already staged for that session id, so a later host never takes a plan left by a cancelled launch. Acceptance: a unit test in listeners.rs that stages a plan, clears it through the new path, and shows take_listen_plan then returns None.

All existing tests must keep passing, including listen_publishes_permitted_port, listen_on_undeclared_port_not_published, listener_close_withdraws_publication and the Kani harness kani_frame_verdict_admits_nothing_undeclared.

The PR body is edited by hand; do not rewrite it.

…ublishes

Round 2 of the listen-publication watcher's retry promises (NET-016,
NET-017):

* A withdrawal whose unexpose failed is now asked for again on every
  poll the box still runs — a forward standing on the switch after its
  listener closed delivers to a lease:port nothing answers — and not
  only at the stop. The stop's passes stay for the forwards still
  standing when the box ends.
* A permitted port whose publish keeps being refused is retried on a
  per-port backoff that doubles off the poll interval and caps at 30 s,
  so a forwarder that is down for a while is waited for rather than
  asked four times a second. The port still publishes the moment the
  forwarder accepts.
* Each half now says its failure once per streak, never once per
  attempt: the wording moved from `net::policy`'s expose and unexpose
  verbs to the watcher that owns the streak, and the publication that
  ends a streak names how many attempts it took.
* The withdrawal's line names its verdict, as the publication's does,
  and the failure of a withdrawal names the box, the port and the
  verdict too.
* `withdraw_all` warns only when a forward is still standing after its
  last pass: a stop whose last pass withdrew everything warns of
  nothing.
* A launch that stages no listen plan clears the one a cancelled launch
  left behind for the same session, so no later host starts a watcher
  on a lease, an address and a gate that launch's attach tore down.
The local strict gate reported two diagnostics on lines this branch
added in `net::listeners`: the stop signal's `let _` drop of a
must-use result, and the log-capture writer's `unwrap` inside its
`io::Write` impl. The first takes the repo's `#[expect]` pattern with
the reason the join below already reports a loop that ended; the second
recovers the poisoned buffer instead, so no line a proof reads is ever
dropped on the floor.
@minimal-foundry

Copy link
Copy Markdown
Contributor Author

Round 2 of 10 on a /revise note, pushed as f3ef16349427.

line exit tail
cargo nextest run -p minimald listen_publishes_permitted_port 0 Applying loadouts: default Running task runtime-implement-test-0 in session task-runtime-implement-test-0-2b97... Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/26e03/tree/crates/ot) Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/26e03/tree/crates/args) C
cargo nextest run -p minimald listen_on_undeclared_port_not_published 0 Applying loadouts: default Running task runtime-implement-test-1 in session task-runtime-implement-test-1-f44e... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/d3931/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/d3931/tree/crate
cargo nextest run -p minimald listener_close_withdraws_publication 0 Applying loadouts: default Running task runtime-implement-test-2 in session task-runtime-implement-test-2-1fa9... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/46862/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/46862/tree/crate

Verify min task run agent-verify passed.

Review threads the coder judged:

  • 👎 invalid — crates/minimald/src/net/listeners.rs: Already so on this branch (09f2f30): poll keeps a failed bind's port out of its listening book, so every later poll reads it as appeared again and retries the expose — the appearance is not consumed by the failure. Proved by a_failed_publish_is_retried_on_the_next_poll; this round adds the per-port
  • 👎 invalid — crates/minimald/src/net/listeners.rs: Already so on this branch (09f2f30): withdraw_all makes WITHDRAW_PASSES bounded passes, one poll-interval apart, before stop returns, so close()'s re-insert is live and the stop retries a refused unexpose instead of abandoning the forward. Proved by a_failed_withdrawal_is_retried_before_the_stop_re
  • 👎 invalid — crates/minimald/src/net/listeners.rs:668: Already so on this branch (09f2f30): listen_port keeps only rows whose bind a forward dialing the box's lease can answer — the v4 any address or the lease itself (byte-swapped out of the kernel's little-endian print), the v6 dual-stack any or a mapped any/lease — so a loopback-bound listener is lef
  • 👍 valid — crates/minimald/src/net/listeners.rs: Fixed this round: poll now asks again for every forward still held in forwards whose port the freshly read table does not name, once per poll while the box runs, so a failed unexpose no longer waits for the stop; the failure is said once per streak and the withdrawal's own line ends it. Proved by

A server a box's process starts on a permitted port is published at the box's own address and reachable there with no ingress declaration; a port the rules do not permit is never published; and closing the server — or the box — withdraws it. This round holds that same surface under refusals: a withdrawal whose unexpose failed is asked for again on every poll the box still runs instead of waiting for the stop, a persistently refused publish backs off per port (doubling off the poll interval to a 30 s cap) instead of being re-asked four times a second and still publishes the moment the switch accepts, the stop warns only when a forward is really still standing, and each publication, withdrawal and failure is one line naming the box, the port and the verdict.

Notes from the agent: All five asks of the directive are in, inside its scope: listeners.rs (mid-life withdrawal retry, publish backoff, once-per-streak failure lines, the verdict field, withdraw_all's warning, and clear_listen_plan with its unit test), policy.rs (only to move the expose/unexpose warn wording to the watcher that owns the streak — the reason the directive allowed that file), and session_host.rs (only the else arm that clears a cancelled launch's plan, ask 5). Nothing outside the three named files changed.

Deferred: cargo nextest run -p sessions kani_frame_verdict_admits_nothing_undeclared (lane: kani). This box has no Kani; the harness already exists at crates/sessions/src/core/egress.rs and this round touched no sessions code, so nothing new needs the lane — it still owes its own evidence.

Two existing proofs in listeners.rs moved with the behaviour: a_listener_back_before_its_failed_withdrawal_keeps_the_publication now asserts a lower bound on unexposes (> WITHDRAW_PASSES) rather than an exact count, because the mid-life retry adds a number of requests between the closure and the rebind that no test can fix; and the same module's stop-time count in a_failed_withdrawal_is_retried_…[truncated]

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 1 finding, 1 inline.

Comment thread crates/minimald/src/net/listeners.rs Resolved
A host build is a staged listen plan's one taker, so it owns the plan's
end too. A build that ended without taking its plan — a launch that
errored, or an attach abandoned with its launch in flight — left the
entry in the table for good: nothing else ever came for it, and it held
the lease, the published address, the gate and the control channel of an
attach already gone. One abandoned attach per entry, over the daemon's
life, contradicted the table's own claim that it is bounded by the
sessions that exist.

Host::build now holds StagedPlanGuard across its launch and its take.
The clear rides Drop — a cancelled build is a dropped future, not a
returned error — so the build that ends without taking the plan takes
the plan with it, and a later build clears an earlier cancelled
launch's orphan too. The take disarms the guard: the table's entry went
with it, and the guard's own end clears nothing. The table is now
bounded by the host builds in flight, proved by
no_staged_plan_outlives_the_build_that_could_take_it.
@minimal-foundry

Copy link
Copy Markdown
Contributor Author

Round 3 of 10 on the runtime's review findings, pushed as 2bda3923a3c4.

line exit tail
cargo nextest run -p minimald listen_publishes_permitted_port 0 Applying loadouts: default Running task runtime-implement-test-0 in session task-runtime-implement-test-0-008b... Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/20609/tree/crates/args) Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/20609/tree/crates/ot) C
cargo nextest run -p minimald listen_on_undeclared_port_not_published 0 Applying loadouts: default Running task runtime-implement-test-1 in session task-runtime-implement-test-1-d21f... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/54d96/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/54d96/tree/crate
cargo nextest run -p minimald listener_close_withdraws_publication 0 Applying loadouts: default Running task runtime-implement-test-2 in session task-runtime-implement-test-2-35de... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/ca8fe/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/ca8fe/tree/crate

Verify min task run agent-verify passed.

Review threads the coder judged:

  • 👎 invalid — crates/minimald/src/net/listeners.rs: The premise does not hold at this branch: a refused expose is not consumed by its failure. poll (listeners.rs:348-383) retains the listening book down to the ports in backoff, so the failed bind's port is out of the book and every later poll reads it as appeared again; publish (390) re-asks on the p
  • 👎 invalid — crates/minimald/src/net/listeners.rs: The re-insert is live, not dead code: a failed unexpose is re-asked on every poll while the box runs — poll's owed pass (listeners.rs:366-375) names every forward still held whose port the fresh table does not — and again on each of the stop's WITHDRAW_PASSES (586-600), which collects self.forwards.
  • 👎 invalid — crates/minimald/src/net/listeners.rs:715: listen_port (listeners.rs:654-669) no longer drops the address: every row passes binds_for_the_lease (687-707), which keeps only a bind on the any address or the box's lease itself — the v4 word byte-swapped out of the kernel's little-endian print, the v6 dual-stack any, or a mapped any/lease — so a
  • 👎 invalid — crates/minimald/src/net/listeners.rs: Already so on this branch (fc100eb): the withdraw half of the nothing-is-one-shot promise is kept mid-life — poll's owed pass asks again for every forward still held whose port the freshly read table does not name, once per poll while the box runs, with the failure said once per streak and ended by
  • 👍 valid — crates/minimald/src/net/listeners.rs: Fixed: Host::build now holds StagedPlanGuard across its launch and its take, so the build that ends without taking its plan — the cancelled-after-Step-4 shape — clears the entry as it ends, and a later build clears an earlier cancelled launch's orphan too; the take disarms the guard. The table is bo

The story's three proofs still hold at this branch — a permitted listener publishes at the box's address with no ingress declaration, an undeclared one publishes nothing, and closing the listener withdraws the port — and this round a staged listen plan no longer outlives the host build that could take it: an attach abandoned with its launch in flight leaves nothing in the plan table holding its box's lease, address, gate and control channel.

Notes from the agent: Round 3 judged all five threads against the head; only the STAGED_PLANS leak (4172284841) held, and it is the one code change this round — StagedPlanGuard in listeners.rs, wired into Host::build in session_host.rs, proved by no_staged_plan_outlives_the_build_that_could_take_it. The other four threads changed nothing: their fixes are already on the branch (c426d32, fc100eb) and their proofs were re-run green at this head. Deferred: 'cargo nextest run -p sessions kani_frame_verdict_admits_nothing_undeclared' (lane: kani) was not run — this box has no Kani; the harness it names exists at crates/sessions/src/core/egress.rs:2065 from round 1. The head this round started at (3de35b4) already carried two merges of origin/main touching .github/workflows/ci-macos.yml and crates/minimald/src/server.rs; they predate this session and are not part of my diff. just clippy-strict is clean on the changed lines.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 1 finding, 1 inline.

Comment thread crates/sessions/src/core/egress.rs Resolved
IngressRules::declares matched a port across every transport, so a TCP
listener on a port the declaration names on UDP alone answered
Declared and was never published on TCP — held back by a forward that
answers UDP only, whatever the permit range and the allow stance said.
A mapping's forward answers the one protocol it was exposed with
(NET-121), so the transport is half of what the declaration must name
for a port to be published already.

The verdict and its declared-half check now take the transport the
listener holds. The watcher reads the kernel's TCP tables and binds
TCP forwards, so it asks for TCP; the sessions unit test, the
listener watcher's end-to-end test, and the Kani oracle — which now
exhausts the listened transport across the two a declaration can
name — each cover the UDP-declared, TCP-listening shape.
Clippy's too_many-lines (threshold 100) fired on
listen_verdict_decides_from_the_declaration: 111 code lines. Split it
along the two halves its own doc comment states — the stance and permit
range, and the declaration's already-named ports — keeping every
assertion verbatim. The exhaustive form of both halves stays the
ingress half of kani_frame_verdict_admits_nothing_undeclared.
@minimal-foundry

Copy link
Copy Markdown
Contributor Author

Round 5 of 6 on a conflict with the base branch, pushed as bc3662f7c32e.

Resolved conflicts in: crates/minimald/src/net/policy.rs

line exit tail
cargo nextest run -p minimald listen_publishes_permitted_port 0 Applying loadouts: default Running task runtime-implement-test-0 in session task-runtime-implement-test-0-ac49... Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/9c546/tree/crates/ot) Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/9c546/tree/crates/args) C
cargo nextest run -p minimald listen_on_undeclared_port_not_published 0 Applying loadouts: default Running task runtime-implement-test-1 in session task-runtime-implement-test-1-4dfd... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/40292/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/40292/tree/crate
cargo nextest run -p minimald listener_close_withdraws_publication 0 Applying loadouts: default Running task runtime-implement-test-2 in session task-runtime-implement-test-2-ab1b... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/ea5cc/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/ea5cc/tree/crate

Verify min task run agent-verify passed.

Review threads the coder judged:

  • 👍 valid — crates/minimald/src/session_host.rs: The watcher now owns leader resolution: it takes Leader::Pending { container_pid } from the build and resolves it on every poll until the box's program appears, so a build-time resolution that fails costs one poll interval instead of dropping the listen plan and the ports it would have published; on

A server bound to a port the box's ingress rules permit is published at the box's own address and reachable there with no ingress flag; a server on a port the rules do not permit is never published and stays unreachable; and closing the listener withdraws the publication — and this now holds even when the box's program had not yet appeared when the session was built, because the watcher keeps asking for the box's leader on every poll instead of dropping the listen plan on the first failed resolution.

Notes from the agent: Conflict resolved first, as the directive asked: crates/minimald/src/net/policy.rs carried markers between this branch's expose_mapping/unexpose_mapping helpers (which listeners.rs publishes and withdraws through) and main's dynamic-ingress API (ExposeRefusal/ExposeFailure/dynamic_ingress_decision/expose_dynamic, landed in #1865 and used by session.rs and env.rs). The merge keeps both halves; every kept symbol is referenced by live code. The merge commit itself also carries main's tree (minvmd, session.rs, env.rs, and friends) — that content came from main through the merge and is not this round's work.

The thread's finding: the watcher now owns leader resolution. crates/minimald/src/session_host.rs no longer resolves the leader at build time or drops the plan when it cannot; it hands the watcher Leader::Pending { container_pid }, and WatchState::poll resolves it, warning once per failed streak (retrying on every poll) and pinning it once found. New test: a_watcher_whose_leader_was_not_yet_findable_publishes_when_it_is drives a real /bin/sh supervisor whose program appears mid-watcher and proves nothing is published while the leader is unfound, the permitted port is published and admitted once it is, the warn fires once (not once per poll), and the publication is withdrawn on stop.

Deferred: test (deferred: kani): cargo nextest run -p sessions kani_frame_verdict_admits_nothing_undeclared — the kani lane does not run on this box; the …[truncated]

@norrietaylor

Copy link
Copy Markdown
Member

/revise Round 6, the last under the cap. All lanes are green at bc3662f, and the earlier asks are in. The design check sets these conditions.

  1. One decision function. Main's T53 policy::dynamic_ingress_decision (crates/minimald/src/net/policy.rs:561) and this PR's IngressRules::listen_verdict (egress.rs) derive the same stance, range and permit twice. The spec's "one decision function" invariant forbids that. Make dynamic_ingress_decision delegate to IngressRules, or have both call one shared function. Keep each surface's typed result (the expose refusals stay as they are). The edit to net/policy.rs is approved as out of layer. Do not touch session.rs's live_ingress. Test: expose_and_listen_share_one_verdict must agree over a table of stance × range × port, covering ask, deny, absent stance, absent range, in-range and out-of-range.
  2. STAGED_PLANS conditions (listeners.rs:167; session_host.rs:3651-3679, 4179):
    • Take-once: the host removes the entry when it reads it.
    • Every failed or aborted launch clears its entry.
    • A respawn under the same SessionId never reads a previous spawn's plan. Either key by spawn, or treat a second take as absent and fail closed.
    • Tests: a_failed_launch_leaves_no_staged_plan and a_respawn_never_reads_the_previous_spawns_plan.
  3. Fresh backoff streak. A port in backoff whose listener closes never reaches disappeared, so its backoff entry outlives it (listeners.rs:530-559). When the listener comes back, it inherits the old count and delay, and its first failure is never logged. In poll, drop backoff entries for ports absent from the fresh table. Test: a_backed_off_port_that_closes_starts_a_fresh_streak.
  4. The watcher stops when it is dropped. ListenWatcher has no Drop. A host dropped or aborted before mainloop reaches its stop (session_host.rs:4409) leaves a detached poll holding forwards that the gate admits. Add an abort-on-drop guard that also withdraws. Test: dropping_a_watcher_stops_its_poll.
  5. Real reachability. Add an #[ignore]d real-gvproxy test in listeners.rs, modelled on gvproxy_network.rs:2127. It connects to published:port, closes the listener, and expects the connection refused. Keep the withdrawal order: gate withdraw first, then unexpose (686-687). Put a comment there saying why.

In the PR body, record as a known limit that runtime min net expose and listen-publish don't yet see each other's ports. One order gives an expose bind error, and the other gives a watcher retry under backoff. Link the follow-up task that will own it (I'll post it here).

Out of scope: session.rs live_ingress, moving the plan into Launched (the follow-up), and UDP listeners.

@norrietaylor

Copy link
Copy Markdown
Member

Follow-up for the known limit in round 6: T83 #1896 gives runtime publications one owner. min net expose and listen-publish will see each other's ports, and the listen plan moves into Launched. Link it from the PR body's known limit.

…en verdict's shared rule

The two runtime ingress surfaces — the daemon's `min net expose`
decision and the listen watcher's verdict — each spelled out the box's
stance-then-range derivation on their own, so a future edit to one could
part ways with the other on a port. Both now call one derivation,
`IngressRules::dynamic_verdict`: the expose side renders its typed
refusals from it, the listen verdict keeps the declaration as its own
half. `expose_and_listen_share_one_verdict` pins the agreement over
every stance x range x port shape the declaration can take.
The backoff book keeps a backed-off port out of the listening table,
so the poll's diff never read one as disappeared and its entry outlived
the listener it was refused for: the next server bound on that port
number inherited a wait it had not earned and a count whose first
failure was never said. The poll now drops backoff entries for ports
absent from the fresh table, so the streak belongs to one listener and
a returning server starts its own.
…ached

A host dropped before its mainloop reached the watcher's stop ended
nothing: the poll kept running by the accident of the watch channel's
close, and nothing said the drop was the stop. The watcher now ends
itself on drop — a Drop guard sends the loop its stop signal, so the
poll ends and the loop runs the same withdrawal every stop runs. The
task is not aborted (the withdrawal is its own last act, and it is the
only owner of the forwards map — an abort would strand every forward
on the switch); the handle detaches so the epilogue finishes, the same
detach-over-abort choice the session's own host kill makes.
The staged-plan table was keyed by session id alone, so the take could
not tell this launch's plan from the one a spawn before it left: a
respawn of the same session reads the table with the same key, and the
lease, published address and gate a dead spawn's attach registered are
exactly the facts its plan carries. The entry now records the container
supervisor its launch ran and the take names the one the caller runs,
so a respawn never reads the spawn before it: a plan staged for another
spawn is refused - dropped, and said - and the respawn fails closed,
with nothing published by listening, rather than publishing on an
attach that is already gone.
The module's proofs ran against a stand-in control channel, so the
expose and unexpose verbs were proven as requests, never as binds. An
ignored proof now runs the watcher against the real binary the daemon
spawns (GVPROXY_BIN, the pinned one scripts/fetch-gvproxy.sh fetches):
a listener bound at the stand-in's lease publishes at the box's own
address - the connect a published box's client makes, which nothing but
the forward can answer while the bind is the lease's alone - and the
listener closing takes the port with it, refused after, never accepted
by a forward delivering to nothing. It self-skips without GVPROXY_BIN,
the way the netns proofs do.
@minimal-foundry

Copy link
Copy Markdown
Contributor Author

Round 6 of 6 on a /revise note, pushed as ee6da05be880.

line exit tail
cargo nextest run -p minimald listen_publishes_permitted_port 0 Applying loadouts: default Running task runtime-implement-test-0 in session task-runtime-implement-test-0-1b78... Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/25b3a/tree/crates/ot) Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/25b3a/tree/crates/args) C
cargo nextest run -p minimald listen_on_undeclared_port_not_published 0 Applying loadouts: default Running task runtime-implement-test-1 in session task-runtime-implement-test-1-ebb5... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/4cfb2/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/4cfb2/tree/crate
cargo nextest run -p minimald listener_close_withdraws_publication 0 Applying loadouts: default Running task runtime-implement-test-2 in session task-runtime-implement-test-2-344f... Compiling stdlib v0.0.21 (/home/runner/.local/state/minimal/sessions/4700c/tree/crates/stdlib) Compiling version v0.7.0 (/home/runner/.local/state/minimal/sessions/4700c/tree/crate

Verify min task run agent-verify passed.

Review threads the coder judged:

  • 👎 invalid — crates/minimald/src/session_host.rs: The premise is already gone at the branch base bc3662f: the take is no longer conditional on leader resolution. Host::build hands the watcher Leader::Pending { container_pid } (session_host.rs:4191) and WatchState::resolve_leader (listeners.rs:501) re-resolves it on every poll until the box's p

A server started on a permitted port inside a box is reachable at the box's address without any ingress flag — proven against the real gvproxy switch when GVPROXY_BIN is set, not only the stand-in channel — a server on a port the rules do not permit stays unreachable there, and closing the server withdraws the port, refused after.

Notes from the agent: All five directive conditions are met on this round's commits (c073bbd, 4865a98, e70b52a, cef2717, bdf86a9). (1) expose and listen now share one derivation: IngressRules::dynamic_verdict in egress.rs holds the stance/range/port match, minimald's dynamic_ingress_decision and listen_verdict both consume it, each surface keeps its typed result, and expose_and_listen_share_one_verdict covers stance x range x port including the absent cases. (2) STAGED_PLANS is keyed to the spawn the launch ran (stage and take both name it; session_host.rs passes the container supervisor PID); a mismatch is refused, said, and dropped — fail closed — with a_failed_launch_leaves_no_staged_plan and a_respawn_never_reads_the_previous_spawns_plan. (3) a port whose listener closes takes its backoff streak with it: poll drops backoff entries absent from the fresh table, so a returning listener starts a fresh streak and its first failure is said — a_backed_off_port_that_closes_starts_a_fresh_streak was shown to fail with the retain disabled. (4) ListenWatcher now has a Drop that sends the stop signal, so a dropped host ends its watcher (withdrawal first, task detached, not aborted — the loop is the only owner of the forwards map); dropping_a_watcher_stops_its_poll. (5) the withdrawal order in close() is gate-first-then-unexpose with a comment carrying why, and an ignored proof runs the watcher against the real gvproxy: a stand-in listener bound at its lease alone is reached at the published address and refused once it closes. KNOWN LIMIT for the PR body: runtime 'min net expose' and listen-publish do not yet see each other's publ…[truncated]

@minimal-foundry

Copy link
Copy Markdown
Contributor Author

The runtime will not revise this pull request again on its own: round 7 would exceed the cap of 6 (the last trigger was a conflict with the base branch). A person decides now. Remove needs-human from this pull request to let /revise <note> or the automatic rounds resume, or finish #1663 by hand.

@minimal-foundry minimal-foundry Bot added the needs-human An agent handed off; a human must act, then clear this label. Set by defer and handoffs. label Oct 3, 2026
@norrietaylor
norrietaylor marked this pull request as ready for review October 3, 2026 20:52

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — approved

Verdict APPROVE — No findings.

@minimal-foundry minimal-foundry Bot added the review:approved minimal-review approved the current head label Oct 3, 2026
@norrietaylor norrietaylor removed the needs-human An agent handed off; a human must act, then clear this label. Set by defer and handoffs. label Oct 3, 2026

@norrietaylor norrietaylor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Babysitter review: plan asks met, ARCH PASS, minimal-review approved at head, lanes green.

@norrietaylor
norrietaylor added this pull request to the merge queue Oct 3, 2026
Merged via the queue into main with commit 0cab30a Oct 3, 2026
34 checks passed
@norrietaylor
norrietaylor deleted the agent/1663-publish-a-permitted-port-when-a-process-listens branch October 3, 2026 21:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:approved minimal-review approved the current head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

T22 — Publish a permitted port when a process listens and withdraw it when it closes

1 participant