@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/tools/info.js

@@ -0,0 +1,50 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/*
+ * `tools.info`, aggregated by the daemon. Consumers (analysis C §3.6): Workbench app.mjs (version), CoworkService
+ * (files / mediaPreviewVersion / fileFindVersion / home / userName), files.mjs (roots / downloads / terminal),
+ * terminal.mjs (home, terminal / terminalError), browser.mjs (browser* fields). Every field keeps the value and meaning
+ * the legacy tools keeper gave it (tools/core.ts at the merge-base, since deleted, + tools/client.ts), and answering it never
+ * starts any keeper:
+ *   - file fields come from the files host's last `ready` (or are computed here before the first one); `files: true`
+ *     is reported even while the host restarts, so a probe never mistakes the machine for an old CLI;
+ *   - terminal fields come from keeper-terminal's hello capabilities when that keeper is already running (connecting to it,
+ *     never starting it: keepers/terminal/client.ts `terminalStatus`), otherwise from a cached node-pty load check
+ *     (update/ptyPreflight.ts);
+ *   - browser fields come from the browser-kind ToolsClient, whose `tools.info` only returns metadata.
+ */
+/** The legacy keeper always sent this (tools/core.ts at the merge-base); the browser metadata never removed it. */
+export const BROWSER_DISABLED_ERROR = 'Browser tools are not enabled in this release';
+export async function aggregateToolsInfo(sources) {
+    const [files, browser, terminal] = await Promise.all([sources.files(), sources.browser('tools.info', {}), sources.terminal()]);
+    return {
+        version: 1,
+        terminal: terminal.terminal,
+        browser: false,
+        ...files,
+        ...(terminal.terminalError ? { terminalError: terminal.terminalError } : {}),
+        browserError: BROWSER_DISABLED_ERROR,
+        ...browser,
+    };
+}
+/**
+ * The file fields before any files host was ready: the same canonical home and roots the host computes
+ * (scope.ts `configuredRoots`), except that a root which cannot be resolved is left out instead of failing the probe.
+ */
+export async function computeFilesInfo(home, roots) {
+    const canonicalHome = await fs.realpath(home).catch(() => home);
+    const canonical = new Set([canonicalHome]);
+    for (const root of roots) {
+        try {
+            const real = await fs.realpath(root);
+            if ((await fs.stat(real)).isDirectory())
+                canonical.add(real);
+        }
+        catch { /* skipped, as the daemon skips it when starting the host */ }
+    }
+    return {
+        files: true, readOnlyFilesVersion: 1, filesystemFilesVersion: 1, mediaPreviewVersion: 2, fileFindVersion: 1,
+        home: canonicalHome, userName: os.userInfo().username, roots: [...canonical], downloads: path.join(canonicalHome, 'Downloads'),
+    };
+}

package/dist/workstation/tools/keeperProcess.js

@@ -0,0 +1,124 @@
+import net from 'node:net';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BrowserCore } from './browser.js';
+import os from 'node:os';
+import { privateDirectory } from './client.js';
+import { object, TOOL_REQUEST_BYTES, TOOL_RESULT_BYTES } from './validation.js';
+export async function runKeeper(config) {
+    // Only the browser keeper runs from here (spec §9): keeper-terminal owns PTYs and the files host owns files.
+    if (config.kind !== 'browser')
+        throw new Error('Only the browser keeper runs from this entry');
+    await privateDirectory(path.dirname(config.socket));
+    const pidFile = path.join(path.dirname(config.socket), 'keeper.pid.json');
+    await fs.writeFile(pidFile, JSON.stringify({ pid: process.pid, identity: config.identity }), { mode: 0o600 });
+    const core = await BrowserCore.create({ home: config.home ?? os.homedir(), profileRoot: config.profileRoot, executablePath: config.executablePath, proxy: config.proxy });
+    const sockets = new Set();
+    let pending = 0;
+    const server = net.createServer({ allowHalfOpen: true }, socket => {
+        if (sockets.size >= 32) {
+            socket.destroy();
+            return;
+        }
+        sockets.add(socket);
+        socket.setEncoding('utf8');
+        socket.setTimeout(8000, () => socket.destroy());
+        let buffer = '';
+        let received = false;
+        socket.on('error', () => socket.destroy());
+        socket.on('close', () => sockets.delete(socket));
+        socket.on('data', chunk => {
+            if (received) {
+                socket.destroy();
+                return;
+            }
+            buffer += chunk;
+            if (Buffer.byteLength(buffer) > TOOL_REQUEST_BYTES) {
+                socket.destroy();
+                return;
+            }
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                return;
+            received = true;
+            let frame;
+            try {
+                const value = JSON.parse(buffer.slice(0, newline));
+                if (!object(value) || typeof value.id !== 'string' || value.id.length > 128 || !value.id.length || typeof value.method !== 'string' || !object(value.params) || Object.keys(value).some(key => !['id', 'method', 'params'].includes(key)) || buffer.slice(newline + 1).length)
+                    throw new Error('Invalid keeper request');
+                frame = value;
+            }
+            catch {
+                socket.destroy();
+                return;
+            }
+            const reply = (ok, result, error) => {
+                const payload = JSON.stringify({ id: frame.id, ok, result, error }) + '\n';
+                if (socket.destroyed)
+                    return;
+                if (Buffer.byteLength(payload) > TOOL_RESULT_BYTES) {
+                    socket.destroy();
+                    return;
+                }
+                socket.end(payload);
+            };
+            if (pending >= 32) {
+                reply(false, {}, 'Tools keeper is busy');
+                return;
+            }
+            pending++;
+            void (async () => {
+                try {
+                    const result = frame.method === 'keeper.ping' ? { pid: process.pid, identity: config.identity } : await core.dispatch(frame.method, frame.params);
+                    reply(true, result, null);
+                }
+                catch (error) {
+                    reply(false, {}, (error instanceof Error ? error.message : 'Workstation tool failed').slice(0, 1024));
+                }
+                finally {
+                    pending--;
+                }
+            })();
+        });
+        socket.on('end', () => { if (!received)
+            socket.destroy(); });
+    });
+    try {
+        // A private umask applies before bind; chmod after listen alone would leave a brief broad mode.
+        process.umask(0o077);
+        await new Promise((resolve, reject) => { server.once('error', reject); server.listen(config.socket, resolve); });
+        await fs.chmod(config.socket, 0o600);
+    }
+    catch (error) {
+        await core.dispose();
+        throw error;
+    }
+    return { async stop() {
+            for (const socket of sockets)
+                socket.destroy();
+            await new Promise(resolve => server.close(() => resolve()));
+            await core.dispose();
+            await fs.unlink(config.socket).catch(() => { });
+            await fs.unlink(pidFile).catch(() => { });
+        } };
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    let config;
+    try {
+        config = JSON.parse(Buffer.from(process.argv[2] ?? '', 'base64').toString('utf8'));
+    }
+    catch { /* below */ }
+    // Anti-resurrection (spec §9): only the browser keeper still starts from this entry. A terminal-kind config (kind 'terminal',
+    // or no kind from older CLIs) comes from a legacy tools keeper unit restarting (`Restart=on-failure`) or an old launcher:
+    // keeper-terminal owns PTYs now and the files host owns files, so exit cleanly (0, which systemd does not restart) before
+    // touching the socket, the pid manifest or any state.
+    if (config?.kind !== 'browser')
+        process.exit(0);
+    const keeper = await runKeeper(config);
+    let stopping = false;
+    const stop = () => { if (stopping)
+        return; stopping = true; void keeper.stop().finally(() => process.exit(0)); };
+    process.on('SIGTERM', stop);
+    process.on('SIGINT', stop);
+}

package/dist/workstation/tools/router.js

@@ -0,0 +1,55 @@
+import { isFilesToolMethod } from '../files/adapters/toolRequests.js';
+import { keys, validateRequest } from './validation.js';
+export function routeTool(method) {
+    if (method === 'tools.info')
+        return 'info';
+    if (method === 'browser.sharedText')
+        return 'shared-text';
+    if (isFilesToolMethod(method))
+        return 'files';
+    if (method.startsWith('terminal.'))
+        return 'terminal';
+    if (method.startsWith('browser.'))
+        return 'browser';
+    return 'unsupported';
+}
+/** A probe is answered even while the workstation drains and is not work a restart would interrupt. */
+export function isProbeTool(method) { return routeTool(method) === 'info'; }
+/**
+ * Answered while draining and not counted as a shell task: probes, and `terminal.*` (spec §4.1: a PTY lives in its keeper, not in
+ * the daemon, so a restart does not interrupt it; counting every poll made the activity flicker).
+ */
+export function isUnaccountedTool(method) {
+    const route = routeTool(method);
+    return route === 'info' || route === 'terminal';
+}
+export class WorkstationTools {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** One `tool_request` (not `browser.sharedText`). Rejects with the `tool_result.error` text. */
+    async request(method, params) {
+        // Validated at the daemon boundary as well as by whoever runs it.
+        validateRequest(method, params);
+        switch (routeTool(method)) {
+            case 'info':
+                keys(params, []);
+                return this.deps.info();
+            case 'files': return this.deps.files.tool(method, params);
+            case 'terminal':
+                if (!this.deps.terminal)
+                    throw new Error('Workstation terminal keeper is not configured');
+                return this.deps.terminal(method, params);
+            case 'browser':
+                if (!this.deps.browser)
+                    throw new Error('Workstation browser keeper is not configured');
+                return this.deps.browser(method, params);
+            default: throw new Error('Unsupported workstation tool');
+        }
+    }
+    /** One `file_*_request`; never rejects (errors are result frames). */
+    runFrame(request, signal) {
+        return this.deps.files.runFrame(request, signal);
+    }
+}

package/dist/workstation/tools/terminalRouter.js

@@ -0,0 +1,222 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CREATE_KEYS, PTY_OPERATIONS } from '../keepers/terminal/pty.js';
+import { PTY_SESSION_LIMIT } from '../keepers/terminal/protocol.js';
+import { TERMINAL_NOT_FOUND } from '../keepers/legacy.js';
+import { identifier, integer, keys } from './validation.js';
+const LEGACY = 'legacy';
+/** The single-keeper form of {@link KitGenerations}: one generation named `kit`, running when it answers a hello. */
+function singleKit(kit) {
+    return {
+        servingGeneration: async () => ({ gen: 'kit', client: kit }),
+        running: async () => [{ gen: 'kit', client: kit }],
+    };
+}
+export class TerminalRouter {
+    deps;
+    owners = new Map();
+    kits;
+    /** Clients of the generations seen in the last listing, by generation. */
+    clients = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        if (!deps.kits && !deps.kit)
+            throw new Error('TerminalRouter needs keeper-terminal');
+        this.kits = deps.kits ?? singleKit(deps.kit);
+    }
+    /** The current owner map (tests and diagnostics): `legacy`, or a generation (`kit` with a single keeper-terminal). */
+    ownerOf(id) { return this.owners.get(id); }
+    async request(method, params) {
+        const op = method.startsWith('terminal.') ? method.slice('terminal.'.length) : '';
+        if (op === 'list') {
+            keys(params, []);
+            return { sessions: await this.list() };
+        }
+        if (op === 'create')
+            return { ...await this.create(params) };
+        if (!PTY_OPERATIONS.has(op))
+            throw new Error('Unsupported workstation tool');
+        const id = identifier(params, 'id');
+        const owner = await this.resolveOwner(id);
+        if (!owner)
+            throw new Error(TERMINAL_NOT_FOUND);
+        const kit = owner === LEGACY ? undefined : this.clients.get(owner);
+        if (owner !== LEGACY && !kit)
+            throw new Error(TERMINAL_NOT_FOUND);
+        try {
+            const result = owner === LEGACY
+                ? await this.deps.legacy.request(method, params)
+                : { ...await kit[op].call(kit, params) };
+            if (op === 'close')
+                this.owners.delete(id);
+            return result;
+        }
+        catch (error) {
+            // The owner no longer has it (closed elsewhere, keeper restarted): forget it; the next request looks it up again.
+            if (error instanceof Error && error.message === TERMINAL_NOT_FOUND)
+                this.owners.delete(id);
+            throw error;
+        }
+    }
+    async list() {
+        const { legacy, kits } = await this.refresh();
+        const seen = new Set((legacy ?? []).map((session) => session.id));
+        const out = [...(legacy ?? [])];
+        for (const sessions of kits.values())
+            for (const session of sessions ?? [])
+                if (!seen.has(session.id)) {
+                    seen.add(session.id);
+                    out.push(session);
+                }
+        return out;
+    }
+    /** Lists every side once (keeper-terminal generations only if running) and refreshes the owners of every side that answered. */
+    async refresh() {
+        const [legacy, kits] = await Promise.all([this.legacySessions(), this.kitRefresh()]);
+        if (legacy)
+            this.replaceOwners(LEGACY, legacy);
+        else if (!this.deps.legacy?.live)
+            this.replaceOwners(LEGACY, []);
+        return { legacy, kits };
+    }
+    /**
+     * Lists every running keeper-terminal generation (never starts one) and refreshes their owners: a generation that answered gets
+     * exactly its sessions; one that did not answer keeps its owners; one that is no longer running loses them (its PTYs are gone).
+     */
+    async kitRefresh() {
+        const listed = new Map();
+        let running;
+        try {
+            running = await this.kits.running();
+        }
+        catch {
+            return listed;
+        }
+        await Promise.all(running.map(async ({ gen, client }) => {
+            this.clients.set(gen, client);
+            listed.set(gen, await this.sessionsOf(client));
+        }));
+        for (const [gen, sessions] of listed)
+            if (sessions)
+                this.replaceOwners(gen, sessions);
+        for (const [id, owner] of [...this.owners])
+            if (owner !== LEGACY && !listed.has(owner))
+                this.owners.delete(id);
+        for (const gen of [...this.clients.keys()])
+            if (!listed.has(gen))
+                this.clients.delete(gen);
+        return listed;
+    }
+    replaceOwners(side, sessions) {
+        for (const [id, owner] of this.owners)
+            if (owner === side)
+                this.owners.delete(id);
+        for (const session of sessions)
+            if (side === LEGACY || !this.owners.has(session.id))
+                this.owners.set(session.id, side);
+    }
+    /** The legacy keeper's sessions; `sessions()` probes it first (read-only), so a daemon that just started finds it too. */
+    async legacySessions() {
+        return this.deps.legacy ? this.deps.legacy.sessions() : null;
+    }
+    /** One generation's sessions if it is already running; null when it is not (or did not answer): nothing is started here. */
+    async sessionsOf(client) {
+        try {
+            if (!await client.runningHello())
+                return null;
+            return (await client.list()).sessions;
+        }
+        catch {
+            return null;
+        }
+    }
+    async resolveOwner(id) {
+        const known = this.owners.get(id);
+        if ((known !== undefined && known !== LEGACY && this.clients.has(known)) || (known === LEGACY && this.deps.legacy?.live))
+            return known;
+        await this.refresh();
+        return this.owners.get(id);
+    }
+    async create(params) {
+        // The legacy keeper's checks, wording and order (tools/terminal.ts at the merge-base: id, clientId, keys, cols, rows, name,
+        // then existing, limit, cwd), all before the cwd is resolved.
+        const id = identifier(params, 'id');
+        identifier(params, 'clientId');
+        keys(params, [...CREATE_KEYS]);
+        integer(params, 'cols', 20, 300, 100);
+        integer(params, 'rows', 5, 100, 30);
+        const name = params.name;
+        if (name !== undefined && (typeof name !== 'string' || !name.length || name.length > 128 || /[\x00-\x1f]/.test(name)))
+            throw new Error('Invalid terminal name');
+        const legacy = this.deps.legacy;
+        const knownOwner = this.owners.get(id);
+        if (legacy && (knownOwner === undefined || knownOwner === LEGACY)) {
+            // The legacy keeper never gains a session after the upgrade (creates go to keeper-terminal), so the ids of its first
+            // successful list answer "is this a retry of one of its sessions?" for good — even while it is busy or hung.
+            if (legacy.knownIds === null) {
+                const sessions = await legacy.sessions(); // bounded; null at once when it is busy or absent
+                if (sessions)
+                    this.replaceOwners(LEGACY, sessions);
+            }
+            if (legacy.live && legacy.knownIds?.has(id))
+                return legacy.request('terminal.create', params);
+        }
+        // Duplicate and limit first (the legacy order), against the keeper-terminal generations already running: an idempotent create
+        // (in whichever generation has the id) costs no files-host round trip. keeper-terminal re-checks both when it really creates.
+        const listed = await this.kitRefresh();
+        for (const [gen, sessions] of listed) {
+            const existing = sessions?.find((session) => session.id === id);
+            if (existing) {
+                this.owners.set(id, gen);
+                return existing;
+            }
+        }
+        const serving = await this.kits.servingGeneration();
+        const running = listed.get(serving.gen);
+        if (running && running.length >= PTY_SESSION_LIMIT)
+            throw new Error('Terminal session limit exceeded');
+        if (params.cwd !== undefined && typeof params.cwd !== 'string')
+            throw new Error('Invalid cwd');
+        const launch = await this.deps.launch(params.cwd);
+        const created = await serving.client.create({ ...params, ...launch });
+        this.clients.set(serving.gen, serving.client);
+        this.owners.set(id, serving.gen);
+        return created;
+    }
+}
+/**
+ * The shell a new PTY runs (as a login shell, `-l`): what the legacy keeper chose (`$SHELL`, else the account's shell, else
+ * `/bin/sh`), restricted to an absolute path to an executable file, which keeper-terminal requires.
+ */
+export function terminalShell(env = process.env) {
+    let account;
+    try {
+        account = os.userInfo().shell ?? undefined;
+    }
+    catch { /* no passwd entry (some containers) */ }
+    for (const candidate of [env.SHELL, account, '/bin/sh']) {
+        if (!candidate || !path.isAbsolute(candidate))
+            continue;
+        try {
+            if (statSync(candidate).isFile()) {
+                accessSync(candidate, constants.X_OK);
+                return candidate;
+            }
+        }
+        catch { /* next */ }
+    }
+    return '/bin/sh';
+}
+/**
+ * The environment a new PTY gets: the daemon's own (the legacy keeper gave its own process.env, which was the daemon's when it
+ * was spawned), never the access token (commands/workstation.ts already drops it from the daemon; dropped again here so a
+ * future spawn path cannot leak it). keeper-terminal adds TERM and COLORTERM.
+ */
+export function terminalEnv(env = process.env) {
+    const out = {};
+    for (const [name, value] of Object.entries(env))
+        if (value !== undefined && name !== 'AXOM_ACCESS_TOKEN')
+            out[name] = value;
+    return out;
+}

package/dist/workstation/tools/validation.js

@@ -0,0 +1,86 @@
+/** Bounds apply on both the encrypted channel and private keeper IPC. */
+export const TOOL_REQUEST_BYTES = 128 * 1024;
+export const TOOL_RESULT_BYTES = 2 * 1024 * 1024;
+export const CHUNK_BYTES = 64 * 1024;
+export const TOOL_METHODS = new Set([
+    'browser.list', 'browser.create', 'browser.attach', 'browser.frame', 'browser.navigate', 'browser.input', 'browser.takeover', 'browser.detach', 'browser.close',
+    'tools.info', 'terminal.list', 'terminal.create', 'terminal.attach', 'terminal.poll',
+    'terminal.write', 'terminal.resize', 'terminal.takeover', 'terminal.detach', 'terminal.close',
+    'files.media.prepare', 'files.media.read', 'files.media.cancel',
+    'files.media.open', 'files.media.status', 'files.media.seek', 'files.media.interest', 'files.media.object', 'files.media.release',
+    'files.list', 'files.find', 'files.read', 'files.mkdir', 'files.rename', 'files.delete',
+    'files.upload.begin', 'files.upload.chunk', 'files.upload.finish', 'files.upload.cancel',
+]);
+export function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function keys(params, allowed) {
+    if (Object.keys(params).some(key => !allowed.includes(key)))
+        throw new Error('Unexpected tool parameter');
+}
+export function string(params, name, max = 4096, fallback) {
+    const value = params[name] === undefined ? fallback : params[name];
+    if (typeof value !== 'string' || !value.length || value.includes('\0') || value.length > max)
+        throw new Error(`Invalid ${name}`);
+    return value;
+}
+export function identifier(params, name) {
+    const value = string(params, name, 128);
+    if (!/^[A-Za-z0-9_.:-]+$/.test(value))
+        throw new Error(`Invalid ${name}`);
+    return value;
+}
+export function integer(params, name, min, max, fallback) {
+    const value = params[name] === undefined ? fallback : params[name];
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        throw new Error(`Invalid ${name}`);
+    return value;
+}
+export function base64(value) {
+    if (typeof value !== 'string' || value.length > Math.ceil(CHUNK_BYTES / 3) * 4 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value))
+        throw new Error('Invalid upload chunk');
+    const bytes = Buffer.from(value, 'base64');
+    if (bytes.length > CHUNK_BYTES || bytes.toString('base64') !== value)
+        throw new Error('Invalid upload chunk');
+    return bytes;
+}
+export function validateRequest(method, params) {
+    if (typeof method !== 'string' || !TOOL_METHODS.has(method))
+        throw new Error('Unsupported workstation tool');
+    if (!object(params) || Buffer.byteLength(JSON.stringify(params)) > TOOL_REQUEST_BYTES)
+        throw new Error('Invalid or oversized tool parameters');
+    const shape = MEDIA_SHAPES[method];
+    if (shape) {
+        keys(params, [...shape, 'readOnly', 'filesystem']);
+        string(params, 'path');
+        identifier(params, 'consumerId');
+        if (method !== 'files.media.open' && !/^[a-f0-9]{64}$/.test(string(params, 'version', 64)))
+            throw new Error('Invalid version');
+        for (const flag of ['readOnly', 'filesystem', 'hls', 'playing']) {
+            if (params[flag] !== undefined && typeof params[flag] !== 'boolean')
+                throw new Error(`Invalid ${flag}`);
+        }
+        if (method === 'files.media.open' && typeof params.hls !== 'boolean')
+            throw new Error('Invalid hls');
+        if (method === 'files.media.seek' || method === 'files.media.interest')
+            integer(params, 'positionMs', 0, 21_600_000);
+        if (method === 'files.media.seek')
+            integer(params, 'revision', 0, Number.MAX_SAFE_INTEGER);
+        if (method === 'files.media.interest' && typeof params.playing !== 'boolean')
+            throw new Error('Invalid playing');
+        if (method === 'files.media.object') {
+            if (!/^[A-Za-z0-9_-]+$/.test(string(params, 'objectId', 128)))
+                throw new Error('Invalid objectId');
+            integer(params, 'offset', 0, Number.MAX_SAFE_INTEGER);
+            integer(params, 'length', 1, 256 * 1024);
+        }
+    }
+}
+const MEDIA_SHAPES = {
+    'files.media.open': ['path', 'consumerId', 'hls'],
+    'files.media.status': ['path', 'version', 'consumerId'],
+    'files.media.seek': ['path', 'version', 'consumerId', 'positionMs', 'revision'],
+    'files.media.interest': ['path', 'version', 'consumerId', 'positionMs', 'playing'],
+    'files.media.object': ['path', 'version', 'consumerId', 'objectId', 'offset', 'length'],
+    'files.media.release': ['path', 'version', 'consumerId'],
+};

package/dist/workstation/update/coordinator.js

@@ -93,6 +93,14 @@ export class UpdateCoordinator {
         await this.transition({ ...this.status, phase: 'SUCCEEDED' });
     }
     async ensureInitialized() {
+        // Concurrent callers must share one in-flight attempt (assigned synchronously below, before
+        // any `await`), but a *rejected* attempt must not stay memoized: a transient failure here --
+        // the state dir being unwritable while the daemon died mid-update, say -- would otherwise wedge
+        // this coordinator forever, since every future `handle`/`snapshotAsync`/`managementReady` call
+        // awaits the same rejected promise and never gets a chance to retry. Clearing `this.initialized`
+        // only happens inside this same promise's own `.catch`, i.e. strictly after it has settled, so
+        // callers that started awaiting it while it was still in flight all observe the same outcome;
+        // only a call that arrives *after* it has rejected gets to start a fresh attempt.
         if (!this.initialized)
             this.initialized = this.options.state.load().then(async (saved) => {
                 if (!saved)
@@ -113,7 +121,28 @@ export class UpdateCoordinator {
                     catch { /* a broken logger must not fail a boot */ }
                     return;
                 }
+                // Any other non-terminal phase was written by a process that no longer exists: the execute()
+                // that owned it died with the previous daemon, so nothing will ever advance it. Adopting it
+                // verbatim makes handle() answer every later command with UPDATE_IN_PROGRESS while the
+                // heartbeat repeats the stale phase to the server forever -- the same permanent wedge the
+                // RESTARTING branch above exists to prevent, reachable by killing the daemon at any earlier
+                // point (a laptop shut mid-download, an operator's restart mid-drain). RESTARTING is the one
+                // deliberate exception in every lifecycle: the successor is *expected* to adopt it and let
+                // management_ready promote it (or the armed watchdog fail it).
+                if (!isTerminalPhase(saved.phase) && saved.phase !== 'RESTARTING') {
+                    this.status = { ...saved, phase: 'FAILED', error: `process restarted during '${saved.phase}'; the update never completed` };
+                    await this.options.state.save(this.status);
+                    // Reported like any other transition, for the same reason the container branch is.
+                    try {
+                        this.options.onPhase?.(this.status);
+                    }
+                    catch { /* a broken logger must not fail a boot */ }
+                    return;
+                }
                 this.status = saved;
+            }).catch((error) => {
+                this.initialized = null;
+                throw error;
             });
         await this.initialized;
     }
@@ -224,6 +253,9 @@ export class UpdateCoordinator {
                     this.options.tasks.accepting = true;
                 return this.transition(this.base(command, 'SUCCEEDED'));
             }
+            // Keeper-hosted agent sessions outlive this process: detach them first (head checkpoint, adapter untouched — no
+            // `session/cancel`, no failed turn), so the next daemon adopts them where they are (spec §5.5.5).
+            await this.options.tasks.detachDurableSessions();
             await this.options.restart();
             return restarting;
         }

package/dist/workstation/update/npmInstaller.js

@@ -1,5 +1,6 @@
 import { spawn as nodeSpawn } from 'node:child_process';
 import { redactPaths, redactSecrets } from './redact.js';
+import { verifyOptionalPty } from './watchdog.js';
 const STDERR_LIMIT = 4096;
 function absolute(value, field) {
     if (!value.startsWith('/') || /[\u0000-\u001f\u007f]/.test(value))
@@ -47,6 +48,7 @@ export class NpmInstaller {
                     reject(new Error(`npm install failed: ${sanitizeNpmError(stderr) || `exit ${code ?? signal ?? 'unknown'}`}`));
             });
         });
+        await verifyOptionalPty(this.options.npmPrefix, this.spawn);
     }
     /** Packs the installed package locally; `--json` gives npm's own name/version validation input. */
     async pack(packageRoot, destination) {

package/dist/workstation/update/ptyPreflight.js

@@ -0,0 +1,45 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { PTY_UNAVAILABLE_ERROR } from '../keepers/terminal/protocol.js';
+const require = createRequire(import.meta.url);
+/**
+ * Says once, at daemon start, when the installed CLI's optional `node-pty` does not load. There is
+ * no repair to attempt: the pinned node-pty ships prebuilds for every desktop target, so a load
+ * failure means an unsupported platform (musl, an older glibc), not a missing build step.
+ */
+export async function preflightOptionalPty(context, deps = {}) {
+    const installedRoot = path.join(context.npmPrefix, process.platform === 'win32' ? 'node_modules' : 'lib/node_modules', '@platless/axom-cli');
+    // Source checkouts and custom unpacked installations load their own node-pty; nothing to report.
+    if (path.resolve(installedRoot) !== path.resolve(context.packageRoot))
+        return;
+    const addon = path.join(installedRoot, 'node_modules/node-pty');
+    try {
+        (deps.load ?? require)(addon);
+    }
+    catch (error) {
+        // An explicitly omitted optional dependency is not a problem worth a warning.
+        if (error.code === 'MODULE_NOT_FOUND' && String(error.message).includes(addon))
+            return;
+        (deps.warn ?? console.warn)('[daemon] Optional node-pty does not load on this platform; the terminal tool stays unavailable.');
+    }
+}
+export { PTY_UNAVAILABLE_ERROR };
+/**
+ * A cached load check of the node-pty copy the terminal would use (the same `require('node-pty')` from this package),
+ * done at most once per daemon. Answering `tools.info` must never start a keeper just to learn this.
+ */
+export function cachedPtyStatus(load = () => require('node-pty')) {
+    let status;
+    return () => {
+        if (status)
+            return status;
+        try {
+            load();
+            status = { terminal: true };
+        }
+        catch {
+            status = { terminal: false, terminalError: PTY_UNAVAILABLE_ERROR };
+        }
+        return status;
+    };
+}