@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/systemMetrics.js

@@ -2,8 +2,8 @@ import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { readFileSync, statfsSync, statSync } from 'node:fs';
 import os from 'node:os';
-import path from 'node:path';
 import { promisify } from 'node:util';
+import { discoverStoragePools } from './storageMetrics.js';
 const execFileAsync = promisify(execFile);
 export const STORAGE_TOPOLOGY_REFRESH_MS = 10 * 60 * 1000;
 function cpuTotals(cpus) {
@@ -36,45 +36,6 @@ function linuxMemoryPressure(readFile) {
 function stablePoolId(key) {
     return createHash('sha256').update(key).digest('hex').slice(0, 16);
 }
-async function defaultIdentifyStorage(platform, cwd, device) {
-    try {
-        if (platform === 'darwin') {
-            const mounted = await execFileAsync('/bin/df', ['-P', cwd], {
-                timeout: 1_000,
-                env: { ...process.env, LC_ALL: 'C' },
-            });
-            const mountFields = mounted.stdout.trim().split('\n').at(-1)?.trim().split(/\s+/) ?? [];
-            const mountPoint = mountFields.slice(5).join(' ') || path.parse(cwd).root;
-            const { stdout } = await execFileAsync('/usr/sbin/diskutil', ['info', mountPoint], {
-                timeout: 1_000,
-                env: { ...process.env, LC_ALL: 'C' },
-            });
-            const container = /^\s*APFS Container Reference:\s*(\S+)\s*$/m.exec(stdout)?.[1];
-            const volume = /^\s*Volume Name:\s*(.+?)\s*$/m.exec(stdout)?.[1];
-            return container
-                ? { key: `apfs:${container}`, label: `APFS Container ${container}` }
-                : { key: `dev:${device}`, label: volume };
-        }
-        if (platform === 'linux') {
-            const { stdout } = await execFileAsync('findmnt', ['-n', '-P', '-o', 'FSTYPE,SOURCE,UUID,LABEL,TARGET', '--target', cwd], {
-                timeout: 2_000,
-                env: { ...process.env, LC_ALL: 'C' },
-            });
-            const fields = Object.fromEntries([...stdout.matchAll(/(\w+)="([^"]*)"/g)].map((match) => [match[1], match[2]]));
-            if (fields.FSTYPE === 'btrfs' && fields.UUID)
-                return { key: `btrfs:${fields.UUID}`, label: fields.SOURCE };
-            if (fields.FSTYPE === 'zfs' && fields.SOURCE) {
-                const pool = fields.SOURCE.split('/')[0];
-                return { key: `zfs:${pool}`, label: pool };
-            }
-            return { key: `dev:${device}`, label: fields.LABEL || fields.TARGET || fields.SOURCE };
-        }
-    }
-    catch {
-        // Resource-pool recognition is best-effort. Device identity below is the conservative fallback.
-    }
-    return { key: `dev:${device}` };
-}
 async function defaultDarwinAvailableMemory() {
     try {
         const { stdout } = await execFileAsync('/usr/bin/vm_stat', [], { timeout: 2_000 });
@@ -100,6 +61,97 @@ async function defaultDarwinMemoryPressure() {
         return null;
     }
 }
+/**
+ * Parses `ioreg -r -d 1 -w 0 -c AGXAccelerator` output. Apple Silicon publishes live GPU
+ * utilization (`Device Utilization %`, a driver-side running average) and GPU-resident unified
+ * memory (`In use system memory`) in each accelerator's `PerformanceStatistics`, without any
+ * privileges. Intel Macs expose no `AGXAccelerator` class, so they parse to null.
+ */
+export function parseAppleAgxStats(output) {
+    const gpus = output.split('+-o ').slice(1).map((block, index) => {
+        const stats = /"PerformanceStatistics"\s*=\s*\{([^}]*)\}/.exec(block)?.[1];
+        if (stats === undefined)
+            return null;
+        const utilizationPercent = Number(/"Device Utilization %"\s*=\s*(\d+(?:\.\d+)?)/.exec(stats)?.[1]);
+        const memoryUsedBytes = Number(/"In use system memory"\s*=\s*(\d+)/.exec(stats)?.[1]);
+        return {
+            id: `apple:agx-${index}`,
+            name: /"model"\s*=\s*"([^"]+)"/.exec(block)?.[1] ?? 'Apple GPU',
+            utilization: Number.isFinite(utilizationPercent)
+                ? Math.max(0, Math.min(1, utilizationPercent / 100))
+                : null,
+            memoryTotalBytes: null,
+            memoryUsedBytes: Number.isFinite(memoryUsedBytes) && memoryUsedBytes >= 0 ? memoryUsedBytes : null,
+            coreCount: (() => {
+                const cores = Number(/"gpu-core-count"\s*=\s*(\d+)/.exec(block)?.[1]);
+                return Number.isFinite(cores) && cores > 0 ? cores : null;
+            })(),
+        };
+    }).filter((gpu) => gpu !== null);
+    return gpus.length > 0 ? gpus : null;
+}
+async function appleAgxGpuProbe() {
+    try {
+        const { stdout } = await execFileAsync('/usr/sbin/ioreg', ['-r', '-d', '1', '-w', '0', '-c', 'AGXAccelerator'], {
+            timeout: 2_000,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        return parseAppleAgxStats(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/** Parses `nvidia-smi --query-gpu=... --format=csv,noheader,nounits` output; `[N/A]` reads as null. */
+export function parseNvidiaSmiGpus(output) {
+    const mib = (field) => {
+        if (field === undefined)
+            return null;
+        const value = Number(field);
+        return Number.isFinite(value) && value >= 0 ? Math.round(value * 1024 * 1024) : null;
+    };
+    const gpus = output.split(/\r?\n/).map((line) => {
+        const fields = line.split(',').map((field) => field.trim());
+        if (fields.length < 6)
+            return null;
+        const [, uuid, name, utilizationField, totalField, usedField] = fields;
+        if (!/^GPU-/.test(uuid) || name.length === 0)
+            return null;
+        const utilizationPercent = Number(utilizationField);
+        return {
+            id: `nvidia:${uuid}`,
+            name,
+            utilization: Number.isFinite(utilizationPercent)
+                ? Math.max(0, Math.min(1, utilizationPercent / 100))
+                : null,
+            memoryTotalBytes: mib(totalField),
+            memoryUsedBytes: mib(usedField),
+            coreCount: null,
+        };
+    }).filter((gpu) => gpu !== null);
+    return gpus.length > 0 ? gpus : null;
+}
+async function nvidiaSmiGpuProbe() {
+    try {
+        const { stdout } = await execFileAsync('nvidia-smi', [
+            '--query-gpu=index,uuid,name,utilization.gpu,memory.total,memory.used',
+            '--format=csv,noheader,nounits',
+        ], { timeout: 3_000 });
+        return parseNvidiaSmiGpus(stdout);
+    }
+    catch {
+        // Absent binary, driver hiccup, or unsupported GPU -- all read as "no reading", never as failure.
+        return null;
+    }
+}
+async function defaultProbeGpus(platform) {
+    const [apple, nvidia] = await Promise.all([
+        platform === 'darwin' ? appleAgxGpuProbe() : Promise.resolve(null),
+        nvidiaSmiGpuProbe(),
+    ]);
+    const gpus = [...(apple ?? []), ...(nvidia ?? [])];
+    return gpus.length > 0 ? gpus : null;
+}
 /**
  * Low-overhead host sampler. CPU and memory are read only while a heartbeat is being built; storage
  * topology is discovered out of band and capacity reads use the cached representative paths.
@@ -114,6 +166,8 @@ export class SystemMetricsSampler {
     darwinMemoryRefreshInFlight = null;
     darwinMemoryAvailable = null;
     darwinMemoryPressure = null;
+    gpuRefreshInFlight = null;
+    gpus = null;
     constructor(workspaces, deps = {
         platform: process.platform,
         cpus: os.cpus,
@@ -123,15 +177,16 @@ export class SystemMetricsSampler {
         readFile: readFileSync,
         statfs: statfsSync,
         stat: statSync,
-        identifyStorage: (cwd, device) => defaultIdentifyStorage(process.platform, cwd, device),
+        discoverStorage: () => discoverStoragePools(process.platform, workspaces),
         darwinAvailableMemory: defaultDarwinAvailableMemory,
         darwinMemoryPressure: defaultDarwinMemoryPressure,
+        probeGpus: () => defaultProbeGpus(process.platform),
     }) {
         this.workspaces = workspaces;
         this.deps = deps;
     }
     async start() {
-        await Promise.all([this.refreshTopology(), this.refreshDarwinMemory()]);
+        await Promise.all([this.refreshTopology(), this.refreshDarwinMemory(), this.refreshGpus()]);
         this.refreshTimer = setInterval(() => this.refreshTopologyInBackground(), STORAGE_TOPOLOGY_REFRESH_MS);
         this.refreshTimer.unref();
     }
@@ -143,6 +198,7 @@ export class SystemMetricsSampler {
     snapshot() {
         try {
             this.refreshDarwinMemoryInBackground();
+            this.refreshGpusInBackground();
             const cpus = this.deps.cpus();
             const currentCpu = cpuTotals(cpus);
             const previousCpu = this.previousCpu;
@@ -166,20 +222,23 @@ export class SystemMetricsSampler {
                 : (this.deps.platform === 'darwin' ? this.darwinMemoryPressure : null);
             const pools = new Map();
             for (const pool of this.storage) {
-                try {
-                    const stats = this.deps.statfs(pool.cwd);
-                    const totalBytes = Number(stats.blocks) * Number(stats.bsize);
-                    const availableBytes = Number(stats.bavail) * Number(stats.bsize);
-                    pools.set(pool.key, {
-                        id: stablePoolId(pool.key),
-                        label: pool.label,
-                        workspaces: pool.workspaces,
-                        totalBytes,
-                        availableBytes,
-                    });
-                }
-                catch {
-                    // A removed/unmounted workspace must not suppress CPU and memory metrics.
+                for (const cwd of pool.paths) {
+                    try {
+                        if (String(this.deps.stat(cwd).dev) !== pool.devices[cwd])
+                            continue;
+                        const stats = this.deps.statfs(cwd);
+                        const totalBytes = Number(stats.blocks) * Number(stats.bsize);
+                        const availableBytes = Number(stats.bavail) * Number(stats.bsize);
+                        pools.set(pool.key, {
+                            id: stablePoolId(pool.key),
+                            label: pool.label,
+                            workspaces: pool.workspaces,
+                            totalBytes,
+                            availableBytes,
+                        });
+                        break;
+                    }
+                    catch { }
                 }
             }
             return {
@@ -192,6 +251,7 @@ export class SystemMetricsSampler {
                 memoryTotalBytes,
                 memoryAvailableBytes,
                 storagePools: [...pools.values()],
+                gpus: this.gpus,
             };
         }
         catch {
@@ -218,6 +278,19 @@ export class SystemMetricsSampler {
                 this.darwinMemoryRefreshInFlight = null;
         });
     }
+    refreshGpusInBackground() {
+        if (this.gpuRefreshInFlight)
+            return;
+        const refresh = this.refreshGpus();
+        this.gpuRefreshInFlight = refresh;
+        void refresh.finally(() => {
+            if (this.gpuRefreshInFlight === refresh)
+                this.gpuRefreshInFlight = null;
+        });
+    }
+    async refreshGpus() {
+        this.gpus = await this.deps.probeGpus().catch(() => null);
+    }
     async refreshDarwinMemory() {
         if (this.deps.platform !== 'darwin')
             return;
@@ -229,43 +302,31 @@ export class SystemMetricsSampler {
         this.darwinMemoryPressure = pressure;
     }
     async refreshTopology() {
-        const candidates = this.workspaces.map(({ name, cwd }) => {
-            try {
-                this.deps.statfs(cwd);
-                const device = String(this.deps.stat(cwd).dev);
-                return { name, cwd, device };
-            }
-            catch {
-                return null;
-            }
-        }).filter((candidate) => candidate !== null);
-        const representatives = new Map();
-        candidates.forEach(({ cwd, device }) => {
-            if (!representatives.has(device))
-                representatives.set(device, { cwd, device });
-        });
-        const identities = new Map(await Promise.all([...representatives.values()].map(async ({ cwd, device }) => [
-            device,
-            await this.deps.identifyStorage(cwd, device).catch(() => null),
-        ])));
-        const identified = candidates.map(({ name, cwd, device }) => {
-            try {
-                const identity = identities.get(device);
-                const key = identity?.key ?? `dev:${device}`;
-                return { name, cwd, key, label: identity?.label || path.parse(cwd).root || cwd };
-            }
-            catch {
-                return null;
-            }
-        });
-        const grouped = new Map();
-        for (const entry of identified.filter((candidate) => candidate !== null)) {
-            const existing = grouped.get(entry.key);
-            if (existing)
-                existing.workspaces.push(entry.name);
-            else
-                grouped.set(entry.key, { cwd: entry.cwd, key: entry.key, label: entry.label, workspaces: [entry.name] });
+        try {
+            const pools = await this.deps.discoverStorage();
+            this.storage = pools.map((pool) => {
+                const devices = Object.fromEntries(pool.paths.flatMap((cwd) => {
+                    try {
+                        return [[cwd, String(this.deps.stat(cwd).dev)]];
+                    }
+                    catch {
+                        return [];
+                    }
+                }));
+                const poolDevices = new Set(Object.values(devices));
+                const workspaces = this.workspaces.filter(({ cwd }) => {
+                    try {
+                        return poolDevices.has(String(this.deps.stat(cwd).dev));
+                    }
+                    catch {
+                        return false;
+                    }
+                }).map(({ name }) => name);
+                return { ...pool, workspaces, devices };
+            });
+        }
+        catch {
+            return;
         }
-        this.storage = [...grouped.values()];
     }
 }

package/dist/workstation/toolchain.js

@@ -0,0 +1,94 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+const PROBE_TIMEOUT_MS = 10_000;
+const VERIFY_TIMEOUT_MS = 3_000;
+/** Interpreters rarely appear or vanish; a slow refresh keeps the heartbeat itself free of any spawning. */
+export const TOOLCHAIN_REFRESH_MS = 15 * 60_000;
+/**
+ * Shells whose `-lc` runs a POSIX-ish command string with `command -v` (fish ≥ 3 included). Any other shell (csh, tcsh,
+ * nu, pwsh, …) is not probed: its answer is unknown, never "missing".
+ */
+const PROBED_SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'mksh', 'fish']);
+/** Separates the probe's answers; no leading `=` (zsh would expand a bare `=word`). */
+const SPLIT = 'AXOM-PROBE-SPLIT';
+const DONE = 'AXOM-PROBE-DONE';
+const NAMES = ['python3', 'python', 'node'];
+/**
+ * One `<shell> -lc` run of `command -v` for each interpreter, the way commands run on this workstation (exec spawns the
+ * same login shell), so a Python found only through the user's profile counts. Each answer is the last absolute-path
+ * line of its segment (a login profile may print its own lines first). Null = unknown: a shell we do not probe, a shell
+ * that could not run, or a run that did not reach its end marker.
+ */
+export async function probeToolchain(shell, env = process.env, options = {}) {
+    if (!PROBED_SHELLS.has(path.basename(shell)))
+        return null;
+    const script = [...NAMES.map((name) => `command -v ${name}`), `echo ${DONE}`].join(`; echo ${SPLIT}; `);
+    const stdout = await run(shell, ['-lc', script], env, PROBE_TIMEOUT_MS);
+    if (stdout === undefined)
+        return null;
+    const lines = stdout.split('\n').map((line) => line.trim());
+    const doneAt = lines.lastIndexOf(DONE);
+    if (doneAt < 0)
+        return null;
+    const segments = [[]];
+    for (const line of lines.slice(0, doneAt)) {
+        if (line === SPLIT)
+            segments.push([]);
+        else
+            segments[segments.length - 1].push(line);
+    }
+    // `command -v python3; echo SPLIT; …; echo SPLIT; echo DONE`: one segment per name, then an empty one. A login
+    // profile's own output lands in the first segment, before the answer, so each answer is its segment's last path.
+    if (segments.length !== NAMES.length + 1)
+        return null;
+    const answers = segments.slice(0, NAMES.length);
+    const found = (index) => [...answers[index]].reverse().find((line) => path.isAbsolute(line)) ?? null;
+    let python3 = found(0);
+    if (python3 === '/usr/bin/python3' && (options.platform ?? process.platform) === 'darwin') {
+        if (!(await (options.macStubRuns ?? macCommandLineToolsInstalled)()))
+            python3 = null;
+    }
+    return { python: python3 ?? found(1), node: found(2) };
+}
+async function macCommandLineToolsInstalled() {
+    return (await run('/usr/bin/xcode-select', ['-p'], process.env, VERIFY_TIMEOUT_MS, true)) !== undefined;
+}
+/** The command's stdout; undefined = it did not run, timed out, or (with [strict]) exited non-zero. */
+function run(file, args, env, timeout, strict = false) {
+    return new Promise((resolve) => {
+        execFile(file, args, { env, timeout, windowsHide: true }, (error, stdout) => {
+            const code = error?.code;
+            if (error && (strict || typeof code !== 'number')) {
+                resolve(undefined);
+                return;
+            }
+            resolve(String(stdout));
+        });
+    });
+}
+/** Holds the latest probe; the first answer arrives shortly after start, until then the heartbeat simply omits it. */
+export class ToolchainProbe {
+    shell;
+    env;
+    latest = null;
+    timer;
+    constructor(shell, env = () => process.env) {
+        this.shell = shell;
+        this.env = env;
+    }
+    current() { return this.latest; }
+    start() {
+        if (process.platform === 'win32' || this.timer)
+            return;
+        const refresh = async () => {
+            const found = await probeToolchain(this.shell(), this.env()).catch(() => null);
+            if (found)
+                this.latest = found;
+        };
+        void refresh();
+        this.timer = setInterval(() => { void refresh(); }, TOOLCHAIN_REFRESH_MS);
+        this.timer.unref();
+    }
+    stop() { if (this.timer)
+        clearInterval(this.timer); this.timer = undefined; }
+}

package/dist/workstation/tools/browser.js

@@ -17,13 +17,31 @@ async function bounded(promise, timeout = TIMEOUT) {
         clearTimeout(timer);
     }
 }
-/** All ancestors are checked: mkdir recursive must never follow a planted profile symlink. */
+/**
+ * All ancestors are checked: mkdir recursive must never follow a planted profile symlink. The one
+ * symlinks allowed across are root-owned system symlinks (`/var -> /private/var` on macOS): stock
+ * macOS tmp dirs sit behind one, and refusing it would reject every per-user tmpdir. A root-owned
+ * symlink whose target is a root-owned, non-group-writable directory is not plantable by the user
+ * this runs as; anything else — every user-owned symlink — still fails the check below.
+ */
 async function ownedDirectory(dir, privateMode = false) {
     const absolute = path.resolve(dir);
     const parts = absolute.split(path.sep).filter(Boolean);
     let current = path.parse(absolute).root;
     const uid = process.getuid?.();
     let protectedByOwner = false;
+    const systemSymlink = async (stat) => {
+        if (stat.uid !== 0 || uid === 0)
+            return false;
+        try {
+            const target = await fs.realpath(current);
+            const targetStat = await fs.lstat(target);
+            return targetStat.isDirectory() && targetStat.uid === 0 && (targetStat.mode & 0o022) === 0;
+        }
+        catch {
+            return false;
+        }
+    };
     for (const part of parts) {
         current = path.join(current, part);
         await fs.mkdir(current, { mode: 0o700 }).catch((e) => {
@@ -31,8 +49,14 @@ async function ownedDirectory(dir, privateMode = false) {
                 throw e;
         });
         const stat = await fs.lstat(current);
+        if (stat.isSymbolicLink()) {
+            if (!(await systemSymlink(stat)))
+                throw Error("Unsafe browser directory");
+            // Root-owned system symlink: cross it; the link itself carries no mode or ownership
+            // expectation (Linux reports links 0777), its target was just verified.
+            continue;
+        }
         if (!stat.isDirectory() ||
-            stat.isSymbolicLink() ||
             (!protectedByOwner &&
                 (stat.mode & 0o022) !== 0 &&
                 !(stat.mode & 0o1000)) ||
@@ -44,11 +68,11 @@ async function ownedDirectory(dir, privateMode = false) {
         if (uid !== undefined && stat.uid === uid && (stat.mode & 0o077) === 0)
             protectedByOwner = true;
     }
-    const stat = await fs.lstat(absolute);
+    const stat = await fs.lstat(current);
     if (process.getuid && stat.uid !== process.getuid())
         throw Error("Browser directory is not owned by this user");
     if (privateMode)
-        await fs.chmod(absolute, 0o700);
+        await fs.chmod(current, 0o700);
 }
 function allowedUrl(params) {
     const url = string(params, "url", 8192, "about:blank");

package/dist/workstation/tools/client.js

@@ -84,15 +84,23 @@ function pidAlive(pid) {
         return error.code === 'EPERM';
     }
 }
+/**
+ * A tools keeper client. The daemon only ever makes the browser kind (`browser`). The kind is required — no default — so nothing can
+ * start the retired terminal-kind tools keeper by accident (spec §9; terminals run in keeper-terminal, files in the daemon's files
+ * host); an explicit `terminal` client exists only for the tests that pin how the retired keeper's startup and tools.info behave.
+ * (`keeperPaths` keeps its terminal default: `keepers/legacy.ts` finds a legacy tools keeper an older CLI left running by it.)
+ */
 export class ToolsClient {
     options;
     kind;
     paths;
     starting;
     browser;
-    constructor(options, kind = 'terminal') {
+    constructor(options, kind) {
         this.options = options;
         this.kind = kind;
+        if (kind !== 'terminal' && kind !== 'browser')
+            throw new Error('ToolsClient needs an explicit kind (browser)');
         this.paths = keeperPaths(options, undefined, undefined, kind);
     }
     async probe(timeoutMs = 250) {

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

@@ -2,18 +2,18 @@ import net from 'node:net';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { ToolsCore } from './core.js';
 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 = config.kind === 'browser' ? await BrowserCore.create({ home: config.home ?? os.homedir(), profileRoot: config.profileRoot, executablePath: config.executablePath, proxy: config.proxy }) : await ToolsCore.create({ home: config.home, roots: config.roots, uploadStateDir: path.join(path.dirname(config.socket), 'uploads') });
-    if (config.kind !== 'browser')
-        process.chdir(path.dirname(config.socket));
+    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 => {
@@ -104,7 +104,17 @@ export async function runKeeper(config) {
         } };
 }
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-    const config = JSON.parse(Buffer.from(process.argv[2] ?? '', 'base64').toString('utf8'));
+    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)

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);
+    }
+}