@aopslabs/aops 0.3.17 → 0.3.19

package/dist/commands/global-update.js

@@ -1,14 +1,18 @@
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, readFileSync, realpathSync, writeFileSync, } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { compareCanonicalText } from '@aopslabs/artifact-trust-contracts';
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
+import { isCommunityDiagnosticV1 } from '../lib/community-diagnostic.js';
 const CHECK_CONTRACT = 'aops.global-update-check/v1';
 const PLAN_CONTRACT = 'aops.global-update-plan/v1';
 const RESULT_CONTRACT = 'aops.global-update-result/v1';
+const EXECUTOR_CONTRACT = 'aops.global-update-executor/v1';
+const RESULT_FILE = 'update-result.json';
+const EXECUTOR_RECEIPT_FILE = 'executor-receipt.json';
 const PUBLIC_REGISTRY = 'https://registry.npmjs.org';
 const EXACT_STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
 const PLAN_ID = /^sha256:[a-f0-9]{64}$/u;
@@ -20,6 +24,16 @@ const HEALTH_SAMPLES = 4;
 const HEALTH_INTERVAL_MS = 3_000;
 const HEALTH_STARTUP_ATTEMPTS = 30;
 const HEALTH_STARTUP_INTERVAL_MS = 2_000;
+class ChildCommandError extends Error {
+    status;
+    diagnostic;
+    constructor(command, status, diagnostic) {
+        super(`${path.basename(command)} failed with status ${status ?? 'unknown'}`);
+        this.name = 'ChildCommandError';
+        this.status = status;
+        this.diagnostic = diagnostic;
+    }
+}
 function cleanEnvironment() {
     return {
         ...process.env,
@@ -44,7 +58,17 @@ function defaultRunner(command, args, cwd = process.cwd()) {
     });
     if (result.error)
         throw result.error;
-    assert.equal(result.status, 0, `${command} ${args.join(' ')} failed\n${result.stdout}\n${result.stderr}`);
+    if (result.status !== 0) {
+        let diagnostic;
+        try {
+            const parsed = JSON.parse(result.stderr.trim());
+            if (isCommunityDiagnosticV1(parsed.error))
+                diagnostic = parsed.error;
+        }
+        catch {
+        }
+        throw new ChildCommandError(command, result.status, diagnostic);
+    }
     return result.stdout;
 }
 export function resolveNpmInvocation(options = {}) {
@@ -54,13 +78,12 @@ export function resolveNpmInvocation(options = {}) {
     const nodeExecutable = path.resolve(options.nodeExecutable ?? process.execPath);
     const environment = options.environment ?? process.env;
     const fileExists = options.fileExists ?? existsSync;
-    const candidates = [
-        path.join(path.dirname(nodeExecutable), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
-    ];
+    const candidates = [];
     const npmExecPath = environment.npm_execpath?.trim();
     if (npmExecPath && /^npm-cli\.(?:c?js)$/iu.test(path.basename(npmExecPath))) {
         candidates.push(path.resolve(npmExecPath));
     }
+    candidates.push(path.join(path.dirname(nodeExecutable), 'node_modules', 'npm', 'bin', 'npm-cli.js'));
     for (const entry of String(environment.PATH ?? '').split(path.delimiter)) {
         if (!entry.trim())
             continue;
@@ -108,6 +131,57 @@ export function compareStableVersions(left, right) {
 function sha256(file) {
     return createHash('sha256').update(readFileSync(file)).digest('hex');
 }
+function executorTreeInventory(executorRoot) {
+    const root = plainDirectory(executorRoot, 'candidate executor root');
+    const records = [];
+    let totalBytes = 0;
+    const visit = (directory, prefix) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })
+            .sort((left, right) => compareCanonicalText(left.name, right.name))) {
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const absolute = path.join(directory, entry.name);
+            const stat = lstatSync(absolute);
+            const normalizedRelative = relative.replace(/\\/gu, '/');
+            if (stat.isSymbolicLink()) {
+                const target = readlinkSync(absolute);
+                const resolved = realpathSync.native(absolute);
+                ensureWithin(root, resolved, `candidate executor link ${normalizedRelative}`);
+                records.push({
+                    path: normalizedRelative,
+                    type: 'link',
+                    target: target.replace(/\\/gu, '/'),
+                    resolved: path.relative(root, resolved).replace(/\\/gu, '/'),
+                });
+                assert.equal(records.length <= 20_000, true, 'candidate executor entry bound exceeded');
+                continue;
+            }
+            if (stat.isDirectory()) {
+                records.push({ path: normalizedRelative, type: 'directory', mode: stat.mode & 0o777 });
+                assert.equal(records.length <= 20_000, true, 'candidate executor entry bound exceeded');
+                visit(absolute, relative);
+                continue;
+            }
+            assert.equal(stat.isFile(), true, `candidate executor entry invalid: ${normalizedRelative}`);
+            const canonical = plainFile(absolute, `candidate executor file ${normalizedRelative}`);
+            ensureWithin(root, canonical, `candidate executor file ${normalizedRelative}`);
+            totalBytes += stat.size;
+            records.push({
+                path: normalizedRelative,
+                type: 'file',
+                mode: stat.mode & 0o777,
+                bytes: stat.size,
+                sha256: sha256(canonical),
+            });
+            assert.equal(records.length <= 20_000, true, 'candidate executor entry bound exceeded');
+            assert.equal(totalBytes <= 512 * 1024 * 1024, true, 'candidate executor package byte bound exceeded');
+        }
+    };
+    visit(root, '');
+    return {
+        entryCount: records.length,
+        sha256: createHash('sha256').update(JSON.stringify(records)).digest('hex'),
+    };
+}
 function plainDirectory(candidate, label) {
     const absolute = path.resolve(candidate);
     const stat = lstatSync(absolute);
@@ -364,6 +438,136 @@ export function readGlobalUpdatePlan(planPath) {
     assert.equal(plan.safety.healthStartupIntervalMs, HEALTH_STARTUP_INTERVAL_MS);
     return plan;
 }
+function readCandidateExecutorReceipt(plan, receiptPath) {
+    const operationRoot = plainDirectory(plan.operationRoot, 'global update operation root');
+    const resolved = plainFile(receiptPath, 'global update executor receipt');
+    assert.equal(resolved, path.join(operationRoot, EXECUTOR_RECEIPT_FILE), 'global update executor receipt must stay at the operation root');
+    const receipt = parseJson(readFileSync(resolved, 'utf8'), 'global_update_executor_receipt');
+    assert.equal(receipt.schemaVersion, 1);
+    assert.equal(receipt.contract, EXECUTOR_CONTRACT);
+    assert.equal(receipt.planId, plan.planId, 'global update executor plan identity mismatch');
+    const executorRoot = plainDirectory(receipt.executorRoot, 'global update executor root');
+    ensureWithin(operationRoot, executorRoot, 'global update executor root');
+    assert.equal(executorRoot, path.join(operationRoot, 'executor'));
+    const entrypoint = plainFile(receipt.entrypoint, 'global update executor entrypoint');
+    ensureWithin(executorRoot, entrypoint, 'global update executor entrypoint');
+    assert.equal(entrypoint, receipt.entrypoint, 'global update executor entrypoint must be canonical');
+    assert.match(receipt.entrypointSha256, SHA256);
+    assert.equal(sha256(entrypoint), receipt.entrypointSha256, 'global update executor entrypoint changed');
+    const candidate = packageRecordByName(plan.candidates, '@aopslabs/aops');
+    assert.equal(receipt.candidate.version, candidate.version);
+    assert.equal(receipt.candidate.sha256, candidate.sha256);
+    const executorPackageRoot = path.join(executorRoot, 'node_modules', '@aopslabs', 'aops');
+    const executorManifest = packageManifest(executorPackageRoot, '@aopslabs/aops');
+    assert.equal(executorManifest.version, plan.target.packages.cli);
+    const dependencies = executorManifest.dependencies;
+    assert.equal(dependencies?.['@aopslabs/aops-server'], plan.target.packages.server);
+    const executorServer = packageManifest(path.join(executorRoot, 'node_modules', '@aopslabs', 'aops-server'), '@aopslabs/aops-server');
+    assert.equal(executorServer.version, plan.target.packages.server);
+    assert.equal(Number.isSafeInteger(receipt.executorEntryCount), true);
+    assert.match(receipt.executorContentSha256, SHA256);
+    const inventory = executorTreeInventory(executorRoot);
+    assert.equal(inventory.entryCount, receipt.executorEntryCount, 'candidate executor entry count changed');
+    assert.equal(inventory.sha256, receipt.executorContentSha256, 'candidate executor content changed');
+    return receipt;
+}
+export function stageCandidateGlobalUpdateExecutor(plan, run = defaultRunner) {
+    const receiptPath = path.join(plan.operationRoot, EXECUTOR_RECEIPT_FILE);
+    if (existsSync(receiptPath)) {
+        return { receipt: readCandidateExecutorReceipt(plan, receiptPath), receiptPath };
+    }
+    const executorRoot = path.join(plan.operationRoot, 'executor');
+    assert.equal(existsSync(executorRoot), false, 'unverified global update executor directory already exists');
+    mkdirSync(executorRoot, { mode: 0o700 });
+    const cacheRoot = path.join(plan.operationRoot, 'cache');
+    mkdirSync(cacheRoot, { recursive: true, mode: 0o700 });
+    const cli = packageRecordByName(plan.candidates, '@aopslabs/aops');
+    const server = packageRecordByName(plan.candidates, '@aopslabs/aops-server');
+    runNpm(run, publicNpmArgs([
+        '--prefix',
+        executorRoot,
+        'install',
+        '--ignore-scripts',
+        '--omit=dev',
+        '--prefer-offline',
+        `--cache=${cacheRoot}`,
+        '--fund=false',
+        '--audit=false',
+        cli.path,
+        server.path,
+    ]));
+    const entrypoint = plainFile(path.join(executorRoot, 'node_modules', '@aopslabs', 'aops', 'dist', 'main.js'), 'global update executor entrypoint');
+    const inventory = executorTreeInventory(executorRoot);
+    const receipt = {
+        schemaVersion: 1,
+        contract: EXECUTOR_CONTRACT,
+        planId: plan.planId,
+        executorRoot: plainDirectory(executorRoot, 'global update executor root'),
+        entrypoint,
+        entrypointSha256: sha256(entrypoint),
+        executorEntryCount: inventory.entryCount,
+        executorContentSha256: inventory.sha256,
+        candidate: { version: cli.version, sha256: cli.sha256 },
+    };
+    writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    return { receipt: readCandidateExecutorReceipt(plan, receiptPath), receiptPath };
+}
+function validateCandidateExecutorInvocation(plan, receiptPath) {
+    const receipt = readCandidateExecutorReceipt(plan, receiptPath);
+    const invokedEntrypoint = plainFile(process.argv[1], 'invoked AOPS CLI entrypoint');
+    assert.equal(invokedEntrypoint, receipt.entrypoint, 'candidate update execution must run from the verified staged entrypoint');
+    return receipt;
+}
+export function validateLegacyGlobalUpdateBridgeInvocation(plan, invokedEntrypoint = process.argv[1]) {
+    const invoked = plainFile(invokedEntrypoint, 'legacy update bridge candidate entrypoint');
+    const globalCliRoot = plainDirectory(path.dirname(path.dirname(plan.cliPath)), 'planned global CLI root');
+    const relativeToGlobal = path.relative(globalCliRoot, invoked);
+    assert.equal(relativeToGlobal.startsWith('..') || path.isAbsolute(relativeToGlobal), true, 'legacy update bridge must run from an external exact candidate, not the installed old CLI');
+    const candidateRoot = plainDirectory(path.dirname(path.dirname(invoked)), 'legacy update bridge candidate root');
+    const manifest = packageManifest(candidateRoot, '@aopslabs/aops');
+    const version = exactVersion(manifest.version, 'legacy update bridge candidate version');
+    assert.equal(version, plan.target.packages.cli, 'legacy update bridge candidate must match the plan target');
+    return { candidateRoot, version };
+}
+export function dispatchGlobalUpdate(options, run = defaultRunner) {
+    const plan = readGlobalUpdatePlan(options.plan);
+    assert.equal(options.confirm, plan.planId, 'global update confirmation does not match the exact plan');
+    const resultPath = path.join(plan.operationRoot, RESULT_FILE);
+    assert.equal(existsSync(resultPath), false, 'global_update_plan_already_terminal');
+    let executorStarted = false;
+    try {
+        const { receipt, receiptPath } = stageCandidateGlobalUpdateExecutor(plan, run);
+        executorStarted = true;
+        return parseJson(run(process.execPath, [
+            receipt.entrypoint,
+            'update',
+            'apply',
+            '--plan',
+            options.plan,
+            '--confirm',
+            options.confirm,
+            '--executor-receipt',
+            receiptPath,
+            '--json',
+        ]).trim(), 'global_update_candidate_result');
+    }
+    catch (error) {
+        if (!existsSync(resultPath)) {
+            writeTerminalUpdateResult(plan, {
+                schemaVersion: 1,
+                contract: RESULT_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',
+                rollbackPerformed: false,
+                error: safeUpdateError(error),
+                events: [],
+            });
+        }
+        throw new Error(`global update candidate executor failed; diagnostic record: ${resultPath}`, { cause: error });
+    }
+}
 export function installGlobalUpdateClosure(run, plan, records, topology) {
     const cli = packageRecordByName(records, '@aopslabs/aops');
     const server = packageRecordByName(records, '@aopslabs/aops-server');
@@ -528,9 +732,61 @@ export function validateLoopbackOrigin(value, label) {
     assert.equal(url.hash, '', `${label} must not include a fragment`);
     return url.origin;
 }
+function nestedCommunityDiagnostic(error) {
+    const pending = [error];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const candidate = pending.shift();
+        if (!candidate || visited.has(candidate))
+            continue;
+        visited.add(candidate);
+        if (typeof candidate === 'object') {
+            const record = candidate;
+            if (isCommunityDiagnosticV1(record.diagnostic))
+                return record.diagnostic;
+            if (record.cause)
+                pending.push(record.cause);
+            if (candidate instanceof AggregateError)
+                pending.push(...candidate.errors);
+        }
+    }
+    return undefined;
+}
+function safeUpdateError(error) {
+    const diagnostic = nestedCommunityDiagnostic(error);
+    if (diagnostic) {
+        const details = diagnostic.details;
+        return Object.fromEntries(Object.entries({
+            code: diagnostic.code,
+            causeCode: diagnostic.cause.code,
+            phase: diagnostic.phase,
+            operationId: typeof details.operationId === 'string' && UUID.test(details.operationId)
+                ? details.operationId
+                : undefined,
+            operation: typeof details.operation === 'string' ? details.operation : undefined,
+            journalPhase: typeof details.journalPhase === 'string' ? details.journalPhase : undefined,
+            journalStep: typeof details.journalStep === 'string' ? details.journalStep : undefined,
+        }).filter(([, value]) => value !== undefined));
+    }
+    const original = error instanceof Error ? error.message : String(error ?? 'global update failed');
+    const message = original
+        .split(/\r?\n/u, 1)[0]
+        .replace(/https?:\/\/\S+/giu, '[REDACTED_URL]')
+        .replace(/((?:password|passwd|secret|token|api[_-]?key|authorization)\s*[=:]\s*)\S+/giu, '$1[REDACTED]')
+        .replace(/(?:[A-Za-z]:\\|\/)\S+/gu, '[REDACTED_PATH]')
+        .slice(0, 500);
+    const code = /\b(?:aops|community|global_update)_[a-z0-9_]+\b/iu.exec(original)?.[0]?.toLowerCase()
+        ?? 'global_update_failed';
+    return { code, message };
+}
+function writeTerminalUpdateResult(plan, result) {
+    const resultPath = path.join(plan.operationRoot, RESULT_FILE);
+    writeFileSync(resultPath, `${JSON.stringify(result, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+}
 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');
+    assert.equal(existsSync(path.join(plan.operationRoot, RESULT_FILE)), false, 'global_update_plan_already_terminal');
     const current = inspectGlobalInstall(run);
     assert.deepEqual(current.packages, plan.prior.packages, 'global packages changed after update planning');
     assert.deepEqual(current.topology, plan.prior.topology, 'global package topology changed after update planning');
@@ -538,31 +794,39 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
     assertHealthyServices(serviceSnapshot(run, current.cliPath));
     const events = [];
     let applicationUpdateId = null;
+    let failedStage = 'stop-cockpit';
     try {
         stopService(run, current.cliPath, 'cockpit');
         events.push('stopped:cockpit');
+        failedStage = 'stop-server';
         stopService(run, current.cliPath, 'server');
         events.push('stopped:server');
+        failedStage = 'install-candidate';
         installGlobalUpdateClosure(run, plan, plan.candidates, plan.target.topology);
         events.push('installed:candidate');
+        failedStage = 'verify-candidate';
         const updated = inspectGlobalInstall(run);
         assert.deepEqual(updated.packages, plan.target.packages, 'installed candidate closure is not exact');
         assert.deepEqual(updated.topology, plan.target.topology, 'installed candidate topology is not canonical');
         if (plan.prior.packages.server === plan.target.packages.server) {
+            failedStage = 'start-unchanged-server';
             startService(run, updated.cliPath, 'server');
             events.push('started:server-unchanged');
         }
         else {
+            failedStage = 'update-server-application';
             applicationUpdateId = updateServerApplication(run, updated.cliPath, {
                 prior: plan.prior.packages.server,
                 target: plan.target.packages.server,
             });
             events.push('updated:server');
         }
+        failedStage = 'start-cockpit';
         startService(run, updated.cliPath, 'cockpit');
         events.push('started:cockpit');
+        failedStage = 'stable-health';
         const healthEvidence = await assertStableHealth(run, plan, execution);
-        return {
+        const result = {
             schemaVersion: 1,
             contract: RESULT_CONTRACT,
             status: 'updated',
@@ -573,9 +837,13 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
             healthEvidence,
             next: 'Exit and reopen the AOPS TUI to run the newly installed binary.',
         };
+        writeTerminalUpdateResult(plan, result);
+        return result;
     }
     catch (updateError) {
+        const updateStage = failedStage;
         events.push('rollback:started');
+        let rollbackError;
         try {
             stopService(run, plan.cliPath, 'cockpit', true);
             stopService(run, plan.cliPath, 'server', true);
@@ -611,10 +879,50 @@ export async function applyGlobalUpdate(options, run = defaultRunner, execution
                 events.push('rollback:services-recovered');
             }
             catch (serviceRecoveryError) {
+                writeTerminalUpdateResult(plan, {
+                    schemaVersion: 1,
+                    contract: RESULT_CONTRACT,
+                    status: 'recovery-required',
+                    planId: plan.planId,
+                    failedStage: updateStage,
+                    rollbackPerformed: true,
+                    rollback: { status: 'failed', error: safeUpdateError(rollbackError) },
+                    serviceRecovery: { status: 'failed', error: safeUpdateError(serviceRecoveryError) },
+                    error: safeUpdateError(updateError),
+                    events,
+                });
                 throw new AggregateError([updateError, rollbackError, serviceRecoveryError], `global update, automatic rollback, and service recovery failed; services may remain stopped; recovery artifacts remain at ${plan.operationRoot}`);
             }
+            writeTerminalUpdateResult(plan, {
+                schemaVersion: 1,
+                contract: RESULT_CONTRACT,
+                status: 'failed-restored',
+                planId: plan.planId,
+                failedStage: updateStage,
+                installed: plan.prior.packages,
+                rollbackPerformed: true,
+                rollback: {
+                    status: 'healthy',
+                    recovery: 'services-recovered',
+                    applicationRollbackError: safeUpdateError(rollbackError),
+                },
+                error: safeUpdateError(updateError),
+                events,
+            });
             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}`);
         }
+        writeTerminalUpdateResult(plan, {
+            schemaVersion: 1,
+            contract: RESULT_CONTRACT,
+            status: 'failed-restored',
+            planId: plan.planId,
+            failedStage: updateStage,
+            installed: plan.prior.packages,
+            rollbackPerformed: true,
+            rollback: { status: 'healthy' },
+            error: safeUpdateError(updateError),
+            events,
+        });
         throw new Error('global update failed; the prior exact packages were restored and are healthy', { cause: updateError });
     }
 }
@@ -639,7 +947,27 @@ export function makeGlobalUpdateCommand() {
         .description('Apply one exact prepared plan with automatic rollback and health verification')
         .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) => output(await applyGlobalUpdate(options), options.json === true));
+        .action(async (options) => {
+        if (typeof options.executorReceipt === 'string') {
+            const plan = readGlobalUpdatePlan(options.plan);
+            validateCandidateExecutorInvocation(plan, options.executorReceipt);
+            output(await applyGlobalUpdate(options), options.json === true);
+            return;
+        }
+        output(dispatchGlobalUpdate(options), options.json === true);
+    });
+    command
+        .command('bridge')
+        .description('Apply an old-CLI plan from an externally launched exact public candidate')
+        .requiredOption('--plan <path>', 'Exact update-plan.json path returned by the installed old CLI')
+        .requiredOption('--confirm <plan-id>', 'Exact sha256 plan id returned by prepare')
+        .option('--json', 'Output JSON')
+        .action((options) => {
+        const plan = readGlobalUpdatePlan(options.plan);
+        validateLegacyGlobalUpdateBridgeInvocation(plan);
+        output(dispatchGlobalUpdate(options), options.json === true);
+    });
     return command;
 }

package/dist/lib/agent-assets/native-fs.js

@@ -543,9 +543,9 @@ function defaultNativeRoot() {
     return moduleDirectory.endsWith(`${path.sep}dist`) ? bundled : compiledOrSource;
 }
 function injectedNativeManifestSha256() {
-    return typeof "6164b5c4d71eb6eed7d12b49faf10cd9f7c5324de4e893f50087e7089b5483b3" === 'undefined'
+    return typeof "bfaede623bfbea984d9711454380227e4f4e7a2bc816dee2b47002065209c741" === 'undefined'
         ? undefined
-        : "6164b5c4d71eb6eed7d12b49faf10cd9f7c5324de4e893f50087e7089b5483b3";
+        : "bfaede623bfbea984d9711454380227e4f4e7a2bc816dee2b47002065209c741";
 }
 function sha256(bytes) {
     return createHash('sha256').update(bytes).digest('hex');

package/dist/lib/community-cockpit-lifecycle.js

@@ -187,6 +187,24 @@ function statusBase(state, port, serverPort = state.server.publicPort) {
         port,
     };
 }
+function terminalObservation(record, observedAt, disappeared = false) {
+    const classification = disappeared
+        ? 'disappeared'
+        : record.signal
+            ? 'signal'
+            : record.status === 'exited' && record.exitCode === 0
+                ? 'clean-exit'
+                : record.exitCode !== undefined && record.exitCode !== null
+                    ? 'failed-exit'
+                    : 'launch-failure';
+    return {
+        classification,
+        lastSeenAt: record.updatedAt,
+        observedAt,
+        exitCode: record.exitCode ?? null,
+        signal: record.signal ?? null,
+    };
+}
 async function observeCockpit(params) {
     const record = params.processRecord;
     const identityPresent = existsSync(params.paths.identityPath);
@@ -203,6 +221,7 @@ async function observeCockpit(params) {
             hostAlive: false,
             health: 'not-checked',
             reason: identityPresent ? 'community_cockpit_identity_without_process_record' : null,
+            terminalObservation: null,
         };
     }
     const supervisorAlive = params.runtime.processExists(record.pid);
@@ -218,6 +237,7 @@ async function observeCockpit(params) {
                 supervisorAlive, hostAlive: record.hostPid ? params.runtime.processExists(record.hostPid) : false,
                 health: 'not-checked',
                 reason: error instanceof Error ? error.message : 'community_cockpit_identity_invalid',
+                terminalObservation: null,
             };
         }
     }
@@ -231,6 +251,7 @@ async function observeCockpit(params) {
                 runtimeState: 'stopped', recoverable: true, process: record, identity,
                 supervisorAlive: false, hostAlive: false, health: 'not-checked',
                 reason: identity ? 'community_cockpit_terminal_identity_stale' : null,
+                terminalObservation: terminalObservation(record, record.updatedAt),
             };
         }
         return {
@@ -238,6 +259,7 @@ async function observeCockpit(params) {
             runtimeState: 'identity-conflict', recoverable: false, process: record, identity,
             supervisorAlive, hostAlive, health: 'not-checked',
             reason: 'community_cockpit_terminal_record_with_live_or_unowned_process',
+            terminalObservation: null,
         };
     }
     if (!supervisorAlive && !hostAlive) {
@@ -246,6 +268,7 @@ async function observeCockpit(params) {
             runtimeState: 'crashed', recoverable: true, process: record, identity,
             supervisorAlive: false, hostAlive: false, health: 'not-checked',
             reason: 'community_cockpit_process_disappeared',
+            terminalObservation: terminalObservation(record, params.now().toISOString(), true),
         };
     }
     if (record.instanceName !== params.state.instanceName) {
@@ -254,6 +277,7 @@ async function observeCockpit(params) {
             runtimeState: 'identity-conflict', recoverable: false, process: record, identity,
             supervisorAlive, hostAlive, health: 'not-checked',
             reason: 'community_cockpit_process_instance_mismatch',
+            terminalObservation: null,
         };
     }
     if (!identity) {
@@ -262,6 +286,7 @@ async function observeCockpit(params) {
             runtimeState: 'identity-conflict', recoverable: false, process: record, identity: null,
             supervisorAlive, hostAlive, health: 'not-checked',
             reason: 'community_cockpit_live_process_without_matching_identity',
+            terminalObservation: null,
         };
     }
     if (!supervisorAlive && hostAlive) {
@@ -269,6 +294,7 @@ async function observeCockpit(params) {
             ...base,
             runtimeState: 'orphaned', recoverable: false, process: record, identity,
             supervisorAlive, hostAlive, health: 'not-checked', reason: 'community_cockpit_host_orphaned',
+            terminalObservation: null,
         };
     }
     if (supervisorAlive && !hostAlive) {
@@ -276,6 +302,7 @@ async function observeCockpit(params) {
             ...base,
             runtimeState: 'unhealthy', recoverable: false, process: record, identity,
             supervisorAlive, hostAlive, health: 'unhealthy', reason: 'community_cockpit_host_process_missing',
+            terminalObservation: null,
         };
     }
     const healthy = await params.runtime.health(`${base.origin}/_aops/cockpit-health`);
@@ -289,6 +316,7 @@ async function observeCockpit(params) {
         hostAlive,
         health: healthy ? 'healthy' : 'unhealthy',
         reason: healthy ? null : 'community_cockpit_health_failed',
+        terminalObservation: null,
     };
 }
 export async function inspectCommunityNativeCockpit(params = {}) {
@@ -302,6 +330,7 @@ export async function inspectCommunityNativeCockpit(params = {}) {
         paths,
         processRecord: readProcess(paths),
         runtime: params.runtime ?? communityNativeRuntime,
+        now: params.now ?? (() => new Date()),
     });
 }
 function cockpitEnvironment(params) {
@@ -409,8 +438,9 @@ async function startCommunityNativeCockpitUnlocked(params = {}) {
     const state = install.state;
     const paths = resolveCommunityCockpitPaths(params);
     const runtime = params.runtime ?? communityNativeRuntime;
+    const now = params.now ?? (() => new Date());
     const prior = readProcess(paths);
-    const observed = await observeCockpit({ state, paths, processRecord: prior, runtime });
+    const observed = await observeCockpit({ state, paths, processRecord: prior, runtime, now });
     if (observed.runtimeState === 'running') {
         return {
             action: 'already-running', state, paths, process: observed.process,
@@ -426,7 +456,6 @@ async function startCommunityNativeCockpitUnlocked(params = {}) {
         removeControlIfOwned(paths, prior.launchId);
     mkdirSync(paths.logRoot, { recursive: true, mode: 0o700 });
     assertPaths(paths);
-    const now = params.now ?? (() => new Date());
     const launchId = (params.createId ?? randomUUID)();
     const startedAt = now().toISOString();
     const handle = await runtime.spawnChild({
@@ -507,6 +536,7 @@ async function stopCommunityNativeCockpitUnlocked(params = {}) {
         paths,
         processRecord: readProcess(paths),
         runtime,
+        now,
     });
     if (observed.runtimeState === 'stopped' || observed.runtimeState === 'crashed') {
         return { status: 'already-stopped', state: install.state, process: observed.process };

package/native/manifest.json

@@ -42,7 +42,7 @@
       "capabilityClass": "windows-ntfs-crash-recoverable-v1",
       "qualification": {
         "relativePath": "qualifications/win32-x64.json",
-        "sha256": "08d7ccc099bcc86e1e4a8cea6ea0d7b50eee76f3a126d6020bf11b2b2edacb3c"
+        "sha256": "fdbdfc275dd6053bb6609a9d2aaad6728fee6f7777802ae08c3cb77e2b0d5d50"
       }
     }
   ]

package/native/qualifications/win32-x64.json

@@ -7,7 +7,7 @@
   "filesystem": "NTFS",
   "primitiveProfile": "windows-createfile-flush-movefileex-v1",
   "capabilityClass": "windows-ntfs-crash-recoverable-v1",
-  "evidenceSha256": "dd80c815d10feb9499911bc5eb9c3bf56964afe66faa894ebc9de478cb0e5311",
+  "evidenceSha256": "76057d52ed4b1f01ed24fbbaa1014b6be4d1db044bb2f5cdc0e6c77524f7a28c",
   "crashInjectionPoints": [
     "authority-history",
     "authority-current",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aopslabs/aops",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "type": "module",
   "description": "AOPS CLI and terminal setup application.",
   "aopsDockerServerVersion": "0.2.15",
@@ -44,6 +44,7 @@
     "test:package-identity": "node --test test/package-identity.test.mjs test/npm-tar-entry-mode.test.mjs",
     "test:tui-launcher": "node --test test/tui-launcher.test.mjs",
     "test:global-update": "node --test test/global-update.test.mjs test/cli-error-format.test.mjs",
+    "test:global-update-public-bridge": "node scripts/verify-global-update-public-bridge.mjs",
     "test:skill-discovery": "node --test test/skill-discovery.test.mjs",
     "test:target-auth": "node --test test/target-auth.test.mjs test/device-login.test.mjs",
     "test:target-transport": "node --test test/target-transport.test.mjs",