maka-agent 0.2.0-dev.8.20260830 → 0.2.0-dev.9.20260831

package/dist/cli-core.js

@@ -340,6 +340,17 @@ export async function runMakaCli(argv = process.argv.slice(2), options = RELEASE
                 ...(command.awaitCoordinatorCommit ? { inheritableAuthorityLeaseFd: 4 } : {}),
             });
         }
+        case 'runtime-host-local-source-retire': {
+            const { runRuntimeHostLocalSourceRetirement } = await import('./runtime-host-local-source-retirement.js');
+            return runRuntimeHostLocalSourceRetirement({
+                rootPath: command.rootPath,
+                expectedRootId: command.expectedRootId,
+                expectedHostEpoch: command.expectedHostEpoch,
+                activeWorkPolicy: command.allowInterruptActiveTasks
+                    ? 'interrupt_active_work'
+                    : 'refuse_active_work',
+            });
+        }
         case 'runtime-host-setup': {
             const { runRuntimeHostSetupCli } = await import('./runtime-host-setup-command.js');
             const { RUNTIME_HOST_SETUP_SOURCE_PACKAGE_INTEGRITY_ENV } = await import('@maka/runtime-host/operator');

package/dist/runtime-host-cli.js

@@ -28,6 +28,8 @@ export function parseRuntimeHostCommand(argv) {
         return parseLocalUpdateApply(argv.slice(1));
     if (argv[0] === 'local-update-activate')
         return parseLocalUpdateActivate(argv.slice(1));
+    if (argv[0] === 'local-source-retire')
+        return parseLocalSourceRetire(argv.slice(1));
     if (argv[0] === 'serve')
         return parseServeCommand(argv.slice(1));
     if (argv[0] === 'setup')
@@ -277,6 +279,48 @@ function parseLocalUpdateActivate(argv) {
         ...(targetIntegrity ? { targetIntegrity } : {}),
     };
 }
+function parseLocalSourceRetire(argv) {
+    const values = new Map();
+    let allowInterruptActiveTasks = false;
+    const options = new Set(['--root', '--expected-root-id', '--expected-host-epoch']);
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === '--allow-interrupt-active-tasks') {
+            if (allowInterruptActiveTasks)
+                return error(`Duplicate ${argument}`);
+            allowInterruptActiveTasks = true;
+            continue;
+        }
+        if (!argument || !options.has(argument))
+            return error(`Unexpected argument: ${argument ?? ''}`);
+        if (values.has(argument))
+            return error(`Duplicate ${argument}`);
+        const parsed = optionValue(argv, index, argument);
+        if (typeof parsed !== 'string')
+            return parsed;
+        values.set(argument, parsed);
+        index += 1;
+    }
+    const rootPath = values.get('--root');
+    const expectedRootId = values.get('--expected-root-id');
+    const expectedHostEpoch = values.get('--expected-host-epoch');
+    if (!rootPath || !expectedRootId || !expectedHostEpoch) {
+        return error('runtime-host local-source-retire requires its exact source Host identity');
+    }
+    if (!isSafeAbsolutePath(rootPath)) {
+        return error('runtime-host local-source-retire root path must be absolute');
+    }
+    if (!/^[a-f0-9]{64}$/u.test(expectedRootId) || !isSafeIdentity(expectedHostEpoch)) {
+        return error('runtime-host local-source-retire Host identity is invalid');
+    }
+    return {
+        kind: 'runtime-host-local-source-retire',
+        rootPath,
+        expectedRootId,
+        expectedHostEpoch,
+        allowInterruptActiveTasks,
+    };
+}
 function isSafeIdentity(value) {
     return value.length <= 512 && !/[\u0000-\u001f\u007f]/u.test(value);
 }

package/dist/runtime-host-installed-update-activator.js

@@ -18,8 +18,18 @@
  */
 import { randomUUID } from 'node:crypto';
 import { createRuntimeHostCandidateLaunchBarrier, prepareConnectedRuntimeHostRetirement, runtimeHostStartupError, } from '@maka/runtime-host/client';
-import { readLocalHostDeploymentRecord } from '@maka/runtime-host/operator';
+import { LocalHostDeploymentAuthorityError, readLocalHostDeploymentRecord, } from '@maka/runtime-host/operator';
 import { INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, RUNTIME_HOST_PROTOCOL_VERSION, } from '@maka/runtime-host/protocol';
+const DURABLE_SETTLEMENT_RETRY_MS = 100;
+const DURABLE_SETTLEMENT_TIMEOUT_MS = 10_000;
+export class RuntimeHostDurableSettlementError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'RuntimeHostDurableSettlementError';
+    }
+}
 export async function runRuntimeHostInstalledUpdateActivator(input, overrides = {}) {
     const launchBarrier = (overrides.createLaunchBarrier ?? createRuntimeHostCandidateLaunchBarrier)();
     const result = await (overrides.connectOrSpawn ?? ((request) => launchBarrier.connect(request)))({
@@ -36,7 +46,7 @@ export async function runRuntimeHostInstalledUpdateActivator(input, overrides =
     });
     if (result.kind === 'connected') {
         let exactTarget = false;
-        let commitWaitOwnsAbort = false;
+        let durableSettlementOwnsRetirement = false;
         try {
             if (result.registration.rootId !== input.expectedRootId ||
                 result.registration.generation !== input.generation ||
@@ -49,9 +59,8 @@ export async function runRuntimeHostInstalledUpdateActivator(input, overrides =
                 if (!input.expectedOwnerInstallationId || !input.targetVersion || !input.targetIntegrity) {
                     throw new Error('The activator is missing its exact durable commit expectation');
                 }
-                commitWaitOwnsAbort = true;
+                durableSettlementOwnsRetirement = true;
                 await (overrides.awaitCoordinatorCommit ?? awaitCoordinatorCommit)({
-                    registration: result.registration,
                     connection: result.connection,
                     expectedRootId: input.expectedRootId,
                     ownerInstallationId: input.expectedOwnerInstallationId,
@@ -69,7 +78,7 @@ export async function runRuntimeHostInstalledUpdateActivator(input, overrides =
             return 0;
         }
         catch (error) {
-            if (exactTarget && !commitWaitOwnsAbort) {
+            if (exactTarget && !durableSettlementOwnsRetirement) {
                 await retireUncommittedTarget({
                     connection: result.connection,
                     ownsCandidate: result.spawnedProcess !== undefined,
@@ -100,8 +109,11 @@ export async function runRuntimeHostInstalledUpdateActivator(input, overrides =
  */
 async function awaitCoordinatorCommit(input) {
     if (typeof process.send !== 'function' || !process.connected) {
-        await retireUncommittedTarget(input);
-        throw new Error('The installed update activator lost its coordinator channel');
+        const settlement = await settleTargetFromDurableAuthority(input);
+        if (settlement === 'retired') {
+            throw new Error('The installed update activator lost its coordinator before ownership committed');
+        }
+        return;
     }
     await new Promise((resolve, reject) => {
         let settled = false;
@@ -119,28 +131,19 @@ async function awaitCoordinatorCommit(input) {
         const onMessage = (message) => {
             if (!isCoordinatorMessage(message))
                 return;
-            if (message.kind === 'committed') {
-                settle(async () => {
-                    if (!(await isCommittedTarget(input))) {
-                        await retireUncommittedTarget(input);
-                        throw new Error('The target activation was acknowledged before durable ownership committed');
-                    }
-                    input.launchBarrier.release();
-                });
-            }
-            if (message.kind === 'abort') {
-                settle(async () => {
-                    await retireUncommittedTarget(input);
-                    throw new Error('The installed update coordinator aborted before durable ownership committed');
-                });
-            }
+            settle(async () => {
+                const settlement = await settleTargetFromDurableAuthority(input);
+                if (settlement === 'retired') {
+                    throw new Error('The installed update coordinator settled without durable ownership');
+                }
+            });
         };
         const onDisconnect = () => {
             settle(async () => {
-                if (await isCommittedTarget(input))
-                    return;
-                await retireUncommittedTarget(input);
-                throw new Error('The installed update coordinator exited before durable ownership committed');
+                const settlement = await settleTargetFromDurableAuthority(input);
+                if (settlement === 'retired') {
+                    throw new Error('The installed update coordinator exited before ownership committed');
+                }
             });
         };
         process.on('message', onMessage);
@@ -149,14 +152,48 @@ async function awaitCoordinatorCommit(input) {
     });
 }
 function isCoordinatorMessage(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        value.kind !== undefined &&
-        (value.kind === 'committed' ||
-            value.kind === 'abort'));
+    return (typeof value === 'object' && value !== null && value.kind === 'settle');
+}
+/**
+ * Makes the activator the only authority for target release versus retirement.
+ * Read failures are ambiguous, so retain the launch barrier and inherited lease
+ * while retrying transient uncertainty. Permanent corruption and a bounded
+ * transient-read timeout fail closed: the activator exits without releasing the
+ * barrier, and the launch-owner guard retires the inaccessible candidate.
+ */
+export async function settleTargetFromDurableAuthority(input, options = {}) {
+    const now = options.now ?? (() => performance.now());
+    const retryRead = options.retryRead ??
+        ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+    const deadline = now() + (options.timeoutMs ?? DURABLE_SETTLEMENT_TIMEOUT_MS);
+    let record;
+    for (;;) {
+        try {
+            record = await input.readRecord(input.expectedRootId);
+            break;
+        }
+        catch (error) {
+            if (error instanceof LocalHostDeploymentAuthorityError &&
+                error.code !== 'authority_io_failed') {
+                throw new RuntimeHostDurableSettlementError(error.code === 'invalid_record' ? 'invalid_record' : 'authority_unavailable', error.code === 'invalid_record'
+                    ? 'The local Runtime Host update requires recovery because its durable owner record is invalid'
+                    : 'The local Runtime Host update requires recovery because its durable owner record cannot be read safely', { cause: error });
+            }
+            const remainingMs = deadline - now();
+            if (remainingMs <= 0) {
+                throw new RuntimeHostDurableSettlementError('authority_unavailable', 'The local Runtime Host update requires recovery because its durable owner record remained unavailable', { cause: error });
+            }
+            await retryRead(Math.min(DURABLE_SETTLEMENT_RETRY_MS, remainingMs));
+        }
+    }
+    if (isCommittedTarget(record, input)) {
+        input.launchBarrier.release();
+        return 'committed';
+    }
+    await retireUncommittedTarget(input);
+    return 'retired';
 }
-async function isCommittedTarget(input) {
-    const record = await input.readRecord(input.expectedRootId);
+function isCommittedTarget(record, input) {
     return (record?.state.kind === 'owned' &&
         record.state.owner.kind === 'cli' &&
         record.state.owner.installationId === input.ownerInstallationId &&

package/dist/runtime-host-installed-update-coordinator.js

@@ -27,6 +27,7 @@ import { resolveStorageRoot } from '@maka/storage/root-authority';
 import { prepareRuntimeHostNpmGlobalStagedDeployment, reconcilePreparedRuntimeHostNpmGlobalDeployment, } from './runtime-host-local-handoff.js';
 import { resolveRuntimeHostNpmGlobalInstallation, } from './runtime-host-cli-installation.js';
 import { assertRuntimeHostArchiveExpansionBudget, withVerifiedRuntimeHostUpdateArchive, } from './runtime-host-update-package.js';
+import { launchRuntimeHostTargetActivator, } from './runtime-host-local-target-activation.js';
 const NPM_TIMEOUT_MS = 5 * 60_000;
 const NPM_OUTPUT_MAX_BYTES = 64 * 1024;
 const OFFLINE_REGISTRY = 'http://127.0.0.1:9/';
@@ -40,7 +41,7 @@ export async function runRuntimeHostInstalledUpdateCoordinator(input, authorityO
         withArchive: withVerifiedRuntimeHostUpdateArchive,
         prepareStaged: prepareRuntimeHostNpmGlobalStagedDeployment,
         reconcile: reconcilePreparedRuntimeHostNpmGlobalDeployment,
-        activateTarget: launchTargetActivator,
+        activateTarget: launchRuntimeHostTargetActivator,
         installArchive: installRuntimeHostNpmGlobalArchive,
         ...overrides,
     };
@@ -161,15 +162,18 @@ export async function runRuntimeHostInstalledUpdateCoordinator(input, authorityO
                     await finalizeInstalledPackage(input, installation, archivePath, installationOptions, deps, inheritableAuthorityLeaseFd);
                 },
             }, authorityOptions);
-            if (result.kind === 'completed' && targetActivator) {
-                await targetActivator.settle('committed');
-                targetActivator = undefined;
-            }
         }
         finally {
-            if (targetActivator)
-                await targetActivator.settle('abort').catch(() => undefined);
+            if (targetActivator) {
+                const settlement = targetActivator.settle();
+                if (result?.kind === 'completed')
+                    await settlement;
+                else
+                    await settlement.catch(() => undefined);
+            }
         }
+        if (!result)
+            throw new Error('The installed update transaction produced no result');
         if (result.kind === 'completed') {
             process.stdout.write(`Updated Maka to ${input.target.version}.\n`);
             return 0;
@@ -258,95 +262,6 @@ export async function installRuntimeHostNpmGlobalArchive(archivePath, inheritabl
         });
     });
 }
-function launchTargetActivator(input) {
-    const args = [
-        input.staged.cliPath,
-        'runtime-host',
-        'local-update-activate',
-        '--root',
-        input.rootPath,
-        '--expected-root-id',
-        input.rootId,
-        '--generation',
-        input.staged.launchGeneration,
-        '--candidate-entrypoint',
-        input.staged.candidateEntrypoint,
-        '--await-coordinator-commit',
-        'true',
-        '--expected-owner-installation-id',
-        input.ownerInstallationId,
-        '--target-version',
-        input.target.version,
-        '--target-integrity',
-        input.target.integrity,
-        ...(input.takeoverHostEpoch ? ['--takeover-host-epoch', input.takeoverHostEpoch] : []),
-    ];
-    return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, args, {
-            // fd 3 is the coordinator channel; fd 4 is the inherited authority
-            // lease. The activator, not the long-lived target, owns that lease.
-            stdio: ['inherit', 'inherit', 'inherit', 'ipc', input.inheritableAuthorityLeaseFd],
-            windowsHide: false,
-        });
-        let ready = false;
-        let settled = false;
-        const closed = new Promise((resolveClosed) => {
-            child.once('close', (code, signal) => resolveClosed({ code, signal }));
-        });
-        const closeError = async () => {
-            const { code, signal } = await closed;
-            if (signal)
-                throw new Error(`Maka target activator exited on ${signal}`);
-            if (code === 3)
-                throw new Error('The activated Runtime Host still owns active work');
-            if (code === 4)
-                throw new Error('The observed Runtime Host requires its operator');
-            throw new Error('The exact Maka target could not be activated');
-        };
-        const settle = async (outcome) => {
-            if (settled)
-                return;
-            settled = true;
-            if (child.connected) {
-                await new Promise((resolveSent, rejectSent) => {
-                    child.send({ kind: outcome }, (error) => (error ? rejectSent(error) : resolveSent()));
-                });
-            }
-            const exited = await closed;
-            if (outcome === 'committed' && (exited.signal || exited.code !== 0)) {
-                if (exited.signal)
-                    throw new Error(`Maka target activator exited on ${exited.signal}`);
-                throw new Error('The exact Maka target activator did not confirm durable ownership');
-            }
-        };
-        child.once('error', reject);
-        child.on('message', (message) => {
-            if (ready || !isTargetActivatorReadyMessage(message))
-                return;
-            ready = true;
-            resolve({ kind: 'ready', settle });
-        });
-        void closed.then(({ code, signal }) => {
-            if (ready)
-                return;
-            if (signal) {
-                reject(new Error(`Maka target activator exited on ${signal}`));
-            }
-            else if (code === 3) {
-                resolve({ kind: 'active_work', settle: async () => undefined });
-            }
-            else if (code === 4) {
-                resolve({ kind: 'operator_required', settle: async () => undefined });
-            }
-            else {
-                void closeError().catch(reject);
-            }
-        });
-    });
-}
-function isTargetActivatorReadyMessage(value) {
-    return (typeof value === 'object' && value !== null && value.kind === 'ready');
-}
 function updateTransactionId(rootId, installation, target) {
     return `npm-global-update:${createHash('sha256')
         .update(rootId)

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

@@ -52,6 +52,7 @@ export async function applyRetiredRuntimeHostLifecycleTransition(input) {
     let transitionError;
     let previousAuthorityRestored = false;
     try {
+        await input.validateRetiredState?.();
         result = await applyRuntimeHostLifecycleTransition(input.owner, {
             operation: input.operation,
             ...(current ? { current } : {}),
@@ -304,6 +305,7 @@ export async function replaceRuntimeHostLifecycle(input) {
         desired,
         deps: input.deps,
         ...(input.activatePrevious ? { activatePrevious: input.activatePrevious } : {}),
+        ...(input.validateRetiredState ? { validateRetiredState: input.validateRetiredState } : {}),
     });
     try {
         if (input.activateDesired) {