maka-agent 0.2.0-dev.26.20260909 → 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/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 });
                         },

package/dist/session-export-command.js

@@ -0,0 +1,72 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { exportSessionBundle } from '@maka/runtime/session-export';
+const USAGE = 'maka session-export --workspace-root <dir> --session <id> --out <file.maka-session>';
+const FAILURE_EXIT_CODES = {
+    session_not_found: 2,
+    session_active: 3,
+    artifact_missing: 4,
+    destination_exists: 5,
+    workspace_not_found: 6,
+};
+function parseArgs(args) {
+    const values = {};
+    for (let index = 0; index < args.length; index += 2) {
+        const name = args[index];
+        const value = args[index + 1];
+        if (!name || !value)
+            throw new Error(USAGE);
+        if (name === '--workspace-root')
+            values.workspaceRoot = value;
+        else if (name === '--session')
+            values.sessionId = value;
+        else if (name === '--out')
+            values.destination = value;
+        else
+            throw new Error(USAGE);
+    }
+    if (!values.workspaceRoot || !values.sessionId || !values.destination)
+        throw new Error(USAGE);
+    return values;
+}
+export async function runMakaSessionExportCli(args) {
+    let parsed;
+    try {
+        parsed = parseArgs(args);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    const result = await exportSessionBundle({
+        workspaceRoot: parsed.workspaceRoot,
+        sessionId: parsed.sessionId,
+        destination: parsed.destination,
+    });
+    if (!result.ok) {
+        process.stderr.write(`${JSON.stringify(result.reason)}\n`);
+        return FAILURE_EXIT_CODES[result.reason.kind] ?? 1;
+    }
+    process.stdout.write(`${JSON.stringify({
+        export: result.export,
+        archiveDigest: result.artifact.archiveDigest,
+        compressedBytes: result.artifact.compressedBytes,
+    })}\n`);
+    return 0;
+}

package/node_modules/@maka/core/dist/usage-stats/types.js

@@ -29,4 +29,6 @@ export const MODEL_CALL_KINDS = [
     'session_recap',
     'daily_review',
     'memory_extraction',
+    'workhub_intent',
+    'workhub_recall',
 ];