@platless/axom-cli 0.1.0

package/dist/workstation/service/installer.js

@@ -0,0 +1,362 @@
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { launchAgentPath, renderLaunchAgent } from './launchd.js';
+import { renderSystemdUnit, systemdUnitPath } from './systemd.js';
+import { assertSafeServiceContext, SERVICE_LABEL } from './types.js';
+async function runProcess(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        child.once('error', reject);
+        child.once('close', (code) => {
+            if (code === 0)
+                resolve({ code, stdout, stderr });
+            else
+                reject(new Error(`${command} ${args.join(' ')} failed (${code ?? 'signal'}): ${stderr || stdout}`));
+        });
+    });
+}
+async function writeTemp(contents) {
+    const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'axom-workstation-service-'));
+    const file = path.join(directory, `${SERVICE_LABEL}.tmp`);
+    await fs.writeFile(file, contents, { mode: 0o600 });
+    return file;
+}
+/**
+ * Whether launchd's own reported job state is "running" — `launchctl print` *succeeding* only means
+ * the job is loaded, not that it is actually running: a crash-looping or stopped-but-loaded job
+ * still prints successfully, with output like `state = not running` and no `pid` line. Real output
+ * for a running job looks like:
+ *
+ * ```
+ *   state = running
+ *   pid = 33497
+ *   last exit code = (never exited)
+ * ```
+ *
+ * Falls back to treating the print as running if no `state` line is found at all, so an
+ * unrecognised output shape (a future macOS version) still reports something instead of throwing.
+ */
+function launchdIsRunning(printStdout) {
+    const match = /^\s*state = (.+)$/m.exec(printStdout);
+    if (!match)
+        return true;
+    return match[1].trim() === 'running';
+}
+async function assertWritable(directory) {
+    try {
+        await fs.access(directory, fs.constants.W_OK);
+    }
+    catch {
+        throw new Error(`The npm prefix ${directory} is not writable by the service user. Grant the authorizing user write access before enabling unattended updates.`);
+    }
+}
+const defaultDeps = {
+    run: runProcess,
+    writeTemp,
+    assertWritable,
+    ensureDirectory: async (directory) => { await fs.mkdir(directory, { recursive: true }); },
+    pathExists: async (file) => {
+        try {
+            await fs.access(file);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    wait: async (milliseconds) => { await new Promise((resolve) => { setTimeout(resolve, milliseconds); }); },
+    removeTemp: async (file) => {
+        await fs.rm(file, { force: true });
+        const directory = path.dirname(file);
+        // `writeTemp` owns only its uniquely prefixed directory. Never infer ownership from a caller
+        // supplied path: tests and integrations may stage a file directly under /tmp.
+        if (path.basename(directory).startsWith('axom-workstation-service-')) {
+            await fs.rmdir(directory).catch(() => undefined);
+        }
+    },
+};
+/**
+ * Pauses between `kickstart` attempts while launchd is still transitioning a job out of the domain
+ * (error 37). The schedule MUST outlast launchd's 20s SIGTERM-to-SIGKILL grace (`ExitTimeOut`,
+ * which the LaunchAgent this writes does not override), because on the server-driven update path
+ * the job being torn down is the old daemon — and that daemon deliberately lingers after SIGTERM
+ * to observe this very command (`awaitProvisionOutcome`, runUpdate.ts). launchd keeps the job "in
+ * transition" for exactly as long as that process lives, so a budget shorter than the grace loses
+ * the race by construction: the previous 3.25s schedule returned 37 on every attempt on two real
+ * machines, gave up, and — the `bootout` having already succeeded — left both with no job
+ * registered in launchd at all. Exported so runUpdate.ts can assert its confirm window exceeds
+ * this whole schedule instead of re-deriving the invariant by hand.
+ */
+export const LAUNCHD_TRANSITION_BACKOFF_MS = [250, 500, 1_000, 1_500, 2_500, 4_000, 6_000, 8_000];
+/**
+ * Creates a manager for the current user's service. Service files are staged as `.tmp` files and
+ * renamed only after a complete copy, so an interrupted install never leaves a partial unit.
+ */
+export function createServiceManager(context, overrides = {}) {
+    assertSafeServiceContext(context);
+    const deps = { ...defaultDeps, ...overrides };
+    const target = context.platform === 'darwin' ? launchAgentPath(context.homeDir) : systemdUnitPath(context.homeDir);
+    const contents = context.platform === 'darwin' ? renderLaunchAgent(context) : renderSystemdUnit(context);
+    const launchdDomain = `gui/${context.userId}/${SERVICE_LABEL}`;
+    // `gui/<uid>` exists only while someone is logged into the GUI. Switching this agent to
+    // `user/<uid>` was tried and reverted — record the measurement so nobody re-derives the wrong
+    // conclusion: `launchctl bootstrap user/<uid> <plist>` fails with "Bootstrap failed: 5" for any
+    // agent plist, including a minimal one that only runs /bin/sleep, on machines with and without a
+    // GUI session, with and without root. What actually varies is whether the GUI session exists: an
+    // SSH shell on a logged-in machine reaches `gui/<uid>` fine and needs no sudo; a Mac at the login
+    // window has no such domain and every call returns 125. Distinct from `launchdAbsent`: that means
+    // "domain reachable, job not present", this means "no domain at all".
+    const launchdDomainUnreachable = (error) => /Domain does not support specified action/i.test(error instanceof Error ? error.message : String(error));
+    const launchdAbsent = (error) => /Could not find service|No such process/i.test(error instanceof Error ? error.message : String(error));
+    /**
+     * The single place launchd's "125" becomes something a user can act on. Every darwin path —
+     * install, start, stop, restart, status — funnels through here, because translating it in only
+     * one of them is exactly the gap this replaces: `start` on a machine with the plist already in
+     * place never reaches `install`, so it surfaced the raw text.
+     */
+    const NO_GUI_SESSION = 'No GUI login session on this machine, so launchd has no user session to run the workstation '
+        + 'service in. Log in at the console (or enable automatic login), then run '
+        + '`axom workstation install` again.';
+    const withGuiSessionHint = async (op) => {
+        try {
+            return await op();
+        }
+        catch (error) {
+            if (context.platform === 'darwin' && launchdDomainUnreachable(error))
+                throw new Error(NO_GUI_SESSION);
+            throw error;
+        }
+    };
+    const launchdBootstrapRace = (error) => /Bootstrap failed:\s*5:\s*Input\/output error/i.test(error instanceof Error ? error.message : String(error));
+    const launchdTransitioning = (error) => /launchctl kickstart.*failed \(37\)/i.test(error instanceof Error ? error.message : String(error));
+    const launchdPrint = () => deps.run('launchctl', ['print', launchdDomain]);
+    const launchdKickstart = () => deps.run('launchctl', ['kickstart', '-k', launchdDomain]);
+    const launchdBootstrap = () => deps.run('launchctl', ['bootstrap', `gui/${context.userId}`, target]);
+    const detail = (error) => (error instanceof Error ? error.message : String(error)).trim();
+    const launchdStuck = (error) => new Error(`launchd never finished releasing ${SERVICE_LABEL}: ${LAUNCHD_TRANSITION_BACKOFF_MS.length + 1} kickstart attempts over `
+        + `${LAUNCHD_TRANSITION_BACKOFF_MS.reduce((total, each) => total + each, 0)}ms all reported the job as still transitioning. `
+        + 'The service is NOT registered with launchd right now, so nothing will start it. '
+        + 'Re-run `axom workstation install` on this machine once launchd has settled. '
+        + `Last launchd error: ${detail(error)}`);
+    /**
+     * Bring the job up, tolerating the window where launchd has acknowledged a bootout but has not
+     * finished tearing the job down.
+     *
+     * Error 37 is launchd's answer to `kickstart` for a job in that transitional state. The retry
+     * used to be a single 100ms sleep, which real-machine acceptance disproved twice on two machines:
+     * `kickstart` still returned 37, the caller gave up, and — because the `bootout` in
+     * `performInstall` had already succeeded — the machine was left with *no* job in launchd at all.
+     * The schedule below is deliberately bounded (never an unbounded retry loop) and deliberately
+     * shorter than the window `provisionService` waits for this whole command (runUpdate.ts), so an
+     * exhausted retry is reported as a failure rather than swallowed by that timeout.
+     *
+     * Exhaustion throws {@link launchdStuck} instead of falling through to `bootstrap`: bootstrapping
+     * a job launchd is still tearing down fails with its own unrelated-looking error, and reporting
+     * *that* is how the real cause stayed invisible.
+     */
+    const launchdStart = async () => {
+        let transitionError = null;
+        for (let attempt = 0;; attempt++) {
+            let loaded = false;
+            try {
+                // Querying the system domain first avoids the common duplicate Bootstrap failed: 5 error.
+                await launchdPrint();
+                loaded = true;
+            }
+            catch (error) {
+                if (!launchdAbsent(error))
+                    throw error;
+            }
+            if (loaded) {
+                try {
+                    return await launchdKickstart();
+                }
+                catch (error) {
+                    // The job may be booted out after `print` but before `kickstart`, or still be on its way
+                    // out (37). Re-probe after a short pause: once launchd reports definitive absence the
+                    // loop falls through to `bootstrap` below, which is the correct action for an absent job.
+                    if (!launchdAbsent(error) && !launchdTransitioning(error))
+                        throw error;
+                    if (attempt >= LAUNCHD_TRANSITION_BACKOFF_MS.length)
+                        throw launchdStuck(error);
+                    transitionError = error;
+                    await deps.wait(LAUNCHD_TRANSITION_BACKOFF_MS[attempt]);
+                    continue;
+                }
+            }
+            try {
+                return await launchdBootstrap();
+            }
+            catch (error) {
+                if (!launchdBootstrapRace(error)) {
+                    // A bootstrap failure that follows a run of 37s is that transition, still unfinished.
+                    // Say so, rather than surfacing a bootstrap error nobody can connect to the real cause.
+                    if (transitionError)
+                        throw launchdStuck(error);
+                    throw error;
+                }
+                // A concurrent bootstrap can win between the absence check and our bootstrap. Confirm that
+                // state before kickstarting; never turn an arbitrary bootstrap error into a false success.
+                await launchdPrint();
+                return launchdKickstart();
+            }
+        }
+    };
+    const lifecycle = async (action) => {
+        if (context.platform === 'linux') {
+            return deps.run('systemctl', ['--user', action === 'status' ? 'is-active' : action, SERVICE_LABEL + '.service']);
+        }
+        if (action === 'status')
+            return launchdPrint();
+        // `kill` is not a stop operation for a KeepAlive job: launchd immediately respawns it. A
+        // bootout removes the job from the user's GUI domain; start/bootstrap restores it from the
+        // durable LaunchAgent plist. This keeps explicit stop meaningful across both service managers.
+        if (action === 'stop')
+            return deps.run('launchctl', ['bootout', launchdDomain]);
+        if (action === 'restart') {
+            try {
+                await deps.run('launchctl', ['bootout', launchdDomain]);
+            }
+            catch (error) {
+                // `restart` after an explicit `stop` is a valid request: absence means there is nothing
+                // left to unload, and launchdStart will bootstrap the durable plist.
+                if (!launchdAbsent(error))
+                    throw error;
+            }
+            return launchdStart();
+        }
+        return launchdStart();
+    };
+    // Extracted so `start()` can reuse it: reinstalling is the same work whether triggered
+    // explicitly (`axom workstation install`) or as `start()`'s self-heal for a missing definition
+    // file. Both platform branches leave the service running, so callers need no separate start.
+    const performInstall = async (_options = {}) => {
+        await deps.assertWritable(context.npmPrefix);
+        await deps.ensureDirectory(path.dirname(target));
+        const temp = await deps.writeTemp(contents);
+        const targetTemp = `${target}.tmp`;
+        try {
+            await deps.run('install', ['-m', '644', temp, targetTemp]);
+            await deps.run('mv', [targetTemp, target]);
+            if (context.platform === 'linux') {
+                await deps.run('systemctl', ['--user', 'daemon-reload']);
+                await deps.run('systemctl', ['--user', 'enable', '--now', `${SERVICE_LABEL}.service`]);
+            }
+            else {
+                // Reload an existing service before bootstrapping the replacement into the GUI domain.
+                await deps.run('launchctl', ['bootout', launchdDomain]).catch(() => undefined);
+                // A just-booted-out job can briefly race launchd's domain bookkeeping. Reuse the
+                // bounded probe/bootstrap path so Bootstrap failed: 5 is confirmed then kickstarted, and
+                // so a launchd that never releases the job is reported instead of leaving the machine
+                // with the bootout applied and nothing bootstrapped in its place.
+                await launchdStart();
+            }
+        }
+        finally {
+            await deps.removeTemp?.(temp);
+        }
+    };
+    return {
+        async install(options = {}) {
+            await withGuiSessionHint(() => performInstall(options));
+        },
+        /**
+         * The inverse of `install`: unload/disable the running unit (tolerating one that was never
+         * loaded — uninstalling something absent is success, not an error) and remove its definition
+         * file. Best-effort by design: a machine that already hand-removed the file should still end
+         * up in the same clean state.
+         */
+        async uninstall() {
+            if (context.platform === 'linux') {
+                await deps.run('systemctl', ['--user', 'disable', '--now', `${SERVICE_LABEL}.service`]).catch((error) => {
+                    if (!/does not exist|not loaded|No such file/i.test(error instanceof Error ? error.message : String(error)))
+                        throw error;
+                });
+                await deps.run('rm', ['-f', target]);
+                // Unlike `disable` above, `daemon-reload` has no "the unit was already absent" failure
+                // mode to discriminate — it just reloads systemd's unit cache wholesale. A failure here
+                // means something is genuinely wrong with the user's systemd session (permissions, DBus
+                // unreachable), not a benign no-op, so let it propagate exactly like install()'s identical
+                // call at line 153: swallowing it would report `uninstall` as successful while leaving a
+                // real error unsurfaced.
+                await deps.run('systemctl', ['--user', 'daemon-reload']);
+            }
+            else {
+                await deps.run('launchctl', ['bootout', launchdDomain]).catch((error) => {
+                    if (!launchdAbsent(error))
+                        throw error;
+                });
+                await deps.run('rm', ['-f', target]);
+            }
+        },
+        /**
+         * `uninstall` removes only the service definition file, never the workstation credential that
+         * gates whether `axom workstation start`'s credential chain treats this machine as already
+         * registered. A `start` after `uninstall` would otherwise bootstrap a definition that is no
+         * longer on disk and surface launchd/systemd's raw error; reinstall first instead.
+         */
+        async start() {
+            await withGuiSessionHint(async () => {
+                if (!(await deps.pathExists(target)))
+                    await performInstall({});
+                await lifecycle('start');
+            });
+        },
+        async stop() { await withGuiSessionHint(() => lifecycle('stop')); },
+        async restart() { await withGuiSessionHint(() => lifecycle('restart')); },
+        async status() {
+            try {
+                const result = await lifecycle('status');
+                // `systemctl is-active` succeeding means the unit genuinely is active — its own definition
+                // of "status" already answers the question. `launchctl print` succeeding only means the
+                // job is loaded, so on macOS the answer has to come from the state it actually reports.
+                const running = context.platform === 'darwin' ? launchdIsRunning(result.stdout) : true;
+                return { running, detail: result.stdout.trim() || undefined };
+            }
+            catch (error) {
+                // Absence must report `{ running: false }`, not throw — and darwin/linux say "absent" in
+                // different vocabularies, so each platform gets its own predicate rather than one regex
+                // built to (mis)match both. `launchdAbsent` is the same predicate the start/stop paths
+                // already trust to recognise real launchd absence text.
+                if (context.platform === 'darwin') {
+                    if (launchdAbsent(error))
+                        return { running: false };
+                    // No GUI session means no domain, which means the service is definitionally not running.
+                    // Reporting that is more truthful than raising — `status` answers a question, and the
+                    // answer here is simply "no". The actionable explanation belongs on the paths that were
+                    // asked to *change* something (start/stop/restart/install), not on the one that asks.
+                    if (launchdDomainUnreachable(error))
+                        return { running: false };
+                    throw error;
+                }
+                const detail = error instanceof Error ? error.message : String(error);
+                // `systemctl is-active` exits nonzero for an inactive *or failed* unit. Its process error
+                // is not a privilege error and must remain a useful status result.
+                if (/inactive|systemctl(?: --user)? is-active.*\bfailed\b/i.test(detail))
+                    return { running: false };
+                throw error;
+            }
+        },
+    };
+}
+export async function installService(context, options) {
+    await createServiceManager(context).install(options);
+}
+export async function startService(context) {
+    await createServiceManager(context).start();
+}
+export async function stopService(context) {
+    await createServiceManager(context).stop();
+}
+export async function restartService(context) {
+    await createServiceManager(context).restart();
+}
+export async function serviceStatus(context) {
+    return createServiceManager(context).status();
+}

package/dist/workstation/service/launchd.js

@@ -0,0 +1,46 @@
+import { assertSafeServiceContext, SERVICE_LABEL } from './types.js';
+function xml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}
+function keyValue(key, value) {
+    return `\t\t<key>${xml(key)}</key>\n\t\t<string>${xml(value)}</string>`;
+}
+export function launchAgentPath(homeDir) {
+    return `${homeDir}/Library/LaunchAgents/${SERVICE_LABEL}.plist`;
+}
+export function renderLaunchAgent(context) {
+    assertSafeServiceContext(context);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>Label</key>
+\t<string>${SERVICE_LABEL}</string>
+\t<key>WorkingDirectory</key>
+\t<string>${xml(context.homeDir)}</string>
+\t<key>ProgramArguments</key>
+\t<array>
+\t\t<string>${xml(context.nodePath)}</string>
+\t\t<string>${xml(context.cliPath)}</string>
+\t\t<string>__daemon</string>
+\t</array>
+\t<key>EnvironmentVariables</key>
+\t<dict>
+${keyValue('HOME', context.homeDir)}
+${keyValue('AXOM_WORKSTATION_CONFIG_DIR', context.configDir)}
+${keyValue('AXOM_WORKSTATION_NPM_PATH', context.npmPath)}
+${keyValue('AXOM_WORKSTATION_NPM_PREFIX', context.npmPrefix)}
+${keyValue('PATH', context.pathEnv)}
+\t</dict>
+\t<key>StandardOutPath</key>
+\t<string>${xml(`${context.configDir}/daemon.log`)}</string>
+\t<key>StandardErrorPath</key>
+\t<string>${xml(`${context.configDir}/daemon.log`)}</string>
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>KeepAlive</key>
+\t<true/>
+</dict>
+</plist>
+`;
+}

package/dist/workstation/service/loginShell.js

@@ -0,0 +1,36 @@
+import { execFile } from 'node:child_process';
+/** A login shell that will not answer within this is not worth blocking an install on. */
+const LOGIN_SHELL_TIMEOUT_MS = 3_000;
+/**
+ * The `PATH` the user's own login shell produces, or `undefined` if it cannot be obtained.
+ *
+ * Needed because a service definition can be (re)written from two very different environments. When
+ * a person runs `service install` in a terminal, `process.env.PATH` already describes where their
+ * tools are. When the **daemon** re-provisions itself after an update, `process.env.PATH` is the
+ * service's own PATH — the one the service definition gave it. Building the new definition from
+ * that would bake in whatever the old one had, so a machine whose daemon cannot see `~/.local/bin`
+ * could never repair itself by updating: it would faithfully reinstall its own blind spot.
+ *
+ * `-l` is what makes this worth doing: the profile files are where per-user prefixes get added.
+ * Best effort by construction — a shell that errors, times out, or prints nothing leaves the caller
+ * on `process.env.PATH`, which is exactly today's behaviour.
+ */
+export function loginShellPath(deps = {}) {
+    const shell = deps.shell ?? process.env.SHELL;
+    if (!shell)
+        return Promise.resolve(undefined);
+    const exec = deps.exec ?? execFile;
+    return new Promise((resolve) => {
+        try {
+            exec(shell, ['-lc', 'printf %s "$PATH"'], { timeout: LOGIN_SHELL_TIMEOUT_MS }, (error, stdout) => {
+                if (error)
+                    return resolve(undefined);
+                const value = String(stdout).trim();
+                resolve(value.length > 0 ? value : undefined);
+            });
+        }
+        catch {
+            resolve(undefined);
+        }
+    });
+}

package/dist/workstation/service/systemd.js

@@ -0,0 +1,48 @@
+import { assertSafeServiceContext, SERVICE_LABEL } from './types.js';
+const SIMPLE_TOKEN = /^[A-Za-z0-9_@+.,/:=-]+$/;
+function escapeUnitValue(value) {
+    // `%%` is the literal-percent form for systemd specifier expansion. Environment assignments
+    // are not shell commands, so `$` remains literal there.
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%');
+}
+function escapeExecValue(value) {
+    // ExecStart additionally performs systemd's environment expansion; `$$` carries a literal `$`
+    // into Node instead of resolving an environment variable while systemd parses the unit.
+    return escapeUnitValue(value).replace(/\$/g, '$$$$');
+}
+/** One argument according to systemd's command-line parser. */
+function systemdToken(value) {
+    const escaped = escapeExecValue(value);
+    return SIMPLE_TOKEN.test(value) ? escaped : `"${escaped}"`;
+}
+/** Environment quotes must enclose the complete KEY=value assignment, not just its value. */
+function environment(key, value) {
+    const assignment = `${key}=${value}`;
+    return SIMPLE_TOKEN.test(value) ? `Environment=${assignment}` : `Environment="${escapeUnitValue(assignment)}"`;
+}
+export function systemdUnitPath(homeDir) {
+    return `${homeDir}/.config/systemd/user/${SERVICE_LABEL}.service`;
+}
+export function renderSystemdUnit(context) {
+    assertSafeServiceContext(context);
+    return `[Unit]
+Description=Axomwork Workstation Client
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${systemdToken(context.homeDir)}
+${environment('HOME', context.homeDir)}
+${environment('AXOM_WORKSTATION_CONFIG_DIR', context.configDir)}
+${environment('AXOM_WORKSTATION_NPM_PATH', context.npmPath)}
+${environment('AXOM_WORKSTATION_NPM_PREFIX', context.npmPrefix)}
+${environment('PATH', context.pathEnv)}
+ExecStart=${systemdToken(context.nodePath)} ${systemdToken(context.cliPath)} __daemon
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+}

package/dist/workstation/service/types.js

@@ -0,0 +1,73 @@
+import path from 'node:path';
+export const SERVICE_LABEL = 'com.platless.axom-workstation';
+const PATH_FIELDS = ['homeDir', 'nodePath', 'cliPath', 'npmPath', 'npmPrefix', 'configDir'];
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
+const SAFE_USERNAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+/**
+ * The context is rendered into a user-owned service definition. Paths may legitimately contain
+ * spaces and quotes, but never controls; accepting a newline would let an environment value add a
+ * new unit directive. Reject traversal spellings too, so the displayed and executed paths match.
+ */
+/** `/usr/bin` and `/bin` are the floor: a pathological `PATH` must still leave a usable service. */
+const PATH_FLOOR = ['/usr/bin', '/bin'];
+/**
+ * The `PATH` to write into the service definition, built from the environment `service install`
+ * was run in.
+ *
+ * That environment is the best evidence available of where the user's tools actually live: the
+ * install command is typed into a shell that can see them. The previous behaviour — node's own
+ * directory plus `/usr/bin:/bin` — could not see `~/.local/bin`, `/opt/homebrew/bin` or any other
+ * per-user prefix, so a bridge that spawns its CLI (codex does; the Claude one does not, which is
+ * exactly why the gap stayed hidden) reported the tool as missing while it worked fine in a
+ * terminal.
+ *
+ * [nodeDirectory] is forced in because the daemon must be able to re-exec node regardless of what
+ * the caller's `PATH` says. Empty and relative entries are dropped rather than rejected: a real
+ * shell `PATH` may well contain `.` or a stray `::`, and a install that fails over that would be
+ * worse than one that quietly ignores an entry the daemon could not safely use anyway. Control
+ * characters are the one hard error — a newline in a systemd unit value would let an environment
+ * entry inject a directive of its own.
+ */
+export function buildServicePath(rawPath, nodeDirectory) {
+    const segments = [nodeDirectory, ...(rawPath ?? '').split(':'), ...PATH_FLOOR];
+    const kept = [];
+    for (const segment of segments) {
+        if (CONTROL_CHARACTER.test(segment))
+            throw new Error('PATH contains control characters');
+        if (segment.length === 0 || !path.isAbsolute(segment))
+            continue;
+        if (!kept.includes(segment))
+            kept.push(segment);
+    }
+    return kept.join(':');
+}
+export function assertSafeServiceContext(context) {
+    if (context.platform !== 'darwin' && context.platform !== 'linux') {
+        throw new Error('platform must be darwin or linux');
+    }
+    if (!SAFE_USERNAME.test(context.username)) {
+        throw new Error('username contains unsafe characters');
+    }
+    if (!Number.isInteger(context.userId) || context.userId < 0) {
+        throw new Error('userId must be a non-negative integer');
+    }
+    for (const field of PATH_FIELDS) {
+        const value = context[field];
+        if (CONTROL_CHARACTER.test(value))
+            throw new Error(`${field} contains control characters`);
+        if (!path.isAbsolute(value))
+            throw new Error(`${field} must be an absolute path`);
+        if (path.normalize(value) !== value)
+            throw new Error(`${field} must not contain traversal or redundant separators`);
+    }
+    // pathEnv is a colon-joined list, so the single-path rules above do not apply to it as a whole.
+    // It is checked per segment, and by the same standard: nothing that could end a plist string or
+    // a unit line early. Built by buildServicePath, but re-checked here because the context can also
+    // be constructed by a caller that did not go through it.
+    if (CONTROL_CHARACTER.test(context.pathEnv))
+        throw new Error('pathEnv contains control characters');
+    const segments = context.pathEnv.split(':');
+    if (segments.length === 0 || segments.some((segment) => segment.length === 0 || !path.isAbsolute(segment))) {
+        throw new Error('pathEnv must be a colon-joined list of absolute paths');
+    }
+}

package/dist/workstation/supervision.js

@@ -0,0 +1,52 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+export const SUPERVISION_ENV = 'AXOM_WORKSTATION_SUPERVISION';
+const VALUES = new Set(['launchd', 'systemd', 'container', 'foreground']);
+const defaultProbes = {
+    platform: process.platform,
+    env: process.env,
+    exists: (p) => existsSync(p),
+    readText: (p) => { try {
+        return readFileSync(p, 'utf8');
+    }
+    catch {
+        return undefined;
+    } },
+    systemdUserSessionAvailable: () => {
+        try {
+            const out = execFileSync('systemctl', ['--user', 'is-system-running'], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 }).toString().trim();
+            return out !== 'offline' && out !== '';
+        }
+        catch (error) {
+            // systemctl --user is-system-running exits non-zero for degraded while still printing it
+            if (error instanceof Error && 'stdout' in error) {
+                const stdout = error.stdout?.toString().trim();
+                return stdout && stdout !== 'offline' && stdout !== '';
+            }
+            return false;
+        }
+    },
+};
+/**
+ * Who restarts the daemon when it exits. Explicit env wins; then macOS is launchd; a container is
+ * detected *before* systemd because a container occasionally has systemd but almost never a user
+ * session, and the Docker sandbox is the case this exists for; a real systemd-in-container user
+ * pins the value with the env var.
+ */
+export function detectSupervision(overrides = {}) {
+    const p = { ...defaultProbes, ...overrides };
+    const explicit = p.env[SUPERVISION_ENV]?.trim();
+    if (explicit) {
+        if (!VALUES.has(explicit))
+            throw new Error(`${SUPERVISION_ENV} must be one of launchd, systemd, container, foreground (got '${explicit}')`);
+        return explicit;
+    }
+    if (p.platform === 'darwin')
+        return 'launchd';
+    const cgroup = p.readText('/proc/1/cgroup') ?? '';
+    if (p.exists('/.dockerenv') || p.exists('/run/.containerenv') || /docker|containerd|kubepods/.test(cgroup) || Boolean(p.env.KUBERNETES_SERVICE_HOST))
+        return 'container';
+    if (p.systemdUserSessionAvailable())
+        return 'systemd';
+    return 'foreground';
+}