fix(cli): explain residency-blocked host conflicts

[me2seeks]

Summary

English

Explain local Runtime Host compatibility conflicts when an older ephemeral Host is retained by resident work.

The CLI now projects safe registration facts—PID, lifecycle mode, and compatibility epoch—and explains that retrying cannot itself retire resident work. The TUI still permits an explicit wait when another compatible Client is expected to finish work, but re-prompts after each failed retry instead of entering a silent loop.

This does not alter Goal durability, Host admission, or the one-Host-per-State-Root authority model.

Fixes #3207

中文

改进本地 Runtime Host 兼容冲突的诊断：展示 PID、lifecycle 和 compatibility epoch，并明确仅重试不会让 resident work 自动结束。

TUI 仍允许用户在预期其他兼容 Client 会完成工作时选择等待，但每次失败后都会重新展示状态与取消选项，不再静默循环。

本修复不改变 Goal durability、Host admission 或一个 State Root 只有一个 Host authority 的约束。

Verification

English

• node --test --test-name-pattern='non-interactive CLI reports how to retire an incompatible Runtime Host' packages/cli/dist/__tests__/runtime-host-cli-context.test.js
• npm --workspace maka-agent run typecheck
• npm run lint
• npm run format:check
• Manual TTY regression against a real epoch-23 local Host retained by paused Goals

中文

• 定向 CLI 测试、typecheck、lint 与 format 检查通过。
• 使用真实 epoch-23、本地 paused Goal 留存的 Host 完成 TTY 回归。

AI use

• Generative tooling made a substantive contribution

Tool(s) and scope: Codex investigated the lifecycle behavior, implemented the CLI/TUI projection, and ran local verification. The commit includes the required Generated-by: Codex trailer.

Visual evidence

The representative TUI conflict state shows the projected Host identity/lifecycle facts and makes the explicit wait (w) versus default cancel (C) choice visible.

[coderabbitai]

📝 Walkthrough

Summary

This PR improves CLI and TUI diagnostics for local Runtime Host compatibility conflicts caused by retained resident work.

• The CLI reports the Host PID, lifecycle mode, and compatibility epoch.
• The error explains when resident work prevents Host replacement.
• The error directs users to the prior compatible Client or to stop the Host after confirming that interruption is safe.
• The TUI prompts after each failed retry.
• The TUI permits waiting only when another compatible Client is expected to finish.
• Tests cover residency-blocked conflicts, idle Hosts, retry behavior, and cancellation.

The change extends the existing Runtime Host registration and admission path. It does not create a parallel Host authority or change Goal durability, Host admission, or the one-Host-per-State-Root model.

The implementation is the smallest coherent solution shown by the supplied change summary. No code or tests are clearly removable without weakening behavior or regression coverage.

Validation includes targeted CLI tests, typecheck, lint, format checks, and a manual TTY regression with a retained epoch-23 Host. Final required-check status remains unverified.

Complexity delta

• Authorities: No new authority. The Runtime Host remains authoritative for residency, admission, and durable Goal state.
• State: The TUI removes its waitingForHost state.
• Branches: Conflict handling adds lifecycle-specific guidance and evaluates each retry decision explicitly.
• Configuration: No new configuration.
• Public surface: RuntimeHostCliConflictError now requires HostRegistration. shouldRetryRuntimeHostConflict is added.
• Test maintenance: Fixtures accept lifecycle-mode overrides. Assertions cover registration facts and retry decisions.

The total maintenance complexity stays justified. The diagnostics address the reported compatibility conflict. Removing the waiting-state logic offsets part of the added branch and test complexity.

Review-relevant risks

The CLI and TUI user-visible behavior changes. The RuntimeHostCliConflictError constructor signature changes. The public shouldRetryRuntimeHostConflict helper is added. Material changes in these areas require independent human review under repository policy.

No protected-area effect was identified in the current diff for security, licensing, releases, or governance. Final required-check status is unverified. The person performing the merge reviews the final diff, and a maintainer makes the final determination.

Walkthrough

The CLI now includes Runtime Host PID, lifecycle mode, and compatibility epoch in incompatibility errors. The TUI prompts after each conflict and retries only after an explicit wait response. Tests cover lifecycle-specific diagnostics and retry decisions.

Changes

Runtime Host conflict handling

Layer / File(s)	Summary
Conflict metadata and diagnostics packages/cli/src/runtime-host-cli-context.ts, packages/cli/src/__tests__/runtime-host-cli-context.test.ts	RuntimeHostCliConflictError receives HostRegistration data and reports PID, lifecycle mode, compatibility epoch, and lifecycle-specific guidance. Tests cover ephemeral and service Host messages and updated registration fixtures.
Explicit retry prompt control packages/cli/src/runtime-host-tui-command.ts, packages/cli/src/runtime-host-cli-context.ts, packages/cli/src/__tests__/runtime-host-cli-context.test.ts	shouldRetryRuntimeHostConflict accepts trimmed w and wait responses. The TUI reports each conflict, prompts again, and returns null on cancellation without timed blind retries. Tests cover accepted and rejected responses.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to a110d

The change improves diagnostics and retry/cancel behavior for residency-blocked host conflicts; no actionable merge-blocking risk remains beyond normal checks and review.

Possibly related issues

• maka-agent/maka-agent#3245 — Extends the same Runtime Host conflict diagnostics and retry behavior.

Possibly related PRs

• maka-agent/maka-agent#3136 — Modifies handshake compatibility-epoch conflict handling.
• maka-agent/maka-agent#3246 — Covers CLI diagnostics for incompatible Runtime Hosts.
• maka-agent/maka-agent#2991 — Also changes Runtime TUI command behavior.

Suggested reviewers: m4n5ter, jackwener, moonold

Sequence Diagram(s)

sequenceDiagram
  participant TUI
  participant RuntimeHostCliContext
  participant RuntimeHost
  TUI->>RuntimeHostCliContext: request Runtime Host connection
  RuntimeHostCliContext->>RuntimeHost: perform handshake
  RuntimeHost-->>RuntimeHostCliContext: return incompatible handshake and registration
  RuntimeHostCliContext-->>TUI: display conflict details
  TUI->>TUI: prompt for explicit wait response
  TUI->>RuntimeHostCliContext: retry only for w or wait

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the CLI fix for residency-blocked host conflicts.
Description check	✅ Passed	The description covers the summary, issue reference, verification, AI use, behavior, and evidence; the missing checklist is non-critical.
Linked Issues check	✅ Passed	The changes satisfy issue #3207 by improving conflict diagnostics, retry behavior, operator guidance, and test coverage without changing Host authority.
Out of Scope Changes check	✅ Passed	The changes remain within issue #3207 and do not introduce compatibility-contract changes, direct Goal control, or additional Host ownership.
Ai Use Disclosure	✅ Passed	The PR selects generative tooling, names Codex and its implementation scope, and the sole introduced commit has the valid standalone trailer Generated-by: Codex.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[qodo-code-review]

PR Summary by Qodo

Explain residency-blocked Runtime Host conflicts in CLI

🐞 Bug fix 🧪 Tests 🕐 20-40 Minutes

AI Description

• Reports safe Host registration facts when resident work blocks compatibility replacement.
• Explains why retries cannot retire retained work and recommends compatible-build recovery.
• Re-prompts TUI users after every failed wait instead of silently retrying.

Diagram

sequenceDiagram
  actor User
  participant TUI as TUI Command
  participant Context as CLI Context
  participant Connector as Host Connector
  User->>TUI: Start local session
  TUI->>Context: Create context
  Context->>Connector: Connect or spawn
  Connector-->>Context: Incompatible plus registration
  Context-->>TUI: Conflict with host facts
  TUI-->>User: Explain and prompt
  alt Cancel
    User-->>TUI: Cancel
  else Wait
    User-->>TUI: Wait
    TUI->>Context: Retry after delay
  end

Loading

High-Level Assessment

The current approach is appropriate: it uses registration metadata already returned by local discovery, avoiding protocol or Host-admission changes, and keeps interruption decisions explicit. Extending the incompatibility handshake or silently polling until replacement becomes possible would add broader coupling or recreate the confusing retry behavior this fix removes.

Files changed (3) +29 / -14

Bug fix (2) +19 / -12

runtime-host-cli-context.tsInclude Host registration facts in compatibility errors +14/-5

Include Host registration facts in compatibility errors

• Carries the discovered Host registration into 'RuntimeHostCliConflictError' and reports its PID, lifecycle mode, and compatibility epoch. Replaces generic stop-or-wait guidance with residency-aware recovery instructions that discourage unsafe interruption.

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

runtime-host-tui-command.tsRe-prompt after each failed Host retry +5/-7

Re-prompt after each failed Host retry

• Removes the silent retry state so every failed attempt redisplays current conflict details and cancellation controls. Clarifies that waiting is appropriate only when another compatible Client is expected to finish resident work, with cancellation as the default.

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

Tests (1) +10 / -2

runtime-host-cli-context.test.tsVerify actionable residency-conflict diagnostics +10/-2

Verify actionable residency-conflict diagnostics

• Updates the incompatible-Host test to require PID, lifecycle mode, compatibility epoch, retry limitations, and compatible-build recovery guidance. Extends the registration fixture with lifecycle-mode support.

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

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: dc3501e5-0872-4267-98ac-7202710b0db7

📥 Commits

Reviewing files that changed from the base of the PR and between 4a54ee2 and a796de8.

📒 Files selected for processing (3)

• packages/cli/src/__tests__/runtime-host-cli-context.test.ts
• packages/cli/src/runtime-host-cli-context.ts
• packages/cli/src/runtime-host-tui-command.ts

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

[qodo-code-review]

Code Review by Qodo

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

1. Residency claim is unconditional ✓ Resolved 🐞 Bug ≡ Correctness

Description

The formatter states that every incompatible Host has resident work, but service Hosts and ephemeral
Hosts with only active connections or operations receive the same blocking outcome even when
residency count is zero. Users can therefore be incorrectly told to reopen an older build to clear
retained work instead of receiving lifecycle-appropriate restart guidance.

Code

packages/cli/src/runtime-host-cli-context.ts[R168-169]

+    `Local Runtime Host: PID ${registration.pid}; lifecycle ${registration.lifecycleMode ?? 'unknown'}; compatibility epoch ${registration.compatibilityEpoch}.`,
+    'The Host has resident work and will not exit merely because this Client retries.',

Relevance

●●● Strong

Accepted history strongly favors concrete correctness findings exposing inaccurate
lifecycle-specific diagnostics.

PR-#3176
PR-#3128

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The kernel assigns blocked_by_residency to every service Host regardless of its residency count,
and to any ephemeral Host that is not fully idle; isTrueIdle() separately includes transports,
operations, and residencies. The execution service uses the same interactive composition targeted by
the CLI, so an idle service Host is a concrete path to this newly added false diagnostic.

packages/runtime-host/src/server/host-kernel.ts[435-454]
packages/runtime-host/src/server/host-kernel.ts[702-708]
packages/runtime-host/src/server/execution-service.ts[37-53]
packages/runtime-host/src/server/execution-composition-factory.ts[43-46]
packages/runtime-host/src/client/connect-or-spawn.ts[296-300]

Agent prompt

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

## Issue description
The conflict formatter unconditionally claims that an incompatible Host has resident work. The Host kernel's incompatibility predicate also covers service Hosts and non-idle ephemeral Hosts without any active residency, so the resulting remediation can be false.

## Issue Context
Reuse the existing handshake replacement outcome and registration lifecycle mode rather than introducing another authority. Give service Hosts service-specific stop/restart guidance, and avoid claiming retained residency unless existing protocol facts prove it; no new protocol state is necessary.

## Fix Focus Areas
- packages/cli/src/runtime-host-cli-context.ts[162-180]
- packages/cli/src/__tests__/runtime-host-cli-context.test.ts[94-99]

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

---

2. Cancel default still waits ✓ Resolved 🐞 Bug ≡ Correctness

Description

The prompt advertises [w/C], but the code retries for every response except exactly c or
cancel, so pressing Enter or entering invalid text silently chooses wait. This violates the stated
explicit-wait behavior and can keep users in the retry loop without affirmative consent.

Code

packages/cli/src/runtime-host-tui-command.ts[R111-114]

+        const answer = (
+          await readline.question(
+            'Wait only if another compatible Client is expected to finish that work, or cancel? [w/C] ',
+          )

Relevance

●●● Strong

Explicit prompt semantics and invalid-input handling are deterministic correctness issues; recent
CLI bug findings were accepted.

PR-#1587
PR-#3169

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

After normalization, only c and cancel return null. Every other value falls through to the
two-second delay and the enclosing loop retries context creation, including empty input and
arbitrary invalid text.

packages/cli/src/runtime-host-tui-command.ts[103-123]
packages/cli/src/runtime-host-tui-command.ts[127-128]

Agent prompt

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

## Issue description
The `[w/C]` prompt says cancellation is the default, but empty and invalid answers fall through to the wait-and-retry path. Only an explicit `w` or `wait` should authorize waiting.

## Issue Context
Make the smallest local correction: positively recognize the wait choices, return cancellation for empty input, and re-prompt or cancel on invalid input. Add focused tests for empty, invalid, wait, and cancel responses; no new state or public surface is needed.

## Fix Focus Areas
- packages/cli/src/runtime-host-tui-command.ts[100-128]

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

---

Context sources

Review mode: ⚖️ Balanced: This is a localized runtime CLI/TUI behavior change involving host lifecycle diagnostics and retry/cancellation control flow; it has real state/invariant and user-facing contract risk, but not enough independent logic for extended 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 ↗

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ad3b9f4c-cc1a-4a87-8e5d-9c53ac659139

📥 Commits

Reviewing files that changed from the base of the PR and between a796de8 and 123cfc3.

📒 Files selected for processing (3)

• packages/cli/src/__tests__/runtime-host-cli-context.test.ts
• packages/cli/src/runtime-host-cli-context.ts
• packages/cli/src/runtime-host-tui-command.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/cli/src/runtime-host-tui-command.ts
• packages/cli/src/runtime-host-cli-context.ts

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

[Astro-Han]

The change now projects the relevant registration facts, distinguishes operator-managed service Hosts, and requires an explicit wait choice on each retry. I found no concrete P0–P3 issue in this head. The wait_for_idle_exit path remains intentionally handled inside connection election; the CLI conflict diagnostic only receives blocked_by_residency, where the non-idle wording is accurate.

Reviewed with Codex using two independent review passes and DeepSeek V4 Flash as an external adversarial pass; I verified the replacement-state control flow against this exact head and current main.

中文

当前实现已投影必要的 registration 事实，区分 operator 管理的 service Host，并要求每次重试都显式选择 wait。未发现具体的 P0–P3 问题。wait_for_idle_exit 仍由连接选举层内部处理；CLI 冲突诊断只会收到 blocked_by_residency，此时 non-idle 描述成立。

本次由 Codex 两轮独立审查，并使用 DeepSeek V4 Flash 做外部对抗审查；我核对了当前 head 与最新 main。

[Astro-Han]

This PR changes the user-visible Runtime Host conflict flow. Could you please add a screenshot showing the updated TUI conflict message and the available wait or cancel choices? One representative state is fine. Thanks!

Posted by Codex on behalf of Astro-Han.

[me2seeks]

Added the requested representative TUI screenshot to the PR body. It shows the revised Host conflict facts and the explicit wait (w) versus default cancel (C) choices.

[me2seeks]

Rebased the unchanged PR patch onto current main (a110dfa71) so CI includes #3223, which fixes the unrelated Eval drain-admission race that failed the previous run. git range-diff 8fd116726^! a110dfa71^! reports the patch as equivalent. Local verification: full build, all-workspace typecheck, CLI context 7/7, and the previously failing Eval regression 1/1.

[coderabbitai]

🧹 Nitpick comments (1)

packages/cli/src/__tests__/runtime-host-cli-context.test.ts (1)

149-158: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add one test for the observable TUI retry loop.

These assertions verify only shouldRetryRuntimeHostConflict. They do not verify that createTuiContextWithHostConflictPrompt retries after w, re-prompts after a second conflict, and stops without another attempt after cancellation. A regression in that loop could pass this test unchanged.

Disposition: follow-up. Add one focused TUI-boundary test and reuse these parser cases instead of duplicating them.

As per path instructions, tests must protect observable behavior.

Source: Path instructions

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8cb630d1-251e-40f2-8f1a-28b1a5f92894

📥 Commits

Reviewing files that changed from the base of the PR and between 123cfc3 and a110dfa.

📒 Files selected for processing (2)

• packages/cli/src/__tests__/runtime-host-cli-context.test.ts
• packages/cli/src/runtime-host-tui-command.ts

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

[Astro-Han]

Human merge confirmation: Astro-Han reviewed the final diff at a110dfa712 and explicitly authorized this squash merge. All required checks are green, the current head is approved, the UI evidence and AI provenance are complete, and there are no unresolved review threads. The squash commit will retain Generated-by: Codex.