@platless/axom-cli 0.6.36 → 0.6.52

package/dist/commands/workstation.js

@@ -1,237 +1,108 @@
-import { assertIdentityCanStart, recoverStoppedIdentity } from '../workstation/control/daemonIdentity.js';
-import { withWorkstationLock } from '../workstation/control/locks.js';
-import { inspectWorkstation } from '../workstation/control/inspect.js';
-import { runLocalJsonCommand } from '../workstation/control/commands.js';
-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';
+import { clientDir } from '../workstation/config.js';
 import { configureRd, rdStatus } from '../workstation/rd/control.js';
 import { runManagedDesktop } from '../workstation/rd/sessions.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 { 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 localJson = deps.localJson ?? runLocalJsonCommand;
-    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();
     const applyRd = deps.configureRd ?? configureRd;
-    workstation
-        .command('start')
-        .option('--json', 'Emit local management protocol JSON')
-        .option('--input-stdin', 'Read the guarded request from stdin')
-        .option('--server <url>', 'Axomwork server URL to register this workstation against')
-        .option('--name <name>', 'Workstation name (default: AXOM_WORKSTATION_NAME, then the hostname)')
-        .option('--enable-rd', 'Install and enable Linux remote desktop')
-        .option('--disable-rd', 'Disable remote desktop without changing workstation registration')
-        .option('--rd-session <mode>', 'Desktop selection: auto, existing, or virtual')
-        .option('--rd-display <display>', 'Choose an existing local X11 display, such as :10')
-        .description('Start the workstation user service')
-        .action((options) => runCommand(async () => {
-        const rd = { ...workstationOption(), ...options, server: options.server ?? workstationOption().server ?? serverOption() };
-        if (options.json && (rd.enableRd || rd.disableRd || rd.rdSession || rd.rdDisplay))
-            throw new UsageError('RD flags cannot be combined with the JSON management protocol');
-        if (options.json) {
-            if (!options.inputStdin)
-                throw new UsageError('--json requires --input-stdin');
-            await localJson('start');
+    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;
         }
-        await applyRd(clientDir(), rd);
-        // `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.
-        await withWorkstationLock(clientDir(), 'operation', async () => { await recoverStoppedIdentity(clientDir()); await assertIdentityCanStart(clientDir()); });
-        const justRegistered = await ensureRegistered(deps, options.server ?? workstationOption().server ?? serverOption(), options.name ?? workstationOption().name);
-        await withWorkstationLock(clientDir(), 'operation', async () => { await assertIdentityCanStart(clientDir()); if (justRegistered)
-            await deps.install(); await deps.start(); });
-    }));
-    workstation
-        .command('stop')
-        .option('--json', 'Emit local management protocol JSON')
-        .option('--input-stdin', 'Read the guarded request from stdin')
-        .description('Stop the workstation user service')
-        .action((options) => runCommand(async () => { if (options.json) {
-        if (!options.inputStdin)
-            throw new UsageError('--json requires --input-stdin');
-        await localJson('stop');
-    }
-    else
-        await withWorkstationLock(clientDir(), 'operation', () => deps.stop()); }));
-    workstation
-        .command('restart')
-        .option('--json', 'Emit local management protocol JSON')
-        .option('--input-stdin', 'Read the guarded request from stdin')
-        .description('Restart the workstation user service')
-        .action((options) => runCommand(async () => { if (options.json) {
-        if (!options.inputStdin)
-            throw new UsageError('--json requires --input-stdin');
-        await localJson('restart');
-    }
-    else
-        await withWorkstationLock(clientDir(), 'operation', async () => { await recoverStoppedIdentity(clientDir()); await assertIdentityCanStart(clientDir()); 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')
-        .option('--json', 'Emit local management protocol JSON')
-        .option('--input-stdin', 'Read the guarded request from stdin')
-        .description('Install and enable the operating-system service')
-        .action((options) => runCommand(async () => { if (options.json) {
-        if (!options.inputStdin)
-            throw new UsageError('--json requires --input-stdin');
-        await localJson('install');
-    }
-    else
-        await withWorkstationLock(clientDir(), 'operation', async () => { await recoverStoppedIdentity(clientDir()); await assertIdentityCanStart(clientDir()); await deps.install(); }); }));
-    workstation
-        .command('uninstall')
-        .description('Disable and remove the operating-system service')
-        .action(() => runCommand(async () => { await withWorkstationLock(clientDir(), 'operation', () => deps.uninstall()); }));
-    workstation.command('inspect').requiredOption('--json', 'Emit local management protocol JSON')
-        .action(() => runCommand(async () => { process.stdout.write(JSON.stringify(await inspectWorkstation(clientDir())) + '\n'); }));
-    workstation.command('set-enabled').description('Persistently enable or disable this workstation service')
-        .requiredOption('--json').requiredOption('--input-stdin').action(() => localJson('set-enabled'));
-    for (const verb of ['register', 'forget', 'begin-remove', 'adopt-owner', 'recover']) {
-        workstation.command(verb, { hidden: verb === 'forget' }).requiredOption('--json', 'Emit local management protocol JSON')
-            .requiredOption('--input-stdin', 'Read the guarded request from stdin').action(() => localJson(verb));
+        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]());
+        }));
     }
-    const rd = workstation.command('rd').description('Manage Linux remote desktop independently of the workstation service');
+    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(async () => { await applyRd(clientDir(), { disableRd: true }); }));
-    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)')
-        .option('--enable-rd', 'Install and enable Linux remote desktop')
-        .option('--disable-rd', 'Disable remote desktop without changing workstation registration')
-        .option('--rd-session <mode>', 'Desktop selection: auto, existing, or virtual')
-        .option('--rd-display <display>', 'Choose an existing local X11 display, such as :10')
-        .description('Run the workstation daemon in the foreground (Docker ENTRYPOINT / debugging); subcommands manage the OS service')
+    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 applyRd(clientDir(), { ...options, server: options.server ?? serverOption() });
-        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('__rd-desktop', { hidden: true }).requiredOption('--directory <path>')
-        .action((options) => runCommand(async () => { dropAccessTokenFromEnvironment(); await runManagedDesktop(options.directory); }));
-    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)

package/dist/credentials.js

@@ -34,6 +34,22 @@ export async function accessTokenFor(server, forceRefresh = false) {
     }
     return accessTokenFromNativeStore(server, forceRefresh);
 }
+export function peekNativeAccessToken(server) {
+    const cached = accessCache.get(server);
+    return cached?.accessToken && Date.parse(cached.expiresAt) - Date.now() >= 30_000 ? cached.accessToken : undefined;
+}
+export async function peekAccessToken(server) {
+    const fromEnv = process.env.AXOM_ACCESS_TOKEN?.trim();
+    if (fromEnv)
+        return fromEnv;
+    if (usesTestMemoryStore()) {
+        const cached = memoryStore.get(server);
+        return cached?.accessToken && Date.parse(cached.expiresAt) - Date.now() >= 30_000 ? cached.accessToken : undefined;
+    }
+    if (process.platform === 'darwin')
+        return (await requestCredentialBroker({ action: 'peek', server })).accessToken;
+    return peekNativeAccessToken(server);
+}
 export async function clearTokens(server) {
     if (usesTestMemoryStore()) {
         memoryStore.delete(server);

package/dist/install/claude/commands.js

@@ -41,8 +41,8 @@ $ARGUMENTS
 Workflow:
 1. Find the operation on its model (\`axom__app_struct__get_model\`) or the service by name.
 2. Call \`axom__execute__run_operation\` (applicationName/modelName/operationName/input) or \`axom__execute__run_service\` (serviceName/input).
-3. Interpret the ExecuteResult payload: \`status\` (success/failure/running), \`message\`, \`text\`, \`returnValue\`, \`runId\`/\`runType\`, \`errors[]\` ({target,code,message}).
-4. When \`status\` is \`running\`, follow \`runId\` (see \`runType\`) until a terminal state before reporting the outcome.
+3. Interpret the ExecuteResult payload: \`status\` (success/failure/running), \`message\`, \`text\`, \`returnValue\`, \`workId\`/\`workKind\`, \`errors[]\` ({target,code,message}).
+4. When \`status\` is \`running\`, follow \`workId\` (see \`workKind\`) until a terminal state before reporting the outcome.
 
 For sync-vs-job semantics see knowledge page \`concepts/execution/synchronous-and-task-execution.md\`; for run following see knowledge page \`agent-integration/operating-patterns/following-runs.md\`.
 `,