opencode-courier 0.2.2 → 0.2.3

package/dist/hub.d.ts

@@ -0,0 +1,325 @@
+import type { Plugin } from "@opencode/plugin";
+import type { Server } from "node:http";
+import { type LaterPorts } from "./later.js";
+import type { Asked, Outcome, Withdrawal } from "./notices.js";
+import type { Permissions, Waiting } from "./relay.js";
+import type { RosterStorage } from "./roster.js";
+import { type Registry } from "./storage.js";
+import type { WebhookConfig, WebhookPorts } from "./webhook.js";
+type Context = Plugin.Context;
+/**
+ * The plugin's process-wide state, in one place. OpenCode sets the plugin up once per location
+ * (project or worktree), all in one process, and after an update loads the new copy of the package
+ * next to the old one until the old one unloads; so the state every instance shares lives on
+ * `globalThis`, outside the module graph, and this is the only module that puts it there.
+ *
+ * The hub is versioned by `HUB_VERSION`, not by the package's version: copies whose hub has the
+ * same shape share one hub, however far apart their releases, and only a change to the hub's shape
+ * (the ports a `Member` carries included) or to the meaning of one of its fields bumps it. An
+ * optional field that a copy without it gets along without, such as `Member.location` or
+ * `Scheduler.running`, is added without a bump while no release has the hub (the latest is 0.2.2).
+ *
+ * Version skew: a copy that finds a hub of another version under `opencode-courier.hub` logs that
+ * once and runs its own hub under `opencode-courier.hub@<version>`. Whatever its version, a hub
+ * takes the claim sets and the other shared objects of the copies before the hub from their own
+ * keys (`opencode-courier.claimed`, `.watched`, `.forms`, `.questions`, `.receiver`, `.locations`),
+ * making each when it is missing, so every copy in the process, with a hub or without, claims an
+ * event or a delivery in the same set, and an old and a new copy never both act on it. Those keys'
+ * shapes and meanings are therefore fixed: a hub version that needs other ones makes new keys, and
+ * keeps claiming in the old ones too while a copy that uses them may still be loaded. `members` is
+ * the one thing each version keeps to itself, so a job a hub runs once for its members runs once
+ * per hub version, and still claims what it acts on in the shared sets, which keep it from acting
+ * twice.
+ */
+export declare const HUB_VERSION = 1;
+/** The key of the hub; a copy that finds another version there keeps its own under `${HUB_KEY}@<version>`. */
+export declare const HUB_KEY = "opencode-courier.hub";
+/**
+ * A question this process knows: one whose call waits (`call`), or one whose call was cut off,
+ * which is answered by message. `link` withdraws the top session's question call that passes its
+ * answer on, once the question is settled without that call.
+ */
+export interface Question extends Asked {
+    /** The directory of the location the call runs in, whose shutdown withdraws its form. */
+    directory?: string;
+    /** Hands the waiting call the top session's outcome; true once the call has ended with it. */
+    call?: (outcome: Outcome) => Promise<boolean>;
+    link?: (how: Withdrawal) => void;
+    /** Storing the question and telling the top session, while that is under way. */
+    relaying?: Promise<boolean>;
+    /** Working out what became of it once its call ended without the top session's answer. */
+    settling?: Promise<void>;
+}
+/**
+ * The relay's timings, carried by its ports: how long a question cut off by a closing location
+ * waits before an instance still loaded tells its top session, how long an answer waits for another
+ * one to it that is still being passed on, how long what follows a call's end waits for the notice
+ * of the question to go out, and how long a dismissal is held to see whether the location is
+ * shutting down.
+ */
+export interface QuestionTiming {
+    readonly closingGraceMs: number;
+    readonly passingWaitMs: number;
+    readonly relayWaitMs: number;
+    readonly dismissalGraceMs: number;
+}
+export interface QuestionPorts {
+    readonly storage: RosterStorage;
+    readonly session: Pick<Context["session"], "synthetic">;
+    /** The directory of the instance's location. */
+    readonly directory: string;
+    /** The clock, in epoch milliseconds, as OpenCode's location shutdowns are recorded. */
+    readonly now: () => number;
+    readonly timing: QuestionTiming;
+    readonly newID: () => string;
+    readonly log: (message: string) => void;
+}
+export interface WatchPorts {
+    readonly storage: RosterStorage;
+    readonly session: Pick<Context["session"], "synthetic">;
+    readonly event: Pick<Context["event"], "subscribe">;
+    /**
+     * The permission domains of every loaded location, whose pending requests are relayed when the
+     * watcher (re)subscribes: one watcher serves them all, and an isolated child's are in its worktree's.
+     */
+    readonly permissions: () => Iterable<Pick<Context["permission"], "list">>;
+    /** The clock a location shutdown is recorded by: the question relay's, which judges it. */
+    readonly now: () => number;
+    readonly log: (message: string) => void;
+}
+/**
+ * What every plugin instance in the process shares. A hub follows OpenCode's events through two of
+ * its members, one a standby, and a copy of another hub version, or one from before the hub, follows
+ * them too, all sent the same events; so an event id is claimed synchronously and handled once.
+ * `waiting` holds the permission requests a session was told about and has not answered;
+ * `answered`, requests answered before anyone was told, so a notice whose roster lookup was
+ * overtaken by the answer is not sent. `forms` does the same for the forms of spawned sessions.
+ */
+export interface WatchState {
+    readonly seen: Set<string>;
+    readonly waiting: Waiting;
+    readonly answered: Set<string>;
+    readonly forms: FormsTold;
+}
+/** The forms sessions were told about, kept apart from the permission requests. */
+export interface FormsTold {
+    /** Forms still shown whose notice went out, or is going out: the notice's delivery. */
+    readonly told: Map<string, Promise<unknown>>;
+    /** Forms settled before anyone was told, so a notice whose roster lookup was overtaken is not sent. */
+    readonly settled: Set<string>;
+}
+/**
+ * The webhook receiver, one per process: every instance configured with a `webhook` option joins
+ * `instances`, the first one starts the server, and the last one to unload stops it.
+ */
+export interface Receiver {
+    readonly config: WebhookConfig;
+    readonly instances: Set<WebhookPorts>;
+    readonly server: Promise<Server | undefined>;
+}
+/** The current receiver, if any, and the previous one while it closes, which a new one waits for. */
+export interface Receivers {
+    current?: Receiver;
+    closing?: Promise<void>;
+}
+/**
+ * The question relay's state, shared by every instance, since a child and the session it asks can
+ * be in different locations: the questions told to a top session and not yet settled, the cut-off
+ * ones whose top session has been told so, and the question calls waiting for their form to be shown.
+ */
+export interface QuestionState {
+    readonly questions: Map<string, Question>;
+    readonly noticed: Set<string>;
+    readonly shown: Map<string, () => void>;
+    /** The questions whose answer is being passed on, each until that is done, and those whose answer went out. */
+    readonly passing: Map<string, Promise<unknown>>;
+    readonly answered: Set<string>;
+    /**
+     * The ports of the loaded instances, of every copy of the plugin. A release before the hub picks
+     * one here to tell a cut-off question through, so every copy keeps it filled; this copy reads its
+     * hub's members, and this only for an instance of another copy, when it has none.
+     */
+    readonly loaded: Set<QuestionPorts>;
+    /** How many instances follow OpenCode's events now, and whether any has since the process started. */
+    following: number;
+    followed: boolean;
+    /**
+     * When OpenCode last reported each location shutting down (`location.shutdown`), by directory
+     * in epoch milliseconds by the clock of the watcher that saw it; under `""` when the event named no location.
+     */
+    readonly shutdowns: Map<string, number>;
+    /** Woken when a location shuts down or an instance unloads: dismissals held to see whether one follows. */
+    readonly closingWaiters: Set<() => void>;
+}
+/**
+ * A loaded plugin instance: its location's directory and permission domain, and the ports a job
+ * run once for the whole process would run it through.
+ */
+export interface Member {
+    readonly directory: string;
+    /**
+     * The location OpenCode set the instance up with, the very object the instance's Effect half is
+     * handed too, which finds its member by it (`portsAt`). A member of a copy before it has none.
+     */
+    readonly location?: object;
+    readonly permission: Permissions;
+    readonly later: LaterPorts;
+    readonly watch: WatchPorts;
+    readonly questions: QuestionPorts;
+    readonly log: (message: string) => void;
+}
+/**
+ * A tick under way: the member it runs through, when it started, by the wall clock every member's
+ * `now` reads (the next ticks compare it with another member's), and its end.
+ */
+export interface Tick {
+    readonly member: Member;
+    readonly since: number;
+    /** Settles once the tick has ended, the owner key released if its loop stopped meanwhile; never rejects. */
+    readonly done: Promise<void>;
+}
+/**
+ * The scheduler's loop, one per hub: it runs while the hub has members, and each tick delivers the
+ * due `courier_later` messages through the ports of the member that joined first and is still loaded.
+ */
+export interface Scheduler {
+    /** The loop's interval, while it runs. */
+    timer?: unknown;
+    /**
+     * The tick under way, if any, whichever copy of the plugin started it and whether or not its
+     * member is still loaded. A tick that falls due meanwhile renews the owner key for it, for up to a
+     * minute from its start, and is skipped; past that minute one whose member has left holds up
+     * nothing, and the next tick starts. Optional, since a copy of the same hub version made before it
+     * existed keeps only `ticking`.
+     */
+    running?: Tick;
+    /**
+     * The member the tick under way runs through, if any, set and cleared with `running`, for a copy
+     * that reads only this: a tick that falls due meanwhile is skipped, unless that member has left.
+     */
+    ticking?: Member;
+    /** One tick, by the copy of the plugin that joined last, so a copy loaded after an update runs its own code. */
+    tick?: () => Promise<void>;
+}
+/** How the hub starts and stops the scheduler's loop, and waits before re-reading the owner key; tests pass their own. */
+export interface Timers {
+    readonly every: (run: () => void, ms: number) => unknown;
+    readonly stop: (timer: unknown) => void;
+    readonly wait: (ms: number) => Promise<void>;
+}
+/**
+ * The key in the plugin's storage, shared by every OpenCode server on one data directory, naming
+ * the server whose scheduler delivers the `courier_later` messages: `{ server, at }`, its id and
+ * when it last wrote the key, in epoch milliseconds. Outside `later/`, which the schedulers scan
+ * for messages, those of copies before the key included.
+ */
+export declare const OWNER_KEY = "scheduler/owner";
+/** How long the owner key holds without being renewed; the owner renews it every tick, four times as often. */
+export declare const OWNER_EXPIRY_MS: number;
+/**
+ * How old the owner's own key may be for it to renew the key and deliver at once. An older one,
+ * which it may no longer hold by the time it writes, is taken again like a free one, with the wait.
+ */
+export declare const OWNER_RENEW_MS: number;
+/** The wait between writing the owner key and reading it back, at least `OWNER_WAIT_MS` and up to twice that. */
+export declare const OWNER_WAIT_MS = 500;
+/**
+ * This server's id in the owner key: the same for every copy of the plugin in the process, and
+ * different in every other process, a restart of this one included.
+ */
+export declare const SERVER: string;
+/**
+ * How long an unloading instance waits, before it lets go, for the work it leaves behind: what it
+ * started itself, a tick or an event's notice still under way through it, and on the last leave the
+ * owner key's release.
+ */
+export declare const LEAVE_MS = 2000;
+/** How many subscriptions to OpenCode's events a hub keeps, each through another member: one, and a standby. */
+export declare const WATCHERS = 2;
+/** One of the hub's subscriptions to OpenCode's events: the member whose ports it runs through, and how it ends. */
+export interface Watcher {
+    readonly member: Member;
+    readonly stop: AbortController;
+    /** Settles once the subscription has ended, after `stop`: after the event it is handling, not the stream's close. */
+    readonly done: Promise<void>;
+}
+export interface Hub {
+    readonly version: typeof HUB_VERSION;
+    /** The instances loaded now, in the order they joined. */
+    readonly members: Set<Member>;
+    readonly scheduler: Scheduler;
+    /**
+     * The hub's subscriptions to OpenCode's events, each through another member: two while two members
+     * are loaded, so one is always connected when the other's member leaves.
+     */
+    readonly watchers: Watcher[];
+    /**
+     * Starts a subscription through a member, by the copy of the plugin that set it last; until one
+     * has, the hub follows no events.
+     */
+    subscribe?: (member: Member) => Watcher;
+    /** The ids of the `courier_later` messages being delivered. */
+    readonly claimed: Set<string>;
+    /** The events handled, and the permission requests a session was told about or that were answered first. */
+    readonly watched: Omit<WatchState, "forms">;
+    /** The forms sessions were told about, and those settled first. */
+    readonly forms: FormsTold;
+    /**
+     * The permission domain of every loaded instance, by instance. OpenCode keeps a request where its
+     * session runs, so a request of an isolated child is answered through the instance loaded in its worktree.
+     */
+    readonly locations: Map<object, Permissions>;
+    readonly receivers: Receivers;
+    readonly questions: QuestionState;
+    /** Whether the hub of another version found under `HUB_KEY` has been logged. */
+    skewLogged: boolean;
+}
+/** A hub, as `open` finds or makes it, and how instances join it. */
+export interface Opened {
+    readonly hub: Hub;
+    /**
+     * Adds a loaded instance to the hub and its permission domain to `locations`; returns its leave,
+     * which takes both out again. The first instance to join logs a hub of another version found
+     * under `HUB_KEY`. An instance joining a hub without members starts the scheduler's loop, with a
+     * tick at once; the last one to leave stops it. An instance joining while the hub has fewer than
+     * `WATCHERS` subscriptions to OpenCode's events starts one through itself; when one leaves that
+     * has one, another member without one starts its replacement before it ends. The last leave
+     * settles once the scheduler's owner key is released, after the tick under way, whichever copy
+     * started it. Every leave first waits for the work its member leaves behind: what was handed to
+     * `track`, a tick under way through it, and the subscription it ran, which ends after the event
+     * it is handling; all of it, the release included, for up to `LEAVE_MS`. The question relay's
+     * own work is not waited for: it outlives the instance on purpose.
+     */
+    readonly join: (member: Member) => () => Promise<void>;
+    /** Hands the hub work a member started, which its leave waits for; the member's own background work. */
+    readonly track: (member: Member, work: Promise<unknown>) => void;
+}
+/**
+ * Finds or makes this copy's hub in `registry`: the one under `HUB_KEY`, or its own under a
+ * versioned key when a hub of another version holds that. Either way, its claim sets and shared
+ * objects are the ones under the keys of the copies before the hub, made when missing.
+ */
+export declare function open(registry: Registry, timers?: Timers, server?: string): Opened;
+/** This copy's hub, in the process. */
+export declare const hub: Hub;
+/** Joins this copy's hub; see `Opened.join`. */
+export declare const join: (member: Member) => () => Promise<void>;
+/** Hands this copy's hub work a member started; see `Opened.track`. */
+export declare const track: (member: Member, work: Promise<unknown>) => void;
+/** The member of this copy's hub set up with `location` that joined last, while it is loaded. */
+export declare function memberAt(location: object): Member | undefined;
+/**
+ * The question ports of the member that has just joined at `location`, the newest there, for as long
+ * as it stays loaded: resolved once, so an instance joining later at the same location, while this
+ * one is still loaded, does not take its place.
+ */
+export declare function portsAt(location: object): () => QuestionPorts | undefined;
+/** The permission domains of the loaded instances. */
+export declare const permissions: () => MapIterator<Permissions>;
+/**
+ * For tests: forgets every remembered id and the question relay's state, the relay's loaded
+ * instances and its count of watchers included. The hub's members, the locations and the webhook
+ * receiver are left alone; leaving and unloading take them out.
+ */
+export declare function resetHub(): void;
+export {};

package/dist/hub.js

@@ -0,0 +1,340 @@
+import { randomInt } from "node:crypto";
+import { hostname } from "node:os";
+import { num, obj, str } from "./json.js";
+import { deliverDue, TICK_MS } from "./later.js";
+import { processWide } from "./storage.js";
+/**
+ * The plugin's process-wide state, in one place. OpenCode sets the plugin up once per location
+ * (project or worktree), all in one process, and after an update loads the new copy of the package
+ * next to the old one until the old one unloads; so the state every instance shares lives on
+ * `globalThis`, outside the module graph, and this is the only module that puts it there.
+ *
+ * The hub is versioned by `HUB_VERSION`, not by the package's version: copies whose hub has the
+ * same shape share one hub, however far apart their releases, and only a change to the hub's shape
+ * (the ports a `Member` carries included) or to the meaning of one of its fields bumps it. An
+ * optional field that a copy without it gets along without, such as `Member.location` or
+ * `Scheduler.running`, is added without a bump while no release has the hub (the latest is 0.2.2).
+ *
+ * Version skew: a copy that finds a hub of another version under `opencode-courier.hub` logs that
+ * once and runs its own hub under `opencode-courier.hub@<version>`. Whatever its version, a hub
+ * takes the claim sets and the other shared objects of the copies before the hub from their own
+ * keys (`opencode-courier.claimed`, `.watched`, `.forms`, `.questions`, `.receiver`, `.locations`),
+ * making each when it is missing, so every copy in the process, with a hub or without, claims an
+ * event or a delivery in the same set, and an old and a new copy never both act on it. Those keys'
+ * shapes and meanings are therefore fixed: a hub version that needs other ones makes new keys, and
+ * keeps claiming in the old ones too while a copy that uses them may still be loaded. `members` is
+ * the one thing each version keeps to itself, so a job a hub runs once for its members runs once
+ * per hub version, and still claims what it acts on in the shared sets, which keep it from acting
+ * twice.
+ */
+export const HUB_VERSION = 1;
+/** The key of the hub; a copy that finds another version there keeps its own under `${HUB_KEY}@<version>`. */
+export const HUB_KEY = "opencode-courier.hub";
+const realTimers = {
+    every: (run, ms) => setInterval(run, ms),
+    stop: (timer) => clearInterval(timer),
+    wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/**
+ * The key in the plugin's storage, shared by every OpenCode server on one data directory, naming
+ * the server whose scheduler delivers the `courier_later` messages: `{ server, at }`, its id and
+ * when it last wrote the key, in epoch milliseconds. Outside `later/`, which the schedulers scan
+ * for messages, those of copies before the key included.
+ */
+export const OWNER_KEY = "scheduler/owner";
+/** How long the owner key holds without being renewed; the owner renews it every tick, four times as often. */
+export const OWNER_EXPIRY_MS = 4 * TICK_MS;
+/**
+ * How old the owner's own key may be for it to renew the key and deliver at once. An older one,
+ * which it may no longer hold by the time it writes, is taken again like a free one, with the wait.
+ */
+export const OWNER_RENEW_MS = OWNER_EXPIRY_MS / 2;
+/** The wait between writing the owner key and reading it back, at least `OWNER_WAIT_MS` and up to twice that. */
+export const OWNER_WAIT_MS = 500;
+/**
+ * This server's id in the owner key: the same for every copy of the plugin in the process, and
+ * different in every other process, a restart of this one included.
+ */
+export const SERVER = `${hostname()}:${process.pid}:${performance.timeOrigin}`;
+async function readOwner(ports) {
+    const value = obj(await ports.storage.get(OWNER_KEY));
+    const server = str(value.server);
+    const at = num(value.at);
+    return server !== undefined && at !== undefined ? { server, at } : undefined;
+}
+/**
+ * How long an unloading instance waits, before it lets go, for the work it leaves behind: what it
+ * started itself, a tick or an event's notice still under way through it, and on the last leave the
+ * owner key's release.
+ */
+export const LEAVE_MS = 2_000;
+/** Whether a key written at `at` still holds at `now`; one from the future, after the clock went back, holds as long. */
+const holds = (at, now, ms) => Math.abs(now - at) < ms;
+/** How many subscriptions to OpenCode's events a hub keeps, each through another member: one, and a standby. */
+export const WATCHERS = 2;
+/**
+ * Finds or makes this copy's hub in `registry`: the one under `HUB_KEY`, or its own under a
+ * versioned key when a hub of another version holds that. Either way, its claim sets and shared
+ * objects are the ones under the keys of the copies before the hub, made when missing.
+ */
+export function open(registry, timers = realTimers, server = SERVER) {
+    const shared = (name, create) => processWide(`opencode-courier.${name}`, create, registry);
+    const questionState = () => {
+        // Field by field, since a copy before the hub may have made it without the fields added later.
+        const state = shared("questions", () => ({}));
+        state.questions ??= new Map();
+        state.noticed ??= new Set();
+        state.shown ??= new Map();
+        state.passing ??= new Map();
+        state.answered ??= new Set();
+        state.loaded ??= new Set();
+        state.following ??= 0;
+        state.followed ??= false;
+        state.shutdowns ??= new Map();
+        state.closingWaiters ??= new Set();
+        return state;
+    };
+    const create = () => ({
+        version: HUB_VERSION,
+        members: new Set(),
+        scheduler: {},
+        watchers: [],
+        claimed: shared("claimed", () => new Set()),
+        watched: shared("watched", () => ({ seen: new Set(), waiting: new Set(), answered: new Set() })),
+        forms: shared("forms", () => ({ told: new Map(), settled: new Set() })),
+        locations: shared("locations", () => new Map()),
+        receivers: shared("receiver", () => ({})),
+        questions: questionState(),
+        skewLogged: false,
+    });
+    const found = registry[Symbol.for(HUB_KEY)];
+    // The version of the hub of another copy found under `HUB_KEY`, if one is there.
+    const skew = found != null && found.version !== HUB_VERSION ? { version: found.version } : undefined;
+    const hub = processWide(skew ? `${HUB_KEY}@${HUB_VERSION}` : HUB_KEY, create, registry);
+    /**
+     * Whether this server holds the owner key, taking or renewing it through `ports`. Its own fresh
+     * key is renewed. A free one, an expired one, or its own after a stall, is written and read back
+     * after a random wait: of two servers taking it at once, the one that wrote last holds it.
+     */
+    const own = async (ports) => {
+        const held = await readOwner(ports);
+        const now = ports.now();
+        if (held && held.server !== server && holds(held.at, now, OWNER_EXPIRY_MS))
+            return false;
+        await ports.storage.set(OWNER_KEY, { server, at: now });
+        if (fresh(held, now))
+            return true;
+        await timers.wait(randomInt(OWNER_WAIT_MS, 2 * OWNER_WAIT_MS));
+        return (await readOwner(ports))?.server === server;
+    };
+    /** Whether `held` is this server's key, recent enough to renew without reading it back. */
+    const fresh = (held, now) => held?.server === server && holds(held.at, now, OWNER_RENEW_MS);
+    /** Renews the owner key if this server holds it fresh: what a tick does, for a tick still delivering. */
+    const renew = async (ports) => {
+        const now = ports.now();
+        if (fresh(await readOwner(ports), now))
+            await ports.storage.set(OWNER_KEY, { server, at: now });
+    };
+    /** Whether a hub of another version in the process has instances, so its loop, under the same server id, still holds the key. */
+    const othersRunning = () => Object.getOwnPropertySymbols(registry).some((key) => {
+        const other = registry[key];
+        const name = key.description ?? "";
+        return other !== hub && (name === HUB_KEY || name.startsWith(`${HUB_KEY}@`)) && Number(other?.members?.size) > 0;
+    });
+    /**
+     * Removes the owner key if this server holds it, so another server takes over at its next tick:
+     * once the loop has stopped and no tick is under way, whichever copy started it (a tick whose loop
+     * stopped releases it as it ends), and while no hub of another version in the process still runs a
+     * loop under the same id.
+     */
+    const release = async (ports) => {
+        const scheduler = hub.scheduler;
+        const idle = () => scheduler.timer === undefined && !scheduler.running && !scheduler.ticking && !othersRunning();
+        if (idle() && (await readOwner(ports))?.server === server && idle())
+            await ports.storage.remove(OWNER_KEY);
+    };
+    /**
+     * Whether the tick under way, kept on the hub by whichever copy started it, still holds up the
+     * next: within a minute of its start it does, and the key is renewed for it, through the first
+     * member still loaded, since a delivery may run longer than the key holds; past the minute it is
+     * taken to hang, and holds up the next only while its member is still loaded. A tick of a copy that
+     * keeps only `ticking` holds it up while its member is loaded, without renewing the key.
+     */
+    const underWay = () => {
+        const { running, ticking } = hub.scheduler;
+        if (!running)
+            return ticking !== undefined && hub.members.has(ticking);
+        const first = hub.members.values().next().value;
+        if (first && holds(running.since, first.later.now(), OWNER_EXPIRY_MS)) {
+            void renew(first.later).catch((error) => first.log(`courier_later scheduler: ${String(error)}`));
+            return true;
+        }
+        return hub.members.has(running.member);
+    };
+    // One tick, through the first member still loaded, by the server holding the owner key. The claim
+    // on each delivery stays, as the second line of defence against a copy before the hub, which runs
+    // its own interval until it unloads, and has no owner key.
+    const tick = async () => {
+        const scheduler = hub.scheduler;
+        if (underWay())
+            return;
+        const owner = hub.members.values().next().value;
+        if (!owner)
+            return;
+        let since;
+        try {
+            since = owner.later.now();
+        }
+        catch (error) {
+            owner.log(`courier_later scheduler: ${String(error)}`);
+            return;
+        }
+        let end = () => { };
+        const run = { member: owner, since, done: new Promise((resolve) => (end = resolve)) };
+        scheduler.running = run;
+        scheduler.ticking = owner;
+        // `done` settles however the tick ends, and the key is given back, a log that throws included:
+        // leaves wait for it. A log that throws is not logged again; there is nowhere left to tell.
+        const tell = (message) => {
+            try {
+                owner.log(message);
+            }
+            catch { }
+        };
+        try {
+            if ((await own(owner.later)) && scheduler.timer !== undefined && hub.members.has(owner))
+                await deliverDue(owner.later, hub.claimed);
+        }
+        catch (error) {
+            tell(`courier_later scheduler: ${String(error)}`);
+        }
+        finally {
+            // A tick past its minute may have been followed by another, whose record stays.
+            if (scheduler.running === run) {
+                scheduler.running = undefined;
+                scheduler.ticking = undefined;
+            }
+        }
+        // A loop stopped meanwhile, its members gone, gives back the key this tick may have written.
+        if (scheduler.timer === undefined)
+            await release(owner.later).catch((error) => tell(`courier_later scheduler: owner key not released: ${String(error)}`));
+        end();
+    };
+    // Subscriptions through the earliest members without one, the longest loaded, until there are
+    // `WATCHERS`; never through `leaving`.
+    const watch = (leaving) => {
+        const watching = new Set(hub.watchers.map((watcher) => watcher.member));
+        for (const member of hub.members) {
+            if (hub.watchers.length >= WATCHERS || !hub.subscribe)
+                return;
+            if (member !== leaving && !watching.has(member))
+                hub.watchers.push(hub.subscribe(member));
+        }
+    };
+    // The work each member of this copy started and handed over, until it settles.
+    const work = new WeakMap();
+    const track = (member, started) => {
+        const set = work.get(member) ?? new Set();
+        work.set(member, set);
+        const settled = started.catch(() => { }).finally(() => set.delete(settled));
+        set.add(settled);
+    };
+    const join = (member) => {
+        if (skew && !hub.skewLogged) {
+            hub.skewLogged = true;
+            member.log(`courier: another copy of the plugin with hub version ${String(skew.version)} has been loaded in this process; ` +
+                `this copy (hub version ${HUB_VERSION}) keeps its own under ${HUB_KEY}@${HUB_VERSION} and shares the claim sets with it`);
+        }
+        hub.members.add(member);
+        hub.locations.set(member, member.permission);
+        const scheduler = hub.scheduler;
+        scheduler.tick = tick;
+        if (scheduler.timer === undefined) {
+            scheduler.timer = timers.every(() => void hub.scheduler.tick?.(), TICK_MS);
+            void tick();
+        }
+        watch();
+        return () => {
+            hub.members.delete(member);
+            hub.locations.delete(member);
+            // What this member leaves behind: the work it handed over, and a tick under way through it,
+            // which keeps using its storage and session until it ends.
+            const behind = [...(work.get(member) ?? [])];
+            if (scheduler.running?.member === member)
+                behind.push(scheduler.running.done);
+            // The other subscription, already connected, follows the events meanwhile; this one is
+            // replaced before it ends, so the question relay's count of watchers never drops to none.
+            // It ends once the event it is handling, whose notice may be going out, has been handled.
+            const index = hub.watchers.findIndex((watcher) => watcher.member === member);
+            if (index >= 0) {
+                const [leaving] = hub.watchers.splice(index, 1);
+                watch(member);
+                leaving.stop.abort();
+                behind.push(leaving.done);
+            }
+            if (hub.members.size === 0 && scheduler.timer !== undefined) {
+                timers.stop(scheduler.timer);
+                scheduler.timer = undefined;
+                // After the tick under way, whichever copy started it, which may be writing the key.
+                behind.push((async () => {
+                    await scheduler.running?.done;
+                    await release(member.later);
+                })().catch((error) => member.log(`courier_later scheduler: owner key not released: ${String(error)}`)));
+            }
+            if (behind.length === 0)
+                return Promise.resolve();
+            return Promise.race([Promise.allSettled(behind).then(() => { }), timers.wait(LEAVE_MS)]);
+        };
+    };
+    return { hub, join, track };
+}
+const opened = open(globalThis);
+/** This copy's hub, in the process. */
+export const hub = opened.hub;
+/** Joins this copy's hub; see `Opened.join`. */
+export const join = opened.join;
+/** Hands this copy's hub work a member started; see `Opened.track`. */
+export const track = opened.track;
+/** The member of this copy's hub set up with `location` that joined last, while it is loaded. */
+export function memberAt(location) {
+    let found;
+    for (const member of hub.members)
+        if (member.location === location)
+            found = member;
+    return found;
+}
+/**
+ * The question ports of the member that has just joined at `location`, the newest there, for as long
+ * as it stays loaded: resolved once, so an instance joining later at the same location, while this
+ * one is still loaded, does not take its place.
+ */
+export function portsAt(location) {
+    const own = memberAt(location);
+    return () => (own && hub.members.has(own) ? own.questions : undefined);
+}
+/** The permission domains of the loaded instances. */
+export const permissions = () => hub.locations.values();
+/**
+ * For tests: forgets every remembered id and the question relay's state, the relay's loaded
+ * instances and its count of watchers included. The hub's members, the locations and the webhook
+ * receiver are left alone; leaving and unloading take them out.
+ */
+export function resetHub() {
+    hub.claimed.clear();
+    hub.watched.seen.clear();
+    hub.watched.waiting.clear();
+    hub.watched.answered.clear();
+    hub.forms.told.clear();
+    hub.forms.settled.clear();
+    const questions = hub.questions;
+    questions.questions.clear();
+    questions.noticed.clear();
+    questions.shown.clear();
+    questions.passing.clear();
+    questions.answered.clear();
+    questions.loaded.clear();
+    questions.following = 0;
+    questions.followed = false;
+    questions.shutdowns.clear();
+    questions.closingWaiters.clear();
+}