@platless/axom-cli 0.1.0

package/dist/workstation/update/redact.js

@@ -0,0 +1,36 @@
+/**
+ * Absolute paths, as they appear inside an error message.
+ *
+ * Two things the previous pattern got wrong. It matched every non-space, non-colon character, so
+ * `open '/a/b/c'` lost its closing quote along with the path and the operator saw a message that
+ * ended mid-quote. And it had no left boundary, so the `/b` inside a relative `a/b` was redacted as
+ * though it were absolute -- the lookbehind requires the slash to follow something that cannot be
+ * part of a path segment.
+ */
+const ABSOLUTE_PATH = /(?<![\w.~-])(?:\/[^\s:'"()[\]]+)+\/?/g;
+/**
+ * Replaces the directories of an absolute path with `[path]`, keeping the final segment.
+ *
+ * Redaction is here so a workstation's status field cannot publish the daemon's filesystem layout
+ * to the server. Replacing the *whole* path also removes the one thing that makes such a message
+ * actionable: on 2026-09-06 a container with a deleted `/data/ws` mount reported
+ * `ENOENT: no such file or directory, open '[path]` for every failed action, which named neither
+ * the file nor anything that pointed at the mount. `[path]/.update-state.json...tmp` would have.
+ *
+ * The file name is the diagnostic; the directories are the layout. This keeps the first and drops
+ * the second.
+ */
+export function redactPaths(value) {
+    return value.replace(ABSOLUTE_PATH, (match) => {
+        if (match.endsWith('/'))
+            return '[path]/';
+        const name = match.slice(match.lastIndexOf('/') + 1);
+        return name ? `[path]/${name}` : '[path]';
+    });
+}
+/** Credentials that must never reach a status field, whatever else a message carries. */
+export function redactSecrets(value) {
+    return value
+        .replace(/https?:\/\/[^\s/@]+:[^\s/@]+@[^\s/]+[^\s]*/gi, '[redacted-url]')
+        .replace(/(?:token|password|secret)=\S+/gi, '$1=[redacted]');
+}

package/dist/workstation/update/runUpdate.js

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process';
+import { closeSync, openSync } from 'node:fs';
+import { downloadVerified } from './artifact.js';
+import { UpdateCoordinator } from './coordinator.js';
+import { NpmInstaller } from './npmInstaller.js';
+import { UpdateStateStore } from './stateStore.js';
+import { TaskRegistry } from './taskRegistry.js';
+import { LastKnownGoodCache, SERVICE_UNREGISTERED_REMEDIATION, writeReadinessMarker } from './watchdog.js';
+import { updateServiceContext } from '../config.js';
+import { CLIENT_VERSION } from '../version.js';
+/**
+ * The argv `provisionService` spawns the installed CLI with. Exported so a test can spawn the
+ * same command out-of-process and prove it resolves against the unified CLI's actual command
+ * surface, instead of only ever seeing it through a mock.
+ */
+export const PROVISION_SERVICE_ARGV = ['workstation', 'install'];
+/**
+ * How long the update waits for the provisioning child to say whether the OS service is back.
+ *
+ * The one hard bound: it must exceed the child's own worst case — `axom workstation install`
+ * retries a still-transitioning launchd job for the whole of installer.ts's
+ * `LAUNCHD_TRANSITION_BACKOFF_MS` schedule (23.75s) plus the `bootout`/`print`/`kickstart`
+ * subprocesses around it. A shorter window records "did not confirm" — and rolls the machine
+ * back — while the child is seconds from succeeding, which is exactly how two real machines were
+ * stranded: this window was 15s, the child's budget 3.25s, and both numbers sat *below* launchd's
+ * 20s SIGTERM-to-SIGKILL grace that the transition actually takes.
+ *
+ * That grace is no longer an upper bound here, and being SIGKILLed mid-wait is the *designed*
+ * outcome of the slow-success path, not a failure: on macOS the child's `bootout` SIGTERMs this
+ * very process, launchd keeps the job in transition while we linger observing the child, and
+ * kills us at 20s — which is the moment the transition ends and the child's next attempt can
+ * bootstrap the replacement. Dying here records nothing, deliberately: the state is already the
+ * durably persisted RESTARTING, the new daemon's authenticated Ready proves success, and the
+ * armed watchdog's 120s readiness deadline owns the failure side. What this window still catches
+ * is the child failing outright (fast non-zero exit — recorded within seconds) or hanging without
+ * ever having booted us out.
+ */
+export const PROVISION_CONFIRM_TIMEOUT_MS = 30_000;
+/**
+ * Appended to every provisioning failure, so the one line a person reads in `daemon.log` — and the
+ * `error` the server shows on the failed update — names the command that repairs the machine.
+ *
+ * This is not decoration. When provisioning fails after `install` has already booted the old job
+ * out, the end state is *worse* than a rolled-back update: the service is gone from launchd
+ * entirely, so nothing will ever restart the workstation on its own.
+ *
+ * The wording lives in `watchdog.ts` because the rollback path reaches the same end state from the
+ * other side and has to say the same thing. Kept as an alias rather than folded into its call sites
+ * so this file's own tests and readers keep the name that describes *when* it is used.
+ */
+export const PROVISION_REMEDIATION = SERVICE_UNREGISTERED_REMEDIATION;
+/**
+ * Resolves only when the provisioning child has *proved* it re-provisioned the service, rejects
+ * otherwise — including when it simply has not answered in time.
+ *
+ * The child stays `detached` and is deliberately not killed on timeout: it may well be seconds away
+ * from succeeding, and killing it mid-`bootstrap` is how a machine loses its service definition.
+ * What is bounded is only how long the *update* is willing to be held open by it. An unconfirmed
+ * outcome is reported as a failure rather than as success: on the real machines this fix comes
+ * from, "we never looked" was rendered as SUCCEEDED while the workstation was offline and
+ * unregistered, and a false alarm costs an idempotent `axom workstation install` while a false
+ * SUCCEEDED costs a machine nobody knows is broken.
+ */
+export function awaitProvisionOutcome(child, timeoutMs = PROVISION_CONFIRM_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.removeListener('exit', onExit);
+            child.removeListener('error', onError);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const onExit = (code, signal) => {
+            if (code === 0)
+                return settle();
+            settle(new Error(`service re-provisioning ${signal ? `was killed by ${signal}` : `exited with code ${code ?? 'unknown'}`}`
+                + ` (see daemon.log for what \`axom ${PROVISION_SERVICE_ARGV.join(' ')}\` reported). ${PROVISION_REMEDIATION}`));
+        };
+        const onError = (error) => {
+            settle(new Error(`service re-provisioning could not be started: ${error.message}. ${PROVISION_REMEDIATION}`));
+        };
+        const timer = setTimeout(() => {
+            // Stop holding this process's event loop open for a child we are no longer waiting on.
+            child.unref();
+            settle(new Error(`service re-provisioning did not confirm within ${timeoutMs}ms. ${PROVISION_REMEDIATION}`));
+        }, timeoutMs);
+        child.once('exit', onExit);
+        child.once('error', onError);
+    });
+}
+/**
+ * What each `serviceLifecycle` permits, computed once so `createUpdateCoordinator` has a single
+ * place deciding it and a test can pin the whole table without reaching into
+ * `UpdateCoordinator`'s private options.
+ */
+export function lifecyclePolicy(lifecycle) {
+    return {
+        provisions: lifecycle === 'provision-and-arm',
+        rollsBack: lifecycle === 'provision-and-arm',
+        cachesRelease: lifecycle === 'provision-and-arm',
+        reconcilesOnBoot: lifecycle === 'container',
+        restartsOnHandoff: lifecycle !== 'none',
+        logsPhases: lifecycle === 'container',
+    };
+}
+/**
+ * Assembles the one `UpdateCoordinator` every caller runs — the management-channel handler
+ * (daemon.ts), the bare `axom workstation` foreground daemon, and the manual `axom update`
+ * command alike — same npm installer, same last-known-good rollback cache, same on-disk state
+ * file. There is deliberately no second implementation of this assembly.
+ *
+ * Callers differ only in `serviceLifecycle`: `'provision-and-arm'` for the OS service manager's own
+ * supervised process, `'container'` for a detected Docker `ENTRYPOINT`, and `'none'` for everything
+ * else — which includes both the one-shot manual `axom update` command and a long-lived foreground
+ * daemon that is neither service-supervised nor a container (see the field's doc for why `'none'`
+ * does no provisioning, no rollback and no boot reconciliation).
+ */
+export function createUpdateCoordinator(deps) {
+    const policy = lifecyclePolicy(deps.serviceLifecycle);
+    const updateContext = updateServiceContext(deps.dir);
+    const npm = new NpmInstaller(updateContext);
+    // This cache also resumes the restart handshake after service supervision starts a new daemon.
+    const releaseCache = new LastKnownGoodCache({
+        ...updateContext, runningVersion: CLIENT_VERSION, pack: (root, destination) => npm.pack(root, destination),
+        download: (release) => downloadVerified(release, { server: deps.server }),
+        // The same `cli.js` `provisionService` below spawns. It is staged into the watchdog's plan so a
+        // rollback can re-provision with it; the watchdog runs from a copy outside the package and has
+        // no way to find it otherwise.
+        cliPath: deps.cliPath,
+    });
+    return new UpdateCoordinator({
+        tasks: deps.tasks ?? new TaskRegistry(), installer: npm, state: new UpdateStateStore(deps.dir),
+        drainTimeoutMs: deps.drainTimeoutMs,
+        // Without an artifact source the coordinator cannot fetch the release at all: every update and
+        // reinstall fails at DOWNLOADING with "requires the configured server URL". The artifact is
+        // served by the same authenticated server this call is already connected to — which is why
+        // the rollback cache constructed just above could download while the update itself could not.
+        artifact: { server: deps.server },
+        // Only armed for the caller that declared 'provision-and-arm' — see UpdateCoordinatorDeps.
+        rollback: policy.rollsBack ? releaseCache : undefined,
+        releaseCache: policy.cachesRelease ? releaseCache : undefined,
+        readiness: { clientVersion: CLIENT_VERSION, write: async (record) => { await writeReadinessMarker(deps.dir, record); } },
+        /**
+         * Re-writes the service definition from the package that was just installed.
+         *
+         * Has to be a detached child rather than an in-process call: `install()` boots the service out
+         * of launchd's domain before bootstrapping the replacement, and this process *is* that
+         * service — an in-process call would die at the bootout and never reach the bootstrap, leaving
+         * the daemon down. The child outlives us on purpose, and re-running the same hardened
+         * `workstation install` path a person would run keeps one implementation of the lifecycle
+         * races.
+         *
+         * On macOS this is also the only thing that makes a changed definition take effect at all: a
+         * bootstrapped job keeps the environment it was loaded with, so writing the plist and exiting
+         * would restart the daemon with the *old* environment until the next login.
+         *
+         * stdio is redirected to the same `daemon.log` the service definition itself points
+         * `StandardOutPath`/`StandardErrorPath` at — not discarded — so an `unknown command` or any
+         * other failure from this child leaves a trace instead of vanishing silently.
+         *
+         * Detached, but **awaited** for a bounded window (see {@link PROVISION_CONFIRM_TIMEOUT_MS}).
+         * The original `spawn(); unref(); resolve()` made provisioning failure structurally
+         * unobservable — the promise could not reject, so `onProvisionFailure` was dead code and a
+         * machine whose service had just been booted out and never bootstrapped reported SUCCEEDED.
+         * Not waiting also *caused* that report: this process exited immediately afterwards, launchd's
+         * KeepAlive started a replacement daemon, whose heartbeat of the persisted RESTARTING is what
+         * the server promotes to SUCCEEDED — and only then did the child boot that replacement out.
+         * Waiting first removes the race as well as the blindness.
+         *
+         * Only wired up for the caller that declared 'provision-and-arm'. On the manual path a service
+         * definition that needs to change is left for the next server-driven update to rewrite.
+         */
+        provisionService: policy.provisions ? async () => {
+            const log = openSync(`${deps.dir}/daemon.log`, 'a');
+            let child;
+            try {
+                child = spawn(process.execPath, [deps.cliPath, ...PROVISION_SERVICE_ARGV], {
+                    detached: true,
+                    stdio: ['ignore', log, log],
+                });
+            }
+            finally {
+                closeSync(log);
+            }
+            await awaitProvisionOutcome(child);
+        } : undefined,
+        /**
+         * Now genuinely reachable (it never was before), and the only place this message reaches a
+         * person on the machine: `console.error` lands in the same `daemon.log` the plist points at.
+         * The coordinator additionally fails the update, which is how the server gets to see it.
+         */
+        onProvisionFailure: policy.provisions ? (error) => {
+            console.error(`service re-provisioning failed: ${error instanceof Error ? error.message : String(error)}`);
+        } : undefined,
+        // Gated here, alongside the other three policy fields, rather than at daemon.ts's call site:
+        // `runDaemon` passes `() => process.exit(0)` for every lifecycle, and a caller that has not
+        // thought about which mode it is in must not be able to exit a daemon nothing will restart.
+        restart: policy.restartsOnHandoff ? deps.restart : undefined,
+        // Only the container lifecycle needs this — see reconcilesOnBoot's doc above and
+        // UpdateCoordinatorOptions.reconcileRestartOnBoot in coordinator.ts.
+        reconcileRestartOnBoot: policy.reconcilesOnBoot ? { runningVersion: CLIENT_VERSION } : undefined,
+        // See logsPhases' doc: in a container this is the only trace an update leaves outside the
+        // volume. `version` is on every phase but the initial SUCCEEDED, and `error` only on FAILED.
+        onPhase: policy.logsPhases ? (status) => {
+            const detail = [status.version && `version ${status.version}`, status.error].filter(Boolean).join(': ');
+            console.log(`[update] ${status.phase}${detail ? ` (${detail})` : ''}`);
+        } : undefined,
+    });
+}

package/dist/workstation/update/stateStore.js

@@ -0,0 +1,87 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+const STATE_FILE = 'update-state.json';
+const PHASES = new Set([
+    'REQUESTED', 'DRAINING', 'BUSY', 'DOWNLOADING', 'VERIFYING', 'INSTALLING', 'RESTARTING',
+    'SUCCEEDED', 'FAILED', 'ROLLED_BACK', 'UPDATE_IN_PROGRESS',
+]);
+function isUpdateStatus(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const status = value;
+    if (typeof status.phase !== 'string' || !PHASES.has(status.phase))
+        return false;
+    for (const field of ['commandId', 'version', 'releaseSha512', 'error'])
+        if (status[field] !== undefined && typeof status[field] !== 'string')
+            return false;
+    for (const field of ['force'])
+        if (status[field] !== undefined && typeof status[field] !== 'boolean')
+            return false;
+    for (const field of ['activeShellTasks', 'activeAgentTasks'])
+        if (status[field] !== undefined && (!Number.isSafeInteger(status[field]) || status[field] < 0))
+            return false;
+    return true;
+}
+/** Persists only non-secret update progress. Atomic rename makes a crash recoverable. */
+export class UpdateStateStore {
+    directory;
+    path;
+    constructor(directory) {
+        this.directory = directory;
+        this.path = path.join(directory, STATE_FILE);
+    }
+    async load() {
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.path, 'utf8'));
+            return isUpdateStatus(parsed) ? parsed : null;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            // A partial/corrupt state must not make the daemon unavailable. The former command can be
+            // retried; a later watchdog task owns recovery for an already-installed package.
+            return null;
+        }
+    }
+    /**
+     * Proves the state directory can actually be written, and leaves nothing behind.
+     *
+     * A real create-and-delete, not `stat` or `access`: a directory can resolve and still refuse
+     * `open`. That is precisely what a bind-mount source deleted on the host does -- the container
+     * keeps resolving the mount to an inode with `nlink=0`, so `ls` succeeds, `stat` succeeds, and
+     * every write returns ENOENT. On 2026-09-06 a workstation in that state reported ONLINE with all
+     * three channels connected while it had not persisted a byte for hours.
+     *
+     * Throws with the directory named, because the errno alone ("ENOENT ... open") tells an operator
+     * nothing about which directory has gone.
+     */
+    async assertWritable() {
+        const probe = path.join(this.directory, `.writable-probe.${process.pid}.${Date.now()}`);
+        try {
+            await fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+            await fs.writeFile(probe, '', { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        }
+        catch (error) {
+            const code = error.code ?? 'unknown error';
+            throw new Error(`workstation state directory is not writable: ${this.directory} (${code})`);
+        }
+        finally {
+            await fs.rm(probe, { force: true }).catch(() => undefined);
+        }
+    }
+    async save(status) {
+        await fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const temporary = path.join(this.directory, `.${STATE_FILE}.${process.pid}.${Date.now()}.tmp`);
+        try {
+            await fs.writeFile(temporary, `${JSON.stringify(status)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+            await fs.chmod(temporary, 0o600);
+            await fs.rename(temporary, this.path);
+            // Existing state files might have been created by an older client under a permissive umask.
+            await fs.chmod(this.path, 0o600);
+        }
+        catch (error) {
+            await fs.rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+}

package/dist/workstation/update/taskRegistry.js

@@ -0,0 +1,142 @@
+/**
+ * Owns the process-lifetime update gate. A graceful update may reopen it after a BUSY timeout; a
+ * forced update closes it permanently because this daemon is about to be replaced.
+ */
+export class TaskRegistry {
+    /** Every running shell's abort handle plus the promise that says its finally cleanup has run. */
+    shellTasks = new Map();
+    agentTasks = new Set();
+    agentOpenReservations = new Map();
+    agentSessions = new Map();
+    idleWaiters = new Set();
+    stopping = null;
+    accepting = true;
+    snapshot() {
+        const activeAgentRefs = new Set(this.agentTasks);
+        for (const sessionRef of this.agentOpenReservations.keys())
+            activeAgentRefs.add(sessionRef);
+        return { activeShellTasks: this.shellTasks.size, activeAgentTasks: activeAgentRefs.size };
+    }
+    canUpdate() {
+        const snapshot = this.snapshot();
+        return this.accepting && snapshot.activeShellTasks === 0 && snapshot.activeAgentTasks === 0;
+    }
+    /** Count-only drain predicate: unlike canUpdate(), closing admission does not make this false. */
+    isIdle() {
+        const snapshot = this.snapshot();
+        return snapshot.activeShellTasks === 0 && snapshot.activeAgentTasks === 0;
+    }
+    /** Waits until both active counts are zero, or returns false at the bounded drain deadline. */
+    waitForIdle(timeoutMs, signal) {
+        if (this.isIdle())
+            return Promise.resolve(true);
+        if (signal?.aborted)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            let timer;
+            const finish = (idle) => {
+                if (timer === undefined)
+                    return;
+                clearTimeout(timer);
+                timer = undefined;
+                this.idleWaiters.delete(onIdle);
+                signal?.removeEventListener('abort', onAbort);
+                resolve(idle);
+            };
+            const onIdle = () => finish(true);
+            const onAbort = () => finish(false);
+            this.idleWaiters.add(onIdle);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            timer = setTimeout(() => finish(false), timeoutMs);
+        });
+    }
+    notifyIfIdle() {
+        if (!this.isIdle())
+            return;
+        for (const waiter of [...this.idleWaiters])
+            waiter();
+    }
+    /** Run one shell task under an abort signal which force-update owns. */
+    async withShellTask(run) {
+        if (!this.accepting)
+            throw new Error('Workstation is not accepting new work');
+        const controller = new AbortController();
+        let complete;
+        const cleanedUp = new Promise((resolve) => { complete = resolve; });
+        this.shellTasks.set(controller, cleanedUp);
+        try {
+            return await run(controller.signal);
+        }
+        finally {
+            this.shellTasks.delete(controller);
+            complete();
+            this.notifyIfIdle();
+        }
+    }
+    /** Register a live native agent for force-stop; idle sessions deliberately do not count as busy. */
+    registerAgentSession(sessionRef, close) {
+        this.agentSessions.set(sessionRef, close);
+    }
+    /** Atomically admits and counts an asynchronous open before any journal or subprocess await. */
+    tryReserveAgentOpen(sessionRef) {
+        if (!this.accepting)
+            return false;
+        this.agentOpenReservations.set(sessionRef, (this.agentOpenReservations.get(sessionRef) ?? 0) + 1);
+        return true;
+    }
+    agentOpenFinished(sessionRef) {
+        const reservations = this.agentOpenReservations.get(sessionRef) ?? 0;
+        if (reservations <= 1)
+            this.agentOpenReservations.delete(sessionRef);
+        else
+            this.agentOpenReservations.set(sessionRef, reservations - 1);
+        this.notifyIfIdle();
+    }
+    /** Graceful drain closes admission too; only this flag authorizes destructive late-open cleanup. */
+    isForceStopping() {
+        return this.stopping !== null;
+    }
+    unregisterAgentSession(sessionRef) {
+        this.agentSessions.delete(sessionRef);
+        this.agentTasks.delete(sessionRef);
+        this.notifyIfIdle();
+    }
+    /** Returns false whenever an update has closed the new-turn admission gate. */
+    agentTurnStarted(sessionRef) {
+        if (!this.accepting)
+            return false;
+        this.agentTasks.add(sessionRef);
+        return true;
+    }
+    agentTurnFinished(sessionRef) {
+        this.agentTasks.delete(sessionRef);
+        this.notifyIfIdle();
+    }
+    /**
+     * Atomically refuse future work, signal every shell process group through its owning executor,
+     * and close every native agent. All closes are attempted even when one bridge fails.
+     */
+    async stopAll() {
+        if (this.stopping)
+            return this.stopping;
+        this.accepting = false;
+        this.stopping = (async () => {
+            // Snapshot before aborting: an executor may synchronously observe abort and finish, deleting
+            // itself from the live map. The snapshot's cleanup promises are the authoritative barrier.
+            const shells = [...this.shellTasks.entries()];
+            for (const [task] of shells)
+                task.abort();
+            this.agentTasks.clear();
+            this.agentOpenReservations.clear();
+            this.notifyIfIdle();
+            const [outcomes] = await Promise.all([
+                Promise.allSettled([...this.agentSessions.values()].map(async (close) => close())),
+                Promise.all(shells.map(([, cleanedUp]) => cleanedUp)),
+            ]);
+            const failures = outcomes.filter((outcome) => outcome.status === 'rejected');
+            if (failures.length > 0)
+                throw new AggregateError(failures.map((failure) => failure.reason), 'Unable to close all agent sessions');
+        })();
+        return this.stopping;
+    }
+}

package/dist/workstation/update/types.js

@@ -0,0 +1,3 @@
+export function isTerminalPhase(phase) {
+    return phase === 'BUSY' || phase === 'SUCCEEDED' || phase === 'FAILED' || phase === 'ROLLED_BACK';
+}