Skip to content

feat(cli): add explicit SSH fallback for remote agent attach - #1483

Merged
khaliqgant merged 8 commits into
mainfrom
feat/cross-node-attach-barry-1449
Aug 11, 2026
Merged

feat(cli): add explicit SSH fallback for remote agent attach#1483
khaliqgant merged 8 commits into
mainfrom
feat/cross-node-attach-barry-1449

Conversation

@khaliqgant

@khaliqgant khaliqgant commented Aug 11, 2026

Copy link
Copy Markdown
Member

Closes the physical-node fallback slice of #1449.

What changed

  • adds agent-relay node agent attach <name> --ssh-host <host> as an explicit SSH fallback
  • reserves --node for the canonical fleet-native attach path
  • executes the existing attach client on the target, preserving view, drive, and passthrough
  • keeps the target broker loopback-only and never copies its API key off-host
  • uses ssh -T for --json so NDJSON stdout is not contaminated by a PTY or login banner
  • accepts an explicit remote --state-dir; otherwise discovers host-managed state, the standard project-local broker state, or one unambiguous managed-node fallback
  • rejects option/shell-bearing SSH targets, shell-quotes all remote data, and fails closed on ambiguous state

Live Barry proof

From Khaliq's Mac, against chief-barry-codex-0811-1440:

  • exact built CLI --ssh-host barry --mode view rendered the live Chief TUI
  • exact built CLI --ssh-host barry --mode drive delivered input and Chief replied NODE_DRIVE_OK
  • --ssh-host barry@barrys-mac-mini.tail9110d0.ts.net --mode view proved SSH-alias/FQDN discovery
  • the diagnostic port-forward was removed; the product fallback needs no broker exposure or copied credential

Verification

  • npm run build:core
  • npm run build:cli
  • 326 attach/CLI regression tests passed
  • focused ESLint and Prettier checks passed
  • git diff --check passed
  • independent review passed the project-local discovery, shell quoting/injection, macOS/Linux discovery, and empty-host behavior

Scope boundary

SSH is the explicit fallback, not the canonical node identity or transport. Fleet-native --node should resolve placement through Relay/Cloud and open an outbound ephemeral terminal stream, with the same path serving physical nodes and Daytona sandboxes without inbound SSH.

@cursor

cursor Bot commented Aug 11, 2026

Copy link
Copy Markdown

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

@coderabbitai

coderabbitai Bot commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

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

The CLI adds --ssh-host support for physical fleet-node attachment through SSH. It validates node and credential options, builds safe remote commands, selects TTY behavior, propagates SSH results, and preserves local attachment behavior.

Changes

Remote node attachment

Layer / File(s) Summary
SSH transport and command execution
packages/cli/src/cli/lib/attach-mode.ts, packages/cli/src/cli/lib/attach-remote-node.ts, packages/cli/src/cli/lib/attach-remote-node.test.ts
Adds attachment modes, node validation, state-directory resolution, shell-safe command construction, SSH execution, TTY handling, error handling, and exit-code propagation.
CLI routing and validation
packages/cli/src/cli/commands/local-agent.ts, packages/cli/src/cli/commands/local-agent.test.ts
Adds --ssh-host, the attachRemote dependency, remote dispatch, broker credential validation, and CLI coverage.
Release and implementation records
CHANGELOG.md, .agentworkforce/trajectories/completed/2026-08/traj_jzmkf8ctib43/*
Records the remote attachment capability, implementation decisions, and verification results.

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

Sequence Diagram(s)

sequenceDiagram
  participant LocalAgentCLI
  participant attachRemoteNode
  participant SSH
  participant RemoteRelay
  LocalAgentCLI->>attachRemoteNode: Request attachment for agent and node
  attachRemoteNode->>SSH: Start quoted remote attach command
  SSH->>RemoteRelay: Execute remote attach command
  RemoteRelay-->>SSH: Return output and exit status
  SSH-->>attachRemoteNode: Propagate process result
  attachRemoteNode-->>LocalAgentCLI: Return attachment status
Loading

Possibly related PRs

Suggested labels: size:L

Suggested reviewers: willwashburn

Poem

A rabbit sends an agent through SSH,
With quoted commands and credentials fresh.
View, drive, or passthrough modes take flight,
While remote exits return just right.
Safe nodes guide the relay tonight.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main change: adding an explicit SSH fallback for remote agent attachment.
Description check ✅ Passed The description clearly covers the change, scope, security behavior, live verification, automated tests, and validation results.
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 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/cross-node-attach-barry-1449

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fd695e70b9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread packages/cli/src/cli/lib/attach-remote-node.ts

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 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 `@CHANGELOG.md`:
- Line 12: Update the changelog heading containing “Unreleased - Minor” to the
exact “## [Unreleased]” form, preserving the new agent-relay entry beneath it.

In `@packages/cli/src/cli/commands/local-agent.ts`:
- Around line 510-511: Update the node-selection logic around options.node to
check for undefined rather than truthiness, so an explicit empty --node value
enters attachRemoteNode and is rejected by remote validation. Add a regression
test covering --node '' and verify it does not start local attachment.
🪄 Autofix

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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 36749f5b-2a45-4ca4-add2-1c07485ed18e

📥 Commits

Reviewing files that changed from the base of the PR and between 542c4df and e3039bc.

📒 Files selected for processing (7)
  • .agentworkforce/trajectories/completed/2026-08/traj_jzmkf8ctib43/summary.md
  • .agentworkforce/trajectories/completed/2026-08/traj_jzmkf8ctib43/trajectory.json
  • CHANGELOG.md
  • packages/cli/src/cli/commands/local-agent.test.ts
  • packages/cli/src/cli/commands/local-agent.ts
  • packages/cli/src/cli/lib/attach-remote-node.test.ts
  • packages/cli/src/cli/lib/attach-remote-node.ts

Comment thread CHANGELOG.md Outdated
Comment thread packages/cli/src/cli/commands/local-agent.ts Outdated

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread packages/cli/src/cli/lib/attach-remote-node.ts
Comment thread packages/cli/src/cli/commands/local-agent.ts Outdated
Comment thread packages/cli/src/cli/lib/attach-remote-node.ts Outdated
@khaliqgant khaliqgant changed the title feat(cli): attach to physical fleet nodes over SSH feat(cli): add explicit SSH fallback for remote agent attach Aug 11, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 `@packages/cli/src/cli/commands/local-agent.ts`:
- Around line 512-513: Update the conflict check in the local-agent command to
detect brokerUrl and apiKey whenever either option was explicitly supplied,
including empty-string values, by checking against undefined rather than
truthiness. Add tests covering --ssh-host combined with each empty broker
option.
🪄 Autofix

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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ab3401ad-b76d-4b38-991f-27d29ecab397

📥 Commits

Reviewing files that changed from the base of the PR and between e3039bc and 14ce3ea.

📒 Files selected for processing (5)
  • CHANGELOG.md
  • packages/cli/src/cli/commands/local-agent.test.ts
  • packages/cli/src/cli/commands/local-agent.ts
  • packages/cli/src/cli/lib/attach-remote-node.test.ts
  • packages/cli/src/cli/lib/attach-remote-node.ts
🚧 Files skipped from review as they are similar to previous changes (3)
  • CHANGELOG.md
  • packages/cli/src/cli/lib/attach-remote-node.test.ts
  • packages/cli/src/cli/commands/local-agent.test.ts

Comment thread packages/cli/src/cli/commands/local-agent.ts Outdated

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 6 files (changes from recent commits).

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

Comment thread packages/cli/src/cli/lib/attach-remote-node.ts Outdated
Comment thread packages/cli/src/cli/lib/attach-remote-node.ts Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 `@packages/cli/src/cli/lib/attach-remote-node.ts`:
- Around line 62-66: Update the broker PID discovery command in attachRemoteNode
to request and propagate the broker’s own PID rather than ppid, so the
subsequent state-directory lookup uses broker_pids directly. Preserve the
existing command matching and filtering logic.
🪄 Autofix

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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 49ec5b78-bf2a-4a8c-8106-8e105a1abfd7

📥 Commits

Reviewing files that changed from the base of the PR and between 3b74d2e and 7fda94f.

📒 Files selected for processing (4)
  • packages/cli/src/cli/commands/local-agent.test.ts
  • packages/cli/src/cli/commands/local-agent.ts
  • packages/cli/src/cli/lib/attach-remote-node.test.ts
  • packages/cli/src/cli/lib/attach-remote-node.ts
🚧 Files skipped from review as they are similar to previous changes (3)
  • packages/cli/src/cli/lib/attach-remote-node.test.ts
  • packages/cli/src/cli/commands/local-agent.test.ts
  • packages/cli/src/cli/commands/local-agent.ts

Comment thread packages/cli/src/cli/lib/attach-remote-node.ts Outdated

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 4 files (changes from recent commits).

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

Comment thread packages/cli/src/cli/lib/attach-remote-node.ts Outdated

@barryollama barryollama left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent exact-head review complete at 986b90e. All 11 review threads are resolved; latest-head checks are terminal with 36 passing and 5 change-scope skips; focused remote tests, the 333-test attach/local-agent suite, CLI/core builds, lint, formatting, and diff checks passed. Approving. No merge performed.

@khaliqgant
khaliqgant merged commit ed8144c into main Aug 11, 2026
41 checks passed
@khaliqgant
khaliqgant deleted the feat/cross-node-attach-barry-1449 branch August 11, 2026 17:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants