thumb/05-agent-binary #100

Open
prskr wants to merge 47 commits from thumb/05-agent-binary into main
Owner
No description provided.
Thumb: implement wire protocol
Some checks failed
boredaem CI / build-and-lint (pull_request) Has been cancelled
d9ec0b300d
- Unmap IPv4-mapped IPv6 addresses in Listener.DialAddr before
  loopback/unspecified checks; use netip.IPv6Loopback() and a package-level
  loopbackV4 constant.
- Wrap each snaps.MatchJSON case in t.Run for stable snapshot names.
- Extract shared listener sort into sortListeners using slices.SortFunc.
- Add TestHelloNormalize for the Baseline sort guarantee.
- Treat JSON null as a no-op in Duration.UnmarshalJSON.
- Add tests for null duration and v4-mapped IPv6 dial addresses.
- Tolerate errNoListeners from either /proc/net/tcp or /proc/net/tcp6 in
  Parser.Read, preserving listeners from the other file.
- Add logger() accessor so zero-value Parser falls back to slog.Default().
- Use slices.Concat in mergeListeners to avoid mutating caller slices.
- Make IPv6 expectation explicit in TestParseHexAddr.
- Use bytes.NewReader in BenchmarkParseLarge to avoid per-iteration copies.
Thumb: address procnet parser review findings
Some checks failed
boredaem CI / build-and-lint (pull_request) Has been cancelled
723017c0f6
- move Go instructions to AGENTS.md for all agents to find them
- updated review instructions
Thumb: address rpc review findings on backpressure doc and tests
Some checks failed
boredaem CI / build-and-lint (pull_request) Has been cancelled
1161ac14f4
- document that a blocked send also suspends the sender's inbound dispatch and scopes send semantics to unbuffered transports
- add Hub/Agent Close() as the caller's way out of a hung connection
- tighten TestThousandSnapshotsNoDrops to assert the send loop finishes well before the handler
- add teardown test with both handlers blocked and table-driven partial-nil handler tests against exported ErrNilHandler
- drop unreachable nil-agent blocks; mustHub/mustAgent panic on nil instead
- Close now closes the transport writer first, which unblocks any send stuck
  on the wire (a blocked send holds the server lock, so Stop alone could not
  break it), then stops the server; guarded by sync.Once so it still takes
  effect only once
- update package and method docs to match the corrected Close behavior
- read doneAt in TestThousandSnapshotsNoDrops and assert the send loop
  finishes in under a quarter of the handler's elapsed time
- add TestCloseUnblocksBlockedSend pinning Close while a Snapshot push is
  blocked on an undrained pipe
- make NewHub/NewAgent name the actual missing handler(s) so the error
  message (and its test assertion) is discriminating
Thumb: name blocked-send test fixture fields and de-duplicate Close caveat
Some checks failed
boredaem CI / build-and-lint (pull_request) Has been cancelled
e1b27293fc
- WithAttrs resolves attributes eagerly against the current group prefix so
  attributes added before WithGroup stay ungrouped (slog semantics)
- failed sends fold their records into the Dropped count instead of losing
  them silently
- replace the dropped-counter CAS reset with an atomic subtract
- bound the final flush with Options.ShutdownTimeout so Close cannot hang
- ship records-less batches when drops are pending
- drop unreachable nil-level and emits-close branches
- make the final-flush ShutdownTimeout bound structural: run the send in a
  goroutine and give up on flushCtx.Done(), so Close returns on schedule even
  when the sink ignores its context
- throttle drops-only batches to at most one per RateLimit so a failing sink
  is not polled with an empty payload at flush cadence
- document on the package and wire.LogBatch.Dropped that the count covers
  both buffer overflow and failed-send losses
- add tests for the shutdown bound, the records-less drop batch and the
  drops-only throttle
- make TestCloseBoundedByShutdownTimeout use a ctx-ignoring sink so it only
  passes because of the structural goroutine+select bound, not the sink
  honouring its deadline; tighten the bound assertion to 4x ShutdownTimeout
- document that a timed-out final flush abandons its goroutine (it may
  deliver or fail after Close returns) and gate its diag/dropped accounting
  behind a control.abandoned flag set on timeout
- add Options.DropReportInterval (defaulting to RateLimit) for the
  drops-only batch cadence, decoupling it from the recursion-guard diag rate
- move the abandoned check in send to right after the sink returns so the
  late goroutine skips all accounting, not just the failure path
- add TestAbandonedFlushSkipsFailureAccounting pinning that a post-Close
  sink failure never reaches the diag writer
- reword the abandoned and DropReportInterval comments: best-effort gate,
  and DropReportInterval is unrelated to RateLimit apart from its default
- replace the bare bytes.Buffer with a mutex-guarded syncBuffer that signals
  the first Write, so the read is race-free and a regression fails with the
  intended assertion instead of a data race
- replace the bare time.Sleep with an explicit wait on the sink having
  returned and a bounded select on the writer signal
- document that the test pins the failure-path gate; the success-path skip
  is invariant hygiene with no externally observable effect
- remove assert.Equal on the diag buffer, which could never fail because
  syncBuffer.Write closes written on the first write so the preceding select
  already fails the test
- document that detection is anchored to the sink returning and that a
  removed gate is caught as soon as its write lands; widen the grace window
  to 200ms
- add runtime.Gosched() after the sinkDone wait so the abandoned goroutine
  runs the gate immediately, then keep the bounded poll at 50ms; the failure
  signal is observed the moment it lands on diag.written, so the window only
  guards against descheduling
- cuts every green run of TestAbandonedFlushSkipsFailureAccounting from
  ~200ms to ~50ms of waiting
- PLAN.md §7 and task 04: logstream's non-blocking guarantee covers only its
  own sink; the stderr TextHandler is synchronous and safe only while the hub
  drain consumes, and a stopped drain (scanner error, hub blocked) blocks agent
  logging through stderr too
- PLAN.md §7, tasks 04 and 07: stderr drain is debug while agent.log batches
  flow and promotes to info when the RPC path errors or goes quiet
- task 04: define Close as safe before Run starts
- task 05: agent-binary snippet handles the NewAgent error, defers ls.Close()
  and logs Run's error instead of starting the pump on a nil peer
- PLAN.md §7 and task 04: note the dual-sink duplication doubles wire bytes and
  that the stderr TextHandler keeps the shared LevelVar
- stop tracking per-developer opencode.json and gitignore it
- logstream_test: soften the Gosched comment (yield is not a scheduling
  guarantee; the bounded window bounds detection)
Every agent log record used to ship twice: once via agent.log RPC
notifications, once as a stderr duplicate — doubling wire bytes on the
one SSH channel whose window exhaustion can deadlock both directions,
and forcing a hub-side heuristic to hide the duplicate. Replace the
stderr copy with a durable JSON file on the VM (last.log, truncated
and size-capped per run); stderr becomes logstream's recursion-guard
channel only, so any stderr line is now itself a "log path is broken"
signal instead of routine traffic. A --log-mode=stderr escape hatch
remains for hand-debugging, selected by the operator, never the hub.

logstream.Handler no longer needs a Run(ctx, sink) the caller must
launch and track: New starts its own pump, and SetSink registers the
destination once the RPC peer exists (a real construction-order
constraint — rpc.NewAgent's handlers may log before peer.Log exists).
Records flushed with no sink registered are dropped and folded into
the count rather than held, which is safe now that the fallback file
has every record regardless.

Also drops hub.setConfig-driven runtime log-level changes: direct-tcpip
forwarding is entirely hub-driven and unaffected by an agent restart,
so changing the agent's verbosity is a cheap restart with a different
--log-level rather than a live push. wire.Config.LogLevel is removed
and logstream.New takes a plain slog.Level fixed at construction.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
roborev flagged that Close could hang indefinitely: logstream's pump
sends regular (ticker/MaxBatch-triggered) batches synchronously inside
its main loop using context.Background(), so a sink blocked mid-flush
— the documented realistic case, an RPC write into a full SSH window —
left the loop unable to reach its stop signal or its final-flush defer.
This is a regression from the Run(ctx, sink) design this session
replaced: the caller-supplied ctx at least gave a context-respecting
sink a chance to unblock on shutdown.

Fix: run's pump now receives a context cancelled by Close, threaded
through to every regular send, so a context-respecting sink stuck in a
regular flush unblocks the moment Close is called. For a sink that
ignores its context entirely, Close's own wait on the pump's done
signal is now itself bounded by ShutdownTimeout — the same abandon-the-
goroutine tolerance already documented for a stuck final flush, applied
uniformly instead of only there. The context is threaded as a run/flush
parameter rather than stored on control, per nogo's containedctx check;
the final flush's own deadline derives via context.WithoutCancel(ctx)
rather than context.Background(), per nogo's contextcheck, since ctx is
already cancelled by the time that deferred block runs.

Also fixes two ByteSize.UnmarshalText bugs the same review caught:
"512B" was rejected because the trimmed-suffix string was discarded in
favor of the original when no unit matched, and n << shift could
overflow silently into a negative size with no bounds check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
roborev review 29 flagged that the previous Close fix had a side
effect: cancelling the pump context on Close made a context-respecting
sink return ctx.Err(), which send treated as a genuine failure — a
"context canceled" diagnostic on stderr on every ordinary clean
shutdown that happened to land mid-flush (exactly the false "log path
is broken" signal PLAN.md §7 designed the recursion guard to avoid),
plus pending was cleared before the final flush's own detached context
ever got a chance to actually deliver the batch, turning a deliverable
record into a guaranteed drop.

Fix: flush skips the send outright when its context is already
cancelled on entry (a ticker tick racing the stop signal), and send
now distinguishes "the sink failed" from "our own cancellation cut
this short" by checking ctx.Err() after the call — ctx here is always
one of logstream's own internally-built contexts, never caller-
supplied, so ctx.Err() != nil is unambiguous. Either way pending is
left for the final flush to retry rather than dropped or reported.

Also from the same review: Close is idempotent but a second call after
the pump was abandoned used to re-pay a full ShutdownTimeout every
time; a control.abandoned flag makes later calls return immediately.
ByteSize.UnmarshalText trimmed the optional B suffix case-sensitively
while matching unit suffixes (K/M/G/T) case-insensitively, rejecting
"512b"/"8mib" though "512B"/"8MiB" worked — now uses the same
cutSuffixFold for both. The ShutdownTimeout field doc was also stale
after the prior fix; restated what it actually bounds now.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Review 30 (low severity):
- send's cancellation-retry path trades at-most-once delivery for
  at-least-once: whether a batch is "resolved" is decided from ctx.Err()
  after the sink returns, not from whether the sink had already handed
  the batch to its transport before noticing cancellation. A sink that
  writes the frame and then has its response wait cut short looks
  identical here to one that sent nothing, so the retry may deliver the
  same batch twice. Documented explicitly on send and Close so a future
  Sink implementer doesn't read "cut short" as "definitely untransmitted".
- Close's "later calls return immediately" guarantee only holds for
  sequential calls — concurrent Close calls aren't coordinated beyond
  the CompareAndSwap gating close(stop)/cancelPump, so two goroutines
  calling it at once could each independently pay ShutdownTimeout.
  Scoped the doc to say so rather than adding coordination for a
  scenario the agent's own single-defer call site never exercises.

Also fixes the one still-open finding from review 26 (predates this
session's fallback-file work; its other three findings targeted a
debug/info promotion heuristic and a recursion-prone log line that no
longer exist post-refactor): the agent-binary task's logger-composition
snippet didn't say which kong lifecycle function it belongs in. A defer
placed in AfterApply fires as soon as AfterApply returns, tearing the
logger down before the agent's actual lifetime in Run ever begins. Task
05 now states explicitly that the whole snippet lives in Run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Review 31 caught two low-severity issues in the logger-composition
snippet added by the previous commit (which itself was fixing a
review 26 finding — turns out doc fixes need their own review pass
too):

- Turning the fragment into a full func (a *app) Run(ctx
  context.Context) error body made rpcIn/rpcOut read as in-scope
  locals, but per the "Stdout is sacred" section main dups fd 1 and
  hands both ends to the app struct before kong ever parses a flag —
  Run can only reach them as a.rpcIn/a.rpcOut. Also added the missing
  return peer.Wait() so the exit path isn't left implicit.
- "There is nothing here that genuinely needs to happen in
  AfterApply" read as licence to skip AfterApply's project-mandated
  role (constructing dependencies after flags parse) rather than the
  narrower point actually intended: anything owning a defer-based
  lifetime must be built in whichever function's exit ends that
  lifetime, which is Run, not AfterApply for a defer. Reworded to
  keep AfterApply's role intact and state the defer-scope argument
  precisely instead of implying AfterApply is unneeded.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Review 32 flagged two gaps in the Run-scoping snippet from the previous
commit:

- No defer peer.Close(). NewAgent's own doc is explicit that "the
  caller owns w and tears the peer down with Close or by closing w" —
  the snippet showed construction but never disposal.
- return peer.Wait() as the literal last line ignores ctx entirely,
  even though Run's signature takes one and task 05's Steps have main
  build a signal context specifically to hand it in. The ping watchdog
  also wasn't tied to anything that would make Wait() actually return.

Fixed by adding defer peer.Close() and a comment establishing the
actual mechanism: every exit path (stdin EOF, ctx cancellation, hub
watchdog) converges on the same peer.Close() call, which unblocks
Wait() — Close is idempotent, so the deferred call is a no-op wherever
one of the others already ran it. Rewrote the Lifetime section to
state this explicitly and added ctx cancellation as its own mechanism
(distinct from sshd SIGHUP, which only fires on the SSH session ending,
not on someone signalling the agent process directly on the VM).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
thumb: fix Close teardown ordering and lifecycle framing from review 34
Some checks failed
boredaem CI / build-and-lint (pull_request) Has been cancelled
b7ba048a74
Review 34 caught a real regression in the previous commit's fix, plus
three doc-accuracy gaps:

- Medium: defer peer.Close(), registered after defer lg.Close(), ran
  LIFO — peer.Close() first, lg.Close() second — tearing the RPC
  transport down before the logger's final flush could use it. The
  doc's own "lg.Close() flushes the last batch" promise was silently
  defeated for the RPC half. Fixed by combining both into a single
  deferred closure with lg.Close() called before peer.Close() inside
  it, making the order an explicit decision instead of an accident of
  defer registration order. peer is now a var assigned after NewAgent
  succeeds so the same closure, registered once at the top, covers
  both the NewAgent-failure path (peer stays nil) and the success path.

- Low: "one mechanism wearing different hats" overstated what stdin
  EOF and SIGHUP actually do — neither runs a peer.Close() call on
  this side. Reframed: only ctx cancellation and the ping watchdog
  converge on peer.Close(); stdin EOF unblocks Wait() directly and
  SIGHUP bypasses Go entirely.

- Low: "[SIGHUP] tears down the process ... regardless of Go-level
  handling" is wrong — SIGHUP is catchable, and main's signal.NotifyContext
  could register it. Reworded to state the actual dependency: free as
  long as SIGHUP isn't in that signal set, since Go's default
  disposition for it terminates the process.

- Low: item 3's ctx-cancellation goroutine had a stated placement
  constraint ("right after peer exists") that the canonical Run
  snippet — the one place that exists specifically to pin down
  ordering — didn't show, and its trailing comment read as "no ctx
  handling here" instead. Added the goroutine to the snippet and
  reworded the comment.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
thumb: refactor agent package to remove artificial complexity
All checks were successful
boredaem CI / build-and-lint (pull_request) Successful in 9m6s
1ce51b1b53
Some checks are pending
boredaem CI / build-and-lint (pull_request) Successful in 9m6s
Validate / validate (pull_request)
Required
This pull request has changes conflicting with the target branch.
  • .claude/settings.json
  • .roborev.toml
  • .zed/settings.json
  • AGENTS.md
  • MODULE.bazel
  • go.mod
  • go.sum
  • pkg/testx/BUILD.bazel
  • thumb/PLAN.md
  • thumb/internal/procnet/BUILD.bazel
  • thumb/internal/procnet/parser.go
  • thumb/internal/procnet/procnet_test.go
  • thumb/internal/sshx/BUILD.bazel
  • thumb/internal/sshx/sshd_integration_test.go
  • thumb/internal/sshx/sshx.go
  • thumb/internal/sshx/sshx_internal_test.go
  • thumb/internal/sshx/sshx_test.go
  • thumb/internal/sshx/testdata/sshd/Dockerfile
  • thumb/tasks/02-procnet-parser.md
  • thumb/tasks/06-sshx-connection.md
  • thumb/tasks/08-hub-reconciliation.md
  • thumb/tasks/09-forward-data-plane.md
  • thumb/tasks/10-hub-binary.md
  • thumb/tasks/12-resilience.md
  • thumb/tasks/13-polish.md
  • thumb/tasks/14-packaging-and-release.md
  • thumb/tasks/15-documentation.md
  • thumb/tasks/README.md
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin thumb/05-agent-binary:thumb/05-agent-binary
git switch thumb/05-agent-binary
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
prskr/tools!100
No description provided.