discussion(cli): define durable Runtime Host ownership for npx launches

[me2seeks]

English

Question

May a transient npx invocation own a Runtime Host that outlives that invocation because of durable work? If so, what persistent artifact and installation authority owns that Host after the npm cache entry is no longer a reliable deployment root?

Current evidence

Current

• npx --yes maka-agent@next runs the exact package selected by the npm dist-tag or version.
• The local CLI resolves its Runtime Host candidate entrypoint from that package and may launch a detached ephemeral Host.
• /exit disconnects the TUI Surface. Durable residency may intentionally keep the Host alive afterward.
• Therefore a Host launched from an _npx cache path can outlive the invocation that supplied its code.
• Current managed-service setup avoids this problem by copying an exact package into a Maka-owned persistent deployment. Direct persistent service installation from a temporary npx path is rejected.

Decision to make

Choose one explicit ownership model; do not retain the current ambiguous middle state.

Option A — invocation-owned

An npx TUI may launch an owned local Host, but that Host must retire when the invocation ends. Background Scheduled Tasks and other durable work do not continue while no installed Maka owner is running.

Option B — managed local artifact

Before enabling Host work that may outlive npx, copy and verify the exact release into a versioned Maka-owned local deployment. The durable deployment—not the npm cache entry—becomes installation owner and later updates use #3231 retirement semantics.

Option C — connect-only

An npx invocation may connect to an existing compatible Host but cannot create a durable local Host. When none exists, it directs the user to install Maka or explicitly create a managed deployment.

Proposed direction

Planned — pending maintainer confirmation

The two user intents should not be forced into one global option:

• Direct npx maka uses the invocation-owned rule from Option A. It may connect to an existing compatible Host or start an invocation-owned ephemeral Host, but a Host it starts retires when the invocation ends; durable background work does not continue without a persistent owner.
• Explicit npx ... runtime-host setup uses the managed-artifact rule from Option B because the user deliberately requested persistent hosting. Setup resolves and verifies the exact invoked release, copies it into a Maka-owned persistent deployment, then installs systemd or LaunchAgent from that durable path. The _npx cache never becomes the service executable.
• A verified persistent Desktop/CLI/service installation may establish the initial owner when no owner exists. A different durable owner must use an explicit transfer; last-launch-wins, package path, PID, version, epoch compatibility, and ordinary Client access are not transfer authority.

This preserves user choice without allowing a transient cache entry to become durable authority. It is the product rule to carry into #3709; the issue remains open until the owner record, transfer protocol, invocation-liveness behavior, and released-package qualification are accepted and implemented.

Refs #3709

Required evaluation

• Expected npx product promise: disposable trial, full local product, or operator/setup tool
• Scheduled Task and Goal behavior after the invoking shell exits
• npm cache eviction and mutation while the Host is resident
• coexistence with Desktop and globally installed CLI releases
• same-epoch release skew versus genuinely incompatible epochs (discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204)
• ownership and cleanup of versioned artifacts, native dependencies, logs, credentials, and State Roots
• offline restart and recovery after the original npm cache entry disappears
• downgrade and rollback boundaries
• Windows, macOS, and Linux package-path behavior

Stable constraints

• A temporary cache path is not silently treated as durable installation authority.
• Ordinary compatible version skew does not itself authorize Host replacement.
• npx never silently updates a managed remote Host.
• One State Root retains one writer throughout any ownership transition.
• Removing an artifact remains separate from deleting the State Root.

Success criteria

• The chosen model has one identifiable installation owner and one cleanup policy.
• Users can predict whether durable work continues after npx exits.
• Cache eviction cannot leave a resident or restartable Host dependent on missing code.
• Desktop, global CLI, and npx cannot repeatedly replace one another's compatible Host merely because their releases differ.
• Released-package tests cover launch, Surface exit, durable residency, cache disappearance, and later recovery.

Part of #3231. The chosen model will constrain the installed-CLI update work and the TUI lifecycle UX.

简体中文

问题

临时 npx invocation 是否可以拥有一个因 durable work 而在 invocation 结束后继续运行的 Runtime Host？如果可以，当 npm cache entry 不再是可靠 deployment root 后，哪一份持久 artifact 和哪一个 installation authority 继续拥有该 Host？

当前证据

Current

• npx --yes maka-agent@next 会运行 npm dist-tag 或精确版本选择的 package。
• 本地 CLI 从该 package 解析 Runtime Host candidate entrypoint，并可能启动 detached ephemeral Host。
• /exit 只断开 TUI Surface；durable residency 可以有意让 Host 此后继续运行。
• 因此从 _npx cache 路径启动的 Host 可能比提供其代码的 invocation 活得更久。
• 当前 managed-service setup 会把精确 package 复制到 Maka-owned 的持久 deployment；直接从临时 npx 路径安装 persistent service 会被拒绝。

需要作出的决策

必须明确选择一种 ownership model，不能保留当前模糊的中间状态。

方案 A：invocation-owned

npx TUI 可以启动 owned local Host，但 invocation 结束时 Host 必须退场。没有 installed Maka owner 运行时，后台 Scheduled Task 和其他 durable work 不继续执行。

方案 B：managed local artifact

在允许 Host work 超过 npx 生命周期前，将精确 release 复制并验证到版本化的 Maka-owned local deployment。由该 durable deployment 而不是 npm cache entry 成为 installation owner，后续更新复用 #3231 retirement 语义。

方案 C：connect-only

npx 可以连接已有兼容 Host，但不能创建 durable local Host。没有 Host 时，引导用户安装 Maka 或明确创建 managed deployment。

建议方向

Planned——等待 maintainer 确认

两种用户意图不应被强制压成一个全局选项：

• 直接 npx maka 采用方案 A 的 invocation-owned 规则。它可以连接已有 compatible Host，或启动 invocation-owned ephemeral Host；但由它启动的 Host 必须随 invocation 结束而退场。没有 persistent owner 时，durable background work 不继续运行。
• 用户显式运行 npx ... runtime-host setup 时采用方案 B 的 managed-artifact 规则，因为用户主动选择了持久托管。Setup 解析并验证本次调用的精确 release，将它复制到 Maka-owned 持久 deployment，再从该持久路径安装 systemd 或 LaunchAgent；_npx cache 永远不成为 service executable。
• 没有 owner 时，经过验证的持久 Desktop/CLI/service installation 可以建立初始 owner。另一个 durable owner 接管时必须显式 transfer；last-launch-wins、package path、PID、version、epoch compatibility 与普通 Client access 都不是 transfer authority。

这个方向既保留用户选择，也不允许临时 cache entry 获得 durable authority。它应作为 #3709 后续实现采用的产品规则；在 owner record、transfer protocol、invocation liveness 与 released-package qualification 被接受并实现前，本 Issue 保持开放。

关联 #3709

必须评估

• npx 的产品承诺：一次性试用、完整本地产品，还是 operator/setup 工具
• invocation shell 退出后的 Scheduled Task 与 Goal 行为
• Host 常驻时 npm cache 被清理或变更
• 与 Desktop 和全局 CLI release 共存
• 同 epoch release skew 与真正不兼容 epoch 的区别（discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204）
• versioned artifact、native dependency、log、credential 和 State Root 的 owner 与清理
• 原 npm cache entry 消失后的离线重启与恢复
• downgrade 与 rollback 边界
• Windows、macOS 与 Linux package path 行为

稳定约束

• 临时 cache path 不会被静默视为 durable installation authority。
• 普通兼容版本差异本身不授权替换 Host。
• npx 不会静默更新 managed remote Host。
• 任何 ownership transition 中，一个 State Root 仍只有一个 writer。
• 删除 artifact 与删除 State Root 保持分离。

完成标准

• 选定模型只有一个可识别的 installation owner 和一套 cleanup policy。
• 用户可以预期 npx 退出后 durable work 是否继续。
• Cache 清理不会让 resident 或可恢复 Host 依赖已消失的代码。
• Desktop、全局 CLI 与 npx 不会仅因 release 不同而反复替换彼此兼容的 Host。
• 已发布 package 测试覆盖启动、Surface 退出、durable residency、cache 消失和后续恢复。

属于 #3231。最终选择会约束 installed-CLI update 工作和 TUI lifecycle UX。

AI assistance disclosure

This discussion was investigated and drafted with Codex using current source, live npm registry metadata, and isolated npx/Runtime Host experiments.

[me2seeks]

I’m working on this.

我正在推进这项工作。