@aywengo/mercury-fleet 0.0.1-bootstrap

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to **Mercury Fleet** are recorded here. The host product
+has its own [`../CHANGELOG.md`](../CHANGELOG.md).
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - not yet published
+
+First published Fleet release, **pending**: `@aywengo/mercury-fleet` is still not on the npm
+registry, so nothing here is installable yet. Fleet runs from a source checkout with
+`npm run fleet`. See [the release notes](../docs/releases/fleet/0.1.0.md) for what publishing
+still requires.
+
+The one packaging change since `0.1.0-rc1` matters more than it looks: the package now ships
+compiled JavaScript in `dist/` with `bin` pointing at `dist/cli.js`. It previously shipped
+TypeScript sources with `bin` pointing at `cli.ts`, and Node refuses to strip types from a file
+under `node_modules`, so the package would have installed cleanly and failed on its first command.
+
+### Changed
+
+- Ship `dist/*.js` instead of `*.ts`, so the installed package runs. `bin` now points at
+  `dist/cli.js`; `files` now ships `dist/`.
+- The package description names what Fleet actually does. It said "Phase 0, no dispatch" long
+  after dispatch, routing, reconciliation, event mirroring and the metrics rollup had landed, and
+  that string is what npm renders on the package page.
+
+## [0.1.0-rc1] - 2026-09-06
+
+Recorded here as a version but **never published**: `@aywengo/mercury-fleet`
+is not on the npm registry (404), there is no `fleet-v0.1.0-rc1` tag and no GitHub Release for it, so
+`npm install -g @aywengo/mercury-fleet` does not work. Fleet can only be run from a source checkout
+(`npm run fleet`). See [`../docs/releases/fleet/0.1.0-rc1.md`](../docs/releases/fleet/0.1.0-rc1.md).
+
+### Added
+
+- Host registry and probe (`fleet hosts`, `fleet probe --watch`).
+- `fleet serve` HTTP API and systemd unit.
+- Credential file (mode `0600`); names travel on the command line, never secrets.
+- `GET /healthz` reports `{ ok, ts, product: "fleet", version }`.
+- `fleet --version` prints `mercury-fleet <version>`.
+- Run dispatch: submission records a binding that survives the process that made it, and the same
+  client token never produces a second child Run.
+- The reconciliation sweep. A child Fleet cannot reach yields `UNKNOWN`, never `FAILED`.
+- Event mirroring, metadata-only by default, with paging that resumes where it stopped.
+- Routing across registered hosts, and forwarding of input, cancel and retry.
+- `GET /metrics`, a Prometheus rollup that merges hosts into one HELP/TYPE block per metric.
+
+### Not included
+
+- Moving a Run between hosts. One Run, one host, for life.
+- `mercuryctl` (separate, unreleased product).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Melnyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# Fleet
+
+Fleet manages several independent Mercury instances from one place. It is a federation layer: it talks to
+each Mercury over its public HTTP API and never touches a Mercury database or imports Mercury code.
+
+Design: [`docs/fleet-design.md`](../docs/fleet-design.md). All six build phases are shipped: registry and
+probe, dispatch, reconciliation, event aggregation, routing, interaction, and the metrics rollup.
+
+Two surfaces, deliberately different:
+
+- **`fleet` (this CLI)** — the host registry, probing, and credential inspection. Local, interactive, no
+  network service of its own.
+- **`fleet serve` (the service)** — everything that has to outlive the person who started it: submitting
+  Runs, routing them, reconciling their state, aggregating events, and the Prometheus rollup. See
+  [Service](#service) below.
+
+Version `FLEET_VERSION` lives in [`version.ts`](version.ts) and must match
+[`package.json`](package.json). Changelog: [`CHANGELOG.md`](CHANGELOG.md).
+`fleet --version` prints `mercury-fleet <version>`. `GET /healthz` includes
+`product: "fleet"` and that same version.
+
+## Quick start
+
+```bash
+# 1. Child credentials live in a 0600 file, referenced by name. Never a command-line argument: argv is
+#    world-readable through ps, and Fleet holds a credential for every Mercury it can reach.
+mkdir -p ~/.fleet && chmod 700 ~/.fleet
+cat > ~/.fleet/credentials.json <<'JSON'
+{ "mac-studio": "<token from that host's MERCURY_API_TOKENS>" }
+JSON
+chmod 600 ~/.fleet/credentials.json
+
+# 2. Register hosts and look at them.
+npm run fleet -- hosts add mac-studio --url https://studio.lan:3000 --credential mac-studio
+npm run fleet -- hosts list --live
+```
+
+```
+ID         STATE      SEEN  WORKERS  RUNS  QUEUE  AGENTS  URL
+mac-studio up         0s    1        2     0      5       https://studio.lan:3000
+box-lan-2  auth-fail  0s    0        0     3      -       http://box2.lan:3000
+    box-lan-2: HTTP 401 from /api/agents: the host is reachable but this credential was rejected.
+box-lan-3  down       4m    -        -     -      -       http://box3.lan:3000
+```
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `fleet hosts add <id> --url <base> --credential <ref> [--label k=v] [--path <abs>] [--disabled]` | Register a host. `--credential` names a ref; the secret is never an argument. |
+| `fleet hosts list [--json] [--live]` | Show hosts with their last probe. `--live` probes first. |
+| `fleet hosts probe [<id>] [--json]` | Probe now. Exits non-zero if the host is unusable, so it composes in a readiness check. |
+| `fleet hosts enable\|disable <id>` | Include or exclude a host from sweeps. |
+| `fleet hosts rm <id>` | Forget a host and its cached probe. |
+| `fleet probe --watch` | Sweep every enabled host on `FLEET_PROBE_INTERVAL_MS` until interrupted. |
+| `fleet credentials list` | Credential **names** only. Values are never printed by any command. |
+
+## What each state means
+
+The states are deliberately not collapsed into up/down. Each one sends the operator somewhere different,
+and a probe that reports "down" for a host that is healthy but rejecting our token wastes the operator's
+time on the wrong machine.
+
+| State | Means | Fix |
+| --- | --- | --- |
+| `up` | Reachable, queue configured, credential accepted. | — |
+| `auth-fail` | Host is fine. Our credential is not. | Check the ref in the credential file. |
+| `no-worker` | API answers, but its queue is not configured, so it executes nothing. | Start that host's worker. |
+| `down` | Nothing listening. | Host, port, or `MERCURY_BIND_HOST`. |
+| `timeout` | Something answered too slowly to trust. | Load, or a half-dead process. |
+| `not-mercury` | A server is there; it is not a Mercury API. | Wrong port or URL. |
+| `http-error` | Unexpected status from a Mercury endpoint. | Check that host's logs. |
+| `never-probed` | Registered, not swept yet. | `fleet hosts probe`. |
+
+## Configuration
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `FLEET_DB` | `fleet.db` | Fleet's own SQLite database, separate from every Mercury's. |
+| `FLEET_CREDENTIALS_FILE` | `~/.fleet/credentials.json` | Must be mode `0600`; Fleet refuses otherwise. |
+| `FLEET_PROBE_INTERVAL_MS` | `15000` | Sweep interval for `probe --watch`. |
+| `FLEET_PROBE_TIMEOUT_MS` | `5000` | Per-request timeout. A hung host must not stall the sweep. |
+| `FLEET_ALLOW_INSECURE_CREDENTIALS` | unset | `1` bypasses the mode check. For filesystems that cannot do `0600`. |
+
+> The default is laptop-shaped on purpose, for development. Fleet runs as a **service**
+> ([`docs/fleet-design.md` §15](../docs/fleet-design.md#15-fleet-as-a-service)), and a hardened unit sets
+> `ProtectHome=true`, which cannot read anything under a home directory. A service deployment sets
+> `FLEET_CREDENTIALS_FILE=/etc/fleet/credentials.json` explicitly instead of relying on this default.
+
+## Service
+
+`fleet serve` runs the HTTP API. It binds `127.0.0.1:3100` by default.
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `FLEET_BIND_HOST` | `127.0.0.1` | Bind address. |
+| `FLEET_PORT` | `3100` | Listen port. |
+| `FLEET_API_TOKENS` | unset | `token:owner[:hosts]`, comma-separated. `hosts` scopes a caller to a subset. |
+| `FLEET_ADMIN_TOKEN` | unset | A caller that may see and change every host. |
+| `FLEET_TLS_CERT` / `FLEET_TLS_KEY` | unset | Both or neither. Required to bind beyond loopback. |
+| `FLEET_SWEEP_INTERVAL_MS` | `10000` | How often bindings are reconciled against every host. |
+| `FLEET_STREAM_POLL_MS` | `1000` | Poll interval behind the aggregated Run stream. |
+| `FLEET_REPO_URLS_FILE` | unset | `localPath` → git URL map used by the router. |
+
+**It refuses to start in an unsafe configuration**, rather than serving and leaving discovery to an audit:
+binding beyond loopback without TLS, half a TLS pair, or no caller tokens at all each fail at startup with
+the reason. A Fleet token reaches every Mercury in the fleet, so plaintext on a shared network is not a
+deployment someone should arrive at by omission.
+
+| Endpoint | Does |
+| --- | --- |
+| `GET /healthz` | Liveness, with `product: "fleet"` and the version. Unauthenticated. |
+| `GET /metrics` | Prometheus rollup across hosts, every series relabelled `host="<hostId>"`. |
+| `GET\|POST /fleet/hosts` | List and register hosts. |
+| `POST /fleet/hosts/:id/enable`, `.../disable`, `DELETE /fleet/hosts/:id` | Include or exclude a host from sweeps. |
+| `POST /fleet/hosts/:id/probe` | Probe one host now. |
+| `POST /fleet/runs` | Submit a Run. Name a `host`, or omit it and let the router choose. |
+| `GET /fleet/runs` | Every Run across the fleet, one merged view. |
+| `GET /fleet/runs/:id` | One Run, with its binding and current child state. |
+| `GET /fleet/runs/:id/events`, `.../stream` | Aggregated history and SSE for a fleet Run. |
+| `POST /fleet/runs/:id/input`, `.../cancel`, `.../retry` | Answer, cancel, or retry through Fleet. |
+| `POST /fleet/probe` | Sweep every enabled host. |
+
+Changing the registry — adding, removing, enabling or disabling a host, and sweeping — requires the admin
+token. Reads and Run submission do not, but are scoped: a caller limited to a subset of hosts cannot route
+work onto a hidden host, read another host's Run, or learn another host's queue depth from `/metrics`.
+Routing failures name every host considered and why each was excluded, because "no host matched" without
+reasons is an hour of guessing.
+
+## Two rules this directory is built around
+
+**Nothing here imports from `src/`.** Fleet speaks HTTP so that it can drive a Mercury it did not build.
+`fleet/test/coupling.test.ts` enforces this, and includes tests proving the guard can actually fire.
+
+**`hosts` is truth; everything else is cache.** Probe results live in their own table, so deleting them
+costs one sweep. That split is what makes a Fleet crash cheap: the registry survives, and nothing Fleet
+holds can orphan a Run on a machine nobody is watching.
+
+## Development
+
+```bash
+npm run test:fleet    # 187 tests, no network beyond localhost
+npm run typecheck     # covers fleet/ as well as src/
+```

package/dist/auth.js

@@ -0,0 +1,89 @@
+/**
+ * Caller authentication and the per-caller host allowlist (docs/fleet-design.md sections 9 and 15.3).
+ *
+ * Two credential boundaries exist and must not be conflated:
+ *
+ *   caller -> Fleet    tokens in FLEET_API_TOKENS. Never forwarded to a child.
+ *   Fleet  -> child    credential_ref entries in the credential file.
+ *
+ * The allowlist is authorisation, not a filter. A caller permitted only for `box-lan-2` gets 403 when it
+ * names another host; it does not get a silently narrowed choice, and it does not get to learn whether the
+ * other host exists. Without this, one leaked Fleet token is every Mercury on the LAN, which is the whole
+ * reason section 9 exists.
+ */
+import { timingSafeEqual } from 'node:crypto';
+/**
+ * Parse FLEET_API_TOKENS.
+ *
+ * Format: `token:owner[:hosts]`, entries separated by commas, where hosts is `*` or `host1+host2`.
+ *
+ * Omitting the hosts field grants NOTHING rather than everything. The permissive default would be the
+ * convenient one, and it is the one that turns a single leaked token into fleet-wide access, so the safe
+ * reading is the default and an operator has to type `:*` to widen it.
+ */
+export function parseCallerTokens(raw) {
+    const map = new Map();
+    for (const entry of (raw ?? '').split(',')) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const parts = trimmed.split(':');
+        const [token, owner, hosts] = parts;
+        if (!token || !owner)
+            continue;
+        if (parts.length > 3)
+            continue; // malformed rather than guessed at
+        let allowed;
+        if (hosts === undefined || hosts === '') {
+            allowed = [];
+        }
+        else if (hosts === '*') {
+            allowed = '*';
+        }
+        else {
+            const list = hosts.split('+').map((h) => h.trim()).filter(Boolean);
+            allowed = list.length ? list : [];
+        }
+        map.set(token, { ownerId: owner, isAdmin: false, allowedHosts: allowed });
+    }
+    return {
+        resolve(token) {
+            return map.get(token) ?? null;
+        },
+        owners() {
+            return [...map.values()].map((c) => c.ownerId).sort();
+        },
+        unrestrictedOwners() {
+            return [...map.values()].filter((c) => c.allowedHosts === '*').map((c) => c.ownerId).sort();
+        },
+        secrets() {
+            return [...map.keys()];
+        },
+        get size() {
+            return map.size;
+        },
+    };
+}
+/**
+ * Compare a bearer token against the admin token without leaking content through timing.
+ *
+ * A length mismatch returns false immediately. That discloses the length of the configured secret and
+ * nothing about its content; padding to a common length would risk a comparison that reports equality on a
+ * shared prefix, which is the worse failure.
+ */
+export function isAdminToken(adminToken, token) {
+    if (!adminToken)
+        return false;
+    const a = Buffer.from(adminToken, 'utf8');
+    const b = Buffer.from(token, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+export function hostAllowed(caller, hostId) {
+    if (caller.isAdmin)
+        return true;
+    if (caller.allowedHosts === '*')
+        return true;
+    return caller.allowedHosts.includes(hostId);
+}

package/dist/bindings.js

@@ -0,0 +1,201 @@
+/**
+ * The binding table: which host owns which Run.
+ *
+ * This is Fleet's second piece of truth, and the one the design singles out. Losing `hosts` means Fleet does
+ * not know what to talk to; losing `fleet_runs` means Runs are executing on machines nobody can name. So the
+ * operations here are written so that a binding exists BEFORE Fleet asks a child for anything, and the
+ * child's id is filled in afterwards.
+ */
+/** Status recorded for a Run whose child could not be reached. Distinct from every real child status. */
+export const UNKNOWN = 'UNKNOWN';
+function toBinding(row) {
+    let requested = {};
+    try {
+        requested = JSON.parse(row.requested);
+    }
+    catch {
+        // A corrupt payload must not make the binding unreadable. The binding is the thing that matters; the
+        // echo of the request is a convenience.
+        requested = { _unparseable: true };
+    }
+    return {
+        fleetRunId: row.fleet_run_id,
+        hostId: row.host_id,
+        ownerId: row.owner_id,
+        childRunId: row.child_run_id,
+        clientToken: row.client_token,
+        requested,
+        createdAt: row.created_at,
+        boundAt: row.bound_at,
+    };
+}
+function toState(row) {
+    return {
+        fleetRunId: row.fleet_run_id,
+        status: row.status,
+        cursor: Number(row.cursor),
+        lastSeenAt: row.last_seen_at,
+        lastError: row.last_error,
+        eventsDrained: Number(row.events_drained ?? 0) === 1,
+    };
+}
+export class BindingStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Record the intent to dispatch, before contacting the child.
+     *
+     * `requested` is stored as received so a later retry after a crash re-sends exactly the same payload; a
+     * payload that drifted between attempts would defeat the child's idempotency key.
+     */
+    createPending(input) {
+        this.db
+            .prepare(`INSERT INTO fleet_runs (fleet_run_id, host_id, owner_id, child_run_id, client_token, requested, created_at)
+         VALUES (?, ?, ?, NULL, ?, ?, ?)`)
+            .run(input.fleetRunId, input.hostId, input.ownerId, input.clientToken ?? null, JSON.stringify(input.requested), new Date().toISOString());
+        return this.get(input.fleetRunId);
+    }
+    get(fleetRunId) {
+        const row = this.db.prepare('SELECT * FROM fleet_runs WHERE fleet_run_id = ?').get(fleetRunId);
+        return row ? toBinding(row) : null;
+    }
+    /**
+     * Look up by idempotency token WITHIN one owner. Unscoped lookup was a leak: two callers reusing the same
+     * memorable token collided, and the second received the first one's run id, host and status.
+     */
+    findByClientToken(ownerId, token) {
+        const row = this.db
+            .prepare('SELECT * FROM fleet_runs WHERE owner_id = ? AND client_token = ?')
+            .get(ownerId, token);
+        return row ? toBinding(row) : null;
+    }
+    bind(fleetRunId, childRunId) {
+        this.db
+            .prepare('UPDATE fleet_runs SET child_run_id = ?, bound_at = ? WHERE fleet_run_id = ?')
+            .run(childRunId, new Date().toISOString(), fleetRunId);
+        return this.get(fleetRunId);
+    }
+    /**
+     * Drop a binding when the child definitively refused.
+     *
+     * Only reachable for a 4xx, where no Run was created. A transport failure or a 5xx must leave the binding
+     * in place with child_run_id NULL, because the Run may exist and a deleted binding is how it becomes an
+     * orphan.
+     */
+    discard(fleetRunId) {
+        this.db.prepare('DELETE FROM fleet_runs WHERE fleet_run_id = ?').run(fleetRunId);
+    }
+    /** Bindings whose child answer was never recorded: the crash-recovery worklist. */
+    pending() {
+        const rows = this.db
+            .prepare('SELECT * FROM fleet_runs WHERE child_run_id IS NULL ORDER BY created_at')
+            .all();
+        return rows.map(toBinding);
+    }
+    /**
+     * Bindings scoped to the hosts the caller may see. An empty allowlist yields no rows rather than all of
+     * them -- the same fail-closed reading the caller allowlist uses.
+     */
+    /**
+     * Bindings scoped to the hosts the caller may see. An empty allowlist yields no rows rather than all of
+     * them -- the same fail-closed reading the caller allowlist uses.
+     *
+     * run_state is joined rather than fetched per row. The previous shape issued one extra SELECT per binding,
+     * so a list of N Runs cost N+1 queries on the endpoint operators hit most often.
+     */
+    list(hostIds) {
+        // Fail closed on an empty allowlist. node:sqlite happens to accept `IN ()` and return no rows, so the
+        // query would also come back empty without this line -- but that is one driver's behaviour, not a
+        // guarantee worth depending on for an authorization decision. The order matters too: '*' is a string of
+        // length 1, so an emptiness test written first would never catch the wildcard.
+        if (hostIds !== '*' && hostIds.length === 0)
+            return [];
+        const where = hostIds === '*' ? '' : `WHERE fleet_runs.host_id IN (${hostIds.map(() => '?').join(',')})`;
+        const args = hostIds === '*' ? [] : hostIds;
+        const rows = this.db
+            .prepare(`SELECT fleet_runs.*,
+                run_state.status AS state_status, run_state.cursor AS state_cursor,
+                run_state.last_seen_at AS state_last_seen_at, run_state.last_error AS state_last_error,
+                run_state.events_drained AS state_events_drained
+           FROM fleet_runs
+           LEFT JOIN run_state ON run_state.fleet_run_id = fleet_runs.fleet_run_id
+           ${where}
+          ORDER BY fleet_runs.created_at DESC`)
+            .all(...args);
+        return rows.map((row) => ({
+            ...toBinding(row),
+            state: row.state_status === null || row.state_status === undefined
+                ? null
+                : {
+                    fleetRunId: row.fleet_run_id, status: row.state_status, cursor: Number(row.state_cursor ?? 0),
+                    lastSeenAt: row.state_last_seen_at ?? null, lastError: row.state_last_error ?? null,
+                    eventsDrained: Number(row.state_events_drained ?? 0) === 1,
+                },
+        }));
+    }
+    recordState(input) {
+        this.db
+            .prepare(`INSERT INTO run_state (fleet_run_id, status, cursor, last_seen_at, last_error)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(fleet_run_id) DO UPDATE SET
+           status = excluded.status, cursor = excluded.cursor,
+           last_seen_at = excluded.last_seen_at, last_error = excluded.last_error`)
+            .run(input.fleetRunId, input.status, input.cursor, input.lastSeenAt, input.lastError);
+    }
+    /**
+     * Point a binding at a new child Run and drop the mirrored window with it.
+     *
+     * Retry creates a NEW child Run, and the mirror is keyed on the child's own (run, sequence) pair -- so a
+     * second child Run would collide with the first one's sequences rather than continue them. Clearing is the
+     * honest option: the old events still live on the child under the old id, and the new Run's log is rebuilt
+     * from sequence 1. Doing neither would serve an interleaving of two Runs' events as if they were one.
+     */
+    rebind(fleetRunId, childRunId) {
+        const now = new Date().toISOString();
+        // One transaction. Three separate statements here could leave a binding pointing at a new child Run while
+        // the mirror still holds the OLD Run's sequences -- which is worse than either half failing, because the
+        // two windows are indistinguishable in the table: both are (run, sequence) rows starting at 1.
+        this.db.exec('BEGIN');
+        try {
+            this.db.prepare('DELETE FROM fleet_events WHERE fleet_run_id = ?').run(fleetRunId);
+            this.db
+                .prepare('UPDATE fleet_runs SET child_run_id = ?, bound_at = ? WHERE fleet_run_id = ?')
+                .run(childRunId, now, fleetRunId);
+            this.db
+                .prepare('UPDATE run_state SET cursor = 0, events_drained = 0 WHERE fleet_run_id = ?')
+                .run(fleetRunId);
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+        return this.get(fleetRunId);
+    }
+    /**
+     * Record how far a Run's event log has been read, touching nothing else.
+     *
+     * Status and staleness are deliberately absent: mirroring and reconciliation are separate concerns with
+     * separate failure modes, and a successful event read implies nothing about the Run's state. Going through
+     * recordState() would overwrite a status reconciliation had just decided.
+     *
+     * `drained` reports what the last pass saw rather than being one-way. A terminal Run that still owes a log
+     * is re-read regardless of this value, so an occasional false costs one extra read while a false `true`
+     * would abandon a log forever -- which is why mirrorEvents distinguishes the two.
+     */
+    setCursor(fleetRunId, cursor, drained) {
+        this.db
+            .prepare(`INSERT INTO run_state (fleet_run_id, status, cursor, last_seen_at, last_error, events_drained)
+         VALUES (?, ?, ?, NULL, NULL, ?)
+         ON CONFLICT(fleet_run_id) DO UPDATE SET
+           cursor = excluded.cursor,
+           events_drained = excluded.events_drained`)
+            .run(fleetRunId, UNKNOWN, cursor, drained ? 1 : 0);
+    }
+    state(fleetRunId) {
+        const row = this.db.prepare('SELECT * FROM run_state WHERE fleet_run_id = ?').get(fleetRunId);
+        return row ? toState(row) : null;
+    }
+}

package/dist/child.js

@@ -0,0 +1,137 @@
+/**
+ * The slice of a child Mercury's HTTP API that Fleet uses.
+ *
+ * Only the enumerated endpoints (design section 9: Fleet must not proxy arbitrary paths). A caller can never
+ * widen this surface; it is fixed here, so a child growing an internal route does not hand Fleet a new way to
+ * be pointed at it.
+ */
+/**
+ * Describe a transport failure usefully.
+ *
+ * undici wraps everything as `fetch failed` and puts the actual reason in `cause`, so reporting only the
+ * message tells an operator nothing about why a host is unreachable. The distinction they need -- refused,
+ * timed out, name not resolving, TLS -- lives in the cause.
+ */
+function describeTransportError(err) {
+    const e = err;
+    const detail = e.cause?.code ?? e.cause?.message;
+    return `${e.message}${detail ? `: ${detail}` : ''}`.slice(0, 200);
+}
+async function call(opts, url, init) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await doFetch(url, { ...init, signal: AbortSignal.timeout(opts.timeoutMs) });
+    }
+    catch (err) {
+        // Transport failure after a POST means the request may have been fully processed. The caller must not
+        // conclude anything from this except "ask again later".
+        return { kind: 'unknown', reason: describeTransportError(err) };
+    }
+    if (res.status >= 500) {
+        return { kind: 'unknown', reason: `HTTP ${res.status} from child` };
+    }
+    if (res.status >= 400) {
+        let detail = '';
+        try {
+            const body = await res.json();
+            detail = body.error ?? '';
+        }
+        catch { /* body was not JSON; the status still stands */ }
+        return { kind: 'rejected', status: res.status, detail: detail.slice(0, 300) };
+    }
+    try {
+        return { kind: 'ok', value: await res.json() };
+    }
+    catch (err) {
+        // A 2xx with an unreadable body is genuinely ambiguous for a create: the Run may exist.
+        return { kind: 'unknown', reason: `child response was not JSON: ${err.message}`.slice(0, 200) };
+    }
+}
+/**
+ * Same classification as `call`, but the success body is text.
+ *
+ * Kept separate rather than parameterised because the failure meanings differ: a 2xx with an unreadable JSON
+ * body after a POST is ambiguous about whether a Run was created, whereas a body that cannot be read here is
+ * simply a scrape that produced nothing usable.
+ */
+async function callText(opts, url, init) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await doFetch(url, { ...init, signal: AbortSignal.timeout(opts.timeoutMs) });
+    }
+    catch (err) {
+        return { kind: 'unknown', reason: describeTransportError(err) };
+    }
+    if (res.status >= 500)
+        return { kind: 'unknown', reason: `HTTP ${res.status} from child` };
+    if (res.status >= 400)
+        return { kind: 'rejected', status: res.status, detail: `HTTP ${res.status}` };
+    try {
+        return { kind: 'ok', value: await res.text() };
+    }
+    catch (err) {
+        return { kind: 'unknown', reason: `child metrics body unreadable: ${err.message}`.slice(0, 200) };
+    }
+}
+export function createChildClient(opts) {
+    const headers = (token) => ({
+        authorization: `Bearer ${token}`, accept: 'application/json',
+    });
+    return {
+        async createRun(host, payload, idempotencyKey) {
+            return call(opts, `${host.baseUrl}/api/runs`, {
+                method: 'POST',
+                headers: { ...headers(host.token), 'content-type': 'application/json', 'idempotency-key': idempotencyKey },
+                body: JSON.stringify(payload),
+            });
+        },
+        async getRun(host, runId) {
+            // The id comes from Fleet's own binding table, never from a caller, so this cannot be aimed at an
+            // arbitrary path on a child.
+            const safe = encodeURIComponent(runId);
+            const res = await call(opts, `${host.baseUrl}/api/runs/${safe}`, { method: 'GET', headers: headers(host.token) });
+            if (res.kind !== 'ok')
+                return res;
+            // Unwrap here rather than at every call site. Reading `.status` off the envelope yields undefined,
+            // which then reaches a SQLite bind as a 500 -- which is exactly what this line used to do, because
+            // the fake child in the tests had the same wrong shape as this client.
+            if (!res.value || typeof res.value.run !== 'object' || res.value.run === null) {
+                return { kind: 'unknown', reason: 'child run response had no run object' };
+            }
+            return { kind: 'ok', value: res.value.run };
+        },
+        async submitInput(host, runId, input) {
+            const safe = encodeURIComponent(runId);
+            return call(opts, `${host.baseUrl}/api/runs/${safe}/input`, {
+                method: 'POST', headers: { ...headers(host.token), 'content-type': 'application/json' },
+                body: JSON.stringify({ input }),
+            });
+        },
+        async cancelRun(host, runId) {
+            const safe = encodeURIComponent(runId);
+            return call(opts, `${host.baseUrl}/api/runs/${safe}/cancel`, { method: 'POST', headers: headers(host.token) });
+        },
+        async retryRun(host, runId) {
+            const safe = encodeURIComponent(runId);
+            return call(opts, `${host.baseUrl}/api/runs/${safe}/retry`, { method: 'POST', headers: headers(host.token) });
+        },
+        async getMetrics(host) {
+            // Text, not JSON: the value is returned verbatim rather than parsed here, so an unexpected metric family
+            // reaches the merge layer intact and can be reported as dropped instead of vanishing.
+            return callText(opts, `${host.baseUrl}/metrics`, {
+                method: 'GET',
+                // The shared helper asks for JSON because every other endpoint returns it. Asking a metrics endpoint
+                // for JSON is a latent trap: harmless while the child ignores Accept, wrong the day it honours it.
+                headers: { ...headers(host.token), accept: 'text/plain' },
+            });
+        },
+        async getEvents(host, runId, after, limit) {
+            const safe = encodeURIComponent(runId);
+            const url = `${host.baseUrl}/api/runs/${safe}/events?after=${encodeURIComponent(String(after))}`
+                + `&limit=${encodeURIComponent(String(limit))}`;
+            return call(opts, url, { method: 'GET', headers: headers(host.token) });
+        },
+    };
+}