maka-agent 0.2.0-dev.26.20260909 → 0.2.0-dev.28.20260911

package/LICENSE

@@ -261,6 +261,112 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+Pi TUI dependency patch
+
+Source: https://www.npmjs.com/package/@earendil-works/pi-tui/v/0.84.4
+Repository: https://github.com/earendil-works/pi/tree/v0.84.4/packages/tui
+Version: 0.84.4
+Dependency patch: patches/@earendil-works+pi-tui+0.84.4.patch
+Copyright (c) 2025 Mario Zechner
+License: MIT
+
+Maka redistributes a source patch that copies mutable editor undo state while
+sharing immutable pasted strings. The following MIT License applies to that
+material:
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Zod dependency patch
+
+Source: https://www.npmjs.com/package/zod/v/4.5.4
+Repository: https://github.com/colinhacks/zod
+Version: 4.5.4
+Dependency patch: patches/zod+4.5.4.patch
+Copyright (c) 2025 Colin McDonnell
+License: MIT
+
+Maka redistributes a source patch that releases recursive parse state after
+completion or failure. The following MIT License applies to that material:
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Model Context Protocol client dependency patch
+
+Source: https://www.npmjs.com/package/@modelcontextprotocol/client/v/2.0.0
+Repository: https://github.com/modelcontextprotocol/typescript-sdk
+Version: 2.0.0
+Dependency patch: patches/@modelcontextprotocol+client+2.0.0.patch
+Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
+Declared package license: MIT
+
+Maka redistributes a source patch that releases settled request observers under
+transport backpressure. The upstream package's LICENSE describes a transition
+from MIT to Apache-2.0: contributions with relicensing consent use Apache-2.0,
+while contributions without that consent retain their original MIT license.
+The Apache License, Version 2.0 is reproduced above. The upstream MIT notice is:
+
+MIT License
+
+Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 Sigstore dependency patch
 
 Source: https://www.npmjs.com/package/@sigstore/core/v/4.0.1

package/dist/cli-core.js

@@ -52,6 +52,10 @@ 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 === 'session-import')
+        return { kind: 'session-import', args: argv.slice(1) };
     if (first === 'eval')
         return { kind: 'eval', args: argv.slice(1) };
     if (first === 'update')
@@ -97,6 +101,8 @@ 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} session-import --workspace-root <dir> --bundle <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 +249,14 @@ 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 'session-import': {
+            const { runMakaSessionImportCli } = await import('./session-import-command.js');
+            return runMakaSessionImportCli(command.args);
+        }
         case 'eval': {
             const { configureInstalledEvalBundle } = await import('./eval-bundle-path.js');
             configureInstalledEvalBundle();
@@ -386,6 +400,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 +501,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 +525,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/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-run-command.js

@@ -569,19 +569,25 @@ class NonInteractiveInteractionController {
     #tasks = new Set();
     #unsubscribe;
     #failure;
-    #failureSignal;
-    #publishFailure;
+    #failureWaiters = new Set();
     constructor(driver, stop) {
         this.#driver = driver;
         this.#stop = stop;
-        this.#failureSignal = new Promise((resolve) => {
-            this.#publishFailure = resolve;
-        });
         this.#unsubscribe = driver.subscribePendingInteractions((pending) => this.#accept(pending));
     }
     race(operation) {
         this.throwIfFailed();
-        return Promise.race([operation, this.#failureSignal.then((error) => Promise.reject(error))]);
+        return new Promise((resolve, reject) => {
+            this.#failureWaiters.add(reject);
+            // Detach completed waits so the controller does not retain consumed event payloads.
+            operation.then((value) => {
+                this.#failureWaiters.delete(reject);
+                resolve(value);
+            }, (error) => {
+                this.#failureWaiters.delete(reject);
+                reject(error);
+            });
+        });
     }
     async settle() {
         await Promise.all([...this.#tasks]);
@@ -623,7 +629,9 @@ class NonInteractiveInteractionController {
         if (this.#failure)
             return;
         this.#failure = error;
-        this.#publishFailure(error);
+        for (const reject of this.#failureWaiters)
+            reject(error);
+        this.#failureWaiters.clear();
     }
 }
 function delay(ms) {

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 });
                         },