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

package/dist/cli-core.js

@@ -52,6 +52,8 @@ export function parseMakaCliArgs(argv, version, cliCommand = RELEASE_MAKA_CLI_LA
         return { kind: 'run', args: argv.slice(1) };
     if (first === 'activate')
         return { kind: 'activate', args: argv.slice(1) };
+    if (first === 'session-export')
+        return { kind: 'session-export', args: argv.slice(1) };
     if (first === 'eval')
         return { kind: 'eval', args: argv.slice(1) };
     if (first === 'update')
@@ -97,6 +99,7 @@ function helpText(cliCommand) {
         `  ${cliCommand} --acp      Serve ACP v1 over stdio (initialize, session/new, session/list)`,
         `  ${cliCommand} run ...      Run one non-interactive model turn`,
         `  ${cliCommand} activate ... Run one Cloud Session activation and emit JSONL`,
+        `  ${cliCommand} session-export --workspace-root <dir> --session <id> --out <file.maka-session>`,
         `  ${cliCommand} -p ...       Alias for ${cliCommand} run`,
         `  ${cliCommand} eval ...     Run one declarative multi-arm experiment`,
         `  ${cliCommand} update --target <latest|next|version>  Update this npm-global CLI and its local Runtime Host`,
@@ -243,6 +246,10 @@ export async function runMakaCli(argv = process.argv.slice(2), options = RELEASE
             const { runMakaActivationCli } = await import('./activation-command.js');
             return runMakaActivationCli(command.args);
         }
+        case 'session-export': {
+            const { runMakaSessionExportCli } = await import('./session-export-command.js');
+            return runMakaSessionExportCli(command.args);
+        }
         case 'eval': {
             const { configureInstalledEvalBundle } = await import('./eval-bundle-path.js');
             configureInstalledEvalBundle();
@@ -386,6 +393,8 @@ export async function runMakaCli(argv = process.argv.slice(2), options = RELEASE
                 bindPairingToClient: command.bindPairingToClient,
                 ...(command.repairRootAfterRemount ? { repairRootAfterRemount: true } : {}),
                 updateExisting: command.updateExisting,
+                reuseExistingEnvironment: command.reuseExistingEnvironment,
+                allowInterruptActiveTasks: command.allowInterruptActiveTasks,
                 ...(command.rootPath ? { rootPath: command.rootPath } : {}),
                 ...(command.projectDirectoryRoots
                     ? { projectDirectoryRoots: command.projectDirectoryRoots }
@@ -485,7 +494,13 @@ export async function runMakaCli(argv = process.argv.slice(2), options = RELEASE
                     defaultRootPath: serviceDataRoots.workspaceRoot,
                     selector: command.selector,
                     expectedTarget: command.expectedTarget,
+                    ...(command.expectedSourceVersion
+                        ? { expectedSourceVersion: command.expectedSourceVersion }
+                        : {}),
                     ...(command.expectedHost ? { expectedHost: command.expectedHost } : {}),
+                    ...(command.expectedConfigFingerprint
+                        ? { expectedConfigFingerprint: command.expectedConfigFingerprint }
+                        : {}),
                     ...(command.managedRootId ? { managedRootId: command.managedRootId } : {}),
                     ...(command.operatorDeploymentId
                         ? { operatorDeploymentId: command.operatorDeploymentId }
@@ -503,7 +518,13 @@ export async function runMakaCli(argv = process.argv.slice(2), options = RELEASE
                 ...(sourcePackageIntegrity ? { sourcePackageIntegrity } : {}),
                 version,
                 expectedTarget: command.expectedTarget,
+                ...(command.expectedSourceVersion
+                    ? { expectedSourceVersion: command.expectedSourceVersion }
+                    : {}),
                 ...(command.expectedHost ? { expectedHost: command.expectedHost } : {}),
+                ...(command.expectedConfigFingerprint
+                    ? { expectedConfigFingerprint: command.expectedConfigFingerprint }
+                    : {}),
                 ...(command.managedRootId ? { managedRootId: command.managedRootId } : {}),
                 ...(command.operatorDeploymentId
                     ? { operatorDeploymentId: command.operatorDeploymentId }

package/dist/mcp-capability-provider.js

@@ -73,7 +73,10 @@ export function createMcpCapabilityProvider(manager) {
             if (!binding)
                 throw new Error('MCP capability is not part of the published snapshot');
             await options.accept({ kind: 'none' });
-            return projectMcpResult(await manager.callTool(binding, frame.arguments, { signal: options.signal }));
+            return projectMcpResult(await manager.callTool(binding, frame.arguments, {
+                signal: options.signal,
+                requestInteraction: options.requestInteraction,
+            }));
         },
     };
 }

package/dist/pi-tui-mcp-status.js

@@ -210,7 +210,7 @@ export class McpManagementOverlay {
             return;
         const protocol = matchesKey(data, '1')
             ? 'legacy'
-            : matchesKey(data, '2')
+            : matchesKey(data, '2') || matchesKey(data, 'enter')
                 ? 'auto'
                 : matchesKey(data, '3')
                     ? '2026-07-28'
@@ -371,7 +371,7 @@ export class McpManagementOverlay {
             return [ansi.bold(editor.transportTitle), '', '1  stdio', '2  Streamable HTTP'];
         }
         if (this.phase.kind === 'protocol') {
-            return [ansi.bold(editor.protocolTitle), '', '1  legacy', '2  auto', '3  2026-07-28'];
+            return [ansi.bold(editor.protocolTitle), '', '1  legacy', '2  auto (Enter)', '3  2026-07-28'];
         }
         if (this.phase.kind === 'confirm_add') {
             return confirmAddDocument(this.phase.draft, this.input.locale);

package/dist/pi-tui-pickers.js

@@ -21,6 +21,7 @@ import { defineUiMessageCatalog, formatUiMessage, resolveUiMessageCatalog, } fro
 import { providerDefaultsOf, validateSlug, } from '@maka/core/llm-connections';
 import { CONNECTION_NAME_MAX_LENGTH } from '@maka/core/runtime-policy';
 import { ansi, editorTheme, selectListTheme, stripAnsi } from './tui-ansi.js';
+import { stripUnfocusedCursorStyle } from './tui-editor-render.js';
 import { TUI_COPY_RESOURCES } from './tui-copy-catalog.js';
 const TUI_PICKER_COPY = resolveUiMessageCatalog(defineUiMessageCatalog()(TUI_COPY_RESOURCES.pickers));
 export function onboardingFailureMessage(failure, locale) {
@@ -433,22 +434,13 @@ export class UserQuestionOverlay {
         return assemble(cappedTitle, optionRows.map((rows) => clampRowsWithEllipsis(rows, perOption, safeWidth)));
     }
     renderInputRow(width) {
-        const prefix = this.onInputRow ? '→ ' : '  ';
-        const contentWidth = Math.max(1, width - USER_QUESTION_ROW_PREFIX_WIDTH);
-        // Focused only while the input row is highlighted: that both shows the block
-        // cursor and emits the hardware-cursor marker (#1064) so IME candidate windows
-        // anchor to the edited text instead of the terminal bottom.
+        const marker = this.onInputRow ? '→' : ' ';
+        // Focus controls the IME marker and our cursor-visibility adapter (#1064).
         this.editor.focused = this.onInputRow;
         if (!this.onInputRow && this.editor.getText().length === 0) {
-            return [padLine(`${prefix}${ansi.dim(this.input.placeholder)}`, width)];
+            return [padLine(`${marker} ${ansi.dim(this.input.placeholder)}`, width)];
         }
-        // Drop the editor's own top/bottom border rows; keep just its content lines
-        // so the answer reads as one row of the list.
-        const editorLines = this.editor.render(contentWidth).slice(1, -1);
-        if (editorLines.length === 0) {
-            return [padLine(`${prefix}${ansi.dim(this.input.placeholder)}`, width)];
-        }
-        return editorLines.map((line, index) => padLine(`${index === 0 ? prefix : '  '}${line}`, width));
+        return renderFieldRow(this.editor, marker, width);
     }
 }
 export function modelPickerItems(currentModel, models, locale) {
@@ -750,14 +742,7 @@ export class ModelSearchOverlay {
         ];
     }
     renderFieldRow(editor, label, width) {
-        const prefix = `${label} `;
-        const prefixWidth = visibleWidth(prefix);
-        const contentWidth = Math.max(1, width - prefixWidth);
-        const editorLines = editor.render(contentWidth).slice(1, -1);
-        if (editorLines.length === 0) {
-            return [padLine(prefix, width)];
-        }
-        return editorLines.map((line, index) => padLine(`${index === 0 ? prefix : ' '.repeat(prefixWidth)}${line}`, width));
+        return renderFieldRow(editor, label, width);
     }
 }
 /**
@@ -873,6 +858,18 @@ function padLine(text, width) {
     const trimmed = visibleWidth(text) > safeWidth ? truncateToWidth(text, safeWidth, '') : text;
     return `${trimmed}${' '.repeat(Math.max(0, safeWidth - visibleWidth(trimmed)))}`;
 }
+function renderFieldRow(editor, label, width) {
+    const prefix = `${label} `;
+    const prefixWidth = visibleWidth(prefix);
+    const contentWidth = Math.max(1, width - prefixWidth);
+    // These field editors have no autocomplete rows. Keep Editor's wrapping and
+    // scrolling, but omit its top/bottom borders.
+    const lines = editor.render(contentWidth).slice(1, -1);
+    const editorLines = stripUnfocusedCursorStyle(lines, editor.focused);
+    if (editorLines.length === 0)
+        return [padLine(prefix, width)];
+    return editorLines.map((line, index) => padLine(`${index === 0 ? prefix : ' '.repeat(prefixWidth)}${line}`, width));
+}
 function keyEntryHint(copy, hasConnection, returnsTo) {
     const action = hasConnection ? 'reuse' : 'enter';
     return copy.keyHints[action][returnsTo];
@@ -1546,13 +1543,6 @@ export class OnboardingWizard {
         ];
     }
     renderFieldRow(editor, label, width) {
-        const prefix = `${label} `;
-        const prefixWidth = visibleWidth(prefix);
-        const contentWidth = Math.max(1, width - prefixWidth);
-        const editorLines = editor.render(contentWidth).slice(1, -1);
-        if (editorLines.length === 0) {
-            return [padLine(prefix, width)];
-        }
-        return editorLines.map((line, index) => padLine(`${index === 0 ? prefix : ' '.repeat(prefixWidth)}${line}`, width));
+        return renderFieldRow(editor, label, width);
     }
 }

package/dist/runtime-host-cli.js

@@ -363,6 +363,8 @@ function parseSetupCommand(argv) {
     let bindPairingToClient = false;
     let repairRootAfterRemount = false;
     let updateExisting = false;
+    let reuseExistingEnvironment = false;
+    let allowInterruptActiveTasks = false;
     let clientDataRoot;
     let enableDirectPeer = false;
     const coordinationRelays = [];
@@ -418,6 +420,16 @@ function parseSetupCommand(argv) {
                     return error('Duplicate --repair-root-after-remount');
                 repairRootAfterRemount = true;
             },
+            '--allow-interrupt-active-tasks': () => {
+                if (allowInterruptActiveTasks)
+                    return error('Duplicate --allow-interrupt-active-tasks');
+                allowInterruptActiveTasks = true;
+            },
+            '--reuse-existing-environment': () => {
+                if (reuseExistingEnvironment)
+                    return error('Duplicate --reuse-existing-environment');
+                reuseExistingEnvironment = true;
+            },
             '--update-existing': () => {
                 if (updateExisting)
                     return error('Duplicate --update-existing');
@@ -427,6 +439,17 @@ function parseSetupCommand(argv) {
     });
     if ('kind' in options)
         return options;
+    if (reuseExistingEnvironment &&
+        (lifecycle !== 'on_demand' ||
+            updateExisting ||
+            enableDirectPeer ||
+            deferPairingCommit ||
+            bindPairingToClient)) {
+        return error('--reuse-existing-environment requires on-demand local setup without update or remote pairing options');
+    }
+    if (allowInterruptActiveTasks && !updateExisting) {
+        return error('--allow-interrupt-active-tasks requires --update-existing');
+    }
     if (!principalId || !/^[A-Za-z0-9_.:-]{1,128}$/u.test(principalId)) {
         return error('runtime-host setup requires a valid --principal');
     }
@@ -448,6 +471,8 @@ function parseSetupCommand(argv) {
         ...(bindPairingToClient ? { bindPairingToClient: true } : {}),
         ...(repairRootAfterRemount ? { repairRootAfterRemount: true } : {}),
         ...(updateExisting ? { updateExisting: true } : {}),
+        ...(reuseExistingEnvironment ? { reuseExistingEnvironment: true } : {}),
+        ...(allowInterruptActiveTasks ? { allowInterruptActiveTasks: true } : {}),
         ...(clientDataRoot ? { clientDataRoot } : {}),
         ...(enableDirectPeer ? { directPeer: { coordinationRelays } } : {}),
     };
@@ -522,6 +547,7 @@ function parseServiceManagementCommand(argv) {
     let updateTarget;
     let expectedHost;
     let expectedConfigFingerprint;
+    let expectedSourceVersion;
     const flagOptions = action === 'uninstall'
         ? {
             '--retain-managed-deployment': () => {
@@ -580,6 +606,17 @@ function parseServiceManagementCommand(argv) {
                     },
                 }
                 : {}),
+            ...(action === 'update'
+                ? {
+                    '--expected-source-version': (value) => {
+                        if (expectedSourceVersion !== undefined)
+                            return error('Duplicate --expected-source-version');
+                        if (!isProductReleaseVersion(value))
+                            return error('--expected-source-version must be an exact package version');
+                        expectedSourceVersion = value;
+                    },
+                }
+                : {}),
             ...(action === 'update' || action === 'restart'
                 ? {
                     '--expected-host-json': (value) => {
@@ -592,7 +629,7 @@ function parseServiceManagementCommand(argv) {
                     },
                 }
                 : {}),
-            ...(action === 'configure'
+            ...(action === 'configure' || action === 'update'
                 ? {
                     '--expected-config-fingerprint': (value) => {
                         if (expectedConfigFingerprint !== undefined) {
@@ -674,8 +711,9 @@ function parseServiceManagementCommand(argv) {
         };
     }
     if (action === 'update') {
-        if (expectedHost && !options.managedRootId) {
-            return error('--expected-host-json requires --managed-root-id');
+        if ((expectedHost || expectedSourceVersion || expectedConfigFingerprint) &&
+            !options.managedRootId) {
+            return error('Observed Host and deployment fences require --managed-root-id');
         }
         const selector = updateTarget === undefined ? undefined : parseUpdateSelector(updateTarget, 'update');
         if (selector && 'kind' in selector && selector.kind === 'error')
@@ -697,6 +735,8 @@ function parseServiceManagementCommand(argv) {
                 : {}),
             expectedTarget: options.expectedTarget,
             ...(expectedHost ? { expectedHost } : {}),
+            ...(expectedConfigFingerprint ? { expectedConfigFingerprint } : {}),
+            ...(expectedSourceVersion ? { expectedSourceVersion } : {}),
             ...(selector ? { selector } : {}),
             ...(allowManualUpdate ? { allowManualUpdate: true } : {}),
             ...(allowInterruptActiveTasks ? { allowInterruptActiveTasks: true } : {}),

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

@@ -60,7 +60,7 @@ export function createCliHostHandoffSurface(locale, input = process.stdin, outpu
                     '\n');
                 if (view.actions.length === 0)
                     return;
-                const options = copy.actions.map(({ action, label }) => `${action === 'interrupt' ? 'stop' : action === 'retry' ? 'r' : 'Enter'}: ${label}`);
+                const options = copy.actions.map(({ action, label }) => `${action === 'interrupt' ? 'stop' : action === 'retry' ? 'r' : action === 'replace' ? 'update' : '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({
@@ -82,13 +82,15 @@ export function createCliHostHandoffSurface(locale, input = process.stdin, outpu
                     if (readline !== reader || current?.revision !== view.revision)
                         return;
                     const answer = line.trim().toLowerCase();
-                    const action = answer === 'r'
-                        ? 'retry'
-                        : answer === 'stop'
-                            ? 'interrupt'
-                            : answer === ''
-                                ? 'cancel'
-                                : undefined;
+                    const action = answer === 'update'
+                        ? 'replace'
+                        : answer === 'r'
+                            ? 'retry'
+                            : answer === 'stop'
+                                ? 'interrupt'
+                                : answer === ''
+                                    ? 'cancel'
+                                    : undefined;
                     if (!action || !view.actions.includes(action)) {
                         reader.prompt();
                         return;

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

@@ -178,9 +178,6 @@ export async function retireRuntimeHostLifecycleOwner(input) {
 }
 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');
-    }
     const capability = await resolveExistingStorageRoot({
         path: input.rootPath,
         kind: 'interactive',
@@ -189,6 +186,9 @@ async function retireRuntimeHostLifecycleOwnerWithSignal(input, signal) {
     const idleOwner = await tryAcquireStateRootOwner(capability);
     if (idleOwner) {
         try {
+            if (input.expectedOwner && !input.supervisor) {
+                throw new RuntimeHostLifecycleTransactionError('owner_changed', 'The observed Runtime Host has exited');
+            }
             if (input.expectedOwner && input.supervisor) {
                 const status = await input.supervisor.status();
                 assertExpectedSupervisorOwner(input.expectedOwner, status);
@@ -212,6 +212,21 @@ async function retireRuntimeHostLifecycleOwnerWithSignal(input, signal) {
     });
     assertExpectedRuntimeHostOwner(input.expectedOwner, 'registration' in connected ? connected.registration : undefined);
     if (connected.kind !== 'connected') {
+        if (connected.kind === 'incompatible' &&
+            connected.registration?.rootId === input.rootId &&
+            connected.registration.lifecycleMode === 'ephemeral' &&
+            input.expectedOwner &&
+            !input.supervisor &&
+            input.prepareSourceRetirement) {
+            signal?.throwIfAborted();
+            const prepared = await input.prepareSourceRetirement(signal);
+            if (prepared === 'active_work')
+                return { kind: 'active_tasks' };
+            if (prepared === 'prepared') {
+                return waitForRuntimeHostLifecycleOwner(capability, input.timeoutMs ?? 45_000);
+            }
+            throw new RuntimeHostLifecycleTransactionError('transition_failed', 'The installed source package cannot retire this Runtime Host');
+        }
         if (input.supervisor) {
             const status = await input.supervisor.status();
             assertExpectedSupervisorOwner(input.expectedOwner, status);
@@ -316,6 +331,10 @@ export async function replaceRuntimeHostLifecycle(input) {
     const retirement = await retireRuntimeHostLifecycleOwner({
         rootPath: desired.root.path,
         rootId: desired.root.id,
+        ...(input.deps.connectExisting ? { connectExisting: input.deps.connectExisting } : {}),
+        ...(input.prepareSourceRetirement
+            ? { prepareSourceRetirement: input.prepareSourceRetirement }
+            : {}),
         ...(input.retirementSupervisor
             ? { supervisor: input.retirementSupervisor }
             : currentProvider
@@ -345,6 +364,12 @@ export async function replaceRuntimeHostLifecycle(input) {
         }
     }
     catch (activationError) {
+        // An on-demand update may have allowed its successor to open the State Root
+        // before readiness failed. Keep that successor authoritative; configuring an
+        // existing package and supervised updates retain their rollback behavior.
+        if (input.operation === 'update' && desired.lifecycle.mode === 'on_demand') {
+            throw new RuntimeHostLifecycleTransactionError('recovery_failed', 'The updated Runtime Host could not become ready. Its deployment is retained; retry activation or repair it without restoring older code.', { cause: activationError });
+        }
         const rollback = current
             ? {
                 ...current,

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

@@ -74,7 +74,7 @@ export function launchRuntimeHostLocalSourceRetirement(input) {
             : []),
     ];
     return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, args, {
+        const child = spawn(input.sourceNodePath ?? process.execPath, args, {
             // fd 4 inherits the existing owner-authority lease. The source helper
             // holds it only while the authenticated retirement request is in flight.
             stdio: ['ignore', 'ignore', 'inherit', 'ignore', input.inheritableAuthorityLeaseFd],

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

@@ -23,7 +23,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { truncateUtf8 } from '@maka/core/diagnostic-log';
 import { generalizedErrorMessage } from '@maka/core/redaction';
 import { activateRuntimeHostManagedDeployment, connectRemoteRuntimeHost, ensureRuntimeHostPeerIdentity, RuntimeHostOperationError, } from '@maka/runtime-host/client';
-import { RuntimeHostManagedDeploymentError as RuntimeHostDeploymentAuthorityError, encodeRuntimeHostSetupFrame, isSha512PackageIntegrity, resolveRuntimeHostManagedDeployment, runtimeHostManagedOperatorCommand, RUNTIME_HOST_SETUP_ERROR_CODE_MAX_BYTES, RUNTIME_HOST_SETUP_ERROR_MESSAGE_MAX_BYTES, } from '@maka/runtime-host/operator';
+import { RuntimeHostManagedDeploymentError as RuntimeHostDeploymentAuthorityError, encodeRuntimeHostSetupFrame, isSha512PackageIntegrity, resolveRuntimeHostManagedDeployment, resolveRuntimeHostManagedDeploymentAuthority, runtimeHostManagedOperatorCommand, RUNTIME_HOST_SETUP_ERROR_CODE_MAX_BYTES, RUNTIME_HOST_SETUP_ERROR_MESSAGE_MAX_BYTES, } from '@maka/runtime-host/operator';
 import { INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, RUNTIME_HOST_PROTOCOL_VERSION, } from '@maka/runtime-host/protocol';
 import { prepareRuntimeHostAccessCredential, replaceRuntimeHostAccessCredential, revokeRuntimeHostAccessCredential, RuntimeHostAccessUnavailableError, } from './runtime-host-access-command.js';
 import { convergeRuntimeHostManagedOperator, verifyRuntimeHostManagedOperator, isRuntimeHostDevelopmentPackageVersion, openRuntimeHostManagedPackageDeployment, prepareRuntimeHostManagedPackageDeployment, pruneRuntimeHostManagedPackages, removeRuntimeHostManagedDeployment, resolveRuntimeHostManagedPackageCliPath, resolveRuntimeHostManagedControlRoot, resolveRuntimeHostManagedDeploymentRoot, restoreRuntimeHostLegacyManagedOperator, RuntimeHostManagedDeploymentError, } from './runtime-host-managed-deployment.js';
@@ -107,7 +107,7 @@ export async function runRuntimeHostSetupCli(options, overrides = {}) {
     try {
         const rootId = await resolveRuntimeHostSetupRootId(options);
         const controlRoot = resolveRuntimeHostManagedControlRoot(rootId);
-        await withRuntimeHostManagedServiceDeploymentLock(options.clientDataRoot, () => withRuntimeHostManagedServiceLifecycleLock(options.clientDataRoot, () => withRuntimeHostManagedServiceDeploymentLock(controlRoot, () => withRuntimeHostManagedServiceLifecycleLock(controlRoot, () => runRuntimeHostSetupLocked(options, deps, emit), SETUP_LOCK_TIMEOUT_MS), SETUP_LOCK_TIMEOUT_MS), SETUP_LOCK_TIMEOUT_MS), SETUP_LOCK_TIMEOUT_MS);
+        await withRuntimeHostManagedServiceDeploymentLock(options.clientDataRoot, () => withRuntimeHostManagedServiceLifecycleLock(options.clientDataRoot, () => withRuntimeHostManagedServiceDeploymentLock(controlRoot, () => withRuntimeHostManagedServiceLifecycleLock(controlRoot, () => runRuntimeHostSetupLocked(options, deps, emit, rootId), SETUP_LOCK_TIMEOUT_MS), SETUP_LOCK_TIMEOUT_MS), SETUP_LOCK_TIMEOUT_MS), SETUP_LOCK_TIMEOUT_MS);
         return 0;
     }
     catch (error) {
@@ -138,7 +138,30 @@ async function readOptionalLegacyServiceConfig(clientDataRoot) {
         throw error;
     }
 }
-async function runRuntimeHostSetupLocked(options, deps, emit) {
+async function runRuntimeHostSetupLocked(options, deps, emit, rootId) {
+    if (options.reuseExistingEnvironment) {
+        if (options.lifecycle !== 'on_demand' || options.updateExisting) {
+            throw new RuntimeHostSetupError('invalid_setup', 'Environment discovery cannot replace a deployment');
+        }
+        const existing = await resolveRuntimeHostManagedDeploymentAuthority(rootId);
+        if (existing) {
+            const { config, capability } = await resolveRuntimeHostManagedDeployment(rootId);
+            assertCanonicalSetupTarget(options.expectedTarget, rootId, capability.canonicalPath);
+            assertExpectedDeploymentGeneration(options.expectedTarget, config);
+            // The binding comes from canonical authority. The installed operator validates
+            // its own projection when connected; discovery must not rewrite an older launcher.
+            emit({
+                kind: 'existing_environment',
+                version: config.launch.package.version,
+                serviceId: rootId,
+                deploymentId: config.deploymentId,
+                rootId,
+                rootPath: capability.canonicalPath,
+                operator: runtimeHostManagedOperatorCommand(config, process.platform === 'win32' ? 'win32' : 'posix'),
+            });
+            return;
+        }
+    }
     if (options.lifecycle === 'on_demand') {
         await runRuntimeHostOnDemandSetupLocked(options, deps, emit);
         return;
@@ -260,7 +283,7 @@ async function runRuntimeHostSupervisedSetupLocked(options, deps, emit) {
                             .then(() => undefined),
                     }
                     : {}),
-                allowInterruptActiveTasks: Boolean(current && packageChanged && options.updateExisting),
+                allowInterruptActiveTasks: options.allowInterruptActiveTasks === true,
                 deps: lifecycleDeps,
             });
             if (replacement.kind === 'active_tasks') {
@@ -561,7 +584,7 @@ async function runRuntimeHostOnDemandSetupLocked(options, deps, emit) {
                     activateDesired: async () => {
                         await deps.activateDesired({ rootId: capability.rootId });
                     },
-                    allowInterruptActiveTasks: Boolean(current && packageChanged && options.updateExisting),
+                    allowInterruptActiveTasks: options.allowInterruptActiveTasks === true,
                     deps: lifecycleDeps,
                 });
                 if (replacement.kind === 'active_tasks') {
@@ -826,7 +849,7 @@ function createEmitter(json, deps) {
         if (frame.kind === 'progress') {
             deps.writeOutput(`${humanPhase(frame.phase)}\n`);
         }
-        else if (frame.kind === 'complete') {
+        else if (frame.kind === 'complete' || frame.kind === 'existing_environment') {
             deps.writeOutput(`${JSON.stringify(frame, null, 2)}\n`);
         }
         else {

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

@@ -20,13 +20,14 @@ import { spawn } from 'node:child_process';
 import { dirname, join, resolve } from 'node:path';
 import { truncateUtf8 } from '@maka/core/diagnostic-log';
 import { activateRuntimeHostManagedDeployment } from '@maka/runtime-host/client';
-import { createRuntimeHostLegacyPosixOperatorCommand, decodeRuntimeHostServiceManagementFrame, encodeRuntimeHostServiceManagementFrame, RUNTIME_HOST_SERVICE_ERROR_CODE_MAX_BYTES, RUNTIME_HOST_SERVICE_ERROR_MESSAGE_MAX_BYTES, RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY, RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV, RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY, runtimeHostOperatorInvocation, RuntimeHostManagedDeploymentError as RuntimeHostDeploymentAuthorityError, } from '@maka/runtime-host/operator';
-import { assertRuntimeHostManagedOperatorConfig, assertRuntimeHostManagedOperatorDeployment, convergeRuntimeHostManagedOperator, verifyRuntimeHostManagedOperator, openRuntimeHostManagedPackageDeployment, prepareRuntimeHostManagedPackageDeployment, pruneRuntimeHostManagedPackages, resolveRuntimeHostManagedControlRoot, resolveRuntimeHostManagedPackageCliPath, RuntimeHostManagedDeploymentError, } from './runtime-host-managed-deployment.js';
-import { manageRuntimeHostService, replaceRuntimeHostManagedService, resolveRuntimeHostManagedServiceId, RuntimeHostServiceManagerError, verifyRuntimeHostManagedServiceReady, withRuntimeHostManagedServiceDeploymentLock, withRuntimeHostManagedServiceLegacyOperatorLeases, withRuntimeHostManagedServiceLifecycleLock, } from './runtime-host-service-manager.js';
+import { compareProductReleaseVersions, createRuntimeHostLegacyPosixOperatorCommand, decodeRuntimeHostServiceManagementFrame, encodeRuntimeHostServiceManagementFrame, RUNTIME_HOST_SERVICE_ERROR_CODE_MAX_BYTES, RUNTIME_HOST_SERVICE_ERROR_MESSAGE_MAX_BYTES, RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY, RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV, RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY, runtimeHostOperatorInvocation, RuntimeHostManagedDeploymentError as RuntimeHostDeploymentAuthorityError, } from '@maka/runtime-host/operator';
+import { isRuntimeHostDevelopmentPackageVersion, assertRuntimeHostManagedOperatorConfig, assertRuntimeHostManagedOperatorDeployment, convergeRuntimeHostManagedOperator, verifyRuntimeHostManagedOperator, openRuntimeHostManagedPackageDeployment, prepareRuntimeHostManagedPackageDeployment, pruneRuntimeHostManagedPackages, resolveRuntimeHostManagedControlRoot, resolveRuntimeHostManagedPackageCliPath, RuntimeHostManagedDeploymentError, } from './runtime-host-managed-deployment.js';
+import { runtimeHostManagedServiceConfigFingerprint, manageRuntimeHostService, replaceRuntimeHostManagedService, resolveRuntimeHostManagedServiceId, RuntimeHostServiceManagerError, verifyRuntimeHostManagedServiceReady, withRuntimeHostManagedServiceDeploymentLock, withRuntimeHostManagedServiceLegacyOperatorLeases, withRuntimeHostManagedServiceLifecycleLock, } from './runtime-host-service-manager.js';
 import { createPlatformRuntimeHostServiceBackend, resolveRuntimeHostLifecycleProvider, runtimeHostServiceSummary, } from './runtime-host-service-management-command.js';
 import { resolveManagedRuntimeHostUpdateSelection, RuntimeHostUpdateDiscoveryError, } from './runtime-host-update-discovery.js';
 import { RuntimeHostUpdatePackageError, withRuntimeHostRegistryUpdatePackage, } from './runtime-host-update-package.js';
 import { canDiscardRuntimeHostLifecycleDesiredArtifacts, convergeRuntimeHostLifecycleControlProjection, replaceRuntimeHostLifecycle, resolveRecoverableRuntimeHostManagedDeployment, RuntimeHostLifecycleTransactionError, verifyRuntimeHostLifecycleProjection, } from './runtime-host-lifecycle-transaction.js';
+import { launchRuntimeHostLocalSourceRetirement } from './runtime-host-local-source-retirement.js';
 import { manageRuntimeHostManagedLifecycle } from './runtime-host-managed-lifecycle-manager.js';
 const OPERATOR_TIMEOUT_MS = 2 * 60_000;
 const OPERATOR_OUTPUT_MAX_BYTES = 256 * 1024;
@@ -53,6 +54,7 @@ export async function runManagedRuntimeHostUpdateCli(options, overrides = {}, fr
         openDeployment: openRuntimeHostManagedPackageDeployment,
         prepareDeployment: prepareRuntimeHostManagedPackageDeployment,
         prunePackages: pruneRuntimeHostManagedPackages,
+        retireSource: launchRuntimeHostLocalSourceRetirement,
         activateDesired: (input) => activateRuntimeHostManagedDeployment(input, {
             reconcileActivation: async () => undefined,
         }),
@@ -379,7 +381,7 @@ export async function runManagedRuntimeHostUpdateCli(options, overrides = {}, fr
 async function runCanonicalRuntimeHostUpdate(options, deps, emit) {
     let staged;
     try {
-        return await deps.withDeploymentLock(resolveRuntimeHostManagedControlRoot(options.managedRootId), async () => {
+        return await deps.withDeploymentLock(resolveRuntimeHostManagedControlRoot(options.managedRootId), async (inheritableAuthorityLeaseFd) => {
             await deps.canonical.assertOperatorDeployment(options.managedRootId, options.operatorDeploymentId, process.argv[1] ?? '');
             const rejection = await deps.revalidateSelection();
             if (rejection) {
@@ -395,6 +397,10 @@ async function runCanonicalRuntimeHostUpdate(options, deps, emit) {
                 throw new RuntimeHostServiceManagerError('not_installed', 'The managed Runtime Host deployment is not installed');
             }
             const current = recovered.config;
+            if (options.expectedSourceVersion &&
+                current.launch.package.version !== options.expectedSourceVersion) {
+                throw new RuntimeHostServiceManagerError('target_mismatch', 'The installed Runtime Host package changed; check it again before updating');
+            }
             await deps.canonical.convergeControlProjection(current, lifecycleDeps);
             await deps.canonical.verifyProjection(current, lifecycleDeps);
             deps.canonical.assertOperatorConfig(current, options.operatorDeploymentId, process.argv[1] ?? '');
@@ -406,6 +412,21 @@ async function runCanonicalRuntimeHostUpdate(options, deps, emit) {
                 cliPath: process.argv[1] ?? '',
                 expectedTarget: options.expectedTarget,
             }, { resolveProvider: resolveRuntimeHostLifecycleProvider });
+            if (options.expectedConfigFingerprint &&
+                (!currentStatus.service.config ||
+                    runtimeHostManagedServiceConfigFingerprint(currentStatus.service.config) !==
+                        options.expectedConfigFingerprint)) {
+                throw new RuntimeHostServiceManagerError('target_mismatch', 'The managed Runtime Host configuration changed; check it again before updating');
+            }
+            const developmentArtifact = isRuntimeHostDevelopmentPackageVersion(options.version) ||
+                isRuntimeHostDevelopmentPackageVersion(current.launch.package.version);
+            if (developmentArtifact && !options.sourcePackageIntegrity) {
+                throw new RuntimeHostServiceManagerError('target_mismatch', 'Development deployments require an explicitly selected source artifact; source hashes do not establish release order');
+            }
+            if (!developmentArtifact &&
+                compareProductReleaseVersions(options.version, current.launch.package.version) < 0) {
+                throw new RuntimeHostServiceManagerError('target_mismatch', 'This update would downgrade the shared Runtime Host. Update the Client instead.');
+            }
             const targetIntegrity = options.sourcePackageIntegrity ??
                 options.registrySelection?.integrity ??
                 (options.version === current.launch.package.version
@@ -468,15 +489,38 @@ async function runCanonicalRuntimeHostUpdate(options, deps, emit) {
                 },
             };
             emit(progress('retiring', current.launch.package.version, options.version));
-            emit(progress('replacing', current.launch.package.version, options.version));
             const replacement = await deps.canonical.replaceLifecycle({
                 operation: 'update',
+                validateRetiredState: async () => {
+                    emit(progress('replacing', current.launch.package.version, options.version));
+                },
                 current,
                 desired,
                 allowInterruptActiveTasks: options.allowInterruptActiveTasks ?? false,
                 ...(options.expectedHost ? { expectedOwner: options.expectedHost } : {}),
                 ...(desired.lifecycle.mode === 'on_demand'
                     ? {
+                        ...(options.expectedHost
+                            ? {
+                                prepareSourceRetirement: (signal) => {
+                                    if (inheritableAuthorityLeaseFd === undefined) {
+                                        throw new RuntimeHostServiceManagerError('target_mismatch', 'Source-package retirement requires the deployment authority lease');
+                                    }
+                                    return deps.retireSource({
+                                        sourceCliPath: currentCliPath,
+                                        sourceNodePath: current.launch.nodePath,
+                                        rootPath: current.root.path,
+                                        expectedRootId: current.root.id,
+                                        expectedHostEpoch: options.expectedHost.hostEpoch,
+                                        activeWorkPolicy: options.allowInterruptActiveTasks
+                                            ? 'interrupt_active_work'
+                                            : 'refuse_active_work',
+                                        inheritableAuthorityLeaseFd,
+                                        ...(signal ? { signal } : {}),
+                                    });
+                                },
+                            }
+                            : {}),
                         activateDesired: async () => {
                             await deps.activateDesired({ rootId: options.managedRootId });
                         },