feat(cli): set up managed remote Runtime Hosts

[M4n5ter]

English

Summary

Add one idempotent Host-side setup flow for managed remote Runtime Hosts. A released CLI can now:

• copy its exact self-contained package into a Maka-owned persistent deployment
• install or repair the existing Linux systemd user service
• replace the credential for one stable Client identity instead of accumulating credentials
• verify the authenticated loopback Runtime Host before returning framed connection facts
• remove the managed deployment during service uninstall while retaining the State Root

This is the CLI contract that the later Desktop Add Computer wizard will invoke through interactive system SSH. Desktop UI, version switching, automatic updates, and macOS service support remain outside this PR.

Fixes #3229

Verification

• npm run build:test
• npm run typecheck
• npm --workspace @maka/runtime-host test — 979 passed
• npm --workspace maka-agent test — 285 passed
• Biome check and git diff --check
• Real Linux systemd user-service test with a packed release artifact:
  • setup completed twice and retained exactly one active credential for the stable principal
  • a new local Client authenticated through an SSH tunnel after the setup SSH session ended
  • uninstall stopped and removed the service and managed package while retaining the State Root and access authority

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: OpenAI Codex assisted with implementation, tests, documentation, and validation under the maintainer's direction

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

简体中文

摘要

为托管的远程 Runtime Host 增加一个幂等的 Host 侧 setup 流程。发布版 CLI 现在可以：

• 将当前精确的自包含 package 复制到 Maka-owned 的持久 deployment
• 安装或修复现有 Linux systemd user service
• 替换稳定 Client identity 的 credential，而不是不断累积 credential
• 返回带 framing 的连接信息前，验证经过认证的 loopback Runtime Host
• 卸载 service 时删除托管 deployment，同时保留 State Root

这是后续 Desktop 添加电脑 向导通过交互式 system SSH 调用的 CLI 契约。Desktop UI、版本切换、自动更新和 macOS service 支持不属于本 PR。

修复 #3229

验证

• npm run build:test
• npm run typecheck
• npm --workspace @maka/runtime-host test — 979 项通过
• npm --workspace maka-agent test — 285 项通过
• Biome check 与 git diff --check
• 使用打包 release artifact 完成真实 Linux systemd user service 验证：
  • 连续执行两次 setup 后，稳定 principal 只有一个 active credential
  • setup SSH session 结束后，新 Local Client 仍可通过 SSH tunnel 完成认证
  • uninstall 会停止并删除 service 和托管 package，同时保留 State Root 与 access authority

AI 使用

OpenAI Codex 在维护者指导下协助实现、测试、文档与验证；权威选择见英文部分

检查清单

• 测试覆盖新增行为，并会在缺少实现时失败
• lint、format、typecheck 与受影响测试均在本地通过
• 本 PR 包含上文已说明的行为变化

[coderabbitai]

Warning

Review limit reached

@M4n5ter, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 11 minutes

Limit details: You’ve used all 3 included reviews currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 98e58cd0-0225-4b05-b70e-9140ea78c5e9

📥 Commits

Reviewing files that changed from the base of the PR and between ba5a60b and 05ddec0.

📒 Files selected for processing (3)

• packages/cli/src/__tests__/runtime-host-service-manager.test.ts
• packages/cli/src/runtime-host-managed-deployment.ts
• packages/cli/src/runtime-host-service-manager.ts

📝 Walkthrough

Problem solved

This PR adds an idempotent Linux CLI setup transaction for managed remote Runtime Hosts. It:

• Copies the exact CLI package into persistent Maka-owned storage.
• Installs and verifies the systemd user service.
• Replaces credentials for one stable Client identity.
• Verifies authenticated loopback connectivity.
• Returns framed, machine-readable connection facts.
• Removes the managed deployment during uninstall while retaining the State Root.
• Preserves retry safety through locking, staging, validation, rollback, and cleanup.

The setup contract supports the future Desktop Add Computer flow. It does not add Desktop UI, automatic updates, version switching, macOS or Windows service support, Node.js installation, sudo usage, or SSH configuration changes.

Source of truth and solution scope

The PR extends the existing CLI, Runtime Host access-authority, service-management, and protocol paths. It does not create a parallel authentication or service-management system.

The new setup command composes existing service and access-authority operations. The managed deployment path preserves the exact package identity, supports safe rollback, and removes only managed files during uninstall. Canonical WebSocket-path validation is shared across setup, service management, serving, SSH tunneling, and listener code.

The solution is the smallest coherent implementation supported by the provided change summary. Each added orchestration, deployment validation, framing, credential replacement, and test seam supports a required transaction or failure boundary.

Simplification and deletion assessment

No safe deletion is evident. The tests cover convergence, credential replacement, deployment cleanup, output redaction, malformed frames, path validation, service-install failure, and State Root retention. Removing these tests or their supporting seams would weaken regression coverage.

Shared option parsing and canonical WebSocket-path validation reduce duplicated logic. Further dependency-injection simplification can be considered after broader usage. This is optional follow-up work.

Validation and risks

The change summary reports tests for:

• Setup command parsing and framed output.
• Repeated setup convergence.
• Credential replacement and remote-owner authorization.
• Authenticated WebSocket replacement behavior.
• Malformed frame and oversized error handling.
• Canonical WebSocket-path validation.
• Exact managed deployment paths and version cleanup.
• Package cleanup after service-install failure.
• Managed deployment removal.
• State data retention.

The final status of required checks is unverified. The requested repository diff produced no output, so it provides no additional validation evidence.

Complexity delta

The PR adds:

• A setup transaction with progress, completion, and error phases.
• File-lock serialization.
• Managed deployment staging, path validation, rollback, and uninstall handling.
• Schema-validated setup frames with bounded fields and sequencing.
• The access.credential.replace protocol and authority operation.
• Public CLI options, result types, deployment APIs, and frame APIs.
• Dependency-injection seams and integration-test maintenance.

It removes or consolidates:

• Dependence on the temporary npx cache after setup.
• Separate credential replacement logic for the managed setup path.
• Repeated WebSocket-path validation logic.
• Newly created deployment files after setup failure.
• Managed package files during uninstall while retaining State Root data.

The PR increases local implementation complexity. The added states, validation, and public surface are necessary for an idempotent, retry-safe, machine-readable transaction. The available evidence supports that total maintenance complexity stays justified, but not that it decreases.

Review-relevant risks

• The CLI gains a user-visible runtime-host setup command and new public APIs. Public behavior and contract changes require independent human review under repository policy.
• Credential replacement revokes prior active credentials for the same principal. This security change requires independent human review under repository policy.
• Persistent package deployment and systemd user-service management change release and operational behavior. These changes require independent human review under repository policy.
• Successful setup frames return credentials. Strict loopback and WebSocket-path validation change security and protocol behavior. These changes require independent human review under repository policy.

The person performing the merge reviews the final diff. A maintainer makes the final determination.

Walkthrough

The PR adds an idempotent Linux Runtime Host setup command. It manages persistent package deployment, service installation, credential replacement, authenticated verification, structured output, canonical WebSocket paths, cleanup, tests, and documentation.

Changes

Runtime Host setup

Layer / File(s)	Summary
Credential replacement protocol packages/runtime-host/src/protocol/*, packages/runtime-host/src/server/*, packages/cli/src/runtime-host-access-command.ts, packages/runtime-host/src/__tests__/*	Adds access.credential.replace, replaces credentials per principal, revokes prior credentials, and wires the operation through the host kernel and CLI.
Setup result framing packages/runtime-host/src/client/*, packages/cli/src/runtime-host-setup-command.ts, packages/cli/src/__tests__/runtime-host-setup.test.ts	Adds validated progress, completion, and error frames with bounded fields, encoded output, and loopback endpoint checks.
Managed package deployment and service lifecycle packages/cli/src/runtime-host-managed-deployment.ts, packages/cli/src/runtime-host-service-manager.ts, packages/cli/src/runtime-host-service-management-command.ts, packages/cli/src/__tests__/runtime-host-service-manager.test.ts	Adds service-owned deployment roots, path validation, persistent managed CLI handling, cleanup, and uninstall integration.
Setup command and documentation packages/cli/src/runtime-host-cli.ts, packages/cli/src/cli-core.ts, packages/cli/src/runtime-host-setup-command.ts, packages/cli/src/__tests__/runtime-host-setup.test.ts, docs/*, packages/cli/README*	Adds setup parsing, locking, deployment and service verification, failure handling, integration tests, and Linux setup instructions in English and Chinese.
Canonical WebSocket path validation packages/runtime-host/src/protocol/websocket-path.ts, packages/runtime-host/src/client/*, packages/runtime-host/src/server/websocket-listener.ts, packages/cli/src/runtime-host-cli.ts, packages/cli/src/runtime-host-service-manager.ts, apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx	Defines one canonical path validator and applies it to Runtime Host clients, listeners, CLI commands, service configuration, and desktop settings.

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: 🟠 High · up to ba5a6

The setup flow can revoke an existing client credential when verification fails, leaving the host inaccessible, and a later service-install path can lose the deployment cleanup reference so uninstall leaves managed files behind. Merge should be blocked until both rollback and cleanup failures are fixed and covered by regression tests.

Sequence Diagram(s)

sequenceDiagram
  participant MakaCli
  participant ManagedDeployment
  participant RuntimeHostService
  participant RuntimeHostAccessAuthority
  participant RuntimeHostWebSocket
  MakaCli->>ManagedDeployment: prepare service-owned package deployment
  MakaCli->>RuntimeHostService: install and verify managed service
  MakaCli->>RuntimeHostAccessAuthority: replace principal credential
  MakaCli->>RuntimeHostWebSocket: verify authenticated connection
  MakaCli-->>MakaCli: emit completion or error frame

Loading

Possibly related PRs

• maka-agent/maka-agent#3205: Provides the Runtime Host service-management foundation extended by this setup flow.
• maka-agent/maka-agent#3169: Both changes extend CLI dispatch in cli-core.ts.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The implementation covers #3229's setup contract, managed deployment, service convergence, credential replacement, framed results, verification, failure safety, and uninstall retention.
Out of Scope Changes check	✅ Passed	The changes stay within #3229, including CLI setup, Runtime Host access, service safety, protocol validation, tests, and documentation.
Ai Use Disclosure	✅ Passed	The PR selects generative use, names OpenAI Codex and its scope, and both introduced commits contain the standalone trailer Generated-by: Codex.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding CLI setup for managed remote Runtime Hosts.
Description check	✅ Passed	The description follows the template, explains the behavior and scope, lists verification results, records AI use, and completes the checklist.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/runtime-host-remote-setup

---

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

[qodo-code-review]

PR Summary by Qodo

Add managed remote Runtime Host setup transaction

✨ Enhancement 🧪 Tests 📝 Documentation 🕐 40+ Minutes

AI Description

• Adds idempotent Linux CLI setup for managed, persistent remote Runtime Hosts.
• Rotates stable Client credentials and verifies authenticated loopback connectivity before
 returning connection facts.
• Removes managed deployments on uninstall while retaining Runtime Host state and project data.

Diagram

graph TD
  A["CLI setup"] -->|"orchestrates"| B["Setup transaction"] -->|"copies release"| C["Managed package"] -->|"launches"| D["systemd service"] -->|"serves endpoint"| F["Loopback verifier"] -->|"emits result"| G["Setup frames"]
  B -->|"replaces identity"| E["Access authority"] -->|"issues credential"| F

Loading

High-Level Assessment

The dedicated, locked Host-side transaction is the strongest approach for SSH-driven onboarding because it centralizes rollback, exact-package persistence, credential rotation, readiness verification, and machine-readable output. Composing the existing service and access commands from Desktop was considered but would expose interruption boundaries and make credential delivery and recovery less reliable.

Files changed (21) +1253 / -21

Enhancement (12) +901 / -14

cli-core.tsDispatch and describe Runtime Host setup +29/-0

Dispatch and describe Runtime Host setup

• Adds setup help text and routes parsed setup commands to the new coordinator using the invoking package root and version.

packages/cli/src/cli-core.ts

runtime-host-access-command.tsAdd stable-principal credential replacement client +36/-0

Add stable-principal credential replacement client

• Introduces a local-owner helper that requests credential replacement, consumes the one-time delivery, and returns connection metadata with the new secret.

packages/cli/src/runtime-host-access-command.ts

runtime-host-cli.tsParse managed Runtime Host setup options +93/-1

Parse managed Runtime Host setup options

• Adds the setup command model and validates principal IDs, Client presets, project roots, loopback port settings, WebSocket paths, and JSON output selection.

packages/cli/src/runtime-host-cli.ts

runtime-host-managed-deployment.tsManage atomic versioned CLI deployments +207/-0

Manage atomic versioned CLI deployments

• Copies and validates self-contained releases into a Maka-owned data directory through temporary staging and atomic rename. Supports retry cleanup, selective rollback, platform-aware paths, and complete managed deployment removal.

packages/cli/src/runtime-host-managed-deployment.ts

runtime-host-service-management-command.tsRemove managed package during service uninstall +18/-3

Remove managed package during service uninstall

• Extends uninstall to delete the managed deployment after service removal while preserving the State Root. Exports platform backend creation for reuse by setup and reports deployment-specific failures.

packages/cli/src/runtime-host-service-management-command.ts

runtime-host-setup-command.tsImplement the idempotent setup transaction +307/-0

Implement the idempotent setup transaction

• Coordinates environment checks, exact-package deployment, service installation or repair, stable credential replacement, authenticated loopback verification, and framed output under a file lock. Rejects implicit version changes and rolls back newly copied packages when service installation fails.

packages/cli/src/runtime-host-setup-command.ts

index.tsExport setup framing utilities +7/-0

Export setup framing utilities

• Exposes setup frame types, prefix, encoder, and decoder through the Runtime Host client entry point.

packages/runtime-host/src/client/index.ts

setup-frame.tsDefine validated machine-readable setup frames +115/-0

Define validated machine-readable setup frames

• Introduces bounded, versioned progress, completion, and error frames encoded as prefixed base64url records. Decoding strictly validates fields and only accepts loopback WebSocket completion endpoints.

packages/runtime-host/src/client/setup-frame.ts

access-authority.tsAdd credential replacement protocol operation +14/-0

Add credential replacement protocol operation

• Defines access.credential.replace with the same validated authority inputs and one-time credential delivery result as issuance.

packages/runtime-host/src/protocol/access-authority.ts

access-authority.tsReplace active credentials by principal +65/-10

Replace active credentials by principal

• Implements atomic replacement of active credentials matching a principal kind and ID while retaining unrelated and historical credentials. Publishes revocations for replaced credentials after durable persistence.

packages/runtime-host/src/server/access-authority.ts

host-kernel.tsDispatch credential replacement requests +3/-0

Dispatch credential replacement requests

• Connects the new replacement protocol operation to the configured Runtime Host access authority.

packages/runtime-host/src/server/host-kernel.ts

operation-dispatcher.tsHandle unavailable credential replacement +7/-0

Handle unavailable credential replacement

• Adds the standard operation-unavailable response when a Runtime Host has no access authority configured.

packages/runtime-host/src/server/operation-dispatcher.ts

Tests (5) +286 / -3

runtime-host-operator-command.test.tsVerify credential replacement operation grants +2/-0

Verify credential replacement operation grants

• Confirms remote-owner presets cannot replace credentials while the local-owner authority includes the replacement operation.

packages/cli/src/tests/runtime-host-operator-command.test.ts

runtime-host-service-manager.test.tsTest parsing the managed setup command +16/-0

Test parsing the managed setup command

• Adds coverage for setup command recognition, required pairing fields, preset selection, and JSON output mode.

packages/cli/src/tests/runtime-host-service-manager.test.ts

runtime-host-setup.test.tsTest setup convergence, framing, and rollback +240/-0

Test setup convergence, framing, and rollback

• Covers repeated idempotent setup, exact version deployment, verified credential pairing, abandoned staging cleanup, malformed frame rejection, uninstall cleanup, and rollback after service installation failure.

packages/cli/src/tests/runtime-host-setup.test.ts

authenticated-websocket.test.tsTest live credential replacement semantics +27/-3

Test live credential replacement semantics

• Verifies replacement disconnects the old authenticated Client, admits the replacement credential, and leaves the new credential revocable.

packages/runtime-host/src/tests/authenticated-websocket.test.ts

websocket-listener.test.tsExtend access authority test double +1/-0

Extend access authority test double

• Adds the credential replacement method required by the expanded access authority contract.

packages/runtime-host/src/tests/websocket-listener.test.ts

Documentation (4) +66 / -4

runtime-host-remote-access.mdDocument one-command Linux Runtime Host setup +23/-2

Document one-command Linux Runtime Host setup

• Adds the managed setup workflow, stable principal guidance, preset selection, and uninstall retention behavior. Distinguishes this workflow from manual persistent installation.

docs/runtime-host-remote-access.md

runtime-host-remote-access.zh-CN.mdDocument managed setup in Simplified Chinese +18/-2

Document managed setup in Simplified Chinese

• Adds the translated Linux setup command, credential rotation behavior, managed package lifecycle, and retained-data guarantees.

docs/runtime-host-remote-access.zh-CN.md

README.mdAdd remote Runtime Host setup guidance +13/-0

Add remote Runtime Host setup guidance

• Documents installing a persistent Host from an exact released package and safely rotating a Client credential by rerunning setup.

packages/cli/README.md

README.zh-CN.mdAdd translated remote setup guidance +12/-0

Add translated remote setup guidance

• Documents the managed release installation and credential rotation workflow in Simplified Chinese.

packages/cli/README.zh-CN.md

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 690905ed-1433-4a9c-bc5d-0b888dd22bc2

📥 Commits

Reviewing files that changed from the base of the PR and between 57593a9 and 7c46b9a.

📒 Files selected for processing (21)

• docs/runtime-host-remote-access.md
• docs/runtime-host-remote-access.zh-CN.md
• packages/cli/README.md
• packages/cli/README.zh-CN.md
• packages/cli/src/__tests__/runtime-host-operator-command.test.ts
• packages/cli/src/__tests__/runtime-host-service-manager.test.ts
• packages/cli/src/__tests__/runtime-host-setup.test.ts
• packages/cli/src/cli-core.ts
• packages/cli/src/runtime-host-access-command.ts
• packages/cli/src/runtime-host-cli.ts
• packages/cli/src/runtime-host-managed-deployment.ts
• packages/cli/src/runtime-host-service-management-command.ts
• packages/cli/src/runtime-host-setup-command.ts
• packages/runtime-host/src/__tests__/authenticated-websocket.test.ts
• packages/runtime-host/src/__tests__/websocket-listener.test.ts
• packages/runtime-host/src/client/index.ts
• packages/runtime-host/src/client/setup-frame.ts
• packages/runtime-host/src/protocol/access-authority.ts
• packages/runtime-host/src/server/access-authority.ts
• packages/runtime-host/src/server/host-kernel.ts
• packages/runtime-host/src/server/operation-dispatcher.ts

Included review availability: Your plan provides up to 3 included reviews per hour; 2 remain after this review.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Symlinked parent redirects deletion ✓ Resolved 🐞 Bug ⛨ Security ⭐ New

Description

isRuntimeHostManagedDeploymentRoot() validates only lexical path components, then uninstall
recursively removes the configured path. If an ancestor such as Maka or runtime-host-services is
replaced with a symlink, uninstall follows it and deletes the matching <serviceId> directory
outside the managed deployment tree.

Code

packages/cli/src/runtime-host-managed-deployment.ts[R109-116]

+export function isRuntimeHostManagedDeploymentRoot(root: string, serviceId: string): boolean {
+  const canonical = resolve(root);
+  return (
+    isAbsolute(root) &&
+    basename(canonical) === serviceId &&
+    basename(dirname(canonical)) === 'runtime-host-services' &&
+    basename(dirname(dirname(canonical))) === 'Maka'
+  );

Relevance

●●● Strong

Recent accepted precedent explicitly requires realpath-based protection against symlink escapes in
path containment validation.

PR-#3169

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The changed validator does not canonicalize filesystem ancestors, and the changed uninstall flow
passes the persisted value to recursive deletion after only that validation.

packages/cli/src/runtime-host-managed-deployment.ts[109-116]
packages/cli/src/runtime-host-managed-deployment.ts[134-145]
packages/cli/src/runtime-host-service-manager.ts[195-208]
packages/cli/src/runtime-host-service-manager.ts[436-442]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Managed-deployment root validation is lexical, so a symlinked `Maka` or `runtime-host-services` ancestor can redirect recursive uninstall deletion outside the intended data-home deployment tree.

## Issue Context
Do not rely on `resolve()`/`basename()` checks alone for a path later passed to recursive `rm`. Reuse the existing managed-deployment root resolver as the authority for the expected location, then canonicalize/verify the parent chain before deletion. Reject a missing or symlink-redirection path rather than deleting it.

## Fix Focus Areas
- packages/cli/src/runtime-host-managed-deployment.ts[109-145]
- packages/cli/src/runtime-host-service-manager.ts[195-208]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Rejects documented npx setup ✓ Resolved 🐞 Bug ≡ Correctness

Description

runtime-host setup installs the copied managed deployment.cliPath, but its service-manager
invocation inherits the npx environment. assertPersistentCliInstallation() rejects every process
with npm_command === 'exec' before considering that the supplied CLI path is the persistent
managed copy, so the documented npx --yes maka-agent@next runtime-host setup ... exits with
invalid_launch and never installs the service.

Code

packages/cli/src/runtime-host-setup-command.ts[R125-130]

+    installed = await deps.manageService(
+      {
+        ...common,
+        action: 'install',
+        cliPath: deployment.cliPath,
+        ...(options.rootPath ? { rootPath: options.rootPath } : {}),

Relevance

●●● Strong

The documented npx workflow is the PR’s stated contract; accepted history favors fixing
environment-dependent launch failures.

PR-#3169
PR-#2674

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR’s new setup flow passes the managed deployment path into the existing service manager, while
the manager’s preflight rejects the npx process context regardless of that path. The new
documentation explicitly requires that invocation path.

packages/cli/src/runtime-host-setup-command.ts[115-130]
packages/cli/src/runtime-host-service-manager.ts[281-291]
packages/cli/src/runtime-host-service-manager.ts[450-467]
docs/runtime-host-remote-access.md[9-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`runtime-host setup` copies its package to a persistent managed deployment, then invokes service installation while still running in an `npx` environment. The shared service-manager guard rejects `npm_command === 'exec'` unconditionally, causing the documented setup command to fail even though `cliPath` is outside the temporary npx cache.

## Issue Context
The existing path-based npx-cache check already prevents a service from launching an ephemeral npx package. The unconditional invocation-environment check is incompatible with this new setup flow, whose purpose is to replace that ephemeral package with `deployment.cliPath`.

## Fix Focus Areas
- packages/cli/src/runtime-host-service-manager.ts[450-467]
- packages/cli/src/runtime-host-setup-command.ts[125-130]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Encoded paths fail verification ✓ Resolved 🐞 Bug ≡ Correctness

Description

Fix-now: parseSetupCommand accepts paths containing spaces, Unicode, or backslashes even though
constructing the WebSocket URL normalizes/percent-encodes them, while the listener compares the
normalized request pathname against the original configured string. For example, `--websocket-path
'/host path'` installs and starts the service but makes setup verification fail after credential
replacement.

Code

packages/cli/src/runtime-host-cli.ts[R170-174]

+  if (
+    websocketPath !== undefined &&
+    (!websocketPath.startsWith('/') || websocketPath.includes('?') || websocketPath.includes('#'))
+  ) {
+    return error('--websocket-path must be an absolute URL path without a query or fragment');

Relevance

●●● Strong

Recent accepted reviews favor fail-closed validation for path normalization and boundary mismatches.

PR-#3169
PR-#2163

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Setup persists the raw accepted path and forms the verification URL by direct concatenation. The
WebSocket client constructs a standards-based WebSocket URL, while the server parses the request
URL and compares its normalized pathname to the unnormalized configured path, so values such as a
literal space cannot match.

packages/cli/src/runtime-host-cli.ts[170-184]
packages/cli/src/runtime-host-setup-command.ts[171-177]
packages/cli/src/runtime-host-setup-command.ts[286-292]
packages/runtime-host/src/client/connection.ts[1507-1510]
packages/runtime-host/src/server/websocket-listener.ts[187-190]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Reject or consistently canonicalize WebSocket paths whose URL pathname differs from the persisted listener path, so every setup path accepted by parsing can be reached during verification.

## Issue Context
WebSocket-path validation is duplicated across CLI parsing, service configuration, listener configuration, SSH profiles, and tunnels. Consolidate that authority into the closest shared validator rather than adding another setup-only rule; this introduces no new state or public configuration.

## Fix Focus Areas
- packages/cli/src/runtime-host-cli.ts[170-174]
- packages/cli/src/runtime-host-service-manager.ts[379-393]
- packages/runtime-host/src/server/websocket-listener.ts[187-190]
- packages/cli/src/__tests__/runtime-host-setup.test.ts[116-146]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View high (2)

4. Existing package bypasses deployment ✗ Dismissed 🐞 Bug ≡ Correctness

Description

Fix-now: when a same-version deployment directory already exists, setup reuses it after checking
only package name/version and the presence of two files, without comparing it to the invoking
release package. A truncated, corrupted, or previously modified dist or dependency tree therefore
survives reruns and is launched instead of the advertised exact self-contained package.

Code

packages/cli/src/runtime-host-managed-deployment.ts[R46-48]

+  if (await pathExists(packageRoot)) {
+    await validatePackage(packageRoot, input.version);
+    return deployment(input.version, packageRoot, cliPath, false);

Relevance

●●● Strong

Recent accepted reviews consistently flag integrity gaps where persisted artifacts differ from their
authoritative source.

PR-#2961
PR-#3192

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The existing-directory branch never reads or copies the provided source package after its
superficial validation. validatePackage checks only the top-level manifest identity plus
dist/cli.js and one dependency manifest being files, so arbitrary differences elsewhere in the
deployed executable/dependency tree are accepted.

packages/cli/src/runtime-host-managed-deployment.ts[40-48]
packages/cli/src/runtime-host-managed-deployment.ts[141-165]
packages/cli/src/runtime-host-setup-command.ts[115-120]
packages/cli/src/runtime-host-setup-command.ts[125-136]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Ensure an existing same-version managed deployment is proven identical to the invoking self-contained package or atomically replaced before the service launches it.

## Issue Context
The invoking release package is already the source authority, so do not add a second mutable version-to-integrity registry unless unavoidable. Prefer deriving integrity from and atomically converging to that source; add coverage that modifies an existing deployed CLI or dependency and verifies rerunning setup repairs or rejects it.

## Fix Focus Areas
- packages/cli/src/runtime-host-managed-deployment.ts[40-70]
- packages/cli/src/runtime-host-managed-deployment.ts[141-165]
- packages/cli/src/__tests__/runtime-host-setup.test.ts[24-114]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Failed setup commits rotation ✗ Dismissed 🐞 Bug ☼ Reliability

Description

Fix-now: once service installation succeeds, a pairing or verification error returns failure without
restoring the prior service/package, and verification failure occurs after replaceCredential has
already revoked the old stable-principal credential while the replacement is never returned. This
violates the advertised setup transaction and safe credential rotation contract, leaving callers
with partial deployment state and no usable credential for that identity.

Code

packages/cli/src/runtime-host-setup-command.ts[R173-177]

+  await deps.verifyCredential({
+    endpoint,
+    rootId: paired.rootId,
+    credential: paired.credential,
+  });

Relevance

●● Moderate

Transactional rollback and credential recovery are reliability-sensitive, but exact setup-rotation
precedent is absent.

PR-#1742
PR-#1755
PR-#3176

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The setup rollback only surrounds the service install call; pairing and verification run afterward.
Replacement durably commits a file that excludes every active credential for the principal and
publishes their revocations before setup verifies the new credential, while only a complete frame
exposes that new secret.

packages/cli/src/runtime-host-setup-command.ts[122-177]
packages/cli/src/runtime-host-setup-command.ts[178-186]
packages/runtime-host/src/server/access-authority.ts[130-157]
packages/cli/src/runtime-host-managed-deployment.ts[178-189]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Make managed setup transactional across service installation, credential rotation, and verification. A failed pairing or verification must not leave newly installed deployment/service state committed or revoke the caller's prior stable-principal credential without returning a usable replacement.

## Issue Context
Reuse the existing service deployment rollback and credential authority seams where possible. Reuse alone cannot preserve the old credential because `access.credential.replace` durably removes it before network verification; introduce only the minimum staged/promotion behavior needed to verify a candidate credential before atomically making it authoritative, and add failure-path tests for the new transient state and rollback burden.

## Fix Focus Areas
- packages/cli/src/runtime-host-setup-command.ts[122-186]
- packages/runtime-host/src/server/access-authority.ts[130-157]
- packages/cli/src/__tests__/runtime-host-setup.test.ts[148-195]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

Review mode: ⚖️ Balanced: This push changes managed-service launch validation and guarded deployment deletion, including security-sensitive path and service invariants; the logic is localized but carries real behavioral and security risk warranting a complete single-pass review.

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous reviews

Review updated until commit 05ddec0

Results up to commit 7c46b9a 🧠 Deep

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Existing package bypasses deployment ✗ Dismissed 🐞 Bug ≡ Correctness

Description

Fix-now: when a same-version deployment directory already exists, setup reuses it after checking
only package name/version and the presence of two files, without comparing it to the invoking
release package. A truncated, corrupted, or previously modified dist or dependency tree therefore
survives reruns and is launched instead of the advertised exact self-contained package.

Code

packages/cli/src/runtime-host-managed-deployment.ts[R46-48]

+  if (await pathExists(packageRoot)) {
+    await validatePackage(packageRoot, input.version);
+    return deployment(input.version, packageRoot, cliPath, false);

Relevance

●●● Strong

Recent accepted reviews consistently flag integrity gaps where persisted artifacts differ from their
authoritative source.

PR-#2961
PR-#3192

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The existing-directory branch never reads or copies the provided source package after its
superficial validation. validatePackage checks only the top-level manifest identity plus
dist/cli.js and one dependency manifest being files, so arbitrary differences elsewhere in the
deployed executable/dependency tree are accepted.

packages/cli/src/runtime-host-managed-deployment.ts[40-48]
packages/cli/src/runtime-host-managed-deployment.ts[141-165]
packages/cli/src/runtime-host-setup-command.ts[115-120]
packages/cli/src/runtime-host-setup-command.ts[125-136]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Ensure an existing same-version managed deployment is proven identical to the invoking self-contained package or atomically replaced before the service launches it.

## Issue Context
The invoking release package is already the source authority, so do not add a second mutable version-to-integrity registry unless unavoidable. Prefer deriving integrity from and atomically converging to that source; add coverage that modifies an existing deployed CLI or dependency and verifies rerunning setup repairs or rejects it.

## Fix Focus Areas
- packages/cli/src/runtime-host-managed-deployment.ts[40-70]
- packages/cli/src/runtime-host-managed-deployment.ts[141-165]
- packages/cli/src/__tests__/runtime-host-setup.test.ts[24-114]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Rejects documented npx setup ✓ Resolved 🐞 Bug ≡ Correctness

Description

runtime-host setup installs the copied managed deployment.cliPath, but its service-manager
invocation inherits the npx environment. assertPersistentCliInstallation() rejects every process
with npm_command === 'exec' before considering that the supplied CLI path is the persistent
managed copy, so the documented npx --yes maka-agent@next runtime-host setup ... exits with
invalid_launch and never installs the service.

Code

packages/cli/src/runtime-host-setup-command.ts[R125-130]

+    installed = await deps.manageService(
+      {
+        ...common,
+        action: 'install',
+        cliPath: deployment.cliPath,
+        ...(options.rootPath ? { rootPath: options.rootPath } : {}),

Relevance

●●● Strong

The documented npx workflow is the PR’s stated contract; accepted history favors fixing
environment-dependent launch failures.

PR-#3169
PR-#2674

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR’s new setup flow passes the managed deployment path into the existing service manager, while
the manager’s preflight rejects the npx process context regardless of that path. The new
documentation explicitly requires that invocation path.

packages/cli/src/runtime-host-setup-command.ts[115-130]
packages/cli/src/runtime-host-service-manager.ts[281-291]
packages/cli/src/runtime-host-service-manager.ts[450-467]
docs/runtime-host-remote-access.md[9-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`runtime-host setup` copies its package to a persistent managed deployment, then invokes service installation while still running in an `npx` environment. The shared service-manager guard rejects `npm_command === 'exec'` unconditionally, causing the documented setup command to fail even though `cliPath` is outside the temporary npx cache.

## Issue Context
The existing path-based npx-cache check already prevents a service from launching an ephemeral npx package. The unconditional invocation-environment check is incompatible with this new setup flow, whose purpose is to replace that ephemeral package with `deployment.cliPath`.

## Fix Focus Areas
- packages/cli/src/runtime-host-service-manager.ts[450-467]
- packages/cli/src/runtime-host-setup-command.ts[125-130]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Encoded paths fail verification ✓ Resolved 🐞 Bug ≡ Correctness

Description

Fix-now: parseSetupCommand accepts paths containing spaces, Unicode, or backslashes even though
constructing the WebSocket URL normalizes/percent-encodes them, while the listener compares the
normalized request pathname against the original configured string. For example, `--websocket-path
'/host path'` installs and starts the service but makes setup verification fail after credential
replacement.

Code

packages/cli/src/runtime-host-cli.ts[R170-174]

+  if (
+    websocketPath !== undefined &&
+    (!websocketPath.startsWith('/') || websocketPath.includes('?') || websocketPath.includes('#'))
+  ) {
+    return error('--websocket-path must be an absolute URL path without a query or fragment');

Relevance

●●● Strong

Recent accepted reviews favor fail-closed validation for path normalization and boundary mismatches.

PR-#3169
PR-#2163

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Setup persists the raw accepted path and forms the verification URL by direct concatenation. The
WebSocket client constructs a standards-based WebSocket URL, while the server parses the request
URL and compares its normalized pathname to the unnormalized configured path, so values such as a
literal space cannot match.

packages/cli/src/runtime-host-cli.ts[170-184]
packages/cli/src/runtime-host-setup-command.ts[171-177]
packages/cli/src/runtime-host-setup-command.ts[286-292]
packages/runtime-host/src/client/connection.ts[1507-1510]
packages/runtime-host/src/server/websocket-listener.ts[187-190]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Reject or consistently canonicalize WebSocket paths whose URL pathname differs from the persisted listener path, so every setup path accepted by parsing can be reached during verification.

## Issue Context
WebSocket-path validation is duplicated across CLI parsing, service configuration, listener configuration, SSH profiles, and tunnels. Consolidate that authority into the closest shared validator rather than adding another setup-only rule; this introduces no new state or public configuration.

## Fix Focus Areas
- packages/cli/src/runtime-host-cli.ts[170-174]
- packages/cli/src/runtime-host-service-manager.ts[379-393]
- packages/runtime-host/src/server/websocket-listener.ts[187-190]
- packages/cli/src/__tests__/runtime-host-setup.test.ts[116-146]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View high (1)

4. Failed setup commits rotation ✗ Dismissed 🐞 Bug ☼ Reliability

Description

Fix-now: once service installation succeeds, a pairing or verification error returns failure without
restoring the prior service/package, and verification failure occurs after replaceCredential has
already revoked the old stable-principal credential while the replacement is never returned. This
violates the advertised setup transaction and safe credential rotation contract, leaving callers
with partial deployment state and no usable credential for that identity.

Code

packages/cli/src/runtime-host-setup-command.ts[R173-177]

+  await deps.verifyCredential({
+    endpoint,
+    rootId: paired.rootId,
+    credential: paired.credential,
+  });

Relevance

●● Moderate

Transactional rollback and credential recovery are reliability-sensitive, but exact setup-rotation
precedent is absent.

PR-#1742
PR-#1755
PR-#3176

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The setup rollback only surrounds the service install call; pairing and verification run afterward.
Replacement durably commits a file that excludes every active credential for the principal and
publishes their revocations before setup verifies the new credential, while only a complete frame
exposes that new secret.

packages/cli/src/runtime-host-setup-command.ts[122-177]
packages/cli/src/runtime-host-setup-command.ts[178-186]
packages/runtime-host/src/server/access-authority.ts[130-157]
packages/cli/src/runtime-host-managed-deployment.ts[178-189]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Make managed setup transactional across service installation, credential rotation, and verification. A failed pairing or verification must not leave newly installed deployment/service state committed or revoke the caller's prior stable-principal credential without returning a usable replacement.

## Issue Context
Reuse the existing service deployment rollback and credential authority seams where possible. Reuse alone cannot preserve the old credential because `access.credential.replace` durably removes it before network verification; introduce only the minimum staged/promotion behavior needed to verify a candidate credential before atomically making it authoritative, and add failure-path tests for the new transient state and rollback burden.

## Fix Focus Areas
- packages/cli/src/runtime-host-setup-command.ts[122-186]
- packages/runtime-host/src/server/access-authority.ts[130-157]
- packages/cli/src/__tests__/runtime-host-setup.test.ts[148-195]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[M4n5ter]

/agentic_review

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/cli/src/runtime-host-setup-command.ts (1)

143-181: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Keep the prior pairing state until verification succeeds.

deployment.rollback() runs only when manageService() throws. A failed readiness check, pairing operation, or credential verification exits without compensating the changed state.

For an existing principalId, replaceCredential() revokes the prior credential before verifyCredential() runs. If verification fails, setup emits only an error frame. The prior Client credential is revoked, and the new credential is not returned. The existing Client can no longer reconnect.

Disposition: fix-now.

Deletion or reuse of the current rollback is insufficient. The current replacement operation commits immediately. Add a pending credential or equivalent commit-and-rollback protocol. Finalize replacement only after authenticated verification succeeds. Coordinate service and deployment rollback in the same transaction scope. This adds temporary credential state, a commit surface, and failure-path tests.

Source: Path instructions

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 12fe5c97-edd4-4461-8f60-a391d8dbc7a6

📥 Commits

Reviewing files that changed from the base of the PR and between 7c46b9a and ba5a60b.

📒 Files selected for processing (19)

• apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx
• docs/runtime-host-remote-access.md
• docs/runtime-host-remote-access.zh-CN.md
• packages/cli/README.md
• packages/cli/README.zh-CN.md
• packages/cli/src/__tests__/runtime-host-service-manager.test.ts
• packages/cli/src/__tests__/runtime-host-setup.test.ts
• packages/cli/src/runtime-host-cli.ts
• packages/cli/src/runtime-host-managed-deployment.ts
• packages/cli/src/runtime-host-service-management-command.ts
• packages/cli/src/runtime-host-service-manager.ts
• packages/cli/src/runtime-host-setup-command.ts
• packages/runtime-host/src/client/host-profile.ts
• packages/runtime-host/src/client/index.ts
• packages/runtime-host/src/client/setup-frame.ts
• packages/runtime-host/src/client/ssh-tunnel.ts
• packages/runtime-host/src/protocol/index.ts
• packages/runtime-host/src/protocol/websocket-path.ts
• packages/runtime-host/src/server/websocket-listener.ts

Included review availability: Your plan provides up to 3 included reviews per hour; 0 remain after this review.

[qodo-code-review]

Code review by qodo was updated up to the latest commit ba5a60b

[M4n5ter]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit 05ddec0

[M4n5ter]

Given that there are currently almost no users on the remote host and the associated risk is relatively low, it is hereby decided to proceed with the merge first.