@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/agentSessions.js

@@ -5,6 +5,7 @@ import { SESSION_WINDOW_BYTES, SESSION_WINDOW_EVENTS } from './acp/outbox.js';
 import { SocketGate } from './agentFlow.js';
 import { AGENT_PROBE_TIMEOUT_MS, AgentRefusedSessionError, LOCAL_SESSION_UNMOVABLE } from './acp/acpAgents.js';
 import { projectFrame } from './acp/processor/projection.js';
+import { TaskRegistry } from './update/taskRegistry.js';
 import { reportsActivity, supportsAsyncTaskStop } from './acp/activityReporting.js';
 import { activityIsBusy } from './acp/activityBusy.js';
 import { ADAPTER_LOST_REOPEN_ATTEMPTS, plainSwitchBlocker, REOPEN_REQUEST_RETRY_MS, switchBlockers, SWITCH_QUIET_MS } from './acp/switching.js';
@@ -230,6 +231,8 @@ export class AgentSessionManager {
     agents;
     journalDir;
     tasks;
+    admission;
+    ownership;
     sessions = new Map();
     /** A failed recorded-build respawn keeps this binding even after no LiveSession remains. */
     retainedRespawnBuilds = new Map();
@@ -338,10 +341,12 @@ export class AgentSessionManager {
     /** `<configDir>/agents`: the legacy journals (`sessions/<ref>.jsonl`) an older CLI left are migrated from here, once. */
     journalDir, 
     /** Shared update admission and force-cancellation authority, when this daemon supports updates. */
-    tasks) {
+    tasks, admission = () => true, ownership) {
         this.agents = agents;
         this.journalDir = journalDir;
         this.tasks = tasks;
+        this.admission = admission;
+        this.ownership = ownership;
         this.send = send;
     }
     /** Where an older CLI's journals live: `<journalDir>/sessions/<sessionRef>.jsonl` (read-only legacy, `journal.ts`). */
@@ -369,7 +374,7 @@ export class AgentSessionManager {
             }
             for (const sessionRef of refs) {
                 try {
-                    const entries = await readLegacyJournal(this.sessionsDir, sessionRef);
+                    const entries = await readLegacyJournal(this.sessionsDir, sessionRef, this.ownership);
                     const imported = await importOutbox(sessionRef, entries.map((entry) => ({
                         seq: entry.seq,
                         ...(entry.src ? { src: entry.src } : {}),
@@ -560,7 +565,7 @@ export class AgentSessionManager {
         this.send = send;
         this.serverAgentWire = serverAgentWire;
         // A new connection: its own window and socket. What was sent on the previous one waits for the server's reopen to say how far
-        // it got; what was never sent goes out now.
+        // it got. An already-exited adapter's recovered turn is replayed in full to finish it before reopen.
         this.epoch += 1;
         for (const live of this.sessions.values())
             live.session.outbox.connectionChanged();
@@ -568,6 +573,9 @@ export class AgentSessionManager {
         // Before any inbound frame on this connection can be answered: a sweep notice that arrived here
         // after the server had already re-opened its ref would invalidate a healthy generation.
         this.flushSwept();
+        for (const live of this.sessions.values())
+            if (live.replayDeadTail)
+                live.session.outbox.resendAll();
         this.pump();
         // Account observations are outside the session journal. Replay the cached state on reconnect
         // so a server restart does not depend on the provider sending another quota notification.
@@ -738,12 +746,17 @@ export class AgentSessionManager {
                 highestScopedJournalSeq = Math.max(highestScopedJournalSeq, item.seq);
         }
         const live = {
-            sessionRef: candidate.sessionRef, adopted: true, agentId: candidate.agentId, agentKey: candidate.agentKey, session,
+            sessionRef: candidate.sessionRef, adopted: true, replayDeadTail: candidate.agentAlive === false, agentId: candidate.agentId, agentKey: candidate.agentKey, session,
             nativeSessionId: session.nativeSessionId ?? null,
             scopedReplayBlocked: false, highestScopedJournalSeq, unwatch: () => { }, replays: Promise.resolve(), closed: false,
             lastActivityAt: Date.now(),
         };
-        this.register(live);
+        this.register(live, this.adoptionOrigin);
+        // An exited adapter is adopted only to finish its recovered turn. Release its entire retained
+        // prefix in order so that tail can settle the server's turn before a reopen respawns the adapter.
+        // Live adapters retain the ordinary reopen/watermark gate.
+        if (live.replayDeadTail)
+            live.session.outbox.resendAll();
         console.info(`[acp:${live.agentId} agent:${live.agentKey}] adopted session ${live.sessionRef} from keeper-acp`);
     }
     /** Waits (bounded) for the start-time adoption; what is still rebuilding afterwards is reported as such. */
@@ -778,6 +791,23 @@ export class AgentSessionManager {
         clearTimeout(timer);
     }
     async handleFrame(frame) {
+        const live = 'sessionRef' in frame && typeof frame.sessionRef === 'string' ? this.liveSession(frame.sessionRef) : undefined;
+        const openContinuation = frame.t === 'agent_open' && ((live && !this.needsRespawn(live)) || this.opening.has(frame.sessionRef) || this.adopting.has(frame.sessionRef));
+        const newWork = !openContinuation && ['agent_open', 'agent_prompt', 'agent_list_native', 'agent_delete_native', 'agent_account_read', 'agent_verify', 'agent_authenticate', 'agent_install', 'agent_switch_idle'].includes(frame.t);
+        const registry = this.tasks ?? this.acceptedTasks;
+        const ticket = newWork && this.admission() ? registry.beginAcceptedAgentWork(frame.t, frame, frame.t === 'agent_prompt' ? this.adoptionOrigin : undefined) : null;
+        const admitted = (!newWork && (frame.t !== 'agent_open' || this.admission())) || ticket !== null;
+        try {
+            await this.handleAcceptedFrame(frame, ticket, admitted, registry);
+        }
+        finally {
+            if (ticket)
+                registry.finishAcceptedAgentWork(ticket);
+        }
+    }
+    acceptedTasks = new TaskRegistry();
+    adoptionOrigin = {};
+    async handleAcceptedFrame(frame, ticket, admitted, registry) {
         // A frame for a ref keeper-acp still runs from a previous daemon waits until that session is rebuilt (Task 21): answering
         // it "unknown session" would end a turn that is going on.
         const frameRef = 'sessionRef' in frame && typeof frame.sessionRef === 'string' ? frame.sessionRef : undefined;
@@ -792,7 +822,7 @@ export class AgentSessionManager {
             await parked;
         switch (frame.t) {
             case 'agent_open': {
-                const admission = this.reserveOpen(frame.id, frame.sessionRef);
+                const admission = this.reserveOpen(frame, ticket, admitted, registry);
                 if (admission === 'rejected')
                     return;
                 const ref = frame.sessionRef;
@@ -802,7 +832,7 @@ export class AgentSessionManager {
                 }
                 finally {
                     if (admission === 'reserved')
-                        this.tasks?.agentOpenFinished(ref);
+                        registry.agentOpenFinished(ref);
                     const left = (this.openHandling.get(ref) ?? 1) - 1;
                     if (left > 0)
                         this.openHandling.set(ref, left);
@@ -818,7 +848,7 @@ export class AgentSessionManager {
                 const live = this.routableSession(frame.sessionRef, 'prompt');
                 if (!live)
                     return;
-                if (this.tasks && !this.tasks.tryAdmitTurn(frame.sessionRef)) {
+                if (!admitted) {
                     // The refusal is the daemon's decision, so it is a note (`agent_prompt{admitted:false}`) and the processor ends the
                     // turn `failed` with the same words (`ADMISSION_REFUSED`), numbered in the session's own sequence (spec §5.4). No
                     // `authMethods`: the processor's short frame carries no `agentRefused`, so the projection adds none — the prompt
@@ -826,6 +856,14 @@ export class AgentSessionManager {
                     live.session.refusePrompt(frame.platformTurnId);
                     return;
                 }
+                if (ticket)
+                    try {
+                        registry.consumeAcceptedAgentWork(ticket, frame.t, frame);
+                    }
+                    catch {
+                        live.session.refusePrompt(frame.platformTurnId);
+                        return;
+                    }
                 live.session.prompt(promptBlocks(frame), frame.platformTurnId);
                 return;
             }
@@ -963,6 +1001,10 @@ export class AgentSessionManager {
              * keep holding that row or to deliver it the ordinary way. A silent drop parks it forever.
              */
             case 'agent_steer': {
+                if (!this.admission()) {
+                    this.emit({ t: 'agent_steered', id: frame.id, ok: false, error: 'Registration admission is paused' });
+                    return;
+                }
                 const live = this.routableSession(frame.sessionRef, 'steer');
                 if (!live) {
                     this.emit({ t: 'agent_steered', id: frame.id, ok: false, error: `no live session '${frame.sessionRef}'` });
@@ -1004,6 +1046,10 @@ export class AgentSessionManager {
              * a request that never resolves.
              */
             case 'agent_set_config_option': {
+                if (!this.admission()) {
+                    this.emit({ t: 'agent_config_option_set', id: frame.id, ok: false, error: 'Registration admission is paused' });
+                    return;
+                }
                 const live = this.routableSession(frame.sessionRef, 'set_config_option');
                 if (!live) {
                     this.emit({ t: 'agent_config_option_set', id: frame.id, ok: false, error: `no live session '${frame.sessionRef}'` });
@@ -1039,14 +1085,14 @@ export class AgentSessionManager {
                 return;
             }
             case 'agent_list_native':
-                if (this.tasks && !this.tasks.accepting) {
+                if (!admitted) {
                     this.emit({ t: 'agent_native_sessions', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
                     return;
                 }
                 await this.onListNative(frame);
                 return;
             case 'agent_delete_native':
-                if (this.tasks && !this.tasks.accepting) {
+                if (!admitted) {
                     this.emit({ t: 'agent_native_deleted', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
                     return;
                 }
@@ -1055,7 +1101,7 @@ export class AgentSessionManager {
             // Both of these spawn an agent subprocess, exactly as `agent_list_native` does, so they answer
             // a draining workstation the same way rather than starting work it is trying to finish.
             case 'agent_account_read': {
-                if (this.tasks && !this.tasks.accepting) {
+                if (!admitted) {
                     this.emit({ t: 'agent_account_read_result', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
                     return;
                 }
@@ -1077,14 +1123,14 @@ export class AgentSessionManager {
                 return;
             }
             case 'agent_verify':
-                if (this.tasks && !this.tasks.accepting) {
+                if (!admitted) {
                     this.emit({ t: 'agent_verified', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
                     return;
                 }
                 await this.onVerify(frame);
                 return;
             case 'agent_authenticate':
-                if (this.tasks && !this.tasks.accepting) {
+                if (!admitted) {
                     this.emit({ t: 'agent_authenticated', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
                     return;
                 }
@@ -1093,7 +1139,7 @@ export class AgentSessionManager {
             // Downloads a package; starts nothing. Still refused while draining, because a workstation on
             // its way down should not begin a multi-megabyte fetch it will be killed in the middle of.
             case 'agent_install':
-                if (this.tasks && !this.tasks.accepting) {
+                if (!admitted) {
                     this.emit({ t: 'agent_installed', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
                     return;
                 }
@@ -1101,7 +1147,7 @@ export class AgentSessionManager {
                 return;
             // "Move idle sessions" (Task 25): a move spawns adapters, so a draining workstation refuses it like an install.
             case 'agent_switch_idle':
-                if (this.tasks && !this.tasks.accepting) {
+                if (!admitted) {
                     this.emit({ t: 'agent_switch_idle_result', id: frame.id, ok: false, error: 'Workstation is not accepting new work' });
                     return;
                 }
@@ -1149,24 +1195,31 @@ export class AgentSessionManager {
      * stop leaves attached. A ref absent from both maps is genuinely new work and still needs
      * the ordinary TaskRegistry admission reservation.
      */
-    reserveOpen(openId, sessionRef) {
-        if (!this.tasks)
-            return 'continuation';
+    reserveOpen(frame, ticket, admitted, registry) {
+        const { id: openId, sessionRef } = frame;
+        if (!admitted) {
+            this.emit({ t: 'agent_opened', id: openId, ok: false, error: 'Workstation is not accepting new work' });
+            return 'rejected';
+        }
         const live = this.liveSession(sessionRef);
         // A keeper-hosted session whose adapter is gone is respawned by this open: new work, not a continuation — it takes a reservation,
         // and a draining workstation refuses it like any open (spec §8.2; fix round 1, minor 9).
         const respawn = live !== undefined && this.needsRespawn(live);
-        if (this.tasks.isForceStopping()) {
+        if (registry.isForceStopping()) {
             // A keeper-hosted session a force update left attached (TaskRegistry.stopAll) is still reopened as a continuation — a reconnect
             // during the download must not cut it off; anything else is refused.
-            if (live && !respawn && this.tasks.isDurableSession(sessionRef))
+            if (live && !respawn && registry.isDurableSession(sessionRef))
                 return 'continuation';
             this.emit({ t: 'agent_opened', id: openId, ok: false, error: 'Workstation is not accepting new work' });
             return 'rejected';
         }
         if ((live && !respawn) || this.opening.has(sessionRef) || this.adopting.has(sessionRef))
             return 'continuation';
-        if (this.tasks.tryReserveAgentOpen(sessionRef))
+        if (ticket) {
+            registry.reserveAcceptedAgentOpen(ticket, frame);
+            return 'reserved';
+        }
+        if (registry.tryReserveAgentOpen(sessionRef))
             return 'reserved';
         this.emit({ t: 'agent_opened', id: openId, ok: false, error: 'Workstation is not accepting new work' });
         return 'rejected';
@@ -2241,7 +2294,7 @@ export class AgentSessionManager {
         return { live };
     }
     /** A session joins: held, registered with the TaskRegistry, its frames and its outbox wired to the sender. */
-    register(live) {
+    register(live, adoption) {
         const session = live.session;
         this.detached.delete(live.sessionRef);
         this.sessions.set(live.sessionRef, live);
@@ -2251,7 +2304,7 @@ export class AgentSessionManager {
         () => this.retire(live, durable ? 'detach' : 'destroy'), 
         // 两个层级量取或：本进程发出的提示词是否在途（agent 自己也许在续跑一个我们没发起的回合，
         // 那一种由第二项回答），以及 agent 自报的状态。两者都不累积，所以没有可泄漏的状态。
-        () => live.session.liveness.turnRunning || activityIsBusy(live.session.activityRaw), { durable });
+        () => live.session.liveness.turnRunning || activityIsBusy(live.session.activityRaw), { durable, adoption });
         // Everything the session produces arrives as processor frames (Task 19): numbered by the processor, projected for the
         // connected server here, recorded in the outbox (the numbered ones) and sent from it (Task 20).
         live.unwatch = session.outbox.onChange(() => this.pump());

package/dist/workstation/channels/agent.js

@@ -3,6 +3,7 @@ import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
 import { AGENT_WIRE_MIN_VERSION, AGENT_WIRE_RESUME_OFFER_VERSION, AGENT_WIRE_VERSION, decodeAgentFrame, encodeAgentFrame, outboundAgentFrameRejection, } from '../protocol/agent.js';
 import { bridgesForWire, helloRoster } from '../protocol/common.js';
 import { workstationChannelUrl } from './url.js';
+import { DeviceEventRouter } from '../runtime/events.js';
 /** Binds daemon-scoped sessions only to the encrypted agent channel's sender. */
 export class AgentChannel {
     options;
@@ -24,7 +25,14 @@ export class AgentChannel {
         });
         // Hoisted rather than inlined twice: `closeAll` compares it by identity to decide whether the
         // binding it is being asked to drop is still this connection's. See AgentSessionManager.closeAll.
-        const send = (frame) => channel.send(frame);
+        const registrationId = this.options.registrationId;
+        const events = registrationId ? new DeviceEventRouter((_recipient, event) => channel.send(event.payload), new Set([registrationId])) : undefined;
+        const send = (frame) => {
+            if (events && registrationId)
+                events.publish({ scope: 'registration', registrationId, payload: frame });
+            else
+                channel.send(frame);
+        };
         // The socket's unsent bytes: the manager's socket gate holds session frames back above 1 MiB so the heartbeat (written by the
         // channel itself) never queues behind a backlog (spec §5.6).
         void dispatchAgentChannelFrames(channel.messages, send, this.options.agents, () => channel.close(), () => channel.bufferedAmount);

package/dist/workstation/channels/computer.js

@@ -11,7 +11,8 @@ import { TaskRegistry } from '../update/taskRegistry.js';
 import { toFileError } from '../files/errors.js';
 import { object } from '../tools/validation.js';
 import { isUnaccountedTool } from '../tools/router.js';
-import { requestRootFileExecutors } from '../files/adapters/computerFileFrames.js';
+import { requestRootFileExecutors, fileErrorFrame } from '../files/adapters/computerFileFrames.js';
+import { DeviceEventRouter } from '../runtime/events.js';
 /**
  * Consumes computer frames without serializing long-running commands behind one another.
  * All command failures and post-close sends are contained here because this is called detached
@@ -211,6 +212,20 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
     };
     try {
         for await (const frame of messages) {
+            if (durable.admission?.() === false) {
+                if (frame.t === 'exec_request') {
+                    safeSend({ t: 'exec_exit', id: frame.id, exitCode: null, stdout: '', stderr: 'Registration admission is paused', timedOut: false, truncated: false });
+                    continue;
+                }
+                if (frame.t === 'tool_request' && frame.method !== 'tools.info') {
+                    safeSend({ t: 'tool_result', id: frame.id, ok: false, result: {}, error: 'Registration admission is paused' });
+                    continue;
+                }
+                if (frame.t === 'file_write_request' || frame.t === 'file_mkdir_request') {
+                    safeSend(fileErrorFrame(frame, { code: 'workstation_offline', message: 'Registration admission is paused' }));
+                    continue;
+                }
+            }
             if (frame.t.startsWith('desktop_'))
                 desktop?.onFrame(frame);
             else if (frame.t === 'tool_request')
@@ -279,9 +294,17 @@ export class ComputerChannel {
         return { closed: channel.closed, close: () => channel.close() };
     }
     async dispatch(channel) {
-        const desktop = new DesktopBridge(resolveBrowserBinding(this.options.browserBinding), frame => channel.send(frame), () => channel.bufferedAmount);
-        await dispatchComputerFrames(channel.messages, (frame) => channel.send(frame), this.options.runExec ?? ((request, onOutput, signal) => runExec(request, onOutput, signal)), this.tasks, this.options, this.tools, desktop, {
-            host: this.execs, bufferedAmount: () => channel.bufferedAmount, log: this.options.log,
+        const registrationId = this.options.registrationId;
+        const events = registrationId ? new DeviceEventRouter((_recipient, event) => channel.send(event.payload), new Set([registrationId])) : undefined;
+        const send = (frame) => {
+            if (events && registrationId)
+                events.publish({ scope: 'registration', registrationId, payload: frame });
+            else
+                channel.send(frame);
+        };
+        const desktop = new DesktopBridge(this.options.desktopEnabled === false ? undefined : resolveBrowserBinding(this.options.browserBinding), frame => channel.send(frame), () => channel.bufferedAmount);
+        await dispatchComputerFrames(channel.messages, send, this.options.runExec ?? ((request, onOutput, signal) => runExec(request, onOutput, signal)), this.tasks, this.options, this.tools, desktop, {
+            host: this.execs, bufferedAmount: () => channel.bufferedAmount, log: this.options.log, admission: this.options.admission,
         });
     }
 }

package/dist/workstation/channels/management.js

@@ -97,7 +97,16 @@ export function metricsForManagementWire(metrics, serverManagementWire) {
  *
  * Exported for tests; production's only caller is `routeMessages`.
  */
-export function dispatchUpdateCommand(channel, command, onUpdate, serverManagementWire) {
+export function dispatchUpdateCommand(channel, command, onUpdate, serverManagementWire, requiredRemoteUpdatePolicy) {
+    if (requiredRemoteUpdatePolicy && command.remoteForcePolicy !== requiredRemoteUpdatePolicy) {
+        if (channel.state === 'OPEN') {
+            try {
+                channel.send(toClientUpdateStatusFrame(command, { phase: 'FAILED', remoteForcePolicy: 'drain-only', error: 'upgrade_required: the server must support authenticated device update readiness' }, serverManagementWire));
+            }
+            catch { }
+        }
+        return Promise.resolve();
+    }
     return onUpdate(command)
         .then((status) => {
         if (channel.state !== 'OPEN')
@@ -189,12 +198,27 @@ export class ManagementChannel {
     constructor(options) {
         this.options = options;
     }
+    async receiveDeviceFact(event) {
+        const generation = this.generation;
+        const channel = this.channel;
+        if (event.scope !== 'device' || !generation || channel?.state !== 'OPEN')
+            return;
+        if (event.kind === 'tool-state' && this.options.onExternalAgentsScan) {
+            const bridges = await this.options.onExternalAgentsScan();
+            if (this.generation === generation && this.channel === channel)
+                this.pushRoster(bridges);
+        }
+        else if (event.kind === 'desktop-capability')
+            this.refreshDesktopCapabilities(generation);
+    }
     refreshDesktopCapabilities(generation) {
         if (generation === undefined || generation === this.generation)
             this.desktopReporter?.refresh();
     }
     /** T10 reports only on its authenticated current management socket. */
     sendDesktopState(generation, frame) {
+        if (frame.t === 'desktop_ownership_result' && (this.serverManagementWire ?? 0) < 10)
+            return false;
         if (generation !== this.generation || (this.serverManagementWire ?? 0) < 9 || this.channel?.state !== 'OPEN')
             return false;
         try {
@@ -293,7 +317,7 @@ export class ManagementChannel {
         // is never driven by the local browser/device-authorization flow.
         await this.options.onReady?.({ generation: ready.generation, selectedWire: ready.protocols.MANAGEMENT, release: ready.release });
         const pending = new Map();
-        void this.routeMessages(channel, pending);
+        void this.routeMessages(channel, pending, ready.generation);
         return {
             generation: ready.generation,
             closed: channel.closed,
@@ -344,17 +368,24 @@ export class ManagementChannel {
                 return frame;
         throw new Error('Management channel closed before ready');
     }
-    async routeMessages(channel, pending) {
+    async routeMessages(channel, pending, generation) {
         try {
             for await (const frame of channel.messages) {
                 if (channel !== this.channel)
                     break;
+                if (frame.t === 'desktop_automation_prepare') {
+                    if (frame.deviceGeneration === this.generation && this.generation && this.options.onAutomationPrepare)
+                        void this.options.onAutomationPrepare(frame, this.generation).catch(() => { });
+                    continue;
+                }
                 if (frame.t === 'workstation_capabilities_request') {
                     if ((this.serverManagementWire ?? 0) >= 9 && frame.generation === this.generation)
                         this.desktopReporter?.refresh();
                     continue;
                 }
-                if ((frame.t === 'desktop_background' || frame.t === 'desktop_lobby' || frame.t === 'desktop_prepare' || frame.t === 'desktop_cancel') && (this.serverManagementWire ?? 0) >= 9) {
+                if ((frame.t === 'desktop_background' || frame.t === 'desktop_lobby' || frame.t === 'desktop_prepare' || frame.t === 'desktop_cancel' || frame.t === 'desktop_ownership') && (this.serverManagementWire ?? 0) >= 9) {
+                    if (frame.t === 'desktop_ownership' && (this.serverManagementWire ?? 0) < 10)
+                        continue;
                     if (frame.t !== 'desktop_cancel' && frame.deviceGeneration !== this.generation)
                         continue;
                     if (this.options.onDesktopCommand && this.generation) {
@@ -374,7 +405,7 @@ export class ManagementChannel {
                 if (frame.t === 'client_update' && this.options.onUpdate) {
                     // Deliberately not awaited — see dispatchUpdateCommand for why inline handling both
                     // stalled this loop for the whole update and threw the final status away.
-                    void dispatchUpdateCommand(channel, frame, this.options.onUpdate, this.serverManagementWire);
+                    void dispatchUpdateCommand(channel, frame, command => this.options.onUpdate(command, generation), this.serverManagementWire, this.options.requiredRemoteUpdatePolicy);
                     continue;
                 }
                 if (frame.t === 'keeper_control' && this.options.onKeeperControl) {

package/dist/workstation/config.js

@@ -6,6 +6,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
 import { z } from 'zod';
+import { withWorkstationLock } from './control/locks.js';
+import { assertLegacyRoot } from './control/rootFormat.js';
 const localPath = z.string().refine(p => path.isAbsolute(p) && !p.includes('\0'));
 const nativeConfig = z.strictObject({ kind: z.literal('linux-native'), helperPath: localPath, runtimeDir: localPath });
 export function updateServiceContext(configDir = clientDir(), overrides = {}) {
@@ -14,10 +16,14 @@ export function updateServiceContext(configDir = clientDir(), overrides = {}) {
     const managed = loadManagedCliInstallSync(packageRoot);
     const nodePath = managed?.nodePath ?? overrides.nodePath ?? process.execPath;
     const npmPrefix = managed?.prefix ?? overrides.npmPrefix ?? process.env.AXOM_WORKSTATION_NPM_PREFIX ?? path.resolve(packageRoot, '../../../..');
+    // A previous sudo npm command can leave the interactive user's cache root-owned. Updates and
+    // their detached rollback watchdog share a cache owned by this workstation service instead.
+    const env = { ...npmExecutionContext({ prefix: npmPrefix, nodePath }, process.env), NPM_CONFIG_CACHE: path.join(configDir, 'update/npm-cache') };
+    delete env.npm_config_cache;
     return {
         configDir,
         ...(managed ? { managed } : {}),
-        env: npmExecutionContext({ prefix: npmPrefix, nodePath }, process.env),
+        env,
         platform: overrides.platform ?? (process.platform === 'darwin' ? 'darwin' : 'linux'),
         nodePath,
         npmPath: managed?.npmPath ?? overrides.npmPath ?? process.env.AXOM_WORKSTATION_NPM_PATH ?? path.join(path.dirname(nodePath), 'npm'),
@@ -33,8 +39,11 @@ export function clientDir() {
     return process.env.AXOM_WORKSTATION_CONFIG_DIR ?? path.join(os.homedir(), '.axom', 'workstation');
 }
 export async function saveClientConfig(dir, cfg) {
-    await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(path.join(dir, 'config.yml'), yaml.dump(cfg), { mode: 0o600 });
+    await withWorkstationLock(dir, 'operation', async () => {
+        await assertLegacyRoot(dir);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, 'config.yml'), yaml.dump(cfg), { mode: 0o600 });
+    });
 }
 export async function loadClientConfig(dir) {
     const raw = await fs.readFile(path.join(dir, 'config.yml'), 'utf8');
@@ -50,9 +59,12 @@ export async function loadClientConfig(dir) {
     return { ...(browserBinding ? { browserBinding } : {}), ...(desktopProvider ? { desktopProvider } : {}), server: parsed.server, workstationId: parsed.workstationId, ...(typeof parsed.ownerUserId === 'string' && parsed.ownerUserId ? { ownerUserId: parsed.ownerUserId } : {}), ...(Array.isArray(parsed.workspaces) ? { workspaces: parsed.workspaces } : {}) };
 }
 export async function writeKeys(dir, clientKeyB64, serverPubB64) {
-    await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(path.join(dir, 'client.key'), clientKeyB64, { mode: 0o600 });
-    await fs.writeFile(path.join(dir, 'server.pub'), serverPubB64);
+    await withWorkstationLock(dir, 'operation', async () => {
+        await assertLegacyRoot(dir);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, 'client.key'), clientKeyB64, { mode: 0o600 });
+        await fs.writeFile(path.join(dir, 'server.pub'), serverPubB64);
+    });
 }
 export async function readKeys(dir) {
     const clientKey = Buffer.from((await fs.readFile(path.join(dir, 'client.key'), 'utf8')).trim(), 'base64');

package/dist/workstation/control/bindingStore.js

@@ -7,6 +7,7 @@ import { loadClientConfig } from '../config.js';
 import { privateDirectory } from '../keepers/kit/paths.js';
 import { bindingSchema, operationRecordSchema, LocalControlError } from './protocol.js';
 import { normalizeWorkstationServer } from './serverIdentity.js';
+import { assertLegacyRoot } from './rootFormat.js';
 const IDENTITY_FILES = ['client.key', 'server.pub', 'config.yml'];
 const missing = (error) => error.code === 'ENOENT';
 async function readPrivateFile(file) {
@@ -106,6 +107,7 @@ export class BindingStore {
         }
     }
     async recover() {
+        await assertLegacyRoot(this.directory);
         if (!await exists(this.pending))
             return;
         const stat = await fs.lstat(this.pending);
@@ -148,6 +150,7 @@ export class BindingStore {
         await syncDirectory(this.directory);
     }
     async commit(config, keys, operation, repair = false) {
+        await assertLegacyRoot(this.directory);
         const binding = bindingOf(config);
         validateKeys(keys);
         const safeOperation = operationRecordSchema.parse(operation);
@@ -176,6 +179,7 @@ export class BindingStore {
         await this.recover();
     }
     async clear(expectedRevision) {
+        await assertLegacyRoot(this.directory);
         await this.recover();
         const current = await this.inspect();
         if (current.revision !== expectedRevision || current.identityState !== 'ready')

package/dist/workstation/control/commands.js

@@ -10,6 +10,7 @@ import { inspectWorkstation } from './inspect.js';
 import { enrollWorkstation, enrollmentFailure } from './enrollment.js';
 import { withWorkstationLock } from './locks.js';
 import { bindingGuardSchema, LocalControlError } from './protocol.js';
+export { executeDeviceCommand } from './deviceCommands.js';
 const lifecycleRequest = z.object({ operationId: z.string().min(1).max(128), guard: bindingGuardSchema }).strict();
 export async function readLocalRequest(input) {
     const chunks = [];