@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/control/commands.js

@@ -0,0 +1,124 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { assertIdentityCanStart } from './daemonIdentity.js';
+import { normalizeWorkstationServer } from './serverIdentity.js';
+import { saveOperation } from './enrollment.js';
+import { clientDir, loadClientConfig, readKeys } from '../config.js';
+import { createDaemonController } from '../daemonctl.js';
+import { BindingStore } from './bindingStore.js';
+import { inspectWorkstation } from './inspect.js';
+import { enrollWorkstation, enrollmentFailure } from './enrollment.js';
+import { withWorkstationLock } from './locks.js';
+import { bindingGuardSchema, LocalControlError } from './protocol.js';
+const lifecycleRequest = z.object({ operationId: z.string().min(1).max(128), guard: bindingGuardSchema }).strict();
+export async function readLocalRequest(input) {
+    const chunks = [];
+    let size = 0;
+    for await (const part of input) {
+        const chunk = Buffer.from(part);
+        size += chunk.length;
+        if (size > 65_536)
+            throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local command input');
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Invalid local command input');
+    }
+}
+export async function executeLocalCommand(action, input, directory, controllerFactory, inspect = inspectWorkstation) {
+    if (action === 'register')
+        return enrollWorkstation(input, directory);
+    try {
+        const request = action === 'adopt-owner' ? lifecycleRequest.extend({ server: z.string(), expectedOwnerUserId: z.string().min(1), workstationId: z.string().min(1) }).parse(input) : action === 'set-enabled' ? lifecycleRequest.extend({ enabled: z.boolean() }).parse(input) : lifecycleRequest.parse(input);
+        return await withWorkstationLock(directory, 'operation', async () => {
+            const before = await inspect(directory);
+            if (before.revision !== request.guard.revision || before.runtime.generation !== request.guard.runtimeGeneration)
+                throw new LocalControlError('BINDING_CONFLICT', 'Workstation changed; check it again');
+            if (action === 'recover') {
+                if (before.runtime.state !== 'stopped' || before.keepers !== 'stopped')
+                    throw new LocalControlError('OUTCOME_UNKNOWN', 'Stop and verify the workstation before recovering its identity');
+                await new BindingStore(directory).recover();
+                return { status: 'succeeded', inspection: await inspect(directory) };
+            }
+            if (before.pending?.kind === 'remove' && !['begin-remove', 'forget', 'stop'].includes(action))
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Finish removing this workstation before continuing');
+            if (before.runtime.state === 'unknown')
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Cannot verify the running workstation');
+            if (action === 'adopt-owner') {
+                const ownerRequest = lifecycleRequest.extend({ server: z.string(), expectedOwnerUserId: z.string().min(1), workstationId: z.string().min(1) }).parse(input);
+                if (before.identityState !== 'ready' || !before.binding || before.binding.ownerUserId || before.binding.server !== normalizeWorkstationServer(ownerRequest.server) || before.binding.workstationId !== ownerRequest.workstationId)
+                    throw new LocalControlError('BINDING_CONFLICT', 'The local connection changed');
+                const config = await loadClientConfig(directory);
+                const keys = await readKeys(directory);
+                await new BindingStore(directory).commit({ ...config, ownerUserId: ownerRequest.expectedOwnerUserId }, { clientKey: keys.clientKey.toString('base64'), serverPub: keys.serverPub.toString('base64') }, { id: request.operationId, kind: 'register', phase: 'owner-confirmed', target: { server: before.binding.server, ownerUserId: ownerRequest.expectedOwnerUserId }, workstationId: before.binding.workstationId, outcome: 'succeeded' });
+            }
+            else if (action === 'forget') {
+                if (before.runtime.state !== 'stopped' || before.keepers !== 'stopped')
+                    throw new LocalControlError('INSTANCE_OCCUPIED', 'Stop the workstation and its sessions before removing the connection');
+                await new BindingStore(directory).clear(request.guard.revision);
+            }
+            else {
+                if (before.identityState !== 'ready')
+                    throw new LocalControlError('CORRUPT_IDENTITY', 'The workstation needs registration or repair');
+                const controller = controllerFactory?.() ?? createDaemonController({ identity: () => new BindingStore(directory).inspect(), runtime: async () => (await inspect(directory)).runtime });
+                if (action === 'set-enabled') {
+                    const enabled = lifecycleRequest.extend({ enabled: z.boolean() }).parse(input).enabled;
+                    if (enabled)
+                        await assertIdentityCanStart(directory);
+                    if (!controller.setEnabled)
+                        throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Update the CLI to manage service enablement');
+                    await controller.setEnabled(enabled, request);
+                }
+                else if (action === 'begin-remove') {
+                    if (before.runtime.state !== 'stopped' || before.keepers !== 'stopped')
+                        await controller.stop(request);
+                    const stopped = await inspect(directory);
+                    if (stopped.runtime.state !== 'stopped' || stopped.keepers !== 'stopped')
+                        throw new LocalControlError('OUTCOME_UNKNOWN', 'Workstation shutdown could not be confirmed');
+                    await saveOperation(directory, { id: request.operationId, kind: 'remove', phase: 'removing', target: { server: before.binding.server, ownerUserId: before.binding.ownerUserId ?? null }, workstationId: before.binding.workstationId, outcome: 'pending' });
+                }
+                else if (action === 'install') {
+                    if (before.runtime.state !== 'stopped')
+                        throw new LocalControlError('INSTANCE_OCCUPIED', 'Stop the workstation before changing its service');
+                    await controller.install();
+                }
+                else {
+                    if (action === 'start' || action === 'restart')
+                        await assertIdentityCanStart(directory);
+                    await controller[action](request);
+                }
+            }
+            const after = await inspect(directory);
+            if (action === 'set-enabled') {
+                const expected = lifecycleRequest.extend({ enabled: z.boolean() }).parse(input).enabled;
+                if (!after.service || after.service.enabled !== expected || after.service.reason || (!expected && (after.runtime.state !== 'stopped' || after.keepers !== 'stopped'))) {
+                    throw new LocalControlError('OUTCOME_UNKNOWN', 'Service enablement could not be confirmed');
+                }
+            }
+            if (action === 'stop' && (after.runtime.state !== 'stopped' || after.keepers !== 'stopped'))
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Workstation shutdown could not be confirmed');
+            return { status: 'succeeded', inspection: after };
+        });
+    }
+    catch (error) {
+        return enrollmentFailure(error, directory);
+    }
+}
+export async function runLocalJsonCommand(action, input = process.stdin, write = value => { process.stdout.write(value); }, directory = clientDir(), controllerFactory, inspect = inspectWorkstation) {
+    let operationId = randomUUID();
+    let result;
+    try {
+        const request = await readLocalRequest(input);
+        if (typeof request === 'object' && request && 'operationId' in request && typeof request.operationId === 'string' && /^[\w-]{1,128}$/.test(request.operationId))
+            operationId = request.operationId;
+        result = await executeLocalCommand(action, request, directory, controllerFactory, inspect);
+    }
+    catch (error) {
+        result = await enrollmentFailure(error, directory);
+    }
+    const event = { schemaVersion: 1, kind: 'result', operationId, result };
+    write(JSON.stringify(event) + '\n');
+}

package/dist/workstation/control/daemonIdentity.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { loadClientConfig, readKeys } from '../config.js';
+import { BindingStore } from './bindingStore.js';
+import { withWorkstationLock } from './locks.js';
+import { inspectRuntime } from './runtimeClient.js';
+import { readControlFile } from './runtimeHost.js';
+import { LocalControlError, operationRecordSchema } from './protocol.js';
+export async function assertIdentityCanStart(directory) {
+    try {
+        const operation = operationRecordSchema.parse(JSON.parse(await readControlFile(path.join(directory, 'operation.json'))));
+        if (operation.outcome === 'pending' || operation.outcome === 'unknown')
+            throw new LocalControlError('OUTCOME_UNKNOWN', operation.kind === 'remove' ? 'Finish removing this workstation before starting it' : 'The workstation operation needs verification');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+export async function recoverStoppedIdentity(directory) {
+    const store = new BindingStore(directory);
+    if ((await store.inspect()).identityState === 'incomplete') {
+        const runtime = await inspectRuntime(directory);
+        const { inspectKeepers } = await import('./inspect.js');
+        if (runtime.state !== 'stopped' || await inspectKeepers(directory) !== 'stopped')
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Stop and verify the existing workstation before recovering its identity');
+    }
+    await store.recover();
+}
+/** Publish runtime ownership under the same lock as identity writes; initialization uses this snapshot only. */
+export async function claimDaemonIdentity(directory, claim) {
+    const deadline = Date.now() + 10_000;
+    for (;;)
+        try {
+            return await withWorkstationLock(directory, 'operation', async () => {
+                const runtime = await inspectRuntime(directory);
+                if (runtime.state !== 'stopped')
+                    throw new LocalControlError(runtime.state === 'running' ? 'INSTANCE_OCCUPIED' : 'OUTCOME_UNKNOWN', 'The existing workstation must be verified before startup');
+                const store = new BindingStore(directory);
+                await recoverStoppedIdentity(directory);
+                await assertIdentityCanStart(directory);
+                if ((await store.inspect()).identityState !== 'ready')
+                    throw new LocalControlError('CORRUPT_IDENTITY', 'The workstation identity needs registration or repair');
+                const config = await loadClientConfig(directory);
+                const keys = await readKeys(directory);
+                return claim({ config, ...keys });
+            });
+        }
+        catch (error) {
+            if (!(error instanceof LocalControlError) || error.code !== 'BUSY' || Date.now() >= deadline)
+                throw error;
+            await new Promise(resolve => setTimeout(resolve, 50));
+        }
+}

package/dist/workstation/control/enrollment.js

@@ -0,0 +1,106 @@
+import os from 'node:os';
+import { sanitizeName } from '../names.js';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { requestWorkstationRegistration } from '../register.js';
+import { BindingStore } from './bindingStore.js';
+import { inspectRuntime } from './runtimeClient.js';
+import { inspectWorkstation } from './inspect.js';
+import { bindingGuardSchema, LocalControlError, operationRecordSchema } from './protocol.js';
+import { assertLockOwnership, withWorkstationLock } from './locks.js';
+import { normalizeWorkstationServer } from './serverIdentity.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { KeeperLauncher } from '../keepers/kit/launcher.js';
+import { stopKeepers } from '../keepers/stop.js';
+export const registrationInputSchema = z.object({ operationId: z.string().min(1).max(128), server: z.string(), expectedOwnerUserId: z.string().min(1), name: z.string().min(1).max(200).optional(), workstationId: z.string().min(1).optional(), workspace: z.object({ name: z.string(), cwd: z.string(), shell: z.string() }).optional(), guard: bindingGuardSchema, switchConfirmed: z.boolean(), accessToken: z.string().min(1).max(32_768) }).strict();
+export async function saveOperation(directory, operation) {
+    assertLockOwnership();
+    await privateDirectory(directory);
+    const file = path.join(directory, 'operation.json');
+    const temporary = file + '.' + randomUUID();
+    const handle = await fs.open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(operationRecordSchema.parse(operation)));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    assertLockOwnership();
+    await fs.rename(temporary, file);
+}
+export async function enrollmentFailure(error, directory) {
+    const e = error instanceof LocalControlError ? error : new LocalControlError('SERVICE_FAILED', 'The local workstation operation failed. Check its status and try again.');
+    return { status: e.code === 'BUSY' ? 'busy' : e.code === 'OUTCOME_UNKNOWN' ? 'pending' : ['BINDING_CONFLICT', 'INSTANCE_OCCUPIED'].includes(e.code) ? 'conflict' : 'failed', inspection: await inspectWorkstation(directory).catch(() => null), error: { code: e.code, message: e.message } };
+}
+async function defaultShell() {
+    const candidates = [process.env.SHELL, os.userInfo().shell, process.platform === 'darwin' ? '/bin/zsh' : '/bin/sh'];
+    for (const shell of candidates)
+        if (shell && path.isAbsolute(shell) && !/[\x00-\x1f]/.test(shell)) {
+            try {
+                await fs.access(shell, fs.constants.X_OK);
+                if ((await fs.stat(shell)).isFile())
+                    return shell;
+            }
+            catch { /* Try the user's login shell, then the platform fallback. */ }
+        }
+    throw new LocalControlError('UNSUPPORTED_INSTALLATION', 'No executable login shell is available');
+}
+async function enroll(input, directory, deps) {
+    const server = normalizeWorkstationServer(input.server);
+    const store = new BindingStore(directory);
+    await store.recover();
+    const identity = await store.inspect();
+    const runtime = await deps.runtime();
+    if (runtime.state !== 'stopped')
+        throw new LocalControlError(runtime.state === 'running' ? 'INSTANCE_OCCUPIED' : 'OUTCOME_UNKNOWN', 'Stop the existing workstation before registering this computer');
+    if (input.guard && (identity.revision !== input.guard.revision || runtime.generation !== input.guard.runtimeGeneration))
+        throw new LocalControlError('BINDING_CONFLICT', 'Workstation changed; check it again');
+    if (identity.identityState === 'corrupt' && (!identity.binding || !input.expectedOwnerUserId || (identity.binding.ownerUserId && identity.binding.ownerUserId !== input.expectedOwnerUserId) || identity.binding.server !== server))
+        throw new LocalControlError('CORRUPT_IDENTITY', 'The saved workstation identity needs verification');
+    const switching = identity.binding && (identity.binding.server !== server || (input.expectedOwnerUserId && identity.binding.ownerUserId !== input.expectedOwnerUserId));
+    if (switching && !input.switchConfirmed)
+        throw new LocalControlError('BINDING_CONFLICT', 'Confirm switching this computer to the selected server and account');
+    const inspection = await inspectWorkstation(directory);
+    if (inspection.pending && ['pending', 'unknown'].includes(inspection.pending.outcome))
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'An earlier registration needs verification. Refresh the workstation list before retrying.');
+    if (identity.binding) {
+        const reports = await stopKeepers(new KeeperLauncher({ configDir: directory, ...identity.binding }));
+        if (reports.some(report => !report.result.stopped))
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Existing workstation sessions could not be stopped');
+    }
+    const history = await store.history();
+    const known = input.expectedOwnerUserId ? history.find(item => item.server === server && item.ownerUserId === input.expectedOwnerUserId) : undefined;
+    const same = identity.binding?.server === server && (!input.expectedOwnerUserId || identity.binding.ownerUserId === input.expectedOwnerUserId);
+    const workstationId = input.workstationId ?? known?.workstationId ?? (same ? identity.binding?.workstationId : undefined);
+    const operation = { id: input.operationId, kind: switching ? 'switch' : 'register', phase: 'registering', target: { server, ownerUserId: input.expectedOwnerUserId ?? null }, outcome: 'pending' };
+    await saveOperation(directory, operation);
+    try {
+        const workspace = input.workspace;
+        const shell = workspace?.shell ?? await defaultShell();
+        const response = await requestWorkstationRegistration(server, input.name ?? sanitizeName(os.hostname(), 'computer'), input.accessToken, workspace, workstationId, shell);
+        if (input.expectedOwnerUserId && response.ownerUserId !== input.expectedOwnerUserId)
+            throw new LocalControlError('OWNER_MISMATCH', 'The server returned a different workstation owner');
+        assertLockOwnership();
+        await store.commit({ server, workstationId: response.workstationId, ...(response.ownerUserId ? { ownerUserId: response.ownerUserId } : {}), workspaces: workspace ? [{ name: workspace.name, cwd: workspace.cwd }] : [] }, response, { ...operation, workstationId: response.workstationId, phase: 'registered', outcome: 'succeeded' }, identity.identityState === 'corrupt');
+        return { status: 'succeeded', inspection: await inspectWorkstation(directory) };
+    }
+    catch (error) {
+        await saveOperation(directory, { ...operation, outcome: error instanceof LocalControlError && error.code !== 'OUTCOME_UNKNOWN' ? 'failed' : 'unknown' });
+        throw error;
+    }
+}
+export async function enrollWorkstation(input, directory, deps = { runtime: () => inspectRuntime(directory) }) {
+    try {
+        const parsed = registrationInputSchema.parse(input);
+        return await withWorkstationLock(directory, 'operation', () => enroll(parsed, directory, deps));
+    }
+    catch (error) {
+        return enrollmentFailure(error, directory);
+    }
+}
+export async function enrollLegacyWorkstation(input, directory) {
+    await withWorkstationLock(directory, 'operation', () => enroll(input, directory, { runtime: () => inspectRuntime(directory) }));
+}

package/dist/workstation/control/inspect.js

@@ -0,0 +1,71 @@
+import os from 'node:os';
+import { createServiceManager } from '../service/installer.js';
+import { serviceContext } from '../daemonctl.js';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BindingStore } from './bindingStore.js';
+import { inspectRuntime } from './runtimeClient.js';
+import { localInspectionSchema, operationRecordSchema } from './protocol.js';
+import { readControlFile } from './runtimeHost.js';
+import { updateServiceContext } from '../config.js';
+import { CLIENT_VERSION } from '../version.js';
+import { readPidManifest, manifestProcessLive } from '../keepers/kit/lock.js';
+export async function inspectKeepers(directory) {
+    try {
+        let running = false;
+        for (const kind of ['acp', 'terminal']) {
+            const root = path.join(directory, 'keepers', kind, 'run');
+            let entries;
+            try {
+                entries = await fs.readdir(root);
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    continue;
+                throw e;
+            }
+            for (const entry of entries) {
+                const manifest = await readPidManifest(path.join(root, entry, 'keeper.pid.json'));
+                if (manifest && await manifestProcessLive(manifest))
+                    running = true;
+            }
+        }
+        return running ? 'running' : 'stopped';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export async function inspectWorkstation(directory, deps = {}) {
+    const identity = await new BindingStore(directory).inspect();
+    let pending = null;
+    try {
+        const operation = operationRecordSchema.parse(JSON.parse(await readControlFile(path.join(directory, 'operation.json'))));
+        if (operation.outcome !== 'succeeded')
+            pending = operation;
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    const cliPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../cli.js');
+    const context = updateServiceContext(directory);
+    let runtime = await inspectRuntime(directory);
+    const standardHome = os.userInfo().homedir;
+    const standardDirectory = path.join(standardHome, '.axom/workstation');
+    const probeLegacy = deps.legacyServiceRunning ?? (process.platform === 'darwin' && path.resolve(directory) === standardDirectory && os.homedir() === standardHome
+        ? async () => (await createServiceManager(serviceContext()).status()).running : undefined);
+    if (runtime.state === 'stopped' && probeLegacy) {
+        try {
+            if (await probeLegacy())
+                runtime = { ...runtime, state: 'unknown', connection: 'unknown' };
+        }
+        catch {
+            runtime = { ...runtime, state: 'unknown', connection: 'unknown' };
+        }
+    }
+    const service = (process.platform === 'darwin' || process.platform === 'linux') && path.resolve(directory) === standardDirectory && os.homedir() === standardHome
+        ? await createServiceManager(serviceContext()).enablement() : undefined;
+    return localInspectionSchema.parse({ schemaVersion: 1, ...identity, installation: { source: context.managed ? 'managed' : 'existing', version: CLIENT_VERSION, nodeVersion: process.versions.node, nodePath: context.nodePath, cliPath, npmPath: context.npmPath, npmPrefix: context.npmPrefix }, runtime, ...(service ? { service } : {}), keepers: await inspectKeepers(directory), pending });
+}

package/dist/workstation/control/locks.js

@@ -0,0 +1,63 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import lockfile from 'proper-lockfile';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { pidAlive, processCommand } from '../keepers/kit/lock.js';
+import { LocalControlError } from './protocol.js';
+const ownership = new AsyncLocalStorage();
+export function assertLockOwnership() {
+    if (ownership.getStore()?.valid === false)
+        throw new LocalControlError('BUSY', 'Workstation lock ownership was lost');
+}
+export async function withPrivateLock(stem, work) {
+    await privateDirectory(path.dirname(stem));
+    const ownerFile = stem + '.owner.json';
+    // proper-lockfile's time lease alone is insufficient: a suspended live app still owns its operation.
+    let lockPresent = false;
+    try {
+        const stat = await fs.lstat(stem + '.lock');
+        lockPresent = true;
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw Error('Unsafe lock');
+        if (Date.now() - stat.mtimeMs > 30_000) {
+            const owner = JSON.parse(await fs.readFile(ownerFile, 'utf8'));
+            if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0 || typeof owner.command !== 'string')
+                throw Error('Unknown owner');
+            if (pidAlive(owner.pid))
+                throw Error('Live or unverifiable owner');
+        }
+    }
+    catch (error) {
+        if (lockPresent || error.code !== 'ENOENT')
+            throw new LocalControlError('BUSY', 'Another workstation operation is active');
+    }
+    const lease = { valid: true };
+    const nonce = randomUUID();
+    let release;
+    try {
+        release = await lockfile.lock(stem, { realpath: false, stale: 30_000, update: 2_000, retries: 0, onCompromised: () => { lease.valid = false; } });
+    }
+    catch {
+        throw new LocalControlError('BUSY', 'Another workstation operation is active');
+    }
+    try {
+        await fs.writeFile(ownerFile, JSON.stringify({ schemaVersion: 1, pid: process.pid, command: await processCommand(process.pid), nonce }), { mode: 0o600 });
+        return await ownership.run(lease, async () => { const result = await work(); assertLockOwnership(); return result; });
+    }
+    finally {
+        if (lease.valid) {
+            try {
+                if (JSON.parse(await fs.readFile(ownerFile, 'utf8')).nonce === nonce)
+                    await fs.rm(ownerFile);
+            }
+            catch { /* release still required */ }
+            await release();
+        }
+    }
+}
+export function withWorkstationLock(directory, name, work) {
+    return withPrivateLock(name === 'operation' ? path.join(directory, 'control/operation') : path.join(os.homedir(), '.axom/locks/cli-install'), work);
+}

package/dist/workstation/control/protocol.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export const bindingSchema = z.object({ server: z.string().min(1), workstationId: z.string().min(1), ownerUserId: z.string().min(1).optional() });
+export const bindingGuardSchema = z.object({ revision: z.string().min(1), runtimeGeneration: z.string().nullable() });
+const activitySchema = z.object({ commands: z.number().int().nonnegative(), terminals: z.number().int().nonnegative(), agents: z.number().int().nonnegative(), transfers: z.number().int().nonnegative() });
+export const runtimeSnapshotSchema = z.object({
+    state: z.enum(['stopped', 'running', 'unknown']), binding: bindingSchema.nullable(), generation: z.string().nullable(),
+    mode: z.enum(['launchd', 'foreground', 'unknown']), connection: z.enum(['offline', 'connecting', 'online', 'reconnecting', 'rejected', 'unknown']), activity: activitySchema.nullable(),
+});
+export const cliInstallationSchema = z.object({
+    source: z.enum(['managed', 'existing']), version: z.string(), nodeVersion: z.string(),
+    nodePath: z.string(), cliPath: z.string(), npmPath: z.string(), npmPrefix: z.string(),
+});
+export const operationRecordSchema = z.object({
+    id: z.string().min(1), kind: z.enum(['register', 'switch', 'start', 'stop', 'remove', 'update']), phase: z.string().min(1).max(80),
+    target: z.object({ server: z.string().min(1), ownerUserId: z.string().min(1).nullable() }).strict(),
+    workstationId: z.string().min(1).optional(), outcome: z.enum(['pending', 'succeeded', 'failed', 'unknown']),
+}).strict();
+export const serviceSnapshotSchema = z.object({ installed: z.boolean(), enabled: z.boolean().nullable(), loaded: z.boolean(), running: z.boolean(), reason: z.string().optional() });
+export const localInspectionSchema = z.object({
+    schemaVersion: z.literal(1), installation: cliInstallationSchema, binding: bindingSchema.nullable(), revision: z.string().min(1),
+    identityState: z.enum(['absent', 'ready', 'incomplete', 'corrupt']), runtime: runtimeSnapshotSchema,
+    service: serviceSnapshotSchema.optional(),
+    keepers: z.enum(['stopped', 'running', 'unknown']), pending: operationRecordSchema.nullable(),
+});
+export const localErrorCodeSchema = z.enum(['UNSUPPORTED_INSTALLATION', 'UNSUPPORTED_PROTOCOL', 'BINDING_CONFLICT', 'INSTANCE_OCCUPIED', 'AUTHORIZATION_REQUIRED', 'OWNER_MISMATCH', 'NETWORK_FAILED', 'CORRUPT_IDENTITY', 'SERVICE_FAILED', 'BUSY', 'OUTCOME_UNKNOWN']);
+export const cliResultSchema = z.object({
+    status: z.enum(['succeeded', 'busy', 'pending', 'failed', 'conflict']), inspection: localInspectionSchema.nullable(),
+    error: z.object({ code: localErrorCodeSchema, message: z.string().max(1024) }).optional(),
+}).refine(value => value.status !== 'succeeded' || value.inspection !== null, 'Successful operations require inspection');
+export class LocalControlError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'LocalControlError';
+    }
+}
+export function stoppedRuntime() {
+    return { state: 'stopped', binding: null, generation: null, mode: 'unknown', connection: 'offline', activity: null };
+}

package/dist/workstation/control/restartGuard.js

@@ -0,0 +1,46 @@
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import { promisify } from 'node:util';
+import { LocalControlError } from './protocol.js';
+import { readControlFile, runtimeOwnerLive, runtimePaths } from './runtimeHost.js';
+const run = promisify(execFile);
+async function parentPid(pid) {
+    let value;
+    if (process.platform === 'linux') {
+        const stat = await fs.readFile(`/proc/${pid}/stat`, 'utf8');
+        value = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/)[1];
+    }
+    else
+        value = (await run('ps', ['-o', 'ppid=', '-p', String(pid)], { timeout: 1000 })).stdout.trim();
+    const parent = Number(value);
+    if (!value || !Number.isSafeInteger(parent) || parent < 0)
+        throw new Error('Unknown process parent');
+    return parent;
+}
+export async function assertRuntimeRestartSafe(directory, generation, overrides = {}) {
+    const deps = { owner: async () => JSON.parse(await readControlFile(runtimePaths(directory).ownerFile)),
+        live: runtimeOwnerLive, parent: parentPid, pid: process.pid, ...overrides };
+    try {
+        const owner = await deps.owner();
+        if (owner.generation !== generation)
+            throw new LocalControlError('BINDING_CONFLICT', 'Workstation changed before restart');
+        if (!Number.isSafeInteger(owner.pid) || owner.pid <= 1 || !await deps.live(owner))
+            throw new Error('Unknown runtime process');
+        const seen = new Set();
+        const deadline = Date.now() + 3000;
+        let current = deps.pid;
+        while (current > 1 && !seen.has(current) && seen.size < 128 && Date.now() < deadline) {
+            if (current === owner.pid)
+                throw new LocalControlError('BUSY', 'This command is running inside the workstation daemon. Restarting it would terminate the current agent or command. Finish the session or move it to an independent keeper before restarting.');
+            seen.add(current);
+            current = await deps.parent(current);
+        }
+        if (current > 1)
+            throw new Error('Unknown process ancestry');
+    }
+    catch (error) {
+        if (error instanceof LocalControlError)
+            throw error;
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Cannot verify that workstation restart will preserve the calling session');
+    }
+}

package/dist/workstation/control/runtimeClient.js

@@ -0,0 +1,97 @@
+import net from 'node:net';
+import { runtimePaths, readControlFile, runtimeOwnerLive } from './runtimeHost.js';
+import { runtimeSnapshotSchema, stoppedRuntime, LocalControlError } from './protocol.js';
+import { pidAlive } from '../keepers/kit/lock.js';
+export async function runtimeRequest(directory, action, expectedGeneration, extra = {}) {
+    const paths = runtimePaths(directory);
+    const owner = JSON.parse(await readControlFile(paths.ownerFile));
+    if (typeof owner.generation !== 'string' || !pidAlive(owner.pid))
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Runtime owner cannot be verified');
+    if (expectedGeneration && owner.generation !== expectedGeneration)
+        throw new LocalControlError('BINDING_CONFLICT', 'Runtime changed');
+    const token = await readControlFile(paths.tokenFile);
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(paths.socket);
+        let data = '';
+        let done = false;
+        const fail = (error) => { if (!done) {
+            done = true;
+            socket.destroy();
+            reject(error);
+        } };
+        socket.setTimeout(3000, () => fail(new LocalControlError('OUTCOME_UNKNOWN', 'Runtime did not respond')));
+        socket.on('error', () => fail(new LocalControlError('OUTCOME_UNKNOWN', 'Cannot contact runtime')));
+        socket.on('end', () => { if (!done)
+            fail(new LocalControlError('OUTCOME_UNKNOWN', 'Incomplete runtime response')); });
+        socket.on('connect', () => socket.write(JSON.stringify({ ...extra, action, generation: owner.generation, token }) + '\n'));
+        socket.on('data', chunk => {
+            data += chunk.toString();
+            if (Buffer.byteLength(data) > 65_536) {
+                fail(Error('Oversized response'));
+                return;
+            }
+            if (!data.includes('\n') || done)
+                return;
+            try {
+                const result = JSON.parse(data.split('\n')[0]);
+                if (!result.ok)
+                    throw new LocalControlError(result.code === 'BINDING_CONFLICT' ? result.code : 'SERVICE_FAILED', 'Runtime rejected the request');
+                done = true;
+                socket.destroy();
+                resolve(result.value);
+            }
+            catch (error) {
+                fail(error);
+            }
+        });
+    });
+}
+export async function inspectRuntime(directory) {
+    try {
+        return runtimeSnapshotSchema.parse(await runtimeRequest(directory, 'inspect'));
+    }
+    catch (error) {
+        try {
+            const owner = JSON.parse(await readControlFile(runtimePaths(directory).ownerFile));
+            if (Number.isSafeInteger(owner.pid) && owner.pid > 0 && typeof owner.command === 'string' && typeof owner.generation === 'string' && !await runtimeOwnerLive(owner))
+                return stoppedRuntime();
+        }
+        catch { /* Partial ownership evidence remains unknown. */ }
+        if (error.code === 'ENOENT') {
+            // No control files at all is stopped; partial state must remain uncertain.
+            const p = runtimePaths(directory);
+            const { promises: fs } = await import('node:fs');
+            try {
+                await fs.lstat(p.socket);
+            }
+            catch (e) {
+                if (e.code === 'ENOENT') {
+                    try {
+                        await fs.lstat(p.ownerFile);
+                    }
+                    catch (e2) {
+                        if (e2.code === 'ENOENT')
+                            return stoppedRuntime();
+                    }
+                }
+            }
+        }
+        return { ...stoppedRuntime(), state: 'unknown', connection: 'unknown' };
+    }
+}
+export async function stopRuntime(directory, expectedGeneration) {
+    await runtimeRequest(directory, 'stop', expectedGeneration);
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+        const state = await inspectRuntime(directory);
+        if (state.state === 'stopped')
+            return;
+        if (state.generation && state.generation !== expectedGeneration)
+            throw new LocalControlError('BINDING_CONFLICT', 'A new daemon started');
+        await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    throw new LocalControlError('OUTCOME_UNKNOWN', 'Workstation shutdown has not been confirmed');
+}
+export async function requestRuntimeUpdate(directory, release, operationId) {
+    return await runtimeRequest(directory, 'update', undefined, { release, operationId });
+}