Add fork mailbox payload API

[sjmiller609]

Summary

• add optional named JSON mailbox payloads to instance and snapshot fork requests
• patch matching mailbox markers in standby snapshot memory before the fork resumes
• optionally wait for guest UDP acknowledgements after resume when a mailbox requests it
• share mailbox marker/layout helpers through lib/mailbox so host and guest-side integrations use the same contract
• preserve existing fork network readiness behavior: running forks wait for network readiness, with resume-network fallback paths unchanged

Tests

• make oapi-generate
• git diff --check origin/main --
• go test ./lib/mailbox ./lib/guest ./lib/system/guest_agent ./lib/oapi -count=1
• go test ./cmd/api/api ./lib/instances -run 'Test(ForkInstanceSuccess|ForkSnapshotSuccess|PatchForkMailbox|ForkMailboxPayloadWithAckPort|ForkReturnReadinessDoesNotUseMailboxEligibility)' -count=1 (with local placeholder embedded binaries)\n\nFull cmd/api/api and lib/instances package test runs still require embedded hypervisor, guest-agent, and caddy binaries in this checkout.

---

Note

High Risk
Changes fork/restore orchestration and direct snapshot memory patching; incorrect markers or ack handling can fail forks or leave guests misconfigured, and the feature is limited to Firecracker standby→Running paths.

Overview
Adds optional named JSON mailboxes to instance and snapshot fork APIs so callers can inject per-fork configuration into guest memory before a forked standby VM resumes.

Fork requests accept a mailboxes array (name, guest-provided token, JSON payload, optional wait_for_ack / ack_timeout_ms). The API layer maps these into domain types; Firecracker standby forks that target Running validate payloads (limits, duplicate names, JSON object shape) and patch matching markers in snapshot memory before restore. When wait_for_ack is set, the host injects ack_port and fails restore if the guest does not send a UDP stage=applied ack for that mailbox in time.

lib/mailbox gains fork-specific layout/marker helpers and shared FindMarker / WritePayloadAt used by resume-network and fork paths. Restore runs resume-network and fork-mailbox handoffs through a common post-resume hook; UDP ack parsing is stricter (field-based matching).

^{Reviewed by Cursor Bugbot for commit f763c6e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

✱ Stainless preview builds for hypeman

This PR will update the hypeman SDKs with the following commit message.

feat: Add fork mailbox payload API

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ hypeman-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

✅ hypeman-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@84994f2dccb63780d86f57aee40d97431884c7a6

✅ hypeman-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ✅

npm install https://pkg.stainless.com/s/hypeman-typescript/92db82215c08c8aff3f5024fd90669896d652687/dist.tar.gz

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-06-02 21:19:39 UTC

[firetiger-agent]

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

PRs in the kernel, infra, hypeman, and hypeship repos. kernel is a ~mono repo with many logical services underneath, ensure to focus on the implicated service for the PR

Reason: PR repository cannot be determined from provided information; please confirm this is in the kernel, infra, hypeman, or hypeship repo to enable automatic deploy monitoring.

To monitor this PR anyway, reply with @firetiger monitor this.

[rgarcia]

blocking on a few maintainability/design issues:

• lib/instances/fork.go:50 and lib/instances/snapshot.go:390 only gate mailbox usage on standby + running target, but lib/instances/fork_mailbox.go:225 assumes a Firecracker-style raw memory snapshot file and fixed mailbox offsets. Non-Firecracker standby forks can accept mailbox requests and fail later inside restore. Please make this an explicit capability/hypervisor check before fork work begins, so the API rejects unsupported mailbox forks at the boundary.

• lib/instances/fork_mailbox.go:209 duplicates the open/stat/mmap/find/write/cache logic already in lib/instances/guest_resume_network.go:186. This is the same mailbox-frame operation with a different layout. Please push the common primitive into lib/mailbox with layout config, instead of maintaining two snapshot-memory patchers that can drift. Ideally the fork path should also preflight all requested markers before writing any payloads, so multi-mailbox patching is structurally all-or-nothing rather than relying on outer fork cleanup.

• lib/instances/guest_resume_network.go:143 adds mailbox ACK matching as raw substring checks. mailbox=foo can match mailbox=foobar, and any free-form UDP text containing stage=applied is accepted. Since this ACK now gates successful fork restore, please parse the key/value payload and require exact fields for stage and mailbox.

[rgarcia]

1. Suggestion, maybe too early: Unify the two handoffs into one interface + slice (main ask).
   After this PR, restoreInstance prepares two handoffs back-to-back (restore.go:263 and :271) that now implement the identical trio — prepare… / Close() / AfterResume(ctx) error — and the two post-resume teardown blocks (restore.go:332-341 and :343-349) are line-for-line the same recovery (hv.Shutdown → rollbackAdmissionAllocationActive → releaseNetwork → wrapped return). That's the setup for:

type resumeHandoff interface {
    AfterResume(ctx context.Context) error
    Close()
}
handoffs := []resumeHandoff{resumeNetworkHandoff, forkMailboxHandoff}
for _, h := range handoffs { defer h.Close() }
// after resume, in order:
for _, h := range handoffs {
    if err := h.AfterResume(ctx); err != nil { /* one shared teardown */ }
}

Order is preserved (network up before the guest can UDP-ack), so the slice is safe. Collapses the duplicated teardown and makes a third handoff one line. No guest changes needed.

2. Light suggestion: Collapse the duplicated UDP-wait machinery.
   WaitApplied and WaitMailboxApplied (guest_resume_network.go:119 and :140) are methods on the same waiter, reading the same channel, with identical select loops — they differ only in the match predicate. Suggest one wait(ctx, match func(fields map[string]string) bool) and route both through parseUDPAckFields. That also removes the case-handling mismatch between them (one lowercases the whole string, the other only the keys).

3. WriteForkMailboxPayloadAt is a thin wrapper used only by its own test.
   mailbox.go:110 just calls WritePayloadAt(w, ForkLayout, …); production calls WritePayloadAt directly (fork_mailbox.go:272), and the only caller of the wrapper is TestWriteForkMailboxPayloadAt. Suggest deleting it and pointing the test at WritePayloadAt.

4. AckTimeout validation is asymmetric + message is off.
   fork_mailbox.go:99-104: the < 0 check is gated on WaitForAck but the > 30s check isn't, and "must be positive" is misleading since 0 is valid (maps to the 2s default). Suggest aligning the gating and changing the message to "must not be negative."

5. Question on wait_for_ack failure semantics.
   On a missing ack, a fork that resumed successfully gets torn down (restore.go:343). Two asymmetries vs the resume-network path worth confirming are intentional: that path falls back to host-initiated reconfigure (resume_network_handoff.go:81) rather than aborting, and its default timeout is 5s vs 2s here. Since the guest-side consumer of a fork mailbox is caller-implemented, wait_for_ack=true against a guest that doesn't ack will reliably destroy the fork after 2s — fine if that's the intended contract, but worth a note on the API field and a deliberate choice on the 2s vs 5s default.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1778dc2. Configure here.}

[sjmiller609]

Closing this for now because we are dropping the mailbox direction. Leaving the branch intact for reference.