@slock-ai/computer 0.0.37 → 0.0.52

package/dist/lib/index.d.ts

@@ -1,679 +0,0 @@
-type DaemonState = {
-    running: true;
-    pid: number;
-} | {
-    running: false;
-};
-type ServerHealth = "ok" | "degraded" | "offline";
-interface ServerStatusRow {
-    serverId: string;
-    serverSlug: string | null;
-    serverMachineId: string;
-    serverUrl: string;
-    attachedAt: string | null;
-    serverRunnerLogPath: string;
-    daemon: DaemonState;
-    /** v6 §11 health enum surfaced in `status` table (PR-H §3.3). */
-    health: ServerHealth;
-}
-interface ComputerStatusReport {
-    slockHome: string;
-    loggedIn: boolean;
-    userId: string | null;
-    loginServerUrl: string | null;
-    userSessionError: string | null;
-    service: DaemonState & {
-        logPath: string;
-    };
-    servers: ServerStatusRow[];
-}
-
-interface LegacyMachineRosterEntry {
-    daemonId: string;
-    apiKeyFingerprint: string;
-    machineName: string;
-    hostname: string | null;
-    lastSeenAt: string | null;
-}
-type LegacyMachineRosterResult = {
-    status: "success";
-    entries: LegacyMachineRosterEntry[];
-} | {
-    status: "auth_required";
-} | {
-    status: "not_authorized";
-} | {
-    status: "disabled";
-} | {
-    status: "error";
-    code: string;
-};
-/** A server the user belongs to. `role` mirrors the server-side
- *  `server_members.role` enum (`owner | admin | member`). */
-interface UserServerEntry {
-    id: string;
-    name: string;
-    slug: string;
-    role: "owner" | "admin" | "member";
-}
-type UserServersResult = {
-    status: "success";
-    servers: UserServerEntry[];
-} | {
-    status: "auth_required";
-} | {
-    status: "error";
-    code: string;
-};
-declare class ServersClient {
-    private readonly baseUrl;
-    private readonly accessToken;
-    constructor(baseUrl: string, accessToken: string);
-    private url;
-    list(): Promise<UserServersResult>;
-}
-declare class LegacyMachinesClient {
-    private readonly baseUrl;
-    private readonly accessToken;
-    constructor(baseUrl: string, accessToken: string);
-    private url;
-    list(serverSlug: string): Promise<LegacyMachineRosterResult>;
-}
-interface RunnerListItem {
-    agentId: string;
-    name: string;
-    status: string;
-    model: string;
-    runtime: string;
-}
-
-/**
- * Per-runner lifecycle states (§3.2). One state at a time per runner.
- *
- *   starting  — spawned, not yet reporting ready
- *   running   — healthy, reporting heartbeats
- *   degraded  — alive but not satisfying health invariants (e.g. crash
- *               budget near breach, see §1/§2)
- *   crashed   — observed exit / fatal signal
- *   stopped   — intentional stop (operator-driven via `runners stop` or
- *               service shutdown)
- */
-declare const RUNNER_STATE_VALUES: readonly ["starting", "running", "degraded", "crashed", "stopped"];
-type RunnerState = (typeof RUNNER_STATE_VALUES)[number];
-declare function isRunnerState(value: unknown): value is RunnerState;
-/**
- * Service (service) lifecycle states (§3.2). Mirrors runner shape but
- * narrower — the service is a singleton per install root.
- *
- *   starting  — pidfile written, socket not yet listening
- *   running   — socket listening, heartbeat active
- *   degraded  — service alive but one or more invariants violated
- *               (e.g. SERVICE_DEGRADED §7.3 crash-budget breach)
- *   stopping  — graceful shutdown in flight (SERVICE_SHUTTING_DOWN
- *               §7.3 emitted to clients)
- *   stopped   — pidfile cleared, socket closed
- */
-declare const SERVICE_STATE_VALUES: readonly ["starting", "running", "degraded", "stopping", "stopped"];
-type ServiceState = (typeof SERVICE_STATE_VALUES)[number];
-declare function isServiceState(value: unknown): value is ServiceState;
-
-/**
- * IPC error code family — the seed that `ServiceClient.request` and
- * `ServiceClient.events` propagate. Forward-only post v9-sign: additions
- * are additive minor library bumps; renames / removals are major.
- *
- * Full §7.3 enumeration (SETUP/ATTACH/MIGRATE/UPGRADE/SERVICE families)
- * lands in a follow-up reconcile commit that also unifies the codes
- * currently emitted via `ComputerServiceError` across services/*.
- */
-declare const IPC_ERROR_CODES: readonly ["IPC_FRAME_TOO_LARGE", "IPC_PROTOCOL_VERSION_UNSUPPORTED", "IPC_PROTOCOL_HANDSHAKE_FAILED", "IPC_HEARTBEAT_TIMEOUT", "IPC_MALFORMED_FRAME", "IPC_REQUEST_TIMEOUT", "IPC_REQUEST_CANCELED", "IPC_CLIENT_CLOSED"];
-type IpcErrorCode = (typeof IPC_ERROR_CODES)[number];
-/**
- * Runtime narrow guard — exposed so consumers can pattern-match without
- * pulling in a generic `as` cast. The CI gate (§7.4) over a final
- * `ERROR_CODES` union will subsume this once the reconcile lands.
- */
-declare function isIpcErrorCode(value: unknown): value is IpcErrorCode;
-/**
- * Caller-facing options for `ServiceClient.request`. Pairs active cancel
- * (`signal` — primary G-stage unmount path) with passive deadline
- * (`timeoutMs` — library-side safety net). On either path the client
- * emits an IPC `cancel` frame for the in-flight request id and rejects
- * the returned promise with `IPC_REQUEST_CANCELED` or
- * `IPC_REQUEST_TIMEOUT` respectively (§4.4).
- */
-interface RequestOptions {
-    signal?: AbortSignal;
-    timeoutMs?: number;
-}
-/**
- * Typed RPC table — keys are kebab-case wire literals (§5.5), values are
- * per-method `{ params, result }` pairs. The v9 sign-lock seed listed
- * here is the §3.2 6-method floor; new methods are additive minor bumps
- * (extending this map).
- *
- * State-reader results (`service-status` / `runner-status` /
- * `list-runners`) are pinned to the lib reader return types — the
- * D-stage §4 IPC handlers in PR-impl-2 satisfy the wire surface by
- * delegating to those readers (mechanical `satisfies`).
- *
- * Mutation results (`upgrade-start` / `reset-service` / `reset-runner`)
- * remain `unknown` here — they pin alongside the PR-impl-3 §X migration /
- * verb pipeline that owns the corresponding handlers.
- */
-interface RequestMethodMap {
-    "service-status": {
-        params: void;
-        result: ServiceStatusResult;
-    };
-    "runner-status": {
-        params: {
-            serverId: string;
-        };
-        result: RunnerStatusResult;
-    };
-    "list-runners": {
-        params: void;
-        result: ListRunnersResult;
-    };
-    "upgrade-start": {
-        params: {
-            targetVersion?: string;
-        };
-        result: UpgradeStartResult;
-    };
-    "reset-service": {
-        params: void;
-        result: ResetServiceResult;
-    };
-    "reset-runner": {
-        params: {
-            serverId: string;
-        };
-        result: ResetRunnerResult;
-    };
-}
-/**
- * Server-pushed event over `ServiceClient.events`. The discriminant field
- * is `kind` (§5.5 — established at v9.7 sign); values are past-participle
- * kebab-case literals. The 6-kind enumeration is the v9.8 §4.4 floor.
- *
- * Payload shapes finalize alongside §4 IPC impl (PR-impl-2, liuliu-owned);
- * the discriminator is locked here so consumers can write exhaustive
- * switches today.
- *
- * Note: v9.8 §4.4 has an example block still showing the v9.7-pre field
- * name `topic` + present-tense values; §5.5 is the byte-pin source of
- * truth (`kind` + past-participle). The §4.4 example will be reconciled
- * in a follow-up doc-clean pass.
- */
-type ServiceEvent = {
-    kind: "service-state-changed";
-    payload: unknown;
-} | {
-    kind: "runner-state-changed";
-    payload: unknown;
-} | {
-    kind: "runner-attached";
-    payload: unknown;
-} | {
-    kind: "runner-detached";
-    payload: unknown;
-} | {
-    kind: "upgrade-log-appended";
-    payload: unknown;
-} | {
-    kind: "heartbeat";
-    payload: unknown;
-};
-/**
- * Library-side error envelope thrown by `ServiceClient`. `code` is a
- * member of the §7 closed-set; `cause` is retained in-process only and
- * MUST NOT cross IPC / CLI fail boundaries (§7.4 redaction).
- */
-declare class ServiceClientError extends Error {
-    readonly code: IpcErrorCode;
-    readonly cause?: unknown;
-    constructor(code: IpcErrorCode, message: string, cause?: unknown);
-}
-/**
- * Typed IPC client. The implementation in PR-impl-2 §4 satisfies this
- * interface; this commit only locks the surface.
- *
- * Termination semantics (§4.7):
- *   - `events` completes naturally (`Symbol.asyncIterator` return) on any
- *     socket-close path (graceful local/remote, transient, TCP RST). The
- *     `for-await` loop exits without throwing — idiomatic reconnect is a
- *     plain outer `while (!stopped) { … }` wrap, no try/catch.
- *   - `events` THROWS `ServiceClientError` only on protocol-level
- *     failures: handshake mismatch, frame parse, frame > 1 MiB.
- * The disjoint split lets consumers distinguish "retry" (iterator end)
- * from "give up" (throw) without runtime classification.
- */
-interface ServiceClient {
-    events: AsyncIterable<ServiceEvent>;
-    request<M extends keyof RequestMethodMap>(method: M, params: RequestMethodMap[M]["params"], options?: RequestOptions): Promise<RequestMethodMap[M]["result"]>;
-    close(): Promise<void>;
-}
-/**
- * Connection options. `protocolVersion` lets a consumer opt-in to a
- * specific handshake version; the service negotiates highest mutually
- * supported (§4.3) and may reject with `IPC_PROTOCOL_VERSION_UNSUPPORTED`.
- */
-interface ConnectServiceOptions {
-    protocolVersion?: number;
-}
-/**
- * Open a typed IPC connection to the Computer service. Throws
- * `ServiceClientError` on handshake failure. Concrete implementation
- * lands in PR-impl-2 §4 (liuliu-owned); the type is locked here so
- * `apps/slock-computer-app` and other library consumers can type-check
- * call sites before the transport ships.
- */
-type ConnectService = (installRoot: string, options?: ConnectServiceOptions) => Promise<ServiceClient>;
-
-/**
- * Canonical lib-side name for the `service-status` reader result, aligned
- * with the wire method literal. Identical shape to `ComputerStatusReport`
- * (re-exported above for callers that prefer the historical internal
- * name).
- *
- * SECRET-FREE INVARIANT: the report carries server attachment IDENTITY
- * and pid/liveness derived from filesystem state but NEVER the user
- * access token or any `sk_computer_*` credential (status.ts §3.3.1
- * redline, enforced by `status.test.ts` token-leak guards).
- */
-type ServiceStatusResult = ComputerStatusReport;
-/**
- * Per-server block in `ListRunnersResult.servers[]`. The discriminator
- * preserves the underlying `RunnersClient.list()` outcome so a single
- * server's `unauthorized` / `error` does NOT mask another server's data.
- */
-type RunnerListPerServer = {
-    serverId: string;
-    serverSlug: string | null;
-    status: "ok";
-    whitelist: string[];
-    runners: RunnerListItem[];
-} | {
-    serverId: string;
-    serverSlug: string | null;
-    status: "unauthorized";
-} | {
-    serverId: string;
-    serverSlug: string | null;
-    status: "error";
-    code: string;
-};
-/**
- * Aggregate result of `listRunners(installRoot, opts?)`. When `opts.serverId`
- * is omitted, `servers[]` contains one block per attached server (zero
- * blocks if the Computer has no attachments). When `opts.serverId` is set,
- * `servers[]` contains exactly that server's block, or the call throws
- * `StateReaderError("NOT_ATTACHED")` if the id is not attached.
- */
-interface ListRunnersResult {
-    servers: RunnerListPerServer[];
-}
-/**
- * Result of `readRunnerStatus(installRoot, serverId)` — per-server state
- * row plus the runners running on it. Unauthorized / error discriminate
- * the runners-API outcome while still surfacing the `server` row so the
- * caller has the daemon state context.
- */
-type RunnerStatusResult = {
-    status: "ok";
-    server: ServerStatusRow;
-    whitelist: string[];
-    runners: RunnerListItem[];
-} | {
-    status: "unauthorized";
-    server: ServerStatusRow;
-} | {
-    status: "error";
-    server: ServerStatusRow;
-    code: string;
-};
-/**
- * State-reader error closed set. Library boundary errors only — does NOT
- * include the CLI ambient-rule errors (`NO_ATTACHMENT` / `AMBIGUOUS_SERVER`)
- * which are v4 §6 ergonomics handled by the CLI wrapper, not the lib
- * primitive.
- */
-declare const STATE_READER_ERROR_CODES: readonly ["NOT_ATTACHED", "INVALID_ATTACHMENT"];
-type StateReaderErrorCode = (typeof STATE_READER_ERROR_CODES)[number];
-/**
- * Library-side error envelope thrown by state-readers. Lib readers
- * NEVER call `fail()` / `process.exit` — CLI wrappers translate this to
- * `fail(code, message)` at the boundary; D-stage IPC handlers map it to
- * an IPC error frame.
- */
-declare class StateReaderError extends Error {
-    readonly code: StateReaderErrorCode;
-    constructor(code: StateReaderErrorCode, message: string);
-}
-
-/**
- * Result of `reset-service` (`slock-computer reset --service`). Clears
- * the service-level `crashHistory` and transitions service state
- * `degraded → running`. MUST NOT kill runners (§1.3).
- *
- * `previousState` reports the state observed prior to the reset write —
- * for callers that want to log/surface "was already running" vs
- * "recovered from degraded". `clearedCrashCount` counts the entries
- * removed from `service.state.json::crashHistory`.
- */
-interface ResetServiceResult {
-    status: "ok";
-    previousState: ServiceState;
-    clearedCrashCount: number;
-}
-/**
- * Result of `reset-runner` (`slock-computer reset --runner <slug>`).
- * Clears the per-runner `crashHistory` and transitions runner state
- * `degraded → running`. MUST NOT respawn or kill the runner process
- * (§2.4).
- *
- * `status: "not-found"` is returned when the resolved `serverId` does
- * not correspond to an attached server (the CLI ambient `--server` slug
- * resolver returns its own error before the handler is invoked; this
- * branch defends the IPC path where the caller passes a serverId
- * directly).
- */
-type ResetRunnerResult = {
-    status: "ok";
-    serverId: string;
-    previousState: RunnerState;
-    clearedCrashCount: number;
-} | {
-    status: "not-found";
-    serverId: string;
-};
-/**
- * Result of `upgrade-start` (§12 phase pipeline trigger). The same
- * pipeline is funneled by manual CLI / auto scheduler / IPC; this
- * result describes the trigger outcome only — the per-phase events
- * stream over `ServiceEvent` (`upgrade-log-appended` kind).
- *
- * `status: "already-running"` is returned when an upgrade is already
- * in flight; `upgradeId` then refers to the in-flight upgrade so the
- * caller can attach to its event stream instead of starting a new one.
- */
-interface UpgradeStartResult {
-    status: "started" | "already-running";
-    upgradeId: string;
-    targetVersion: string;
-}
-/**
- * Identity record for a legacy `@slock-ai/daemon` machine candidate
- * surfaced by `detectLegacyMigration`. Each candidate is the result of
- * intersecting (a) local `<installRoot>/machines/machine-<fp>/owner.json`
- * evidence with (b) the server's `GET /api/computer/legacy-machines`
- * roster on `apiKeyFingerprint` for the logged-in user + target server.
- * The shape is identity-only — it never carries credentials.
- *
- * `apiKeyFingerprint` is the v9.9 intersection key —
- * `sha256(apiKey).slice(0,16)`. The same value is computed locally by
- * the legacy daemon (`packages/daemon/src/machineLock.ts`) and stored
- * server-side on `daemons.api_key_fingerprint` (handshake-backfilled).
- * Stable as long as the legacy api key is unchanged.
- *
- * `daemonId` is the server's `daemons.id` UUID (display + post-migration
- * identity). It is NOT a join key — fingerprint is. Cody redline
- * msg=ec68c27f: server daemonId / machineName are display-only.
- *
- * `localPath` is the absolute path of the local owner.json that
- * supplied the fingerprint side of the intersection. Surfaced so the
- * picker can show the operator which on-disk legacy install they are
- * about to adopt, and so the manual `--migrate-from` flag's three-gate
- * validator (path-readable / owner.json-parseable / fingerprint-in-roster)
- * can return a candidate that points at the same path the operator
- * passed.
- *
- * `machineName` / `hostname` / `lastSeenAt` come from the server roster
- * row — display-only, used for picker presentation. May be empty for
- * stale rows; the picker tolerates blanks.
- */
-interface LegacyMachineCandidate {
-    apiKeyFingerprint: string;
-    daemonId: string;
-    localPath: string;
-    machineName: string;
-    hostname?: string;
-    lastSeenAt?: string;
-}
-/**
- * §X.2 migration detection result — the discriminated union returned by
- * `detectLegacyMigration(installRoot, target)`.
- *
- * Per RFC v9.9 §X.2:
- *   - `candidates`: zero-or-more legacy daemons survived the
- *     local-owner-json ∩ server-roster intersection. Empty intersection
- *     is a valid `candidates` result with `candidates.length === 0` —
- *     the setup flow's fresh-attach trigger #1 (§X.4). One-or-more
- *     candidates → setup picker prompts the operator (TTY) or falls
- *     through to fresh attach (non-TTY).
- *   - `server-unavailable`: roster fetch failed (network / auth /
- *     server gate off / 5xx). Setup falls through to fresh attach
- *     under the documented "best-effort detection" discipline — a
- *     transiently unreachable server must NOT block fresh setup.
- *
- * Fingerprint discipline (Cody msg=ec68c27f redline):
- *   - `apiKeyFingerprint` is treated as a sensitive identity. It is
- *     scoped to this caller's authenticated request and never logged.
- *   - The intersection is setup's adoption identity after user login:
- *     a candidate proves the server has a roster row keyed by the same
- *     fingerprint that appears in the local owner.json. The server
- *     still enforces ownership by requiring the session user to own the
- *     selected machine row; fingerprint is only the selector.
- */
-/**
- * Closed set of `MigrationDetection.kind` discriminator values. Mirrors
- * the `IPC_ERROR_CODES` / `RUNNER_STATE_VALUES` `as const` tuple pattern
- * so consumers can pattern-match exhaustively and so a future §7.4 CI
- * gate can verify the runtime kind against the type union without an
- * `as` cast (state-machine-modeling discipline — correlated/mutex
- * properties land as a closed-set state-enum).
- */
-declare const MIGRATION_DETECTION_KINDS: readonly ["candidates", "server-unavailable"];
-type MigrationDetectionKind = (typeof MIGRATION_DETECTION_KINDS)[number];
-/** Runtime narrow guard for `MigrationDetection.kind`. */
-declare function isMigrationDetectionKind(value: unknown): value is MigrationDetectionKind;
-type MigrationDetection = {
-    kind: "candidates";
-    candidates: LegacyMachineCandidate[];
-} | {
-    kind: "server-unavailable";
-};
-
-/**
- * Roster fetcher contract — `LegacyMachinesClient.list(serverSlug)`
- * satisfies this structurally. Defining it as an interface here lets
- * tests stub the network call without instantiating undici.
- */
-interface LegacyMachineRosterClient {
-    list(serverSlug: string): Promise<LegacyMachineRosterResult>;
-}
-/**
- * Detect whether the logged-in user has a legacy `@slock-ai/daemon`
- * machine on the target server that matches a local install on this
- * host (intersection on `apiKeyFingerprint`).
- *
- * Returns:
- *   - `{ kind: "candidates"; candidates: LegacyMachineCandidate[] }` —
- *     zero-or-more mutually-known legacy daemons. Empty list is the
- *     §X.4 fresh-attach trigger #1; non-empty drives the picker.
- *   - `{ kind: "server-unavailable" }` — roster fetch failed
- *     transiently. Caller falls through to fresh attach.
- *
- * Lib-pure: no env reads, no terminal IO, no `process.exit`. Local
- * filesystem errors are swallowed; only the roster-fetch outcome can
- * change the discriminator.
- */
-declare function detectLegacyMigration(installRoot: string, serverSlug: string, client: LegacyMachineRosterClient): Promise<MigrationDetection>;
-/**
- * Manual `--migrate-from <path>` validator — the three-gate chain that
- * RFC v9.9 §X.4 specifies for the manual escape hatch when the picker's
- * intersection set is non-empty but the operator wants to migrate a
- * different on-disk install.
- *
- * Gates (executed in order, hard-fail on first failure):
- *   1. `MIGRATE_FROM_NOT_FOUND` — `path` does not exist or is not a
- *      readable directory / file. Accepts either the `machines/
- *      machine-<fp>/` directory or its `daemon.lock/owner.json`
- *      directly; the latter is what doctor / forensic flows surface.
- *   2. `MIGRATE_FROM_INVALID` — owner.json is unreadable, malformed,
- *      or missing a 16-hex-char `apiKeyFingerprint` field.
- *   3. `MIGRATE_FROM_NOT_OWNED` — owner.json's fingerprint is not in
- *      the supplied roster (the logged-in user does not have a
- *      legacy daemon row with this fingerprint on the target server,
- *      or the row is already migrated / NULL-fingerprinted).
- *
- * On success returns the same `LegacyMachineCandidate` shape the
- * picker emits, so the setup driver's adoption call is the same code
- * path on both branches.
- */
-type ManualPathValidation = {
-    ok: true;
-    candidate: LegacyMachineCandidate;
-} | {
-    ok: false;
-    code: "MIGRATE_FROM_NOT_FOUND" | "MIGRATE_FROM_INVALID" | "MIGRATE_FROM_NOT_OWNED";
-};
-declare function validateManualMigratePath(inputPath: string, roster: LegacyMachineRosterEntry[]): Promise<ManualPathValidation>;
-
-type PickerSelection = {
-    kind: "candidate";
-    index: number;
-} | {
-    kind: "fresh";
-} | {
-    kind: "manual";
-    path: string;
-};
-/**
- * Closed-set enumeration of the §X.4 fresh-attach triggers. Used in
- * setup info() lines so QA can grep for "fresh trigger: <name>" and
- * test mocks can assert that ONLY these inputs route to fresh attach
- * (Cody NIT `msg=9102a817`). The picker function itself only emits
- * `explicit-zero` / `eof`; the other three are decided upstream in
- * `runSetup` before the picker ever fires.
- */
-declare const MIGRATION_FRESH_TRIGGERS: readonly ["empty-intersection", "explicit-zero", "eof", "non-tty", "server-unavailable"];
-type MigrationFreshTrigger = (typeof MIGRATION_FRESH_TRIGGERS)[number];
-/**
- * Pure picker grammar — extracted so it can be exercised by unit tests
- * without stubbing global stdin/stdout. RFC v9.9 §X.4 (post-Jianwei FAIL
- * `msg=ecc2e57e` / Cody NIT `msg=9102a817`):
- *   - `1`..`N` / `<Enter>` → adopt that candidate (1-indexed; Enter picks
- *     the first candidate, since the operator already saw the
- *     intersection list).
- *   - `0` → fresh attach (Trigger #2: explicit-zero).
- *   - EOF (Ctrl-D / closed stdin) → fresh attach (Trigger #2: eof).
- *   - `m` / `M` → emits `manual` and prompts for path on the next line.
- *   - Anything else → reprompt. The picker NEVER silently falls through
- *     to fresh attach on unrecognized input — that was the B1/B4 contract
- *     drift that QA rejected.
- */
-declare function pickMigrationCandidateFromInput(candidates: LegacyMachineCandidate[], read: () => Promise<{
-    line: string;
-    eof: boolean;
-}>, write: (s: string) => void): Promise<PickerSelection>;
-
-/**
- * Read the Computer-level aggregate status from `installRoot`. Identical
- * shape to `buildStatusReport(installRoot)` — exposed under the
- * wire-aligned name `readServiceStatus` for IPC `service-status` parity.
- */
-declare function readServiceStatus(installRoot: string): Promise<ServiceStatusResult>;
-/**
- * Read a single attached server's daemon state row plus the runners
- * currently running on it. Throws `StateReaderError("NOT_ATTACHED")` if
- * `serverId` is not in the attached set, or `"INVALID_ATTACHMENT"` if
- * the runner.state.json under that id is unreadable.
- */
-declare function readRunnerStatus(installRoot: string, serverId: string): Promise<RunnerStatusResult>;
-/**
- * List runners across attached servers. With no `serverId` filter,
- * returns one block per attached server (zero if no attachments). With
- * a `serverId` filter, returns exactly that server's block or throws
- * `StateReaderError("NOT_ATTACHED")`.
- *
- * Per-server discriminator preserves `unauthorized` / `error` outcomes
- * so consumers can pattern-match without losing context.
- */
-declare function listRunners(installRoot: string, opts?: {
-    serverId?: string;
-}): Promise<ListRunnersResult>;
-
-type UpgradeTrigger = "cli" | "web" | "tray";
-/**
- * v8.3.3 §4.4 (6) closed-set, verbatim 7 values. Adding / renaming /
- * deleting any value requires an RFC bump (locked discipline). This
- * constant array is the runtime source of truth for `assertUpgradeLogEntry`
- * membership check; the type alias below mirrors it.
- */
-declare const UPGRADE_ERROR_CODES: readonly ["UPGRADE_DEPS_CHANGED", "UPGRADE_NETWORK_FAILED", "UPGRADE_INTEGRITY_FAILED", "UPGRADE_SWAP_FAILED", "UPGRADE_RESTART_FAILED", "UPGRADE_NO_TARGET", "UPGRADE_ALREADY_RUNNING"];
-type UpgradeErrorCode = (typeof UPGRADE_ERROR_CODES)[number];
-interface UpgradeBundle {
-    computerVersion: string;
-    /**
-     * Forensic-only per v8.3.2 cleanup. May be omitted; consumers MUST
-     * NOT treat presence/absence as a user-facing contract. The bundled
-     * daemon version plumbing (read from Computer package
-     * `dependencies["@slock-ai/daemon"]`) lands as a follow-up; until
-     * then writers emit just `computerVersion` and downstream readers
-     * default to "unknown" when the field is absent.
-     */
-    bundledDaemonVersion?: string;
-}
-/**
- * v8.3.3 audit-log entry shape, discriminated on `outcome`. Splitting
- * the union means:
- *   - `outcome: "ok"` forbids `errorCode` at the type level
- *     (`errorCode?: never`)
- *   - `outcome: "err"` requires `errorCode: UpgradeErrorCode` (closed-set
- *     7-value membership enforced by TS)
- *
- * Together with the runtime `assertUpgradeLogEntry` guard below, this
- * eliminates the prior "caller-discipline only" silent contract drift
- * (Hao caveat msg=308d99db — `errorCode?: string` allowed any string +
- * silent omission on `err` paths).
- */
-type UpgradeLogEntry = UpgradeLogEntryOk | UpgradeLogEntryErr;
-interface UpgradeLogEntryOk {
-    /** ISO timestamp via formatUpgradeLogTimestamp(); caller may omit to auto-fill. */
-    at?: string;
-    fromBundle: UpgradeBundle;
-    toBundle: UpgradeBundle;
-    channel: string;
-    trigger: UpgradeTrigger;
-    outcome: "ok";
-    /** Forbidden on ok entries — discriminated-union enforcement. */
-    errorCode?: never;
-}
-interface UpgradeLogEntryErr {
-    at?: string;
-    fromBundle: UpgradeBundle;
-    toBundle: UpgradeBundle;
-    channel: string;
-    trigger: UpgradeTrigger;
-    outcome: "err";
-    /** Required iff outcome === "err"; one of the v8.3.3 closed 7-value set. */
-    errorCode: UpgradeErrorCode;
-}
-/**
- * Runtime assertion: `entry` is a valid `UpgradeLogEntry`. Throws
- * `TypeError` with an actionable message on contract violation. Defense
- * in depth against JS-interop callers, JSON-deserialized payloads, and
- * future type-system escapes.
- *
- * Validations:
- *   - `outcome === "ok"` AND `errorCode` is set → reject
- *   - `outcome === "err"` AND `errorCode` is missing → reject
- *   - `outcome === "err"` AND `errorCode` not in 7-value closed set → reject
- *   - Both bundle objects must have a non-empty `computerVersion` string
- */
-declare function assertUpgradeLogEntry(entry: UpgradeLogEntry): void;
-
-export { type ComputerStatusReport, type ConnectService, type ConnectServiceOptions, type DaemonState, IPC_ERROR_CODES, type IpcErrorCode, type LegacyMachineCandidate, type LegacyMachineRosterClient, type LegacyMachineRosterEntry, type LegacyMachineRosterResult, LegacyMachinesClient, type ListRunnersResult, MIGRATION_DETECTION_KINDS, MIGRATION_FRESH_TRIGGERS, type ManualPathValidation, type MigrationDetection, type MigrationDetectionKind, type MigrationFreshTrigger, type PickerSelection, RUNNER_STATE_VALUES, type RequestMethodMap, type RequestOptions, type ResetRunnerResult, type ResetServiceResult, type RunnerListItem as RunnerInfo, type RunnerListPerServer, type RunnerState, type RunnerStatusResult, SERVICE_STATE_VALUES, STATE_READER_ERROR_CODES, type ServerHealth, type ServerStatusRow, ServersClient, type ServiceClient, ServiceClientError, type ServiceEvent, type ServiceState, type ServiceStatusResult, StateReaderError, type StateReaderErrorCode, UPGRADE_ERROR_CODES, type UpgradeBundle, type UpgradeErrorCode, type UpgradeLogEntry, type UpgradeLogEntryErr, type UpgradeLogEntryOk, type UpgradeStartResult, type UpgradeTrigger, type UserServerEntry, type UserServersResult, assertUpgradeLogEntry, detectLegacyMigration, isIpcErrorCode, isMigrationDetectionKind, isRunnerState, isServiceState, listRunners, pickMigrationCandidateFromInput, readRunnerStatus, readServiceStatus, validateManualMigratePath };