Skip to content

Commit c249b28

Browse files
author
npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d
committed
docs(remote-agents): Wren re-review — I5 launcher-neutral, tail unbounded not 87s, finalization slice quantified
Fixes Wren's three blockers from his re-review at 2076faf. - Blocker 1 (I5 layer leak): the universal I5 restart-policy paragraph no longer mandates Kubernetes spellings. Generic rule: if a supervisor exists, its policy MAY revive abnormal death and MUST NOT revive an intentional clean exit; a supervisor-less hand launch satisfies it vacuously. The bounded->Never / indefinite->OnFailure mapping is named as this binding's [L3] policy living in §Pod shape; enforcement prose now says 'the substrate's unit of execution' with the container realization pointed at §Pod shape. Same fix applied to the §Auto-Stop closing paragraph, which repeated the mapping in universal text. - Blocker 2 (partial sum labeled worst case): ~87s/~197s are now stated as what the counted segment ALONE can reach — already proving the 60s overrun — not the worst case. All three passages (§Stop, §K8s Grace, Known Defect 7) now name the earlier uncounted segments at b4f4ed1: the 30s wake-task drain (lib.rs:2612) and the awakened-pool shutdown (:2620-2624) whose per-slot acp.shutdown() loop (:3747-3751) has no timeout, and state the total tail is not bounded by today's segment timeouts. - Blocker 3 (unquantified finalization slice): the reserved slice MUST be no smaller than the finalizers' declared bounds — currently 2s presence + 5s relay close = 7s — in §Stop, §K8s Grace, and Known Defect 7. Verified: wake-drain/awakened-pool/shutdown_agent_pool line numbers checked against git show b4f4ed1:crates/buzz-acp/src/lib.rs in this worktree. Co-authored-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz> Signed-off-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz>
1 parent 2076faf commit c249b28

1 file changed

Lines changed: 62 additions & 40 deletions

File tree

‎docs/remote-agents.md‎

Lines changed: 62 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -259,34 +259,42 @@ one.
259259
indefinite agents safe is *intent vs accident*: dying on purpose
260260
(`!shutdown`, inactivity reap) is final; dying by accident (node
261261
eviction, OOM) may restart the body — same key, same agent, the
262-
resurrection story working *for* the owner. A bounded-lifetime agent
263-
takes `restartPolicy: Never` (any restart machinery would resurrect what
264-
the reaper terminates). An indefinite agent takes `restartPolicy:
265-
OnFailure` — **but only after the exit-code contract lands**: the
266-
supervisor can distinguish intent from accident only if the harness
267-
formally promises *clean exit = exit code 0* on every intentional path
268-
and nonzero otherwise, pinned by test. At `c1bca1b56` that property is
269-
emergent, not defended (Known Defect 6); `OnFailure` before the pinned
270-
contract is how a refactor silently converts every clean stop into a
271-
restart loop with no failing test. Ordering is normative: exit-code
272-
contract first, `OnFailure` second. (The systemd binding needs the
273-
identical primitive for `Restart=on-failure` — independent confirmation
274-
this is the real seam. `Restart=always` remains non-conforming at any
275-
layer: it resurrects after a *clean* exit, defeating `!shutdown`.)
262+
resurrection story working *for* the owner. Stated launcher-neutrally:
263+
**if a supervisor exists, its restart policy MAY revive an abnormal
264+
death and MUST NOT revive an intentional clean exit.** A launcher with
265+
no supervisor at all — a hand-launched process on a VPS — satisfies
266+
this vacuously: nothing restarts anything. How bounded vs indefinite
267+
lifetime maps onto a concrete supervisor policy is binding policy
268+
([L3]), realized and documented by each binding — this binding's
269+
mapping lives in §Pod shape; a systemd binding's in its unit
270+
directives. Any revive-on-abnormal-death policy carries a universal
271+
precondition: the supervisor can distinguish intent from accident only
272+
if the harness formally promises *clean exit = exit code 0* on every
273+
intentional path and nonzero otherwise, pinned by test. At `c1bca1b56`
274+
that property is emergent, not defended (Known Defect 6);
275+
restart-on-failure before the pinned contract is how a refactor
276+
silently converts every clean stop into a restart loop with no failing
277+
test. Ordering is normative: exit-code contract first,
278+
restart-on-failure second — the identical seam in every supervisor that
279+
offers the distinction. An always-restart policy remains non-conforming
280+
at any layer: it resurrects after a *clean* exit, defeating
281+
`!shutdown`.
276282

277283
Enforcement: the self-stop lives *inside the harness* (the only place
278-
that can see activity, per M1) (§Auto-Stop), and the binding makes it
279-
effective on the substrate by requiring that a terminated harness
280-
terminates its container (harness as the container's signal-receiving
281-
PID 1) and that the substrate's restart policy respects intent as above.
284+
that can see activity, per M1) (§Auto-Stop), and each binding makes it
285+
effective on its substrate by requiring that harness exit terminates
286+
the substrate's unit of execution (this binding's realization — the
287+
harness as the container's signal-receiving process — is §Pod shape,
288+
[L3]) and that any supervisor's restart policy respects intent as
289+
above.
282290
Boundaries: (a) the guarantee is conditional on a live harness event
283291
loop — a wedged process that cannot run its reaper timer cannot reap
284292
itself, and M1 means nothing else will (the mitigation is the substrate
285293
operator's, e.g. a namespace-level TTL policy, out of scope per
286294
§Non-Goals); (b) restart policy prevents resurrection, it does not prove
287-
process exit; (c) I5 bounds *agent* lifetime, not substrate residue — a
288-
Completed pod object persists for forensics until the next deploy's GC
289-
(§K8s GC).
295+
process exit; (c) I5 bounds *agent* lifetime, not substrate residue —
296+
residue (in this binding, a Completed pod object) persists for
297+
forensics until the next deploy's GC (§K8s GC).
290298

291299
## Provider Protocol
292300

@@ -846,18 +854,24 @@ can yield two live instances in one scope.
846854
(late-arriving reap `lib.rs:2664`, idle-slot reap loop `:2670`, respawn
847855
drain `:2684-2688`) runs *outside* the 30s drain timeout (opened at
848856
`:2636`, closed at `:2657`) and serially awaits a 5s post-SIGKILL wait
849-
per occupied pool slot (`acp.rs:436`), so the worst-case tail is
850-
`30 + 5×parallelism + 7` — **~87s at the desktop's default parallelism
857+
per occupied pool slot (`acp.rs:436`). **That segment alone can reach
858+
`30 + 5×parallelism + 7` — ~87s at the desktop's default parallelism
851859
of 10** (`DEFAULT_AGENT_PARALLELISM`, `types.rs:809`; lowered from 24 by
852-
#3038), ~197s at the harness cap of 32 (`config.rs:293`), against a 60s
853-
grace.
860+
#3038), ~197s at the harness cap of 32 (`config.rs:293`) — already
861+
exceeding a 60s grace. And it is a *lower* bound on the tail, not the
862+
worst case: the same path runs earlier segments before the prompt drain
863+
even opens — a separate 30s wake-task drain (`:2612`) followed by
864+
serial shutdown of any awakened pools (`:2620-2624`), whose per-slot
865+
`acp.shutdown()` loop (`:3747-3751`) has no timeout of its own. The
866+
total tail is not bounded by today's segment timeouts at all.
854867
The requirement is therefore stated as a budget, not a sum (Known
855868
Defect 7): **the harness MUST bound its total shutdown tail — every
856869
post-signal segment, including per-slot reaping — under one shared
857870
deadline no greater than the declared grace budget**, and the budget
858-
MUST include a **reserved finalization slice**: a tail portion held back
859-
for presence `offline` publish and relay close, which child cleanup may
860-
never consume — child reaping degrades first (skip remaining per-slot
871+
MUST include a **reserved finalization slice** held back for presence
872+
`offline` publish and relay close, **no smaller than those finalizers'
873+
declared bounds — currently 2s + 5s = 7s** — which child cleanup may
874+
never consume: child reaping degrades first (skip remaining per-slot
861875
waits, force-kill), because a shared deadline without the reservation
862876
can legally spend all 60s reaping children and hit SIGKILL before the
863877
one action the grace period exists to protect. The binding declares the
@@ -925,8 +939,9 @@ substrate half *and* the graceful-shutdown budget: the termination signal
925939
lands on the wrapper, the harness never learns to shut down, and the
926940
force-kill leaves presence stale-online — exactly the staleness window the
927941
grace period exists to close. See §K8s Entrypoint for the concrete rule.
928-
With the restart policy that matches the lifetime policy (bounded →
929-
`Never`, indefinite → `OnFailure` after the exit-code contract; I5),
942+
With the supervisor policy that matches the lifetime policy (this
943+
binding's [L3] mapping — bounded → `Never`, indefinite → `OnFailure`
944+
after both prerequisites, §Pod shape; the universal rule is I5's),
930945
harness exit completes the pod on every intentional path — turning
931946
agent-level I5 into substrate-level I5.
932947

@@ -1152,14 +1167,16 @@ regardless of `HOME`.
11521167
would SIGKILL the harness mid-drain, leaving presence stale-online — the
11531168
avoidable half of I3's staleness window — so the binding declares 60s.
11541169
But the shutdown tail is *variable*, not constant (§Stop: the post-drain
1155-
reap segment scales with occupied pool slots — ~87s worst case at
1156-
default parallelism at `b4f4ed1a6`), so no fixed grace can be proven
1170+
reap segment alone reaches ~87s at default parallelism at `b4f4ed1a6`,
1171+
and earlier untimed segments precede it — the total is not bounded by
1172+
today's segment timeouts), so no fixed grace can be proven
11571173
sufficient by adding segment timeouts. The two halves of the requirement:
11581174
the binding *declares* the budget here, and the harness *enforces* it —
11591175
one shared deadline across the entire post-signal path, with a reserved
1160-
finalization slice for presence `offline` and relay close, child cleanup
1176+
finalization slice (≥ the finalizers' declared bounds, currently 7s) for
1177+
presence `offline` and relay close, child cleanup
11611178
degrading first (§Stop, Known Defect 7). Until the harness enforcement
1162-
lands, 60s is an operational margin that the worst case can exceed.
1179+
lands, 60s is an operational margin that the tail can exceed.
11631180
- **Hardening defaults (normative).** The workload is a prompted coding
11641181
agent running repository and tool code while holding an nsec; the pod MUST
11651182
NOT hand it ambient cluster credentials or kernel privilege on top:
@@ -1601,12 +1618,17 @@ Desktop- and harness-side, discovered during this design:
16011618
reap segment
16021619
(`lib.rs:2664-2688`) runs *after* the 30s drain timeout closes
16031620
(`:2636,:2657`) and serially awaits a 5s post-SIGKILL wait per occupied
1604-
slot (`acp.rs:436`) — worst case ~87s at the desktop's default
1605-
parallelism of 10 (`types.rs:809`; #3038 lowered it from 24), ~197s at
1606-
the harness cap of 32
1607-
(`config.rs:293`), against the binding's
1608-
60s grace. The fix is one shared deadline across the entire post-signal
1609-
path with a reserved finalization slice for presence `offline` and
1621+
slot (`acp.rs:436`) — that segment alone reaches ~87s at the desktop's
1622+
default parallelism of 10 (`types.rs:809`; #3038 lowered it from 24),
1623+
~197s at the harness cap of 32 (`config.rs:293`), against the binding's
1624+
60s grace; and it is not the whole tail — the wake-task drain
1625+
(`:2612`) and awakened-pool shutdown (`:2620-2624`, per-slot loop
1626+
`:3747-3751`, no timeout) precede it (§Stop), so the total is
1627+
unbounded by today's segment timeouts. The fix is one shared deadline
1628+
across the entire post-signal
1629+
path with a reserved finalization slice (≥ the finalizers' declared
1630+
bounds, currently 2s presence + 5s relay close = 7s) for presence
1631+
`offline` and
16101632
relay close, child cleanup degrading first (§Stop); natural home is the
16111633
same harness change as the I5 reaper (defect 4).
16121634
8. **Cleared numeric config fields ship as strings** (desktop code

0 commit comments

Comments
 (0)