maka-agent 0.2.0-dev.23.20260906 → 0.2.0-dev.25.20260908

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

@@ -0,0 +1,106 @@
+/*
+ * 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 { clearLine, createInterface, cursorTo } from 'node:readline';
+import { stripVTControlCharacters } from 'node:util';
+import { formatHostHandoff, } from '@maka/runtime-host/client';
+/** The surface owns terminal input; replacement policy stays in the shared handoff. */
+export function createCliHostHandoffSurface(locale, input = process.stdin, output = process.stderr) {
+    return (submit) => {
+        let readline;
+        let current;
+        let closed = false;
+        let ended = false;
+        const releaseReader = () => {
+            const previous = readline;
+            readline = undefined;
+            previous?.close();
+        };
+        const cancel = () => {
+            if (current)
+                submit(current.revision, 'cancel');
+        };
+        return {
+            update(view) {
+                if (closed || current?.revision === view.revision)
+                    return;
+                current = view;
+                if (ended) {
+                    cancel();
+                    return;
+                }
+                // A new observation gets a new input buffer. Ctrl+U leaves text after
+                // the cursor intact and is ignored by readline in TERM=dumb.
+                releaseReader();
+                if (output.isTTY) {
+                    clearLine(output, 0);
+                    cursorTo(output, 0);
+                }
+                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}`);
+                // Create the reader only after the explanation is visible, with the
+                // final action prompt already installed. Never draw readline's default >.
+                const reader = createInterface({
+                    input,
+                    output,
+                    terminal: output.isTTY === true,
+                    prompt: options.join(' · ') + ' > ',
+                });
+                readline = reader;
+                reader.on('SIGINT', cancel);
+                reader.on('close', () => {
+                    if (readline !== reader)
+                        return;
+                    ended = true;
+                    if (!closed)
+                        cancel();
+                });
+                reader.on('line', (line) => {
+                    if (readline !== reader || current?.revision !== view.revision)
+                        return;
+                    const answer = line.trim().toLowerCase();
+                    const action = answer === 'r'
+                        ? 'retry'
+                        : answer === 'stop'
+                            ? 'interrupt'
+                            : answer === ''
+                                ? 'cancel'
+                                : undefined;
+                    if (!action || !view.actions.includes(action)) {
+                        reader.prompt();
+                        return;
+                    }
+                    submit(view.revision, action);
+                });
+                reader.prompt();
+            },
+            close() {
+                closed = true;
+                releaseReader();
+            },
+        };
+    };
+}

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)

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

@@ -20,9 +20,10 @@ import { createHash, randomUUID } from 'node:crypto';
 import { realpath, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join, posix, resolve, win32 } from 'node:path';
-import { claimLocalHostProcessDeployment, handoffLocalHostProcessDeployment, readLocalHostDeploymentRecord, } from '@maka/runtime-host/operator';
+import { isDeepStrictEqual } from 'node:util';
+import { claimLocalHostProcessDeployment, handoffLocalHostProcessDeployment, readLocalHostDeploymentRecord, resolveRuntimeHostManagedDeploymentAuthority, } from '@maka/runtime-host/operator';
 import { compareProductReleaseVersions } from '@maka/runtime-host/operator/update-package-evidence';
-import { connectExistingRuntimeHost } from '@maka/runtime-host/client';
+import { connectExistingRuntimeHost, forceTerminateObservedRegisteredRuntimeHost, } from '@maka/runtime-host/client';
 import { INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, RUNTIME_HOST_PROTOCOL_VERSION, } from '@maka/runtime-host/protocol';
 import { resolveRuntimeHostNpmGlobalInstallation, } from './runtime-host-cli-installation.js';
 import { openRuntimeHostPackageDeployment, prepareRuntimeHostPackageDeployment, resolveRuntimeHostPackageCliPath, } from './runtime-host-package-deployment.js';
@@ -53,6 +54,7 @@ export class RuntimeHostLocalHandoffError extends Error {
  * retain only the bounded true-idle takeover adapter.
  */
 export async function restartRuntimeHostNpmGlobalDeployment(input, authorityOptions = {}, overrides = {}) {
+    input.signal?.throwIfAborted();
     if (input.registration.lifecycleMode !== 'ephemeral') {
         return {
             kind: 'operator_required',
@@ -64,15 +66,23 @@ export async function restartRuntimeHostNpmGlobalDeployment(input, authorityOpti
         withPackage: withRuntimeHostRegistryUpdatePackage,
         prepareDeployment: prepareRuntimeHostPackageDeployment,
         readRecord: readLocalHostDeploymentRecord,
+        resolveManagedAuthority: resolveRuntimeHostManagedDeploymentAuthority,
         claim: claimLocalHostProcessDeployment,
         handoff: handoffLocalHostProcessDeployment,
         resolveCandidate: resolveRuntimeHostRegistryUpdateCandidate,
         connectExisting: connectExistingRuntimeHost,
         activateTarget: launchRuntimeHostTargetActivator,
         retireSource: launchRuntimeHostLocalSourceRetirement,
+        terminateObservedHost: forceTerminateObservedRegisteredRuntimeHost,
         ...overrides,
     };
+    if (await deps.resolveManagedAuthority(input.registration.rootId)) {
+        return { kind: 'operator_required', reason: 'unowned_host' };
+    }
     const installation = await deps.resolveInstallation(input.installationOptions);
+    if (input.expectedInstallation && !isDeepStrictEqual(installation, input.expectedInstallation)) {
+        return { kind: 'changed' };
+    }
     const current = await deps.readRecord(input.registration.rootId, authorityOptions);
     const sourceOwner = current?.state.kind === 'handoff' ? current.state.from : current?.state.owner;
     if (sourceOwner && !sameOwner(sourceOwner, installation.owner)) {
@@ -130,9 +140,13 @@ export async function restartRuntimeHostNpmGlobalDeployment(input, authorityOpti
         return 'target_present';
     };
     const prepare = async (rootId, selectedDeployment, stagedTarget, inheritableAuthorityLeaseFd) => {
+        input.signal?.throwIfAborted();
         if (rootId !== input.registration.rootId) {
             throw new RuntimeHostLocalHandoffError('root_changed', 'The local Runtime Host State Root changed before restart');
         }
+        if (await deps.resolveManagedAuthority(rootId)) {
+            throw new Error('The managed Runtime Host requires its operator to perform replacement');
+        }
         const observed = await deps.connectExisting({
             rootPath: input.rootPath,
             protocol: { min: RUNTIME_HOST_PROTOCOL_VERSION, max: RUNTIME_HOST_PROTOCOL_VERSION },
@@ -179,6 +193,7 @@ export async function restartRuntimeHostNpmGlobalDeployment(input, authorityOpti
                 expectedHostEpoch: registration.hostEpoch,
                 activeWorkPolicy,
                 inheritableAuthorityLeaseFd,
+                ...(input.signal ? { signal: input.signal } : {}),
             });
             if (retired === 'active_work')
                 return { kind: 'active_work' };
@@ -191,6 +206,15 @@ export async function restartRuntimeHostNpmGlobalDeployment(input, authorityOpti
             }
             return { kind: 'target_present' };
         }
+        // Older source packages cannot negotiate retirement. Explicit consent may
+        // use Desktop's exact-process recovery, inside this existing deployment
+        // transaction and only after staging the verified successor.
+        if (activeWorkPolicy === 'interrupt_active_work' && input.processIdentity) {
+            input.signal?.throwIfAborted();
+            const stopped = await deps.terminateObservedHost({ rootPath: input.rootPath, registration: input.registration }, { processIdentity: input.processIdentity, isCurrent: () => !input.signal?.aborted });
+            if (!stopped)
+                throw new Error('The observed Runtime Host changed before it could be stopped safely');
+        }
         const activated = await activateExactTarget(rootId, stagedTarget, inheritableAuthorityLeaseFd, registration.hostEpoch);
         if (activated === 'active_work')
             return { kind: 'active_work' };
@@ -286,6 +310,12 @@ export async function reconcilePreparedRuntimeHostNpmGlobalDeployment(request, l
         return request.staged;
     };
     const current = await overrides.readRecord(request.rootId, authorityOptions);
+    if (request.expectedOwner &&
+        (current?.state.kind !== 'owned' ||
+            current.revision !== request.expectedOwner.revision ||
+            !sameOwner(current.state.owner, request.expectedOwner.owner))) {
+        throw new RuntimeHostLocalHandoffError('source_owner_mismatch', 'The observed local Host owner changed before update reconciliation');
+    }
     if (!current) {
         return overrides.claim({
             rootId: request.rootId,
@@ -297,9 +327,12 @@ export async function reconcilePreparedRuntimeHostNpmGlobalDeployment(request, l
     }
     return overrides.handoff({
         rootId: request.rootId,
-        expectedRevision: current.revision,
+        // The same captured CAS token is checked again by begin_handoff under
+        // the authority lock. Never substitute a newly observed owner revision.
+        expectedRevision: request.expectedOwner?.revision ?? current.revision,
         transactionId: current.state.kind === 'handoff' ? current.state.transactionId : request.transactionId,
-        from: current.state.kind === 'handoff' ? current.state.from : current.state.owner,
+        from: request.expectedOwner?.owner ??
+            (current.state.kind === 'handoff' ? current.state.from : current.state.owner),
         to: request.installation.owner,
         target: request.target,
         activeWorkPolicy: request.activeWorkPolicy,
@@ -331,7 +364,7 @@ export async function prepareRuntimeHostNpmGlobalStagedDeployment(input, pathOpt
         launchGeneration: launchGeneration(input.transactionId, input.target),
     };
 }
-async function openRuntimeHostNpmGlobalStagedDeployment(input, pathOptions = {}) {
+export async function openRuntimeHostNpmGlobalStagedDeployment(input, pathOptions = {}) {
     const deploymentRoot = resolveRuntimeHostLocalCliDeploymentRoot(input.rootId, input.owner, pathOptions);
     const staged = await openRuntimeHostPackageDeployment({
         deploymentRoot,
@@ -379,6 +412,16 @@ async function requireCandidateEntrypoint(packageRoot) {
     }
     return candidate;
 }
+/** Read-only capability check against the same verified source package the transaction uses. */
+export async function runtimeHostNpmGlobalSourceRetirementAvailable(input) {
+    const source = await openRuntimeHostNpmGlobalStagedDeployment({
+        rootId: input.rootId,
+        owner: input.owner,
+        target: input.source,
+        transactionId: 'source-capability-probe',
+    }, input.deploymentPathOptions);
+    return hasSourceRetirementHelper(source);
+}
 async function hasSourceRetirementHelper(source) {
     try {
         return (await stat(join(dirname(source.cliPath), 'runtime-host-local-source-retirement.js'))).isFile();

package/dist/runtime-host-local-managed-activation.js

@@ -0,0 +1,84 @@
+/*
+ * 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 { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { resolveStorageRoot } from '@maka/storage/root-authority';
+import { runtimeHostStartupError } from '@maka/runtime-host/client';
+import { decodeRuntimeHostActivationFrame, readRuntimeHostManagedDeploymentConfig, RUNTIME_HOST_ACTIVATION_FRAME_MAX_BYTES, runtimeHostManagedOperatorCommand, runtimeHostOperatorInvocation, } from '@maka/runtime-host/operator';
+const run = promisify(execFile);
+/** Invoke the installed owner; never launch the calling CLI's candidate as the owner. */
+export async function activateLocalManagedRuntimeHost(input) {
+    input.signal?.throwIfAborted();
+    const capability = await resolveStorageRoot({ path: input.rootPath, kind: 'interactive' });
+    const config = await readRuntimeHostManagedDeploymentConfig(capability);
+    if (!config || config.lifecycle.mode !== 'on_demand') {
+        throw runtimeHostStartupError('managed_root_requires_operator');
+    }
+    const operator = runtimeHostManagedOperatorCommand(config, process.platform === 'win32' ? 'win32' : 'posix');
+    let invocation = runtimeHostOperatorInvocation(operator, [
+        'activate',
+        '--framed',
+        '--root-id',
+        capability.rootId,
+    ]);
+    // Older installations have only the stable POSIX operator executable.
+    try {
+        await access(operator.modulePath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || process.platform === 'win32') {
+            throw error;
+        }
+        invocation = {
+            executable: join(config.deploymentRoot, 'operator'),
+            args: invocation.args.slice(1),
+        };
+    }
+    const result = await run(invocation.executable, [...invocation.args], {
+        encoding: 'utf8',
+        timeout: 120_000,
+        killSignal: 'SIGKILL',
+        maxBuffer: RUNTIME_HOST_ACTIVATION_FRAME_MAX_BYTES + 256,
+        ...(input.signal ? { signal: input.signal } : {}),
+    }).catch((error) => {
+        input.signal?.throwIfAborted();
+        // Operators report a framed diagnostic and exit nonzero on expected failures.
+        if (error instanceof Error && 'stdout' in error && typeof error.stdout === 'string') {
+            const frame = decodeSingleActivationFrame(error.stdout);
+            if (frame?.kind === 'error')
+                throw new Error(frame.error.message, { cause: error });
+        }
+        throw error;
+    });
+    input.signal?.throwIfAborted();
+    const frame = decodeSingleActivationFrame(result.stdout);
+    if (!frame)
+        throw new Error('The installed Runtime Host operator returned an invalid activation result');
+    if (frame.kind === 'error')
+        throw new Error(frame.error.message);
+    if (frame.rootId !== capability.rootId || frame.deploymentId !== config.deploymentId) {
+        throw new Error('The installed Runtime Host operator activated a different deployment');
+    }
+}
+function decodeSingleActivationFrame(stdout) {
+    const line = stdout.replace(/\r?\n$/u, '');
+    return /[\r\n]/u.test(line) ? undefined : decodeRuntimeHostActivationFrame(line);
+}

package/dist/runtime-host-local-source-retirement.js

@@ -58,6 +58,7 @@ export async function runRuntimeHostLocalSourceRetirement(input, overrides = {})
     }
 }
 export function launchRuntimeHostLocalSourceRetirement(input) {
+    input.signal?.throwIfAborted();
     const args = [
         input.sourceCliPath,
         'runtime-host',
@@ -81,9 +82,24 @@ export function launchRuntimeHostLocalSourceRetirement(input) {
             killSignal: 'SIGKILL',
             windowsHide: false,
         });
-        child.once('error', reject);
+        // Only this retirement client is stopped, never the parent that owns the
+        // durable deployment transaction. Wait for its fd/connection to close.
+        const cancel = () => {
+            child.kill('SIGKILL');
+        };
+        input.signal?.addEventListener('abort', cancel, { once: true });
+        if (input.signal?.aborted)
+            cancel();
+        let spawnError;
+        child.once('error', (error) => {
+            spawnError = error;
+        });
         child.once('close', (code, signal) => {
-            if (signal) {
+            input.signal?.removeEventListener('abort', cancel);
+            if (spawnError) {
+                reject(spawnError);
+            }
+            else if (signal) {
                 reject(new Error(`Maka source retirement helper exited on ${signal}`));
             }
             else if (code === 0) {

package/dist/runtime-host-managed-lifecycle-manager.js

@@ -77,6 +77,7 @@ export async function manageRuntimeHostManagedLifecycle(rootId, input, dependenc
         }
         if (input.action === 'restart') {
             const retirement = await retireRuntimeHostLifecycleOwner({
+                ...(input.expectedHost ? { expectedOwner: input.expectedHost } : {}),
                 rootPath: config.root.path,
                 rootId,
                 supervisor: provider.supervisor,

package/dist/runtime-host-operator-retirement.js

@@ -0,0 +1,50 @@
+/*
+ * 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 { RUNTIME_HOST_OPERATOR_RETIREMENT_CANCELLATION_ENV } from '@maka/runtime-host/operator';
+/** Consume the operator's one-shot cancellation channel only around reversible retirement. */
+export function withOperatorRetirementCancellation(operation) {
+    if (process.env[RUNTIME_HOST_OPERATOR_RETIREMENT_CANCELLATION_ENV] !== '1') {
+        return operation(undefined);
+    }
+    // Recovery may retire another owner later. It must finish independently of
+    // the original user's cancellation, and activators must not inherit this channel.
+    delete process.env[RUNTIME_HOST_OPERATOR_RETIREMENT_CANCELLATION_ENV];
+    return withRetirementCancellation(process.stdin, operation);
+}
+export async function withRetirementCancellation(input, operation) {
+    const controller = new AbortController();
+    const cancel = () => controller.abort(new Error('Runtime Host retirement was cancelled'));
+    input.once('end', cancel);
+    input.once('error', cancel);
+    input.once('close', cancel);
+    input.resume();
+    if (input.readableEnded || input.destroyed)
+        cancel();
+    try {
+        return await operation(controller.signal);
+    }
+    finally {
+        input.removeListener('end', cancel);
+        input.removeListener('error', cancel);
+        input.removeListener('close', cancel);
+        input.pause();
+        // A parent's still-open cancellation pipe must not keep the completed CLI alive.
+        input.unref?.();
+    }
+}

package/dist/runtime-host-service-manager.js

@@ -59,6 +59,9 @@ function runtimeHostServiceManagerDeps(overrides) {
     };
 }
 export async function manageRuntimeHostService(input, backend, overrides = {}) {
+    if (input.expectedHost) {
+        throw new RuntimeHostServiceManagerError('target_mismatch', 'An exact Host fence requires the canonical managed deployment operator');
+    }
     const deps = runtimeHostServiceManagerDeps(overrides);
     const configPath = resolveRuntimeHostManagedServiceConfigPath(input.clientDataRoot);
     const configDirectory = dirname(configPath);
@@ -667,9 +670,6 @@ async function normalizeStateRoot(requestedRoot) {
         throw new RuntimeHostServiceManagerError('invalid_config', `Invalid Runtime Host State Root: ${requestedRoot}`, { cause: error });
     }
 }
-export async function resolveRuntimeHostManagedStateRoot(requestedRoot) {
-    return normalizeStateRoot(requestedRoot);
-}
 async function normalizeProjectDirectoryRoots(roots) {
     let canonicalRoots;
     try {

package/dist/runtime-host-session-channel.js

@@ -37,6 +37,7 @@ export class RuntimeHostSessionChannel {
     #now;
     #onTurnStarted;
     #onRuntimeResourceChanged;
+    #onSessionDomainChanged;
     #onInteractionPending;
     #onInteractionResolved;
     #onTranscriptSettlement;
@@ -71,6 +72,7 @@ export class RuntimeHostSessionChannel {
         this.#now = options.now;
         this.#onTurnStarted = options.onTurnStarted;
         this.#onRuntimeResourceChanged = options.onRuntimeResourceChanged;
+        this.#onSessionDomainChanged = options.onSessionDomainChanged;
         this.#onInteractionPending = options.onInteractionPending;
         this.#onInteractionResolved = options.onInteractionResolved;
         this.#onTranscriptSettlement = options.onTranscriptSettlement;
@@ -79,6 +81,16 @@ export class RuntimeHostSessionChannel {
         this.#onSnapshotChanged = options.onSnapshotChanged;
         this.#onFailed = options.onFailed;
         this.#onRecovered = options.onRecovered;
+        this.#subscribeSessionDomainChanges(subscription);
+    }
+    #subscribeSessionDomainChanges(subscription) {
+        if (!this.#onSessionDomainChanged)
+            return;
+        subscription.subscribeSessionDomainChanges((frame) => {
+            if (!this.#closing && this.#subscription === subscription) {
+                this.#onSessionDomainChanged?.(frame);
+            }
+        });
     }
     static async open(options) {
         const subscription = await options.connection.openSessionSubscription({
@@ -343,6 +355,7 @@ export class RuntimeHostSessionChannel {
                 return;
             }
             this.#subscription = replacement;
+            this.#subscribeSessionDomainChanges(replacement);
             this.#ready = false;
             this.#pendingFrames.length = 0;
             void this.#pump(replacement);