feat(onboard): stream machine-readable progress events

[HOYALIM]

Summary

Add an opt-in nemoclaw onboard --events=jsonl observer for automation consumers such as the Brev onboarding UI. The mode emits versioned, redacted events from the existing onboarding FSM while keeping normal human output on stderr; default onboarding behavior is unchanged.

Related Issue

Refs #6403

Changes

• Add a stable version 1 JSONL envelope over the canonical onboarding machine-event stream.
• Keep the observer read-only and best-effort: a closed output pipe disables observation without changing onboarding control flow.
• Expose the mode only on the canonical onboard command and document schema evolution, redaction, and non-goals.
• Add behavior coverage for envelope stability, secret redaction, stdout purity, broken observers, flag parsing, and deprecated aliases.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — vitest run src/lib/onboard/machine/events.test.ts src/lib/onboard/machine/jsonl-events.test.ts src/lib/onboard/command-support.test.ts test/cli/onboard-compatibility.test.ts test/stdout-guard.test.ts (31 passed)
• Applicable broad gate passed — npm run typecheck:cli
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Ho Lim subhoya@gmail.com

Summary by CodeRabbit

• New Features

  • Added --events=jsonl to nemoclaw onboard.
  • When enabled, emits a read-only, versioned JSONL stream of canonical onboarding-machine events on stdout (one object per line) with secret values redacted; progress remains on stderr. Closing a pipe/backpressure disables event emission without cancelling onboarding.

• Documentation

  • Documented the schemaVersion envelope, forward-compatibility expectations, and payload redaction rules.

• Tests

  • Added CLI help/flag forwarding checks, confirmed setup alias rejects --events=jsonl, and added stream/backpressure/pipe-disconnect coverage.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Onboarding now supports --events=jsonl, streaming redacted, versioned machine events to stdout while human progress uses stderr. The onboard command conditionally enables this mode, preserves normal behavior otherwise, and documents pipe-handling semantics.

Changes

Onboard JSONL event streaming

Layer / File(s)	Summary
JSONL event serialization and observation src/lib/onboard/machine/jsonl-events.ts, src/lib/onboard/machine/jsonl-events.test.ts	Adds a versioned event envelope, redaction, newline-delimited output, observer lifecycle management, stderr progress routing, and broken-pipe handling with tests.
CLI flag exposure and command integration src/lib/onboard/command-support.ts, src/commands/onboard.ts, test/cli/onboard-compatibility.test.ts, docs/reference/commands.mdx	Adds the onboard-only --events=jsonl flag, routes JSONL mode through the event-stream wrapper, verifies setup compatibility behavior, and documents the stream contract.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant OnboardCliCommand
  participant withOnboardJsonlEventStream
  participant OnboardMachine
  participant stdout
  participant stderr
  OnboardCliCommand->>withOnboardJsonlEventStream: run with --events=jsonl
  withOnboardJsonlEventStream->>OnboardMachine: observe onboarding events
  OnboardMachine->>stdout: write redacted JSONL event
  withOnboardJsonlEventStream->>stderr: route human progress output
  withOnboardJsonlEventStream-->>OnboardCliCommand: return onboarding result

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding machine-readable event streaming for onboard.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / medium confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 2 blockers · 1 warning · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported 2 more blockers, the same number of warnings, the same number of suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, inference-routing, network-policy, onboard-repair, onboard-resume, state-backup-restore, upgrade-stale-sandbox

3 optional E2E recommendations

• ollama-auth-proxy
• onboard-negative-paths
• bootstrap-install-smoke

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover JSONL stdout routing for the Ollama CLI pull

• Location: src/lib/inference/ollama/proxy.ts:574
• Category: tests
• Problem: The changed CLI-pull path redirects inherited stdout when JSONL owns stdout, but no checked-in proxy test invokes this path in JSONL and ordinary modes.
• Impact: A later change can bypass the JSONL stdout guard for Ollama pull progress and corrupt the machine-readable event stream without a focused regression failure.
• Recommendation: Add a proxy unit test that stubs `spawnSync`, invokes the CLI-pull path with and without `withStdoutRedirectedToStderr`, and verifies the two stdio values.
• Verification: Inspect the proxy test inventory for a test that reaches `pullOllamaModelViaCli` and asserts its `spawnSync` `stdio` option in both modes.
• Test coverage: A unit test must assert that Ollama CLI pull uses `["inherit", process.stderr, "inherit"]` during JSONL observation and `"inherit"` otherwise.
• Evidence: `pullOllamaModelViaCli` changes `stdio` at src/lib/inference/ollama/proxy.ts:574. The changed test inventory has stdout-routing tests for runner, OpenShell, installer, and Docker prebuild, but no proxy test reaches the Ollama CLI-pull path.

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/onboard/machine/jsonl-events.ts`:
- Around line 26-30: Update writeStdoutLine to avoid synchronous stdout writes
blocking the onboarding machine-event listener: use a queued, nonblocking
transport that disables observation or drops output when backpressure or write
errors occur. Preserve event-line delivery when stdout is available and add
coverage for a stalled consumer.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 322fa0a6-1cb3-416c-89b4-529a47c8169f

📥 Commits

Reviewing files that changed from the base of the PR and between b634f01 and 61abf6e.

📒 Files selected for processing (7)

• docs/reference/commands.mdx
• src/commands/onboard.ts
• src/lib/onboard/command-support.test.ts
• src/lib/onboard/command-support.ts
• src/lib/onboard/machine/jsonl-events.test.ts
• src/lib/onboard/machine/jsonl-events.ts
• test/cli/onboard-compatibility.test.ts

[wscurran]

✨ Thanks for the feature, @HOYALIM. Adding a stable machine-readable event stream for onboarding automation is a great improvement. Ready for maintainer review.

---

Related open issues:

• #6403 Define a stable machine-readable onboarding and progress protocol

[apurvvkumaria]

Reviewed exact head 009cabb on current main. The JSONL observer remains read-only and best-effort, stdout backpressure and write failures cannot stall or alter onboarding, and credential-bearing event fields stay bounded/redacted. Focused validation passed: CLI build, 31 onboarding/JSONL/CLI tests, and CLI typecheck. Automated advisors report 0 blockers, 0 warnings, and 0 suggestions; no unresolved review threads.

[laitingsheng]

Verified against the linked issue and project criteria at head 215dab4c:

• Mechanism — the observer captures the original stdout.write before withStdoutRedirectedToStderr swaps it, so versioned JSONL reaches stdout while human progress is routed to stderr. Ordering confirmed correct.
• Event flow — the onboarding FSM emits through emitOnboardMachineEvent in onboard-session.ts and runtime.ts; the observer registers as a listener, so --events=jsonl produces real output rather than an empty stream.
• Redaction — model, sandboxName, metadata, and error all pass through redactUrl / redactSensitiveText / redactForLog; only credential environment-variable names are exposed, matching the documented contract, and tests assert no secret survives serialisation.
• No second state machine — reuses the existing event bus; observation is read-only and best-effort, and a closed pipe or sustained backpressure disables observation without altering onboarding control flow.
• Alias isolation — --events is exposed only on the canonical onboard command; setup and setup-spark build flags without it, and a test asserts the alias rejects the flag.
• Reliability — asynchronous write path with error-handler lifetime tracking; the closed-stdout asynchronous-write-failure path is covered.
• Docs — usage line and the --events=jsonl reference section updated with envelope, schema-evolution, and redaction notes.
• Hygiene — no stray markers, SPDX headers present, the new file is co-located beside events.ts, and the spelling register is consistent with the repository.
• Discussion — the single CodeRabbit finding (synchronous stdout write) was addressed and re-confirmed resolved; no outstanding threads.
• CI — all required checks are green on the head SHA, and the PR Review Advisor reports zero findings at 215dab4c.

[apurvvkumaria]

Exact-head review at 215dab4 found a correctness blocker. JSONL purity only intercepts process.stdout.write, while reachable OpenShell and Ollama child processes inherit fd 1. A real child can therefore emit raw progress before the JSON event, and a closed JSONL consumer can EPIPE that child and change onboarding behavior. Route child stdout away from the machine-readable stream and add a real-child regression test proving stdout remains JSONL-only and consumer closure does not alter child/onboard success. Persisted sessionId and credentialEnv also need structural sanitization before emission so untrusted resumed state cannot be echoed verbatim.

[apurvvkumaria]

Addressed the requested JSONL hardening in two append-only commits, with original-author credit preserved:

• b1d39e0 validates persisted session IDs and credential environment identifiers before serialization.
• 349c96e redirects inherited child fd 1 to the human-output channel while JSONL owns stdout, including direct installer, BuildKit, Ollama, and central runner paths.

Validation: independent audit PASS; 77 focused tests PASS; CLI typecheck PASS; Biome and diff checks PASS. Both commits are DCO-signed and GitHub Verified. I will keep the exact head under CI/advisor monitoring before clearing the superseded review state.

[apurvvkumaria]

Follow-up 4f6ac24 removes the test-helper conditional flagged by the codebase growth guard while preserving both open-stdout and closed-stdout child-process regressions. The focused 22-test file, conditional scan, CLI typecheck, Biome, and diff checks pass; the commit is signed, credited, and GitHub Verified. I approved the exact-head fork workflows so CI can proceed.

[apurvvkumaria]

Maintainer follow-up on exact head 04cec7677:

• fixed the current-head CLI typecheck failure by awaiting the async stdout-routing guard in the OpenShell client test;
• added regression coverage for the production default Docker builder (without injecting buildImage), proving child stdout is inherited normally and redirected to stderr while JSONL owns stdout;
• preserved Ho Lim's original-author credit in the signed/DCO commit.

Validation: 42 focused tests pass, CLI typecheck passes, Biome is clean, git diff --check is clean, and an independent audit repeated the focused suite three times (126/126). The exact-head fork workflows have been approved once and are now running.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

[apurvvkumaria]

Re-reviewed at exact refreshed head f18acfc. The prior blockers are addressed: persisted sessionId and credentialEnv values are structurally validated before serialization; child fd 1 is isolated across the shared runner, OpenShell, Ollama, installer, and BuildKit paths; and real-child regressions prove JSONL stdout purity plus closed-consumer independence. The branch merged current main cleanly with a Verified DCO commit, 97 focused tests pass, and pre-push type checks pass. The remaining Ollama-specific assertion is test-depth only and safe fix-forward.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.