@prohost/cli 0.14.0 → 0.16.0

package/dist/host/computer.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `prohost host`'s files, and the computer credential.
+ *
+ * Everything the host service keeps lives under `$PROHOST_HOME/host`:
+ *
+ * - `computer.json` — the computer credential from `host pair` (0600).
+ * - `state.json` — what the running service last saw (slots, runs, logins),
+ *   for `host status` and the desktop app; local only, 0600.
+ * - `activity.json` — busy / running, for the menu bar.
+ * - `control.json` — `host pause` / `resume`, read by the running service.
+ * - `adopted.json` — what `host migrate` adopted.
+ * - `employees/<agent_id>/` — one home per employee placed here: its
+ *   sessions, its workspace (and the skills written into it).
+ * - `runs.json` — the run ledger, keyed by employee and conversation.
+ */
+import os from 'node:os';
+import type { ProhostAccount } from '../agent/credentials.js';
+export declare function hostDir(env?: NodeJS.ProcessEnv): string;
+export declare function computerPath(env?: NodeJS.ProcessEnv): string;
+export declare function statePath(env?: NodeJS.ProcessEnv): string;
+export declare function hostActivityPath(env?: NodeJS.ProcessEnv): string;
+export declare function controlPath(env?: NodeJS.ProcessEnv): string;
+export declare function adoptedPath(env?: NodeJS.ProcessEnv): string;
+export declare function hostLedgerPath(env?: NodeJS.ProcessEnv): string;
+export declare function hostLogPath(env?: NodeJS.ProcessEnv): string;
+export declare function hostLockPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Hold this home's host service lock: one `host run` per home. A second one
+ * would load the same ledger and report the first one's live runs as
+ * unfinished. A lock whose process is gone is taken over. Returns a release
+ * function, or the pid that holds it.
+ */
+export declare function acquireHostLock(env?: NodeJS.ProcessEnv, pid?: number, isAlive?: (pid: number) => boolean, now?: () => number): {
+    ok: true;
+    release: () => void;
+} | {
+    ok: false;
+    heldBy: number;
+};
+/** One employee's home: its sessions and workspace. The id is checked before it names a path. */
+export declare function employeeHome(agentId: string, env?: NodeJS.ProcessEnv): string;
+/** Write JSON atomically (temp file + rename) and owner-only. */
+export declare function writePrivateFile(file: string, value: unknown): void;
+/**
+ * Write JSON readable by everyone on the computer: a dedicated service's
+ * state for the logged-in user (never a secret, never an email). Written in
+ * place — the folder is root's, only the file is the service's — so a reader
+ * can catch it mid-write: read it with {@link readSharedObject}.
+ */
+export declare function writeSharedFile(file: string, value: unknown): void;
+/** {@link readObject} for a file written in place: a read caught mid-write is tried once more. */
+export declare function readSharedObject(file: string): Record<string, unknown> | undefined;
+/** The JSON object at `file`, or `undefined` for a missing, unreadable or non-object file. */
+export declare function readObject(file: string): Record<string, unknown> | undefined;
+/** The computer credential, as `host pair` stored it. */
+export interface ComputerCredentials {
+    version: 1;
+    computer_id: string;
+    account: ProhostAccount;
+    api_key: string;
+    webhook_secret: string | null;
+    /** The event subscription the stream is pinned to; sent on the socket's auth frame. */
+    subscription_id?: string | null;
+    ws_url: string;
+    mcp_url: string;
+    /** The public API base the credential belongs to. */
+    base_url: string;
+    /** The id this machine paired with (see `machineFacts`). */
+    machine_id: string;
+    name: string;
+    paired_at: string;
+    /**
+     * The `PROHOST_HOME` whose Code-thread host this service runs — the
+     * desktop app's, when `host migrate` adopted it — so its terminals, folders
+     * and switches carry over. Unset: the service's own home.
+     */
+    code_host_home?: string;
+}
+export declare class ComputerMissingError extends Error {
+}
+export declare function saveComputer(credentials: ComputerCredentials, env?: NodeJS.ProcessEnv): string;
+export declare function loadComputer(env?: NodeJS.ProcessEnv): ComputerCredentials;
+/** The `claude setup-token` token a dedicated install put in this home (`host/claude-oauth-token`). */
+export declare function readClaudeToken(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The environment that gives a Claude Code process the installed token —
+ * passed to Claude runs, Claude terminal sessions and the Claude login checks
+ * only, never to the host's own environment (a Codex run must not see it).
+ * Re-read each time, so a rotated token applies without a restart.
+ */
+export declare function claudeTokenEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Delete the computer credential (after the server removed the computer). */
+export declare function clearComputer(env?: NodeJS.ProcessEnv): void;
+export declare function tryLoadComputer(env?: NodeJS.ProcessEnv): ComputerCredentials | null;
+export type ComputerOs = 'macos' | 'windows' | 'linux';
+/** What pairing tells the server about this machine. Never the user's name or email. */
+export interface MachineFacts {
+    name: string;
+    hostname: string;
+    machine_id: string;
+    os: ComputerOs;
+    os_version: string;
+    arch: string;
+    chip: string | null;
+    memory_gb: number;
+    cpu_cores: number;
+}
+export declare function computerOs(platform?: NodeJS.Platform): ComputerOs;
+/** A friendly default name: "This Mac" on a Mac is the UI's job; here it is the short hostname. */
+export declare function defaultComputerName(hostname?: string): string;
+export declare function machineFacts(options?: {
+    env?: NodeJS.ProcessEnv;
+    name?: string;
+    platform?: NodeJS.Platform;
+    hostname?: string;
+    release?: string;
+    arch?: string;
+    cpus?: () => os.CpuInfo[];
+    totalmem?: () => number;
+}): MachineFacts;

package/dist/host/computer.js

@@ -0,0 +1,291 @@
+/**
+ * `prohost host`'s files, and the computer credential.
+ *
+ * Everything the host service keeps lives under `$PROHOST_HOME/host`:
+ *
+ * - `computer.json` — the computer credential from `host pair` (0600).
+ * - `state.json` — what the running service last saw (slots, runs, logins),
+ *   for `host status` and the desktop app; local only, 0600.
+ * - `activity.json` — busy / running, for the menu bar.
+ * - `control.json` — `host pause` / `resume`, read by the running service.
+ * - `adopted.json` — what `host migrate` adopted.
+ * - `employees/<agent_id>/` — one home per employee placed here: its
+ *   sessions, its workspace (and the skills written into it).
+ * - `runs.json` — the run ledger, keyed by employee and conversation.
+ */
+import { chmodSync, existsSync, linkSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { machineId } from '../agent/accounts.js';
+import { prohostHome } from '../agent/credentials.js';
+export function hostDir(env = process.env) {
+    return path.join(prohostHome(env), 'host');
+}
+export function computerPath(env = process.env) {
+    return path.join(hostDir(env), 'computer.json');
+}
+export function statePath(env = process.env) {
+    return path.join(hostDir(env), 'state.json');
+}
+export function hostActivityPath(env = process.env) {
+    return path.join(hostDir(env), 'activity.json');
+}
+export function controlPath(env = process.env) {
+    return path.join(hostDir(env), 'control.json');
+}
+export function adoptedPath(env = process.env) {
+    return path.join(hostDir(env), 'adopted.json');
+}
+export function hostLedgerPath(env = process.env) {
+    return path.join(hostDir(env), 'runs.json');
+}
+export function hostLogPath(env = process.env) {
+    return path.join(hostDir(env), 'host.log');
+}
+export function hostLockPath(env = process.env) {
+    return path.join(hostDir(env), 'service.lock');
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: it exists, it just isn't ours to signal.
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * Hold this home's host service lock: one `host run` per home. A second one
+ * would load the same ledger and report the first one's live runs as
+ * unfinished. A lock whose process is gone is taken over. Returns a release
+ * function, or the pid that holds it.
+ */
+export function acquireHostLock(env = process.env, pid = process.pid, isAlive = alive, now = Date.now) {
+    const file = hostLockPath(env);
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    // Written whole beside the lock, then hard-linked into place: the link is
+    // atomic and fails if a lock exists, so a lock is never seen half written.
+    const mine = `${file}.${pid}.${Math.random().toString(16).slice(2)}`;
+    writeFileSync(mine, `${JSON.stringify({ pid, started_at: new Date(now()).toISOString() })}\n`, { mode: 0o600 });
+    try {
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                linkSync(mine, file);
+                return {
+                    ok: true,
+                    release: () => {
+                        if (readObject(file)?.pid === pid)
+                            rmSync(file, { force: true });
+                    },
+                };
+            }
+            catch (err) {
+                if (err.code !== 'EEXIST')
+                    throw err;
+            }
+            const holder = readObject(file)?.pid;
+            // Our own pid holding it is a service already running in this process.
+            if (typeof holder === 'number' && (holder === pid || isAlive(holder)))
+                return { ok: false, heldBy: holder };
+            if (typeof holder !== 'number') {
+                // Unreadable: give a writer a moment before calling it abandoned.
+                let age = Number.POSITIVE_INFINITY;
+                try {
+                    age = now() - statSync(file).mtimeMs;
+                }
+                catch {
+                    continue;
+                }
+                if (age < STALE_LOCK_GRACE_MS)
+                    return { ok: false, heldBy: -1 };
+            }
+            // Abandoned. Only one start at a time may clear it (`mkdir` is atomic),
+            // and it looks again once it may: a lock that is live by then stays.
+            const reclaim = `${file}.reclaim`;
+            try {
+                mkdirSync(reclaim);
+                writeFileSync(path.join(reclaim, 'pid'), String(pid), { mode: 0o600 });
+            }
+            catch {
+                // Another start is clearing it. Its mutex is broken only once that
+                // start is dead — a paused one (a sleeping laptop) still holds it.
+                let reclaimer;
+                let age = 0;
+                try {
+                    reclaimer = Number.parseInt(readFileSync(path.join(reclaim, 'pid'), 'utf8'), 10);
+                }
+                catch {
+                    reclaimer = undefined;
+                }
+                try {
+                    age = now() - statSync(reclaim).mtimeMs;
+                }
+                catch {
+                    continue;
+                }
+                const dead = reclaimer !== undefined && Number.isFinite(reclaimer)
+                    ? reclaimer !== pid && !isAlive(reclaimer)
+                    : age > STALE_LOCK_GRACE_MS;
+                if (!dead)
+                    return { ok: false, heldBy: -1 };
+                rmSync(reclaim, { recursive: true, force: true });
+                continue;
+            }
+            try {
+                // Gone already (another start cleared it and may be linking its own
+                // right now): nothing to clear — removing now could take theirs.
+                if (!existsSync(file))
+                    continue;
+                const current = readObject(file)?.pid;
+                if (typeof current === 'number' && (current === pid || isAlive(current)))
+                    return { ok: false, heldBy: current };
+                // Still the abandoned lock: while it exists nobody can link a new one,
+                // and only a holder of this mutex removes it, so this is the one judged.
+                rmSync(file, { force: true });
+            }
+            finally {
+                rmSync(reclaim, { recursive: true, force: true });
+            }
+        }
+        return { ok: false, heldBy: -1 };
+    }
+    finally {
+        rmSync(mine, { force: true });
+    }
+}
+/** An unreadable lock younger than this may still be being written. */
+const STALE_LOCK_GRACE_MS = 10_000;
+const SAFE_ID = /^[A-Za-z0-9-]{1,64}$/;
+/** One employee's home: its sessions and workspace. The id is checked before it names a path. */
+export function employeeHome(agentId, env = process.env) {
+    if (!SAFE_ID.test(agentId))
+        throw new Error(`not an employee id: ${JSON.stringify(agentId)}`);
+    return path.join(hostDir(env), 'employees', agentId);
+}
+/** Write JSON atomically (temp file + rename) and owner-only. */
+export function writePrivateFile(file, value) {
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    try {
+        writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(temp, 0o600);
+        renameSync(temp, file);
+    }
+    catch (err) {
+        rmSync(temp, { force: true });
+        throw err;
+    }
+}
+/**
+ * Write JSON readable by everyone on the computer: a dedicated service's
+ * state for the logged-in user (never a secret, never an email). Written in
+ * place — the folder is root's, only the file is the service's — so a reader
+ * can catch it mid-write: read it with {@link readSharedObject}.
+ */
+export function writeSharedFile(file, value) {
+    // In place: the folder is root's (a dedicated install made it), the file the service's.
+    writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o644 });
+}
+/** {@link readObject} for a file written in place: a read caught mid-write is tried once more. */
+export function readSharedObject(file) {
+    const first = readObject(file);
+    if (first !== undefined || !existsSync(file))
+        return first;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+    return readObject(file);
+}
+/** The JSON object at `file`, or `undefined` for a missing, unreadable or non-object file. */
+export function readObject(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export class ComputerMissingError extends Error {
+}
+export function saveComputer(credentials, env = process.env) {
+    const file = computerPath(env);
+    writePrivateFile(file, credentials);
+    return file;
+}
+export function loadComputer(env = process.env) {
+    const file = computerPath(env);
+    const raw = readObject(file);
+    if (!raw)
+        throw new ComputerMissingError(`This computer isn't added yet (no ${file}). Run: prohost host pair`);
+    if (typeof raw.api_key !== 'string' || !raw.api_key || typeof raw.computer_id !== 'string' || !raw.computer_id) {
+        throw new ComputerMissingError(`${file} has no computer key. Add the computer again: prohost host pair`);
+    }
+    return raw;
+}
+/** The `claude setup-token` token a dedicated install put in this home (`host/claude-oauth-token`). */
+export function readClaudeToken(env = process.env) {
+    try {
+        // Windows dedicated installs keep it in an administrators' folder instead.
+        const file = env.PROHOST_CLAUDE_TOKEN_FILE || path.join(hostDir(env), 'claude-oauth-token');
+        const token = readFileSync(file, 'utf8').trim();
+        return token || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The environment that gives a Claude Code process the installed token —
+ * passed to Claude runs, Claude terminal sessions and the Claude login checks
+ * only, never to the host's own environment (a Codex run must not see it).
+ * Re-read each time, so a rotated token applies without a restart.
+ */
+export function claudeTokenEnv(env = process.env) {
+    const token = readClaudeToken(env);
+    return token ? { CLAUDE_CODE_OAUTH_TOKEN: token } : {};
+}
+/** Delete the computer credential (after the server removed the computer). */
+export function clearComputer(env = process.env) {
+    rmSync(computerPath(env), { force: true });
+}
+export function tryLoadComputer(env = process.env) {
+    try {
+        return loadComputer(env);
+    }
+    catch {
+        return null;
+    }
+}
+export function computerOs(platform = process.platform) {
+    if (platform === 'darwin')
+        return 'macos';
+    if (platform === 'win32')
+        return 'windows';
+    return 'linux';
+}
+/** A friendly default name: "This Mac" on a Mac is the UI's job; here it is the short hostname. */
+export function defaultComputerName(hostname = os.hostname()) {
+    const short = hostname.split('.')[0]?.trim();
+    return short || 'My computer';
+}
+export function machineFacts(options = {}) {
+    const env = options.env ?? process.env;
+    const id = machineId(env);
+    if (!id)
+        throw new Error(`could not store this machine's id under ${env.PROHOST_ACCOUNTS_ROOT ?? '~/.prohost-accounts'}`);
+    const hostname = options.hostname ?? os.hostname();
+    const cpus = (options.cpus ?? os.cpus)();
+    return {
+        name: (options.name ?? '').trim() || defaultComputerName(hostname),
+        hostname,
+        machine_id: id,
+        os: computerOs(options.platform),
+        os_version: options.release ?? os.release(),
+        arch: options.arch ?? process.arch,
+        chip: cpus[0]?.model?.trim() || null,
+        memory_gb: Math.round((options.totalmem ?? os.totalmem)() / 1024 ** 3),
+        cpu_cores: cpus.length,
+    };
+}

package/dist/host/events.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The host's own record of the events it sent (`login_resting`, `login_moved`,
+ * `hold_started`, …) for the last 24 hours, so the desktop app can raise a
+ * notification for each once (`host status --json` → `events`, deduped by `id`).
+ */
+export declare const EVENT_RETENTION_MS: number;
+export declare const MAX_EVENTS = 200;
+export interface HostEvent {
+    id: string;
+    kind: string;
+    /** ISO time it was sent. */
+    at: string;
+    [field: string]: unknown;
+}
+export declare function journalPath(env?: NodeJS.ProcessEnv): string;
+/** Events in a file, newest last, from the last 24 h. */
+export declare function readEvents(file: string, now?: number): HostEvent[];
+export declare class EventJournal {
+    private readonly now;
+    private readonly file;
+    constructor(env?: NodeJS.ProcessEnv, now?: () => number);
+    add(event: Record<string, unknown>): HostEvent;
+    list(): HostEvent[];
+}

package/dist/host/events.js

@@ -0,0 +1,47 @@
+/**
+ * The host's own record of the events it sent (`login_resting`, `login_moved`,
+ * `hold_started`, …) for the last 24 hours, so the desktop app can raise a
+ * notification for each once (`host status --json` → `events`, deduped by `id`).
+ */
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { hostDir, readObject, writePrivateFile } from './computer.js';
+export const EVENT_RETENTION_MS = 24 * 60 * 60_000;
+export const MAX_EVENTS = 200;
+export function journalPath(env = process.env) {
+    return path.join(hostDir(env), 'events.json');
+}
+/** Events in a file, newest last, from the last 24 h. */
+export function readEvents(file, now = Date.now()) {
+    const raw = readObject(file)?.events;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((e) => !!e &&
+        typeof e === 'object' &&
+        typeof e.id === 'string' &&
+        typeof e.kind === 'string' &&
+        typeof e.at === 'string' &&
+        now - Date.parse(e.at) < EVENT_RETENTION_MS);
+}
+export class EventJournal {
+    now;
+    file;
+    constructor(env = process.env, now = Date.now) {
+        this.now = now;
+        this.file = journalPath(env);
+    }
+    add(event) {
+        const entry = { ...event, id: randomUUID(), kind: String(event.kind), at: new Date(this.now()).toISOString() };
+        const events = [...this.list(), entry].slice(-MAX_EVENTS);
+        try {
+            writePrivateFile(this.file, { v: 1, events });
+        }
+        catch {
+            /* a convenience: the event itself went to ProhostAI */
+        }
+        return entry;
+    }
+    list() {
+        return readEvents(this.file, this.now());
+    }
+}

package/dist/host/install.d.ts

@@ -0,0 +1,152 @@
+/**
+ * `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`.
+ */
+export declare const LAUNCHD_HOST_LABEL = "ai.prohost.host";
+export declare const SYSTEMD_HOST_UNIT = "prohost-host.service";
+export declare const WINDOWS_TASK_NAME = "\\ProhostAI\\Host";
+/** launchd / systemd wait this long after SIGTERM: the service drains (finishes runs going) first. */
+export declare 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 declare const RESTART_WAIT_MS: number;
+/** Set in a dedicated service's environment: where it publishes its state for the logged-in user. */
+export declare 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 declare const CLAUDE_TOKEN_FILE = "claude-oauth-token";
+export type ServiceRunner = (command: string, args: string[], input?: string) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+export declare const defaultServiceRunner: ServiceRunner;
+export interface ServiceSpec {
+    platform: NodeJS.Platform;
+    dedicated: boolean;
+    /** Dedicated only: the account the service runs as. */
+    serviceUser?: string;
+    /** The executable that runs the CLI: Node, or the desktop app's Electron binary (see `electron`). */
+    nodePath: string;
+    scriptPath: string;
+    /** `PROHOST_HOME` for the service. */
+    home: string;
+    /** `PATH` for the service (the launching process's). */
+    pathEnv: string;
+    /** The installing user's home (personal mode file locations). */
+    userHome: string;
+    /**
+     * The service's label (launchd label; systemd unit and Windows task are named
+     * after it). Default {@link LAUNCHD_HOST_LABEL} for the default home, else one
+     * derived from the home (see {@link defaultLabel}), so two homes never replace
+     * each other's service.
+     */
+    label?: string;
+    /**
+     * `nodePath` is Electron running as Node (the desktop app's bundled CLI): the
+     * service keeps `ELECTRON_RUN_AS_NODE=1`, or launching it would open the app.
+     */
+    electron?: boolean;
+}
+/** The label for a home: the plain one for the default home, else one with a short digest of the home. */
+export declare function defaultLabel(home: string, defaultHome: string): string;
+export declare function labelOf(spec: Pick<ServiceSpec, 'label'>): string;
+export declare function systemdUnitOf(spec: Pick<ServiceSpec, 'label'>): string;
+export declare function windowsTaskOf(spec: Pick<ServiceSpec, 'label'>): string;
+export declare function serviceArgs(spec: ServiceSpec): string[];
+/** Where a dedicated service publishes its state, read by `host status` as the logged-in user. */
+export declare function sharedBase(platform: NodeJS.Platform): string;
+export declare function sharedDirFor(spec: Pick<ServiceSpec, 'platform' | 'label'>): string;
+/**
+ * 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 declare function logPathFor(spec: ServiceSpec): string | undefined;
+/** The environment the service runs with. */
+export declare function serviceEnv(spec: ServiceSpec): Record<string, string>;
+/** Where the service definition lives. */
+export declare function serviceFilePath(spec: ServiceSpec): string;
+export declare function buildHostPlist(spec: ServiceSpec): string;
+export declare function buildHostSystemdUnit(spec: ServiceSpec): string;
+/** The `.cmd` the Windows task runs: sets the environment, then the CLI, logging to its log file. */
+export declare function buildWindowsWrapper(spec: ServiceSpec): string;
+export declare function windowsWrapperPath(spec: ServiceSpec): string;
+/** Where a Windows dedicated install keeps its task definition and wrapper: administrators write, the account reads. */
+export declare function windowsServiceDir(spec: Pick<ServiceSpec, 'label'>): string;
+/** Task Scheduler XML: at logon (personal) or at boot as the service user via S4U (dedicated). */
+export declare function buildWindowsTaskXml(spec: ServiceSpec, currentUser: string): string;
+export interface InstallOutcome {
+    ok: boolean;
+    message: string;
+    file?: string;
+}
+export interface InstallIo {
+    run?: ServiceRunner;
+    uid?: number;
+    isAdmin?: boolean;
+    currentUser?: string;
+    writeFile?: (file: string, content: string | Buffer, mode: number, flag?: 'w' | 'wx') => void;
+    readFile?: (file: string) => string | undefined;
+    /** Not a plain file of its own: a link, a folder, or a hard link (`lstat`). */
+    isLink?: (file: string) => boolean;
+    /** A symbolic link or junction (`lstat`). */
+    isSymlink?: (file: string) => boolean;
+    /** Make one folder (its parent exists): `exists` when it already did — never check-then-make. */
+    mkdirOnce?: (dir: string) => 'created' | 'exists';
+    /** Owner and link-ness of a path (`lstat`). */
+    ownerOf?: (file: string) => {
+        uid: number;
+        link: boolean;
+    } | undefined;
+    removeFile?: (file: string) => void;
+    exists?: (file: string) => boolean;
+    mkdir?: (dir: string, mode: number) => void;
+    /** Seams for waiting on a re-install's previous service to stop (macOS). */
+    sleep?: (ms: number) => void;
+    now?: () => number;
+}
+/** What a dedicated install sets up for the service user, beyond the service itself. */
+export interface DedicatedSetup {
+    /** A 0600 file holding a `claude setup-token` token: installed for the service user, never printed. */
+    claudeTokenFile?: string;
+    /** The invoking user's `PROHOST_HOME`: its computer credential is copied into the service home if that has none. */
+    adoptFrom?: string;
+}
+/** Validate a spec before anything is written. */
+export declare function specProblem(spec: ServiceSpec, io?: InstallIo, setup?: DedicatedSetup): string | undefined;
+/** Where a Windows dedicated install keeps the Claude token: an administrators' folder the account may only read. */
+export declare function windowsTokenPath(spec: Pick<ServiceSpec, 'label'>): string;
+/**
+ * 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 declare function aclPrincipals(icaclsOutput: string, dir: string): string[];
+/** The files a dedicated service publishes in its shared folder, and the pause switch. */
+export declare const SHARED_FILES: readonly ["state.json", "activity.json", "events.json"];
+export declare function installService(spec: ServiceSpec, io?: InstallIo, setup?: DedicatedSetup): InstallOutcome;
+export declare function uninstallService(spec: ServiceSpec, io?: InstallIo): InstallOutcome;
+/** Where a dedicated service user's `PROHOST_HOME` is by default. */
+export declare function serviceUserHome(platform: NodeJS.Platform, user: string): string;