Skip to content

Commit 2076faf

Browse files
author
npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d
committed
docs(remote-agents): Sami's review — stale pin corrected, crash-loop prerequisite, coercion defect
Fixes Sami's R1 (blocker), R3, and the flagged minor from his review of 4432030. (R2 was independently fixed by ffe760a — Wren's blocker 1/2, same finding.) - R1: the parallelism "correction" was backwards. c1bca1b — the document's pre-existing citation pin — is an unmerged feature-branch commit that diverged from main Jul 18 and predates #3038 (default parallelism 24 -> 10, which IS in this PR's base b4f4ed1). The shutdown-tail worst case is ~87s at default parallelism 10, not ~157s at 24. Corrected in §Stop, §K8s Grace, and Known Defect 7, with every line reference in those passages re-verified against b4f4ed1 itself (drain timeout lib.rs:2636/2657, reap segment :2664-2688, graceful Ok(()) :2723, !shutdown :2045, Ctrl-C :1635, SIGTERM :1644, acp.rs:436, types.rs:809, config.rs:293, config.rs:378 for no_presence). Known Defects gains a citation-pin caveat naming the stale pin and promising a follow-up re-pin; structural claims unchanged (87s still blows the 60s grace). - R3: OnFailure's second prerequisite named. A crash-looping harness (phase Running, waiting{CrashLoopBackOff}, restartCount > 0) falls through every deploy-state-machine row and fails the started criterion while the kubelet is reviving it. §Pod shape now states that the exit-code contract alone is NOT the green light: a crash-loop classification row + restartCount treatment in the started-criterion MUST land before the binding ships OnFailure; L3 conformance item 2 gates on both prerequisites. - Known Defect 8 (new): coerceConfigValues (ProviderConfigFields.tsx:6) ships a cleared numeric field as "" — a JSON string — and blessing inactivity_seconds: 0 puts that arm on a documented path. Desktop fix (cleared -> omit-or-default) plus provider-side in-band error for non-numeric numerics. Verified: git merge-base --is-ancestor c1bca1b b4f4ed1 -> false; DEFAULT_AGENT_PARALLELISM = 10 at b4f4ed1 types.rs:809; all replaced line references checked against git show b4f4ed1 in this worktree. Surviving pool_ready cites (lib.rs:1743/:1320/:2570, pool_lifecycle.rs:42) hold identically at b4f4ed1 and were left. Co-authored-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz> Signed-off-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz>
1 parent ffe760a commit 2076faf

1 file changed

Lines changed: 59 additions & 23 deletions

File tree

‎docs/remote-agents.md‎

Lines changed: 59 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -842,14 +842,15 @@ can yield two live instances in one scope.
842842
derive an upper bound for this path from its segment timeouts, because
843843
review proved that arithmetic wrong twice**: the visible constants (30s
844844
drain, 2s presence, 5s relay close) omit terms that are *variable*, not
845-
constant — at `c1bca1b56` the post-drain reap segment (late-arriving
846-
reap `lib.rs:2401`, idle-slot reap loop `:2407`, respawn drain `:2425`)
847-
runs *outside* the 30s drain timeout (opened at `:2366`, closed at
848-
`:2394`) and serially awaits a 5s post-SIGKILL wait per occupied pool
849-
slot (`acp.rs:393`), so the worst-case tail is `30 + 5×parallelism + 7`
850-
— **~157s at the desktop's default parallelism of 24**
851-
(`DEFAULT_AGENT_PARALLELISM`, `types.rs:725`), ~197s at the harness cap
852-
of 32 (`config.rs:292`), against a 60s grace.
845+
constant — at this PR's base `b4f4ed1a6` the post-drain reap segment
846+
(late-arriving reap `lib.rs:2664`, idle-slot reap loop `:2670`, respawn
847+
drain `:2684-2688`) runs *outside* the 30s drain timeout (opened at
848+
`: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
851+
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.
853854
The requirement is therefore stated as a budget, not a sum (Known
854855
Defect 7): **the harness MUST bound its total shutdown tail — every
855856
post-signal segment, including per-slot reaping — under one shared
@@ -905,7 +906,7 @@ I5's enforcement point. A new harness knob:
905906
`RESERVED_ENV_KEYS` (`env_vars.rs`) when it lands — it is tier-3
906907
authoritative (§Launch data), and without reservation a user env var
907908
could disable the reaper and reopen unbounded lifetime through the front
908-
door. `BUZZ_ACP_NO_PRESENCE` (`config.rs:377`) MUST join in the same
909+
door. `BUZZ_ACP_NO_PRESENCE` (`config.rs:378`) MUST join in the same
909910
change, for the same shape of reason at I3 instead of I5: unreserved, it
910911
lets user env silently defeat the 90s presence bound (I3). One knob
911912
guards "knows when to leave", the other "you can see that it left";
@@ -1077,7 +1078,19 @@ regardless of `HOME`.
10771078
`OnFailure` against an undefended exit convention). `OnFailure`
10781079
restarts the *in-place* abnormal deaths — process crash, container
10791080
OOM-kill — and honors the intentional ones (clean exit completes the
1080-
pod): I5's intent-vs-accident distinction, realized. **Honest
1081+
pod): I5's intent-vs-accident distinction, realized. **Second
1082+
prerequisite — reconciler classification:** `OnFailure` introduces a
1083+
pod state the deploy state machine's rows do not cover — a
1084+
crash-looping harness sits in phase `Running` with
1085+
`state.waiting{reason: CrashLoopBackOff}`, `restartCount > 0`: not
1086+
deletion-marked, not terminated (the kubelet keeps restarting it),
1087+
not "live and started" (`state.running` is false), and not
1088+
never-started (it started, repeatedly) — and it fails the startup
1089+
success criterion while the kubelet is actively reviving it. Before
1090+
the binding ships `OnFailure`, the state machine MUST gain a
1091+
crash-loop classification row and the started-criterion's treatment
1092+
of `restartCount > 0` MUST be specified; the exit-code contract alone
1093+
is *not* the green light. **Honest
10811094
limit:** `restartPolicy` is
10821095
kubelet-level and cannot survive *node-level* loss — a drain or
10831096
API-initiated eviction deletes a bare pod outright, and no
@@ -1139,8 +1152,8 @@ regardless of `HOME`.
11391152
would SIGKILL the harness mid-drain, leaving presence stale-online — the
11401153
avoidable half of I3's staleness window — so the binding declares 60s.
11411154
But the shutdown tail is *variable*, not constant (§Stop: the post-drain
1142-
reap segment scales with occupied pool slots — ~157s worst case at
1143-
default parallelism at `c1bca1b56`), so no fixed grace can be proven
1155+
reap segment scales with occupied pool slots — ~87s worst case at
1156+
default parallelism at `b4f4ed1a6`), so no fixed grace can be proven
11441157
sufficient by adding segment timeouts. The two halves of the requirement:
11451158
the binding *declares* the budget here, and the harness *enforces* it —
11461159
one shared deadline across the entire post-signal path, with a reserved
@@ -1432,8 +1445,9 @@ The realization the two lists above require, in this binding's vocabulary:
14321445
(I5) through this binding's `inactivity_seconds` field: `> 0` →
14331446
a working inactivity bound and `restartPolicy: Never`; `0` (the
14341447
blessed indefinite opt-in) → no bound and `restartPolicy: OnFailure`,
1435-
**only after the pinned exit-code contract lands** — until then the
1436-
provider MUST refuse the combination (I5 ordering rule).
1448+
**only after both prerequisites land** — the pinned exit-code contract
1449+
(I5 ordering rule) *and* the crash-loop classification row (§Pod
1450+
shape); until then the provider MUST refuse the combination.
14371451
3. The harness is the deployed container's **signal-receiving process**
14381452
(PID 1 or the target of the pod's termination signal — §K8s
14391453
Entrypoint's `exec` rule), and `terminationGracePeriodSeconds` carries
@@ -1506,6 +1520,13 @@ hand-written model would have reproduced convincingly.
15061520

15071521
## Known Defects (at `c1bca1b56`)
15081522

1523+
**Citation-pin caveat:** `c1bca1b56` is an unmerged feature-branch commit
1524+
that diverged from main on Jul 18 and predates #3038 (default parallelism
1525+
24 → 10). Line references marked `at b4f4ed1a6` were re-verified against
1526+
this PR's own base; unmarked `c1bca1b56` references may be offset on
1527+
current main. A follow-up re-pins the whole document to one merged
1528+
commit.
1529+
15091530
Desktop- and harness-side, discovered during this design:
15101531

15111532
1. **Windows discovery id pollution**: the `.exe` suffix survives into the
@@ -1563,9 +1584,10 @@ Desktop- and harness-side, discovered during this design:
15631584
resolve-once → stage-and-digest → `info` → explicit-version check →
15641585
`deploy`, both invocations running the staged bytes.
15651586
6. **The clean-exit contract is emergent, not defended** (harness code
1566-
prerequisite; gates `OnFailure`). The graceful path returns `Ok(())`
1567-
(`lib.rs:2460`), and owner `!shutdown` (`:1883`), Ctrl-C (`:1549`), and
1568-
SIGTERM (`:1558`) all route into the same shutdown channel — so clean
1587+
prerequisite; gates `OnFailure`). At `b4f4ed1a6`: the graceful path
1588+
returns `Ok(())` (`lib.rs:2723`), and owner `!shutdown` (`:2045`),
1589+
Ctrl-C (`:1635`), and
1590+
SIGTERM (`:1644`) all route into the same shutdown channel — so clean
15691591
stops exit 0 *today*, but no distinguished exit code exists and no test
15701592
pins "intentional exit ⇒ 0"; every `process::exit(1)` in the crate is a
15711593
startup failure. Until a
@@ -1575,16 +1597,30 @@ Desktop- and harness-side, discovered during this design:
15751597
timeout would silently convert every clean stop into a restart loop —
15761598
I5 defeated with no failing test (I5 ordering rule).
15771599
7. **The shutdown tail overruns the declared grace budget at default
1578-
config** (harness code prerequisite). The post-drain reap segment
1579-
(`lib.rs:2401-2430`) runs *after* the 30s drain timeout closes
1580-
(`:2366,:2394`) and serially awaits a 5s post-SIGKILL wait per occupied
1581-
slot (`acp.rs:393`) — worst case ~157s at the desktop's default
1582-
parallelism of 24 (`types.rs:725`), ~197s at the harness cap of 32
1583-
(`config.rs:292`), against the binding's
1600+
config** (harness code prerequisite). At `b4f4ed1a6`: the post-drain
1601+
reap segment
1602+
(`lib.rs:2664-2688`) runs *after* the 30s drain timeout closes
1603+
(`: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
15841608
60s grace. The fix is one shared deadline across the entire post-signal
15851609
path with a reserved finalization slice for presence `offline` and
15861610
relay close, child cleanup degrading first (§Stop); natural home is the
15871611
same harness change as the I5 reaper (defect 4).
1612+
8. **Cleared numeric config fields ship as strings** (desktop code
1613+
prerequisite, raised by blessing `0`). `coerceConfigValues`
1614+
(`desktop/src/features/agents/ui/ProviderConfigFields.tsx:6` at
1615+
`b4f4ed1a6`) skips numeric coercion when the value is `""`, so a
1616+
*cleared* numeric field reaches the provider as a JSON string instead
1617+
of a number. Blessing `inactivity_seconds: 0` makes clearing that
1618+
field a legitimate user action, so the empty-string arm now sits on a
1619+
documented path: the provider receives `""` where the schema says
1620+
integer, and "0 MUST NOT be rejected" cannot protect a value that
1621+
never parses as 0. Fix is desktop-side (map cleared numeric →
1622+
omit-or-default, never `""`); provider-side, a non-numeric value for a
1623+
numeric field is an in-band error, not a silent default.
15881624

15891625
## Implementation Correspondence
15901626

0 commit comments

Comments
 (0)