@prohost/cli 0.15.0 → 0.16.0

package/dist/host/install.js

@@ -0,0 +1,755 @@
+/**
+ * `prohost host install` / `uninstall` — the background service, per OS,
+ * installed by the CLI itself.
+ *
+ * | | Personal (default) | Dedicated (`--dedicated --service-user <name>`) |
+ * | --- | --- | --- |
+ * | macOS | LaunchAgent `ai.prohost.host` (runs while you're logged in) | LaunchDaemon in `/Library/LaunchDaemons`, `UserName` = the service user |
+ * | Linux | systemd user unit `prohost-host.service` | system unit in `/etc/systemd/system`, `User=` the service user |
+ * | Windows | Task Scheduler task at logon | Task Scheduler task at boot running as the service user (S4U: no password stored) |
+ *
+ * Dedicated mode keeps working when no one is logged in; it must be run as
+ * root / an administrator. On Windows it is a boot-start scheduled task rather
+ * than a Windows service: Node cannot answer the Service Control Manager
+ * without a native wrapper, and an S4U task gives the same "runs whether or
+ * not anyone is logged on" without storing a password.
+ *
+ * Every variant runs `node <cli> host run` with this shell's `PATH` and the
+ * service's `PROHOST_HOME`, restarts it when it exits (an update drains and
+ * exits on purpose), and appends to `$PROHOST_HOME/host/host.log`.
+ */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { buildLaunchdPlist, waitUntilUnloaded } from '../agent/daemon.js';
+export const LAUNCHD_HOST_LABEL = 'ai.prohost.host';
+export const SYSTEMD_HOST_UNIT = 'prohost-host.service';
+export const WINDOWS_TASK_NAME = '\\ProhostAI\\Host';
+/** launchd / systemd wait this long after SIGTERM: the service drains (finishes runs going) first. */
+export const STOP_TIMEOUT_SECONDS = 600;
+/**
+ * How long a macOS re-install waits for the previous service to leave launchd
+ * before bootstrapping the new one: its whole drain, plus a margin. Bootstrapping
+ * sooner fails, and would leave the computer with no service once the old one exits.
+ */
+export const RESTART_WAIT_MS = (STOP_TIMEOUT_SECONDS + 30) * 1000;
+/** Set in a dedicated service's environment: where it publishes its state for the logged-in user. */
+export const SHARED_DIR_ENV = 'PROHOST_HOST_SHARED_DIR';
+/** The `claude setup-token` token a dedicated install hands the service user (read by `host run`). */
+export const CLAUDE_TOKEN_FILE = 'claude-oauth-token';
+export const defaultServiceRunner = (command, args, input) => {
+    const result = spawnSync(command, args, { encoding: 'utf8', ...(input !== undefined ? { input } : {}) });
+    return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? result.error?.message ?? '' };
+};
+const SERVICE_USER = /^[A-Za-z0-9._-][A-Za-z0-9._ -]{0,63}$/;
+const LABEL = /^[A-Za-z0-9][A-Za-z0-9.-]{0,127}$/;
+/** Paths for the OS the service is for (tests build every OS's files on one). */
+function joinFor(platform) {
+    return platform === 'win32' ? path.win32.join : path.posix.join;
+}
+/** The label for a home: the plain one for the default home, else one with a short digest of the home. */
+export function defaultLabel(home, defaultHome) {
+    if (path.resolve(home) === path.resolve(defaultHome))
+        return LAUNCHD_HOST_LABEL;
+    return `${LAUNCHD_HOST_LABEL}.${createHash('sha256').update(path.resolve(home)).digest('hex').slice(0, 8)}`;
+}
+export function labelOf(spec) {
+    return spec.label ?? LAUNCHD_HOST_LABEL;
+}
+export function systemdUnitOf(spec) {
+    const label = labelOf(spec);
+    return label === LAUNCHD_HOST_LABEL ? SYSTEMD_HOST_UNIT : `${label}.service`;
+}
+export function windowsTaskOf(spec) {
+    const label = labelOf(spec);
+    return label === LAUNCHD_HOST_LABEL ? WINDOWS_TASK_NAME : `\\ProhostAI\\${label}`;
+}
+export function serviceArgs(spec) {
+    return [spec.nodePath, spec.scriptPath, 'host', 'run'];
+}
+/** Where a dedicated service publishes its state, read by `host status` as the logged-in user. */
+export function sharedBase(platform) {
+    if (platform === 'darwin')
+        return '/Library/Application Support/Prohost/hosts';
+    if (platform === 'win32')
+        return 'C:\\ProgramData\\Prohost\\hosts';
+    return '/var/lib/prohost/hosts';
+}
+export function sharedDirFor(spec) {
+    return joinFor(spec.platform)(sharedBase(spec.platform), labelOf(spec));
+}
+/**
+ * Where the service logs. Personal: `$PROHOST_HOME/host/host.log`. Dedicated:
+ * never under the service user's home — the service manager opens the log as
+ * root, and a link planted there would point root at any file. macOS: a
+ * root-owned `/Library/Logs/Prohost`; Windows: an ACL'd `ProgramData` folder;
+ * Linux: the journal (`undefined`: no file).
+ */
+export function logPathFor(spec) {
+    if (!spec.dedicated)
+        return joinFor(spec.platform)(spec.home, 'host', 'host.log');
+    if (spec.platform === 'darwin')
+        return `/Library/Logs/Prohost/${labelOf(spec)}.log`;
+    if (spec.platform === 'win32')
+        return path.win32.join('C:\\ProgramData\\Prohost\\Logs', `${labelOf(spec)}.log`);
+    return undefined;
+}
+/** The environment the service runs with. */
+export function serviceEnv(spec) {
+    return {
+        PATH: spec.pathEnv,
+        PROHOST_HOME: spec.home,
+        ...(spec.dedicated ? { PROHOST_HOST_DEDICATED: '1', [SHARED_DIR_ENV]: sharedDirFor(spec) } : {}),
+        ...(spec.dedicated && spec.platform === 'darwin' && spec.serviceUser
+            ? { HOME: path.posix.join('/Users', spec.serviceUser) }
+            : {}),
+        ...(spec.dedicated && spec.platform === 'win32' ? { PROHOST_CLAUDE_TOKEN_FILE: windowsTokenPath(spec) } : {}),
+        // Electron as Node: without this, the service would start the desktop app.
+        ...(spec.electron ? { ELECTRON_RUN_AS_NODE: '1', PROHOST_CLI_RUN: '1' } : {}),
+    };
+}
+/** Where the service definition lives. */
+export function serviceFilePath(spec) {
+    const label = labelOf(spec);
+    if (spec.platform === 'darwin') {
+        return spec.dedicated
+            ? path.join('/Library/LaunchDaemons', `${label}.plist`)
+            : path.join(spec.userHome, 'Library', 'LaunchAgents', `${label}.plist`);
+    }
+    if (spec.platform === 'win32') {
+        return spec.dedicated
+            ? path.win32.join(windowsServiceDir(spec), 'task.xml')
+            : joinFor('win32')(spec.home, 'host', `${label}-task.xml`);
+    }
+    return spec.dedicated
+        ? path.join('/etc/systemd/system', systemdUnitOf(spec))
+        : path.join(spec.userHome, '.config', 'systemd', 'user', systemdUnitOf(spec));
+}
+export function buildHostPlist(spec) {
+    const log = logPathFor(spec);
+    return buildLaunchdPlist({
+        label: labelOf(spec),
+        programArguments: serviceArgs(spec),
+        workdir: spec.home,
+        logPath: log,
+        env: serviceEnv(spec),
+        ...(spec.dedicated && spec.serviceUser ? { userName: spec.serviceUser } : {}),
+        exitTimeoutSeconds: STOP_TIMEOUT_SECONDS,
+    });
+}
+function systemdQuote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%')}"`;
+}
+export function buildHostSystemdUnit(spec) {
+    const log = logPathFor(spec);
+    return [
+        '[Unit]',
+        'Description=ProhostAI computer host (AI employees and terminal sessions)',
+        'After=network-online.target',
+        'Wants=network-online.target',
+        '',
+        '[Service]',
+        'Type=simple',
+        ...(spec.dedicated && spec.serviceUser ? [`User=${spec.serviceUser}`] : []),
+        `WorkingDirectory=${systemdQuote(spec.home)}`,
+        ...Object.entries(serviceEnv(spec)).map(([key, value]) => `Environment=${key}=${systemdQuote(value)}`),
+        `ExecStart=${serviceArgs(spec).map(systemdQuote).join(' ')}`,
+        // A system unit logs to the journal: an `append:` path would be opened by root.
+        ...(log ? [`StandardOutput=append:${log}`, `StandardError=append:${log}`] : ['StandardOutput=journal', 'StandardError=journal']),
+        'Restart=always',
+        'RestartSec=10',
+        'KillSignal=SIGTERM',
+        // SIGTERM to the host alone, so it can drain; the rest of the group only at the timeout.
+        'KillMode=mixed',
+        `TimeoutStopSec=${STOP_TIMEOUT_SECONDS}`,
+        '',
+        '[Install]',
+        `WantedBy=${spec.dedicated ? 'multi-user.target' : 'default.target'}`,
+        '',
+    ].join('\n');
+}
+function xmlEscape(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/** The `.cmd` the Windows task runs: sets the environment, then the CLI, logging to its log file. */
+export function buildWindowsWrapper(spec) {
+    const quote = (value) => value.replace(/%/g, '%%');
+    return [
+        '@echo off',
+        ...Object.entries(serviceEnv(spec)).map(([key, value]) => `set "${key}=${quote(value)}"`),
+        `"${quote(spec.nodePath)}" "${quote(spec.scriptPath)}" host run >> "${quote(logPathFor(spec))}" 2>&1`,
+        '',
+    ].join('\r\n');
+}
+export function windowsWrapperPath(spec) {
+    // Dedicated: in an administrators' folder, never in the account's own home.
+    if (spec.dedicated && spec.platform === 'win32')
+        return path.win32.join(windowsServiceDir(spec), 'host-service.cmd');
+    return joinFor(spec.platform)(spec.home, 'host', `${labelOf(spec)}-service.cmd`);
+}
+/** Where a Windows dedicated install keeps its task definition and wrapper: administrators write, the account reads. */
+export function windowsServiceDir(spec) {
+    return path.win32.join('C:\\ProgramData\\Prohost\\services', labelOf(spec));
+}
+/** Task Scheduler XML: at logon (personal) or at boot as the service user via S4U (dedicated). */
+export function buildWindowsTaskXml(spec, currentUser) {
+    const user = xmlEscape(spec.dedicated && spec.serviceUser ? spec.serviceUser : currentUser);
+    const trigger = spec.dedicated
+        ? '    <BootTrigger><Enabled>true</Enabled></BootTrigger>'
+        : `    <LogonTrigger><Enabled>true</Enabled><UserId>${user}</UserId></LogonTrigger>`;
+    return [
+        '<?xml version="1.0" encoding="UTF-16"?>',
+        '<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">',
+        '  <RegistrationInfo><Description>ProhostAI computer host (AI employees and terminal sessions)</Description></RegistrationInfo>',
+        '  <Triggers>',
+        trigger,
+        '  </Triggers>',
+        '  <Principals>',
+        '    <Principal id="Author">',
+        `      <UserId>${user}</UserId>`,
+        `      <LogonType>${spec.dedicated ? 'S4U' : 'InteractiveToken'}</LogonType>`,
+        '      <RunLevel>LeastPrivilege</RunLevel>',
+        '    </Principal>',
+        '  </Principals>',
+        '  <Settings>',
+        '    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>',
+        '    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>',
+        '    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>',
+        '    <AllowHardTerminate>true</AllowHardTerminate>',
+        '    <StartWhenAvailable>true</StartWhenAvailable>',
+        '    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>',
+        '    <IdleSettings><StopOnIdleEnd>false</StopOnIdleEnd><RestartOnIdle>false</RestartOnIdle></IdleSettings>',
+        '    <AllowStartOnDemand>true</AllowStartOnDemand>',
+        '    <Enabled>true</Enabled>',
+        '    <Hidden>false</Hidden>',
+        '    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>',
+        '    <Priority>7</Priority>',
+        '    <RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure>',
+        '  </Settings>',
+        '  <Actions Context="Author">',
+        '    <Exec>',
+        `      <Command>${xmlEscape(windowsWrapperPath(spec))}</Command>`,
+        `      <WorkingDirectory>${xmlEscape(spec.home)}</WorkingDirectory>`,
+        '    </Exec>',
+        '  </Actions>',
+        '</Task>',
+        '',
+    ].join('\r\n');
+}
+function writer(io) {
+    return (io.writeFile ??
+        ((file, content, mode, flag = 'w') => {
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, content, { mode, flag });
+            chmodSync(file, mode);
+        }));
+}
+function reader(io) {
+    return (io.readFile ??
+        ((file) => {
+            try {
+                return readFileSync(file, 'utf8');
+            }
+            catch {
+                return undefined;
+            }
+        }));
+}
+function failed(step, outcome) {
+    return `${step} failed${outcome.stderr.trim() ? `: ${outcome.stderr.trim()}` : ` (exit ${String(outcome.status)})`}`;
+}
+/** Validate a spec before anything is written. */
+export function specProblem(spec, io = {}, setup = {}) {
+    if (spec.label !== undefined && !LABEL.test(spec.label)) {
+        return `"${spec.label}" is not a usable label (letters, digits, "." and "-", like ai.prohost.desktop.host).`;
+    }
+    if (setup.claudeTokenFile && !spec.dedicated)
+        return '--claude-token-file is for a dedicated install (--dedicated).';
+    if (spec.dedicated) {
+        if (!spec.serviceUser)
+            return '--dedicated needs --service-user <name>: the account the service runs as.';
+        if (!SERVICE_USER.test(spec.serviceUser))
+            return `"${spec.serviceUser}" is not a usable account name.`;
+        const admin = io.isAdmin ??
+            (spec.platform === 'win32'
+                ? // `net session` succeeds only from an elevated prompt.
+                    (io.run ?? defaultServiceRunner)('net', ['session']).status === 0
+                : (io.uid ?? process.getuid?.() ?? 1) === 0);
+        if (!admin) {
+            return spec.platform === 'win32'
+                ? 'A dedicated service is installed from an administrator prompt.'
+                : 'A dedicated service is installed as root: run it with sudo.';
+        }
+    }
+    if (!['darwin', 'linux', 'win32'].includes(spec.platform))
+        return `No background service for ${spec.platform}.`;
+    return undefined;
+}
+/** Create the hidden service account if it does not exist (macOS, Linux). */
+function ensureServiceUser(spec, run) {
+    const user = spec.serviceUser;
+    if (spec.platform === 'win32') {
+        // An S4U task needs an existing local account; making one means choosing a password policy.
+        return run('net', ['user', user]).status === 0
+            ? undefined
+            : `The account "${user}" does not exist. Create it first (net user ${user} /add), then install again.`;
+    }
+    if (run('id', ['-u', user]).status === 0)
+        return undefined;
+    if (spec.platform === 'linux') {
+        const made = run('useradd', ['--system', '--create-home', '--home-dir', `/home/${user}`, '--shell', '/usr/sbin/nologin', user]);
+        return made.status === 0 ? undefined : failed(`useradd ${user}`, made);
+    }
+    // macOS: a hidden account with a UniqueID in 401–499 (below the login window's range).
+    const listed = run('dscl', ['.', '-list', '/Users', 'UniqueID']);
+    const taken = new Set(listed.stdout
+        .split('\n')
+        .map((line) => Number.parseInt(line.trim().split(/\s+/)[1] ?? '', 10))
+        .filter(Number.isFinite));
+    let uid = 401;
+    while (taken.has(uid) && uid < 500)
+        uid += 1;
+    if (uid >= 500)
+        return 'No free hidden user id (401–499) for the service account.';
+    const record = `/Users/${user}`;
+    const steps = [
+        ['dscl', '.', '-create', record],
+        ['dscl', '.', '-create', record, 'UserShell', '/usr/bin/false'],
+        ['dscl', '.', '-create', record, 'RealName', 'ProhostAI host'],
+        ['dscl', '.', '-create', record, 'UniqueID', String(uid)],
+        ['dscl', '.', '-create', record, 'PrimaryGroupID', '20'],
+        ['dscl', '.', '-create', record, 'NFSHomeDirectory', record],
+        ['dscl', '.', '-create', record, 'IsHidden', '1'],
+        ['mkdir', '-p', record],
+        ['chown', `${user}:staff`, record],
+    ];
+    for (const [command, ...args] of steps) {
+        const out = run(command, args);
+        if (out.status !== 0)
+            return failed(`${command} ${args.slice(0, 3).join(' ')}`, out);
+    }
+    return undefined;
+}
+/** Where a Windows dedicated install keeps the Claude token: an administrators' folder the account may only read. */
+export function windowsTokenPath(spec) {
+    return path.win32.join('C:\\ProgramData\\Prohost\\secrets', labelOf(spec), CLAUDE_TOKEN_FILE);
+}
+function mkdirOnce(dir) {
+    try {
+        mkdirSync(dir);
+        return 'created';
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return 'exists';
+        throw err;
+    }
+}
+function ownerOf(file) {
+    try {
+        const stat = lstatSync(file);
+        return { uid: stat.uid, link: stat.isSymbolicLink() };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Create or take over the ProgramData folders a Windows dedicated install
+ * uses, top-down: each one is checked for a junction, owned by
+ * Administrators, and given exactly its ACL, before the next one inside it.
+ */
+/** The principals `icacls <dir>` lists (`BUILTIN\\Administrators:(OI)(CI)(F)` → `Administrators`). */
+export function aclPrincipals(icaclsOutput, dir) {
+    return icaclsOutput
+        .split(/\r?\n/)
+        .map((line) => (line.startsWith(dir) ? line.slice(dir.length) : line).trim())
+        .filter((line) => /:\(/.test(line))
+        .map((line) => line.slice(0, line.indexOf(':(')).split('\\').pop().trim());
+}
+function windowsOwner(run, dir) {
+    const owner = run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-Acl -LiteralPath '${dir}').Owner`]);
+    return owner.status === 0 ? owner.stdout.trim() : '';
+}
+function claimWindowsDirs(spec, run, mkdirOnce, isSymlink) {
+    const user = spec.serviceUser;
+    const base = 'C:\\ProgramData\\Prohost';
+    const admin = ['SYSTEM:(OI)(CI)F', 'Administrators:(OI)(CI)F'];
+    const dirs = [
+        [base, [...admin, 'Users:(OI)(CI)RX']],
+        [path.win32.join(base, 'hosts'), [...admin, 'Users:(OI)(CI)RX']],
+        [sharedDirFor(spec), [...admin, 'Users:(OI)(CI)RX']],
+        [path.win32.join(base, 'Logs'), [...admin, `${user}:(OI)(CI)M`]],
+        [path.win32.join(base, 'secrets'), admin],
+        [path.win32.dirname(windowsTokenPath(spec)), [...admin, `${user}:(OI)(CI)R`]],
+        [path.win32.join(base, 'services'), admin],
+        [windowsServiceDir(spec), [...admin, `${user}:(OI)(CI)RX`]],
+    ];
+    const trusted = (owner) => /\\(Administrators|SYSTEM)$/i.test(owner);
+    for (const [dir, grants] of dirs) {
+        // Made in one step, or found: never "checked absent, then made" (someone could make it in between).
+        if (mkdirOnce(dir) === 'exists') {
+            if (isSymlink(dir))
+                return `${dir} is a link or junction: remove it, then install again.`;
+            // Made by someone else first: never trusted, whatever its ACL says now.
+            const owner = windowsOwner(run, dir);
+            if (!trusted(owner))
+                return `${dir} is owned by ${owner || 'someone else'}: remove it, then install again.`;
+        }
+        // Exactly this ACL: the owner, then no explicit entries left from before, nothing inherited, ours granted.
+        for (const args of [
+            [dir, '/setowner', 'Administrators'],
+            [dir, '/reset'],
+            [dir, '/inheritance:r', '/grant:r', ...grants],
+        ]) {
+            const out = run('icacls', args);
+            if (out.status !== 0)
+                return failed(`icacls ${args.slice(0, 2).join(' ')}`, out);
+        }
+        // And checked after: still ours, still not a link, and only the principals we granted.
+        if (isSymlink(dir))
+            return `${dir} became a link or junction: remove it, then install again.`;
+        const owner = windowsOwner(run, dir);
+        if (!trusted(owner))
+            return `${dir} is owned by ${owner || 'someone else'} after taking it over: install stopped.`;
+        const listed = run('icacls', [dir]);
+        const allowed = new Set(grants.map((grant) => grant.slice(0, grant.indexOf(':')).toLowerCase()));
+        const extra = aclPrincipals(listed.stdout, dir).filter((name) => !allowed.has(name.toLowerCase()));
+        if (listed.status !== 0 || extra.length > 0) {
+            return `${dir} still grants ${extra.join(', ') || 'unknown principals'} after taking it over: install stopped.`;
+        }
+    }
+    return undefined;
+}
+/** The files a dedicated service publishes in its shared folder, and the pause switch. */
+export const SHARED_FILES = ['state.json', 'activity.json', 'events.json'];
+/**
+ * Run a short shell script as the service account (`sudo -u` on macOS,
+ * `runuser` on Linux), with `input` on stdin. Everything root writes into the
+ * account's home goes through here: as the account, a link it planted there
+ * can only point at what it could write anyway.
+ */
+function asUser(run, platform, user, script, args, input) {
+    const shell = ['/bin/sh', '-c', `umask 077; ${script}`, 'sh', ...args];
+    return platform === 'darwin'
+        ? run('sudo', ['-u', user, '-H', '--', ...shell], input)
+        : run('runuser', ['-u', user, '--', ...shell], input);
+}
+/**
+ * The parts of a dedicated install that are not the service: the account, its
+ * home (credential and Claude token in place — written as the account), the
+ * root-owned shared folder its state is published in, and a log location root
+ * controls. Root never writes through a path the account controls.
+ */
+function prepareDedicated(spec, io, setup) {
+    const run = io.run ?? defaultServiceRunner;
+    const write = writer(io);
+    const read = reader(io);
+    const exists = io.exists ?? existsSync;
+    const isLink = io.isLink ?? ((file) => {
+        try {
+            const stat = lstatSync(file);
+            return !stat.isFile() || stat.nlink > 1;
+        }
+        catch {
+            return false;
+        }
+    });
+    const isSymlink = io.isSymlink ?? ((file) => {
+        try {
+            return lstatSync(file).isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    });
+    const remove = io.removeFile ?? ((file) => rmSync(file, { force: true }));
+    const mkdir = io.mkdir ?? ((dir, mode) => mkdirSync(dir, { recursive: true, mode }));
+    const join = joinFor(spec.platform);
+    const user = spec.serviceUser;
+    const problem = ensureServiceUser(spec, run);
+    if (problem)
+        return problem;
+    const hostDir = join(spec.home, 'host');
+    const credential = setup.adoptFrom && path.resolve(setup.adoptFrom) !== path.resolve(spec.home)
+        ? read(join(setup.adoptFrom, 'host', 'computer.json'))
+        : undefined;
+    let token;
+    if (setup.claudeTokenFile) {
+        token = read(setup.claudeTokenFile)?.trim();
+        if (!token || token.length > 4096 || /\s/.test(token))
+            return `${setup.claudeTokenFile} holds no usable token.`;
+    }
+    if (spec.platform === 'win32') {
+        // Everything an administrator touches is claimed top-down (owner
+        // Administrators, nothing inherited) before anything goes in, and a
+        // junction where a folder should be stops the install: a folder another
+        // user made first, or one the account controls, is never written through.
+        const claimed = claimWindowsDirs(spec, run, io.mkdirOnce ?? mkdirOnce, isSymlink);
+        if (claimed)
+            return claimed;
+        if (token) {
+            // Always a new file, in the folder just claimed: whatever was there is replaced, never written through.
+            const tokenFile = windowsTokenPath(spec);
+            if (exists(tokenFile))
+                remove(tokenFile);
+            write(tokenFile, `${token}\n`, 0o600, 'wx');
+        }
+        // The account's home is ACL'd and filled only when this install creates
+        // it: an existing one is the account's, and an administrator writing into
+        // it could be redirected.
+        mkdir(path.win32.dirname(spec.home), 0o755);
+        if ((io.mkdirOnce ?? mkdirOnce)(spec.home) === 'created') {
+            mkdir(hostDir, 0o700);
+            const acl = run('icacls', [spec.home, '/inheritance:r', '/grant:r', 'SYSTEM:(OI)(CI)F', 'Administrators:(OI)(CI)F', `${user}:(OI)(CI)F`]);
+            if (acl.status !== 0)
+                return failed(`icacls ${spec.home}`, acl);
+            if (credential)
+                write(join(hostDir, 'computer.json'), credential, 0o600);
+        }
+        else if (isSymlink(spec.home) || isSymlink(hostDir)) {
+            return `${spec.home} is a link: remove it, then install again.`;
+        }
+    }
+    else {
+        let made = asUser(run, spec.platform, user, 'mkdir -p "$1"', [hostDir]);
+        if (made.status !== 0 && !exists(spec.home)) {
+            // A service home where the account can't create it (--service-home under
+            // a root-owned folder): root makes that one folder, if its parent is
+            // root's and no link, and hands it over; everything inside is the account's.
+            const parent = path.posix.dirname(spec.home);
+            const owner = io.ownerOf?.(parent) ?? ownerOf(parent);
+            if (!owner || owner.uid !== 0 || owner.link)
+                return `${parent} is not a root-owned folder: create ${spec.home} for ${user} first.`;
+            mkdir(spec.home, 0o700);
+            const handed = run('chown', ['-h', user, spec.home]);
+            if (handed.status !== 0)
+                return failed(`chown ${spec.home}`, handed);
+            made = asUser(run, spec.platform, user, 'mkdir -p "$1"', [hostDir]);
+        }
+        if (made.status !== 0)
+            return failed(`creating ${hostDir} as ${user}`, made);
+        if (credential) {
+            // Only when the home has none; checked as the account too.
+            const copied = asUser(run, spec.platform, user, 'test -e "$1" || cat > "$1"', [join(hostDir, 'computer.json')], credential);
+            if (copied.status !== 0)
+                return failed('copying computer.json', copied);
+        }
+        if (token) {
+            const stored = asUser(run, spec.platform, user, 
+            // A fresh temp file (noclobber: never one that is already there), then renamed over.
+            'rm -f "$1.new" && set -C && cat > "$1.new" && mv -f "$1.new" "$1"', [join(hostDir, CLAUDE_TOKEN_FILE)], `${token}\n`);
+            if (stored.status !== 0)
+                return failed('installing the Claude token', stored);
+        }
+    }
+    // The shared folder is root's (the account can't swap what's in it); the
+    // account gets only its three files, and everyone the pause switch.
+    const shared = sharedDirFor(spec);
+    if (spec.platform !== 'win32') {
+        mkdir(shared, 0o755);
+        for (const [command, ...args] of [['chown', 'root', shared], ['chmod', '755', shared]]) {
+            const out = run(command, args);
+            if (out.status !== 0)
+                return failed(`${command} ${shared}`, out);
+        }
+    }
+    const managed = [
+        ...SHARED_FILES.map((name) => ({ name, content: '{}\n', mode: 0o644, owner: 'service' })),
+        { name: 'control.json', content: `${JSON.stringify({ v: 1, paused: false })}\n`, mode: 0o666, owner: 'everyone' },
+    ];
+    for (const file of managed) {
+        const target = join(shared, file.name);
+        // Left by an older install that let the account own this folder.
+        if (exists(target) && isLink(target))
+            remove(target);
+        if (!exists(target))
+            write(target, file.content, file.mode, 'wx');
+        if (spec.platform === 'win32') {
+            const grant = file.owner === 'service' ? `${user}:M` : 'Users:M';
+            const acl = run('icacls', [target, '/grant', grant]);
+            if (acl.status !== 0)
+                return failed(`icacls ${target}`, acl);
+        }
+        else if (file.owner === 'service') {
+            const owned = run('chown', ['-h', user, target]);
+            if (owned.status !== 0)
+                return failed(`chown ${target}`, owned);
+        }
+        else {
+            const open = run('chmod', ['666', target]);
+            if (open.status !== 0)
+                return failed(`chmod ${target}`, open);
+        }
+    }
+    if (spec.platform === 'darwin') {
+        // Root's folder, the service's file: it can write its log, never swap it for a link.
+        const log = logPathFor(spec);
+        mkdir(path.posix.dirname(log), 0o755);
+        if (exists(log) && isLink(log))
+            remove(log);
+        if (!exists(log))
+            write(log, '', 0o644, 'wx');
+        const logOwned = run('chown', ['-h', user, log]);
+        if (logOwned.status !== 0)
+            return failed(`chown ${log}`, logOwned);
+    }
+    return undefined;
+}
+export function installService(spec, io = {}, setup = {}) {
+    const problem = specProblem(spec, io, setup);
+    if (problem)
+        return { ok: false, message: problem };
+    const run = io.run ?? defaultServiceRunner;
+    const write = writer(io);
+    const read = reader(io);
+    const file = serviceFilePath(spec);
+    const label = labelOf(spec);
+    const mkdir = io.mkdir ?? ((dir, mode) => mkdirSync(dir, { recursive: true, mode }));
+    if (spec.dedicated) {
+        const prepared = prepareDedicated(spec, io, setup);
+        if (prepared)
+            return { ok: false, message: prepared };
+    }
+    else {
+        mkdir(path.dirname(logPathFor(spec)), 0o700);
+    }
+    const logs = logPathFor(spec) ?? `the journal (journalctl -u ${systemdUnitOf(spec)})`;
+    if (spec.platform === 'darwin') {
+        const domain = spec.dedicated ? 'system' : `gui/${io.uid ?? process.getuid?.() ?? 0}`;
+        const plist = buildHostPlist(spec);
+        const loaded = run('launchctl', ['print', `${domain}/${label}`]).status === 0;
+        // Re-running it changes nothing that is already right: the service keeps
+        // working through every app update that didn't move it.
+        if (loaded && read(file) === plist) {
+            return { ok: true, file, message: `✓ ${label} is installed and running (${file})\n  logs: ${logs}` };
+        }
+        write(file, plist, spec.dedicated ? 0o644 : 0o600);
+        if (loaded)
+            run('launchctl', ['bootout', `${domain}/${label}`]);
+        // A re-install: the running service drains on SIGTERM, and launchd keeps
+        // its label until it exits — bootstrapping before then fails.
+        const oldGone = !loaded ||
+            waitUntilUnloaded((command, args) => {
+                const out = run(command, args);
+                return { status: out.status, stderr: out.stderr };
+            }, `${domain}/${label}`, {
+                sleep: io.sleep ?? ((ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)),
+                now: io.now ?? Date.now,
+                timeoutMs: RESTART_WAIT_MS,
+                onWaiting: (line) => process.stderr.write(`${line.replace('agent', 'host service')}\n`),
+            });
+        const boot = run('launchctl', ['bootstrap', domain, file]);
+        if (boot.status !== 0) {
+            const still = oldGone ? '' : ` (the previous host service was still finishing its runs after ${RESTART_WAIT_MS / 1000}s)`;
+            return { ok: false, file, message: `Wrote ${file}, but ${failed('launchctl bootstrap', boot)}${still}` };
+        }
+        run('launchctl', ['enable', `${domain}/${label}`]);
+        return { ok: true, file, message: `✓ Installed ${label} (${file})\n  logs: ${logs}` };
+    }
+    if (spec.platform === 'linux') {
+        const user = spec.dedicated ? [] : ['--user'];
+        const unitName = systemdUnitOf(spec);
+        const unit = buildHostSystemdUnit(spec);
+        const changed = read(file) !== unit;
+        if (changed) {
+            write(file, unit, 0o644);
+            const reload = run('systemctl', [...user, 'daemon-reload']);
+            if (reload.status !== 0)
+                return { ok: false, file, message: `Wrote ${file}, but ${failed('systemctl daemon-reload', reload)}` };
+        }
+        const enable = run('systemctl', [...user, 'enable', '--now', unitName]);
+        if (enable.status !== 0)
+            return { ok: false, file, message: `Wrote ${file}, but ${failed('systemctl enable', enable)}` };
+        // A changed unit only takes effect on a restart; the service drains on SIGTERM first.
+        if (changed)
+            run('systemctl', [...user, 'try-restart', unitName]);
+        const linger = spec.dedicated
+            ? ''
+            : '\n  It runs while you are logged in. To keep it running after you log out: loginctl enable-linger';
+        return { ok: true, file, message: `✓ Installed ${unitName} (${file})\n  logs: ${logs}${linger}` };
+    }
+    const task = windowsTaskOf(spec);
+    const currentUser = io.currentUser ?? os.userInfo().username;
+    const xml = Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(buildWindowsTaskXml(spec, currentUser), 'utf16le')]);
+    write(windowsWrapperPath(spec), buildWindowsWrapper(spec), 0o600);
+    // Task Scheduler reads its XML as UTF-16 (little-endian, with a BOM).
+    write(file, xml, 0o600);
+    const create = run('schtasks', ['/Create', '/TN', task, '/XML', file, '/F']);
+    if (create.status !== 0)
+        return { ok: false, file, message: failed('schtasks /Create', create) };
+    // Already running (`IgnoreNew`): left to finish; the next start runs the new definition.
+    const start = run('schtasks', ['/Run', '/TN', task]);
+    if (start.status !== 0)
+        return { ok: false, file, message: `Created ${task}, but ${failed('schtasks /Run', start)}` };
+    return { ok: true, file, message: `✓ Installed the ${task} task\n  logs: ${logs}` };
+}
+export function uninstallService(spec, io = {}) {
+    const run = io.run ?? defaultServiceRunner;
+    const remove = io.removeFile ?? ((file) => rmSync(file, { force: true }));
+    const exists = io.exists ?? existsSync;
+    const removed = [];
+    const notes = [];
+    const label = labelOf(spec);
+    if (spec.platform === 'darwin') {
+        for (const dedicated of [false, true]) {
+            const variant = { ...spec, dedicated };
+            const file = serviceFilePath(variant);
+            if (!exists(file))
+                continue;
+            const domain = dedicated ? 'system' : `gui/${io.uid ?? process.getuid?.() ?? 0}`;
+            const out = run('launchctl', ['bootout', `${domain}/${label}`]);
+            if (dedicated && out.status !== 0 && (io.uid ?? process.getuid?.() ?? 1) !== 0) {
+                notes.push(`${file} is a system service: remove it with sudo prohost host uninstall`);
+                continue;
+            }
+            remove(file);
+            removed.push(file);
+        }
+    }
+    else if (spec.platform === 'linux') {
+        for (const dedicated of [false, true]) {
+            const variant = { ...spec, dedicated };
+            const file = serviceFilePath(variant);
+            if (!exists(file))
+                continue;
+            const user = dedicated ? [] : ['--user'];
+            const out = run('systemctl', [...user, 'disable', '--now', systemdUnitOf(spec)]);
+            if (dedicated && out.status !== 0 && (io.uid ?? process.getuid?.() ?? 1) !== 0) {
+                notes.push(`${file} is a system service: remove it with sudo prohost host uninstall`);
+                continue;
+            }
+            remove(file);
+            run('systemctl', [...user, 'daemon-reload']);
+            removed.push(file);
+        }
+    }
+    else if (spec.platform === 'win32') {
+        const task = windowsTaskOf(spec);
+        run('schtasks', ['/End', '/TN', task]);
+        const out = run('schtasks', ['/Delete', '/TN', task, '/F']);
+        if (out.status === 0)
+            removed.push(task);
+        for (const file of [serviceFilePath(spec), windowsWrapperPath(spec)]) {
+            if (exists(file))
+                remove(file);
+        }
+    }
+    if (removed.length === 0 && notes.length === 0) {
+        return { ok: true, message: 'No host service was installed. Nothing to remove.' };
+    }
+    return {
+        ok: notes.length === 0,
+        message: [...removed.map((file) => `✓ Removed ${file}`), ...notes.map((note) => `! ${note}`)].join('\n'),
+    };
+}
+/** Where a dedicated service user's `PROHOST_HOME` is by default. */
+export function serviceUserHome(platform, user) {
+    if (platform === 'darwin')
+        return path.join('/Users', user, '.prohost');
+    if (platform === 'win32')
+        return path.win32.join('C:\\Users', user, '.prohost');
+    return path.join('/home', user, '.prohost');
+}