feat(cli): coordinate npm-global Runtime Host updates

packages/cli/README.md

@@ -106,13 +106,16 @@ modify.
 While using prereleases, keep the `next` tag explicit:
 
 ```sh
-npm install --global maka-agent@next
+maka update --target next
 maka --version
 ```
 
-Do not use a bare `npm update --global maka-agent` for beta upgrades: global npm updates follow the
-`latest` tag and may select a different release line. After a stable release is available, install it
-with `npm install --global maka-agent@latest`.
+The update stages and verifies the exact release before replacing the local Runtime Host or the
+npm-global package. It refuses to interrupt active or durable work by default. Use
+`--allow-interrupt-active-tasks` only after deciding that interruption is safe. A direct
+`npm install --global maka-agent@next` remains available for installation repair; do not use a bare
+`npm update --global maka-agent`, because it follows `latest` and may select a different release
+line. After a stable release is available, select it with `maka update --target latest`.
 
 ## Remote Runtime Host setup
 

packages/cli/README.zh-CN.md

@@ -99,13 +99,15 @@ Maka 默认会在执行高权限工具操作前询问。`maka run --yolo` 会授
 使用预发布版本时，请继续明确指定 `next`：
 
 ```sh
-npm install --global maka-agent@next
+maka update --target next
 maka --version
 ```
 
-Beta 升级不要使用不带 tag 的 `npm update --global maka-agent`：npm 的全局更新会跟随
-`latest`，可能选中不同的发布线。稳定版发布后，使用
-`npm install --global maka-agent@latest` 安装。
+更新流程会先 stage 并验证精确 release，再替换本地 Runtime Host 与 npm-global package；
+默认不会中断 active 或 durable work。只有在你确认可以安全中断后，才使用
+`--allow-interrupt-active-tasks`。`npm install --global maka-agent@next` 仍可用于修复安装；
+不要使用不带 tag 的 `npm update --global maka-agent`，因为它会跟随 `latest`，可能选中
+不同的发布线。稳定版发布后，使用 `maka update --target latest`。
 
 ## 设置远程 Runtime Host
 

packages/cli/src/__tests__/cli.test.ts

@@ -51,6 +51,7 @@ describe('Maka CLI args', () => {
     assert.match(help.text, /^  maka run /m);
     assert.match(help.text, /^  maka activate /m);
     assert.match(help.text, /^  maka eval /m);
+    assert.match(help.text, /^  maka update --target /m);
     assert.match(
       help.text,
       /^  maka --acp      Serve ACP v1 over stdio \(initialize only; session support in progress\)$/m,
@@ -59,6 +60,27 @@ describe('Maka CLI args', () => {
     assert.doesNotMatch(help.text, /cli:dev/);
   });
 
+  test('requires an explicit installed update target and interruption choice', () => {
+    assert.deepEqual(parseMakaCliArgs(['update', '--target', 'next'], '0.1.0'), {
+      kind: 'runtime-host-installed-update',
+      selector: { kind: 'channel', channel: 'next' },
+      allowInterruptActiveTasks: false,
+    });
+    assert.deepEqual(
+      parseMakaCliArgs(['update', '--target', '1.2.3', '--allow-interrupt-active-tasks'], '0.1.0'),
+      {
+        kind: 'runtime-host-installed-update',
+        selector: { kind: 'exact', version: '1.2.3' },
+        allowInterruptActiveTasks: true,
+      },
+    );
+    assert.deepEqual(parseMakaCliArgs(['update'], '0.1.0'), {
+      kind: 'error',
+      message: 'update requires --target <latest|next|version>',
+      exitCode: 2,
+    });
+  });
+
   test('selects a Runtime Host and Project for TUI startup', () => {
     assert.deepEqual(parseMakaCliArgs(['--host', 'office', '--project', 'project-1'], '0.1.0'), {
       kind: 'tui',

packages/cli/src/__tests__/runtime-host-installed-update-activator.test.ts

@@ -0,0 +1,204 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID,
+  RUNTIME_HOST_COMPATIBILITY_EPOCH,
+  RUNTIME_HOST_PROTOCOL_VERSION,
+  RUNTIME_HOST_REGISTRATION_SCHEMA_VERSION,
+  type HostRegistration,
+} from '@maka/runtime-host/protocol';
+import { runRuntimeHostInstalledUpdateActivator } from '../runtime-host-installed-update-activator.js';
+
+const ROOT_ID = 'a'.repeat(64);
+
+test('accepts Ready evidence only from the exact target generation and process', async () => {
+  let closed = false;
+  const exitCode = await runRuntimeHostInstalledUpdateActivator(
+    {
+      rootPath: '/state',
+      expectedRootId: ROOT_ID,
+      generation: 'target-generation',
+      candidateEntrypoint: '/staged/candidate.js',
+      takeoverHostEpoch: 'old-host',
+    },
+    {
+      connectOrSpawn: async (input) => ({
+        kind: 'connected',
+        registration: registration({
+          hostEpoch: 'target-host',
+          pid: 84,
+          generation: input.generation,
+        }),
+        spawnedProcess: { pid: 84, exited: new Promise(() => undefined) },
+        connection: {
+          close: async () => {
+            closed = true;
+          },
+        } as never,
+      }),
+    },
+  );
+  assert.equal(exitCode, 0);
+  assert.equal(closed, true);
+});
+
+test('reports active work and operator-owned lifecycle without forcing takeover', async () => {
+  const active = await runRuntimeHostInstalledUpdateActivator(
+    {
+      rootPath: '/state',
+      expectedRootId: ROOT_ID,
+      generation: 'target-generation',
+      candidateEntrypoint: '/staged/candidate.js',
+      takeoverHostEpoch: 'old-host',
+    },
+    {
+      connectOrSpawn: async () => ({
+        kind: 'upgrade_required',
+        registration: registration(),
+        restartable: false,
+      }),
+    },
+  );
+  assert.equal(active, 3);
+
+  const service = await runRuntimeHostInstalledUpdateActivator(
+    {
+      rootPath: '/state',
+      expectedRootId: ROOT_ID,
+      generation: 'target-generation',
+      candidateEntrypoint: '/staged/candidate.js',
+      takeoverHostEpoch: 'old-host',
+    },
+    {
+      connectOrSpawn: async () => ({
+        kind: 'upgrade_required',
+        registration: registration({ lifecycleMode: 'service' }),
+        restartable: false,
+      }),
+    },
+  );
+  assert.equal(service, 4);
+});
+
+test('keeps the short-lived activator through the coordinator durable-commit boundary', async () => {
+  let closed = false;
+  let observedExpectation:
+    | {
+        readonly expectedRootId: string;
+        readonly ownerInstallationId: string;
+        readonly targetVersion: string;
+        readonly targetIntegrity: string;
+      }
+    | undefined;
+  const exitCode = await runRuntimeHostInstalledUpdateActivator(
+    {
+      rootPath: '/state',
+      expectedRootId: ROOT_ID,
+      generation: 'target-generation',
+      candidateEntrypoint: '/staged/candidate.js',
+      awaitCoordinatorCommit: true,
+      expectedOwnerInstallationId: 'npm-global:slot',
+      targetVersion: '2.0.0',
+      targetIntegrity: `sha512-${Buffer.alloc(64, 4).toString('base64')}`,
+    },
+    {
+      connectOrSpawn: async () => ({
+        kind: 'connected',
+        registration: registration({ generation: 'target-generation', pid: 84 }),
+        spawnedProcess: { pid: 84, exited: new Promise(() => undefined) },
+        connection: { close: async () => (closed = true) } as never,
+      }),
+      awaitCoordinatorCommit: async (input) => {
+        observedExpectation = {
+          expectedRootId: input.expectedRootId,
+          ownerInstallationId: input.ownerInstallationId,
+          targetVersion: input.targetVersion,
+          targetIntegrity: input.targetIntegrity,
+        };
+      },
+    },
+  );
+  assert.equal(exitCode, 0);
+  assert.equal(closed, true);
+  assert.deepEqual(observedExpectation, {
+    expectedRootId: ROOT_ID,
+    ownerInstallationId: 'npm-global:slot',
+    targetVersion: '2.0.0',
+    targetIntegrity: `sha512-${Buffer.alloc(64, 4).toString('base64')}`,
+  });
+});
+
+test('fails closed through the authenticated connection when its coordinator channel is absent', async () => {
+  let retirement:
+    | { readonly hostEpoch: string; readonly mode: 'refuse_active_work' | 'interrupt_active_work' }
+    | undefined;
+  await assert.rejects(
+    runRuntimeHostInstalledUpdateActivator(
+      {
+        rootPath: '/state',
+        expectedRootId: ROOT_ID,
+        generation: 'target-generation',
+        candidateEntrypoint: '/staged/candidate.js',
+        awaitCoordinatorCommit: true,
+        expectedOwnerInstallationId: 'npm-global:slot',
+        targetVersion: '2.0.0',
+        targetIntegrity: `sha512-${Buffer.alloc(64, 4).toString('base64')}`,
+      },
+      {
+        connectOrSpawn: async () => ({
+          kind: 'connected',
+          registration: registration({ generation: 'target-generation', pid: 84 }),
+          connection: {
+            hostEpoch: 'target-host',
+            close: async () => {},
+          } as never,
+        }),
+        retireTarget: async (connection, mode) => {
+          retirement = { hostEpoch: connection.hostEpoch, mode };
+          return { kind: 'prepared', pid: 84 };
+        },
+      },
+    ),
+    /lost its coordinator channel/u,
+  );
+  assert.deepEqual(retirement, { hostEpoch: 'target-host', mode: 'interrupt_active_work' });
+});
+
+function registration(overrides: Partial<HostRegistration> = {}): HostRegistration {
+  return {
+    kind: 'maka-runtime-host',
+    schemaVersion: RUNTIME_HOST_REGISTRATION_SCHEMA_VERSION,
+    rootId: ROOT_ID,
+    hostEpoch: 'old-host',
+    endpoint: '/tmp/maka.sock',
+    protocolMin: RUNTIME_HOST_PROTOCOL_VERSION,
+    protocolMax: RUNTIME_HOST_PROTOCOL_VERSION,
+    compatibilityEpoch: RUNTIME_HOST_COMPATIBILITY_EPOCH,
+    compositionId: INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID,
+    compositionRevision: 'revision',
+    lifecycleMode: 'ephemeral',
+    state: 'ready',
+    pid: 42,
+    createdAt: new Date(0).toISOString(),
+    ...overrides,
+  };
+}

packages/cli/src/__tests__/runtime-host-installed-update-bootstrap.test.ts

@@ -0,0 +1,109 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { runRuntimeHostInstalledUpdateBootstrap } from '../runtime-host-installed-update-bootstrap.js';
+
+const INTEGRITY = `sha512-${Buffer.alloc(64, 9).toString('base64')}`;
+
+test('launches update coordination from a copy outside the mutable npm-global package', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'maka-update-bootstrap-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const packageRoot = join(root, 'global', 'node_modules', 'maka-agent');
+  const cliPath = join(packageRoot, 'dist', 'cli.js');
+  const archivePath = join(root, 'target.tgz');
+  await mkdir(join(packageRoot, 'dist'), { recursive: true });
+  await Promise.all([
+    writeFile(cliPath, '#!/usr/bin/env node\n'),
+    writeFile(archivePath, 'archive'),
+  ]);
+  let launched = false;
+
+  const exitCode = await runRuntimeHostInstalledUpdateBootstrap(
+    {
+      rootPath: join(root, 'state'),
+      selector: { kind: 'channel', channel: 'next' },
+      allowInterruptActiveTasks: true,
+    },
+    {
+      resolveInstallation: async () => ({
+        owner: { kind: 'cli', installationId: 'npm-global:slot' },
+        observedRelease: { version: '1.0.0', packageRoot, cliPath },
+      }),
+      resolveCandidate: async () => ({
+        kind: 'npm_registry',
+        version: '2.0.0',
+        integrity: INTEGRITY,
+        compatibility: 2,
+      }),
+      withArchive: async (_target, use) => use(archivePath),
+      async runCoordinator(input) {
+        launched = true;
+        assert.notEqual(input.coordinatorCliPath, cliPath);
+        assert.equal((await stat(input.coordinatorCliPath)).isFile(), true);
+        assert.equal(input.archivePath, archivePath);
+        assert.equal(input.currentVersion, '1.0.0');
+        assert.equal(input.targetVersion, '2.0.0');
+        assert.equal(input.allowInterruptActiveTasks, true);
+        return 7;
+      },
+    },
+  );
+
+  assert.equal(exitCode, 7);
+  assert.equal(launched, true);
+});
+
+test('rejects unsupported downgrades before package acquisition', async () => {
+  let acquired = false;
+  await assert.rejects(
+    runRuntimeHostInstalledUpdateBootstrap(
+      {
+        rootPath: '/state',
+        selector: { kind: 'exact', version: '1.0.0' },
+        allowInterruptActiveTasks: false,
+      },
+      {
+        resolveInstallation: async () => ({
+          owner: { kind: 'cli', installationId: 'npm-global:slot' },
+          observedRelease: {
+            version: '2.0.0',
+            packageRoot: '/global/maka-agent',
+            cliPath: '/global/maka-agent/dist/cli.js',
+          },
+        }),
+        resolveCandidate: async () => ({
+          kind: 'npm_registry',
+          version: '1.0.0',
+          integrity: INTEGRITY,
+        }),
+        withArchive: async () => {
+          acquired = true;
+          throw new Error('must not acquire');
+        },
+      },
+    ),
+    /Downgrading Maka/u,
+  );
+  assert.equal(acquired, false);
+});