fix(snap): recover gateway after Docker connection

[elezar]

Summary

Recover the Snap gateway when the Docker interface becomes available after installation, then make the release canary wait for bounded readiness and retain Snap diagnostics on failure.

Related Issue

Closes #2055.

Changes

• Add a Docker interface connection hook that restarts the Snap gateway without making ordinary startup Docker-dependent.
• Wait up to 30 seconds for Snap gateway readiness in Release Canary.
• Add failure-only Snap service, connection, journal, log, and listener diagnostics.
• Support manual Snap-canary dispatch when a successful Release Dev artifact run ID is supplied.
• Document the connection lifecycle and update the release-canary skill.

Testing

• mise run pre-commit passes
• Hook packaging assertion
• Local ARM64 Ubuntu VM: original artifact reproduced the connection refusal
• Local ARM64 Ubuntu VM: hook-enabled artifact passed 5/5 attempts with a 30-second readiness bound
• Unit tests added/updated
• E2E tests added/updated (will run through the unchanged Release Canary artifact flow)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-2866.docs.buildwithfern.com/openshell

[github-actions]

Label test:e2e applied for 0fce474. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[johntmyers]

gator-agent

PR Review Status

This focused fix implements the validated Snap gateway lifecycle work in #2055. The initial code review found no blocking defects; required E2E dispatch is blocked because the E2E Label Help bot requires rerunning current-head run 32856962208, while the sandbox policy denies that exact REST action.

Action required: a maintainer can click Re-run all jobs on run 32856962208, or the sandbox policy owner can allow POST /repos/NVIDIA/OpenShell/actions/runs/32856962208/rerun for /usr/bin/gh.

Blocking findings:

• No code-review blockers. Test dispatch remains a process blocker.

Carried findings:

• None

Non-blocking suggestions:

• GATOR-0fce474c-01: Consider adding one sentence to the Fern Snap installation page explaining that connecting the Docker plug automatically restarts the gateway so driver detection reruns.

Gator metadata

• Validation: Focused Snap lifecycle bug fix implementing the reproduced and scoped issue #2055
• Docs: Existing Fern installation commands remain correct; the restart-lifecycle detail is a non-blocking documentation suggestion
• Checks: Current-head DCO, Branch Checks, and Helm gate are green; the required E2E rerun is not queued
• E2E: test:e2e applied; E2E Label Help requires Re-run all jobs on current-head run 32856962208, but sandbox policy denied dispatch
• Head SHA: 0fce474c127057164e477111256fd2ceaa866a08
• Base SHA: 91a6409ef2277d7ba781ed441ebac108ab93d354
• Merge base SHA: 91a6409ef2277d7ba781ed441ebac108ab93d354
• Patch ID: 55f0d379eade47aa3911ea6ccbd128b22ae8d1eb
• Gator payload: 7
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:blocked
• Blocked reason: test_dispatch_required

[johntmyers]

gator-agent

Blocked

Gator's feedback ledger confirms that current head d3a417e422ba9830bf43402b2f008473be1da2b4 is rebase-equivalent to the reviewed head, with the same patch ID and no blocking code findings. The required E2E workflow is running for this head.

The required Branch Checks gate is blocked by an infrastructure failure: the macOS job exited while mise was installing Rust 1.95.0, before Clippy or any PR code ran. Linux lint and tests passed.

Next action: a maintainer should rerun the failed jobs for workflow run 32969912414. Gator will continue once Branch Checks is green and the current-head E2E run completes.

Gator metadata

• Head SHA: d3a417e422ba9830bf43402b2f008473be1da2b4
• Patch ID: 55f0d379eade47aa3911ea6ccbd128b22ae8d1eb
• Gator payload: 7
• Review mode: already_reviewed
• Checks: E2E running; Branch Checks failed during macOS Rust toolchain installation
• Next state: gator:blocked
• Blocked reason: ci_infrastructure_rerun_required

[johntmyers]

gator-agent

PR Review Status

The current head is rebase-equivalent to the already reviewed patch, with the same patch ID and no open blocking findings. Branch Checks and the required E2E workflow are running for this exact head, while Helm Lint is green.

Blocking findings:

• No code-review blockers remain.

Carried findings:

• None

Gator metadata

• Validation: Focused Snap lifecycle bug fix implementing issue bug(snap): gateway startup races interface connections #2055
• Docs: Existing Fern installation flow remains correct; the prior documentation note is non-blocking
• Checks: Current-head Branch Checks run 33519404557 is in progress; Helm Lint is green
• E2E: test:e2e is applied; current-head Branch E2E Checks run 33519405208 is in progress
• Head SHA: f1703254bb1f7605136734420f990fd00f3dfcf6
• Base SHA: f7180c0fd63a89249fa3a22b04689d6702d71886
• Merge base SHA: f7180c0fd63a89249fa3a22b04689d6702d71886
• Patch ID: 55f0d379eade47aa3911ea6ccbd128b22ae8d1eb
• Gator payload: 7
• Review mode: already_reviewed
• Previous reviewed SHA: 9fdcd52932e7dbe922abbe3280500ce1eb139ebe
• Review budget exhausted: yes
• Maintainer decision required: no
• Next state: gator:watch-pipeline

[johntmyers]

gator-agent

PR Review Status

The current head is rebase-equivalent to the already reviewed patch, with the same patch ID and no open blocking findings. Thanks @alangou; I verified that your approval applies to this current head. Branch Checks and the required E2E workflow are still running, while Helm Lint is green.

Blocking findings:

• No code-review blockers remain.

Carried findings:

• None

Gator metadata

• Validation: Focused Snap lifecycle bug fix implementing issue bug(snap): gateway startup races interface connections #2055
• Docs: Existing Fern installation flow remains correct; the prior documentation note is non-blocking
• Checks: Current-head Branch Checks run 33731662620 is in progress; Helm Lint is green
• E2E: test:e2e is applied; current-head Branch E2E Checks run 33731663862 is in progress
• Head SHA: 80c70725866c578b30d5694493485cdc0936e6e5
• Base SHA: 64a858dadebc23cf715bc4292c8c4970f2e9a3d2
• Merge base SHA: 64a858dadebc23cf715bc4292c8c4970f2e9a3d2
• Patch ID: 55f0d379eade47aa3911ea6ccbd128b22ae8d1eb
• Gator payload: 8
• Review mode: already_reviewed
• Previous reviewed SHA: f1703254bb1f7605136734420f990fd00f3dfcf6
• Review budget exhausted: yes
• Maintainer decision required: no
• Next state: gator:watch-pipeline

[johntmyers]

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Final status: The focused Snap gateway lifecycle fix was reviewed with no blocking findings, approved by a maintainer, and its required Branch Checks, Helm Lint, and E2E gates completed successfully before merge.

I removed the active gator:* label because there is nothing left for gator to monitor on this PR.

Gator metadata

• Head SHA: 80c70725866c578b30d5694493485cdc0936e6e5
• Gator payload: 8
• Previous state: gator:watch-pipeline
• Final state: merged