@aopslabs/aops 0.3.23 → 0.3.25

package/dist/commands/global-update.js

@@ -29,11 +29,13 @@ const GLOBAL_UPDATE_EXECUTOR_MAX_BYTES = 512 * 1024 * 1024;
 class ChildCommandError extends Error {
     status;
     diagnostic;
-    constructor(command, status, diagnostic) {
+    stdout;
+    constructor(command, status, diagnostic, stdout = '') {
         super(`${path.basename(command)} failed with status ${status ?? 'unknown'}`);
         this.name = 'ChildCommandError';
         this.status = status;
         this.diagnostic = diagnostic;
+        this.stdout = stdout;
     }
 }
 function cleanEnvironment() {
@@ -69,7 +71,7 @@ function defaultRunner(command, args, cwd = process.cwd()) {
         }
         catch {
         }
-        throw new ChildCommandError(command, result.status, diagnostic);
+        throw new ChildCommandError(command, result.status, diagnostic, result.stdout ?? '');
     }
     return result.stdout;
 }
@@ -280,10 +282,33 @@ export function inspectGlobalUpdate(run = defaultRunner) {
 function runInstalledJson(run, cliPath, args) {
     return parseJson(run(process.execPath, [cliPath, ...args]).trim(), args.join('_'));
 }
+function childCommandStdout(error) {
+    const stdout = error?.stdout;
+    return typeof stdout === 'string' && stdout.trim() !== '' ? stdout : undefined;
+}
+function readServiceStatus(run, cliPath, service) {
+    try {
+        return runInstalledJson(run, cliPath, [service, 'status', '--json']);
+    }
+    catch (error) {
+        const stdout = childCommandStdout(error);
+        if (stdout === undefined)
+            throw error;
+        try {
+            const parsed = JSON.parse(stdout.trim());
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw error;
+            return parsed;
+        }
+        catch {
+            throw error;
+        }
+    }
+}
 function serviceSnapshot(run, cliPath) {
     return {
-        server: runInstalledJson(run, cliPath, ['server', 'status', '--json']),
-        cockpit: runInstalledJson(run, cliPath, ['cockpit', 'status', '--json']),
+        server: readServiceStatus(run, cliPath, 'server'),
+        cockpit: readServiceStatus(run, cliPath, 'cockpit'),
     };
 }
 function assertHealthyServices(services) {
@@ -565,6 +590,7 @@ export function dispatchGlobalUpdate(options, run = defaultRunner) {
                 rollbackPerformed: false,
                 error: safeUpdateError(error),
                 events: [],
+                eventTimes: [],
             });
         }
         throw new Error(`global update candidate executor failed; diagnostic record: ${resultPath}`, { cause: error });
@@ -652,24 +678,161 @@ function rollbackServerApplication(run, cliPath, updateId, serverPath, expectedR
 const defaultExecutionDependencies = {
     fetch: globalThis.fetch.bind(globalThis),
     sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+    now: () => new Date(),
 };
+class GlobalUpdateEventLog {
+    now;
+    names = [];
+    times = [];
+    constructor(now) {
+        this.now = now;
+    }
+    push(event) {
+        this.names.push(event);
+        this.times.push(this.now().toISOString());
+    }
+    includes(event) {
+        return this.names.includes(event);
+    }
+    get events() {
+        return [...this.names];
+    }
+    get eventTimes() {
+        return [...this.times];
+    }
+}
 class StartupHealthPending extends Error {
-    constructor(cause) {
+    detail;
+    constructor(cause, detail) {
         super('global_update_health_startup_pending', { cause });
+        this.detail = detail;
+    }
+}
+function serviceHealthFacts(services) {
+    const liveness = services.server.liveness;
+    return {
+        serverState: services.server.runtimeState,
+        serverHealth: liveness?.health,
+        serverReason: services.server.error,
+        cockpitState: services.cockpit.runtimeState,
+        cockpitHealth: services.cockpit.health,
+        cockpitReason: services.cockpit.reason,
+    };
+}
+const HEALTH_SUBJECTS = new Set([
+    'install-readback', 'server-status', 'cockpit-status', 'service-health',
+    'server', 'cockpit', 'cockpit-proxy',
+]);
+const HEALTH_PHASES = new Set(['startup', 'steady']);
+const SAFE_STATE = /^[a-z][a-z0-9-]{0,40}$/u;
+const SAFE_REASON_CODE = /\b(?:aops|community|global_update)_[a-z0-9_]+\b/iu;
+function sanitizeHealthDetail(detail) {
+    const safe = {
+        subject: typeof detail.subject === 'string' && HEALTH_SUBJECTS.has(detail.subject)
+            ? detail.subject
+            : 'unrecognized',
+    };
+    if (typeof detail.phase === 'string' && HEALTH_PHASES.has(detail.phase))
+        safe.phase = detail.phase;
+    if (typeof detail.reachable === 'boolean')
+        safe.reachable = detail.reachable;
+    for (const key of ['sample', 'attempts', 'childStatus', 'status']) {
+        const value = detail[key];
+        if (typeof value === 'number' && Number.isSafeInteger(value))
+            safe[key] = value;
+    }
+    for (const key of ['serverState', 'serverHealth', 'cockpitState', 'cockpitHealth']) {
+        const value = detail[key];
+        if (value === undefined || value === null)
+            continue;
+        safe[key] = typeof value === 'string' && SAFE_STATE.test(value) ? value : 'unrecognized';
     }
+    for (const key of ['serverReason', 'cockpitReason']) {
+        const value = detail[key];
+        if (value === undefined || value === null)
+            continue;
+        safe[key] = typeof value === 'string'
+            ? SAFE_REASON_CODE.exec(value)?.[0]?.toLowerCase() ?? 'unrecognized'
+            : 'unrecognized';
+    }
+    return safe;
+}
+function childCommandStatus(error) {
+    const status = error?.status;
+    return typeof status === 'number' ? status : undefined;
+}
+class ForwardSchemaRetainsTarget extends Error {
+    applicationRollbackError;
+    constructor(applicationRollbackError) {
+        super('global_update_forward_schema_retains_target');
+        this.applicationRollbackError = applicationRollbackError;
+    }
+}
+export class StableHealthFailure extends Error {
+    healthFailure;
+    constructor(detail) {
+        const safe = sanitizeHealthDetail(detail);
+        super(`global_update_stable_health_failed:${String(safe.subject)}`);
+        this.healthFailure = Object.freeze(safe);
+    }
+}
+export function resolveRecoveryClosure(state) {
+    if (!state.applicationSideEffectPossible)
+        return 'prior';
+    return state.applicationRolledBack ? 'prior' : 'target';
+}
+const APPLICATION_PRE_EFFECT_CODES = new Set([
+    'community_native_application_update_content_unchanged',
+]);
+export function applicationSideEffectPossible(attempted, updateError) {
+    if (!attempted)
+        return false;
+    const diagnostic = nestedCommunityDiagnostic(updateError);
+    if (!diagnostic)
+        return true;
+    const cause = diagnostic.cause;
+    const codes = [diagnostic.code, cause?.code];
+    return !codes.some((code) => typeof code === 'string' && APPLICATION_PRE_EFFECT_CODES.has(code));
 }
 async function assertStableHealth(run, plan, execution) {
     const evidence = [];
+    const fail = (error, startup, detail) => {
+        if (startup)
+            throw new StartupHealthPending(error, detail);
+        throw new StableHealthFailure({ ...detail, phase: 'steady' });
+    };
     const collectSample = async (sample, startup) => {
-        const installed = inspectGlobalInstall(run);
+        let installed;
+        try {
+            installed = inspectGlobalInstall(run);
+        }
+        catch (error) {
+            fail(error, startup, { subject: 'install-readback', sample, childStatus: childCommandStatus(error) });
+            throw error;
+        }
         let services;
         try {
-            services = serviceSnapshot(run, installed.cliPath);
+            services = {
+                server: readServiceStatus(run, installed.cliPath, 'server'),
+                cockpit: { runtimeState: 'not-read' },
+            };
+        }
+        catch (error) {
+            fail(error, startup, { subject: 'server-status', sample, childStatus: childCommandStatus(error) });
+            throw error;
+        }
+        try {
+            services = { ...services, cockpit: readServiceStatus(run, installed.cliPath, 'cockpit') };
+        }
+        catch (error) {
+            fail(error, startup, { subject: 'cockpit-status', sample, childStatus: childCommandStatus(error) });
+            throw error;
+        }
+        try {
             assertHealthyServices(services);
         }
         catch (error) {
-            if (startup)
-                throw new StartupHealthPending(error);
+            fail(error, startup, { subject: 'service-health', sample, ...serviceHealthFacts(services) });
             throw error;
         }
         const serverOrigin = validateLoopbackOrigin(services.server.origin, 'AOPS Server origin');
@@ -685,14 +848,12 @@ async function assertStableHealth(run, plan, execution) {
                 response = await execution.fetch(url, { cache: 'no-store', signal: AbortSignal.timeout(15_000) });
             }
             catch (error) {
-                if (startup)
-                    throw new StartupHealthPending(error);
+                fail(error, startup, { subject: name, sample, reachable: false });
                 throw error;
             }
-            if (response.status !== 200 && startup) {
-                throw new StartupHealthPending(new Error(`${name} health returned ${response.status}`));
+            if (response.status !== 200) {
+                fail(new Error(`${name} health returned ${response.status}`), startup, { subject: name, sample, reachable: true, status: response.status });
             }
-            assert.equal(response.status, 200, `${name} health returned ${response.status}`);
             const body = await response.arrayBuffer();
             endpoints.push({ name, url, status: response.status, bytes: body.byteLength });
         }
@@ -708,7 +869,11 @@ async function assertStableHealth(run, plan, execution) {
         catch (error) {
             if (!(error instanceof StartupHealthPending))
                 throw error;
-            startupError = error.cause ?? error;
+            startupError = new StableHealthFailure({
+                ...error.detail,
+                phase: 'startup',
+                attempts: attempt,
+            });
             if (attempt < plan.safety.healthStartupAttempts) {
                 await execution.sleep(plan.safety.healthStartupIntervalMs);
             }
@@ -755,6 +920,9 @@ function nestedCommunityDiagnostic(error) {
     return undefined;
 }
 function safeUpdateError(error) {
+    if (error instanceof StableHealthFailure) {
+        return { code: 'global_update_stable_health_failed', healthFailure: error.healthFailure };
+    }
     const diagnostic = nestedCommunityDiagnostic(error);
     if (diagnostic) {
         const details = diagnostic.details;
@@ -785,6 +953,160 @@ function writeTerminalUpdateResult(plan, result) {
     const resultPath = path.join(plan.operationRoot, RESULT_FILE);
     writeFileSync(resultPath, `${JSON.stringify(result, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
 }
+const RECOVERY_CONTRACT = 'aops.global-update-recovery/v1';
+const RECOVERY_RESULT_PATTERN = /^update-recovery-(0|[1-9]\d*)\.json$/u;
+const RECOVERABLE_TERMINAL_STATUSES = new Set(['recovery-required']);
+function recoveryAttemptFiles(plan) {
+    const operationRoot = plainDirectory(plan.operationRoot, 'global update operation root');
+    const attempts = [];
+    for (const entry of readdirSync(operationRoot)) {
+        const match = RECOVERY_RESULT_PATTERN.exec(entry);
+        if (match)
+            attempts.push({ attempt: Number(match[1]), path: path.join(operationRoot, entry) });
+    }
+    return attempts.sort((left, right) => left.attempt - right.attempt);
+}
+function nextRecoveryResultPath(plan) {
+    const attempts = recoveryAttemptFiles(plan);
+    const next = attempts.length === 0 ? 1 : attempts[attempts.length - 1].attempt + 1;
+    return path.join(plan.operationRoot, `update-recovery-${next}.json`);
+}
+function sameClosure(installed, expected) {
+    try {
+        assert.deepEqual(installed, expected);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function writeRecoveryResult(resultPath, result) {
+    writeFileSync(resultPath, `${JSON.stringify(result, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+}
+function preflightGlobalUpdateRecovery(options, run) {
+    const plan = readGlobalUpdatePlan(options.plan);
+    assert.equal(options.confirm, plan.planId, 'global update recovery confirmation does not match the exact plan');
+    const terminalPath = path.join(plan.operationRoot, RESULT_FILE);
+    assert.equal(existsSync(terminalPath), true, 'global_update_recovery_requires_terminal_result');
+    const terminal = parseJson(readFileSync(terminalPath, 'utf8'), 'global_update_result');
+    assert.equal(terminal.planId, plan.planId, 'terminal result belongs to a different plan');
+    const terminalStatus = String(terminal.status);
+    assert.equal(RECOVERABLE_TERMINAL_STATUSES.has(terminalStatus), true, `global_update_recovery_status_not_recoverable:${terminalStatus}`);
+    const installed = inspectGlobalInstall(run);
+    assert.equal(installed.globalPrefix, plan.globalPrefix, 'global npm prefix changed after update planning');
+    const installedClosure = [installed.packages, installed.topology];
+    const atTarget = sameClosure(installedClosure, [plan.target.packages, plan.target.topology]);
+    const atPrior = sameClosure(installedClosure, [plan.prior.packages, plan.prior.topology]);
+    assert.equal(atTarget || atPrior, true, 'global_update_recovery_closure_drifted');
+    const succeeded = recoveryAttemptFiles(plan)
+        .map((file) => ({
+        ...file,
+        record: parseJson(readFileSync(file.path, 'utf8'), 'global_update_recovery_result'),
+    }))
+        .find((entry) => entry.record.status === 'recovered');
+    if (succeeded) {
+        assert.equal(atTarget, true, 'global_update_recovery_recorded_but_closure_moved');
+    }
+    return { plan, terminalStatus, installed, atTarget, atPrior, succeeded };
+}
+export function dispatchGlobalUpdateRecovery(options, run = defaultRunner) {
+    const preflight = preflightGlobalUpdateRecovery(options, run);
+    const { plan } = preflight;
+    if (preflight.succeeded)
+        return preflight.succeeded.record;
+    const resultPath = nextRecoveryResultPath(plan);
+    let executorStarted = false;
+    try {
+        const { receipt, receiptPath } = stageCandidateGlobalUpdateExecutor(plan, run);
+        executorStarted = true;
+        return parseJson(run(process.execPath, [
+            receipt.entrypoint,
+            'update',
+            'recover',
+            '--plan',
+            options.plan,
+            '--confirm',
+            options.confirm,
+            '--executor-receipt',
+            receiptPath,
+            '--json',
+        ]).trim(), 'global_update_recovery_result');
+    }
+    catch (error) {
+        if (!existsSync(resultPath)) {
+            writeRecoveryResult(resultPath, {
+                schemaVersion: 1,
+                contract: RECOVERY_CONTRACT,
+                status: executorStarted ? 'executor-result-missing' : 'executor-staging-failed',
+                planId: plan.planId,
+                failedStage: executorStarted ? 'candidate-executor' : 'stage-candidate-executor',
+                globalState: executorStarted ? 'unknown-requires-inspection' : 'unchanged',
+                error: safeUpdateError(error),
+                events: [],
+                eventTimes: [],
+            });
+        }
+        throw new Error(`global update recovery executor failed; diagnostic record: ${resultPath}`, { cause: error });
+    }
+}
+export async function recoverGlobalUpdate(options, run = defaultRunner, execution = defaultExecutionDependencies) {
+    const preflight = preflightGlobalUpdateRecovery(options, run);
+    const { plan, installed: current, atTarget, terminalStatus } = preflight;
+    const installedCliRoot = plainDirectory(path.dirname(path.dirname(current.cliPath)), 'installed global CLI root');
+    const invokedEntrypoint = plainFile(process.argv[1], 'invoked AOPS CLI entrypoint');
+    const relativeToInstalled = path.relative(installedCliRoot, invokedEntrypoint);
+    assert.equal(relativeToInstalled.startsWith('..') || path.isAbsolute(relativeToInstalled), true, 'global_update_recovery_must_not_run_from_the_replaced_cli');
+    if (preflight.succeeded)
+        return preflight.succeeded.record;
+    const resultPath = nextRecoveryResultPath(plan);
+    const events = new GlobalUpdateEventLog(execution.now ?? (() => new Date()));
+    try {
+        stopService(run, current.cliPath, 'cockpit', true);
+        stopService(run, current.cliPath, 'server', true);
+        if (atTarget) {
+            events.push('retained:target-closure');
+        }
+        else {
+            installGlobalUpdateClosure(run, plan, plan.candidates, plan.target.topology);
+            events.push('installed:target-closure');
+        }
+        const restored = inspectGlobalInstall(run);
+        assert.deepEqual(restored.packages, plan.target.packages, 'recovered closure is not the exact target');
+        assert.deepEqual(restored.topology, plan.target.topology, 'recovered topology is not canonical');
+        startService(run, restored.cliPath, 'server');
+        events.push('started:server');
+        startService(run, restored.cliPath, 'cockpit');
+        events.push('started:cockpit');
+        const healthEvidence = await assertStableHealth(run, plan, execution);
+        const result = {
+            schemaVersion: 1,
+            contract: RECOVERY_CONTRACT,
+            status: 'recovered',
+            planId: plan.planId,
+            installed: plan.target.packages,
+            recoveredFrom: terminalStatus,
+            events: events.events,
+            eventTimes: events.eventTimes,
+            healthEvidence,
+        };
+        writeRecoveryResult(resultPath, result);
+        return result;
+    }
+    catch (recoveryError) {
+        writeRecoveryResult(resultPath, {
+            schemaVersion: 1,
+            contract: RECOVERY_CONTRACT,
+            status: 'recovery-failed',
+            planId: plan.planId,
+            recoveredFrom: terminalStatus,
+            globalState: 'unknown-requires-inspection',
+            error: safeUpdateError(recoveryError),
+            events: events.events,
+            eventTimes: events.eventTimes,
+        });
+        throw recoveryError;
+    }
+}
 export async function applyGlobalUpdate(options, run = defaultRunner, execution = defaultExecutionDependencies) {
     const plan = readGlobalUpdatePlan(options.plan);
     assert.equal(options.confirm, plan.planId, 'global update confirmation does not match the exact plan');
@@ -794,8 +1116,9 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
     assert.deepEqual(current.topology, plan.prior.topology, 'global package topology changed after update planning');
     assert.equal(current.globalPrefix, plan.globalPrefix, 'global npm prefix changed after update planning');
     assertHealthyServices(serviceSnapshot(run, current.cliPath));
-    const events = [];
+    const events = new GlobalUpdateEventLog(execution.now ?? (() => new Date()));
     let applicationUpdateId = null;
+    let applicationUpdateAttempted = false;
     let failedStage = 'stop-cockpit';
     try {
         stopService(run, current.cliPath, 'cockpit');
@@ -817,6 +1140,7 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
         }
         else {
             failedStage = 'update-server-application';
+            applicationUpdateAttempted = true;
             applicationUpdateId = updateServerApplication(run, updated.cliPath, {
                 prior: plan.prior.packages.server,
                 target: plan.target.packages.server,
@@ -835,7 +1159,8 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
             planId: plan.planId,
             installed: updated.packages,
             rollbackPerformed: false,
-            events,
+            events: events.events,
+            eventTimes: events.eventTimes,
             healthEvidence,
             next: 'Exit and reopen the AOPS TUI to run the newly installed binary.',
         };
@@ -844,6 +1169,7 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
     }
     catch (updateError) {
         const updateStage = failedStage;
+        const sideEffectPossible = applicationSideEffectPossible(applicationUpdateAttempted, updateError);
         events.push('rollback:started');
         let rollbackError;
         try {
@@ -854,19 +1180,89 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
             const restored = inspectGlobalInstall(run);
             assert.deepEqual(restored.packages, plan.prior.packages, 'rollback package closure is not exact');
             assert.deepEqual(restored.topology, plan.prior.topology, 'rollback package topology is not exact');
+            let applicationRollbackError;
             if (applicationUpdateId) {
-                rollbackServerApplication(run, restored.cliPath, applicationUpdateId, restored.serverPath, plan.prior.packages.server);
-                events.push('rolled-back:server-application');
+                try {
+                    rollbackServerApplication(run, restored.cliPath, applicationUpdateId, restored.serverPath, plan.prior.packages.server);
+                    events.push('rolled-back:server-application');
+                }
+                catch (error) {
+                    applicationRollbackError = error;
+                    events.push('failed:server-application-rollback');
+                }
+            }
+            else if (sideEffectPossible) {
+                applicationRollbackError = new Error('global_update_application_outcome_unrecorded');
+                events.push('failed:server-application-outcome-unrecorded');
             }
             else {
                 startService(run, restored.cliPath, 'server');
                 events.push('started:server-restore');
             }
+            if (resolveRecoveryClosure({
+                applicationSideEffectPossible: sideEffectPossible,
+                applicationRolledBack: applicationUpdateId !== null && applicationRollbackError === undefined,
+            }) === 'target') {
+                throw new ForwardSchemaRetainsTarget(applicationRollbackError);
+            }
             startService(run, restored.cliPath, 'cockpit');
             await assertStableHealth(run, plan, execution);
             events.push('rollback:healthy');
         }
         catch (rollbackError) {
+            if (rollbackError instanceof ForwardSchemaRetainsTarget) {
+                try {
+                    installGlobalUpdateClosure(run, plan, plan.candidates, plan.target.topology);
+                    events.push('reinstalled:target-closure');
+                    const retained = inspectGlobalInstall(run);
+                    assert.deepEqual(retained.packages, plan.target.packages, 'retained target closure is not exact');
+                    assert.deepEqual(retained.topology, plan.target.topology, 'retained target topology is not canonical');
+                    startService(run, retained.cliPath, 'server');
+                    events.push('started:server-target-retained');
+                    startService(run, retained.cliPath, 'cockpit');
+                    events.push('started:cockpit-target-retained');
+                    await assertStableHealth(run, plan, execution);
+                    events.push('target-retained:healthy');
+                }
+                catch (retainError) {
+                    writeTerminalUpdateResult(plan, {
+                        schemaVersion: 1,
+                        contract: RESULT_CONTRACT,
+                        status: 'recovery-required',
+                        planId: plan.planId,
+                        failedStage: updateStage,
+                        rollbackPerformed: false,
+                        rollback: {
+                            status: 'failed',
+                            reason: 'application_rollback_failed_forward_schema',
+                            error: safeUpdateError(rollbackError.applicationRollbackError),
+                        },
+                        targetRetention: { status: 'failed', error: safeUpdateError(retainError) },
+                        error: safeUpdateError(updateError),
+                        events: events.events,
+                        eventTimes: events.eventTimes,
+                    });
+                    throw new AggregateError([updateError, rollbackError.applicationRollbackError, retainError], `global update failed, application rollback failed, and the schema-compatible target closure could not be restarted; services may remain stopped; recovery artifacts remain at ${plan.operationRoot}`);
+                }
+                writeTerminalUpdateResult(plan, {
+                    schemaVersion: 1,
+                    contract: RESULT_CONTRACT,
+                    status: 'failed-target-retained',
+                    planId: plan.planId,
+                    failedStage: updateStage,
+                    installed: plan.target.packages,
+                    rollbackPerformed: false,
+                    rollback: {
+                        status: 'not-applicable',
+                        reason: 'application_rollback_failed_forward_schema',
+                        applicationRollbackError: safeUpdateError(rollbackError.applicationRollbackError),
+                    },
+                    error: safeUpdateError(updateError),
+                    events: events.events,
+                    eventTimes: events.eventTimes,
+                });
+                throw new AggregateError([updateError, rollbackError.applicationRollbackError], 'global update failed and the application could not be rolled back; the schema-compatible target closure was reinstated and healthy services were restarted');
+            }
             try {
                 const restoredForRecovery = inspectGlobalInstall(run);
                 assert.deepEqual(restoredForRecovery.packages, plan.prior.packages, 'service recovery package closure is not exact');
@@ -891,7 +1287,8 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
                     rollback: { status: 'failed', error: safeUpdateError(rollbackError) },
                     serviceRecovery: { status: 'failed', error: safeUpdateError(serviceRecoveryError) },
                     error: safeUpdateError(updateError),
-                    events,
+                    events: events.events,
+                    eventTimes: events.eventTimes,
                 });
                 throw new AggregateError([updateError, rollbackError, serviceRecoveryError], `global update, automatic rollback, and service recovery failed; services may remain stopped; recovery artifacts remain at ${plan.operationRoot}`);
             }
@@ -909,7 +1306,8 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
                     applicationRollbackError: safeUpdateError(rollbackError),
                 },
                 error: safeUpdateError(updateError),
-                events,
+                events: events.events,
+                eventTimes: events.eventTimes,
             });
             throw new AggregateError([updateError, rollbackError], `global update and application rollback failed; prior exact packages and healthy services were restored; recovery artifacts remain at ${plan.operationRoot}`);
         }
@@ -923,7 +1321,8 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
             rollbackPerformed: true,
             rollback: { status: 'healthy' },
             error: safeUpdateError(updateError),
-            events,
+            events: events.events,
+            eventTimes: events.eventTimes,
         });
         throw new Error('global update failed; the prior exact packages were restored and are healthy', { cause: updateError });
     }
@@ -931,6 +1330,22 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
 function output(value, json) {
     process.stdout.write(`${JSON.stringify(value, null, json ? 0 : 2)}\n`);
 }
+const defaultRecoveryCommandDependencies = {
+    dispatch: dispatchGlobalUpdateRecovery,
+    recover: recoverGlobalUpdate,
+    readPlan: readGlobalUpdatePlan,
+    validateExecutor: validateCandidateExecutorInvocation,
+    emit: output,
+};
+export async function runGlobalUpdateRecoveryCommand(options, dependencies = defaultRecoveryCommandDependencies) {
+    if (typeof options.executorReceipt === 'string') {
+        const plan = dependencies.readPlan(options.plan);
+        dependencies.validateExecutor(plan, options.executorReceipt);
+        dependencies.emit(await dependencies.recover(options), options.json === true);
+        return;
+    }
+    dependencies.emit(dependencies.dispatch(options), options.json === true);
+}
 export function makeGlobalUpdateCommand() {
     const command = new Command('update').description('Check, prepare, and apply a guarded global AOPS npm update');
     command
@@ -960,6 +1375,16 @@ export function makeGlobalUpdateCommand() {
         }
         output(dispatchGlobalUpdate(options), options.json === true);
     });
+    command
+        .command('recover')
+        .description('Finish one stranded exact plan at its target closure after a failed apply')
+        .requiredOption('--plan <path>', 'Exact update-plan.json path returned by prepare')
+        .requiredOption('--confirm <plan-id>', 'Exact sha256 plan id returned by prepare')
+        .addOption(new Option('--executor-receipt <path>').hideHelp())
+        .option('--json', 'Output JSON')
+        .action(async (options) => {
+        await runGlobalUpdateRecoveryCommand(options);
+    });
     command
         .command('bridge')
         .description('Apply an old-CLI plan from an externally launched exact public candidate')

package/dist/commands/memory.js

@@ -486,13 +486,19 @@ function matchesClassificationFilters(record, options) {
     }
     return true;
 }
-function filterHostedMemoryResult(result, options) {
+export function filterHostedMemoryResult(result, options) {
     if (buildClassificationTags(options).length === 0)
         return result;
     if (Array.isArray(result)) {
         return result.filter((entry) => matchesClassificationFilters(entry, options));
     }
-    if (!isRecord(result) || !Array.isArray(result.data))
+    if (!isRecord(result))
+        return result;
+    if (Array.isArray(result.items)) {
+        const items = result.items.filter((entry) => matchesClassificationFilters(entry, options));
+        return { ...result, items, returned: items.length };
+    }
+    if (!Array.isArray(result.data))
         return result;
     return {
         ...result,

package/dist/commands/official-catalog.js

@@ -115,7 +115,7 @@ export function makeOfficialCatalogSetupCommand(dependencies = {}) {
 The reserved scope is fixed to ${OFFICIAL_CATALOG_SCOPE_V1.slug}. It is routing
 identity only: official trust comes from the verified Community release and the
 package/release digests persisted in SkillVersion meta. Import is inert and does
-not select a discipline, mutate a mission policy, or touch user/project scopes.
+not select a discipline, mutate a policy, or touch user/project scopes.
 
 Agentspace owns the atomic composite operations and durable receipts. Inspect
 their exact server contracts with:

package/dist/commands/plan.js

@@ -37,8 +37,8 @@ export function makePlanCommand() {
         '  For one-item checklist edits, use `aops-cli pm utask ...` until top-level plan microtask sugar is added.\n');
     applyPlanContextOptions(applyMemoryCadenceOptions(applyWriteOptions(cmd
         .command('create')
-        .description('Create a sprint-backed implementation plan for a kanban task')
-        .requiredOption('--task <id>', 'Kanban task id')
+        .description('Create a sprint-backed implementation plan, optionally bound to a kanban task')
+        .option('--task <id>', 'Optional kanban task id to bind the plan to')
         .requiredOption('--name <name>', 'Plan name')
         .requiredOption('--goal <text>', 'Plan goal')
         .option('--reference <value>', 'Repeatable reference item', collectRepeatedOption, [])