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

package/dist/pi-tui-transcript-viewer.js

@@ -16,8 +16,9 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { Key, matchesKey, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
-import { ansi } from './tui-ansi.js';
+import { Key, Input, isKeyRelease, isKeyRepeat, matchesKey, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
+import { ansi, stripAnsi } from './tui-ansi.js';
+import { TUI_COPY_RESOURCES } from './tui-copy-catalog.js';
 const VIEWER_CHROME_ROWS = 2;
 /**
  * Full-screen, read-only navigation over the CLI transcript projection.
@@ -28,19 +29,100 @@ const VIEWER_CHROME_ROWS = 2;
  */
 export class TranscriptViewerOverlay {
     input;
+    focused = false;
     top = 0;
     documentRows = 0;
     bodyRows = 0;
     followsEnd = true;
+    document = { lines: [], anchors: [] };
+    expanded = true;
+    anchor;
+    search = new Input();
+    searching = false;
+    query = '';
+    matches = [];
+    searchOrigin;
+    matchedLine;
     constructor(input) {
         this.input = input;
     }
     invalidate() { }
     handleInput(data) {
+        if (isKeyRelease(data))
+            return;
+        if (matchesKey(data, Key.ctrl('o'))) {
+            if (!isKeyRepeat(data))
+                this.input.onClose();
+            return;
+        }
+        if (this.searching) {
+            if (matchesKey(data, Key.escape)) {
+                this.searching = false;
+                this.query = '';
+                this.matches = [];
+                if (this.searchOrigin)
+                    Object.assign(this, this.searchOrigin);
+                this.input.onChange();
+                return;
+            }
+            if (matchesKey(data, Key.enter)) {
+                this.searching = false;
+                this.input.onChange();
+                return;
+            }
+            if (matchesKey(data, Key.up) || matchesKey(data, Key.down)) {
+                this.nextMatch(matchesKey(data, Key.up) ? -1 : 1);
+                return;
+            }
+            this.search.handleInput(data);
+            const query = this.search.getValue().trim().toLocaleLowerCase();
+            if (query !== this.query) {
+                this.query = query;
+                this.findMatches();
+                const target = this.matches.find((line) => line >= (this.searchOrigin?.top ?? 0)) ?? this.matches[0];
+                if (target !== undefined)
+                    this.goToMatch(target);
+            }
+            this.input.onChange();
+            return;
+        }
+        if (matchesKey(data, Key.escape) && this.query) {
+            this.query = '';
+            this.matches = [];
+            if (this.searchOrigin)
+                Object.assign(this, this.searchOrigin);
+            this.input.onChange();
+            return;
+        }
         if (matchesKey(data, Key.escape) || matchesKey(data, 'q')) {
             this.input.onClose();
             return;
         }
+        if (matchesKey(data, '/')) {
+            this.searchOrigin = {
+                top: this.top,
+                followsEnd: this.followsEnd,
+                anchor: this.anchor ? { ...this.anchor } : undefined,
+            };
+            this.search.setValue(this.query);
+            this.searching = true;
+            this.input.onChange();
+            return;
+        }
+        if (this.query && (matchesKey(data, 'n') || matchesKey(data, Key.shift('n')))) {
+            this.nextMatch(matchesKey(data, Key.shift('n')) ? -1 : 1);
+            return;
+        }
+        if (matchesKey(data, Key.ctrl('e'))) {
+            if (!isKeyRepeat(data)) {
+                this.expanded = !this.expanded;
+                // A detail that disappears on collapse returns to its own heading.
+                if (!this.expanded && this.anchor)
+                    this.anchor.offset = 0;
+                this.input.onChange();
+            }
+            return;
+        }
         if (matchesKey(data, Key.up)) {
             this.scrollBy(-1);
             return;
@@ -60,12 +142,14 @@ export class TranscriptViewerOverlay {
         if (matchesKey(data, Key.home)) {
             this.followsEnd = false;
             this.top = 0;
+            this.captureAnchor();
             this.input.onChange();
             return;
         }
         if (matchesKey(data, Key.end)) {
             this.followsEnd = true;
             this.top = this.maxTop();
+            this.captureAnchor();
             this.input.onChange();
         }
     }
@@ -76,31 +160,74 @@ export class TranscriptViewerOverlay {
         // navigation chrome only. The footer appears once header + body + footer fit.
         const showFooter = viewportRows > 2;
         this.bodyRows = Math.max(0, viewportRows - (showFooter ? VIEWER_CHROME_ROWS : 1));
-        const document = [...this.input.renderTranscript(safeWidth)];
+        this.document = this.input.renderTranscript(safeWidth, this.expanded);
+        const document = this.document.lines;
         this.documentRows = document.length;
+        if (!this.followsEnd && this.anchor) {
+            const index = this.document.anchors.findIndex((entry) => entry.id === this.anchor.id);
+            if (index >= 0) {
+                const entry = this.document.anchors[index];
+                const end = this.document.anchors[index + 1]?.line ?? document.length;
+                this.top = entry.line + Math.min(this.anchor.offset, Math.max(0, end - entry.line - 1));
+            }
+        }
         const maxTop = this.maxTop();
         this.top = this.followsEnd ? maxTop : clamp(this.top, 0, maxTop);
-        this.followsEnd = this.top === maxTop;
+        this.captureAnchor();
+        this.findMatches();
         const visible = document.slice(this.top, this.top + this.bodyRows);
         const start = visible.length === 0 ? 0 : this.top + 1;
         const end = visible.length === 0 ? 0 : this.top + visible.length;
-        const header = padLine(`${ansi.bold('TRANSCRIPT')} ${ansi.dim(`${start}-${end} of ${document.length}`)}`, safeWidth);
+        const copy = TUI_COPY_RESOURCES['transcript-reader'][this.input.locale ?? 'en'];
+        const header = padLine(`${ansi.bold(copy.title)} ${ansi.dim(`${start}-${end}/${document.length} · ${copy.scope}`)}`, safeWidth);
+        const matchingLines = new Set(this.matches);
         const body = [
-            ...visible.map((line) => padLine(line, safeWidth)),
+            ...visible.map((line, index) => padLine(matchingLines.has(this.top + index) ? ansi.reverse(stripAnsi(line)) : line, safeWidth)),
             ...Array.from({ length: Math.max(0, this.bodyRows - visible.length) }, () => ' '.repeat(safeWidth)),
         ];
         if (!showFooter)
             return [header, ...body];
-        const footer = padLine(ansi.dim('↑/↓ scroll · PgUp/PgDn page · Home/End jump · q/Esc close'), safeWidth);
+        this.search.focused = this.focused && this.searching;
+        const footer = padLine(this.searching
+            ? `/ ${this.search.render(Math.max(1, safeWidth - 3))[0] ?? ''}`
+            : ansi.dim(this.query
+                ? `${this.matches.length} ${copy.matches} · n/N · Esc ${copy.back}`
+                : copy.hint), safeWidth);
         return [header, ...body, footer];
     }
     scrollBy(delta) {
+        this.matchedLine = undefined;
         const maxTop = this.maxTop();
         this.top = clamp(this.top + delta, 0, maxTop);
         // Follow the tail whenever the clamped position is the end, including the
         // no-op case where a short transcript cannot move at all: a stray Up key
         // must not pin the viewer at the head once the transcript grows.
         this.followsEnd = this.top === maxTop;
+        this.captureAnchor();
+        this.input.onChange();
+    }
+    captureAnchor() {
+        const entry = [...this.document.anchors].reverse().find((entry) => entry.line <= this.top);
+        this.anchor = entry ? { id: entry.id, offset: this.top - entry.line } : undefined;
+    }
+    findMatches() {
+        this.matches = this.query
+            ? this.document.lines.flatMap((line, index) => stripAnsi(line).toLocaleLowerCase().includes(this.query) ? [index] : [])
+            : [];
+    }
+    goToMatch(line) {
+        this.matchedLine = line;
+        this.top = clamp(line, 0, this.maxTop());
+        this.followsEnd = false;
+        this.captureAnchor();
+    }
+    nextMatch(direction) {
+        const current = this.matchedLine ?? this.top;
+        const line = direction > 0
+            ? (this.matches.find((line) => line > current) ?? this.matches[0])
+            : ([...this.matches].reverse().find((line) => line < current) ?? this.matches.at(-1));
+        if (line !== undefined)
+            this.goToMatch(line);
         this.input.onChange();
     }
     maxTop() {

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, forceTerminateObservedRegisteredRuntimeHost, 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, RUNTIME_HOST_COMPATIBILITY_EPOCH, } 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,20 @@ 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,
+        terminateObservedHost: forceTerminateObservedRegisteredRuntimeHost,
+        restartDeployment: restartRuntimeHostNpmGlobalDeployment,
+        sourceRetirementAvailable: runtimeHostNpmGlobalSourceRetirementAvailable,
         ...overrides,
     };
     const resolvedProfile = await resolveHostProfile(input, deps);
@@ -83,45 +83,227 @@ 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;
+                let installationFailure;
+                // 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 (error) {
+                        installationFailure = error instanceof Error ? error.message : String(error);
+                    }
+                    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 = connected.processIdentity !== undefined ||
+                            (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,
+                                    ...(connected.processIdentity
+                                        ? { processIdentity: connected.processIdentity }
+                                        : {}),
+                                    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}`,
+                                };
+                            },
+                        };
+                    }
+                }
+                // The same observed-process recovery used by Desktop is available to
+                // persistent local invocations without a deployment owner. This is an
+                // explicit interruption, never an idle inference or an installation claim.
+                const processIdentity = connected.processIdentity;
+                if (!replacement &&
+                    !managed &&
+                    !record &&
+                    !invocationOwned &&
+                    connected.registration.lifecycleMode === 'ephemeral' &&
+                    processIdentity) {
+                    const registration = connected.registration;
+                    replacement = {
+                        kind: 'replace',
+                        canReplaceIdle: false,
+                        canInterrupt: true,
+                        execute: async (policy, progress, consent, attemptSignal) => {
+                            if (policy !== 'interrupt_active_work' || consent !== 'explicit') {
+                                return { kind: 'active_work' };
+                            }
+                            attemptSignal?.throwIfAborted();
+                            if ((await deps.resolveManagedAuthority(registration.rootId)) ||
+                                (await deps.readDeploymentRecord(registration.rootId)))
+                                return { kind: 'changed' };
+                            attemptSignal?.throwIfAborted();
+                            progress('retiring');
+                            const stopped = await deps.terminateObservedHost({ rootPath: input.rootPath, registration }, { processIdentity, isCurrent: () => !signal?.aborted && !attemptSignal?.aborted });
+                            if (!stopped)
+                                return { kind: 'changed' };
+                            progress('verifying');
+                            return { kind: 'completed' };
+                        },
+                    };
+                }
+                return {
+                    kind: 'blocked',
+                    blocker: {
+                        identity: JSON.stringify([
+                            connected.registration,
+                            processIdentity,
+                            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',
+                        ...(!replacement
+                            ? {
+                                recoveryBlocker: managed || connected.registration.lifecycleMode === 'service'
+                                    ? 'managed'
+                                    : record
+                                        ? 'owner'
+                                        : invocationOwned
+                                            ? 'installation'
+                                            : 'identity',
+                                diagnostic: [
+                                    `Host compatibility: ${connected.registration.compatibilityEpoch}; client: ${RUNTIME_HOST_COMPATIBILITY_EPOCH}.`,
+                                    installationFailure,
+                                ]
+                                    .filter(Boolean)
+                                    .join('\n'),
+                            }
+                            : {}),
+                        ...(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 +404,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 } : {}),