maka-agent 0.2.0-dev.22.20260905 → 0.2.0-dev.24.20260907

package/dist/runtime-host-cli-context.js

@@ -16,13 +16,16 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+import { activateLocalManagedRuntimeHost } from './runtime-host-local-managed-activation.js';
 import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { NO_REAL_CONNECTION_CODE } from '@maka/core/connection-error-copy';
-import { connectOrSpawnRuntimeHost, connectRuntimeHostProfile, createClientRuntimeHostProfileCatalog, createRuntimeHostPeerClientFromEnvironment, createRuntimeHostReconnectingConnection, loadOrCreateRuntimeHostClientInstanceId, LOCAL_RUNTIME_HOST_PROFILE, readRuntimeHostConnectionCatalog, RuntimeHostPermanentReconnectError, runtimeHostStartupError, } from '@maka/runtime-host/client';
-import { INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, RUNTIME_HOST_COMPATIBILITY_EPOCH, RUNTIME_HOST_PROTOCOL_VERSION, } from '@maka/runtime-host/protocol';
-import { readLocalHostDeploymentRecord } from '@maka/runtime-host/operator';
+import { connectOrSpawnRuntimeHost, connectRuntimeHost, connectRuntimeHostProfile, createClientRuntimeHostProfileCatalog, createRuntimeHostPeerClientFromEnvironment, createRuntimeHostReconnectingConnection, loadOrCreateRuntimeHostClientInstanceId, LOCAL_RUNTIME_HOST_PROFILE, readRuntimeHostConnectionCatalog, RuntimeHostPermanentReconnectError, RuntimeHostRemoteCompatibilityError, runHostHandoff, runtimeHostStartupError, } from '@maka/runtime-host/client';
+import { INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, RUNTIME_HOST_PROTOCOL_VERSION, } from '@maka/runtime-host/protocol';
+import { readLocalHostDeploymentRecord, resolveRuntimeHostManagedDeploymentAuthority, } from '@maka/runtime-host/operator';
 import { resolveMakaClientDataRoot } from '@maka/storage/workspace-root';
+import { isTemporaryNpxInstallation, resolveRuntimeHostNpmGlobalInstallation, } from './runtime-host-cli-installation.js';
+import { restartRuntimeHostNpmGlobalDeployment, runtimeHostNpmGlobalSourceRetirementAvailable, } from './runtime-host-local-handoff.js';
 /**
  * The mode a new Session starts in belongs to the Host: `session.create`
  * falls back to `chatDefaults.permissionMode` in the Runtime Policy whenever a
@@ -42,17 +45,6 @@ import { resolveMakaClientDataRoot } from '@maka/storage/workspace-root';
 export async function readHostChatDefaultPermissionMode(connection) {
     return (await connection.request('runtime.policy.query', {})).policy.chatDefaults.permissionMode;
 }
-export class RuntimeHostCliConflictError extends RuntimeHostPermanentReconnectError {
-    handshake;
-    registration;
-    code = 'RUNTIME_HOST_RESTART_REQUIRED';
-    constructor(handshake, registration) {
-        super(formatRuntimeHostCliConflict(handshake, registration));
-        this.handshake = handshake;
-        this.registration = registration;
-        this.name = 'RuntimeHostCliConflictError';
-    }
-}
 export async function connectRuntimeHostCli(input, overrides = {}) {
     const context = await connectRuntimeHostCliConnection(input, overrides);
     try {
@@ -67,12 +59,19 @@ export async function connectRuntimeHostCli(input, overrides = {}) {
 export async function connectRuntimeHostCliConnection(input, overrides = {}) {
     const deps = {
         connectOrSpawn: connectOrSpawnRuntimeHost,
+        activateLocalManagedHost: activateLocalManagedRuntimeHost,
+        connectActivatedHost: connectRuntimeHost,
         connectProfile: connectRuntimeHostProfile,
         readConnectionCatalog: readRuntimeHostConnectionCatalog,
         loadClientInstanceId: loadOrCreateRuntimeHostClientInstanceId,
         executionCandidateEntrypoint: new URL(import.meta.resolve('@maka/runtime-host/execution-candidate-main')),
         readDeploymentRecord: readLocalHostDeploymentRecord,
+        resolveManagedAuthority: resolveRuntimeHostManagedDeploymentAuthority,
         createPeerClient: createRuntimeHostPeerClientFromEnvironment,
+        resolveInstallation: resolveRuntimeHostNpmGlobalInstallation,
+        isTemporaryNpxInstallation,
+        restartDeployment: restartRuntimeHostNpmGlobalDeployment,
+        sourceRetirementAvailable: runtimeHostNpmGlobalSourceRetirementAvailable,
         ...overrides,
     };
     const resolvedProfile = await resolveHostProfile(input, deps);
@@ -83,45 +82,171 @@ export async function connectRuntimeHostCliConnection(input, overrides = {}) {
     const peerClient = profile.kind === 'remote' && profile.transport.kind === 'libp2p-direct'
         ? deps.createPeerClient()
         : undefined;
+    // A temporary package is evidence for invocation lifetime, never deployment
+    // authority. This only guards candidates we create; using an existing Host
+    // leaves that Host's ownership and lifetime unchanged.
+    const invocationOwned = profile.kind === 'local' && (await deps.isTemporaryNpxInstallation());
     const connectInput = {
         rootPath: input.rootPath,
         protocol: { min: RUNTIME_HOST_PROTOCOL_VERSION, max: RUNTIME_HOST_PROTOCOL_VERSION },
         clientInstanceId,
         compositionId: INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID,
         candidateEntrypoint: deps.executionCandidateEntrypoint,
+        ...(invocationOwned ? { closeOnLauncherExit: true } : {}),
     };
     const connect = async (signal, sshInteraction = 'batch') => {
-        if (profile.kind !== 'local') {
-            return deps.connectProfile({
-                profile,
-                ...(resolvedProfile.credential ? { credential: resolvedProfile.credential } : {}),
-                clientInstanceId,
-                sshInteraction,
-                ...(peerClient ? { peerClient } : {}),
+        const observe = async () => {
+            if (profile.kind !== 'local') {
+                try {
+                    const connection = await deps.connectProfile({
+                        profile,
+                        ...(resolvedProfile.credential ? { credential: resolvedProfile.credential } : {}),
+                        clientInstanceId,
+                        sshInteraction,
+                        ...(peerClient ? { peerClient } : {}),
+                        ...(signal ? { signal } : {}),
+                    });
+                    return { kind: 'ready', value: connection };
+                }
+                catch (error) {
+                    if (!(error instanceof RuntimeHostRemoteCompatibilityError))
+                        throw error;
+                    return {
+                        kind: 'blocked',
+                        blocker: {
+                            identity: JSON.stringify([profile, error.hostEpoch, error.details]),
+                            target: {
+                                name: profile.name,
+                                location: 'remote',
+                                rootId: profile.rootId,
+                                hostEpoch: error.hostEpoch,
+                            },
+                            reason: 'upgrade',
+                            mayExitNaturally: false,
+                            diagnostic: error.message,
+                        },
+                    };
+                }
+            }
+            let connected = await deps.connectOrSpawn({
+                ...connectInput,
                 ...(signal ? { signal } : {}),
             });
-        }
-        const connected = await deps.connectOrSpawn({
-            ...connectInput,
-            ...(signal ? { signal } : {}),
-        });
-        if (connected.kind === 'incompatible') {
-            throw new RuntimeHostCliConflictError(connected.handshake, connected.registration);
-        }
-        if (connected.kind === 'upgrade_required') {
-            throw new RuntimeHostPermanentReconnectError('RUNTIME_HOST_RESTART_REQUIRED: An older Runtime Host build is still running. Restart it, or wait for its background work to finish.');
-        }
-        if (connected.kind === 'failed') {
-            throw runtimeHostStartupError(connected.reason, connected.diagnostic);
-        }
-        if (connected.registration.generation?.startsWith('npm-global-handoff:')) {
-            const record = await deps.readDeploymentRecord(connected.registration.rootId);
-            if (record?.state.kind !== 'owned' || record.state.owner.kind !== 'cli') {
-                await connected.connection.close().catch(() => undefined);
-                throw new RuntimeHostPermanentReconnectError('RUNTIME_HOST_RECOVERY_REQUIRED: The staged local Runtime Host is Ready, but its installation ownership was not durably committed.');
+            if (connected.kind === 'failed' && connected.reason === 'managed_root_requires_operator') {
+                await deps.activateLocalManagedHost({
+                    rootPath: input.rootPath,
+                    ...(signal ? { signal } : {}),
+                });
+                signal?.throwIfAborted();
+                // The installed operator owns launch. Compatibility is still projected
+                // by the same handoff journey as an already-running managed Host.
+                const activated = await deps.connectActivatedHost(connectInput);
+                if (activated.kind === 'unavailable' || activated.kind === 'draining') {
+                    throw new Error(`The installed Runtime Host was activated but the local CLI could not join it (${activated.kind === 'unavailable' ? activated.reason : activated.kind}). Use a compatible CLI or update the managed Host through its configured operator.`);
+                }
+                if (activated.kind === 'connected' && signal?.aborted) {
+                    await activated.connection.close();
+                    signal.throwIfAborted();
+                }
+                connected = activated;
             }
-        }
-        return connected.connection;
+            if (connected.kind === 'incompatible' || connected.kind === 'upgrade_required') {
+                const managed = await deps.resolveManagedAuthority(connected.registration.rootId);
+                const record = managed
+                    ? undefined
+                    : await deps.readDeploymentRecord(connected.registration.rootId);
+                let replacement;
+                let installation;
+                // On-demand managed Hosts are also ephemeral processes. Their durable
+                // operator authority, not the process lifetime label, decides who may
+                // replace them (including when the Host was already running).
+                if (!managed && connected.registration.lifecycleMode === 'ephemeral') {
+                    try {
+                        installation = await deps.resolveInstallation();
+                    }
+                    catch {
+                        /* No persistent installation authority. */
+                    }
+                    const owner = record?.state.kind === 'handoff' ? record.state.from : record?.state.owner;
+                    if (installation &&
+                        (!owner ||
+                            (owner.kind === installation.owner.kind &&
+                                owner.installationId === installation.owner.installationId))) {
+                        const expectedInstallation = installation;
+                        const canInterrupt = record
+                            ? await deps
+                                .sourceRetirementAvailable({
+                                rootId: connected.registration.rootId,
+                                owner: installation.owner,
+                                source: record.state.selected,
+                            })
+                                .catch(() => false)
+                            : false;
+                        replacement = {
+                            kind: record?.state.kind === 'handoff' ? 'repair' : 'replace',
+                            canReplaceIdle: true,
+                            canInterrupt,
+                            execute: async (activeWorkPolicy, _progress, _consent, attemptSignal) => {
+                                const result = await deps.restartDeployment({
+                                    rootPath: input.rootPath,
+                                    registration: connected.registration,
+                                    activeWorkPolicy,
+                                    expectedInstallation,
+                                    ...(attemptSignal ? { signal: attemptSignal } : {}),
+                                });
+                                if (result.kind === 'completed')
+                                    return { kind: 'completed' };
+                                if (result.kind === 'active_work')
+                                    return { kind: 'active_work' };
+                                if (result.kind === 'changed' ||
+                                    result.kind === 'rejected' ||
+                                    result.kind === 'operator_required')
+                                    return { kind: 'changed' };
+                                return {
+                                    kind: 'recovery_required',
+                                    diagnostic: `Local service recovery is required at ${result.phase}`,
+                                };
+                            },
+                        };
+                    }
+                }
+                return {
+                    kind: 'blocked',
+                    blocker: {
+                        identity: JSON.stringify([
+                            connected.registration,
+                            managed?.record,
+                            record,
+                            installation,
+                        ]),
+                        target: {
+                            name: profile.name,
+                            location: 'local',
+                            rootId: connected.registration.rootId,
+                            hostEpoch: connected.registration.hostEpoch,
+                        },
+                        reason: record?.state.kind === 'handoff' ? 'repair' : 'upgrade',
+                        ...(connected.handshake?.activity ? { activity: connected.handshake.activity } : {}),
+                        mayExitNaturally: !managed &&
+                            connected.registration.lifecycleMode === 'ephemeral' &&
+                            connected.handshake?.replacement === 'wait_for_idle_exit',
+                        ...(replacement ? { replacement } : {}),
+                    },
+                };
+            }
+            if (connected.kind === 'failed') {
+                throw runtimeHostStartupError(connected.reason, connected.diagnostic);
+            }
+            if (connected.registration.generation?.startsWith('npm-global-handoff:')) {
+                const record = await deps.readDeploymentRecord(connected.registration.rootId);
+                if (record?.state.kind !== 'owned' || record.state.owner.kind !== 'cli') {
+                    await connected.connection.close().catch(() => undefined);
+                    throw new RuntimeHostPermanentReconnectError('RUNTIME_HOST_RECOVERY_REQUIRED: The staged local Runtime Host is Ready, but its installation ownership was not durably committed.');
+                }
+            }
+            return { kind: 'ready', value: connected.connection };
+        };
+        return runHostHandoff({ observe, signal, openSurface: input.handoffSurface });
     };
     let initialConnection;
     let connection;
@@ -222,42 +347,6 @@ async function resolveHostProfile(input, deps) {
     const catalog = deps.profileCatalog ?? createClientRuntimeHostProfileCatalog(root);
     return catalog.resolve(input.profileId);
 }
-function formatRuntimeHostCliConflict(handshake, registration) {
-    const lines = [
-        'RUNTIME_HOST_RESTART_REQUIRED: An older Runtime Host is still running and cannot accept this client.',
-        `Local Runtime Host: PID ${registration.pid}; lifecycle ${registration.lifecycleMode ?? 'unknown'}; compatibility epoch ${registration.compatibilityEpoch}.`,
-    ];
-    if (registration.lifecycleMode === 'ephemeral') {
-        lines.push('The ephemeral Host is not currently idle and cannot be replaced by this Client.');
-    }
-    else if (registration.lifecycleMode === 'service') {
-        lines.push('This service Host is managed by its operator and cannot be replaced by this Client.');
-    }
-    else {
-        lines.push('This Host cannot be replaced by this Client.');
-    }
-    if (handshake.compatibilityEpoch < RUNTIME_HOST_COMPATIBILITY_EPOCH) {
-        lines.push(registration.lifecycleMode === 'service'
-            ? 'Use the service operator to inspect or upgrade the Host.'
-            : 'Use a previous compatible Maka build to inspect the Host and finish or clear any retained work. Stop the Host only after deciding that interruption is safe.');
-    }
-    else {
-        lines.push(`Host protocol ${handshake.protocolMin}-${handshake.protocolMax}; CLI protocol ${RUNTIME_HOST_PROTOCOL_VERSION}.`);
-    }
-    return lines.join('\n');
-}
-export function shouldRetryRuntimeHostConflict(answer) {
-    const normalized = answer.trim().toLowerCase();
-    return normalized === 'w' || normalized === 'wait';
-}
-export function resolveRuntimeHostCliConflictDecision(answer, canRestart) {
-    const normalized = answer.trim().toLowerCase();
-    if (canRestart && (normalized === 'r' || normalized === 'restart'))
-        return 'restart';
-    if (normalized === 'w' || normalized === 'wait')
-        return 'wait';
-    return 'cancel';
-}
 export function resolveRuntimeHostCliTarget(catalog, input = {}) {
     const defaultTarget = catalog.defaultTarget;
     const connection = input.connectionSlug

package/dist/runtime-host-cli-installation.js

@@ -76,9 +76,15 @@ export async function resolveRuntimeHostNpmGlobalInstallation(options = {}, over
         observedRelease: { version: manifest.version, packageRoot, cliPath },
     };
 }
-export async function isTemporaryNpxInstallation(path, input) {
+export async function isTemporaryNpxInstallation(path = fileURLToPath(new URL('../', import.meta.url)), input = { environment: process.env, homeDir: homedir() }) {
     const canonicalPath = await realpath(path).catch(() => resolve(path));
-    const cacheRoots = await Promise.all([input.environment.npm_config_cache, join(input.homeDir, '.npm')].flatMap((root) => root ? [realpath(resolve(root, '_npx')).catch(() => resolve(root, '_npx'))] : []));
+    const defaultCache = (input.platform ?? process.platform) === 'win32'
+        ? join(input.environment.LOCALAPPDATA || input.homeDir, 'npm-cache')
+        : join(input.homeDir, '.npm');
+    const cacheRoots = await Promise.all([
+        input.environment.npm_config_cache ?? input.environment.NPM_CONFIG_CACHE,
+        defaultCache,
+    ].flatMap((root) => root ? [realpath(resolve(root, '_npx')).catch(() => resolve(root, '_npx'))] : []));
     return cacheRoots.some((root) => isWithin(root, canonicalPath));
 }
 async function readPackageManifest(url) {

package/dist/runtime-host-cli.js

@@ -136,6 +136,10 @@ function parseLocalUpdateApply(argv) {
         '--target-version',
         '--target-integrity',
         '--target-compatibility',
+        '--expected-root-id',
+        '--expected-deployment-revision',
+        '--expected-owner-installation-id',
+        '--expected-host-epoch',
     ]);
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
@@ -195,6 +199,28 @@ function parseLocalUpdateApply(argv) {
         (!Number.isSafeInteger(targetCompatibility) || targetCompatibility <= 0)) {
         return error('runtime-host local-update-apply compatibility is invalid');
     }
+    const expectedValues = [
+        '--expected-root-id',
+        '--expected-deployment-revision',
+        '--expected-owner-installation-id',
+        '--expected-host-epoch',
+    ].map((name) => values.get(name));
+    let expectedSource;
+    if (expectedValues.some((value) => value !== undefined)) {
+        if (!expectedValues.every((value) => value !== undefined && isSafeIdentity(value))) {
+            return error('runtime-host local-update-apply requires one complete expected source identity');
+        }
+        const [rootId, deploymentRevision, ownerInstallationId, hostEpoch] = expectedValues;
+        if (!/^[a-f0-9]{64}$/u.test(rootId)) {
+            return error('runtime-host local-update-apply expected Root identity is invalid');
+        }
+        expectedSource = {
+            rootId: rootId,
+            deploymentRevision: deploymentRevision,
+            ownerInstallationId: ownerInstallationId,
+            hostEpoch: hostEpoch,
+        };
+    }
     return {
         kind: 'runtime-host-local-update-apply',
         rootPath,
@@ -206,6 +232,7 @@ function parseLocalUpdateApply(argv) {
         targetIntegrity,
         ...(targetCompatibility === undefined ? {} : { targetCompatibility }),
         allowInterruptActiveTasks,
+        ...(expectedSource ? { expectedSource } : {}),
     };
 }
 function parseLocalUpdateActivate(argv) {
@@ -553,7 +580,7 @@ function parseServiceManagementCommand(argv) {
                     },
                 }
                 : {}),
-            ...(action === 'update'
+            ...(action === 'update' || action === 'restart'
                 ? {
                     '--expected-host-json': (value) => {
                         if (expectedHost !== undefined)
@@ -675,10 +702,13 @@ function parseServiceManagementCommand(argv) {
             ...(allowInterruptActiveTasks ? { allowInterruptActiveTasks: true } : {}),
         };
     }
+    if (expectedHost && !options.managedRootId)
+        return error('--expected-host-json requires --managed-root-id');
     return {
         kind: 'runtime-host-service-manage',
         action,
         ...options,
+        ...(expectedHost ? { expectedHost } : {}),
         ...(clientDataRoot ? { clientDataRoot } : {}),
         ...(options.managedRootId ? { managedRootId: options.managedRootId } : {}),
         ...(retainManagedDeployment ? { retainManagedDeployment: true } : {}),

package/dist/runtime-host-handoff-surface.js

@@ -0,0 +1,81 @@
+/*
+ * 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 { createInterface } from 'node:readline';
+import { stripVTControlCharacters } from 'node:util';
+import { formatHostHandoff, } from '@maka/runtime-host/client';
+/** One readline lifetime renders the shared decision; it never selects replacement policy. */
+export function createCliHostHandoffSurface(locale, input = process.stdin, output = process.stderr) {
+    return (submit) => {
+        const readline = createInterface({ input, output, terminal: output.isTTY === true });
+        let current;
+        let closed = false;
+        let ended = false;
+        const cancel = () => {
+            if (current)
+                submit(current.revision, 'cancel');
+        };
+        readline.on('SIGINT', cancel);
+        readline.on('close', () => {
+            ended = true;
+            if (!closed)
+                cancel();
+        });
+        readline.on('line', (line) => {
+            if (!current)
+                return;
+            const answer = line.trim().toLowerCase();
+            const action = answer === 'r' ? 'retry' : answer === 'stop' ? 'interrupt' : 'cancel';
+            if (!current.actions.includes(action)) {
+                readline.prompt();
+                return;
+            }
+            submit(current.revision, action);
+        });
+        return {
+            update(view) {
+                if (closed || current?.revision === view.revision)
+                    return;
+                current = view;
+                if (ended) {
+                    cancel();
+                    return;
+                }
+                // Discard partially typed consent when the observed target/consequences change.
+                if (output.isTTY)
+                    readline.write(null, { ctrl: true, name: 'u' });
+                const copy = formatHostHandoff(view, locale);
+                const text = [copy.title, copy.description, copy.detail, view.diagnostic]
+                    .filter(Boolean)
+                    .join('\n');
+                output.write('\n' +
+                    stripVTControlCharacters(text).replace(/[\p{Cc}\p{Cf}]/gu, (character) => character === '\n' ? character : '\uFFFD') +
+                    '\n');
+                if (view.actions.length === 0)
+                    return;
+                const options = copy.actions.map(({ action, label }) => `${action === 'interrupt' ? 'stop' : action === 'retry' ? 'r' : 'Enter'}: ${label}`);
+                readline.setPrompt(options.join(' · ') + ' > ');
+                readline.prompt();
+            },
+            close() {
+                closed = true;
+                readline.close();
+            },
+        };
+    };
+}

package/dist/runtime-host-installed-update-bootstrap.js

@@ -64,6 +64,7 @@ export async function runRuntimeHostInstalledUpdateBootstrap(input, overrides =
                     ? {}
                     : { targetCompatibility: target.compatibility }),
                 allowInterruptActiveTasks: input.allowInterruptActiveTasks,
+                ...(input.expectedSource ? { expectedSource: input.expectedSource } : {}),
             });
         }
         finally {
@@ -94,6 +95,18 @@ function launchCoordinator(input) {
             ? []
             : ['--target-compatibility', String(input.targetCompatibility)]),
         ...(input.allowInterruptActiveTasks ? ['--allow-interrupt-active-tasks'] : []),
+        ...(input.expectedSource
+            ? [
+                '--expected-root-id',
+                input.expectedSource.rootId,
+                '--expected-deployment-revision',
+                input.expectedSource.deploymentRevision,
+                '--expected-owner-installation-id',
+                input.expectedSource.ownerInstallationId,
+                '--expected-host-epoch',
+                input.expectedSource.hostEpoch,
+            ]
+            : []),
     ];
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, args, { stdio: 'inherit', windowsHide: false });

package/dist/runtime-host-installed-update-coordinator.js

@@ -22,6 +22,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { connectExistingRuntimeHost, prepareConnectedRuntimeHostRetirement, waitForRuntimeHostReady, } from '@maka/runtime-host/client';
+import { resolveRuntimeHostManagedDeploymentAuthority, } from '@maka/runtime-host/operator';
 import { INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, RUNTIME_HOST_PROTOCOL_VERSION, } from '@maka/runtime-host/protocol';
 import { resolveStorageRoot } from '@maka/storage/root-authority';
 import { prepareRuntimeHostNpmGlobalStagedDeployment, reconcilePreparedRuntimeHostNpmGlobalDeployment, } from './runtime-host-local-handoff.js';
@@ -35,6 +36,7 @@ export async function runRuntimeHostInstalledUpdateCoordinator(input, authorityO
     const deps = {
         resolveInstallation: resolveRuntimeHostNpmGlobalInstallation,
         resolveRoot: resolveStorageRoot,
+        resolveManagedAuthority: resolveRuntimeHostManagedDeploymentAuthority,
         connectExisting: connectExistingRuntimeHost,
         waitForReady: waitForRuntimeHostReady,
         prepareRetirement: prepareConnectedRuntimeHostRetirement,
@@ -54,6 +56,14 @@ export async function runRuntimeHostInstalledUpdateCoordinator(input, authorityO
         throw new Error(`The installed Maka release changed from ${input.currentVersion} to ${installation.observedRelease.version} before update coordination`);
     }
     const root = await deps.resolveRoot({ path: input.rootPath, kind: 'interactive' });
+    if (input.expectedSource &&
+        (root.rootId !== input.expectedSource.rootId ||
+            installation.owner.installationId !== input.expectedSource.ownerInstallationId)) {
+        throw new Error('The observed local Host installation owner changed before update.');
+    }
+    if (await deps.resolveManagedAuthority(root.rootId)) {
+        throw new Error('The managed Runtime Host must be updated through its installed operator.');
+    }
     const transactionId = updateTransactionId(root.rootId, installation, input.target);
     return deps.withArchive(input.target, input.archivePath, async ({ packageRoot, archivePath }) => {
         const staged = await deps.prepareStaged({
@@ -90,7 +100,19 @@ export async function runRuntimeHostInstalledUpdateCoordinator(input, authorityO
             return 'target_present';
         };
         const prepare = async (inheritableAuthorityLeaseFd) => {
+            if (await deps.resolveManagedAuthority(root.rootId)) {
+                throw new Error('The managed Runtime Host must be updated through its installed operator.');
+            }
             observation = await observeCurrentHost(input.rootPath, root.rootId, deps);
+            // This callback runs under the existing deployment-authority lease.
+            // Do not turn the TUI's consent for one observed Host into retirement of
+            // a successor that appeared while the archive/coordinator was prepared.
+            if (input.expectedSource &&
+                observation.registration?.hostEpoch !== input.expectedSource.hostEpoch) {
+                await observation.connection?.close();
+                observation = {};
+                throw new Error('The observed Runtime Host changed before update retirement.');
+            }
             if (observation.registration && observation.registration.lifecycleMode !== 'ephemeral') {
                 throw new Error('Only an ephemeral local Runtime Host can be updated by this CLI');
             }
@@ -149,6 +171,17 @@ export async function runRuntimeHostInstalledUpdateCoordinator(input, authorityO
                     : 'refuse_active_work',
                 installation,
                 staged,
+                ...(input.expectedSource
+                    ? {
+                        expectedOwner: {
+                            revision: input.expectedSource.deploymentRevision,
+                            owner: {
+                                kind: 'cli',
+                                installationId: input.expectedSource.ownerInstallationId,
+                            },
+                        },
+                    }
+                    : {}),
             }, {
                 prepareUnownedHostCutover: (_rootId, _target, _staged, _policy, leaseFd) => prepare(leaseFd),
                 prepareHostCutover: (_rootId, _selected, _target, _staged, _policy, leaseFd) => prepare(leaseFd),

package/dist/runtime-host-lifecycle-transaction.js

@@ -17,6 +17,7 @@
  * under the License.
  */
 import { randomUUID } from 'node:crypto';
+import { withOperatorRetirementCancellation } from './runtime-host-operator-retirement.js';
 import { isDeepStrictEqual } from 'node:util';
 import { resolveExistingStorageRoot, tryAcquireStateRootOwner, } from '@maka/storage/root-authority';
 import { connectExistingRuntimeHost, prepareConnectedRuntimeHostRetirement, RuntimeHostOperationError, RuntimeHostRequestInterruptedError, waitForRuntimeHostReady, } from '@maka/runtime-host/client';
@@ -173,6 +174,10 @@ function assertRecoveryTarget(expected, rootId, record) {
     }
 }
 export async function retireRuntimeHostLifecycleOwner(input) {
+    return withOperatorRetirementCancellation((signal) => retireRuntimeHostLifecycleOwnerWithSignal(input, signal));
+}
+async function retireRuntimeHostLifecycleOwnerWithSignal(input, signal) {
+    signal?.throwIfAborted();
     if (input.expectedOwner && !input.supervisor) {
         throw new RuntimeHostLifecycleTransactionError('owner_changed', 'A Runtime Host identity fence requires a supervised deployment');
     }
@@ -188,6 +193,7 @@ export async function retireRuntimeHostLifecycleOwner(input) {
                 const status = await input.supervisor.status();
                 assertExpectedSupervisorOwner(input.expectedOwner, status);
             }
+            signal?.throwIfAborted();
             if (input.retireIdleSupervisor !== false)
                 await input.supervisor?.retire();
             return { kind: 'retired', owner: idleOwner };
@@ -212,6 +218,7 @@ export async function retireRuntimeHostLifecycleOwner(input) {
             if (status.active && status.pid !== null) {
                 if (!input.allowInterruptActiveTasks)
                     return { kind: 'active_tasks' };
+                signal?.throwIfAborted();
                 await input.supervisor.retire();
                 return waitForRuntimeHostLifecycleOwner(capability, input.timeoutMs ?? 45_000);
             }
@@ -234,7 +241,7 @@ export async function retireRuntimeHostLifecycleOwner(input) {
             // The exact Root owner and canonical supervisor now agree while the deployment lock is held.
             // This admits retirement of that deployment; a later same-deployment restart is not a new
             // authority, but it must not acquire the Root before the supervisor is retired.
-            const prepared = await prepareConnectedRuntimeHostRetirement(connected.connection, input.allowInterruptActiveTasks ? 'interrupt_active_work' : 'refuse_active_work');
+            const prepared = await prepareConnectedRuntimeHostRetirement(connected.connection, input.allowInterruptActiveTasks ? 'interrupt_active_work' : 'refuse_active_work', undefined, signal);
             if (prepared.kind === 'active_tasks')
                 return prepared;
             if (prepared.pid !== diagnostics.pid) {
@@ -242,6 +249,7 @@ export async function retireRuntimeHostLifecycleOwner(input) {
             }
         }
         catch (error) {
+            signal?.throwIfAborted();
             if (!isRuntimeHostRetirementUnavailable(error) || !input.supervisor)
                 throw error;
             if (!input.allowInterruptActiveTasks)