@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/tenant-token-verifier.js

@@ -0,0 +1,79 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+export function cognitoIssuer(config) {
+    return `https://cognito-idp.${config.region}.amazonaws.com/${config.userPoolId}`;
+}
+function asStringArray(value) {
+    if (Array.isArray(value)) {
+        return value.filter((entry) => typeof entry === "string");
+    }
+    return typeof value === "string" ? [value] : [];
+}
+/**
+ * Cognito signs with RS256. The algorithm list is an ALLOWLIST on purpose: without
+ * it a token could name `none` (or an HMAC alg keyed on the public JWKS material)
+ * and verify against our own published key.
+ */
+const ALLOWED_ALGORITHMS = ["RS256"];
+export function createTenantTokenVerifier(config) {
+    const issuer = cognitoIssuer(config);
+    // jose caches the key set and re-fetches on an unknown `kid`, so pool key
+    // rotation is handled without restarting the daemon.
+    const jwks = createRemoteJWKSet(new URL(`${issuer}/.well-known/jwks.json`), {
+        cooldownDuration: 30000,
+        cacheMaxAge: 10 * 60000,
+    });
+    return {
+        issuer,
+        async verify(token) {
+            let payload;
+            try {
+                // jwtVerify enforces signature, `iss`, `exp` and `nbf`.
+                ({ payload } = await jwtVerify(token, jwks, {
+                    issuer,
+                    algorithms: [...ALLOWED_ALGORITHMS],
+                }));
+            }
+            catch (error) {
+                // Every failure path lands here, including a JWKS fetch failure. The
+                // caller must treat this as a rejection and never as "skip the check".
+                return { ok: false, reason: error instanceof Error ? error.message : "invalid token" };
+            }
+            const tokenUse = payload.token_use;
+            if (tokenUse !== "id" && tokenUse !== "access") {
+                return { ok: false, reason: `unexpected token_use: ${String(tokenUse)}` };
+            }
+            if (config.clientId) {
+                // Cognito puts the app client in `aud` on id tokens and `client_id` on
+                // access tokens. Checking only one silently accepts the other kind.
+                const audience = tokenUse === "id" ? asStringArray(payload.aud) : [];
+                const clientId = typeof payload.client_id === "string" ? payload.client_id : null;
+                const matches = audience.includes(config.clientId) || (clientId !== null && clientId === config.clientId);
+                if (!matches) {
+                    return { ok: false, reason: "token was not issued for this app client" };
+                }
+            }
+            const groups = asStringArray(payload["cognito:groups"]);
+            if (config.allowedGroups && config.allowedGroups.length > 0) {
+                const permitted = groups.some((group) => config.allowedGroups?.includes(group));
+                if (!permitted) {
+                    return { ok: false, reason: "token carries no permitted group" };
+                }
+            }
+            const sub = typeof payload.sub === "string" ? payload.sub : null;
+            if (!sub) {
+                return { ok: false, reason: "token has no sub" };
+            }
+            return {
+                ok: true,
+                identity: {
+                    sub,
+                    email: typeof payload.email === "string" ? payload.email : undefined,
+                    groups,
+                    tokenUse,
+                    expiresAt: typeof payload.exp === "number" ? payload.exp : 0,
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=tenant-token-verifier.js.map

package/dist/server/server/update/installer.d.ts

@@ -0,0 +1,70 @@
+export interface InstallerDeps {
+    /** Injected for tests. Runs a command and resolves on exit 0. */
+    run?: (command: string, args: string[], options: {
+        cwd?: string;
+        env?: NodeJS.ProcessEnv;
+        timeoutMs?: number;
+    }) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    nodeExecPath?: string;
+    npmExecPath?: string;
+    registryUrl?: string;
+    log?: (message: string, fields?: Record<string, unknown>) => void;
+}
+/**
+ * Install a version into its own slot. Never touches the running slot.
+ *
+ * NODE_ENV is cleared explicitly: this box exports NODE_ENV=production and npm then
+ * resolves with omit=dev, which has already caused real breakage here. A staging
+ * install must be deterministic regardless of the daemon's ambient environment.
+ */
+export declare function stageVersion(paseoHome: string, version: string, deps?: InstallerDeps & {
+    /**
+     * Activate a slot that is already on disk instead of downloading it. For
+     * staging on one machine and activating later, or activating a locally built
+     * slot. Activation is still gated by `verifySlot`, so this skips the download,
+     * never the safety check.
+     */
+    reuseExisting?: boolean;
+}): Promise<{
+    slotRoot: string;
+    reused: boolean;
+}>;
+export interface VerifyResult {
+    ok: boolean;
+    problems: string[];
+    workerEntry: string | null;
+}
+/**
+ * Prove a staged slot is actually runnable before making it `current`.
+ *
+ * The three checks are not arbitrary. Releases 0.2.6 through 0.3.2 installed
+ * cleanly and were still unusable, because `@hyperdrive.bot/fleet-server` depended
+ * on a package that had never been published: `npm install` exited 0 and the daemon
+ * died on `import`. So an exit code is not evidence. What is evidence: the worker
+ * binary exists, the SDK resolves from the server's own tree, and the module in that
+ * failure's stack trace actually imports.
+ */
+export declare function verifySlot(slotRoot: string, deps?: InstallerDeps): Promise<VerifyResult>;
+/**
+ * Make `version` current, remembering the outgoing version as `previous`.
+ *
+ * Returns the version that was displaced, or null on a first install.
+ */
+export declare function swapTo(paseoHome: string, version: string): {
+    previousVersion: string | null;
+};
+/**
+ * Point `current` back at `previous` and pin the failed version.
+ *
+ * Pinning is the part that matters: without it the next poll re-installs the same
+ * broken version, and supervisor backoff only slows that loop rather than ending it.
+ */
+export declare function rollback(paseoHome: string, failedVersion: string, reason: string): {
+    rolledBackTo: string | null;
+};
+/** Delete slots that are neither current nor previous, oldest first. */
+export declare function pruneSlots(paseoHome: string, keep: string[]): string[];
+//# sourceMappingURL=installer.d.ts.map

package/dist/server/server/update/installer.js

@@ -0,0 +1,181 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, symlinkSync, unlinkSync, } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { currentLinkPath, previousLinkPath, readSlotVersion, slotPath, slotWorkerEntryCandidates, slotsRoot, } from "./slots.js";
+import { DAEMON_PACKAGE_NAME } from "./registry.js";
+import { writeUpdateState } from "./state.js";
+const execFileAsync = promisify(execFile);
+function defaultRun(command, args, options) {
+    return execFileAsync(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        timeout: options.timeoutMs ?? 600000,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+}
+/**
+ * Install a version into its own slot. Never touches the running slot.
+ *
+ * NODE_ENV is cleared explicitly: this box exports NODE_ENV=production and npm then
+ * resolves with omit=dev, which has already caused real breakage here. A staging
+ * install must be deterministic regardless of the daemon's ambient environment.
+ */
+export async function stageVersion(paseoHome, version, deps = {}) {
+    const run = deps.run ?? defaultRun;
+    const slotRoot = slotPath(paseoHome, version);
+    if (deps.reuseExisting && existsSync(slotRoot)) {
+        deps.log?.("reusing staged slot", { version, slotRoot });
+        return { slotRoot, reused: true };
+    }
+    // A half-finished slot from a previous attempt is worse than no slot: it can
+    // satisfy the entry-exists check while missing a transitive dependency.
+    if (existsSync(slotRoot)) {
+        rmSync(slotRoot, { recursive: true, force: true });
+    }
+    mkdirSync(slotRoot, { recursive: true });
+    // `--global` is load-bearing, not cosmetic. A local `npm install --prefix X` lands
+    // in `X/node_modules`; a global one lands in `X/lib/node_modules` and also writes
+    // `X/bin/paseo`. Slot resolution looks for the global layout, so dropping `-g` here
+    // produces a slot that installs perfectly and then resolves to nothing.
+    const args = [
+        "install",
+        "--global",
+        "--prefix",
+        slotRoot,
+        "--no-fund",
+        "--no-audit",
+        `${DAEMON_PACKAGE_NAME}@${version}`,
+    ];
+    if (deps.registryUrl) {
+        args.push("--registry", deps.registryUrl);
+    }
+    deps.log?.("staging update", { version, slotRoot });
+    await run(deps.npmExecPath ?? "npm", args, {
+        env: { ...process.env, NODE_ENV: "" },
+        timeoutMs: 900000,
+    });
+    return { slotRoot, reused: false };
+}
+/**
+ * Prove a staged slot is actually runnable before making it `current`.
+ *
+ * The three checks are not arbitrary. Releases 0.2.6 through 0.3.2 installed
+ * cleanly and were still unusable, because `@hyperdrive.bot/fleet-server` depended
+ * on a package that had never been published: `npm install` exited 0 and the daemon
+ * died on `import`. So an exit code is not evidence. What is evidence: the worker
+ * binary exists, the SDK resolves from the server's own tree, and the module in that
+ * failure's stack trace actually imports.
+ */
+export async function verifySlot(slotRoot, deps = {}) {
+    const run = deps.run ?? defaultRun;
+    const node = deps.nodeExecPath ?? process.execPath;
+    const problems = [];
+    const workerEntry = slotWorkerEntryCandidates(slotRoot).find((c) => existsSync(c)) ?? null;
+    if (!workerEntry) {
+        problems.push(`no daemon-worker.js found under ${slotRoot}`);
+        return { ok: false, problems, workerEntry: null };
+    }
+    const serverDir = workerEntry.slice(0, workerEntry.indexOf(`${path.sep}dist${path.sep}`));
+    // 1. The dependency that made seven releases uninstallable must resolve.
+    try {
+        await run(node, [
+            "-e",
+            `require.resolve("@hyperdrive.bot/fleet-extension-sdk", { paths: [${JSON.stringify(serverDir)}] })`,
+        ], { timeoutMs: 60000 });
+    }
+    catch (error) {
+        problems.push(`extension SDK does not resolve from the staged server: ${describe(error)}`);
+    }
+    // 2. The exact module from that failure's stack trace must import.
+    const loader = path.join(serverDir, "dist", "server", "extensions", "extension-loader.js");
+    if (existsSync(loader)) {
+        try {
+            await run(node, ["--input-type=module", "-e", `await import(${JSON.stringify(loader)})`], {
+                timeoutMs: 60000,
+            });
+        }
+        catch (error) {
+            problems.push(`extension-loader.js failed to import: ${describe(error)}`);
+        }
+    }
+    else {
+        problems.push(`extension-loader.js missing at ${loader}`);
+    }
+    return { ok: problems.length === 0, problems, workerEntry };
+}
+function describe(error) {
+    if (error && typeof error === "object" && "stderr" in error) {
+        const stderr = String(error.stderr ?? "").trim();
+        if (stderr)
+            return stderr.split("\n").slice(-2).join(" ").slice(0, 300);
+    }
+    return error instanceof Error ? error.message.slice(0, 300) : String(error).slice(0, 300);
+}
+/** Atomically point a slot symlink at a version directory. */
+function linkAtomically(linkPath, targetDir) {
+    const tmp = `${linkPath}.tmp-${process.pid}-${Math.trunc(performance.now())}`;
+    if (existsSync(tmp)) {
+        unlinkSync(tmp);
+    }
+    symlinkSync(targetDir, tmp, "dir");
+    // rename(2) over an existing symlink is atomic on POSIX: no window where the
+    // daemon could observe a missing `current`.
+    renameSync(tmp, linkPath);
+}
+/**
+ * Make `version` current, remembering the outgoing version as `previous`.
+ *
+ * Returns the version that was displaced, or null on a first install.
+ */
+export function swapTo(paseoHome, version) {
+    const target = slotPath(paseoHome, version);
+    if (!existsSync(target)) {
+        throw new Error(`cannot swap to ${version}: slot ${target} does not exist`);
+    }
+    const previousVersion = readSlotVersion(paseoHome, "current");
+    if (previousVersion) {
+        linkAtomically(previousLinkPath(paseoHome), slotPath(paseoHome, previousVersion));
+    }
+    linkAtomically(currentLinkPath(paseoHome), target);
+    return { previousVersion };
+}
+/**
+ * Point `current` back at `previous` and pin the failed version.
+ *
+ * Pinning is the part that matters: without it the next poll re-installs the same
+ * broken version, and supervisor backoff only slows that loop rather than ending it.
+ */
+export function rollback(paseoHome, failedVersion, reason) {
+    const previousVersion = readSlotVersion(paseoHome, "previous");
+    if (previousVersion && existsSync(slotPath(paseoHome, previousVersion))) {
+        linkAtomically(currentLinkPath(paseoHome), slotPath(paseoHome, previousVersion));
+    }
+    else {
+        // No usable previous slot: drop `current` entirely so entry resolution falls
+        // back to the bundled worker rather than exec'ing a known-bad slot.
+        try {
+            unlinkSync(currentLinkPath(paseoHome));
+        }
+        catch {
+            /* already absent */
+        }
+    }
+    writeUpdateState(paseoHome, { pinned: failedVersion, pinnedReason: reason });
+    return { rolledBackTo: previousVersion };
+}
+/** Delete slots that are neither current nor previous, oldest first. */
+export function pruneSlots(paseoHome, keep) {
+    const root = slotsRoot(paseoHome);
+    if (!existsSync(root))
+        return [];
+    const removed = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || keep.includes(entry.name))
+            continue;
+        rmSync(path.join(root, entry.name), { recursive: true, force: true });
+        removed.push(entry.name);
+    }
+    return removed;
+}
+//# sourceMappingURL=installer.js.map

package/dist/server/server/update/registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reads published versions of the daemon package from the npm registry.
+ *
+ * Deliberately narrow: it answers "what is the newest version on this dist-tag",
+ * and nothing else. It never installs, never writes, and never throws into the
+ * daemon loop, because a version check failing must not degrade a running daemon.
+ */
+export declare const DAEMON_PACKAGE_NAME = "@hyperdrive.bot/fleet-cli";
+/** npm dist-tag a release channel publishes to. */
+export type ReleaseChannel = "stable" | "beta" | "dev";
+export declare function distTagForChannel(channel: ReleaseChannel): string;
+export interface RegistryLookup {
+    /** Newest version on the requested tag, or null when the tag does not exist. */
+    version: string | null;
+    /** Every dist-tag, for diagnostics. */
+    distTags: Record<string, string>;
+}
+export interface FetchDistTagsDeps {
+    fetchImpl?: typeof fetch;
+    registryUrl?: string;
+    timeoutMs?: number;
+}
+/**
+ * Fetch dist-tags for the daemon package.
+ *
+ * Uses the registry's lightweight dist-tags endpoint rather than the full packument,
+ * which for this package is megabytes of version metadata we do not need.
+ *
+ * Throws on network or HTTP failure. Callers in the daemon must catch and degrade;
+ * see `checkForUpdate` which does exactly that.
+ */
+export declare function fetchDistTags(packageName?: string, deps?: FetchDistTagsDeps): Promise<RegistryLookup & {
+    distTags: Record<string, string>;
+}>;
+/** Newest version published to a channel, or null when the channel has no release. */
+export declare function fetchChannelVersion(channel: ReleaseChannel, packageName?: string, deps?: FetchDistTagsDeps): Promise<RegistryLookup>;
+/**
+ * Compare two semver-ish versions.
+ *
+ * Intentionally small rather than pulling a semver dependency into the daemon's
+ * runtime deps: the only question asked is "is `candidate` newer than `current`",
+ * over versions this project itself publishes (`0.3.3`, `0.1.104-beta.4`).
+ * Returns 1, -1 or 0. A prerelease sorts below its own release, per semver.
+ */
+export declare function compareVersions(a: string, b: string): number;
+export declare function isNewer(candidate: string, current: string): boolean;
+//# sourceMappingURL=registry.d.ts.map

package/dist/server/server/update/registry.js

@@ -0,0 +1,95 @@
+/**
+ * Reads published versions of the daemon package from the npm registry.
+ *
+ * Deliberately narrow: it answers "what is the newest version on this dist-tag",
+ * and nothing else. It never installs, never writes, and never throws into the
+ * daemon loop, because a version check failing must not degrade a running daemon.
+ */
+export const DAEMON_PACKAGE_NAME = "@hyperdrive.bot/fleet-cli";
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+const DEFAULT_TIMEOUT_MS = 10000;
+export function distTagForChannel(channel) {
+    // `stable` is npm's default tag. beta/dev map to their own tags, which is what
+    // scripts/publish-workspaces.mjs already does for prerelease versions.
+    return channel === "stable" ? "latest" : channel;
+}
+/**
+ * Fetch dist-tags for the daemon package.
+ *
+ * Uses the registry's lightweight dist-tags endpoint rather than the full packument,
+ * which for this package is megabytes of version metadata we do not need.
+ *
+ * Throws on network or HTTP failure. Callers in the daemon must catch and degrade;
+ * see `checkForUpdate` which does exactly that.
+ */
+export async function fetchDistTags(packageName = DAEMON_PACKAGE_NAME, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const registryUrl = (deps.registryUrl ?? DEFAULT_REGISTRY).replace(/\/+$/, "");
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const url = `${registryUrl}/-/package/${encodeURIComponent(packageName)}/dist-tags`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(url, {
+            signal: controller.signal,
+            headers: { accept: "application/json" },
+        });
+        if (!response.ok) {
+            throw new Error(`registry responded ${response.status} for ${packageName} dist-tags`);
+        }
+        const body = (await response.json());
+        if (typeof body !== "object" || body === null) {
+            throw new Error(`registry returned a non-object dist-tags body for ${packageName}`);
+        }
+        const distTags = {};
+        for (const [tag, version] of Object.entries(body)) {
+            if (typeof version === "string" && version.length > 0) {
+                distTags[tag] = version;
+            }
+        }
+        return { version: null, distTags };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Newest version published to a channel, or null when the channel has no release. */
+export async function fetchChannelVersion(channel, packageName = DAEMON_PACKAGE_NAME, deps = {}) {
+    const { distTags } = await fetchDistTags(packageName, deps);
+    const tag = distTagForChannel(channel);
+    return { version: distTags[tag] ?? null, distTags };
+}
+/**
+ * Compare two semver-ish versions.
+ *
+ * Intentionally small rather than pulling a semver dependency into the daemon's
+ * runtime deps: the only question asked is "is `candidate` newer than `current`",
+ * over versions this project itself publishes (`0.3.3`, `0.1.104-beta.4`).
+ * Returns 1, -1 or 0. A prerelease sorts below its own release, per semver.
+ */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const [core, pre = ""] = v.trim().replace(/^v/, "").split("-", 2);
+        const nums = core.split(".").map((n) => Number.parseInt(n, 10) || 0);
+        return { nums: [nums[0] ?? 0, nums[1] ?? 0, nums[2] ?? 0], pre };
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < 3; i += 1) {
+        if (pa.nums[i] !== pb.nums[i]) {
+            return pa.nums[i] > pb.nums[i] ? 1 : -1;
+        }
+    }
+    if (pa.pre === pb.pre)
+        return 0;
+    // No prerelease outranks any prerelease of the same core version.
+    if (pa.pre === "")
+        return 1;
+    if (pb.pre === "")
+        return -1;
+    return pa.pre > pb.pre ? 1 : -1;
+}
+export function isNewer(candidate, current) {
+    return compareVersions(candidate, current) > 0;
+}
+//# sourceMappingURL=registry.js.map

package/dist/server/server/update/slots.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Self-update slot layout, rooted at the paseo home.
+ *
+ *   <home>/versions/<version>/      an `npm install --prefix` tree
+ *   <home>/current   -> versions/<version>   symlink, atomically swapped
+ *   <home>/previous  -> versions/<version>   symlink, the rollback target
+ *   <home>/update-state.json                 channel, pinned version, failures
+ *
+ * Slots live under the paseo home rather than the npm global prefix on purpose:
+ * that prefix is nvm-versioned (`~/.nvm/versions/node/<v>/lib/node_modules`), so a
+ * node switch would strand the daemon, and `npm i -g` writes in place, which
+ * forecloses rollback. The paseo home is already the unit the pid lock isolates on.
+ */
+export declare const SLOT_CURRENT = "current";
+export declare const SLOT_PREVIOUS = "previous";
+export declare const SLOT_VERSIONS_DIR = "versions";
+export declare const UPDATE_STATE_FILE = "update-state.json";
+export declare function slotsRoot(paseoHome: string): string;
+export declare function slotPath(paseoHome: string, version: string): string;
+export declare function currentLinkPath(paseoHome: string): string;
+export declare function previousLinkPath(paseoHome: string): string;
+export declare function updateStatePath(paseoHome: string): string;
+/**
+ * Worker entry candidates inside an installed slot.
+ *
+ * Two layouts, because npm does not guarantee where a transitive dependency lands:
+ * `@hyperdrive.bot/fleet-server` is nested under the CLI in the layout observed on
+ * this box, but npm is free to hoist it to the top of the prefix instead. Both are
+ * checked rather than assumed.
+ *
+ * The `dist/server/server/` doubling is real: the published tarball ships
+ * `dist/server/server/daemon-worker.js`, verified against the installed 0.3.3 tree.
+ */
+export declare function slotWorkerEntryCandidates(slotRoot: string): string[];
+/**
+ * The worker entry for the active slot, or null when no usable slot is installed.
+ *
+ * Returning null is the normal case for an npm-global or checkout install, and the
+ * caller must fall back to its own resolution so those installs behave exactly as
+ * they did before slots existed.
+ */
+export declare function resolveSlotWorkerEntry(paseoHome: string): string | null;
+/** Version a slot symlink points at, or null when absent or dangling. */
+export declare function readSlotVersion(paseoHome: string, link: string): string | null;
+//# sourceMappingURL=slots.d.ts.map

package/dist/server/server/update/slots.js

@@ -0,0 +1,97 @@
+import { existsSync, readlinkSync, statSync } from "node:fs";
+import path from "node:path";
+/**
+ * Self-update slot layout, rooted at the paseo home.
+ *
+ *   <home>/versions/<version>/      an `npm install --prefix` tree
+ *   <home>/current   -> versions/<version>   symlink, atomically swapped
+ *   <home>/previous  -> versions/<version>   symlink, the rollback target
+ *   <home>/update-state.json                 channel, pinned version, failures
+ *
+ * Slots live under the paseo home rather than the npm global prefix on purpose:
+ * that prefix is nvm-versioned (`~/.nvm/versions/node/<v>/lib/node_modules`), so a
+ * node switch would strand the daemon, and `npm i -g` writes in place, which
+ * forecloses rollback. The paseo home is already the unit the pid lock isolates on.
+ */
+export const SLOT_CURRENT = "current";
+export const SLOT_PREVIOUS = "previous";
+export const SLOT_VERSIONS_DIR = "versions";
+export const UPDATE_STATE_FILE = "update-state.json";
+export function slotsRoot(paseoHome) {
+    return path.join(paseoHome, SLOT_VERSIONS_DIR);
+}
+export function slotPath(paseoHome, version) {
+    return path.join(slotsRoot(paseoHome), version);
+}
+export function currentLinkPath(paseoHome) {
+    return path.join(paseoHome, SLOT_CURRENT);
+}
+export function previousLinkPath(paseoHome) {
+    return path.join(paseoHome, SLOT_PREVIOUS);
+}
+export function updateStatePath(paseoHome) {
+    return path.join(paseoHome, UPDATE_STATE_FILE);
+}
+/**
+ * Worker entry candidates inside an installed slot.
+ *
+ * Two layouts, because npm does not guarantee where a transitive dependency lands:
+ * `@hyperdrive.bot/fleet-server` is nested under the CLI in the layout observed on
+ * this box, but npm is free to hoist it to the top of the prefix instead. Both are
+ * checked rather than assumed.
+ *
+ * The `dist/server/server/` doubling is real: the published tarball ships
+ * `dist/server/server/daemon-worker.js`, verified against the installed 0.3.3 tree.
+ */
+export function slotWorkerEntryCandidates(slotRoot) {
+    const modules = path.join(slotRoot, "lib", "node_modules");
+    const tail = path.join("dist", "server", "server", "daemon-worker.js");
+    return [
+        // Nested under the CLI (observed layout for `npm i @hyperdrive.bot/fleet-cli`).
+        path.join(modules, "@hyperdrive.bot", "fleet-cli", "node_modules", "@hyperdrive.bot", "fleet-server", tail),
+        // Hoisted to the prefix root.
+        path.join(modules, "@hyperdrive.bot", "fleet-server", tail),
+    ];
+}
+/**
+ * The worker entry for the active slot, or null when no usable slot is installed.
+ *
+ * Returning null is the normal case for an npm-global or checkout install, and the
+ * caller must fall back to its own resolution so those installs behave exactly as
+ * they did before slots existed.
+ */
+export function resolveSlotWorkerEntry(paseoHome) {
+    const link = currentLinkPath(paseoHome);
+    // `existsSync` follows symlinks, so a dangling `current` (mid-swap, or a rollback
+    // that removed the target) correctly reports false and we fall back.
+    if (!existsSync(link)) {
+        return null;
+    }
+    try {
+        if (!statSync(link).isDirectory()) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    for (const candidate of slotWorkerEntryCandidates(link)) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/** Version a slot symlink points at, or null when absent or dangling. */
+export function readSlotVersion(paseoHome, link) {
+    const linkPath = path.join(paseoHome, link);
+    try {
+        const target = readlinkSync(linkPath);
+        const base = path.basename(target);
+        return base.length > 0 ? base : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=slots.js.map

package/dist/server/server/update/state.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Durable state for daemon self-update, at `<paseoHome>/update-state.json`.
+ *
+ * The important field is `pinned`. A version that failed to boot is recorded here
+ * so it is never retried automatically. Without it, a bad release plus an update
+ * loop is a restart storm that survives supervisor backoff, because each attempt
+ * looks like a fresh install rather than a repeat of a known-bad one.
+ */
+export interface UpdateState {
+    /** Last version whose install+boot failed. Never auto-installed again. */
+    pinned: string | null;
+    /** Why it was pinned, for the operator reading this file at 3am. */
+    pinnedReason: string | null;
+    /** Version installed by the most recent successful update. */
+    lastInstalled: string | null;
+    /** Epoch ms of the last registry check, used to honour the poll interval. */
+    lastCheckedAt: number | null;
+    /** Newest version seen on the channel at that check. */
+    lastSeenVersion: string | null;
+    /**
+     * Stable per-install id, used as the staged-rollout bucket seed so a given
+     * machine lands in the same percentile on every release rather than
+     * re-rolling the dice and updating on day one half the time.
+     */
+    installId: string | null;
+}
+export declare const EMPTY_UPDATE_STATE: UpdateState;
+/** Read state, returning defaults for a missing or unparseable file. */
+export declare function readUpdateState(paseoHome: string): UpdateState;
+/** Merge a patch into state and write it atomically. */
+export declare function writeUpdateState(paseoHome: string, patch: Partial<UpdateState>): UpdateState;
+/** True when this version previously failed and must not be auto-installed. */
+export declare function isPinned(state: UpdateState, version: string): boolean;
+/**
+ * Stable install id, created on first use.
+ *
+ * Not a machine fingerprint on purpose: it only needs to be stable and uniformly
+ * distributed to seed the rollout bucket.
+ */
+export declare function ensureInstallId(paseoHome: string, generate: () => string): string;
+//# sourceMappingURL=state.d.ts.map