@prohost/cli 0.15.0 → 0.16.1

package/dist/codehost/host.js

@@ -24,7 +24,7 @@ import { LocalTerminalServer } from './local_server.js';
 import { loadNodePty } from './pty.js';
 import { CodeHostRelay } from './relay.js';
 import { codeHostDir, codeHostInstanceId, ensurePrivateDir, loadSettings } from './settings.js';
-import { CodeTerminals, execTmux } from './terminals.js';
+import { CodeTerminals, execTmux, isDefinitive } from './terminals.js';
 import { APPROVAL_DECISIONS, isValidId, socketNameFor, TMUX_CONF } from './tmux.js';
 export const EVENT_CODE_THREAD_START_REQUESTED = 'code_thread.start_requested';
 export const EVENT_CODE_THREAD_INPUT_REQUESTED = 'code_thread.input_requested';
@@ -204,6 +204,11 @@ export class CodeHost {
     remoteTerminalAllowed() {
         return this.settings().allowRemoteTerminal;
     }
+    liveTerminals() {
+        return this.terminals
+            .list()
+            .map((record) => ({ terminalId: record.terminalId, codeThreadId: record.codeThreadId, agent: record.agent }));
+    }
     instanceCapability() {
         return `${HOST_INSTANCE_CAPABILITY_PREFIX}${this.instanceId}`;
     }
@@ -243,6 +248,8 @@ export class CodeHost {
             this.relay = new CodeHostRelay({
                 baseUrl: this.options.baseUrl,
                 apiKey: this.options.apiKey,
+                ...(this.options.fallbackApiKey ? { fallbackApiKey: this.options.fallbackApiKey } : {}),
+                ...(this.options.paused ? { dialsPaused: this.options.paused } : {}),
                 machineId: this.options.machineId,
                 instanceId: this.instanceId,
                 machine: this.options.machine,
@@ -527,6 +534,14 @@ export class CodeHost {
      * Throws {@link UnreportedOutcomeError} when the outcome never reached the
      * server, so the harness asks for the delivery again rather than ack it.
      */
+    async failStart(data, reason) {
+        const request = parseStartRequest(data);
+        if (!request)
+            return true;
+        const status = await this.events.post(request.codeThreadId, event('failed', { reason }, Date.now()));
+        // Retryable answers (401 while the token renews, 408, 429, 5xx) leave the delivery to be retried.
+        return isDefinitive(status);
+    }
     async handleStart(data) {
         const request = parseStartRequest(data);
         if (!request)

package/dist/codehost/host_stats.d.ts

@@ -6,8 +6,10 @@
  * number comes from a stock tool or Node's `os` module; anything that can't be
  * read is `null`, never 0. macOS sources: `vm_stat` (memory in use),
  * `sysctl kern.memorystatus_vm_pressure_level` (pressure), `pmset -g batt`
- * (battery), `sysctl machdep.cpu.brand_string` (spec). Elsewhere only the
- * `os`-module numbers are reported.
+ * (battery), `sysctl machdep.cpu.brand_string` (spec). Linux: `/proc/meminfo`
+ * (memory in use), `/proc/pressure/memory` (pressure, PSI), and
+ * `/sys/class/power_supply` (battery). Windows: `typeperf` performance counters
+ * (memory in use, commit charge → pressure) and PowerShell's `Win32_Battery`.
  */
 import os from 'node:os';
 export type MemoryPressure = 'normal' | 'elevated' | 'critical';
@@ -31,6 +33,47 @@ export declare function parsePmset(text: string): {
     batteryPct: number | null;
     onBattery: boolean | null;
 };
+/**
+ * Linux PSI (`/proc/pressure/memory`): the share of the last 10 s some / all
+ * runnable tasks stalled on memory. `full` stalls mean the machine is
+ * thrashing; sustained `some` stalls mean reclaim is getting in the way.
+ */
+export declare function pressureFromPsi(text: string): MemoryPressure | null;
+/** Bytes in use per `/proc/meminfo`: MemTotal − MemAvailable (what `free` calls used). */
+export declare function usedFromMeminfo(text: string): number | undefined;
+/** `/sys/class/power_supply/BAT*`: its `capacity` and `status`, and whether any AC supply is online. */
+export declare function linuxBattery(supplies: Array<{
+    name: string;
+    type?: string;
+    capacity?: string;
+    status?: string;
+    online?: string;
+}>): {
+    batteryPct: number | null;
+    onBattery: boolean | null;
+};
+/**
+ * One `typeperf -sc 1` sample of `\Memory\Available MBytes` and
+ * `\Memory\% Committed Bytes In Use`: the last CSV row, quoted values.
+ */
+export declare function parseTypeperf(text: string): {
+    availableMb?: number;
+    committedPct?: number;
+};
+/**
+ * Windows has no single pressure level, so it is read from what the memory
+ * manager is short of: physical memory left, and the commit charge against
+ * its limit (past which allocations fail outright).
+ */
+export declare function windowsPressure(sample: {
+    availableMb?: number;
+    committedPct?: number;
+}, totalBytes: number | undefined): MemoryPressure | null;
+/** PowerShell `Win32_Battery` as `<BatteryStatus>,<EstimatedChargeRemaining>`; 1 = discharging. */
+export declare function parseWindowsBattery(text: string): {
+    batteryPct: number | null;
+    onBattery: boolean | null;
+};
 /** e.g. `Apple M3 Max · 64 GB`. */
 export declare function specFrom(brand: string | undefined, totalBytes: number | undefined): string | null;
 interface CpuSample {
@@ -51,6 +94,10 @@ export interface HostStatsSamplerOptions {
         busy: number;
         total: number;
     } | undefined;
+    /** Reads a small system file (`/proc`, `/sys`); `undefined` when it can't. */
+    readFile?: (file: string) => string | undefined;
+    /** Lists a directory (`/sys/class/power_supply`); empty when it can't. */
+    listDir?: (dir: string) => string[];
 }
 /** Samples on demand. Keeps the previous CPU sample so each call reports the interval since the last. */
 export declare class HostStatsSampler {

package/dist/codehost/host_stats.js

@@ -6,11 +6,15 @@
  * number comes from a stock tool or Node's `os` module; anything that can't be
  * read is `null`, never 0. macOS sources: `vm_stat` (memory in use),
  * `sysctl kern.memorystatus_vm_pressure_level` (pressure), `pmset -g batt`
- * (battery), `sysctl machdep.cpu.brand_string` (spec). Elsewhere only the
- * `os`-module numbers are reported.
+ * (battery), `sysctl machdep.cpu.brand_string` (spec). Linux: `/proc/meminfo`
+ * (memory in use), `/proc/pressure/memory` (pressure, PSI), and
+ * `/sys/class/power_supply` (battery). Windows: `typeperf` performance counters
+ * (memory in use, commit charge → pressure) and PowerShell's `Win32_Battery`.
  */
 import { execFile } from 'node:child_process';
+import { readdirSync, readFileSync } from 'node:fs';
 import os from 'node:os';
+import path from 'node:path';
 const GB = 1024 ** 3;
 const round1 = (value) => Math.round(value * 10) / 10;
 /** Bytes in use per `vm_stat`: active + wired + compressed (what Activity Monitor calls used). */
@@ -49,6 +53,96 @@ export function parsePmset(text) {
         onBattery: source === undefined ? null : source === 'Battery Power',
     };
 }
+/**
+ * Linux PSI (`/proc/pressure/memory`): the share of the last 10 s some / all
+ * runnable tasks stalled on memory. `full` stalls mean the machine is
+ * thrashing; sustained `some` stalls mean reclaim is getting in the way.
+ */
+export function pressureFromPsi(text) {
+    const avg10 = (kind) => {
+        const match = new RegExp(`^${kind}\\s.*?avg10=([0-9.]+)`, 'm').exec(text);
+        return match ? Number.parseFloat(match[1]) : undefined;
+    };
+    const some = avg10('some');
+    const full = avg10('full');
+    if (some === undefined && full === undefined)
+        return null;
+    if ((full ?? 0) >= 10 || (some ?? 0) >= 50)
+        return 'critical';
+    if ((full ?? 0) >= 2 || (some ?? 0) >= 10)
+        return 'elevated';
+    return 'normal';
+}
+/** Bytes in use per `/proc/meminfo`: MemTotal − MemAvailable (what `free` calls used). */
+export function usedFromMeminfo(text) {
+    const kb = (label) => {
+        const match = new RegExp(`^${label}:\\s+(\\d+) kB`, 'm').exec(text);
+        return match ? Number.parseInt(match[1], 10) * 1024 : undefined;
+    };
+    const total = kb('MemTotal');
+    const available = kb('MemAvailable');
+    return total !== undefined && available !== undefined ? Math.max(0, total - available) : undefined;
+}
+/** `/sys/class/power_supply/BAT*`: its `capacity` and `status`, and whether any AC supply is online. */
+export function linuxBattery(supplies) {
+    const battery = supplies.find((s) => (s.type ?? '').trim() === 'Battery' || /^BAT/i.test(s.name));
+    if (!battery)
+        return { batteryPct: null, onBattery: null };
+    const pct = Number.parseInt((battery.capacity ?? '').trim(), 10);
+    const acOnline = supplies.some((s) => (s.type ?? '').trim() === 'Mains' && (s.online ?? '').trim() === '1');
+    const status = (battery.status ?? '').trim();
+    return {
+        batteryPct: Number.isFinite(pct) ? Math.min(100, Math.max(0, pct)) : null,
+        onBattery: status ? status === 'Discharging' && !acOnline : null,
+    };
+}
+/**
+ * One `typeperf -sc 1` sample of `\Memory\Available MBytes` and
+ * `\Memory\% Committed Bytes In Use`: the last CSV row, quoted values.
+ */
+export function parseTypeperf(text) {
+    const rows = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('"'));
+    if (rows.length < 2)
+        return {};
+    const cells = (row) => row.split('","').map((cell) => cell.replace(/^"|"$/g, ''));
+    const header = cells(rows[0]);
+    const values = cells(rows[rows.length - 1]);
+    const read = (needle) => {
+        const index = header.findIndex((name) => name.toLowerCase().includes(needle));
+        const value = index >= 0 ? Number.parseFloat(values[index] ?? '') : Number.NaN;
+        return Number.isFinite(value) ? value : undefined;
+    };
+    return { availableMb: read('available mbytes'), committedPct: read('% committed bytes in use') };
+}
+/**
+ * Windows has no single pressure level, so it is read from what the memory
+ * manager is short of: physical memory left, and the commit charge against
+ * its limit (past which allocations fail outright).
+ */
+export function windowsPressure(sample, totalBytes) {
+    const { availableMb, committedPct } = sample;
+    if (availableMb === undefined && committedPct === undefined)
+        return null;
+    const availablePct = availableMb !== undefined && totalBytes ? (availableMb * 1024 * 1024 * 100) / totalBytes : undefined;
+    if ((availablePct !== undefined && availablePct < 5) || (committedPct ?? 0) >= 95)
+        return 'critical';
+    if ((availablePct !== undefined && availablePct < 12) || (committedPct ?? 0) >= 85)
+        return 'elevated';
+    return 'normal';
+}
+/** PowerShell `Win32_Battery` as `<BatteryStatus>,<EstimatedChargeRemaining>`; 1 = discharging. */
+export function parseWindowsBattery(text) {
+    const match = /(\d+)\s*,\s*(\d+)/.exec(text.trim());
+    if (!match)
+        return { batteryPct: null, onBattery: null };
+    return {
+        batteryPct: Math.min(100, Number.parseInt(match[2], 10)),
+        onBattery: Number.parseInt(match[1], 10) === 1,
+    };
+}
 /** e.g. `Apple M3 Max · 64 GB`. */
 export function specFrom(brand, totalBytes) {
     const parts = [brand?.trim(), totalBytes ? `${Math.round(totalBytes / GB)} GB` : undefined].filter(Boolean);
@@ -76,6 +170,25 @@ const defaultRun = (file, args) => new Promise((resolve) => {
         resolve(error ? undefined : String(stdout));
     });
 });
+const defaultReadFile = (file) => {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+};
+const defaultListDir = (dir) => {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+};
+const POWER_SUPPLY_DIR = '/sys/class/power_supply';
+const TYPEPERF_COUNTERS = ['\\Memory\\Available MBytes', '\\Memory\\% Committed Bytes In Use'];
+const WINDOWS_BATTERY_SCRIPT = 'Get-CimInstance Win32_Battery | Select-Object -First 1 | ForEach-Object { "$($_.BatteryStatus),$($_.EstimatedChargeRemaining)" }';
 /** Samples on demand. Keeps the previous CPU sample so each call reports the interval since the last. */
 export class HostStatsSampler {
     options;
@@ -135,6 +248,44 @@ export class HostStatsSampler {
                 this.spec = specFrom(brand || undefined, total);
             }
         }
+        else if (this.platform === 'linux') {
+            const read = this.options.readFile ?? defaultReadFile;
+            const meminfo = read('/proc/meminfo');
+            used = meminfo ? usedFromMeminfo(meminfo) : undefined;
+            if (used === undefined) {
+                const free = safe(this.freemem);
+                used = total !== undefined && free !== undefined ? total - free : undefined;
+            }
+            const psi = read('/proc/pressure/memory');
+            memoryPressure = psi ? pressureFromPsi(psi) : null;
+            const list = this.options.listDir ?? defaultListDir;
+            battery = linuxBattery(list(POWER_SUPPLY_DIR).map((name) => {
+                const field = (key) => read(path.join(POWER_SUPPLY_DIR, name, key));
+                return { name, type: field('type'), capacity: field('capacity'), status: field('status'), online: field('online') };
+            }));
+            if (this.spec === undefined)
+                this.spec = specFrom(safe(() => os.cpus()[0]?.model), total);
+        }
+        else if (this.platform === 'win32') {
+            const [counters, power] = await Promise.all([
+                this.run('typeperf', [...TYPEPERF_COUNTERS, '-sc', '1']),
+                this.run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', WINDOWS_BATTERY_SCRIPT]),
+            ]);
+            const sample = counters ? parseTypeperf(counters) : {};
+            used =
+                sample.availableMb !== undefined && total !== undefined
+                    ? Math.max(0, total - sample.availableMb * 1024 * 1024)
+                    : undefined;
+            if (used === undefined) {
+                const free = safe(this.freemem);
+                used = total !== undefined && free !== undefined ? total - free : undefined;
+            }
+            memoryPressure = windowsPressure(sample, total);
+            if (power)
+                battery = parseWindowsBattery(power);
+            if (this.spec === undefined)
+                this.spec = specFrom(safe(() => os.cpus()[0]?.model), total);
+        }
         else {
             const free = safe(this.freemem);
             used = total !== undefined && free !== undefined ? total - free : undefined;

package/dist/codehost/relay.d.ts

@@ -91,6 +91,14 @@ export declare function parseViewerVerdict(frame: Record<string, unknown>): View
 export interface CodeHostRelayOptions {
     baseUrl: string;
     apiKey: string;
+    /**
+     * A second credential for a relay that refuses `apiKey`: `prohost host`
+     * authenticates as the computer, and falls back to the adopted agent
+     * pairing's key on a server that doesn't take computer keys here yet.
+     */
+    fallbackApiKey?: string;
+    /** No new viewer dials in while this says so (the computer is paused); open streams carry on. */
+    dialsPaused?: () => boolean;
     machineId: string;
     /**
      * This home's CLI instance (see `codeHostInstanceId`): its presence and control
@@ -135,6 +143,8 @@ export declare class CodeHostRelay {
     /** Bumped by {@link dropStreams}: a dial begun before a drop never opens. */
     private generation;
     private refused;
+    /** Authenticating with {@link CodeHostRelayOptions.fallbackApiKey} after `apiKey` was refused. */
+    private usingFallback;
     private readonly log;
     private readonly Ctor;
     private readonly setTimer;

package/dist/codehost/relay.js

@@ -256,6 +256,8 @@ export class CodeHostRelay {
     /** Bumped by {@link dropStreams}: a dial begun before a drop never opens. */
     generation = 0;
     refused;
+    /** Authenticating with {@link CodeHostRelayOptions.fallbackApiKey} after `apiKey` was refused. */
+    usingFallback = false;
     log;
     Ctor;
     setTimer;
@@ -416,7 +418,7 @@ export class CodeHostRelay {
                 try {
                     ws.send(JSON.stringify({
                         type: 'auth',
-                        api_key: this.options.apiKey,
+                        api_key: this.usingFallback ? this.options.fallbackApiKey : this.options.apiKey,
                         machine_id: this.options.machineId,
                         ...(this.options.instanceId ? { instance_id: this.options.instanceId } : {}),
                         machine: this.options.machine,
@@ -481,6 +483,15 @@ export class CodeHostRelay {
             }
             case 'auth_error': {
                 const reason = String(frame.reason ?? 'unknown');
+                // Only "a valid key, but not a pairing this server knows" — a server from
+                // before computer keys. A revoked or invalid key never falls back.
+                if (!this.usingFallback && this.options.fallbackApiKey && reason === 'not_paired') {
+                    // This server doesn't take the first key here: try the second at once.
+                    this.usingFallback = true;
+                    this.log(`    … code-host relay refused the computer key (${reason}); using the adopted agent key`);
+                    ws.close();
+                    return;
+                }
                 if (this.refused !== reason)
                     this.log(`    ✗ code-host relay refused this machine: ${reason}`);
                 this.refused = reason;
@@ -533,6 +544,11 @@ export class CodeHostRelay {
             this.dialError(dial.streamId, 'remote_terminal_disabled');
             return;
         }
+        if (this.options.dialsPaused?.()) {
+            // The relay's own word for "not now" (it knows no other).
+            this.dialError(dial.streamId, 'remote_terminal_disabled');
+            return;
+        }
         const url = relayUrl(this.options.baseUrl, STREAM_PATH);
         if (!url)
             return;

package/dist/host/api.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The public API `prohost host` speaks: `/v1/computers/*`.
+ *
+ * Pairing is unauthenticated (the device code or redeem token is the proof);
+ * everything else carries the computer key as `X-API-Key`, the header every
+ * public-API call from this CLI uses. A run's own token replaces it for that
+ * run's heartbeat, events and completion (see `service.ts`).
+ */
+export interface ComputerApiOptions {
+    baseUrl: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+export interface JsonResponse {
+    /** HTTP status, or `0` when no answer arrived. */
+    status: number;
+    /** The parsed body, when it was a JSON object. */
+    body?: Record<string, unknown>;
+    /** Why no answer arrived, or a short excerpt of a refusal. */
+    error?: string;
+}
+export declare function callJson(options: ComputerApiOptions, path: string, body: unknown, method?: 'POST' | 'GET' | 'DELETE'): Promise<JsonResponse>;
+export declare const PAIRING_START_PATH = "/v1/computers/pairing/start";
+export declare const PAIRING_POLL_PATH = "/v1/computers/pairing/poll";
+export declare const PAIRING_REDEEM_PATH = "/v1/computers/pairing/redeem";
+export declare const PAIRING_ADOPT_PATH = "/v1/computers/pairing/adopt";
+export declare function computerPath(computerId: string): string;
+export type RevokeResult = 'revoked' | 'already_gone' | 'failed';
+/**
+ * Remove this computer from its workspace, as the computer (`DELETE
+ * /v1/computers/{id}`): its key stops working. A key the server no longer
+ * knows (401) or a computer already removed (404 / 410) is already done.
+ */
+export declare function revokeComputer(options: ComputerApiOptions, computerId: string): Promise<{
+    result: RevokeResult;
+    status: number;
+    error?: string;
+}>;
+export declare function statusPath(computerId: string): string;
+export declare function eventsPath(computerId: string): string;
+export declare function claimPath(computerId: string, runId: string): string;
+/** One skill file the claim hands over, written into the run's workspace. */
+export interface SkillFile {
+    path: string;
+    content: string;
+}
+export interface ClaimedSkill {
+    key: string;
+    version?: string | number;
+    files: SkillFile[];
+}
+export type ClaimResult = {
+    kind: 'claimed';
+    runToken: string;
+    expiresAt?: string;
+    payload: Record<string, unknown>;
+    skills: ClaimedSkill[];
+}
+/** Another computer has it (409): skip it, never run it. */
+ | {
+    kind: 'elsewhere';
+}
+/** Gone server-side (404 / 410): nothing to run. */
+ | {
+    kind: 'gone';
+    status: number;
+}
+/** No answer, or one worth asking again (429 / 5xx). */
+ | {
+    kind: 'retry';
+    status: number;
+    error?: string;
+}
+/** Any other refusal. */
+ | {
+    kind: 'refused';
+    status: number;
+    error?: string;
+};
+/** Claim a run for this computer. Exactly one computer ever gets a 200. */
+export declare function claimRun(options: ComputerApiOptions, computerId: string, runId: string): Promise<ClaimResult>;

package/dist/host/api.js

@@ -0,0 +1,122 @@
+/**
+ * The public API `prohost host` speaks: `/v1/computers/*`.
+ *
+ * Pairing is unauthenticated (the device code or redeem token is the proof);
+ * everything else carries the computer key as `X-API-Key`, the header every
+ * public-API call from this CLI uses. A run's own token replaces it for that
+ * run's heartbeat, events and completion (see `service.ts`).
+ */
+import { USER_AGENT } from '../version.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+export async function callJson(options, path, body, method = 'POST') {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(`${options.baseUrl.replace(/\/+$/, '')}${path}`, {
+            method,
+            redirect: 'error',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': USER_AGENT,
+                ...(options.apiKey ? { 'X-API-Key': options.apiKey } : {}),
+            },
+            ...(method === 'POST' ? { body: JSON.stringify(body ?? {}) } : {}),
+            signal: controller.signal,
+        });
+        const text = await response.text().catch(() => '');
+        let parsed;
+        try {
+            const value = text ? JSON.parse(text) : undefined;
+            if (value && typeof value === 'object' && !Array.isArray(value))
+                parsed = value;
+        }
+        catch {
+            parsed = undefined;
+        }
+        const ok = response.status >= 200 && response.status < 300;
+        return { status: response.status, body: parsed, ...(ok ? {} : { error: text.slice(0, 300) }) };
+    }
+    catch (err) {
+        if (controller.signal.aborted)
+            return { status: 0, error: `timed out after ${Math.round(timeoutMs / 1000)}s` };
+        return { status: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export const PAIRING_START_PATH = '/v1/computers/pairing/start';
+export const PAIRING_POLL_PATH = '/v1/computers/pairing/poll';
+export const PAIRING_REDEEM_PATH = '/v1/computers/pairing/redeem';
+export const PAIRING_ADOPT_PATH = '/v1/computers/pairing/adopt';
+export function computerPath(computerId) {
+    return `/v1/computers/${encodeURIComponent(computerId)}`;
+}
+/**
+ * Remove this computer from its workspace, as the computer (`DELETE
+ * /v1/computers/{id}`): its key stops working. A key the server no longer
+ * knows (401) or a computer already removed (404 / 410) is already done.
+ */
+export async function revokeComputer(options, computerId) {
+    const response = await callJson(options, computerPath(computerId), undefined, 'DELETE');
+    if (response.status >= 200 && response.status < 300)
+        return { result: 'revoked', status: response.status };
+    if ([401, 404, 410].includes(response.status))
+        return { result: 'already_gone', status: response.status };
+    return { result: 'failed', status: response.status, ...(response.error ? { error: response.error } : {}) };
+}
+export function statusPath(computerId) {
+    return `/v1/computers/${encodeURIComponent(computerId)}/status`;
+}
+export function eventsPath(computerId) {
+    return `/v1/computers/${encodeURIComponent(computerId)}/events`;
+}
+export function claimPath(computerId, runId) {
+    return `/v1/computers/${encodeURIComponent(computerId)}/runs/${encodeURIComponent(runId)}/claim`;
+}
+function parseSkills(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((raw) => {
+        const skill = raw;
+        if (!skill || typeof skill.key !== 'string' || !Array.isArray(skill.files))
+            return [];
+        const files = skill.files.flatMap((f) => {
+            const file = f;
+            return file && typeof file.path === 'string' && typeof file.content === 'string'
+                ? [{ path: file.path, content: file.content }]
+                : [];
+        });
+        const version = typeof skill.version === 'string' || typeof skill.version === 'number' ? skill.version : undefined;
+        return [{ key: skill.key, ...(version !== undefined ? { version } : {}), files }];
+    });
+}
+/** Claim a run for this computer. Exactly one computer ever gets a 200. */
+export async function claimRun(options, computerId, runId) {
+    const response = await callJson(options, claimPath(computerId, runId), {});
+    if (response.status === 200 || response.status === 201) {
+        const body = response.body ?? {};
+        const token = body.run_token;
+        const payload = body.payload;
+        if (typeof token !== 'string' || !token || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+            return { kind: 'refused', status: response.status, error: 'claim answer carried no run token or payload' };
+        }
+        return {
+            kind: 'claimed',
+            runToken: token,
+            ...(typeof body.expires_at === 'string' ? { expiresAt: body.expires_at } : {}),
+            payload: payload,
+            skills: parseSkills(body.skills),
+        };
+    }
+    if (response.status === 409)
+        return { kind: 'elsewhere' };
+    if (response.status === 404 || response.status === 410)
+        return { kind: 'gone', status: response.status };
+    if (response.status === 0 || response.status === 429 || response.status >= 500) {
+        return { kind: 'retry', status: response.status, error: response.error };
+    }
+    return { kind: 'refused', status: response.status, error: response.error };
+}

package/dist/host/capacity.d.ts

@@ -0,0 +1,41 @@
+/**
+ * How many things this computer works on at once, and when it takes no new work.
+ */
+import type { MemoryPressure } from '../codehost/host_stats.js';
+export type Workload = 'coding' | 'chat';
+/** Memory one run takes, by what the employees here mostly do. */
+export declare const RUN_MEMORY_GB: Record<Workload, number>;
+/** Never recommend more than this, however big the machine. */
+export declare const MAX_RECOMMENDED_CAPACITY = 16;
+/** Memory kept for the person using the computer: the larger of these. */
+export declare const RESERVE_MIN_GB = 8;
+export declare const RESERVE_SHARE = 0.25;
+/**
+ * The recommended capacity: memory after the reserve, divided by what one run
+ * takes; at most half the cores (a run is a CLI plus the tools it starts); at
+ * least 1, at most {@link MAX_RECOMMENDED_CAPACITY}.
+ */
+export declare function recommendCapacity(hardware: {
+    memoryGb: number;
+    cores: number;
+    workload?: Workload;
+}): number;
+/** What the server's `capacity` (null = use recommended) and the local recommendation come to. */
+export declare function effectiveCapacity(configured: number | null | undefined, recommended: number): number;
+export type HeldReason = 'paused' | 'pressure' | 'battery';
+export interface HoldInputs {
+    paused: boolean;
+    holdOnPressure: boolean;
+    holdOnBattery: boolean;
+    memoryPressure: MemoryPressure | null;
+    onBattery: boolean | null;
+}
+/**
+ * Why new work waits, or `null`. Work already running is never stopped by a
+ * hold; it only keeps the next run from starting.
+ *
+ * Pressure holds only at `critical`: `elevated` is routine on a busy Mac
+ * (the compressor is working), and holding on it would idle a computer that is
+ * coping. A battery hold needs the OS to say it is on battery — unknown is not.
+ */
+export declare function holdReason(inputs: HoldInputs): HeldReason | null;

package/dist/host/capacity.js

@@ -0,0 +1,48 @@
+/**
+ * How many things this computer works on at once, and when it takes no new work.
+ */
+/** Memory one run takes, by what the employees here mostly do. */
+export const RUN_MEMORY_GB = { coding: 4, chat: 1.5 };
+/** Never recommend more than this, however big the machine. */
+export const MAX_RECOMMENDED_CAPACITY = 16;
+/** Memory kept for the person using the computer: the larger of these. */
+export const RESERVE_MIN_GB = 8;
+export const RESERVE_SHARE = 0.25;
+/**
+ * The recommended capacity: memory after the reserve, divided by what one run
+ * takes; at most half the cores (a run is a CLI plus the tools it starts); at
+ * least 1, at most {@link MAX_RECOMMENDED_CAPACITY}.
+ */
+export function recommendCapacity(hardware) {
+    const memory = Number.isFinite(hardware.memoryGb) ? Math.max(0, hardware.memoryGb) : 0;
+    const cores = Number.isFinite(hardware.cores) ? Math.max(1, Math.floor(hardware.cores)) : 1;
+    const perRun = RUN_MEMORY_GB[hardware.workload ?? 'chat'];
+    const reserve = Math.max(RESERVE_MIN_GB, memory * RESERVE_SHARE);
+    const byMemory = Math.floor((memory - reserve) / perRun);
+    const byCores = Math.floor(cores / 2);
+    return Math.max(1, Math.min(MAX_RECOMMENDED_CAPACITY, byMemory, byCores));
+}
+/** What the server's `capacity` (null = use recommended) and the local recommendation come to. */
+export function effectiveCapacity(configured, recommended) {
+    if (typeof configured === 'number' && Number.isInteger(configured) && configured >= 1) {
+        return Math.min(configured, 64);
+    }
+    return recommended;
+}
+/**
+ * Why new work waits, or `null`. Work already running is never stopped by a
+ * hold; it only keeps the next run from starting.
+ *
+ * Pressure holds only at `critical`: `elevated` is routine on a busy Mac
+ * (the compressor is working), and holding on it would idle a computer that is
+ * coping. A battery hold needs the OS to say it is on battery — unknown is not.
+ */
+export function holdReason(inputs) {
+    if (inputs.paused)
+        return 'paused';
+    if (inputs.holdOnPressure && inputs.memoryPressure === 'critical')
+        return 'pressure';
+    if (inputs.holdOnBattery && inputs.onBattery === true)
+        return 'battery';
+    return null;
+}