@botiverse/raft-computer 0.0.60 → 0.0.62

package/dist/lib/index.d.ts

@@ -1,3 +1,10 @@
+declare class ComputerError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    constructor(code: string, message: string, exitCode?: number);
+}
+declare function isComputerError(err: unknown): err is ComputerError;
+
 type DaemonState = {
     running: true;
     pid: number;
@@ -486,6 +493,314 @@ type MigrationDetection = {
     kind: "server-unavailable";
 };
 
+type ComputerApiEvent = {
+    kind: "login.device-code";
+    verifyUrl: string;
+    userCode: string;
+    expiresAt: string;
+    expiresInSeconds: number;
+} | {
+    kind: "login.polling";
+} | {
+    kind: "login.approved";
+    userId: string;
+    sessionPath: string;
+} | {
+    kind: "attach.attaching";
+    serverSlug: string;
+} | {
+    kind: "attach.preflight";
+    resumed: boolean;
+} | {
+    kind: "attach.attached";
+    serverId: string;
+    serverMachineId: string;
+    serverSlug: string;
+    attachmentPath: string;
+    resumed: boolean;
+    apiKeyRedactedPrefix: string;
+} | {
+    kind: "detach.detaching";
+    serverId: string;
+    serverLabel: string;
+} | {
+    kind: "detach.revoke_succeeded";
+    serverId: string;
+    serverLabel: string;
+} | {
+    kind: "detach.revoke_failed";
+    serverId: string;
+    serverLabel: string;
+    reason: "http_error" | "network_error";
+    httpStatus?: number;
+    message: string;
+} | {
+    kind: "detach.subtree_cleared";
+    serverId: string;
+    serverLabel: string;
+} | {
+    kind: "detach.detached";
+    serverId: string;
+    serverLabel: string;
+} | {
+    kind: "start.starting";
+    managedTargets: string[];
+    attachedCount: number;
+    foreground: boolean;
+} | {
+    kind: "start.already_running";
+    servicePid: number;
+    managedTargets: string[];
+    attachedCount: number;
+} | {
+    kind: "start.running";
+    managedTargets: string[];
+    attachedCount: number;
+} | {
+    kind: "start.spawned";
+    servicePid: number;
+    managedTargets: string[];
+    attachedCount: number;
+} | {
+    kind: "start.ready";
+    ready: Map<string, number>;
+    managedTargets: string[];
+} | {
+    kind: "start.aborted";
+    servicePid: number;
+    managedTargets: string[];
+    ready: Map<string, number>;
+} | {
+    kind: "stop.stopping";
+    pid: number | null;
+} | {
+    kind: "stop.not_running";
+} | {
+    kind: "stop.stale_pidfile_cleared";
+    pid: number;
+} | {
+    kind: "stop.signaled";
+    pid: number;
+} | {
+    kind: "stop.stopped";
+    pid: number;
+} | {
+    kind: "log.line";
+    line: string;
+};
+
+interface LoginInput {
+    serverUrl?: string;
+}
+interface LoginResult {
+    userId: string;
+    sessionPath: string;
+    serverUrl: string;
+}
+
+interface AttachInput {
+    serverSlug: string;
+    serverUrl?: string;
+    name?: string;
+}
+interface AttachResult {
+    serverId: string;
+    serverMachineId: string;
+    serverSlug: string;
+    serverUrl: string;
+    attachmentPath: string;
+    resumed: boolean;
+    /** First 8 characters of the freshly-issued sk_computer_*; mirrors
+     *  adoption.log redacted_prefix convention. The raw key lives only in
+     *  runner.state.json (mode 0o600) — NEVER on this event/result. */
+    apiKeyRedactedPrefix: string;
+}
+
+/** Generic pidfile reader by absolute path. Returns null on missing / junk. */
+declare function readPidfileAt(pidfilePath: string): Promise<number | null>;
+/** Liveness via signal 0. */
+declare function isProcessAlive(pid: number): boolean;
+
+/**
+ * Spawn a detached `slock-computer __service` child. The detached child
+ * survives the parent process exit, writes its stdio to the service
+ * log, and registers its pid in `service.pid`. Returns the pid.
+ *
+ * Used by `runStart` (foreground CLI → background service) AND by the
+ * §2.5 upgrade flow's restart phase: after `swap` renames the new bits
+ * into `currentBinaryDir`, this helper re-execs the freshly-installed
+ * binary as the new service. After a §2.3 rollback (`.prev` restored)
+ * it re-execs the old bits the same way — same code path, same log sink,
+ * same pidfile invariant. Dayu blocker (msg=911eb84e): without this
+ * shared helper, `runUpgradeCli` had no spawn callback wired into
+ * `runUpgrade`, so the production CLI's restart phase never spawned a
+ * fresh service — it would time out on health and then fail rollback
+ * respawn for the same reason.
+ *
+ * Both current callsites (`runStart`, `runUpgradeCli`) invoke this while
+ * holding `withMutationLock`, so the spawn always sets
+ * `PARENT_LOCK_HELD_ENV_VAR=1` to suppress the child service's
+ * unconditional `forceReleaseLock` startup step. See env-var docstring
+ * above.
+ *
+ * NOT for use inside `__service` itself (the service is already the
+ * detached process). NOT for use inside `restartPhase` defaults: the
+ * orchestrator's `deps.spawnFreshService` callback is the integration
+ * point so unit tests can stub it without spawning real children.
+ *
+ * Throws if the OS refuses the spawn (no pid available).
+ */
+declare function spawnDetachedService(slockHome: string): Promise<number>;
+interface ResidentCore {
+    start: () => void | Promise<void>;
+    stop: () => void | Promise<void>;
+}
+type ResidentCoreFactory = (creds: {
+    serverId: string;
+    serverMachineId: string;
+    apiKey: string;
+    serverUrl: string;
+}) => ResidentCore | Promise<ResidentCore>;
+type RunStartDeps = {
+    coreFactory?: ResidentCoreFactory;
+    spawnDetachedService?: typeof spawnDetachedService;
+    readPidfile?: typeof readPidfileAt;
+    isProcessAlive?: typeof isProcessAlive;
+    sleep?: (ms: number) => Promise<void>;
+    ensureTimeoutMs?: number;
+    ensurePollIntervalMs?: number;
+};
+declare function runService(): Promise<void>;
+/**
+ * `slock-computer start [serverId]` CLI adapter. Thin wrapper over the
+ * StartService (`./services/start.ts`); see service file header for the
+ * locked shape (RFC v0.8 contract v4 §6 line 80 — typed events +
+ * AbortSignal pre/post-spawn boundary + closed-set § codes byte-identical).
+ *
+ * This adapter's responsibilities:
+ *   1. Map start.* events → info() lines byte-identical to the
+ *      pre-extraction implementation.
+ *   2. Map ComputerServiceError → fail(code, message), preserving
+ *      CliExit semantics for the test harness.
+ *   3. Render `formatReadySummary` (kept in adapter on purpose:
+ *      user-visible text formatter, not service axis).
+ *
+ * The pre-extraction `RunStartDeps` shape is preserved so existing
+ * service.test.ts test cases keep working — we forward the deps
+ * straight into the service.
+ */
+declare function runStart(opts?: {
+    foreground?: boolean;
+    serverId?: string | null;
+    serverLabel?: string | null;
+}, deps?: RunStartDeps): Promise<void>;
+
+type StartStatus = "running" | "already_running" | "spawned" | "aborted";
+interface StartResult {
+    status: StartStatus;
+    /** Managed set for this start invocation (single id when serverId
+     *  was set; full attached set otherwise). */
+    managedTargets: string[];
+    /** Total number of attached servers at the moment of start (includes
+     *  managedTargets when start was global). */
+    attachedCount: number;
+    /** Map of serverId → daemon pid for daemons confirmed ready before
+     *  return. Empty when status === "running" (foreground); on
+     *  status === "aborted" reflects whatever was ready at the moment
+     *  the abort was observed. */
+    ready: Map<string, number>;
+    /** Pid of the (newly spawned OR existing) service when known.
+     *  null for status === "running" (the calling process IS the
+     *  service in foreground mode). */
+    servicePid: number | null;
+    /** Path of the service's combined log (for adapter "Logs: …" line). */
+    serviceLogPath: string;
+}
+interface StartDeps {
+    /** Test seams (default to module-level real impls). Mirrors the
+     *  pre-extraction `RunStartDeps` shape so existing service.test.ts
+     *  test cases keep working through the adapter. */
+    spawnDetachedService?: typeof spawnDetachedService;
+    readPidfile?: typeof readPidfileAt;
+    isProcessAlive?: typeof isProcessAlive;
+    sleep?: (ms: number) => Promise<void>;
+    ensureTimeoutMs?: number;
+    ensurePollIntervalMs?: number;
+    /** Foreground service loop. Default: real `runService`. */
+    runService?: typeof runService;
+}
+
+type StopStatus = "not_running" | "stale_pidfile_cleared" | "stopped";
+interface StopResult {
+    status: StopStatus;
+    /** Pid the service observed in the pidfile when status !== "not_running".
+     *  null on the not_running path (no pid was read). */
+    pid: number | null;
+    /** Path of the service pidfile (so adapters can render hints
+     *  without re-resolving paths). */
+    pidfilePath: string;
+}
+interface StopDeps {
+    /** Test seams — pre-extraction `RunStopDeps` shape preserved so
+     *  existing service.test.ts cases keep byte-identical imports
+     *  through the adapter. */
+    readPidfile?: typeof readPidfileAt;
+    isProcessAlive?: typeof isProcessAlive;
+    killService?: (pid: number) => void;
+    sleep?: (ms: number) => Promise<void>;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+}
+
+type DetachStatus = "detached";
+type RevokeOutcome = "success" | "http_error" | "network_error";
+interface DetachResult {
+    status: DetachStatus;
+    serverId: string;
+    serverLabel: string;
+    revokeOutcome: RevokeOutcome;
+    /** HTTP status code on http_error path; undefined otherwise. */
+    revokeHttpStatus?: number;
+}
+
+interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+
+interface CleanupReport {
+    stalePidfiles: string[];
+    orphanProcesses: number[];
+    powerLossRecovered: string[];
+    tmpFilesCleared: string[];
+    staleLocks: string[];
+    /** Was any cleanup actually performed? false = clean baseline. */
+    anyAction: boolean;
+}
+
+interface CrashEntry {
+    at: string;
+    exitCode: number | null;
+    signal: string | null;
+}
+/**
+ * Read the recent crash history (within the crash-window). Returns []
+ * if file missing/corrupt.
+ */
+declare function readCrashHistory(slockHome: string, serverId: string, nowMs?: number): Promise<CrashEntry[]>;
+
+type Channel = "latest" | "alpha" | `pinned:${string}`;
+
+declare function runAttach(opts: {
+    serverSlug: string;
+    serverUrl?: string;
+    name?: string;
+    start?: boolean;
+    foreground?: boolean;
+    orchestrated?: boolean;
+}): Promise<void>;
+
 /**
  * Roster fetcher contract — `LegacyMachinesClient.list(serverSlug)`
  * satisfies this structurally. Defining it as an interface here lets
@@ -542,6 +857,117 @@ type ManualPathValidation = {
 };
 declare function validateManualMigratePath(inputPath: string, roster: LegacyMachineRosterEntry[]): Promise<ManualPathValidation>;
 
+declare function runLogin(opts: {
+    serverUrl?: string;
+    orchestrated?: boolean;
+}): Promise<void>;
+
+/** Credential bridge mode — §5.11.4 closed enum, snake_case byte-exact. */
+type CredentialBridgeMode = "legacy_key_argv" | "legacy_key_file" | "legacy_key_stdin" | "legacy_key_env" | "legacy_fingerprint_roster";
+interface AdoptLegacyByFingerprintInput {
+    serverSlug: string;
+    serverUrl?: string;
+    name?: string;
+    /** Server roster identity selected after user login. */
+    legacyMachineId: string;
+    /** sha256(legacy api key).slice(0,16), intersected with local owner.json. */
+    apiKeyFingerprint: string;
+    /** Absolute local owner.json path from detection/validation. */
+    legacyOwnerPath: string;
+}
+interface LegacyStopResult {
+    attempted: boolean;
+    pid?: number;
+    outcome: "absent" | "already_dead" | "stopped" | "timed_out" | "denied" | "error";
+    reason?: string;
+}
+interface AdoptLegacyResult {
+    serverId: string;
+    serverMachineId: string;
+    /** Legacy machine row id — emitted by the server on success so the
+     *  attachment.json can carry `adoptedFromLegacy: true` / `legacyMachineId`. */
+    legacyMachineId: string;
+    serverSlug: string;
+    serverUrl: string;
+    attachmentPath: string;
+    resumed: boolean;
+    /** First 8 characters of the FRESHLY-ISSUED sk_computer_*; mirrors
+     *  attachment.json/adoption.log convention. The raw fresh key lives ONLY
+     *  in attachment.json (mode 0o600) — NEVER on this event/result. */
+    apiKeyRedactedPrefix: string;
+    legacyStop: LegacyStopResult;
+}
+type AdoptLegacyEvent = {
+    type: "adopting";
+    serverSlug: string;
+    mode: CredentialBridgeMode;
+} | {
+    type: "preflight";
+    resumed: boolean;
+} | {
+    type: "adopted";
+    serverId: string;
+    serverMachineId: string;
+    legacyMachineId: string;
+    serverSlug: string;
+    attachmentPath: string;
+    resumed: boolean;
+    apiKeyRedactedPrefix: string;
+    legacyStop: LegacyStopResult;
+};
+interface AdoptLegacyOptions {
+    signal?: AbortSignal;
+    onEvent?: (event: AdoptLegacyEvent) => void;
+}
+declare function adoptLegacyByFingerprint(input: AdoptLegacyByFingerprintInput, options?: AdoptLegacyOptions): Promise<AdoptLegacyResult>;
+
+interface SetupOptions {
+    serverSlug: string;
+    serverUrl?: string;
+    name?: string;
+    start?: boolean;
+    foreground?: boolean;
+    yes?: boolean;
+    /**
+     * RFC v9.9 §X.4 manual escape hatch. When set, bypasses the picker
+     * and runs the three-gate validator
+     * (`MIGRATE_FROM_NOT_FOUND` / `MIGRATE_FROM_INVALID` /
+     * `MIGRATE_FROM_NOT_OWNED`) against the supplied path. Hard-fails on
+     * any failure — the operator chose this path explicitly.
+     */
+    migrateFrom?: string;
+}
+interface SetupDeps {
+    isTty?: boolean;
+    runLogin?: typeof runLogin;
+    runAttach?: typeof runAttach;
+    runStart?: typeof runStart;
+    refreshUserSession?: typeof refreshUserSession;
+    detectLegacyMigration?: typeof detectLegacyMigration;
+    validateManualMigratePath?: typeof validateManualMigratePath;
+    /**
+     * Roster client factory — defaults to `new LegacyMachinesClient(...)`.
+     * Tests stub this to feed a fake roster without booting undici.
+     */
+    buildRosterClient?: (baseUrl: string, accessToken: string) => {
+        list: LegacyMachinesClient["list"];
+    };
+    /**
+     * Picker prompt — returns the operator's selection. Defaults to a
+     * stdin reader. Each return value drives a distinct branch:
+     *   - `{ kind: "candidate"; index: number }` — adopt picker entry 1..N
+     *   - `{ kind: "fresh" }` — `0` / `<Enter>` / EOF / unrecognized
+     *   - `{ kind: "manual"; path: string }` — `m`, then path on next line
+     */
+    pickMigrationCandidate?: (candidates: LegacyMachineCandidate[]) => Promise<PickerSelection>;
+    /**
+     * Roster-fingerprint adoption service injection — defaults to
+     * `adoptLegacyByFingerprintService`. Tests stub this to verify picker
+     * wiring without hitting the network. Normal setup never reads a raw
+     * legacy key; the selected candidate's roster identity is the authority.
+     */
+    adoptLegacyByFingerprint?: typeof adoptLegacyByFingerprint;
+}
 type PickerSelection = {
     kind: "candidate";
     index: number;
@@ -561,6 +987,7 @@ type PickerSelection = {
  */
 declare const MIGRATION_FRESH_TRIGGERS: readonly ["empty-intersection", "explicit-zero", "eof", "non-tty", "server-unavailable"];
 type MigrationFreshTrigger = (typeof MIGRATION_FRESH_TRIGGERS)[number];
+declare function refreshUserSession(slockHome: string, serverUrl?: string): Promise<boolean>;
 /**
  * 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
@@ -580,31 +1007,132 @@ declare function pickMigrationCandidateFromInput(candidates: LegacyMachineCandid
     eof: boolean;
 }>, write: (s: string) => void): Promise<PickerSelection>;
 
+/** Public CDN root for published Computer SEA binaries (prod default). */
+declare const DEFAULT_UPGRADE_BASE_URL = "https://cdn.slock.ai/computer";
+interface SeaStageResult {
+    /** Absolute path to the downloaded + sha256-verified staged binary. */
+    readonly stagedBinaryPath: string;
+    readonly version: string;
+    /** Verified sha256 (hex) of the staged binary — matches the manifest. */
+    readonly sha256: string;
+}
+interface SeaStageDeps {
+    readonly fetchFn?: typeof fetch;
+    readonly baseUrl?: string;
+    /** The `computer:upgrade` requestId, echoed onto emitted download-progress frames. */
+    readonly requestId?: string;
+    /** Optional sink for throttled byte-% progress during the `downloading` phase. */
+    readonly onProgress?: (e: SeaUpgradeProgressEvent) => void;
+}
 /**
- * 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.
+ * SEA Phase 1 — download the target-version binary for this platform into
+ * `stagingDir` and verify its sha256 against the published manifest. Throws on
+ * any failure (no manifest, no target for this platform, download error, sha
+ * mismatch) so the caller aborts BEFORE the swap — nothing on disk is touched
+ * outside `stagingDir`.
  */
-declare function readServiceStatus(installRoot: string): Promise<ServiceStatusResult>;
+declare function stageSeaPhase(stagingDir: string, version: string, platform: NodeJS.Platform, arch: string, deps?: SeaStageDeps): Promise<SeaStageResult>;
+interface SeaSwapResult {
+    /** Where the old binary was moved to (rollback restores from here). */
+    readonly prevBinaryPath: string;
+    /** The live executable path (unchanged identity; new bytes). */
+    readonly currentBinaryPath: string;
+}
 /**
- * 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.
+ * SEA Phase 4 — atomic single-file swap. Moves the current executable to
+ * `<exe>.prev` (kept until the new service passes health-check), then renames
+ * the staged binary into the executable's path. A stale `.prev` from a prior
+ * failed upgrade is cleared first. On failure mid-swap the caller rolls back
+ * via {@link rollbackSeaSwap}.
  */
-declare function readRunnerStatus(installRoot: string, serverId: string): Promise<RunnerStatusResult>;
+declare function swapSeaPhase(currentBinaryPath: string, stagedBinaryPath: string): Promise<SeaSwapResult>;
+interface ManualRollbackResult {
+    /** The `<exe>.prev` that was restored over the live executable. */
+    readonly restoredFrom: string;
+    /** The live executable path (unchanged identity; restored bytes). */
+    readonly currentBinaryPath: string;
+}
 /**
- * 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")`.
+ * Operator-initiated `upgrade --rollback`: restore the `<exe>.prev` backup the
+ * last successful swap left behind, putting the previous binary back at the
+ * live executable path. Reuses {@link rollbackSeaSwap} (the same primitive the
+ * supervisor's bad-binary watchdog uses) once the `.prev` is confirmed present.
  *
- * Per-server discriminator preserves `unauthorized` / `error` outcomes
- * so consumers can pattern-match without losing context.
+ * Throws `Error("UPGRADE_NO_ROLLBACK")` if no `.prev` exists (nothing to roll
+ * back to) so the CLI can map it to the closed-set token. The supervisor
+ * restarts the service on the restored binary (same as a normal swap).
  */
-declare function listRunners(installRoot: string, opts?: {
-    serverId?: string;
-}): Promise<ListRunnersResult>;
+declare function rollbackToPrev(currentBinaryPath: string): Promise<ManualRollbackResult>;
+type SeaUpgradePhase = "downloading" | "verifying" | "applying" | "restarting";
+interface SeaUpgradeProgressEvent {
+    readonly requestId: string;
+    readonly phase: SeaUpgradePhase;
+    readonly message?: string;
+    /** 0-100 byte-progress, present ONLY on `downloading`-phase progress frames. */
+    readonly percent?: number;
+}
+interface RunSeaUpgradeOpts {
+    readonly slockHome: string;
+    readonly requestId: string;
+    readonly fromVersion: string;
+    readonly targetVersion: string;
+    /** The live executable to swap — normally process.execPath. */
+    readonly currentBinaryPath: string;
+    /** ISO timestamp for the marker (injected for deterministic tests). */
+    readonly nowIso: string;
+    readonly platform?: NodeJS.Platform;
+    readonly arch?: string;
+    readonly deps?: {
+        readonly baseUrl?: string;
+        readonly fetchFn?: typeof fetch;
+        readonly onProgress?: (e: SeaUpgradeProgressEvent) => void;
+        readonly stageFn?: typeof stageSeaPhase;
+        readonly swapFn?: typeof swapSeaPhase;
+        readonly stagingDir?: string;
+    };
+}
+interface RunSeaUpgradeResult {
+    readonly ok: boolean;
+    /** Which phase failed (absent on success). */
+    readonly failedPhase?: "stage" | "swap";
+    readonly reason?: string;
+    /** Present on success — the swap, so the caller / watchdog can roll back via `.prev`. */
+    readonly swap?: SeaSwapResult;
+}
+declare function runSeaUpgrade(opts: RunSeaUpgradeOpts): Promise<RunSeaUpgradeResult>;
+/** Resolve the CDN's always-latest version from the top-level manifest
+ *  (`<base>/manifest.json` → `{ version }`). This is the SAME pointer
+ *  `install.sh` consumes, so `install` and `upgrade` share one source of
+ *  "latest" — no npm registry round-trip (npm dist-tags went stale at the SEA
+ *  cutover; the binary store is the CDN). Returns null on any failure (caller
+ *  maps to a resolve error). */
+declare function fetchCdnLatestVersion(baseUrl: string, fetchFn?: typeof fetch): Promise<string | null>;
+interface ResolveAndRunSeaUpgradeOpts {
+    readonly slockHome: string;
+    readonly requestId: string;
+    readonly fromVersion: string;
+    readonly currentBinaryPath: string;
+    readonly nowIso: string;
+    readonly platform?: NodeJS.Platform;
+    readonly arch?: string;
+    readonly deps?: RunSeaUpgradeOpts["deps"] & {
+        /** Override channel resolution (default: readChannel(slockHome)). */
+        readonly readChannelFn?: (slockHome: string) => Promise<Channel>;
+        /** Override the CDN latest-version fetch (default: read `<base>/manifest.json`). */
+        readonly fetchLatestVersion?: (baseUrl: string) => Promise<string | null>;
+        /** Override the full target-version resolver (bypasses channel resolution). */
+        readonly resolveTargetVersion?: () => Promise<string | null>;
+        readonly runSeaUpgradeFn?: typeof runSeaUpgrade;
+    };
+}
+interface ResolveAndRunSeaUpgradeResult extends Omit<RunSeaUpgradeResult, "failedPhase"> {
+    readonly targetVersion?: string;
+    /** True when already at the resolved target (no-op, no swap, no restart). */
+    readonly alreadyCurrent?: boolean;
+    /** Extends RunSeaUpgradeResult's failedPhase with the resolution step. */
+    readonly failedPhase?: "resolve" | "stage" | "swap";
+}
+declare function resolveAndRunSeaUpgrade(opts: ResolveAndRunSeaUpgradeOpts): Promise<ResolveAndRunSeaUpgradeResult>;
 
 type UpgradeTrigger = "cli" | "web" | "tray";
 /**
@@ -681,4 +1209,304 @@ interface UpgradeLogEntryErr {
  */
 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 };
+interface UpgradeCliOptions {
+    dryRun?: boolean;
+    channel?: string;
+    /**
+     * Explicit target version (bypasses channel resolution). Surfaced on
+     * the CLI as `--target-version`, NOT `--version` — Commander treats
+     * `--version` as the root program version flag and silently shadows
+     * any subcommand option of the same name.
+     */
+    targetVersion?: string;
+    /**
+     * Restore the `<exe>.prev` backup the last successful swap left behind,
+     * putting the previous binary back at the live executable path. Mutually
+     * exclusive with --target-version / --channel / --dry-run (it resolves /
+     * downloads nothing). Fails with `UPGRADE_NO_ROLLBACK` when no `.prev`
+     * exists. SEA-only (same gate as a normal upgrade).
+     */
+    rollback?: boolean;
+    /**
+     * §4.4 (4) trigger source attribution for upgrade.log audit trail.
+     * Defaults to "cli" when invoked through the bare CLI entry point.
+     */
+    trigger?: UpgradeTrigger;
+}
+/**
+ * Pure upgrade core (CLI-over-lib convergence). Validates inputs, resolves
+ * channel + target version, and dispatches to the SEA in-process upgrade. It
+ * NEVER writes to stdout directly: human lines go through the `emit` sink the
+ * presenter supplies, and the UPGRADE / CHANNEL_INVALID / UPGRADE_SEA_ONLY fail
+ * points throw `ComputerError` (the presenter maps them to the
+ * `{ok:false,code,message}` fail-shape). The dry-run / channel / target-version
+ * / rollback flag handling + the SEA-only gate are byte-identical to the
+ * pre-convergence `runUpgradeCli` body. (The IPC-routing + the
+ * UPGRADE_ALREADY_RUNNING mutation-lock remap stay in the index.ts presenter.)
+ */
+declare function upgradeCliCore(slockHome: string, opts: UpgradeCliOptions, onEvent: (event: ComputerApiEvent) => void, deps?: {
+    /** Override the CDN latest-version fetch (default: read `<base>/manifest.json`). */
+    fetchLatestVersion?: (baseUrl: string) => Promise<string | null>;
+    /** Override the CDN base-url resolver (default: `resolveUpgradeBaseUrl()`). */
+    resolveUpgradeBaseUrlFn?: () => string;
+    currentVersion?: () => Promise<string>;
+    /** The live executable to swap (default: `process.execPath`). */
+    currentBinaryPath?: () => string;
+    /** Override the SEA upgrade runner (tests stub this). */
+    resolveAndRunSeaUpgradeFn?: typeof resolveAndRunSeaUpgrade;
+    /** Override the SEA stage primitive (dry-run download+verify). */
+    stageSeaPhaseFn?: typeof stageSeaPhase;
+    /** Override the rollback primitive (restore `<exe>.prev`). Tests stub this. */
+    rollbackToPrevFn?: typeof rollbackToPrev;
+    /**
+     * Test seam for the SEA-only gate. Production uses `isSeaBinary()`.
+     * Tests stub it true so the SEA flow is exercised without packaging a
+     * real single-binary, or false to exercise the migration refusal.
+     */
+    isSeaBinary?: () => boolean;
+}): Promise<void>;
+
+/**
+ * Pure result of `doctor` (`slock-computer doctor [serverSlug] [--fix]`). The
+ * presenter formats it (with `redactSecrets` on every emitted line) and sets
+ * the process exit code from `allOk`.
+ */
+interface DoctorReport {
+    checks: DoctorCheck[];
+    allOk: boolean;
+    cleanup: CleanupReport | null;
+    crashes: Awaited<ReturnType<typeof readCrashHistory>>;
+    serverId?: string;
+    serverLabel?: string;
+}
+interface RunnersListResult {
+    serverSlug: string | null;
+    serverId: string;
+    runners: RunnerListItem[];
+}
+interface RunnersStopResult {
+    serverSlug: string | null;
+    serverId: string;
+    agentId: string;
+}
+interface LogoutResult {
+    status: "logged-out" | "already-logged-out";
+    sessionPath: string;
+}
+/**
+ * The typed Computer library API. Each method is PURE (result | throw
+ * `ComputerError`). `createComputerApi(slockHome)` binds an install root so the
+ * methods take no ambient env reads of their own.
+ */
+interface ComputerApi {
+    /**
+     * Build the Computer-level aggregate status report. Read-only and
+     * secret-free (status.ts §3.3.1 redline).
+     */
+    getStatus(): Promise<ComputerStatusReport>;
+    /**
+     * Clear the service-level crash history and transition service state
+     * `degraded → running` (§1.3). Routes through the running service via IPC
+     * when one is up (single-writer), else applies the disk-only handler.
+     */
+    resetService(): Promise<ResetServiceResult>;
+    /**
+     * Clear a per-runner crash history and transition runner state
+     * `degraded → running` (§2.4). Same single-writer routing as `resetService`.
+     * Returns `{status:"not-found"}` (a RESULT, not a throw) when `serverId` is
+     * not an attached server.
+     */
+    resetRunner(serverId: string): Promise<ResetRunnerResult>;
+    /**
+     * Device-code login (one user identity per Computer / SLOCK_HOME). Drives
+     * the device-code flow; the presenter-supplied `onEvent` sink prints the
+     * verification URL/code + waiting lines. The api itself never prints.
+     */
+    login(opts: {
+        serverUrl?: string;
+    }, onEvent?: (event: ComputerApiEvent) => void): Promise<LoginResult>;
+    /** Clear the saved user session (idempotent). Pure: returns a result. */
+    logout(): Promise<LogoutResult>;
+    /**
+     * Attach this Computer to one server (add-not-replace). `onEvent` prints
+     * the attach progress lines presenter-side.
+     */
+    attach(opts: {
+        serverSlug: string;
+        serverUrl?: string;
+        name?: string;
+    }, onEvent?: (event: ComputerApiEvent) => void): Promise<AttachResult>;
+    /** Remove ONE server's local attachment (per-server isolated). */
+    detach(serverId: string, serverLabel: string, onEvent?: (event: ComputerApiEvent) => void): Promise<DetachResult>;
+    /** Start/ensure the Computer service. `onEvent` formats the start lines. */
+    start(opts: {
+        foreground?: boolean;
+        serverId?: string | null;
+        serverLabel?: string | null;
+    }, onEvent?: (event: ComputerApiEvent) => void, deps?: StartDeps): Promise<StartResult>;
+    /** Stop the Computer service (idempotent). `onEvent` formats the stop lines. */
+    stop(onEvent?: (event: ComputerApiEvent) => void, deps?: StopDeps): Promise<StopResult>;
+    /**
+     * Diagnose login + per-server attachments + preflight + service. Returns the
+     * report (runs the cleanup pass when `cleanup` is true). Pure — the presenter
+     * formats (with `redactSecrets`) and sets the exit code from `allOk`.
+     */
+    doctor(opts: {
+        cleanup?: boolean;
+        serverId?: string;
+        serverLabel?: string;
+    }): Promise<DoctorReport>;
+    /**
+     * Tail one server's runner log (or the service log). Returns the trailing
+     * (already secret-redacted) lines; the presenter prints them. Throws
+     * `NO_DAEMON_LOG` when the target log is absent.
+     */
+    logs(opts: {
+        lines?: number;
+        serverId?: string;
+        service?: boolean;
+    }): Promise<string[]>;
+    /** List runners on one attached server. Throws RUNNERS_* on failure. */
+    runnersList(serverId: string): Promise<RunnersListResult>;
+    /** Stop a runner on one attached server. Throws the RUNNER/RUNNERS errors on failure. */
+    runnersStop(agentId: string, attachment: {
+        serverUrl: string;
+        apiKey: string;
+        serverSlug: string | null;
+        serverId: string;
+    }): Promise<RunnersStopResult>;
+    /** Read the current release channel (default `latest` when unset). */
+    channelShow(): Promise<Channel>;
+    /** Validate + persist the release channel. Throws `CHANNEL_INVALID`. */
+    channelSet(raw: string): Promise<Channel>;
+    /**
+     * Orchestrate `setup <serverSlug>`: login → (detect + picker / --migrate-from)
+     * → attach → start. INTERACTIVE: `onEvent` is the event sink (the presenter
+     * unwraps `log.line` events to `info`); the interactive picker is the
+     * dep-injected `pickMigrationCandidate` prompt callback. The api drives the
+     * flow and throws `ComputerError` for its closed-set fail points; it never
+     * prints.
+     */
+    setup(opts: SetupOptions, deps: SetupDeps, onEvent: (event: ComputerApiEvent) => void): Promise<void>;
+    /**
+     * SEA self-upgrade (or `--rollback`). Validates inputs, resolves channel +
+     * target version, runs the SEA download+verify+swap (or the dry-run / rollback
+     * primitive). INTERACTIVE-ish: `onEvent` is the event sink (the presenter
+     * unwraps `log.line` events to `info`); the SEA-only gate +
+     * dry-run/channel/target-version/rollback flag handling live here, throwing
+     * `ComputerError` for the UPGRADE_* closed set. This is the STANDALONE swap
+     * primitive (cold-boot path); the live-service IPC route is
+     * `tryUpgradeViaService`. The in-process mutation-lock + the
+     * UPGRADE_ALREADY_RUNNING remap stay in the index.ts presenter (the lock
+     * owner) — they wrap this standalone call.
+     */
+    upgrade(opts: UpgradeCliOptions, deps: Parameters<typeof upgradeCliCore>[3], onEvent: (event: ComputerApiEvent) => void): Promise<void>;
+    /**
+     * Route a PLAIN FORWARD upgrade through a live service via IPC
+     * (`upgrade-start`): the service drives download/verify/swap + self-restart
+     * in-process (single-writer). Returns `{routed:true}` after kicking it off
+     * (the started / already-running line is emitted via `onEvent` as a
+     * `log.line`); returns `{routed:false}` when NO service is live (cold boot)
+     * so the caller runs the standalone `upgrade()` under its own mutation lock.
+     * The cross-process upgrade race is guarded by the service's own
+     * `inFlightUpgrade` + the `upgrade-start` already-running response — NOT a
+     * caller-side lock. Only for plain forward upgrades; the presenter gates out
+     * dry-run / channel-override / rollback (those are always standalone).
+     */
+    tryUpgradeViaService(targetVersion: string | undefined, onEvent?: (event: ComputerApiEvent) => void): Promise<{
+        routed: boolean;
+    }>;
+}
+/**
+ * Construct a ComputerApi bound to an explicit install root. The single-writer
+ * reset routing (`resetViaServiceOrDisk`) lives here so the api owns the
+ * IPC-vs-disk decision: when a service is running, mutations route through it
+ * via IPC so the supervisor's in-memory runner state stays consistent; when no
+ * service is up (cold boot) the disk-only lib-pure handlers apply directly.
+ */
+declare function createComputerApi(slockHome: string): ComputerApi;
+
+/**
+ * One Computer trace line. INTENTIONALLY shaped as `@slock-ai/shared`'s
+ * canonical `TraceEvent` (`{ name, timeMs, attrs? }`) so the forthcoming shared
+ * trace-client can route these through the real `Tracer` / `TraceSink` with ZERO
+ * format reconciliation. We MIRROR the shape rather than import the type — that
+ * keeps this interim file sink from pulling `@slock-ai/shared` into the Computer
+ * package early; the shared-client work (B) replaces this helper's internals
+ * (file-append → `Tracer.startSpan` + `TraceSink.record`) while the emitted
+ * shape stays identical.
+ *
+ * `attrs` is the open structured bag (== shared `TraceAttributes`): route
+ * decisions carry `{ method, decision }`, the menu-bar action trail carries
+ * `{ kind, durationMs, outcome, errorCode }`, etc.
+ */
+interface ComputerTraceEvent {
+    /** event name, e.g. "route-decision" | "action" */
+    name: string;
+    /** epoch milliseconds (== shared `TraceEvent.timeMs`) */
+    timeMs: number;
+    /** structured attributes (== shared `TraceAttributes`) */
+    attrs?: Record<string, unknown>;
+}
+/**
+ * Best-effort append of one `ComputerTraceEvent` JSON line to the Computer trace
+ * sink (`run/trace.jsonl`). NEVER throws or blocks the traced operation — any fs
+ * error is swallowed.
+ */
+declare function traceEvent(slockHome: string, event: ComputerTraceEvent): Promise<void>;
+/**
+ * Record a single-writer route decision (reset / upgrade routing) as a
+ * `route-decision` `ComputerTraceEvent` — the answer to "did this op take the
+ * EXPECTED route" (`via-service` | `via-disk` | `ipc` | `standalone`).
+ */
+declare function recordRouteDecision(slockHome: string, opts: {
+    method: string;
+    decision: string;
+    timeMs?: number;
+}): Promise<void>;
+
+/**
+ * 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>;
+
+/**
+ * Connect to the Computer service over the §4 IPC transport, perform the
+ * versioned handshake (§4.3), and return a typed `ServiceClient`. Throws
+ * `ServiceClientError` (member of `IPC_ERROR_CODES`) on any handshake or
+ * connect-time failure.
+ */
+declare function connectService(installRoot: string, options?: ConnectServiceOptions): Promise<ServiceClient>;
+
+declare class ComputerServiceError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, cause?: unknown);
+}
+
+declare function userSessionPath(slockHome: string): string;
+
+declare const COMPUTER_VERSION: string;
+
+export { type AttachInput, type AttachResult, COMPUTER_VERSION, type ComputerApi, type ComputerApiEvent, ComputerError, ComputerServiceError, type ComputerStatusReport, type ComputerTraceEvent, type ConnectService, type ConnectServiceOptions, DEFAULT_UPGRADE_BASE_URL, type DaemonState, IPC_ERROR_CODES, type IpcErrorCode, type LegacyMachineCandidate, type LegacyMachineRosterClient, type LegacyMachineRosterEntry, type LegacyMachineRosterResult, LegacyMachinesClient, type ListRunnersResult, type LoginInput, type LoginResult, 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, connectService, createComputerApi, detectLegacyMigration, fetchCdnLatestVersion, isComputerError, isIpcErrorCode, isMigrationDetectionKind, isRunnerState, isServiceState, listRunners, pickMigrationCandidateFromInput, readRunnerStatus, readServiceStatus, recordRouteDecision, traceEvent, userSessionPath, validateManualMigratePath };