@skrr-ai/cli 0.1.89 → 0.1.90

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/machineUuid.js

@@ -3,8 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HOSTED_RUNTIME_MACHINE_SOURCES = void 0;
+exports.MACHINE_IDENTITY_FILENAME = exports.HOSTED_RUNTIME_MACHINE_SOURCES = void 0;
 exports.hostedRuntimeIdOverride = hostedRuntimeIdOverride;
+exports.getHardwareMachineUuid = getHardwareMachineUuid;
+exports.qualifyMachineUuid = qualifyMachineUuid;
+exports.setMachineUuidProfile = setMachineUuidProfile;
+exports.getMachineUuidProfile = getMachineUuidProfile;
 exports.getMachineUuid = getMachineUuid;
 exports.__resetMachineUuidCacheForTest = __resetMachineUuidCacheForTest;
 /**
@@ -34,7 +38,9 @@ exports.__resetMachineUuidCacheForTest = __resetMachineUuidCacheForTest;
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
+const configRoot_js_1 = require("./configRoot.js");
 /**
  * Daemon sources whose identity is ISSUED by the control plane rather than
  * derived from the host: the provisioner mints the daemon id and machine uuid
@@ -106,20 +112,18 @@ function readMachineUuidWindows() {
     }
 }
 /**
- * Return a stable, machine-scoped UUID. Cached for the process lifetime.
+ * The HARDWARE identity of this machine (IOPlatformUUID / machine-id /
+ * MachineGuid, or a control-plane-issued value on a hosted runtime). Cached for
+ * the process lifetime. Same machine -> same value across reboots.
  *
- * Callers should treat this as opaque: the format differs per platform
- * (macOS IOPlatformUUID, Linux systemd machine-id, Windows MachineGuid).
- * The guarantee is only: same machine -> same value across reboots, and the
- * same value from every binary that calls this function.
- *
- * On a hosted runtime the control-plane-issued `OVERSKY_MACHINE_UUID` wins.
+ * Almost nothing should call this: `getMachineUuid()` is what goes on the wire,
+ * and it equals this for the default profile.
  *
  * Falls back to a deterministic hostname+username hash if the platform
  * probe fails. This preserves server-side record continuity even on
  * locked-down machines that refuse ioreg / registry access.
  */
-function getMachineUuid() {
+function getHardwareMachineUuid() {
     const hostedMachineUuid = hostedRuntimeIdOverride('OVERSKY_MACHINE_UUID');
     if (hostedMachineUuid)
         return hostedMachineUuid;
@@ -150,7 +154,143 @@ function getMachineUuid() {
     cachedMachineUuid = fallback;
     return fallback;
 }
+// ---------------------------------------------------------------------------
+// Profile-qualified machine identity (OSK-13845)
+//
+// The server keys a Daemon row on (user, machineUuid), pins ONE device key to
+// that row, and groups Harness rows into one "machine" by it. A profile is the
+// documented way to run a second, isolated daemon on the same computer, and
+// while the machineUuid was hardware only a second profile landed on the FIRST
+// profile's row: it replaced the machine page's Daemon and working directory,
+// re-registered every harness under itself, and its interactive login re-pinned
+// the row's device key (OSK-12063), so the default profile's next refresh was
+// refused DEVICE_KEY_MISMATCH and every `skrr` call failed until a re-login.
+//
+// So a profile that STARTS NEW on a machine is qualified:
+// `<hardware>:p-<12 hex of sha256(profile)>`. Two rules keep everything that
+// exists where it is:
+//
+//   - the default profile is NEVER qualified: its identity is the hardware value
+//     it has always had, so no existing machine row changes;
+//   - a non-default profile that already holds credentials (an
+//     `auth-binding.json` or a persisted daemon identity) keeps the hardware
+//     value. Its refresh tokens are bound to that row and the server refuses a
+//     refresh whose machineUuid differs from the stored one (H7), so qualifying
+//     it would sign it out. It stays a second daemon on the shared row.
+//
+// The choice is made ONCE, from that evidence, and written to the profile's
+// `machine-identity.json`; afterwards it is read, never re-derived. Deriving it
+// every time would flip a profile from qualified to shared the moment its own
+// first login wrote `auth-binding.json`.
+// ---------------------------------------------------------------------------
+/** The profile's persisted machine-identity choice, beside its other state. */
+exports.MACHINE_IDENTITY_FILENAME = 'machine-identity.json';
+/** Files that prove a profile already holds credentials bound to the shared row. */
+const PRE_EXISTING_PROFILE_EVIDENCE = ['auth-binding.json', 'daemon-identity.json'];
+const DEFAULT_PROFILE_NAME = 'default';
+/** The server caps `machineUuid` at 64 characters; 36 + 15 fits, and so does a 41-character fallback. */
+function qualifyMachineUuid(hardware, profile) {
+    const digest = node_crypto_1.default
+        .createHash('sha256')
+        .update(`profile:${profile}`)
+        .digest('hex')
+        .slice(0, 12);
+    return `${hardware}:p-${digest}`;
+}
+let activeMachineProfile = null;
+const profileChoiceCache = new Map();
+/**
+ * Tell this module which profile the process runs as. Called wherever a binary
+ * resolves its profile (`setActiveProfile` in the daemon and in the CLI), so the
+ * identity cannot depend on call order. `null`, '' and the default profile all
+ * mean "the hardware identity".
+ */
+function setMachineUuidProfile(profile) {
+    activeMachineProfile = typeof profile === 'string' && profile.trim() ? profile.trim() : null;
+}
+function getMachineUuidProfile() {
+    return activeMachineProfile;
+}
+function readPersistedChoice(file, hardware, profile) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(file, 'utf-8'));
+        // A file from another machine (a restored backup, a synced home) is absent.
+        if (parsed?.version !== 1 || parsed.hardware !== hardware)
+            return null;
+        // Only the two values this module can produce are accepted: a hand-edited or
+        // foreign string must never become an identity.
+        if (parsed.machineUuid === hardware)
+            return hardware;
+        const qualified = qualifyMachineUuid(hardware, profile);
+        return parsed.machineUuid === qualified ? qualified : null;
+    }
+    catch {
+        return null;
+    }
+}
+function persistChoice(dir, file, hardware, machineUuid, reason) {
+    try {
+        node_fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        const body = { version: 1, hardware, machineUuid, reason, decidedAt: new Date().toISOString() };
+        node_fs_1.default.writeFileSync(tmp, `${JSON.stringify(body)}\n`, { mode: 0o600 });
+        node_fs_1.default.renameSync(tmp, file);
+    }
+    catch {
+        // Not persisted: the in-process cache keeps this process consistent, and the
+        // next process decides again from the same evidence.
+    }
+}
+/** The identity a NON-default profile registers under. Never throws. */
+function resolveProfileMachineUuid(profile, hardware) {
+    const cacheKey = `${hardware}\u0000${profile}`;
+    const cached = profileChoiceCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const dir = node_path_1.default.join((0, configRoot_js_1.resolveConfigRoot)(), 'profiles', profile);
+    const file = node_path_1.default.join(dir, exports.MACHINE_IDENTITY_FILENAME);
+    let chosen = readPersistedChoice(file, hardware, profile);
+    if (!chosen) {
+        const preExisting = PRE_EXISTING_PROFILE_EVIDENCE.some((name) => {
+            try {
+                return node_fs_1.default.existsSync(node_path_1.default.join(dir, name));
+            }
+            catch {
+                return false;
+            }
+        });
+        chosen = preExisting ? hardware : qualifyMachineUuid(hardware, profile);
+        persistChoice(dir, file, hardware, chosen, preExisting ? 'pre_existing_profile' : 'new_profile');
+    }
+    profileChoiceCache.set(cacheKey, chosen);
+    return chosen;
+}
+/**
+ * Return the `machineUuid` this process sends to the server.
+ *
+ * Callers should treat this as opaque: the format differs per platform
+ * (macOS IOPlatformUUID, Linux systemd machine-id, Windows MachineGuid), and a
+ * non-default profile that started new carries a `:p-<hash>` suffix. The
+ * guarantee is only: same machine + same profile -> same value across reboots,
+ * and the same value from every binary of that profile that calls this function.
+ *
+ * Equals the hardware identity for the default profile, for a hosted runtime
+ * (the control-plane-issued `OVERSKY_MACHINE_UUID` wins) and for a non-default
+ * profile that already held credentials; see the block above.
+ */
+function getMachineUuid() {
+    const hardware = getHardwareMachineUuid();
+    // A hosted runtime's identity is ISSUED and fenced by the control plane.
+    if (hostedRuntimeIdOverride('OVERSKY_MACHINE_UUID'))
+        return hardware;
+    const profile = activeMachineProfile;
+    if (!profile || profile === DEFAULT_PROFILE_NAME)
+        return hardware;
+    return resolveProfileMachineUuid(profile, hardware);
+}
 /** @internal test seam — forget the cached value so the next call re-probes. */
 function __resetMachineUuidCacheForTest() {
     cachedMachineUuid = null;
+    activeMachineProfile = null;
+    profileChoiceCache.clear();
 }

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/computerWire.d.ts

@@ -309,6 +309,28 @@ export declare const COMPUTER_CAPABILITIES: {
      * before, and never sends the input.
      */
     readonly browserViewport: "computer_browser_viewport_v1";
+    /**
+     * A browser surface whose browser is still starting says so (OSK-13824): its
+     * descriptor carries `starting: { since }` from the moment its Chromium
+     * begins to launch until that launch ends (running, or failed), and the
+     * window shows "Starting the browser…" instead of subscribing into a
+     * refusal. A cold start on a fresh guest takes 25–30 s. A daemon announcing
+     * this states the ABSENCE of `starting` too: a browser surface without it
+     * is not starting. Without the announcement a client cannot tell, and falls
+     * back to reading a surface it saw open moments ago as starting.
+     */
+    readonly browserStarting: "computer_browser_starting_v1";
+    /**
+     * An agent actor on the machine's activity and control leases (OSK-13827)
+     * names the REAL agent: `agentId` is the agent's own id for tool-call and
+     * browser sessions too (v1 daemons put the SESSION id there for tool calls,
+     * so no reader could ever name them), and may carry `engine`, the harness
+     * the session runs on, so one agent's sessions on different engines can be
+     * told apart. A daemon announcing this states what it sends; the server
+     * withholds `engine` from every other daemon's actors, and a reader treats
+     * an actor without it as it always did.
+     */
+    readonly activityActorV2: "computer_activity_actor_v2";
 };
 export type ComputerCapabilityKey = keyof typeof COMPUTER_CAPABILITIES;
 export type ComputerCapability = (typeof COMPUTER_CAPABILITIES)[ComputerCapabilityKey];
@@ -355,7 +377,17 @@ export interface ComputerWireAgentActor {
     agentId: string;
     sessionId: string;
     label: string;
+    /**
+     * The engine the session runs on (`claude-code`, `codex`, …), as the daemon
+     * names its backend. Present only from a daemon that announced
+     * `computer_activity_actor_v2` (`COMPUTER_CAPABILITIES.activityActorV2`).
+     * A display distinction between one agent's sessions, never an identity:
+     * `sameComputerActor` still compares the agent id and the session id.
+     */
+    engine?: string;
 }
+/** The longest `engine` the wire carries; a longer one is not an engine name. */
+export declare const COMPUTER_ACTOR_ENGINE_MAX_LENGTH = 64;
 export interface ComputerWireHumanActor {
     kind: 'human';
     userId: string;

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/computerWire.js

@@ -329,6 +329,28 @@ export const COMPUTER_CAPABILITIES = {
      * before, and never sends the input.
      */
     browserViewport: 'computer_browser_viewport_v1',
+    /**
+     * A browser surface whose browser is still starting says so (OSK-13824): its
+     * descriptor carries `starting: { since }` from the moment its Chromium
+     * begins to launch until that launch ends (running, or failed), and the
+     * window shows "Starting the browser…" instead of subscribing into a
+     * refusal. A cold start on a fresh guest takes 25–30 s. A daemon announcing
+     * this states the ABSENCE of `starting` too: a browser surface without it
+     * is not starting. Without the announcement a client cannot tell, and falls
+     * back to reading a surface it saw open moments ago as starting.
+     */
+    browserStarting: 'computer_browser_starting_v1',
+    /**
+     * An agent actor on the machine's activity and control leases (OSK-13827)
+     * names the REAL agent: `agentId` is the agent's own id for tool-call and
+     * browser sessions too (v1 daemons put the SESSION id there for tool calls,
+     * so no reader could ever name them), and may carry `engine`, the harness
+     * the session runs on, so one agent's sessions on different engines can be
+     * told apart. A daemon announcing this states what it sends; the server
+     * withholds `engine` from every other daemon's actors, and a reader treats
+     * an actor without it as it always did.
+     */
+    activityActorV2: 'computer_activity_actor_v2',
 };
 export const COMPUTER_CAPABILITY_VALUES = Object.values(COMPUTER_CAPABILITIES);
 // ---------------------------------------------------------------------------
@@ -432,6 +454,8 @@ export function isComputerPlatformRouteSession(sessionId) {
     return (typeof sessionId === 'string' &&
         COMPUTER_PLATFORM_ROUTE_SESSION_PREFIXES.some((prefix) => sessionId.startsWith(prefix)));
 }
+/** The longest `engine` the wire carries; a longer one is not an engine name. */
+export const COMPUTER_ACTOR_ENGINE_MAX_LENGTH = 64;
 /**
  * How a person present on the machine reached it: as its owner, or through a
  * grant at one of the two tiers. Agents carry no access level — an agent

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/dedicatedRuntimeBusyWire.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The Dedicated Runtime busy-report wire contract (power-control task K2,
+ * `dedicated-runtime-power-and-demand-wake-2026-10-07.md` §7.3 / §13.5).
+ *
+ * Declared ONCE, here. The daemon is published and cannot import the API, so
+ * the capability name, the payload shape and its bounds live in this package,
+ * which every end can import (`@skrr-ai/auth-core/dedicated-runtime-busy-wire`).
+ * `dedicatedRuntimeBusyWire.test.ts` fails on a second spelling of the
+ * capability anywhere else in the repo.
+ *
+ * WHAT THE REPORT SAYS
+ * ---------------------------------------------------------------------------
+ * "Does anything run in the tenant workload slice?" — read by the guest daemon
+ * from cgroup v2 `skrr-workload.slice`, recursively (the slice root is empty by
+ * contract; processes live in leaves), with the root-owned sshd listener left
+ * out. It is a LOCAL read summarised into counts; no per-process list ever
+ * crosses the wire.
+ *
+ * FAIL CLOSED. `busy` is `true | false | 'unknown'`. Any failure to read — a
+ * missing slice, an unreadable file, a tree too large to walk, a quiesce in
+ * progress, an sshd that is not where the image promises — is `'unknown'`, and
+ * a reader MUST treat `'unknown'` as busy. `false` is only ever the daemon
+ * having positively read an empty slice.
+ *
+ * THE POLICY KNOB (OPEN PRODUCT QUESTION — not decided here)
+ * ---------------------------------------------------------------------------
+ * An idle tmux server or a shell prompt keeps a leaf populated forever. The
+ * owner decision is that tmux/SSH shells ARE protected, but whether an IDLE
+ * shell should pin the machine is undecided. So the report carries both
+ * readings and the server chooses:
+ *
+ *   - `busy`                    the STRICT reading (`policy: 'strict'`): every
+ *                                process in the slice counts. This is the
+ *                                default and the only one a server should act
+ *                                on until the product question is answered.
+ *   - `busyIgnoringIdleShells`  the same read with the `idleShell` bucket
+ *                                removed. Classification is by process name
+ *                                (a shell or tmux with nothing else running),
+ *                                a HEURISTIC: it cannot see a shell loop, so
+ *                                it must never be the default.
+ *
+ * The `breakdown` says which bucket made it busy, for the "why" text.
+ */
+export declare const DEDICATED_RUNTIME_BUSY_REPORT_CAPABILITY = "dedicated_runtime_busy_report_v1";
+/** The heartbeat key the report rides under. Sent only by a daemon that announced the capability. */
+export declare const DEDICATED_RUNTIME_BUSY_HEARTBEAT_KEY = "dedicatedRuntimeBusy";
+export declare const DEDICATED_RUNTIME_BUSY_REPORT_VERSION = 1;
+/**
+ * `strict`: every process in the slice (less the root sshd listener) counts.
+ * The only value v1 sends; the field exists so a later relaxation is a new
+ * value rather than a silent change of meaning.
+ */
+export declare const DEDICATED_RUNTIME_BUSY_POLICIES: readonly ["strict"];
+export type DedicatedRuntimeBusyPolicy = (typeof DEDICATED_RUNTIME_BUSY_POLICIES)[number];
+/**
+ * Why the daemon could not give a definite answer, or `ok`. Anything but `ok`
+ * pairs with `busy: 'unknown'`.
+ */
+export declare const DEDICATED_RUNTIME_BUSY_SLICE_HEALTH: readonly ["ok", "not_a_guest", "slice_missing", "slice_unreadable", "ssh_not_in_slice", "tree_too_large", "quiesced", "read_error"];
+export type DedicatedRuntimeBusySliceHealth = (typeof DEDICATED_RUNTIME_BUSY_SLICE_HEALTH)[number];
+export declare const DEDICATED_RUNTIME_BUSY_LIMITS: {
+    /** Service leaf names carried for the "busy because of service X" text. */
+    readonly maxServiceNames: 8;
+    readonly maxServiceNameLength: 48;
+    /** Cgroup leaves the daemon will visit; more is `tree_too_large` -> unknown. */
+    readonly maxLeaves: 64;
+    readonly maxDepth: 4;
+    /** Processes the daemon classifies per read; the rest count as workload. */
+    readonly maxClassifiedPids: 256;
+    /** Hard ceiling on the serialized report. */
+    readonly maxSerializedBytes: 1024;
+};
+export interface DedicatedRuntimeBusyBreakdown {
+    /** Processes in non-service, non-ssh leaves (the `default` leaf, the slice root) that are not idle-shell class. */
+    workload: number;
+    /** Processes in `skrr-svc-*.scope` leaves: a declared service running, always-on by design. */
+    service: number;
+    /** SSH connection plumbing in `ssh.service` that is not the root listener (non-root sshd, the session helper) and other non-shell processes there. */
+    ssh: number;
+    /** Shell or tmux processes in `default` / `ssh.service` (heuristic by name; see header). */
+    idleShell: number;
+    /** Root-owned sshd processes left out of every count above. */
+    excludedSshd: number;
+    /** True when more processes existed than were classified; the rest are in `workload`. */
+    truncated: boolean;
+    /** Up to `maxServiceNames` service leaf names that have processes. */
+    services: string[];
+}
+export interface DedicatedRuntimeBusyReport {
+    version: typeof DEDICATED_RUNTIME_BUSY_REPORT_VERSION;
+    policy: DedicatedRuntimeBusyPolicy;
+    /** Strict reading. `'unknown'` MUST be treated as busy. */
+    busy: boolean | 'unknown';
+    /** Same read with the `idleShell` bucket removed; a heuristic, not the default. */
+    busyIgnoringIdleShells: boolean | 'unknown';
+    breakdown: DedicatedRuntimeBusyBreakdown;
+    /** ISO time the daemon read the slice. */
+    readAt: string;
+    sliceHealth: DedicatedRuntimeBusySliceHealth;
+}
+/**
+ * The reader's view of a daemon's heartbeat section. Anything malformed, from
+ * a daemon that did not announce the capability, or oversized is `null`, and
+ * the caller must then treat the machine as busy. Never trusts a field it did
+ * not validate; a value is clamped, not coerced to "idle".
+ */
+export declare function parseDedicatedRuntimeBusyReport(raw: unknown): DedicatedRuntimeBusyReport | null;

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/dedicatedRuntimeBusyWire.js

@@ -0,0 +1,147 @@
+/**
+ * The Dedicated Runtime busy-report wire contract (power-control task K2,
+ * `dedicated-runtime-power-and-demand-wake-2026-10-07.md` §7.3 / §13.5).
+ *
+ * Declared ONCE, here. The daemon is published and cannot import the API, so
+ * the capability name, the payload shape and its bounds live in this package,
+ * which every end can import (`@skrr-ai/auth-core/dedicated-runtime-busy-wire`).
+ * `dedicatedRuntimeBusyWire.test.ts` fails on a second spelling of the
+ * capability anywhere else in the repo.
+ *
+ * WHAT THE REPORT SAYS
+ * ---------------------------------------------------------------------------
+ * "Does anything run in the tenant workload slice?" — read by the guest daemon
+ * from cgroup v2 `skrr-workload.slice`, recursively (the slice root is empty by
+ * contract; processes live in leaves), with the root-owned sshd listener left
+ * out. It is a LOCAL read summarised into counts; no per-process list ever
+ * crosses the wire.
+ *
+ * FAIL CLOSED. `busy` is `true | false | 'unknown'`. Any failure to read — a
+ * missing slice, an unreadable file, a tree too large to walk, a quiesce in
+ * progress, an sshd that is not where the image promises — is `'unknown'`, and
+ * a reader MUST treat `'unknown'` as busy. `false` is only ever the daemon
+ * having positively read an empty slice.
+ *
+ * THE POLICY KNOB (OPEN PRODUCT QUESTION — not decided here)
+ * ---------------------------------------------------------------------------
+ * An idle tmux server or a shell prompt keeps a leaf populated forever. The
+ * owner decision is that tmux/SSH shells ARE protected, but whether an IDLE
+ * shell should pin the machine is undecided. So the report carries both
+ * readings and the server chooses:
+ *
+ *   - `busy`                    the STRICT reading (`policy: 'strict'`): every
+ *                                process in the slice counts. This is the
+ *                                default and the only one a server should act
+ *                                on until the product question is answered.
+ *   - `busyIgnoringIdleShells`  the same read with the `idleShell` bucket
+ *                                removed. Classification is by process name
+ *                                (a shell or tmux with nothing else running),
+ *                                a HEURISTIC: it cannot see a shell loop, so
+ *                                it must never be the default.
+ *
+ * The `breakdown` says which bucket made it busy, for the "why" text.
+ */
+export const DEDICATED_RUNTIME_BUSY_REPORT_CAPABILITY = 'dedicated_runtime_busy_report_v1';
+/** The heartbeat key the report rides under. Sent only by a daemon that announced the capability. */
+export const DEDICATED_RUNTIME_BUSY_HEARTBEAT_KEY = 'dedicatedRuntimeBusy';
+export const DEDICATED_RUNTIME_BUSY_REPORT_VERSION = 1;
+/**
+ * `strict`: every process in the slice (less the root sshd listener) counts.
+ * The only value v1 sends; the field exists so a later relaxation is a new
+ * value rather than a silent change of meaning.
+ */
+export const DEDICATED_RUNTIME_BUSY_POLICIES = ['strict'];
+/**
+ * Why the daemon could not give a definite answer, or `ok`. Anything but `ok`
+ * pairs with `busy: 'unknown'`.
+ */
+export const DEDICATED_RUNTIME_BUSY_SLICE_HEALTH = [
+    'ok',
+    'not_a_guest',
+    'slice_missing',
+    'slice_unreadable',
+    'ssh_not_in_slice',
+    'tree_too_large',
+    'quiesced',
+    'read_error',
+];
+export const DEDICATED_RUNTIME_BUSY_LIMITS = {
+    /** Service leaf names carried for the "busy because of service X" text. */
+    maxServiceNames: 8,
+    maxServiceNameLength: 48,
+    /** Cgroup leaves the daemon will visit; more is `tree_too_large` -> unknown. */
+    maxLeaves: 64,
+    maxDepth: 4,
+    /** Processes the daemon classifies per read; the rest count as workload. */
+    maxClassifiedPids: 256,
+    /** Hard ceiling on the serialized report. */
+    maxSerializedBytes: 1024,
+};
+/**
+ * The reader's view of a daemon's heartbeat section. Anything malformed, from
+ * a daemon that did not announce the capability, or oversized is `null`, and
+ * the caller must then treat the machine as busy. Never trusts a field it did
+ * not validate; a value is clamped, not coerced to "idle".
+ */
+export function parseDedicatedRuntimeBusyReport(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (r.version !== DEDICATED_RUNTIME_BUSY_REPORT_VERSION)
+        return null;
+    if (!DEDICATED_RUNTIME_BUSY_POLICIES.includes(r.policy))
+        return null;
+    const tri = (v) => v === true || v === false || v === 'unknown' ? v : undefined;
+    const busy = tri(r.busy);
+    const ignoring = tri(r.busyIgnoringIdleShells);
+    if (busy === undefined || ignoring === undefined)
+        return null;
+    if (!DEDICATED_RUNTIME_BUSY_SLICE_HEALTH.includes(r.sliceHealth)) {
+        return null;
+    }
+    const readAtMs = typeof r.readAt === 'string' ? Date.parse(r.readAt) : NaN;
+    if (!Number.isFinite(readAtMs))
+        return null;
+    const b = r.breakdown;
+    if (!b || typeof b !== 'object')
+        return null;
+    const count = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : null;
+    const workload = count(b.workload);
+    const service = count(b.service);
+    const ssh = count(b.ssh);
+    const idleShell = count(b.idleShell);
+    const excludedSshd = count(b.excludedSshd);
+    if (workload === null ||
+        service === null ||
+        ssh === null ||
+        idleShell === null ||
+        excludedSshd === null ||
+        typeof b.truncated !== 'boolean' ||
+        !Array.isArray(b.services)) {
+        return null;
+    }
+    const services = b.services
+        .filter((s) => typeof s === 'string')
+        .slice(0, DEDICATED_RUNTIME_BUSY_LIMITS.maxServiceNames)
+        .map((s) => s.slice(0, DEDICATED_RUNTIME_BUSY_LIMITS.maxServiceNameLength));
+    const report = {
+        version: DEDICATED_RUNTIME_BUSY_REPORT_VERSION,
+        policy: r.policy,
+        busy,
+        busyIgnoringIdleShells: ignoring,
+        breakdown: {
+            workload,
+            service,
+            ssh,
+            idleShell,
+            excludedSshd,
+            truncated: b.truncated,
+            services,
+        },
+        readAt: new Date(readAtMs).toISOString(),
+        sliceHealth: r.sliceHealth,
+    };
+    if (JSON.stringify(report).length > DEDICATED_RUNTIME_BUSY_LIMITS.maxSerializedBytes)
+        return null;
+    return report;
+}

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/dedicatedRuntimeWakeWire.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The Dedicated Runtime wake-progress wire contract (power-control task W5,
+ * `dedicated-runtime-power-and-demand-wake-2026-10-07.md` §5.3, §7.2, §9).
+ *
+ * Declared ONCE, here, for the same reason `computerWire.ts` is: the browser,
+ * the React Native app and the CLI import it, and none of them may spell the
+ * event, the capability or a code a second time. `dedicatedRuntimeWakeWire.test.ts`
+ * fails on a second spelling in the API.
+ *
+ * WHAT IT IS
+ * ---------------------------------------------------------------------------
+ * A person opens a terminal, an SSH channel, a service call or the Computer on a
+ * STOPPED Dedicated Runtime. That is wake progress, not an error: the relay asks
+ * `requestWake` (source `person`) to start the machine, then tells THAT request,
+ * in stages, how far the start has got, until the machine is assignable and the
+ * original request is served, or a bound runs out and it says why and what to do.
+ *
+ * THE CLIENT ANNOUNCES IT
+ * ---------------------------------------------------------------------------
+ * A client that has not announced `dedicated_wake_progress_v1` in the open
+ * request's `capabilities` array is NEVER sent `dedicated:wake:progress` and is
+ * never made to wait: it gets an immediate typed refusal instead. (A client
+ * socket has no registration step to announce on, so the announcement rides each
+ * request — stateless, nothing held in the relay.)
+ *
+ * THE VOCABULARY
+ * ---------------------------------------------------------------------------
+ * `phase` uses the cold-start measurement's phase names
+ * (`scripts/dedicated-runtime/measure-cold-start.js` `COLD_START_PHASES`), so
+ * what the person sees and what F4 measures are the same words. A spec holds the
+ * two lists equal.
+ *
+ * NOT A SPINNER WITHOUT A BOUND
+ * ---------------------------------------------------------------------------
+ * `boundMs` is carried on every event so a surface can show elapsed-of-bound.
+ * The bound sits ABOVE a slow-but-working start (design §9): running out says
+ * "this is taking longer than expected" and the machine is left starting; it is
+ * never an accusation that the machine is dead.
+ */
+/** API -> client, on the same socket as the request it belongs to. */
+export declare const DEDICATED_WAKE_EVENTS: {
+    readonly progress: "dedicated:wake:progress";
+};
+/** Announced in the open request's `capabilities` array. */
+export declare const DEDICATED_WAKE_CAPABILITIES: {
+    readonly progress: "dedicated_wake_progress_v1";
+};
+export type DedicatedWakeCapability = (typeof DEDICATED_WAKE_CAPABILITIES)[keyof typeof DEDICATED_WAKE_CAPABILITIES];
+/** Same names, same order as `WAKE_PHASES` in api/server/services/DedicatedRuntime/wakePhases.js (pinned by a test). */
+export declare const DEDICATED_WAKE_PHASES: readonly ["start_requested", "provider_start_accepted", "instance_running", "daemon_connected", "first_heartbeat", "assignable"];
+export type DedicatedWakePhase = (typeof DEDICATED_WAKE_PHASES)[number];
+/**
+ * - `waking`    a start is in flight; `phase` says how far.
+ * - `ready`     assignable; the original request is about to be served.
+ * - `deferred`  the machine is stopping; nothing was started. Retry after `retryAfterSeconds`.
+ * - `refused`   the start was refused, with `code`, `reason`, `detail`, `fix`.
+ * - `timed_out` the bound ran out while it was still starting. Not a failure of the machine.
+ */
+export declare const DEDICATED_WAKE_STATES: readonly ["waking", "ready", "deferred", "refused", "timed_out"];
+export type DedicatedWakeState = (typeof DEDICATED_WAKE_STATES)[number];
+/** The surfaces a wake can be asked from. */
+export declare const DEDICATED_WAKE_SURFACES: readonly ["terminal", "ssh", "services", "templates", "computer", "http"];
+export type DedicatedWakeSurface = (typeof DEDICATED_WAKE_SURFACES)[number];
+/**
+ * Typed refusals. Each is a different fact with a different next step; none of
+ * them is the generic "Dedicated Runtime dispatch was refused".
+ */
+export declare const DEDICATED_WAKE_CODES: {
+    /** Stopped, and this request did not (or could not) wake it. */
+    readonly stopped: "DEDICATED_RUNTIME_STOPPED";
+    /** A stop is finishing; retry when it has. */
+    readonly stopping: "DEDICATED_RUNTIME_STOPPING";
+    /** A start is in flight (ours or someone's). */
+    readonly starting: "DEDICATED_RUNTIME_STARTING";
+    /** The bound ran out while it was still starting. */
+    readonly timeout: "DEDICATED_RUNTIME_WAKE_TIMEOUT";
+    /** The start was refused: the plan no longer includes the machine. */
+    readonly entitlement: "DEDICATED_RUNTIME_WAKE_REFUSED_ENTITLEMENT";
+    /** The start was refused: the spend cap was reached. */
+    readonly spendCap: "DEDICATED_RUNTIME_WAKE_REFUSED_SPEND_CAP";
+    /** Any other refusal; `reason` names it. */
+    readonly refused: "DEDICATED_RUNTIME_WAKE_REFUSED";
+    /** The start was requested and the machine fell back to stopped or failed. */
+    readonly failed: "DEDICATED_RUNTIME_WAKE_FAILED";
+};
+export type DedicatedWakeCode = (typeof DEDICATED_WAKE_CODES)[keyof typeof DEDICATED_WAKE_CODES];
+/**
+ * How long a surface waits for a start before saying it is taking longer than
+ * expected. Above the slow-but-working case: a cold start on a fresh guest
+ * takes 25-30 s for the browser alone, and the AMI boot is longer. It is a
+ * bound on what we show, never a verdict on the machine.
+ */
+export declare const DEDICATED_WAKE_BOUND_MS = 180000;
+/** How often the relay re-reads the lease while waiting. */
+export declare const DEDICATED_WAKE_POLL_MS = 2000;
+export interface DedicatedWakeProgress {
+    leaseId: string;
+    surface: DedicatedWakeSurface;
+    /** The id of the request this belongs to (`requestId`, `channelId`, ...). */
+    ref?: string;
+    state: DedicatedWakeState;
+    /** Present while `waking`, and on `timed_out` (where the machine had got to). */
+    phase?: DedicatedWakePhase;
+    elapsedMs: number;
+    boundMs: number;
+    /** Power reason (e.g. `wake_refused_spend_cap`) or a lifecycle reason. */
+    reason?: string;
+    /** One of `DEDICATED_WAKE_CODES` on `refused`, `deferred` and `timed_out`. */
+    code?: DedicatedWakeCode;
+    detail?: string;
+    /** What the person can do next. */
+    fix?: string | null;
+    retryAfterSeconds?: number;
+}
+export declare function clientAnnouncesWakeProgress(capabilities: unknown): boolean;