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

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

@@ -20,7 +20,8 @@ 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 { INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, RUNTIME_HOST_PROTOCOL_VERSION, } from '@maka/runtime-host/protocol';
@@ -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,6 +66,7 @@ export async function restartRuntimeHostNpmGlobalDeployment(input, authorityOpti
         withPackage: withRuntimeHostRegistryUpdatePackage,
         prepareDeployment: prepareRuntimeHostPackageDeployment,
         readRecord: readLocalHostDeploymentRecord,
+        resolveManagedAuthority: resolveRuntimeHostManagedDeploymentAuthority,
         claim: claimLocalHostProcessDeployment,
         handoff: handoffLocalHostProcessDeployment,
         resolveCandidate: resolveRuntimeHostRegistryUpdateCandidate,
@@ -72,7 +75,13 @@ export async function restartRuntimeHostNpmGlobalDeployment(input, authorityOpti
         retireSource: launchRuntimeHostLocalSourceRetirement,
         ...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 +139,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 +192,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' };
@@ -286,6 +300,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 +317,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 +354,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 +402,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);

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

@@ -30,6 +30,7 @@ import { isRuntimeHostTerminalTurn as isTerminalTurn } from '@maka/runtime-host/
 import { projectSessionCatalogSummary, readRuntimeHostResources, readRuntimeHostSessions, RuntimeHostOperationError, RuntimeHostRequestInterruptedError, } from '@maka/runtime-host/client';
 import { SESSION_TRANSCRIPT_BOOTSTRAP_MAX_BYTES, } from '@maka/runtime-host/protocol';
 import { RuntimeHostSessionChannel } from './runtime-host-session-channel.js';
+import { getRuntimeHostSession, requireRuntimeHostSessionProjection as requireSession, updateRuntimeHostSession, } from './runtime-host-session-update.js';
 import { inspectSessionResumeAvailability, skillInvocationBlockedMessage, } from './session-driver.js';
 import { cwdRank, firstLine, inspectGitCwdChanges, resolveMoveCwd, } from './session-driver-policy.js';
 const decodeStoredMessage = (value) => decodePersistedStoredMessage(markPersisted(value));
@@ -502,7 +503,7 @@ class RuntimeHostMakaSessionDriverImpl {
             sessionId,
             expectedRevision: current.revision,
             patch: { name },
-        }));
+        }), { operation: 'session.metadata.update' });
         return session.name;
     }
     async #moveSession(rawCwd) {
@@ -602,7 +603,7 @@ class RuntimeHostMakaSessionDriverImpl {
             sessionId,
             expectedRevision: current.revision,
             workspace: { kind: 'host_path', path: cwd },
-        }));
+        }), { operation: 'session.workspace.relocate' });
     }
     async listRewindTargets() {
         if (!this.#sessionId)
@@ -1073,7 +1074,7 @@ class RuntimeHostMakaSessionDriverImpl {
             sessionId,
             expectedRevision: current.revision,
             patch,
-        }));
+        }), { operation: 'session.configuration.update' });
     }
     #adoptConfiguration(session) {
         this.#model = session.model;
@@ -1369,12 +1370,6 @@ function workspaceTargetForCreate(current, input, location) {
     }
     return current.target;
 }
-async function getRuntimeHostSession(connection, sessionId) {
-    const result = await connection.request('session.catalog.query', { kind: 'get', sessionId });
-    if (result.kind !== 'session')
-        throw new Error('Runtime Host returned an invalid Session lookup');
-    return result.session === null ? null : requireSession(result.session);
-}
 function representableSession(item) {
     return 'kind' in item ? [] : [item];
 }
@@ -1426,11 +1421,6 @@ function visibleTranscriptMessages(messages, hiddenThroughTurnId) {
     }
     return boundary < 0 ? messages : messages.slice(boundary + 1);
 }
-function requireSession(item) {
-    if (!('kind' in item))
-        return item;
-    throw new Error(`Runtime Host Session is not representable by this CLI: ${item.id}`);
-}
 function inspectRuntimeHostSessionResumeAvailability(summary, location) {
     if (!summary.cwd) {
         return Promise.resolve({ available: false, reason: 'Missing working directory' });
@@ -1445,17 +1435,6 @@ async function assertSessionResumeAvailable(summary, location) {
         throw new Error(summary.cwd ? `Session cwd no longer exists: ${summary.cwd}` : availability.reason);
     }
 }
-async function updateRuntimeHostSession(connection, sessionId, update) {
-    for (let attempt = 0; attempt < MAX_CATALOG_ATTEMPTS; attempt += 1) {
-        const current = await getRuntimeHostSession(connection, sessionId);
-        if (!current)
-            throw new Error(`Session not found: ${sessionId}`);
-        const result = await update(current);
-        if (result.kind === 'committed')
-            return requireSession(result.session);
-    }
-    throw new Error(`Session kept changing while updating: ${sessionId}`);
-}
 async function loadCurrentMessages(connection, sessionId) {
     const subscription = await connection.openSessionSubscription({
         sessionId,

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

@@ -0,0 +1,62 @@
+/*
+ * 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.
+ */
+const MAX_UPDATE_ATTEMPTS = 3;
+export class RuntimeHostSessionUpdateError extends Error {
+    operation;
+    reason;
+    sessionId;
+    attempts;
+    name = 'RuntimeHostSessionUpdateError';
+    constructor(operation, reason, sessionId, attempts) {
+        super(`Runtime Host Session update failed for session ${sessionId}: ${reason}`);
+        this.operation = operation;
+        this.reason = reason;
+        this.sessionId = sessionId;
+        this.attempts = attempts;
+    }
+}
+export async function getRuntimeHostSession(connection, sessionId) {
+    const result = await connection.request('session.catalog.query', { kind: 'get', sessionId });
+    if (result.kind !== 'session') {
+        throw new RuntimeHostSessionUpdateError('session.catalog.query', 'invalid_projection', sessionId);
+    }
+    return result.session === null
+        ? null
+        : requireRuntimeHostSessionProjection(result.session, 'session.catalog.query');
+}
+export async function updateRuntimeHostSession(connection, sessionId, update, options) {
+    for (let attempt = 0; attempt < MAX_UPDATE_ATTEMPTS; attempt += 1) {
+        options.assertRequestAllowed?.();
+        const current = await getRuntimeHostSession(connection, sessionId);
+        if (!current) {
+            throw new RuntimeHostSessionUpdateError('session.catalog.query', 'not_found', sessionId);
+        }
+        options.assertRequestAllowed?.();
+        const result = await update(current);
+        if (result.kind === 'committed') {
+            return requireRuntimeHostSessionProjection(result.session, options.operation);
+        }
+    }
+    throw new RuntimeHostSessionUpdateError(options.operation, 'revision_conflict', sessionId, MAX_UPDATE_ATTEMPTS);
+}
+export function requireRuntimeHostSessionProjection(session, operation = 'session.catalog.query') {
+    if (!('kind' in session))
+        return session;
+    throw new RuntimeHostSessionUpdateError(operation, 'unsupported_session_projection', session.id);
+}

package/dist/runtime-host-tui-command.js

@@ -17,21 +17,23 @@
  * under the License.
  */
 import { parseNoRealConnectionError } from '@maka/core/connection-error-copy';
-import { createInterface } from 'node:readline/promises';
 import { SessionActivityRegistry } from '@maka/runtime/goal-turn-lifecycle';
-import { readRuntimeHostConnectionCatalog } from '@maka/runtime-host/client';
+import { readRuntimeHostConnectionCatalog, HostHandoffCancelledError, } from '@maka/runtime-host/client';
 import { runtimeHostProfileUsesHostWorkspace } from '@maka/runtime-host/profile-kind';
 import { createForeignSessionStore } from '@maka/storage/foreign-session-store';
 import { formatMakaResumeHint } from './cli-invocation.js';
-import { connectRuntimeHostCli, resolveRuntimeHostCliConflictDecision, RuntimeHostCliConflictError, } from './runtime-host-cli-context.js';
-import { resolveRuntimeHostNpmGlobalInstallation } from './runtime-host-cli-installation.js';
-import { restartRuntimeHostNpmGlobalDeployment } from './runtime-host-local-handoff.js';
+import { connectRuntimeHostCli } from './runtime-host-cli-context.js';
+import { createCliHostHandoffSurface } from './runtime-host-handoff-surface.js';
 import { createRuntimeHostOnboardingSurface } from './runtime-host-onboarding.js';
 import { runMakaPiTui } from './pi-tui-runner.js';
 import { createRuntimeHostTuiContext } from './runtime-host-tui-context.js';
+import { describeTuiHost, prepareTuiHostOwnerAction } from './runtime-host-tui-owner.js';
+import { getTuiHostOwnerCopy } from './tui-host-owner-copy.js';
 export async function runRuntimeHostTui(input) {
+    const ownerCopy = getTuiHostOwnerCopy(input.locale);
     const foreignSessions = createForeignSessionStore();
     const contextInput = {
+        ...(process.stdin.isTTY ? { handoffSurface: createCliHostHandoffSurface(input.locale) } : {}),
         clientDataRoot: input.clientDataRoot,
         rootPath: input.workspaceRoot,
         cwd: input.cwd,
@@ -41,11 +43,11 @@ export async function runRuntimeHostTui(input) {
     };
     let context;
     try {
-        context = await createTuiContextWithHostConflictPrompt(contextInput);
-        if (!context)
-            return 1;
+        context = await createRuntimeHostTuiContext(contextInput);
     }
     catch (error) {
+        if (error instanceof HostHandoffCancelledError)
+            return 1;
         if (!isMissingDefaultConnection(error) || input.resumeSessionId)
             throw error;
         const configured = await runFirstRunOnboarding(input.clientDataRoot, input.workspaceRoot, input.cwd, input.locale, input.hostProfileId);
@@ -53,6 +55,8 @@ export async function runRuntimeHostTui(input) {
             throw error;
         context = await createRuntimeHostTuiContext(contextInput);
     }
+    let ownerAction;
+    let contextOpen = true;
     try {
         await runMakaPiTui({
             driver: context.driver,
@@ -79,6 +83,27 @@ export async function runRuntimeHostTui(input) {
             onboarding: context.onboarding,
             ...(context.mcp ? { mcp: context.mcp } : {}),
             recap: context.recap,
+            hostControl: {
+                status: () => describeTuiHost({ ...context, locale: input.locale }),
+                prepare: async (action, confirm) => {
+                    if (ownerAction || !contextOpen)
+                        throw new Error(ownerCopy.pending);
+                    const execute = await prepareTuiHostOwnerAction({
+                        profile: context.profile,
+                        connection: context.connection,
+                        rootPath: input.workspaceRoot,
+                        locale: input.locale,
+                        action,
+                        confirm,
+                    });
+                    if (!execute)
+                        return false;
+                    if (!contextOpen || ownerAction)
+                        throw new Error(ownerCopy.disconnected);
+                    ownerAction = execute;
+                    return true;
+                },
+            },
             ...(runtimeHostProfileUsesHostWorkspace(context.profile.kind)
                 ? {
                     sessionListScope: 'all',
@@ -103,82 +128,22 @@ export async function runRuntimeHostTui(input) {
         });
         if (hint)
             process.stdout.write(`${hint}\n`);
-        return 0;
     }
     finally {
+        contextOpen = false;
         await context.driver.cleanupOwnedSideConversations().catch(() => undefined);
         await context.close();
     }
-}
-async function createTuiContextWithHostConflictPrompt(input) {
-    const blockedRestartEpochs = new Set();
-    while (true) {
-        try {
-            return await createRuntimeHostTuiContext(input);
-        }
-        catch (error) {
-            if (!(error instanceof RuntimeHostCliConflictError) || !process.stdin.isTTY)
-                throw error;
-            process.stderr.write(`${error.message}\n`);
-            const canRestart = error.registration.lifecycleMode === 'ephemeral' &&
-                !blockedRestartEpochs.has(error.registration.hostEpoch) &&
-                (await isPersistentNpmGlobalCli());
-            const readline = createInterface({ input: process.stdin, output: process.stderr });
-            let decision;
-            try {
-                const answer = await readline.question(canRestart
-                    ? 'Restart this local Host if it is idle, wait for it to exit, or cancel? [r/w/C] '
-                    : 'Wait only if the existing Host is expected to exit, or cancel? [w/C] ');
-                decision = resolveRuntimeHostCliConflictDecision(answer, canRestart);
-            }
-            finally {
-                readline.close();
-            }
-            if (decision === 'cancel')
-                return null;
-            if (decision === 'restart') {
-                const result = await restartRuntimeHostNpmGlobalDeployment({
-                    rootPath: input.rootPath,
-                    registration: error.registration,
-                });
-                if (result.kind === 'completed')
-                    continue;
-                if (result.kind === 'active_work') {
-                    blockedRestartEpochs.add(error.registration.hostEpoch);
-                    process.stderr.write('The existing Runtime Host still owns active or durable work and was not interrupted.\n');
-                    continue;
-                }
-                if (result.kind === 'operator_required') {
-                    blockedRestartEpochs.add(error.registration.hostEpoch);
-                    continue;
-                }
-                if (result.kind === 'rejected')
-                    continue;
-                throw new Error(`Local Runtime Host restart requires recovery at ${result.phase}`, {
-                    cause: result.cause,
-                });
-            }
-            await waitForHostRetry();
-        }
-    }
-}
-async function isPersistentNpmGlobalCli() {
-    try {
-        await resolveRuntimeHostNpmGlobalInstallation();
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function waitForHostRetry() {
-    return new Promise((resolve) => setTimeout(resolve, 2_000));
+    // No reconnecting client remains to respawn a stopped Host, and an updater
+    // can use the restored terminal without competing with the TUI renderer.
+    return ownerAction ? ownerAction() : 0;
 }
 async function runFirstRunOnboarding(clientDataRoot, rootPath, cwd, locale, hostProfileId) {
     const connected = await connectRuntimeHostCli({
         clientDataRoot,
         rootPath,
         interactiveSsh: true,
+        ...(process.stdin.isTTY ? { handoffSurface: createCliHostHandoffSurface(locale) } : {}),
         ...(hostProfileId ? { profileId: hostProfileId } : {}),
     });
     try {

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

@@ -34,6 +34,7 @@ export async function createRuntimeHostTuiContext(input) {
         clientDataRoot: input.clientDataRoot,
         rootPath: input.rootPath,
         interactiveSsh: true,
+        ...(input.handoffSurface ? { handoffSurface: input.handoffSurface } : {}),
         ...(input.hostProfileId ? { profileId: input.hostProfileId } : {}),
     });
     const connection = connected.connection;