@platless/axom-cli 0.1.0

package/dist/workstation/systemMetrics.js

@@ -0,0 +1,271 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync, statfsSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export const STORAGE_TOPOLOGY_REFRESH_MS = 10 * 60 * 1000;
+function cpuTotals(cpus) {
+    return cpus.reduce((sum, cpu) => {
+        const times = Object.values(cpu.times).reduce((total, value) => total + value, 0);
+        return { idle: sum.idle + cpu.times.idle, total: sum.total + times };
+    }, { idle: 0, total: 0 });
+}
+function linuxAvailableMemory(readFile) {
+    try {
+        const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(readFile('/proc/meminfo', 'utf8'));
+        return match ? Number(match[1]) * 1024 : null;
+    }
+    catch {
+        return null;
+    }
+}
+function linuxMemoryPressure(readFile) {
+    try {
+        const line = /^some\s+(.+)$/m.exec(readFile('/proc/pressure/memory', 'utf8'))?.[1];
+        const avg10 = line ? /(?:^|\s)avg10=(\d+(?:\.\d+)?)(?:\s|$)/.exec(line)?.[1] : undefined;
+        if (avg10 === undefined)
+            return null;
+        return Math.max(0, Math.min(1, Number(avg10) / 100));
+    }
+    catch {
+        return null;
+    }
+}
+function stablePoolId(key) {
+    return createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+async function defaultIdentifyStorage(platform, cwd, device) {
+    try {
+        if (platform === 'darwin') {
+            const mounted = await execFileAsync('/bin/df', ['-P', cwd], {
+                timeout: 1_000,
+                env: { ...process.env, LC_ALL: 'C' },
+            });
+            const mountFields = mounted.stdout.trim().split('\n').at(-1)?.trim().split(/\s+/) ?? [];
+            const mountPoint = mountFields.slice(5).join(' ') || path.parse(cwd).root;
+            const { stdout } = await execFileAsync('/usr/sbin/diskutil', ['info', mountPoint], {
+                timeout: 1_000,
+                env: { ...process.env, LC_ALL: 'C' },
+            });
+            const container = /^\s*APFS Container Reference:\s*(\S+)\s*$/m.exec(stdout)?.[1];
+            const volume = /^\s*Volume Name:\s*(.+?)\s*$/m.exec(stdout)?.[1];
+            return container
+                ? { key: `apfs:${container}`, label: `APFS Container ${container}` }
+                : { key: `dev:${device}`, label: volume };
+        }
+        if (platform === 'linux') {
+            const { stdout } = await execFileAsync('findmnt', ['-n', '-P', '-o', 'FSTYPE,SOURCE,UUID,LABEL,TARGET', '--target', cwd], {
+                timeout: 2_000,
+                env: { ...process.env, LC_ALL: 'C' },
+            });
+            const fields = Object.fromEntries([...stdout.matchAll(/(\w+)="([^"]*)"/g)].map((match) => [match[1], match[2]]));
+            if (fields.FSTYPE === 'btrfs' && fields.UUID)
+                return { key: `btrfs:${fields.UUID}`, label: fields.SOURCE };
+            if (fields.FSTYPE === 'zfs' && fields.SOURCE) {
+                const pool = fields.SOURCE.split('/')[0];
+                return { key: `zfs:${pool}`, label: pool };
+            }
+            return { key: `dev:${device}`, label: fields.LABEL || fields.TARGET || fields.SOURCE };
+        }
+    }
+    catch {
+        // Resource-pool recognition is best-effort. Device identity below is the conservative fallback.
+    }
+    return { key: `dev:${device}` };
+}
+async function defaultDarwinAvailableMemory() {
+    try {
+        const { stdout } = await execFileAsync('/usr/bin/vm_stat', [], { timeout: 2_000 });
+        const pageSize = Number(/page size of (\d+) bytes/.exec(stdout)?.[1]);
+        if (!Number.isFinite(pageSize) || pageSize <= 0)
+            return null;
+        const pages = (label) => Number(new RegExp(`^${label}:\\s+(\\d+)\\.`, 'm').exec(stdout)?.[1] ?? 0);
+        return (pages('Pages free') + pages('Pages inactive') + pages('Pages speculative')) * pageSize;
+    }
+    catch {
+        return null;
+    }
+}
+async function defaultDarwinMemoryPressure() {
+    try {
+        const { stdout } = await execFileAsync('/usr/bin/memory_pressure', ['-Q'], { timeout: 2_000 });
+        const freePercent = Number(/System-wide memory free percentage:\s*(\d+(?:\.\d+)?)%/.exec(stdout)?.[1]);
+        if (!Number.isFinite(freePercent))
+            return null;
+        return Math.max(0, Math.min(1, 1 - freePercent / 100));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Low-overhead host sampler. CPU and memory are read only while a heartbeat is being built; storage
+ * topology is discovered out of band and capacity reads use the cached representative paths.
+ */
+export class SystemMetricsSampler {
+    workspaces;
+    deps;
+    previousCpu = null;
+    storage = [];
+    refreshTimer = null;
+    refreshInFlight = null;
+    darwinMemoryRefreshInFlight = null;
+    darwinMemoryAvailable = null;
+    darwinMemoryPressure = null;
+    constructor(workspaces, deps = {
+        platform: process.platform,
+        cpus: os.cpus,
+        loadavg: os.loadavg,
+        totalmem: os.totalmem,
+        freemem: os.freemem,
+        readFile: readFileSync,
+        statfs: statfsSync,
+        stat: statSync,
+        identifyStorage: (cwd, device) => defaultIdentifyStorage(process.platform, cwd, device),
+        darwinAvailableMemory: defaultDarwinAvailableMemory,
+        darwinMemoryPressure: defaultDarwinMemoryPressure,
+    }) {
+        this.workspaces = workspaces;
+        this.deps = deps;
+    }
+    async start() {
+        await Promise.all([this.refreshTopology(), this.refreshDarwinMemory()]);
+        this.refreshTimer = setInterval(() => this.refreshTopologyInBackground(), STORAGE_TOPOLOGY_REFRESH_MS);
+        this.refreshTimer.unref();
+    }
+    stop() {
+        if (this.refreshTimer)
+            clearInterval(this.refreshTimer);
+        this.refreshTimer = null;
+    }
+    snapshot() {
+        try {
+            this.refreshDarwinMemoryInBackground();
+            const cpus = this.deps.cpus();
+            const currentCpu = cpuTotals(cpus);
+            const previousCpu = this.previousCpu;
+            this.previousCpu = currentCpu;
+            const deltaTotal = previousCpu ? currentCpu.total - previousCpu.total : 0;
+            const deltaIdle = previousCpu ? currentCpu.idle - previousCpu.idle : 0;
+            const cpuUtilization = previousCpu && deltaTotal > 0
+                ? Math.max(0, Math.min(1, 1 - (deltaIdle / deltaTotal)))
+                : null;
+            const loadAverages = this.deps.platform !== 'win32' ? this.deps.loadavg() : null;
+            const cpuLoad1 = loadAverages ? Math.max(0, loadAverages[0]) : null;
+            const cpuLoad5 = loadAverages ? Math.max(0, loadAverages[1]) : null;
+            const cpuLoad15 = loadAverages ? Math.max(0, loadAverages[2]) : null;
+            const cpuLogicalCount = cpus.length > 0 ? cpus.length : null;
+            const memoryTotalBytes = this.deps.totalmem();
+            const memoryAvailableBytes = Math.max(0, Math.min(memoryTotalBytes, this.deps.platform === 'linux'
+                ? (linuxAvailableMemory(this.deps.readFile) ?? this.deps.freemem())
+                : (this.darwinMemoryAvailable ?? this.deps.freemem())));
+            const memoryPressure = this.deps.platform === 'linux'
+                ? linuxMemoryPressure(this.deps.readFile)
+                : (this.deps.platform === 'darwin' ? this.darwinMemoryPressure : null);
+            const pools = new Map();
+            for (const pool of this.storage) {
+                try {
+                    const stats = this.deps.statfs(pool.cwd);
+                    const totalBytes = Number(stats.blocks) * Number(stats.bsize);
+                    const availableBytes = Number(stats.bavail) * Number(stats.bsize);
+                    pools.set(pool.key, {
+                        id: stablePoolId(pool.key),
+                        label: pool.label,
+                        workspaces: pool.workspaces,
+                        totalBytes,
+                        availableBytes,
+                    });
+                }
+                catch {
+                    // A removed/unmounted workspace must not suppress CPU and memory metrics.
+                }
+            }
+            return {
+                cpuUtilization,
+                cpuLoad1,
+                cpuLoad5,
+                cpuLoad15,
+                cpuLogicalCount,
+                memoryPressure,
+                memoryTotalBytes,
+                memoryAvailableBytes,
+                storagePools: [...pools.values()],
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    refreshTopologyInBackground() {
+        if (this.refreshInFlight)
+            return;
+        const refresh = this.refreshTopology();
+        this.refreshInFlight = refresh;
+        void refresh.finally(() => {
+            if (this.refreshInFlight === refresh)
+                this.refreshInFlight = null;
+        });
+    }
+    refreshDarwinMemoryInBackground() {
+        if (this.deps.platform !== 'darwin' || this.darwinMemoryRefreshInFlight)
+            return;
+        const refresh = this.refreshDarwinMemory();
+        this.darwinMemoryRefreshInFlight = refresh;
+        void refresh.finally(() => {
+            if (this.darwinMemoryRefreshInFlight === refresh)
+                this.darwinMemoryRefreshInFlight = null;
+        });
+    }
+    async refreshDarwinMemory() {
+        if (this.deps.platform !== 'darwin')
+            return;
+        const [available, pressure] = await Promise.all([
+            this.deps.darwinAvailableMemory().catch(() => null),
+            this.deps.darwinMemoryPressure().catch(() => null),
+        ]);
+        this.darwinMemoryAvailable = available;
+        this.darwinMemoryPressure = pressure;
+    }
+    async refreshTopology() {
+        const candidates = this.workspaces.map(({ name, cwd }) => {
+            try {
+                this.deps.statfs(cwd);
+                const device = String(this.deps.stat(cwd).dev);
+                return { name, cwd, device };
+            }
+            catch {
+                return null;
+            }
+        }).filter((candidate) => candidate !== null);
+        const representatives = new Map();
+        candidates.forEach(({ cwd, device }) => {
+            if (!representatives.has(device))
+                representatives.set(device, { cwd, device });
+        });
+        const identities = new Map(await Promise.all([...representatives.values()].map(async ({ cwd, device }) => [
+            device,
+            await this.deps.identifyStorage(cwd, device).catch(() => null),
+        ])));
+        const identified = candidates.map(({ name, cwd, device }) => {
+            try {
+                const identity = identities.get(device);
+                const key = identity?.key ?? `dev:${device}`;
+                return { name, cwd, key, label: identity?.label || path.parse(cwd).root || cwd };
+            }
+            catch {
+                return null;
+            }
+        });
+        const grouped = new Map();
+        for (const entry of identified.filter((candidate) => candidate !== null)) {
+            const existing = grouped.get(entry.key);
+            if (existing)
+                existing.workspaces.push(entry.name);
+            else
+                grouped.set(entry.key, { cwd: entry.cwd, key: entry.key, label: entry.label, workspaces: [entry.name] });
+        }
+        this.storage = [...grouped.values()];
+    }
+}

package/dist/workstation/update/artifact.js

@@ -0,0 +1,61 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { createWriteStream, promises as fs } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+function expectedDigest(sha512) {
+    if (!/^[0-9a-f]{128}$/i.test(sha512))
+        throw new Error('Artifact SHA-512 digest is invalid');
+    return Buffer.from(sha512, 'hex');
+}
+function safeRelease(release, server) {
+    if (!Number.isSafeInteger(release.size) || release.size < 0)
+        throw new Error('Artifact size is invalid');
+    const configured = new URL(server);
+    if ((configured.protocol !== 'http:' && configured.protocol !== 'https:') || configured.username || configured.password) {
+        throw new Error('Configured server URL must be an HTTP(S) origin without credentials');
+    }
+    const url = new URL(release.url, configured);
+    // The release descriptor arrives over the authenticated management connection, but keeping the
+    // download on that exact origin prevents an injected relative/absolute URL from turning the
+    // client into a credentialed downloader. HTTP remains supported for private-network development
+    // only when the configured management server itself is HTTP; SHA-512 still verifies the bytes.
+    if (url.origin !== configured.origin || url.protocol !== configured.protocol) {
+        throw new Error('Artifact URL must use the configured server origin');
+    }
+    if (url.username || url.password)
+        throw new Error('Artifact URL must not contain credentials');
+    return url.toString();
+}
+/** Downloads to a private directory and returns only after the signed size and SHA-512 match. */
+export async function downloadVerified(release, deps) {
+    const url = safeRelease(release, deps.server);
+    const expected = expectedDigest(release.sha512);
+    const fetch = deps.fetch ?? globalThis.fetch;
+    const directory = await fs.mkdtemp(path.join(deps.temporaryDirectory ?? tmpdir(), 'axom-workstation-update-'));
+    const archive = path.join(directory, 'client.tgz');
+    try {
+        const response = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(60_000) });
+        if (!response.ok || !response.body)
+            throw new Error(`Artifact download failed with HTTP ${response.status}`);
+        const contentLength = response.headers.get('content-length');
+        if (contentLength !== null && (!/^\d+$/.test(contentLength) || Number(contentLength) !== release.size))
+            throw new Error('Artifact size mismatch');
+        const hash = createHash('sha512');
+        let size = 0;
+        const source = Readable.fromWeb(response.body);
+        source.on('data', (chunk) => { size += chunk.length; hash.update(chunk); });
+        await pipeline(source, createWriteStream(archive, { mode: 0o600, flags: 'wx' }));
+        if (size !== release.size)
+            throw new Error('Artifact size mismatch');
+        const actual = hash.digest();
+        if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+            throw new Error('Artifact SHA-512 mismatch');
+        return { path: archive, size, cleanup: async () => { await fs.rm(directory, { recursive: true, force: true }); } };
+    }
+    catch (error) {
+        await fs.rm(directory, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/workstation/update/coordinator.js

@@ -0,0 +1,240 @@
+import { downloadVerified } from './artifact.js';
+import { redactPaths } from './redact.js';
+import { isTerminalPhase } from './types.js';
+/**
+ * No historical workstation task-duration distribution exists yet. Thirty minutes deliberately
+ * gives interactive agent turns and long shell commands generous time to finish, while keeping a
+ * stalled task from blocking an update forever. Callers/tests can override this bound.
+ */
+export const DEFAULT_UPDATE_DRAIN_TIMEOUT_MS = 30 * 60_000;
+function failure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // Individual components already redact their own errors. This is a final limit for unexpected
+    // errors before they become a heartbeat field.
+    return redactPaths(message.replace(/https?:\/\/\S+/gi, '[redacted-url]').replace(/(?:token|password|secret)=\S+/gi, '$1=[redacted]')).slice(0, 512);
+}
+/** Serializes server update commands and persists every externally visible phase transition. */
+export class UpdateCoordinator {
+    options;
+    status = { phase: 'SUCCEEDED' };
+    initialized = null;
+    active = null;
+    constructor(options) {
+        this.options = options;
+    }
+    snapshot() { return { ...this.status }; }
+    async snapshotAsync() { await this.ensureInitialized(); return this.snapshot(); }
+    async handle(command) {
+        await this.ensureInitialized();
+        // Server command IDs are idempotency keys, including after a completed/failed attempt and a
+        // process restart. Re-running a terminal command could silently downgrade a repaired client.
+        if (this.status.commandId === command.commandId)
+            return this.snapshot();
+        if (this.active) {
+            return { phase: 'UPDATE_IN_PROGRESS', commandId: this.status.commandId, version: this.status.version, force: this.status.force };
+        }
+        if (!isTerminalPhase(this.status.phase)) {
+            return { phase: 'UPDATE_IN_PROGRESS', commandId: this.status.commandId, version: this.status.version, force: this.status.force };
+        }
+        // Asked before anything starts, because every phase of an update is persisted: a state
+        // directory that cannot be written turns the first transition into a raw `ENOENT ... open`
+        // that names nothing an operator can act on. This is the workstation saying which directory
+        // has gone instead. See UpdateStateStore.assertWritable for why it is a real write.
+        try {
+            await this.options.state.assertWritable();
+        }
+        catch (error) {
+            const status = { ...this.base(command, 'FAILED'), error: failure(error) };
+            this.status = status;
+            // Persisting is the very thing that just proved impossible. Try anyway -- a directory that
+            // recovered between the probe and here should keep its history -- and never let that attempt
+            // replace the error that explains the failure.
+            await this.options.state.save(status).catch(() => undefined);
+            try {
+                this.options.onPhase?.(status);
+            }
+            catch { /* a broken logger must not fail this */ }
+            return this.snapshot();
+        }
+        this.active = this.execute(command);
+        try {
+            return await this.active;
+        }
+        finally {
+            this.active = null;
+        }
+    }
+    /**
+     * `management_ready` has already passed the encrypted proof-of-key exchange. Only that path can
+     * satisfy a restart, and it must describe the exact artifact that this command installed.
+     */
+    async managementReady(release, generation) {
+        await this.ensureInitialized();
+        const readiness = this.options.readiness;
+        if (!release)
+            return;
+        // Caching must not hold the authenticated channel hostage. The cache itself accepts only its
+        // running version and independently re-verifies the resulting archive digest.
+        if (release.version === this.options.releaseCache?.clientVersion) {
+            void this.options.releaseCache.promoteAuthenticatedRelease(release).catch(() => undefined);
+        }
+        if (!readiness)
+            return;
+        if (this.status.phase !== 'RESTARTING')
+            return;
+        if (!this.status.commandId || this.status.version !== readiness.clientVersion)
+            return;
+        if (release.version !== this.status.version || release.sha512 !== this.status.releaseSha512)
+            return;
+        await readiness.write({ commandId: this.status.commandId, version: this.status.version, generation, readyAt: new Date().toISOString() });
+        // The authenticated Ready above proves the replacement daemon is running the exact release.
+        // Persist the terminal result as well as the watchdog marker: after a server restart there is
+        // no in-memory operation left to infer completion from a later RESTARTING heartbeat.
+        await this.transition({ ...this.status, phase: 'SUCCEEDED' });
+    }
+    async ensureInitialized() {
+        if (!this.initialized)
+            this.initialized = this.options.state.load().then(async (saved) => {
+                if (!saved)
+                    return;
+                const reconcile = this.options.reconcileRestartOnBoot;
+                if (reconcile && saved.phase === 'RESTARTING' && saved.version !== reconcile.runningVersion) {
+                    // A container came back on the image's version: the npm layer that held the update is
+                    // gone. Surface that as a terminal failure instead of heartbeating RESTARTING forever —
+                    // there is no rollback and no watchdog to resolve it any other way in this lifecycle.
+                    this.status = { ...saved, phase: 'FAILED', error: `container recreated, image version ${reconcile.runningVersion} restored` };
+                    await this.options.state.save(this.status);
+                    // Reported like any other transition: this *is* the container lifecycle's only way for an
+                    // interrupted update to resolve, so it is exactly what an operator reading `docker logs`
+                    // after a recreation needs to see.
+                    try {
+                        this.options.onPhase?.(this.status);
+                    }
+                    catch { /* a broken logger must not fail a boot */ }
+                    return;
+                }
+                this.status = saved;
+            });
+        await this.initialized;
+    }
+    async transition(status) {
+        this.status = status;
+        await this.options.state.save(status);
+        // After the persist, and swallowed: a logger is a witness to the update, never a participant
+        // that can fail one.
+        try {
+            this.options.onPhase?.(status);
+        }
+        catch { /* a broken logger must not fail an update */ }
+        return this.snapshot();
+    }
+    base(command, phase) {
+        return { phase, commandId: command.commandId, version: command.release.version, releaseSha512: command.release.sha512, force: command.force };
+    }
+    async execute(command) {
+        let artifact = null;
+        let rollback = null;
+        let drainCancellation = null;
+        try {
+            await this.transition(this.base(command, 'REQUESTED'));
+            let drained = null;
+            if (command.force) {
+                await this.options.tasks.stopAll();
+            }
+            else {
+                // Close admission before the persisted transition can yield: no command may enter in the
+                // gap between announcing DRAINING and establishing the barrier it promises.
+                this.options.tasks.accepting = false;
+                await this.transition(this.base(command, 'DRAINING'));
+                drainCancellation = new AbortController();
+                drained = this.options.tasks.waitForIdle(this.options.drainTimeoutMs ?? DEFAULT_UPDATE_DRAIN_TIMEOUT_MS, drainCancellation.signal);
+            }
+            await this.transition(this.base(command, 'DOWNLOADING'));
+            if (this.options.downloader)
+                artifact = await this.options.downloader(command.release);
+            else {
+                if (!this.options.artifact)
+                    throw new Error('Update artifact download requires the configured server URL');
+                artifact = await downloadVerified(command.release, this.options.artifact);
+            }
+            await this.transition(this.base(command, 'VERIFYING'));
+            if (drained && !await drained) {
+                this.options.tasks.accepting = true;
+                return this.transition({ ...this.base(command, 'BUSY'), ...this.options.tasks.snapshot() });
+            }
+            // This is intentionally after a verified new archive exists but before npm mutates the
+            // installed package. A missing/invalid last-known-good archive must leave the client alone.
+            rollback = await this.options.rollback?.prepare(command) ?? null;
+            await this.transition(this.base(command, 'INSTALLING'));
+            try {
+                await this.options.installer.install(artifact.path);
+            }
+            catch (installError) {
+                try {
+                    await rollback?.restore?.();
+                }
+                catch (restoreError) {
+                    throw new Error(`npm install failed and restore failed: ${failure(installError)}; ${failure(restoreError)}`);
+                }
+                throw installError;
+            }
+            await rollback?.arm();
+            // RESTARTING is persisted *before* provisioning, not after, because provisioning is what
+            // bounces the service: on macOS it boots this very daemon out and kickstarts its
+            // replacement, and that replacement reads this file. Persisting it afterwards would leave
+            // the successor loading INSTALLING and heartbeating a non-terminal phase forever, which the
+            // server never resolves and which blocks every later update command.
+            const restarting = await this.transition(this.base(command, 'RESTARTING'));
+            // Deliberately not inside the try/catch that restores the package: a service definition we
+            // failed to rewrite does not make the installed package wrong, and rolling npm back over a
+            // provisioning failure would be a much bigger hammer than the problem.
+            //
+            // It does, however, fail the update. `provisionService` boots the old job out before writing
+            // the replacement, so "provisioning failed" can mean the service is gone from the service
+            // manager entirely — a strictly worse end state than a rolled-back update, and the one that
+            // was being reported as SUCCEEDED. The restart is skipped for the same reason: exiting is
+            // only a hand-off when something is left to restart us, and we no longer know that.
+            try {
+                await this.options.provisionService?.();
+            }
+            catch (provisionError) {
+                this.options.onProvisionFailure?.(provisionError);
+                if (!command.force)
+                    this.options.tasks.accepting = true;
+                return this.transition({ ...this.base(command, 'FAILED'), error: failure(provisionError) });
+            }
+            if (!this.options.restart) {
+                // Nothing to hand off to (`restartsOnHandoff: false`, i.e. the `'none'` lifecycle): this
+                // process keeps running the old code until a person restarts it, which is exactly what
+                // that lifecycle promises — "install, then print a hint". So the update ends *here*, and
+                // everything RESTARTING made moot by exiting has to be undone instead:
+                //
+                //   * admission, closed before DRAINING, would otherwise stay closed for the life of the
+                //     process and refuse every later shell/agent request with "Workstation is not
+                //     accepting new work" (taskRegistry.ts). Not for a forced update, whose `stopAll()`
+                //     closed it deliberately and permanently — same rule as the BUSY and FAILED paths.
+                //   * RESTARTING is not terminal, so leaving it persisted would answer every future
+                //     update command with UPDATE_IN_PROGRESS — and `'none'` does no boot reconciliation,
+                //     so a manual restart would not clear it either.
+                //
+                // SUCCEEDED is the honest phase: the install did succeed. What has not happened is the
+                // restart, which the caller is the one positioned to say — `axom update` prints it, and
+                // the server-driven case sees the new version only after the operator restarts.
+                if (!command.force)
+                    this.options.tasks.accepting = true;
+                return this.transition(this.base(command, 'SUCCEEDED'));
+            }
+            await this.options.restart();
+            return restarting;
+        }
+        catch (error) {
+            if (!command.force)
+                this.options.tasks.accepting = true;
+            return this.transition({ ...this.base(command, 'FAILED'), error: failure(error) });
+        }
+        finally {
+            drainCancellation?.abort();
+            await artifact?.cleanup().catch(() => undefined);
+        }
+    }
+}

package/dist/workstation/update/npmInstaller.js

@@ -0,0 +1,91 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { redactPaths, redactSecrets } from './redact.js';
+const STDERR_LIMIT = 4096;
+function absolute(value, field) {
+    if (!value.startsWith('/') || /[\u0000-\u001f\u007f]/.test(value))
+        throw new Error(`${field} must be an absolute safe path`);
+}
+/** Removes data that is neither useful nor safe to publish as an update status. */
+export function sanitizeNpmError(value) {
+    return redactPaths(redactSecrets(value)).slice(0, STDERR_LIMIT).trim();
+}
+/** Installs only a previously verified local archive. No command ever reaches a shell. */
+export class NpmInstaller {
+    options;
+    spawn;
+    constructor(options) {
+        this.options = options;
+        absolute(options.npmPath, 'npmPath');
+        absolute(options.npmPrefix, 'npmPrefix');
+        this.spawn = options.spawn ?? nodeSpawn;
+    }
+    async install(archive) {
+        absolute(archive, 'archive');
+        // No `--prefix`: npm installs into its own configured global prefix, which is what puts `axom`
+        // on the user's PATH. Forcing a private prefix put the binary somewhere nothing looks, so every
+        // machine needed a hand-made symlink that nothing in this package created or documented.
+        // `npmPrefix` survives for the writability pre-check, the service definition, and rollback —
+        // it is derived from where this package actually sits, so it still names npm's real prefix.
+        const args = ['install', '--global', archive, '--ignore-scripts', '--no-audit', '--no-fund'];
+        await new Promise((resolve, reject) => {
+            let stderr = '';
+            let child;
+            try {
+                child = this.spawn(this.options.npmPath, args, { shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+            }
+            catch (error) {
+                reject(new Error(`npm install could not start: ${sanitizeNpmError(error instanceof Error ? error.message : String(error))}`));
+                return;
+            }
+            child.stderr?.on('data', (chunk) => { if (stderr.length < STDERR_LIMIT)
+                stderr += chunk.toString().slice(0, STDERR_LIMIT - stderr.length); });
+            child.once('error', (error) => reject(new Error(`npm install could not start: ${sanitizeNpmError(error.message)}`)));
+            child.once('close', (code, signal) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`npm install failed: ${sanitizeNpmError(stderr) || `exit ${code ?? signal ?? 'unknown'}`}`));
+            });
+        });
+    }
+    /** Packs the installed package locally; `--json` gives npm's own name/version validation input. */
+    async pack(packageRoot, destination) {
+        absolute(packageRoot, 'packageRoot');
+        absolute(destination, 'destination');
+        const args = ['pack', packageRoot, '--pack-destination', destination, '--json'];
+        return new Promise((resolve, reject) => {
+            let stdout = '';
+            let stderr = '';
+            let child;
+            try {
+                child = this.spawn(this.options.npmPath, args, { shell: false, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+            }
+            catch (error) {
+                reject(new Error(`npm pack could not start: ${sanitizeNpmError(error instanceof Error ? error.message : String(error))}`));
+                return;
+            }
+            child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
+            child.stderr?.on('data', (chunk) => { if (stderr.length < STDERR_LIMIT)
+                stderr += chunk.toString().slice(0, STDERR_LIMIT - stderr.length); });
+            child.once('error', (error) => reject(new Error(`npm pack could not start: ${sanitizeNpmError(error.message)}`)));
+            child.once('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`npm pack failed: ${sanitizeNpmError(stderr) || `exit ${code ?? 'unknown'}`}`));
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(stdout);
+                    const entry = Array.isArray(parsed) && parsed.length === 1 ? parsed[0] : null;
+                    if (!entry || typeof entry.filename !== 'string' || typeof entry.name !== 'string' || typeof entry.version !== 'string')
+                        throw new Error('npm pack returned invalid metadata');
+                    const archive = `${destination}/${entry.filename}`;
+                    absolute(archive, 'packed archive');
+                    resolve({ path: archive, name: entry.name, version: entry.version });
+                }
+                catch (error) {
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        });
+    }
+}