@platless/axom-cli 0.5.9 → 0.6.36

package/dist/axom-patch/cli/zcode-subagent-subwork.json

@@ -2,8 +2,7 @@
   "id": "zcode-subagent-subwork",
   "package": "zcode-acp-server",
   "versions": [
-    "0.69.3",
-    "0.69.4"
+    "0.76.3"
   ],
   "edits": [
     {
@@ -29,15 +28,15 @@
     },
     {
       "file": "dist/server.js",
-      "before_sha256": "547d640a68ad56a97bd587348ea38ee3eca57d1fad9ea1d14e04c486e1efc85a",
-      "after_sha256": "df37fa0b7e5873d13a2cdd71a5fbc931a7ea9ffca521b0218d60a7a9b11e1d3c",
+      "before_sha256": "40a55e7b7fc6662a664f9d462dd4c8774e2e73d222669cb3902448c026b6b6a2",
+      "after_sha256": "95e940c79d16571c1c125d4536c88c94136ddc09713dee65e003cce3ac2a4a8e",
       "before": "export class ZcodeAcpServer {",
       "after": "/** Axom patch `zcode-subagent-subwork`: normalize ZCode sub-agents and background\n * tasks into the draft ACP subagent variants (RFD #1992) and the AIR async-task\n * extension — the same contracts claude-agent-acp ships. The backend already emits\n * first-class lifecycle events on `session.updated` (agentId/childSessionId for\n * sub-agents, taskId for background tasks); this listener forwards them so hosts\n * can project subworks, and dispatch.js re-scopes a foreground sub-agent's internal\n * `tool_subagent_*` tool calls onto its child session. */\nclass AxomZcodeSubagents {\n    constructor(server, zcodeSid) {\n        this.server = server;\n        this.sid = zcodeSid;\n        /** agentId → { agentId, child, background, terminal, pendingState, pendingP, resultSeen, preview } */\n        this.agents = new Map();\n        /** parentToolCallId → agent record (foreground result flush). */\n        this.parents = new Map();\n        /** taskId → { terminal } (bash/exec background tasks only). */\n        this.tasks = new Map();\n    }\n    /** Draft RFD #1992 negotiated — the axom daemon always declares this. */\n    nativeOk() {\n        const caps = this.server.clientCapabilities;\n        return !!(caps && caps.subagents);\n    }\n    /** AIR async-task capability declared (`_meta.jetbrains.air.capabilities`). */\n    asyncOk() {\n        const air = this.server.clientCapabilities?._meta?.jetbrains?.air;\n        return !!(air && Array.isArray(air.capabilities) && air.capabilities.includes(\"asyncTasks\"));\n    }\n    handleEvent(ev) {\n        try {\n            void this.onEvent(ev);\n        }\n        catch {\n            // Never crash the bridge from a normalization observer.\n        }\n    }\n    async onEvent(ev) {\n        if (!ev || ev.type !== \"session.updated\") {\n            this.onToolEvent(ev);\n            return;\n        }\n        const p = ev.payload ?? {};\n        if (typeof p.agentId === \"string\" && p.agentId && typeof p.childSessionId === \"string\" && p.childSessionId) {\n            this.onAgent(p);\n            return;\n        }\n        // Sub-agent background tasks also carry taskId with taskKind \"subagent\" —\n        // the agentId path above owns those. Workflow runs have their own poller.\n        if (typeof p.taskId === \"string\" && p.taskId && p.taskKind !== \"subagent\" && p.taskKind !== \"workflow\") {\n            this.onTask(p);\n        }\n    }\n    onAgent(p) {\n        if (!this.nativeOk())\n            return;\n        const agentId = p.agentId;\n        const child = p.childSessionId;\n        const status = typeof p.status === \"string\" ? p.status : \"running\";\n        let rec = this.agents.get(agentId);\n        if (!rec) {\n            rec = { agentId, child, background: p.background === true, terminal: false, pendingState: null, pendingP: null, resultSeen: false, preview: null };\n            this.agents.set(agentId, rec);\n            if (typeof p.parentToolCallId === \"string\" && p.parentToolCallId)\n                this.parents.set(p.parentToolCallId, rec);\n            // First sighting already terminal (adapter restart): adopt — emit the\n            // spawn so the host can still link the child, then the state below.\n            if (status !== \"running\")\n                rec.resultSeen = true;\n            this.emit({\n                sessionUpdate: \"subagent_spawned\",\n                subagentSessionId: child,\n                name: (typeof p.description === \"string\" && p.description) || (typeof p.agentType === \"string\" && p.agentType) || \"Subagent\",\n                task: typeof p.prompt === \"string\" ? p.prompt : (p.description ?? \"\"),\n                capabilities: {},\n                _meta: { zcode: { agentId, parentToolCallId: p.parentToolCallId, background: rec.background, adopted: status !== \"running\" } },\n            });\n        }\n        if (rec.child !== child)\n            return;\n        const mapped = status === \"completed\" ? \"completed\"\n            : status === \"failed\" || status === \"error\" ? \"failed\"\n                : status === \"cancelled\" || status === \"stopped\" ? \"cancelled\"\n                    : status === \"disconnected\" ? \"disconnected\" : null;\n        if (!mapped || rec.terminal)\n            return;\n        if (rec.background || rec.resultSeen || mapped !== \"completed\") {\n            this.finishAgent(rec, mapped, p);\n            return;\n        }\n        // Foreground completion: hold the state until the parent Agent tool's own\n        // result event arrives (one event later, measured) so the child-scoped\n        // preview precedes the terminal state on the wire.\n        rec.pendingState = mapped;\n        rec.pendingP = p;\n    }\n    finishAgent(rec, state, p) {\n        rec.terminal = true;\n        if (rec.preview) {\n            this.emitChild(rec.child, { sessionUpdate: \"agent_message_chunk\", content: { type: \"text\", text: rec.preview } });\n            rec.preview = null;\n        }\n        const meta = { zcode: { agentId: rec.agentId } };\n        if (p) {\n            for (const key of [\"parentToolCallId\", \"outputFile\"])\n                if (typeof p[key] === \"string\")\n                    meta.zcode[key] = p[key];\n            if (typeof p.totalTokens === \"number\")\n                meta.zcode.totalTokens = p.totalTokens;\n            if (typeof p.totalDurationMs === \"number\")\n                meta.zcode.totalDurationMs = p.totalDurationMs;\n        }\n        this.emit({ sessionUpdate: \"subagent_state_update\", subagentSessionId: rec.child, state, _meta: meta });\n    }\n    onToolEvent(ev) {\n        if (!ev || ev.type !== \"tool.updated\")\n            return;\n        const p = ev.payload ?? {};\n        if (p.kind !== \"result\" || typeof p.toolCallId !== \"string\")\n            return;\n        const rec = this.parents.get(p.toolCallId);\n        if (!rec || rec.terminal || rec.background)\n            return;\n        rec.resultSeen = true;\n        const text = axomSubagentResultPreview(p.result);\n        if (text)\n            rec.preview = text;\n        if (rec.pendingState)\n            this.finishAgent(rec, rec.pendingState, rec.pendingP);\n    }\n    onTask(p) {\n        if (!this.asyncOk())\n            return;\n        const taskId = p.taskId;\n        let task = this.tasks.get(taskId);\n        const status = typeof p.status === \"string\" ? p.status : \"running\";\n        if (!task) {\n            task = { terminal: false };\n            this.tasks.set(taskId, task);\n            this.emit({\n                sessionUpdate: \"async_task_spawned\",\n                asyncTaskId: taskId,\n                name: (typeof p.description === \"string\" && p.description) || (typeof p.command === \"string\" && p.command) || \"background task\",\n                taskType: typeof p.taskKind === \"string\" ? p.taskKind : \"shell\",\n                description: typeof p.description === \"string\" ? p.description : \"\",\n                showInTranscript: false,\n                canStop: p.cancellable === true,\n                ...(typeof p.outputPath === \"string\" ? { outputFilePath: p.outputPath } : {}),\n                ...(typeof p.toolCallId === \"string\" ? { toolCallId: p.toolCallId } : {}),\n                _meta: { zcode: { taskKind: p.taskKind, command: p.command } },\n            });\n        }\n        const mapped = status === \"completed\" ? \"completed\"\n            : status === \"failed\" || status === \"error\" ? \"failed\"\n                : status === \"cancelled\" ? \"stopped\" : null;\n        if (!mapped || task.terminal)\n            return;\n        task.terminal = true;\n        this.emit({\n            sessionUpdate: \"async_task_state_update\",\n            asyncTaskId: taskId,\n            state: mapped,\n            ...(typeof p.toolCallId === \"string\" ? { toolCallId: p.toolCallId } : {}),\n        });\n    }\n    emit(update) {\n        void this.server.notifyByZcodeSid(this.sid, update);\n    }\n    emitChild(childId, update) {\n        const server = this.server;\n        if (!server.clients || server.clients.size === 0)\n            return;\n        void enqueueSessionSend(childId, () => server.clients.broadcast().notify(\"session/update\", { sessionId: childId, update }));\n    }\n}\n/** The parent Agent tool's result carries the sub-agent's final message plus an\n * `agentId:` line and a `<usage>` block that belong to the envelope, not the\n * answer. The backend delivers the payload as a JSON string or as an already\n * parsed object (both measured) — accept either. */\nfunction axomSubagentResultPreview(result) {\n    let content = null;\n    if (typeof result === \"string\") {\n        try {\n            const parsed = JSON.parse(result);\n            if (parsed && typeof parsed.content === \"string\")\n                content = parsed.content;\n        }\n        catch {\n            content = result;\n        }\n    }\n    else if (result && typeof result === \"object\" && typeof result.content === \"string\") {\n        content = result.content;\n    }\n    if (typeof content !== \"string\" || !content.trim())\n        return null;\n    const stripped = content\n        .replace(/<usage>[\\s\\S]*?<\\/usage>/g, \"\")\n        .split(\"\\n\")\n        .filter((line) => !/^agentId:\\s*\\S+/.test(line))\n        .join(\"\\n\")\n        .trim();\n    return stripped ? stripped.slice(0, 2000) : null;\n}\nexport { AxomZcodeSubagents };\nexport class ZcodeAcpServer {"
     },
     {
       "file": "dist/server.js",
-      "before_sha256": "df37fa0b7e5873d13a2cdd71a5fbc931a7ea9ffca521b0218d60a7a9b11e1d3c",
-      "after_sha256": "55d776521298e0a59d7512be34aeb2b86bc10a4cce9b038a9387ab860ab1aa2c",
+      "before_sha256": "95e940c79d16571c1c125d4536c88c94136ddc09713dee65e003cce3ac2a4a8e",
+      "after_sha256": "240a49618e47792dfbaa5f713dca8072bd1e0c56f726e177a1936e071c69df42",
       "before": "        backend.registerEventListener(zcodeSid, new SessionTitleListener(this, zcodeSid));\n        this.backgroundListenerBackend.set(zcodeSid, backend);",
       "after": "        backend.registerEventListener(zcodeSid, new SessionTitleListener(this, zcodeSid));\n        backend.registerEventListener(zcodeSid, new AxomZcodeSubagents(this, zcodeSid));\n        this.backgroundListenerBackend.set(zcodeSid, backend);"
     },
@@ -57,15 +56,15 @@
     },
     {
       "file": "dist/handlers/session.js",
-      "before_sha256": "e36756aa50f823d97df4861566fafc2ea6b36d7baf6d1f9aa9f918930e1c40a6",
-      "after_sha256": "799343ea4036b518ad7d411d192c696ebe821a4eb2b32e87c0b8b5f288cf509f",
+      "before_sha256": "770b8094520487b3eefbea3b47edfad82895bb2658b38dd8c70b201f29ac07be",
+      "after_sha256": "86877e687c74d97e581a0991e549842130567e2041cf4caa10b8ae910a0f2a77",
       "before": "async function adoptStoredTitle(server, acpSid, zcodeSid) {\n    if (server.sessionTitles.has(acpSid))\n        return;",
       "after": "async function adoptStoredTitle(server, acpSid, zcodeSid) {\n    // Axom patch `zcode-subagent-subwork`: the in-memory title is usually the first\n    // prompt's echo; the backend's stored generated title is the real answer, and the\n    // live titleUpdated push is routinely lost at a backend respawn boundary — this\n    // load-time read is then the only surviving copy. A user-pinned rename still wins.\n    if (server.sessionTitles.has(acpSid) && server.titleUserSetBy.has(acpSid))\n        return;"
     },
     {
       "file": "dist/handlers/session.js",
-      "before_sha256": "799343ea4036b518ad7d411d192c696ebe821a4eb2b32e87c0b8b5f288cf509f",
-      "after_sha256": "e28f651c842a85e308e12f3e97d742bcb49a2f470530f7fe3babe4c04fdca4c9",
+      "before_sha256": "86877e687c74d97e581a0991e549842130567e2041cf4caa10b8ae910a0f2a77",
+      "after_sha256": "ba1d5ba52957793c9f392ee6ab425a13eb912e1a5544b485d548d11e25f95a95",
       "before": "        if (hit?.title) {\n            server.sessionTitles.set(acpSid, hit.title);\n            server.touchSessionSummary(acpSid, hit.title);\n            refreshTerminalTabTitle(server, acpSid);\n            log(`adopted stored title for ${acpSid.slice(0, 8)}: ${hit.title}`);\n        }",
       "after": "        if (hit?.title && server.sessionTitles.get(acpSid) !== hit.title) {\n            server.sessionTitles.set(acpSid, hit.title);\n            server.touchSessionSummary(acpSid, hit.title);\n            refreshTerminalTabTitle(server, acpSid);\n            // Axom patch `zcode-subagent-subwork`: broadcast so hosts sync the stored\n            // generated title on (re-)attach — the live push was lost at a respawn.\n            void sendSessionUpdate(server.clients.broadcast(), acpSid, {\n                sessionUpdate: \"session_info_update\",\n                title: hit.title,\n                updatedAt: new Date().toISOString(),\n            }).catch(() => { });\n            log(`adopted stored title for ${acpSid.slice(0, 8)}: ${hit.title}`);\n        }"
     }

package/dist/cli.js

@@ -4,7 +4,7 @@ import { realpathSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { authAction, logoutAction } from './commands/auth.js';
 import { registerExecuteCommand } from './commands/execute.js';
-import { registerGuideCommands } from './commands/guide.js';
+import { registerKnowledgeCommands } from './commands/knowledge.js';
 import { registerRecordCommands } from './commands/record.js';
 import { registerSkillsCommands } from './commands/skills.js';
 import { registerStructCommands } from './commands/struct.js';
@@ -39,50 +39,18 @@ export function buildProgram() {
     program
         .command('__credential-broker', { hidden: true })
         .action(() => runCredentialBroker());
-    const qoderCommand = program.command('qoder-acp')
-        .description('Prepare or run the Qoder SDK ACP adapter')
-        .option('--qodercli <path>', 'Explicit Qoder CLI executable')
-        .option('--prepare-sdk', 'Install the separate SDK runtime, then exit');
-    qoderCommand.action(async (options) => {
-        if (Boolean(options.qodercli) === Boolean(options.prepareSdk))
-            qoderCommand.error('Choose exactly one of --prepare-sdk or --qodercli <path>');
-        try {
-            if (options.prepareSdk) {
-                const { prepareSdkRuntime } = await import('./workstation/qoderAdapter/sdkRuntimeInstall.js');
-                const controller = new AbortController();
-                const cancel = () => controller.abort();
-                process.once('SIGINT', cancel);
-                process.once('SIGTERM', cancel);
-                try {
-                    console.error('Preparing Qoder SDK…');
-                    const result = await prepareSdkRuntime({ signal: controller.signal });
-                    console.error(`Qoder SDK ready${result.alreadyInstalled ? ' (already prepared)' : ''}: ${result.instance}`);
-                }
-                finally {
-                    process.removeListener('SIGINT', cancel);
-                    process.removeListener('SIGTERM', cancel);
-                }
-            }
-            else {
-                const { runQoderAdapter } = await import('./workstation/qoderAdapter/main.js');
-                await runQoderAdapter(options.qodercli);
-            }
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exitCode = 1;
-        }
-    });
     registerStructCommands(program);
     registerRecordCommands(program);
     registerExecuteCommand(program);
-    registerGuideCommands(program);
+    registerKnowledgeCommands(program);
     registerSkillsCommands(program);
     registerUpdateCommand(program);
     registerWorkstationCommands(program, {
         start, stop, restart, install, uninstall, runDaemon, registerWorkstation,
         status: async () => {
             const current = await status();
+            if (current.uncertain)
+                return 'workstation state is unknown; run `axom workstation inspect --json` to verify it';
             return current.running
                 ? `running connected to ${current.server ?? 'unknown server'} as ${current.workstationId ?? 'unknown workstation'}`
                 : 'stopped';

package/dist/commands/knowledge.js

@@ -0,0 +1,47 @@
+import { loadConfig, resolveServer, UsageError } from '../config.js';
+import { callAxomTool } from '../mcp.js';
+import { printOutcome, runCommand } from '../output.js';
+export const GUIDE_RENAMED_MESSAGE = 'axom guide was renamed: use axom knowledge get|search';
+export function registerKnowledgeCommands(program) {
+    const knowledge = program.command('knowledge').description('Read and search the Axomwork manual');
+    const serverOption = () => program.opts().server;
+    knowledge
+        .command('get')
+        .description('Get a manual page, or the table of contents when no path is given')
+        .argument('[path]', 'manual page path, e.g. script-language/sdk/records.md')
+        .option('--locale <locale>', 'manual locale (en|zh)')
+        .action((path, options) => runCommand(() => knowledgeGetAction({ path, locale: options.locale, server: serverOption() })));
+    knowledge
+        .command('search')
+        .description('Search the manual with keywords or a question')
+        .argument('<query>')
+        .option('--locale <locale>', 'manual locale (en|zh)')
+        .option('--limit <n>', 'maximum hits')
+        .action((query, options) => runCommand(() => knowledgeSearchAction({ query, locale: options.locale, limit: options.limit, server: serverOption() })));
+    // Deliberately not an alias: old scripts must fail loudly and learn the new name.
+    program
+        .command('guide', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .argument('[args...]')
+        .helpOption(false)
+        .action(() => runCommand(async () => { throw new UsageError(GUIDE_RENAMED_MESSAGE); }));
+}
+export async function knowledgeGetAction(options) {
+    const server = resolveServer(await loadConfig(), options.server);
+    const args = {};
+    if (options.path !== undefined)
+        args.path = options.path;
+    if (options.locale !== undefined)
+        args.locale = options.locale;
+    printOutcome(await callAxomTool(server, 'axom__knowledge__get', args));
+}
+export async function knowledgeSearchAction(options) {
+    const server = resolveServer(await loadConfig(), options.server);
+    const args = { query: options.query };
+    if (options.locale !== undefined)
+        args.locale = options.locale;
+    if (options.limit !== undefined)
+        args.limit = Number(options.limit);
+    printOutcome(await callAxomTool(server, 'axom__knowledge__search', args));
+}

package/dist/commands/update.js

@@ -1,3 +1,11 @@
+import { z } from 'zod';
+import { inspectWorkstation } from '../workstation/control/inspect.js';
+import { requestRuntimeUpdate } from '../workstation/control/runtimeClient.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 { UsageError, loadConfig, resolveServer } from '../config.js';
 import { runCommand } from '../output.js';
@@ -13,8 +21,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 +63,15 @@ 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) {
+        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 +95,56 @@ 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();
+export async function updateLocalCli(raw, directory, fetchImpl = globalThis.fetch) {
+    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);
+        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 === 'running' && current.runtime.binding?.server !== server)
+                throw new LocalControlError('INSTANCE_OCCUPIED', 'Another server owns the running daemon');
+            const status = current.runtime.state === 'running'
+                ? await requestRuntimeUpdate(directory, manifest, request.operationId)
+                : 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 id = updateRequestSchema.safeParse(request);
+        process.stdout.write(JSON.stringify({ schemaVersion: 1, kind: 'result', operationId: id.success ? id.data.operationId : randomUUID(), result }) + '\n');
+    }));
 }

package/dist/commands/workstation.js

@@ -1,3 +1,7 @@
+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';
@@ -6,6 +10,8 @@ import { ensureFreshToken } from '../mcp.js';
 import { runCommand } from '../output.js';
 import { clientDir, loadClientConfig } from '../workstation/config.js';
 import { resolveWorkstationName, sanitizeName } from '../workstation/names.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
@@ -89,6 +95,7 @@ function dropAccessTokenFromEnvironment() {
  * top-level argument (see service/launchd.ts and service/systemd.ts).
  */
 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
@@ -106,12 +113,29 @@ export function registerWorkstationCommands(program, deps) {
     // 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');
+            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
@@ -122,40 +146,82 @@ export function registerWorkstationCommands(program, deps) {
         // 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);
-        if (justRegistered)
-            await deps.install();
-        await deps.start();
+        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(() => runCommand(async () => { await deps.stop(); }));
+        .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(() => runCommand(async () => { await deps.restart(); }));
+        .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(() => runCommand(async () => { await deps.install(); }));
+        .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 deps.uninstall(); }));
+        .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));
+    }
+    const rd = workstation.command('rd').description('Manage Linux remote desktop independently of the workstation service');
+    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')
         .action((options) => runCommand(async () => {
+        await applyRd(clientDir(), { ...options, server: options.server ?? serverOption() });
         await ensureRegistered(deps, options.server ?? serverOption(), options.name);
         dropAccessTokenFromEnvironment();
         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

package/dist/install/claude/commands.js

@@ -12,7 +12,7 @@ Workflow:
 2. \`axom__app_struct__list_models\` / \`axom__app_struct__get_model\` for a model's attributes, operations, and display metadata.
 3. Prefer read-only struct tools here; do not mutate anything from this command.
 
-For the underlying concepts (applications, models, attributes, references), load guide \`concepts/data-model/index.md\` with \`axom__guide__load\`.
+For the underlying concepts (applications, models, attributes, references), see knowledge page \`concepts/data-model/index.md\` (\`axom__knowledge__get\`).
 `,
     record: `---
 description: Query, create, update, upsert, or delete Axomwork records
@@ -24,11 +24,11 @@ $ARGUMENTS
 
 Workflow:
 1. Discover structure first when unsure: \`axom__app_struct__get_model\` for attribute names and types.
-2. Query with \`axom__record_query__query_records\` (filters/sorts/page criteria — for criteria syntax, load guide \`agent-integration/mcp/record-query-criteria.md\`).
+2. Query with \`axom__record_query__query_records\` (filters/sorts/page criteria — for criteria syntax, see knowledge page \`agent-integration/mcp/record-query-criteria.md\`).
 3. Mutate with \`axom__record_write__create_record\` / \`axom__record_write__update_record\` / \`axom__record_write__upsert_record\` / \`axom__record_write__delete_record\`. Read the record first before updating; confirm with the user before deleting.
 4. \`axom__record_write__upsert_record\` needs \`identityField\` and the identity value inside \`record\`.
 
-For safe mutation patterns, load guide \`agent-integration/operating-patterns/safe-record-mutations.md\`.
+For safe mutation patterns, see knowledge page \`agent-integration/operating-patterns/safe-record-mutations.md\`.
 `,
     execute: `---
 description: Execute Axomwork operations and services, following async runs to completion
@@ -44,7 +44,7 @@ Workflow:
 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.
 
-For sync-vs-job semantics load guide \`concepts/execution/synchronous-and-task-execution.md\`; for run following load guide \`agent-integration/operating-patterns/following-runs.md\`.
+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\`.
 `,
     definition: `---
 description: Develop Axomwork definitions — apps, models, attributes, operations, workflows (requires app_studio scope and an admin account)
@@ -56,8 +56,8 @@ $ARGUMENTS
 
 Rules:
 1. ETag workflow: read the resource first, send its \`etag\` back as \`expectedEtag\` (bodies use \`expectedBodyEtag\`). On conflict, re-read and merge intentionally.
-2. Before authoring \`.axom.kts\` script bodies, load guide \`script-language/sdk/index.md\`; workflow DSL: \`script-language/workflows/index.md\`; sync/job/streaming patterns: \`script-language/patterns/index.md\`.
-3. For definition semantics (apps, models, attributes, operations, workflows), load guide \`application-development/index.md\`.
+2. Before authoring \`.axom.kts\` script bodies, see knowledge page \`script-language/sdk/index.md\`; workflow DSL: \`script-language/workflows/index.md\`; sync/job/streaming patterns: \`script-language/patterns/index.md\`.
+3. For definition semantics (apps, models, attributes, operations, workflows), see knowledge page \`application-development/index.md\`.
 4. Confirm destructive definition deletes with the user first.
 `,
     platform: `---
@@ -70,20 +70,20 @@ $ARGUMENTS
 
 Rules:
 1. Read current configuration before editing; respect ETag guards where tools expose them.
-2. For configuration semantics (AI providers and profiles, cowork agents, datasources, platform skills and settings), load guide \`platform-operations/index.md\` first.
+2. For configuration semantics (AI providers and profiles, cowork agents, datasources, platform skills and settings), see knowledge page \`platform-operations/index.md\` first.
 3. Confirm with the user before changes that can interrupt running workflows or agent sessions.
 `,
-    guide: `---
-description: Look something up in the Axomwork Guide (platform manual)
+    knowledge: `---
+description: Look something up in the Axomwork manual
 ---
 
-Answer using the Axomwork Guide:
+Answer using the Axomwork manual:
 
 $ARGUMENTS
 
 Workflow:
-1. \`axom__guide__search\` with keywords or the question itself; read the ranked snippets.
-2. \`axom__guide__load\` a hit's \`path\` for the full page (omit \`path\` for the table of contents).
-3. Answer from guide content and cite the guide paths you used. If the guide has no answer, say so and fall back to tool discovery (\`tools/list\`).
+1. \`axom__knowledge__search\` with keywords or the question itself; read the ranked snippets.
+2. \`axom__knowledge__get\` a hit's \`path\` for the full page (omit \`path\` for the table of contents).
+3. Answer from the manual and cite the knowledge page paths you used. If the manual has no answer, say so and fall back to tool discovery (\`tools/list\`).
 `,
 };

package/dist/mcp.js

@@ -98,7 +98,7 @@ export function isInsufficientScope(error) {
     return /\b403\b/.test(message);
 }
 /** Abilities every credential has (Ability registry: BASELINE with the MCP surface). */
-const BASELINE_TOOL_SCOPES = new Set(['system', 'guide', 'app_struct']);
+const BASELINE_TOOL_SCOPES = new Set(['system', 'knowledge', 'app_struct']);
 const TOOL_SCOPE = /^axom__([a-z][a-z0-9]*(?:_[a-z0-9]+)*)__[a-z]/;
 const ADMIN_NOTE = ' Scopes marked "Requires an administrator account" on the consent page also need an administrator user.';
 /** An external tool's middle segment IS the OAuth scope that grants it (spec 2026-09-26 §3.5). */