@platless/axom-cli 0.5.9 → 0.6.52

package/dist/commands/update.js

@@ -1,4 +1,16 @@
+import { z } from 'zod';
+import { inspectWorkstation } from '../workstation/control/inspect.js';
+import { requestDeviceRuntimeUpdate, requestRuntimeUpdate } from '../workstation/control/runtimeClient.js';
+import { inspectLocalDevice } from '../workstation/control/deviceCommands.js';
+import { assertDeviceGuard, deviceRuntimeUpdateRequestSchema } from '../workstation/control/deviceProtocol.js';
+import { withWorkstationLock } from '../workstation/control/locks.js';
+import { bindingGuardSchema, LocalControlError } from '../workstation/control/protocol.js';
+import { enrollmentFailure } from '../workstation/control/enrollment.js';
+import { readLocalRequest } from '../workstation/control/commands.js';
+import { deploymentDownloadURL, normalizeWorkstationServer, workstationEndpoint } from '../workstation/control/serverIdentity.js';
 import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
 import { UsageError, loadConfig, resolveServer } from '../config.js';
 import { runCommand } from '../output.js';
 import { clientDir } from '../workstation/config.js';
@@ -13,8 +25,8 @@ function isManifest(value) {
 }
 /** Fetches the release the server currently publishes for this exact deployment. */
 async function fetchManifest(server, fetchImpl) {
-    const url = new URL('/download/client/manifest.json', server).toString();
-    const response = await fetchImpl(url);
+    const url = workstationEndpoint(server, '/download/client/manifest.json').toString();
+    const response = await fetchImpl(url, { redirect: 'error', signal: AbortSignal.timeout(30_000) });
     if (!response.ok) {
         throw new Error(`Fetching the release manifest failed with HTTP ${response.status}`);
     }
@@ -55,6 +67,35 @@ export async function updateAction(options, deps = {}) {
         version: manifest.version, url: manifest.url, size: manifest.size, sha512: manifest.sha512,
     };
     const dir = deps.dir ?? clientDir();
+    if (!deps.createCoordinator) {
+        let deviceRoot = false;
+        for (const name of ['device.json', 'legacy-migration.json']) {
+            try {
+                await fs.lstat(path.join(dir, name));
+                deviceRoot = true;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        if (deviceRoot) {
+            const current = await inspectLocalDevice(dir);
+            const result = await updateLocalCli({ schemaVersion: 2, action: 'update', operationId: `manual-${randomUUID()}`, server, guard: { deviceRevision: current.deviceRevision, runtimeGeneration: current.runtime.generation }, expectedRelease: { version: release.version, sha512: release.sha512 } }, dir, fetchImpl);
+            if (result.status === 'succeeded' || result.status === 'pending' && !result.error) {
+                (deps.log ?? console.log)(result.status === 'pending' ? 'Update requested. Check workstation status for progress.' : `Installed ${release.version}.`);
+                return;
+            }
+            throw new Error(result.error?.message ?? 'The workstation is busy; try again when its work finishes.');
+        }
+        const current = await inspectWorkstation(dir);
+        const result = await updateLocalCli({ operationId: `manual-${randomUUID()}`, server, guard: { revision: current.revision, runtimeGeneration: current.runtime.generation }, expectedRelease: { version: release.version, sha512: release.sha512 } }, dir, fetchImpl);
+        if (result.status === 'succeeded' || result.status === 'pending') {
+            (deps.log ?? console.log)(result.status === 'pending' ? 'Update requested. Check workstation status for progress.' : `Installed ${release.version}.`);
+            return;
+        }
+        throw new Error(result.error?.message ?? 'The workstation is busy; try again when its work finishes.');
+    }
     const coordinator = deps.createCoordinator ? deps.createCoordinator({ dir, server }) : defaultCoordinator(dir, server);
     const command = { commandId: `manual-${randomUUID()}`, release, force: false };
     const status = await coordinator.handle(command);
@@ -78,11 +119,93 @@ export async function updateAction(options, deps = {}) {
             throw new Error(status.error ?? `Update did not complete (phase: ${status.phase}).`);
     }
 }
+const updateRequestSchema = z.object({ operationId: z.string().min(1).max(128), server: z.string(), guard: bindingGuardSchema, expectedRelease: z.object({ version: z.string(), sha512: z.string().regex(/^[a-f0-9]{128}$/i) }).strict() }).strict();
+const deviceUpdateCliSchema = deviceRuntimeUpdateRequestSchema.omit({ release: true }).extend({ expectedRelease: updateRequestSchema.shape.expectedRelease }).strict();
+async function updateDeviceCli(raw, directory, fetchImpl) {
+    let operationId = randomUUID();
+    try {
+        const request = deviceUpdateCliSchema.parse(raw);
+        operationId = request.operationId;
+        const server = normalizeWorkstationServer(request.server);
+        const current = await inspectLocalDevice(directory);
+        if (current.runtime.state !== 'running')
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Start and verify the original device owner before updating');
+        assertDeviceGuard(request.guard, current);
+        const release = await fetchManifest(server, fetchImpl);
+        if (release.version !== request.expectedRelease.version || release.sha512 !== request.expectedRelease.sha512)
+            throw new LocalControlError('BINDING_CONFLICT', 'The published release changed; review it again');
+        deploymentDownloadURL(server, release.url);
+        const status = await requestDeviceRuntimeUpdate(directory, { schemaVersion: 2, action: 'update', operationId, server, guard: request.guard, release });
+        const result = ['BUSY', 'UPDATE_IN_PROGRESS'].includes(status.phase) ? 'busy' : status.phase === 'SUCCEEDED' ? 'succeeded' : ['FAILED', 'ROLLED_BACK'].includes(status.phase) ? 'failed' : 'pending';
+        const inspection = await inspectLocalDevice(directory).catch(() => null);
+        return { operationId, registrationId: null, status: result, inspection, ...(status.error ? { error: { code: 'SERVICE_FAILED', message: status.error } } : {}) };
+    }
+    catch (error) {
+        const code = error instanceof LocalControlError ? error.code : 'UNSUPPORTED_PROTOCOL';
+        return { operationId, registrationId: null, status: code === 'BUSY' ? 'busy' : code === 'OUTCOME_UNKNOWN' ? 'pending' : 'failed', inspection: null, error: { code, message: 'Device update requires the original verified owner and unchanged source/release' } };
+    }
+}
+export async function updateLocalCli(raw, directory, fetchImpl = globalThis.fetch) {
+    if (raw && typeof raw === 'object' && 'schemaVersion' in raw)
+        return updateDeviceCli(raw, directory, fetchImpl);
+    try {
+        const request = updateRequestSchema.parse(raw);
+        const server = normalizeWorkstationServer(request.server);
+        const manifest = await fetchManifest(server, fetchImpl);
+        if (manifest.version !== request.expectedRelease.version || manifest.sha512 !== request.expectedRelease.sha512)
+            throw new LocalControlError('BINDING_CONFLICT', 'The published release changed; review it again');
+        manifest.url = deploymentDownloadURL(server, manifest.url);
+        const before = await inspectWorkstation(directory);
+        if (before.revision !== request.guard.revision || before.runtime.generation !== request.guard.runtimeGeneration)
+            throw new LocalControlError('BINDING_CONFLICT', 'Workstation changed; check it again');
+        if (before.runtime.state === 'unknown')
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Stop and verify the existing daemon before updating');
+        if (before.runtime.state === 'running') {
+            if (before.runtime.binding?.server !== server)
+                throw new LocalControlError('INSTANCE_OCCUPIED', 'Another server owns the running daemon');
+            const status = await requestRuntimeUpdate(directory, manifest, request.operationId);
+            return { status: ['BUSY', 'UPDATE_IN_PROGRESS'].includes(status.phase) ? 'busy' : status.phase === 'SUCCEEDED' ? 'succeeded' : status.phase === 'FAILED' || status.phase === 'ROLLED_BACK' ? 'failed' : 'pending', inspection: await inspectWorkstation(directory) };
+        }
+        return await withWorkstationLock(directory, 'installation', () => withWorkstationLock(directory, 'operation', async () => {
+            const current = await inspectWorkstation(directory);
+            if (current.revision !== request.guard.revision || current.runtime.generation !== request.guard.runtimeGeneration)
+                throw new LocalControlError('BINDING_CONFLICT', 'Workstation changed; check it again');
+            if (current.runtime.state === 'unknown')
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Stop and verify the existing daemon before updating');
+            if (current.runtime.state !== 'stopped')
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'The original stopped owner changed before offline update admission');
+            const status = await createUpdateCoordinator({ dir: directory, server, cliPath: CLI_PATH, serviceLifecycle: 'none', installationLockHeld: true }).handle({ commandId: request.operationId, release: manifest, force: false });
+            return { status: ['BUSY', 'UPDATE_IN_PROGRESS'].includes(status.phase) ? 'busy' : status.phase === 'SUCCEEDED' ? 'succeeded' : status.phase === 'FAILED' || status.phase === 'ROLLED_BACK' ? 'failed' : 'pending', inspection: await inspectWorkstation(directory) };
+        }));
+    }
+    catch (error) {
+        return enrollmentFailure(error, directory);
+    }
+}
 export function registerUpdateCommand(program) {
     const serverOption = () => program.opts().server;
     program
         .command('update')
         .description('Update axom-cli to the release the configured server currently publishes')
+        .option('--json', 'Emit local management protocol JSON')
+        .option('--input-stdin', 'Read the guarded update request from stdin')
         .option('--version <version>', 'Fail unless the server-published release matches this exact version')
-        .action((options) => runCommand(() => updateAction({ server: serverOption(), version: options.version })));
+        .action((options) => runCommand(async () => {
+        if (!options.json)
+            return updateAction({ server: serverOption(), version: options.version });
+        if (!options.inputStdin)
+            throw new UsageError('--json requires --input-stdin');
+        let request;
+        let result;
+        try {
+            request = await readLocalRequest(process.stdin);
+            result = await updateLocalCli(request, clientDir());
+        }
+        catch (error) {
+            result = await enrollmentFailure(error, clientDir());
+        }
+        const device = deviceUpdateCliSchema.safeParse(request);
+        const id = updateRequestSchema.safeParse(request);
+        process.stdout.write(JSON.stringify({ schemaVersion: device.success ? 2 : 1, kind: 'result', operationId: device.success ? device.data.operationId : id.success ? id.data.operationId : randomUUID(), result }) + '\n');
+    }));
 }

package/dist/commands/workstation.js

@@ -1,171 +1,108 @@
-import { hostname } from 'node:os';
-import { basename } from 'node:path';
-import { loadConfig, resolveServer, UsageError } from '../config.js';
-import { accessTokenFor } from '../credentials.js';
-import { ensureFreshToken } from '../mcp.js';
+import { randomUUID } from 'node:crypto';
+import { UsageError } from '../config.js';
 import { runCommand } from '../output.js';
-import { clientDir, loadClientConfig } from '../workstation/config.js';
-import { resolveWorkstationName, sanitizeName } from '../workstation/names.js';
-/**
- * Registers this workstation with the server if it has no credential yet, then leaves it alone.
- * Returns whether it just registered (`false` when an existing credential meant there was nothing
- * to do), so `start` can gate `install()` on that — see its action below for why that gate matters.
- *
- * Shared by `start` (which then hands off to the OS service) and the bare `axom workstation`
- * command (which runs the daemon directly): both need the exact same credential chain, so it lives
- * here once rather than twice.
- *
- * An existing workstation credential boots directly — the common case, and the only sane one for a
- * container that gets recreated on every restart: re-registering each boot would rotate keys for no
- * reason. Otherwise a usable access token registers this machine — `AXOM_ACCESS_TOKEN` (set by a
- * container with no human and no browser) or a stored user token (from `axom auth`), refreshing it
- * first if it's stale. With neither available, an interactive terminal falls back to the device
- * flow; a headless one gets a hard stop naming the fix.
- */
-async function ensureRegistered(deps, serverFlag, nameFlag) {
-    const registered = await loadClientConfig(clientDir()).then(() => true, () => false);
-    if (registered)
-        return false;
-    const config = await loadConfig();
-    const server = resolveServer(config, serverFlag);
-    let token = await accessTokenFor(server);
-    if (!token) {
-        if (!deps.isInteractive()) {
-            throw new UsageError('No credential for this workstation. Set AXOM_ACCESS_TOKEN (create one under Settings → Security → ' +
-                'Access Tokens), or run `axom auth` on a machine with a browser.');
-        }
-        await deps.authenticate(server);
-        token = await ensureFreshToken(server);
-    }
-    const cwd = process.cwd();
-    await deps.registerWorkstation(server, resolveWorkstationName(nameFlag, process.env, hostname()), token, {
-        name: sanitizeName(basename(cwd), 'default'),
-        cwd,
-        shell: process.env.SHELL ?? '/bin/bash',
-    });
-    return true;
-}
-/**
- * Removes `AXOM_ACCESS_TOKEN` from *this process's* copy of the environment, right before the bare
- * `axom workstation` command becomes a long-lived daemon.
- *
- * The daemon spawns agents and shell commands with `{ ...process.env, ... }` (exec.ts, acpClient.ts),
- * so anything still in here reaches every model-authored command and every dependency postinstall
- * that runs in `/workspace` — a container is precisely where this product runs untrusted code. What
- * would leak is not the workstation's own key pair (scoped to one workstation, on disk) but a
- * credential that authenticates *as the user*: it can register further workstations under their
- * account and, with business scopes, call granted MCP tools as them, until somebody notices and
- * revokes it. Fixed once here rather than filtered at each of the two spawn sites, so the next spawn site
- * inherits the fix instead of having to remember it.
- *
- * Nothing after this point needs the value. The daemon authenticates with the file credential
- * written at registration (`clientKey`/`serverPub`), and the `container` update lifecycle downloads
- * its release over that same authenticated management channel.
- *
- * Unconditional, not gated on "we just registered": a container that still has its `/data/ws` volume
- * boots straight past `ensureRegistered`, and that is exactly the long-lived container this protects.
- *
- * The token stays in the *container's* environment, so a restarted container still registers — only
- * this process's copy is dropped. Every reader of it lives before this line: `accessTokenFor`
- * (credentials.ts) reads `process.env.AXOM_ACCESS_TOKEN` on its first line, and its only caller here
- * is `ensureRegistered` above; `insufficientScopeError`/`envAccessTokenRejectedError` (mcp.ts) read
- * it too, but only from the one-shot `axom execute`/`axom struct` CLI processes, which are separate
- * processes with their own untouched copy.
- *
- * `workstation start` deliberately does not call this: it registers and hands off to launchd/systemd
- * rather than becoming the daemon, so dropping the variable would affect only a CLI process that is
- * about to exit.
- */
-function dropAccessTokenFromEnvironment() {
-    delete process.env.AXOM_ACCESS_TOKEN;
-}
-/**
- * Registers `axom workstation start|stop|restart|status|install|uninstall`, the bare
- * `axom workstation` (Docker ENTRYPOINT / debugging foreground run), and the hidden top-level
- * `axom __daemon`.
- *
- * `__daemon` is registered on `program` itself, not on the `workstation` subcommand group: the
- * generated launchd/systemd service definitions invoke it as `<cliPath> __daemon`, a bare
- * top-level argument (see service/launchd.ts and service/systemd.ts).
- */
+import { clientDir } from '../workstation/config.js';
+import { configureRd, rdStatus } from '../workstation/rd/control.js';
+import { runManagedDesktop } from '../workstation/rd/sessions.js';
+import { executeDeviceCommand, inspectLocalDevice } from '../workstation/control/deviceCommands.js';
+import { readLocalRequest } from '../workstation/control/commands.js';
+import { LocalControlError } from '../workstation/control/protocol.js';
+import { deviceEventSchema } from '../workstation/control/deviceProtocol.js';
+import { operationIdSchema } from '../workstation/registrations/enrollmentPending.js';
+import { registrationIdSchema } from '../workstation/registrations/model.js';
+import { addWorkstationRegistration, listWorkstationRegistrations, removeWorkstationRegistration } from './workstationRegistrations.js';
 export function registerWorkstationCommands(program, deps) {
-    const workstation = program.command('workstation').description('Manage the local Axomwork workstation daemon');
-    // Same idiom as `registerUpdateCommand`: the global `--server` is read at action time, not at
-    // registration time, so `axom --server <url> workstation start` works. `axom auth` only writes
-    // `defaultServer` when it is unset, so a user who authenticated against localhost first and
-    // production second would otherwise have no way to keep `start` off localhost.
+    const workstation = program.command('workstation').description('Manage this device and its workstation registration collection');
+    const registrations = deps.registrations ?? { add: addWorkstationRegistration, list: listWorkstationRegistrations, remove: removeWorkstationRegistration };
     const serverOption = () => program.opts().server;
-    // `workstation` (this group) and its `start` subcommand both declare `--server`/`--name` — the
-    // group needs its own copy so the *bare* command accepts them, and `start` keeps its copy for its
-    // own `--help`. But for `axom workstation start --server/--name <value>`, only one of the two
-    // declarations ever actually captures the flag, and it's not always the same one: `program`
-    // parses its own options over the *entire* remaining argv before `workstation` gets a look, so
-    // `--server` — also declared on `program`, globally — is always captured there, leaving both
-    // `options.server` and `workstationOption().server` dead; `--name` has no `program`-level
-    // declaration, so it falls through to `workstation`, which *does* capture it, leaving `start`'s
-    // own `options.name` the dead one instead. `start`'s action below reads the whole fallback chain
-    // so it doesn't matter which link is live for a given flag.
-    const workstationOption = () => workstation.opts();
-    workstation
-        .command('start')
-        .option('--server <url>', 'Axomwork server URL to register this workstation against')
-        .option('--name <name>', 'Workstation name (default: AXOM_WORKSTATION_NAME, then the hostname)')
-        .description('Start the workstation user service')
-        .action((options) => runCommand(async () => {
-        // `install()` runs only when this call just registered the workstation, not on every
-        // `start` — it's not the free idempotent no-op it looks like. On macOS it's bootout, write
-        // plist, bootstrap, and the `deps.start()` right after it is `kickstart -k`: on an
-        // already-registered machine that's two restart windows where there used to be one, plus a
-        // bootout window with a documented stranding mode (`launchdStuck`: the service is not
-        // registered with launchd right now, so nothing will start it). It would also re-pin the
-        // service's `node` execPath to whatever ran this `start` — which repairs a machine stranded
-        // by a removed nvm version only if that's a *good* node; run from an ad-hoc one and it
-        // manufactures the exact stranding it's meant to cure. That repair belongs to the explicit
-        // verb that already exists for it, `axom workstation install`, not as a side effect here.
-        const justRegistered = await ensureRegistered(deps, options.server ?? workstationOption().server ?? serverOption(), options.name ?? workstationOption().name);
-        if (justRegistered)
-            await deps.install();
-        await deps.start();
-    }));
-    workstation
-        .command('stop')
-        .description('Stop the workstation user service')
-        .action(() => runCommand(async () => { await deps.stop(); }));
-    workstation
-        .command('restart')
-        .description('Restart the workstation user service')
-        .action(() => runCommand(async () => { await deps.restart(); }));
-    workstation
-        .command('status')
-        .description('Report whether the workstation daemon is running')
-        .action(() => runCommand(async () => { deps.log(await deps.status()); }));
-    workstation
-        .command('install')
-        .description('Install and enable the operating-system service')
-        .action(() => runCommand(async () => { await deps.install(); }));
-    workstation
-        .command('uninstall')
-        .description('Disable and remove the operating-system service')
-        .action(() => runCommand(async () => { await deps.uninstall(); }));
-    workstation
-        .option('--server <url>', 'Axomwork server URL to register against (default: AXOM_SERVER, then the stored default)')
-        .option('--name <name>', 'Workstation name (default: AXOM_WORKSTATION_NAME, then the hostname)')
-        .description('Run the workstation daemon in the foreground (Docker ENTRYPOINT / debugging); subcommands manage the OS service')
+    const applyRd = deps.configureRd ?? configureRd;
+    const rejectSelectors = (options = {}) => {
+        const group = workstation.opts();
+        if (options.server !== undefined || options.name !== undefined || group.server !== undefined || group.name !== undefined || serverOption() !== undefined)
+            throw new UsageError('Workstation lifecycle commands apply to the whole device. Use `axom workstation add [address]` to add a server/account registration, or `axom workstation remove <registrationId>` to remove one.');
+    };
+    const removed = () => runCommand(async () => { throw new UsageError('This workstation command was removed. Use `axom workstation add [address]`, `list`, or `remove <registrationId>`; start/stop operate on the whole device.'); });
+    const dispatch = async (action, options, task, registrationId) => {
+        const target = registrationIdSchema.safeParse(registrationId);
+        const operation = { operationId: randomUUID(), registrationId: target.success ? target.data : null };
+        const captureOperationId = (value) => {
+            const parsed = operationIdSchema.safeParse(value);
+            if (!parsed.success)
+                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid workstation operation correlation ID');
+            operation.operationId = parsed.data;
+        };
+        if (!options.json) {
+            if (options.inputStdin)
+                throw new UsageError('--input-stdin requires --json');
+            if (options.operationId !== undefined)
+                captureOperationId(options.operationId);
+            await task(operation);
+            return;
+        }
+        try {
+            if (options.operationId !== undefined)
+                captureOperationId(options.operationId);
+            if (!options.inputStdin) {
+                await task(operation);
+                return;
+            }
+            const request = await readLocalRequest(process.stdin);
+            if (request && typeof request === 'object' && 'operationId' in request)
+                captureOperationId(request.operationId);
+            if (!request || typeof request !== 'object' || !('action' in request) || request.action !== action)
+                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Use a matching v2 device command request');
+            if (registrationId !== undefined && (!('guard' in request) || !request.guard || typeof request.guard !== 'object' || !('registrationId' in request.guard) || request.guard.registrationId !== registrationId))
+                throw new LocalControlError('BINDING_CONFLICT', 'The guarded removal must match the exact registration ID');
+            const result = await executeDeviceCommand(request, clientDir());
+            if (result.operationId !== operation.operationId)
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Original workstation operation reply does not match');
+            deps.log(JSON.stringify(deviceEventSchema.parse({ schemaVersion: 2, kind: 'result', operationId: result.operationId, result })));
+            if (result.status !== 'succeeded')
+                process.exitCode = 1;
+        }
+        catch (error) {
+            const code = error instanceof LocalControlError ? error.code : 'SERVICE_FAILED';
+            deps.log(JSON.stringify(deviceEventSchema.parse({ schemaVersion: 2, kind: 'result', operationId: operation.operationId, result: { operationId: operation.operationId, registrationId: operation.registrationId, status: code === 'BUSY' ? 'busy' : code === 'OUTCOME_UNKNOWN' ? 'pending' : ['BINDING_CONFLICT', 'OWNER_MISMATCH'].includes(code) ? 'conflict' : 'failed', inspection: null, error: { code, message: error instanceof LocalControlError ? error.message : 'The workstation operation could not be confirmed' } } })));
+            process.exitCode = 1;
+        }
+    };
+    workstation.command('list').description('List local workstation registrations and device state').option('--json', 'Emit the v2 device collection').action(options => runCommand(() => dispatch('inspect', options, () => registrations.list(options))));
+    workstation.command('add [address]').description('Add an exact server/account registration without changing ordinary CLI login').option('--name <name>', 'Workstation name').option('--json', 'Emit a v2 correlated result').option('--input-stdin', 'Read a protected v2 enrollment request from stdin').option('--operation-id <id>', 'Operation correlation ID').option('--owner <userId>', 'Require this account identity')
+        .action((address, options) => runCommand(() => dispatch('add-registration', options, operation => registrations.add({ ...options, operation, name: options.name ?? workstation.opts().name, server: address ?? serverOption(), expectedOwnerUserId: options.owner }))));
+    workstation.command('remove <registrationId>').description('Remove this exact local registration; busy resources require explicit --force').option('--force', 'Retire this registration’s resources').option('--json', 'Emit a v2 correlated result').option('--input-stdin', 'Read the original guarded v2 removal request from stdin').option('--operation-id <id>', 'Retry the original operation ID')
+        .action((id, options) => runCommand(() => dispatch('remove-registration', options, operation => registrations.remove(id, { ...options, operation }), id)));
+    for (const verb of ['start', 'stop', 'restart', 'install', 'uninstall']) {
+        const command = workstation.command(verb).description(`${verb} the whole-device service`).option('--name <name>', 'Removed selector; use workstation add').option('--server <url>', 'Removed selector; use workstation add').option('--json', 'Emit a v2 correlated result').option('--input-stdin', 'Read a guarded v2 whole-device request from stdin');
+        if (verb === 'start')
+            command.option('--enable-rd', 'Install and enable Linux remote desktop').option('--disable-rd', 'Disable remote desktop').option('--rd-session <mode>', 'Desktop selection: auto, existing, or virtual').option('--rd-display <display>', 'Choose a local X11 display');
+        command.action(options => runCommand(async () => {
+            rejectSelectors(options);
+            const rdOptions = { ...workstation.opts(), ...options };
+            const hasRd = rdOptions.enableRd || rdOptions.disableRd || rdOptions.rdSession || rdOptions.rdDisplay;
+            if (hasRd && (verb !== 'start' || options.json))
+                throw new UsageError('RD flags require a plain `axom workstation start` or foreground command');
+            if (options.json && !options.inputStdin)
+                throw new UsageError('--json requires --input-stdin for device lifecycle commands');
+            if (hasRd)
+                await applyRd(clientDir(), rdOptions);
+            await dispatch(verb, options, () => deps[verb]());
+        }));
+    }
+    workstation.command('status').description('Report the whole-device service status').action(() => runCommand(async () => { rejectSelectors(); deps.log(await deps.status()); }));
+    workstation.command('inspect').requiredOption('--json', 'Emit the v2 device collection').action(() => runCommand(async () => { deps.log(JSON.stringify(await inspectLocalDevice(clientDir()))); }));
+    for (const verb of ['auth', 'register', 'forget', 'begin-remove', 'adopt-owner', 'recover', 'set-enabled'])
+        workstation.command(verb, { hidden: true }).allowUnknownOption().allowExcessArguments().action(removed);
+    const rd = workstation.command('rd').description('Manage Linux remote desktop');
+    rd.command('status').action(() => runCommand(async () => { deps.log(JSON.stringify(await rdStatus(clientDir()), null, 2)); }));
+    rd.command('disable').action(() => runCommand(() => applyRd(clientDir(), { disableRd: true })));
+    workstation.option('--server <url>', 'Removed registration shortcut; use workstation add').option('--name <name>', 'Removed registration shortcut; use workstation add')
+        .option('--enable-rd', 'Install and enable Linux remote desktop').option('--disable-rd', 'Disable remote desktop').option('--rd-session <mode>', 'Desktop selection: auto, existing, or virtual').option('--rd-display <display>', 'Choose a local X11 display')
         .action((options) => runCommand(async () => {
-        await ensureRegistered(deps, options.server ?? serverOption(), options.name);
-        dropAccessTokenFromEnvironment();
+        rejectSelectors(options);
+        await applyRd(clientDir(), options);
+        delete process.env.AXOM_ACCESS_TOKEN;
         await deps.runDaemon({ supervision: deps.detectSupervision() });
     }));
-    program.command('__daemon', { hidden: true }).action(() => runCommand(async () => {
-        // The literal exec target launchd/systemd start: the one call site allowed to opt into
-        // OS-service treatment. See RunDaemonOptions in daemon.ts for why this must be an explicit
-        // flag rather than "no `supervision` was passed".
-        //
-        // Same reasoning as the bare command's call: this process is about to become the daemon that
-        // spawns agents and shell commands with its own environment. A service definition is not
-        // supposed to carry AXOM_ACCESS_TOKEN at all, which makes this usually a no-op — and exactly
-        // why it belongs here rather than being left to whoever writes the next plist.
-        dropAccessTokenFromEnvironment();
-        await deps.runDaemon({ supervisedByServiceManager: true });
-    }));
+    program.command('__rd-desktop', { hidden: true }).requiredOption('--directory <path>').action((options) => runCommand(async () => { delete process.env.AXOM_ACCESS_TOKEN; await runManagedDesktop(options.directory); }));
+    program.command('__daemon', { hidden: true }).action(() => runCommand(async () => { delete process.env.AXOM_ACCESS_TOKEN; await deps.runDaemon({ supervisedByServiceManager: true }); }));
 }

package/dist/commands/workstationRegistrations.js

@@ -0,0 +1,116 @@
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { basename } from 'node:path';
+import { loadConfig } from '../config.js';
+import { peekAccessToken, revokeRefreshToken } from '../credentials.js';
+import { resolveAuthServer } from './auth.js';
+import { clientDir } from '../workstation/config.js';
+import { executeDeviceCommand, inspectLocalDevice } from '../workstation/control/deviceCommands.js';
+import { deviceEventSchema, deviceResultSchema, parseDeviceInspection } from '../workstation/control/deviceProtocol.js';
+import { LocalControlError } from '../workstation/control/protocol.js';
+import { normalizeWorkstationServer } from '../workstation/control/serverIdentity.js';
+import { verifyRegistrationAuthority } from '../workstation/registrations/enrollment.js';
+import { authorizeDevice } from '../workstation/oauth/deviceAuthorization.js';
+import { resolveWorkstationName, sanitizeName } from '../workstation/names.js';
+import { operationIdSchema } from '../workstation/registrations/enrollmentPending.js';
+import { registrationIdSchema } from '../workstation/registrations/model.js';
+const defaults = {
+    inspect: () => inspectLocalDevice(clientDir()), execute: request => executeDeviceCommand(request, clientDir()),
+    authority: verifyRegistrationAuthority, authorize: authorizeDevice, revoke: revokeRefreshToken, log: console.log,
+};
+export async function resolveWorkstationAddServer(explicit) {
+    return resolveAuthServer(await loadConfig(), explicit);
+}
+function printResult(result, options, log) {
+    result = deviceResultSchema.parse(result);
+    if (options.json)
+        log(JSON.stringify(deviceEventSchema.parse({ schemaVersion: 2, kind: 'result', operationId: result.operationId, result })));
+    else
+        log(`${result.status}: ${result.registrationId ?? 'device'} (operation ${result.operationId})${result.error ? ` — ${result.error.code}: ${result.error.message}` : ''}`);
+    if (result.status !== 'succeeded')
+        process.exitCode = 1;
+}
+export async function listWorkstationRegistrations(options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const inspection = parseDeviceInspection(await deps.inspect());
+    if (options.json) {
+        deps.log(JSON.stringify(inspection));
+        return;
+    }
+    deps.log(`Workstation device: ${inspection.runtime.state}`);
+    if (!inspection.registrations.length)
+        deps.log('No workstation registrations. Use `axom workstation add [address]`.');
+    for (const registration of inspection.registrations)
+        deps.log(`${registration.id}\t${registration.server}\taccount=${registration.ownerUserId}\tworkstation=${registration.workstationId}\t${registration.connection}\t${registration.identityState}\t${registration.removalState}`);
+    for (const pending of inspection.pending)
+        deps.log(`pending: ${pending.id}\t${pending.kind}\t${pending.registrationId ?? 'device'}\t${pending.phase}\t${pending.outcome}`);
+}
+export async function addWorkstationRegistration(options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const operation = options.operation ?? { operationId: operationIdSchema.parse(options.operationId ?? randomUUID()), registrationId: null };
+    const server = normalizeWorkstationServer(await resolveWorkstationAddServer(options.server));
+    const before = parseDeviceInspection(await deps.inspect());
+    if (before.runtime.state === 'unknown')
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Verify the workstation owner before adding a registration');
+    const operationId = operationIdSchema.parse(operation.operationId);
+    const hasExplicitAccessToken = Boolean(process.env.AXOM_ACCESS_TOKEN?.trim());
+    let token = await peekAccessToken(server);
+    let ownerUserId;
+    if (token) {
+        try {
+            ownerUserId = await deps.authority({ server, accessToken: token, expectedOwnerUserId: options.expectedOwnerUserId });
+        }
+        catch (error) {
+            if (!(error instanceof LocalControlError))
+                throw error;
+            if (error.code !== 'AUTHORIZATION_REQUIRED' && (error.code !== 'OWNER_MISMATCH' || hasExplicitAccessToken))
+                throw error;
+            token = undefined;
+        }
+    }
+    let issued;
+    try {
+        if (!token) {
+            if (!options.json)
+                deps.log('Workstation permission needs a separate approval; unavailable or expired ordinary access credentials are left unchanged.');
+            const host = hostname();
+            issued = await deps.authorize(server, `Axomwork workstation (${host})`, host, { print: message => { process.stderr.write(message + '\n'); } }, ['workstation'], Object.freeze({ deviceId: `workstation-${randomUUID()}` }));
+            token = issued.accessToken;
+            ownerUserId = await deps.authority({ server, accessToken: token, expectedOwnerUserId: options.expectedOwnerUserId });
+        }
+        const cwd = process.cwd();
+        const result = await deps.execute({ schemaVersion: 2, action: 'add-registration', operationId,
+            guard: { deviceRevision: before.deviceRevision, runtimeGeneration: before.runtime.generation },
+            input: { operationId, server, accessToken: token, expectedOwnerUserId: ownerUserId, defaults: { name: resolveWorkstationName(options.name, process.env, hostname()), shell: process.env.SHELL ?? '/bin/sh', workspace: { name: sanitizeName(basename(cwd), 'default'), cwd, shell: process.env.SHELL ?? '/bin/sh' } } },
+        });
+        printResult(result, options, deps.log);
+    }
+    finally {
+        if (issued)
+            await deps.revoke(server, issued.refreshToken);
+    }
+}
+export async function removeWorkstationRegistration(id, options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const operation = options.operation ?? { operationId: operationIdSchema.parse(options.operationId ?? randomUUID()), registrationId: null };
+    const target = registrationIdSchema.safeParse(id);
+    if (!target.success) {
+        operation.registrationId = null;
+        throw new LocalControlError('BINDING_CONFLICT', 'Invalid registration ID; use `axom workstation list`');
+    }
+    operation.registrationId = target.data;
+    const before = parseDeviceInspection(await deps.inspect());
+    const registration = before.registrations.find(candidate => candidate.id === id);
+    if (!registration)
+        throw new LocalControlError('BINDING_CONFLICT', 'No registration matches that exact ID; use `axom workstation list`');
+    const pending = before.pending.find(operation => operation.kind === 'remove' && operation.registrationId === id);
+    const operationId = operationIdSchema.parse(options.operationId ?? pending?.id ?? operation.operationId);
+    operation.operationId = operationId;
+    if (before.runtime.state !== 'running' || before.runtime.generation === null) {
+        printResult({ operationId, registrationId: id, status: 'pending', inspection: before, error: { code: 'OUTCOME_UNKNOWN', message: pending ? 'Original removal authority is unavailable; preserve its pending operation and data for verification' : 'Removal needs the authenticated running device owner; start the device, inspect, and retry' } }, options, deps.log);
+        return;
+    }
+    printResult(await deps.execute({ schemaVersion: 2, action: 'remove-registration', operationId, force: options.force === true,
+        guard: { deviceRevision: before.deviceRevision, runtimeGeneration: before.runtime.generation, registrationId: id, registrationRevision: registration.revision },
+    }), options, deps.log);
+}

package/dist/credentialBroker.js

@@ -30,9 +30,17 @@ export async function requestCredentialBroker(request) {
             return await sendRequest(brokerRequest, controller.signal);
         }
         catch (error) {
-            if (error instanceof BrokerOperationError)
+            if (error instanceof BrokerOperationError) {
+                if (request.action === 'peek' && error.message === 'Unsupported credential broker operation.')
+                    return { ok: true, version: PROTOCOL_VERSION };
                 throw error;
+            }
             throwIfAborted(controller.signal);
+            if (request.action === 'peek') {
+                if (['ENOENT', 'ECONNREFUSED'].includes(error.code ?? ''))
+                    return { ok: true, version: PROTOCOL_VERSION };
+                throw error;
+            }
             await installAndStartBroker(controller.signal);
             let lastError;
             for (let attempt = 0; attempt < 20; attempt += 1) {
@@ -129,6 +137,9 @@ async function handleRequest(raw, connection, credentials) {
             const accessToken = await credentials.accessTokenFromNativeStore(request.server, request.forceRefresh);
             response = { ok: true, accessToken, version: PROTOCOL_VERSION };
         }
+        else if (request.action === 'peek') {
+            response = { ok: true, accessToken: credentials.peekNativeAccessToken(request.server), version: PROTOCOL_VERSION };
+        }
         else if (request.action === 'revoke') {
             const persisted = await credentials.loadNativeTokens(request.server);
             if (persisted?.refreshToken)
@@ -319,7 +330,7 @@ function parseRequest(raw) {
     const request = JSON.parse(raw);
     if (request.version !== PROTOCOL_VERSION)
         throw new Error('Unsupported credential broker protocol version.');
-    if (request.action !== 'save' && request.action !== 'access' && request.action !== 'clear' && request.action !== 'revoke') {
+    if (request.action !== 'save' && request.action !== 'access' && request.action !== 'clear' && request.action !== 'revoke' && request.action !== 'peek') {
         throw new Error('Unsupported credential broker operation.');
     }
     if (typeof request.server !== 'string' || !request.server)