@aywengo/mercury-fleet 0.0.1-bootstrap

package/dist/db.js

@@ -0,0 +1,162 @@
+/**
+ * Fleet's own SQLite database. Same engine and same operational shape as Mercury, deliberately no new
+ * infrastructure (docs/fleet-design.md section 5).
+ *
+ * The schema is split by what a crash costs, and that split is structural rather than a comment
+ * convention:
+ *
+ *   TRUTH  -- hosts. Losing it means Fleet does not know what it may talk to.
+ *   CACHE  -- host_probe. Rebuildable in one sweep, so it is never worth backing up.
+ *
+ * Phase 0 has no dispatch, so fleet_runs/run_state (the other truth table, and the one the design says
+ * must be backed up as seriously as a Mercury database) arrive with Phase 1.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+const MIGRATIONS = [
+    {
+        version: 1,
+        sql: `
+      CREATE TABLE IF NOT EXISTS hosts (
+        id             TEXT PRIMARY KEY,
+        base_url       TEXT NOT NULL,
+        credential_ref TEXT NOT NULL,
+        enabled        INTEGER NOT NULL DEFAULT 1,
+        labels         TEXT NOT NULL DEFAULT '{}',
+        local_paths    TEXT NOT NULL DEFAULT '[]',
+        agents_cache   TEXT NOT NULL DEFAULT '[]',
+        added_at       TEXT NOT NULL,
+        last_seen_at   TEXT
+      );
+
+      -- Probe results are a cache, so they live in their own table rather than as extra columns on
+      -- hosts. That keeps the truth/cache line visible in the schema: deleting this table is always
+      -- safe and costs one sweep, while deleting hosts is not.
+      CREATE TABLE IF NOT EXISTS host_probe (
+        host_id        TEXT PRIMARY KEY REFERENCES hosts(id) ON DELETE CASCADE,
+        -- One of: ok | unreachable | unauthorized | not_mercury | not_serving | http_error | timeout.
+        -- Distinct values on purpose: "down" would collapse failures that need different fixes.
+        outcome        TEXT NOT NULL,
+        detail         TEXT,
+        -- Live capacity, present only on a successful probe.
+        active_runs    INTEGER,
+        queue_depth    INTEGER,
+        worker_count   INTEGER,
+        worker_id      TEXT,
+        agents         TEXT,
+        probed_at      TEXT NOT NULL,
+        last_error     TEXT
+      );
+    `,
+    },
+    {
+        version: 2,
+        sql: `
+      -- TRUTH. Section 5 is explicit about what losing this costs: orphaned Runs on remote machines that
+      -- nobody can find. child_run_id is nullable, and the NULL is not a placeholder for "failed" -- it
+      -- means Fleet asked a child for a Run and has not yet learned the answer. Section 7's rule that
+      -- UNKNOWN is not FAILED is expressed by that column staying NULL rather than by a status string.
+      CREATE TABLE IF NOT EXISTS fleet_runs (
+        fleet_run_id   TEXT PRIMARY KEY,
+        -- Deliberately NOT ON DELETE CASCADE. A cascade here would mean that removing a host from the
+        -- registry silently deletes the record of Runs still executing on it. That is section 5's worst
+        -- failure -- orphaned Runs nobody can find -- reachable through an ordinary registry edit. The FK
+        -- is RESTRICT by omission, and HostRegistry.remove turns it into an explanation.
+        host_id        TEXT NOT NULL REFERENCES hosts(id),
+        child_run_id   TEXT,
+        -- The caller Fleet authenticated, never a value taken from the request body. Idempotency is scoped
+        -- to it below: a globally unique token would let one caller who guessed another's token receive
+        -- that caller's run id, host and status.
+        owner_id       TEXT NOT NULL,
+        client_token   TEXT,
+        requested      TEXT NOT NULL,
+        created_at     TEXT NOT NULL,
+        bound_at       TEXT,
+        UNIQUE (host_id, child_run_id),
+        -- Scoped rather than global: the same token string from two callers is two distinct keys.
+        UNIQUE (owner_id, client_token)
+      );
+
+      -- CACHE ONLY: rebuildable by re-reading the child. status holds the child's own status string, or
+      -- UNKNOWN when Fleet could not reach the child -- which is deliberately not the same value.
+      CREATE TABLE IF NOT EXISTS run_state (
+        fleet_run_id   TEXT PRIMARY KEY REFERENCES fleet_runs(fleet_run_id) ON DELETE CASCADE,
+        status         TEXT NOT NULL,
+        cursor         INTEGER NOT NULL DEFAULT 0,
+        last_seen_at   TEXT,
+        last_error     TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_fleet_runs_pending ON fleet_runs(host_id) WHERE child_run_id IS NULL;
+    `,
+    },
+    {
+        version: 3,
+        sql: `
+      -- CACHE, like host_probe: this mirrors what the child already has, so deleting it costs a re-read and
+      -- nothing else. The child stays the source of truth (section 2). Keeping it in its own table is what
+      -- makes that claim checkable rather than aspirational.
+      --
+      -- Metadata only by default (section 8): agent output can be large, and mirroring bodies turns Fleet
+      -- into a second copy of every Run's transcript with all the retention and secret questions that raises.
+      -- payload is therefore NULL unless the host opted in.
+      CREATE TABLE IF NOT EXISTS fleet_events (
+        fleet_run_id TEXT NOT NULL REFERENCES fleet_runs(fleet_run_id) ON DELETE CASCADE,
+        -- The child's own per-Run sequence, not a Fleet-assigned one. Re-mirroring the same event must be a
+        -- no-op, and the child's sequence is the only stable identity available.
+        sequence     INTEGER NOT NULL,
+        type         TEXT NOT NULL,
+        timestamp    TEXT NOT NULL,
+        payload      TEXT,
+        PRIMARY KEY (fleet_run_id, sequence)
+      );
+
+      CREATE INDEX IF NOT EXISTS fleet_events_run_seq
+        ON fleet_events (fleet_run_id, sequence);
+
+      -- Opt-in per host, because the right default differs by machine: a laptop Fleet may mirror freely where
+      -- a shared instance should not hold transcripts at all.
+      ALTER TABLE hosts ADD COLUMN mirror_bodies INTEGER NOT NULL DEFAULT 0;
+
+      -- Set once a mirror pass finds nothing more to read. Without it there is no way to leave a finished Run
+      -- alone: skipping terminal Runs outright means a Run that ended before the first sweep never has its
+      -- log mirrored at all, and Fleet could never show how anything finished.
+      ALTER TABLE run_state ADD COLUMN events_drained INTEGER NOT NULL DEFAULT 0;
+    `,
+    },
+];
+/** Open Fleet's database and apply any pending migrations. */
+export function openFleetDb(path) {
+    if (path !== ':memory:') {
+        const dir = dirname(path);
+        if (dir && dir !== '.')
+            mkdirSync(dir, { recursive: true });
+    }
+    const db = new DatabaseSync(path);
+    // Fleet may probe hosts from a timer while a CLI command reads, so readers must not block on the writer.
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec('CREATE TABLE IF NOT EXISTS fleet_meta (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)');
+    const done = new Set(db.prepare('SELECT version FROM fleet_meta').all().map((r) => r.version));
+    const applied = [];
+    const insert = db.prepare('INSERT INTO fleet_meta (version, applied_at) VALUES (?, ?)');
+    for (const m of MIGRATIONS) {
+        if (done.has(m.version))
+            continue;
+        // One transaction per migration: a half-applied migration is worse than none, because the version row
+        // would claim the schema exists when only part of it does.
+        db.exec('BEGIN');
+        try {
+            db.exec(m.sql);
+            insert.run(m.version, new Date().toISOString());
+            db.exec('COMMIT');
+            applied.push(m.version);
+        }
+        catch (err) {
+            db.exec('ROLLBACK');
+            throw new Error(`fleet migration ${m.version} failed: ${err.message}`);
+        }
+    }
+    return { db, appliedVersions: applied };
+}

package/dist/dispatch.js

@@ -0,0 +1,176 @@
+/**
+ * Dispatch: submit a task to a named host and record the binding.
+ *
+ * Phase 1 of docs/fleet-design.md section 12. No routing -- the caller names the host. What this phase has to
+ * prove is the binding model, idempotency across restarts, and crash recovery.
+ *
+ * The ordering is the whole design. A binding is written BEFORE the child is contacted, and the child call
+ * carries an idempotency key derived from Fleet's own run id. So the dangerous interleaving -- child created
+ * a Run, the response was lost -- resolves on the next attempt to the SAME child Run rather than to a second
+ * one or to an orphan.
+ */
+import { randomUUID } from 'node:crypto';
+import { UNKNOWN } from "./bindings.js";
+export class DispatchError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function newFleetRunId() {
+    // A distinct prefix from a child's run ids so an id is never ambiguous about which system issued it.
+    return `fr_${randomUUID().replace(/-/g, '')}`;
+}
+/** Resolve a host the caller may use, or explain why not. */
+export function resolveHost(deps, hostId) {
+    const host = deps.registry.get(hostId);
+    if (!host)
+        throw new DispatchError(404, `no such host: ${hostId}`);
+    if (!host.enabled) {
+        throw new DispatchError(409, `host ${hostId} is disabled; enable it before submitting work to it`);
+    }
+    return { baseUrl: host.baseUrl, token: deps.resolveToken(host.credentialRef) };
+}
+export async function submitRun(deps, input) {
+    // Caller-level idempotency, checked before anything is written. This is what makes a retry after a
+    // transport failure cheap: the same token returns the same binding, so no second child call happens and
+    // no second Run is paid for.
+    if (input.clientToken) {
+        const existing = deps.bindings.findByClientToken(input.ownerId, input.clientToken);
+        if (existing) {
+            // Reuse is only correct if the caller means the same thing it meant the first time. Silently
+            // returning a binding for a DIFFERENT host would suppress dispatch to the host the caller just named
+            // and hand back a Run running somewhere else.
+            if (existing.hostId !== input.hostId) {
+                throw new DispatchError(409, `idempotency token was already used for host ${existing.hostId}, not ${input.hostId}. ` +
+                    `Reuse would return the existing Run rather than dispatch to the host you named; use a new token.`);
+            }
+            return {
+                binding: existing,
+                reused: true,
+                pending: existing.childRunId === null,
+                // Accurate about WHEN this resolves: Phase 1 recovers at startup or on an explicit call. The
+                // background sweep is Phase 2, and claiming otherwise here would send an operator to wait for
+                // something that does not exist yet.
+                note: existing.childRunId === null
+                    ? 'existing binding is still awaiting its child answer; it is resolved at Fleet startup or via a manual recovery'
+                    : undefined,
+            };
+        }
+    }
+    const host = resolveHost(deps, input.hostId);
+    const fleetRunId = newFleetRunId();
+    const binding = deps.bindings.createPending({
+        fleetRunId,
+        hostId: input.hostId,
+        ownerId: input.ownerId,
+        requested: input.requested,
+        clientToken: input.clientToken ?? null,
+    });
+    const result = await deps.child.createRun(host, input.requested, fleetRunId);
+    if (result.kind === 'ok') {
+        const bound = deps.bindings.bind(fleetRunId, result.value.runId);
+        deps.bindings.recordState({
+            fleetRunId, status: result.value.status, cursor: 0,
+            lastSeenAt: new Date().toISOString(), lastError: null,
+        });
+        return { binding: bound, reused: false, pending: false };
+    }
+    if (result.kind === 'rejected') {
+        // A 4xx means the child refused and created nothing, so the binding is dead weight and removing it is
+        // safe. This is the ONLY branch that discards.
+        deps.bindings.discard(fleetRunId);
+        throw new DispatchError(result.status === 404 ? 404 : 400, `host ${input.hostId} rejected the submission (HTTP ${result.status}${result.detail ? `: ${result.detail}` : ''})`);
+    }
+    // Unknown: transport failure or 5xx. A Run may exist and be running right now. The binding stays, marked
+    // UNKNOWN, and recovery resolves it later. Reporting failure here would be the section 7 mistake.
+    deps.bindings.recordState({
+        fleetRunId, status: UNKNOWN, cursor: 0,
+        lastSeenAt: null, lastError: result.reason,
+    });
+    return {
+        binding: deps.bindings.get(fleetRunId),
+        reused: false,
+        pending: true,
+        note: `child answer unknown (${result.reason}); the Run may already exist and will be resolved on recovery`,
+    };
+}
+/**
+ * Crash recovery: re-derive every binding whose child answer was never recorded.
+ *
+ * Re-sends the stored payload with the SAME idempotency key. If the original request reached the child, the
+ * child's dedupe returns the Run it already created; if it never arrived, this creates it. Either way Fleet
+ * ends up able to name the Run, which is the point of the table.
+ */
+export async function recoverPending(deps) {
+    const pending = deps.bindings.pending();
+    let resolved = 0;
+    for (const binding of pending) {
+        let host;
+        try {
+            host = resolveHost(deps, binding.hostId);
+        }
+        catch {
+            // Host removed or disabled since the binding was made. Leave it pending: deleting the binding here is
+            // exactly the orphaning this function exists to prevent.
+            continue;
+        }
+        const result = await deps.child.createRun(host, binding.requested, binding.fleetRunId);
+        if (result.kind === 'ok') {
+            deps.bindings.bind(binding.fleetRunId, result.value.runId);
+            deps.bindings.recordState({
+                fleetRunId: binding.fleetRunId, status: result.value.status, cursor: 0,
+                lastSeenAt: new Date().toISOString(), lastError: null,
+            });
+            resolved++;
+            continue;
+        }
+        if (result.kind === 'rejected') {
+            // The child says it never had this key and refuses the payload now. Nothing is running.
+            deps.bindings.discard(binding.fleetRunId);
+            continue;
+        }
+        deps.bindings.recordState({
+            fleetRunId: binding.fleetRunId, status: UNKNOWN, cursor: 0,
+            lastSeenAt: null, lastError: result.reason,
+        });
+    }
+    return { resolved, stillPending: deps.bindings.pending().length };
+}
+/** Refresh cached status for every bound Run the caller can see. */
+export async function refreshStates(deps, hostIds) {
+    const views = deps.bindings.list(hostIds);
+    let updated = 0;
+    for (const view of views) {
+        if (!view.childRunId)
+            continue;
+        let host;
+        try {
+            host = resolveHost(deps, view.hostId);
+        }
+        catch {
+            continue;
+        }
+        const result = await deps.child.getRun(host, view.childRunId);
+        if (result.kind === 'ok') {
+            deps.bindings.recordState({
+                fleetRunId: view.fleetRunId, status: result.value.status,
+                cursor: view.state?.cursor ?? 0,
+                lastSeenAt: new Date().toISOString(), lastError: result.value.error ?? null,
+            });
+            updated++;
+        }
+        else {
+            // Unreachable is not failed. Keep the last known status but record why it may be stale.
+            deps.bindings.recordState({
+                fleetRunId: view.fleetRunId,
+                status: view.state?.status ?? UNKNOWN,
+                cursor: view.state?.cursor ?? 0,
+                lastSeenAt: view.state?.lastSeenAt ?? null,
+                lastError: result.kind === 'unknown' ? result.reason : `child said HTTP ${result.status}`,
+            });
+        }
+    }
+    return updated;
+}

package/dist/events.js

@@ -0,0 +1,114 @@
+import { DispatchError, resolveHost } from "./dispatch.js";
+/**
+ * Pages are capped per call rather than drained until exhausted. A Run emitting thousands of events per
+ * second would otherwise hold the sweep open indefinitely and starve every other Run of reconciliation --
+ * the same class of mistake as letting one slow host stall a probe sweep.
+ */
+const MAX_PAGES_PER_RUN = 5;
+const PAGE_LIMIT = 1000;
+function mirrorBodiesEnabled(db, hostId) {
+    const row = db.prepare('SELECT mirror_bodies FROM hosts WHERE id = ?').get(hostId);
+    return row?.mirror_bodies === 1;
+}
+/**
+ * Pull the next window of a Run's events and store them.
+ *
+ * Idempotent by construction: the primary key is the child's own (run, sequence) pair and inserts are
+ * INSERT OR IGNORE, so re-reading a window after a crash costs nothing. That is what makes it safe to call
+ * this from a timer that may be interrupted at any point.
+ */
+export async function mirrorEvents(deps, fleetRunId) {
+    const binding = deps.bindings.get(fleetRunId);
+    if (!binding)
+        throw new DispatchError(404, `no Fleet Run ${fleetRunId}`);
+    if (!binding.childRunId) {
+        // Not drained: there is no child Run to read yet, so nothing has been learned about any log.
+        return { fleetRunId, inserted: 0, cursor: 0, hasMore: false, drained: false, pages: 0 };
+    }
+    const host = resolveHost(deps, binding.hostId);
+    const withBodies = mirrorBodiesEnabled(deps.db, binding.hostId);
+    const state = deps.bindings.state(fleetRunId);
+    let cursor = state?.cursor ?? 0;
+    const insert = deps.db.prepare(`INSERT OR IGNORE INTO fleet_events (fleet_run_id, sequence, type, timestamp, payload)
+     VALUES (?, ?, ?, ?, ?)`);
+    let inserted = 0;
+    let hasMore = false;
+    let drained = false;
+    let pages = 0;
+    for (let page = 0; page < MAX_PAGES_PER_RUN; page++) {
+        const res = await deps.child.getEvents(host, binding.childRunId, cursor, PAGE_LIMIT);
+        if (res.kind !== 'ok') {
+            // Nothing is lost: the stored cursor still points at the last event actually mirrored, so the next
+            // sweep resumes from here. A failed read must never advance the cursor.
+            if (pages === 0) {
+                throw new DispatchError(res.kind === 'rejected' ? res.status : 502, res.kind === 'rejected' ? `child refused events: ${res.detail}` : `events unreadable: ${res.reason}`);
+            }
+            break;
+        }
+        pages++;
+        const events = res.value.events ?? [];
+        if (events.length === 0) {
+            // Nothing beyond the cursor and the child says so: the log is drained.
+            hasMore = false;
+            drained = !res.value.hasMore;
+            break;
+        }
+        for (const ev of events) {
+            const payload = withBodies && ev.payload !== undefined ? JSON.stringify(ev.payload) : null;
+            const r = insert.run(fleetRunId, ev.sequence, ev.type, ev.timestamp, payload);
+            if (r.changes > 0)
+                inserted++;
+        }
+        // Resume from what the child says it returned, never from lastSequence. That distinction is the whole
+        // content of Mercury issue #54 and the reason a truncated page is still safe to page from.
+        const next = res.value.nextCursor;
+        if (typeof next !== 'number' || next <= cursor) {
+            // A child that will not advance the cursor would spin this loop forever. Stop rather than repeat -- but
+            // do NOT call this drained. The log may hold plenty more; we simply cannot make progress right now, and
+            // recording drained here is what would make a terminal Run's missing log permanent.
+            hasMore = false;
+            drained = false;
+            break;
+        }
+        cursor = next;
+        hasMore = Boolean(res.value.hasMore);
+        if (!hasMore) {
+            drained = true;
+            break;
+        }
+    }
+    // Reaching the per-call page cap with more still pending is explicitly not drained; the next pass continues.
+    deps.bindings.setCursor(fleetRunId, cursor, drained);
+    return { fleetRunId, inserted, cursor, hasMore, drained, pages };
+}
+/**
+ * Read the mirrored window back out, in the same cursor shape the child uses, so a Fleet client resumes the
+ * same way whether it is talking to Fleet or to a host directly.
+ */
+export function listMirroredEvents(db, fleetRunId, after, limit) {
+    const rows = db
+        .prepare(`SELECT sequence, type, timestamp, payload FROM fleet_events
+        WHERE fleet_run_id = ? AND sequence > ?
+        ORDER BY sequence ASC LIMIT ?`)
+        .all(fleetRunId, after, limit);
+    const events = rows.map((r) => {
+        const base = { sequence: Number(r.sequence), type: r.type, timestamp: r.timestamp };
+        if (r.payload !== null && r.payload !== undefined) {
+            try {
+                base.payload = JSON.parse(r.payload);
+            }
+            catch {
+                // A payload that will not parse is still worth surfacing as text rather than dropping the event.
+                base.payload = r.payload;
+            }
+        }
+        return base;
+    });
+    const last = events.length > 0 ? events[events.length - 1].sequence : after;
+    // Same rule as the child: the resume point is the last sequence returned, and hasMore is decided by whether
+    // anything further exists -- not by the page size, which lies on the final partial page.
+    const more = db
+        .prepare('SELECT 1 AS x FROM fleet_events WHERE fleet_run_id = ? AND sequence > ? LIMIT 1')
+        .get(fleetRunId, last);
+    return { events, nextCursor: last, hasMore: more !== undefined };
+}

package/dist/http.js

@@ -0,0 +1,91 @@
+/**
+ * A minimal HTTP layer: bearer auth, JSON bodies, and a route table with no dependencies.
+ *
+ * Fleet deliberately declares no runtime dependencies (docs/fleet-design.md section 11, enforced by
+ * fleet/test/coupling.test.ts). Mercury uses express; Fleet cannot import it and adding it would make Fleet
+ * a second web framework to keep patched for a surface this small. node:http plus this file is enough, and
+ * "enough" is checked by the tests rather than asserted here.
+ */
+import { isAdminToken } from "./auth.js";
+export class HttpError extends Error {
+    status;
+    code;
+    /**
+     * Structured detail for callers that can act on it -- routing returns which hosts were considered and why
+     * each was ruled out, which is the difference between a five-second fix and an hour of guessing.
+     */
+    details;
+    constructor(status, message, code, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+export function matchRoute(routes, method, path) {
+    const parts = path.split('/').filter(Boolean);
+    for (const route of routes) {
+        if (route.method !== method)
+            continue;
+        if (route.pattern.length !== parts.length)
+            continue;
+        const params = [];
+        let ok = true;
+        for (let i = 0; i < route.pattern.length; i++) {
+            const p = route.pattern[i];
+            if (p.startsWith(':'))
+                params.push(decodeURIComponent(parts[i]));
+            else if (p !== parts[i]) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok)
+            return { route, params };
+    }
+    return null;
+}
+const MAX_BODY_BYTES = 1024 * 1024;
+/** Read and parse a JSON body, bounded. An unbounded read is a memory-exhaustion route. */
+export async function readJsonBody(req) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = chunk;
+        total += buf.length;
+        if (total > MAX_BODY_BYTES)
+            throw new HttpError(413, `request body exceeds ${MAX_BODY_BYTES} bytes`);
+        chunks.push(buf);
+    }
+    if (total === 0)
+        return {};
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch (err) {
+        throw new HttpError(400, `request body is not valid JSON: ${err.message}`);
+    }
+}
+/**
+ * Resolve the caller from the Authorization header.
+ *
+ * Returns null rather than responding, so the caller of this function decides the status: a missing
+ * credential is 401 and a credential that names a host the caller may not touch is 403. Collapsing those
+ * tells an operator nothing about which of the two problems they have.
+ */
+export function authenticate(req, deps) {
+    const header = req.headers.authorization ?? '';
+    const m = /^Bearer\s+(.+)$/i.exec(header);
+    if (!m)
+        return null;
+    const token = m[1];
+    if (isAdminToken(deps.adminToken, token)) {
+        return { ownerId: 'admin', isAdmin: true, allowedHosts: '*' };
+    }
+    return deps.callers.resolve(token);
+}
+export function sendJson(res, status, payload) {
+    const body = JSON.stringify(payload, null, 2) + '\n';
+    res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) });
+    res.end(body);
+}

package/dist/interact.js

@@ -0,0 +1,88 @@
+import { DispatchError, resolveHost } from "./dispatch.js";
+function requireBound(deps, fleetRunId) {
+    const binding = deps.bindings.get(fleetRunId);
+    if (!binding)
+        throw new DispatchError(404, `no Fleet Run ${fleetRunId}`);
+    if (!binding.childRunId) {
+        // Nothing exists on the child yet, so there is nothing to talk to. This is not a failure of the action.
+        throw new DispatchError(409, `Fleet Run ${fleetRunId} has no child Run yet; its dispatch is still unresolved`);
+    }
+    return { binding, host: resolveHost(deps, binding.hostId) };
+}
+/**
+ * A child refusal is the caller's problem to see, so it surfaces as a 400 carrying the child's own reason.
+ *
+ * Only refusals go through here. An unreachable child is NOT an error and never was: it returns an outcome with
+ * unknown set, because throwing would invite someone to map it to a status that implies the action failed.
+ */
+function refuse(detail) {
+    throw new DispatchError(400, detail);
+}
+export async function sendInput(deps, fleetRunId, input) {
+    const { binding, host } = requireBound(deps, fleetRunId);
+    const res = await deps.child.submitInput(host, binding.childRunId, input);
+    if (res.kind === 'rejected')
+        refuse(`child refused input: ${res.detail}`);
+    if (res.kind === 'unknown') {
+        return {
+            fleetRunId, hostId: binding.hostId, childRunId: binding.childRunId, status: null, unknown: true,
+            note: `input delivery unconfirmed (${res.reason}); the Run may still have received it`,
+        };
+    }
+    return { fleetRunId, hostId: binding.hostId, childRunId: binding.childRunId, status: null, unknown: false };
+}
+export async function cancelRun(deps, fleetRunId) {
+    const { binding, host } = requireBound(deps, fleetRunId);
+    const res = await deps.child.cancelRun(host, binding.childRunId);
+    if (res.kind === 'rejected')
+        refuse(`child refused cancel: ${res.detail}`);
+    if (res.kind === 'unknown') {
+        // Deliberately not recorded as CANCELLED. Reconciliation will read the real status on the next pass.
+        return {
+            fleetRunId, hostId: binding.hostId, childRunId: binding.childRunId, status: null, unknown: true,
+            note: `cancel unconfirmed (${res.reason}); status will be corrected by reconciliation`,
+        };
+    }
+    // The child answered, so record what it said rather than the status we hoped for.
+    deps.bindings.recordState({
+        fleetRunId, status: res.value.status, cursor: deps.bindings.state(fleetRunId)?.cursor ?? 0,
+        lastSeenAt: new Date().toISOString(), lastError: null,
+    });
+    return {
+        fleetRunId, hostId: binding.hostId, childRunId: binding.childRunId,
+        status: res.value.status, unknown: false,
+    };
+}
+/**
+ * Retry, and follow the binding to the new child Run.
+ *
+ * Mercury's retry creates a NEW Run (it answers a fresh runId plus retryOf). The binding must move with it or
+ * Fleet would keep polling a Run the operator has superseded -- and the mirrored window has to be cleared,
+ * because it is keyed on the child's sequence and the new Run restarts at 1.
+ */
+export async function retryRun(deps, fleetRunId) {
+    const { binding, host } = requireBound(deps, fleetRunId);
+    const previousChildRunId = binding.childRunId;
+    const res = await deps.child.retryRun(host, previousChildRunId);
+    if (res.kind === 'rejected')
+        refuse(`child refused retry: ${res.detail}`);
+    if (res.kind === 'unknown') {
+        // A retry that we cannot confirm is the dangerous case: the child may have created a Run that Fleet does
+        // not know about. Say so plainly rather than leaving the binding silently pointing at the old Run.
+        return {
+            fleetRunId, hostId: binding.hostId, childRunId: previousChildRunId, status: null, unknown: true,
+            note: `retry unconfirmed (${res.reason}); a child Run may exist that Fleet has not bound. `
+                + 'Re-submit with a new idempotency key only after checking the host.',
+        };
+    }
+    const rebound = deps.bindings.rebind(fleetRunId, res.value.runId);
+    deps.bindings.recordState({
+        fleetRunId, status: res.value.status, cursor: 0,
+        lastSeenAt: new Date().toISOString(), lastError: null,
+    });
+    return {
+        fleetRunId, hostId: rebound.hostId, childRunId: res.value.runId,
+        status: res.value.status, unknown: false,
+        note: `retried: child Run ${previousChildRunId} superseded by ${res.value.runId}`,
+    };
+}

package/dist/logger.js

@@ -0,0 +1,50 @@
+/**
+ * Structured JSON logging for the Fleet service.
+ *
+ * Same shape as Mercury's log lines on purpose -- one journald query across the fleet -- but a separate
+ * implementation, because the coupling rule forbids importing Mercury's logger. Every line goes through the
+ * redactor, including the message and every string field, so a caller-supplied string cannot smuggle a
+ * secret into a log and neither can an exception message.
+ */
+const ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+function redactDeep(value, redactor) {
+    if (typeof value === 'string')
+        return redactor.redact(value);
+    if (value instanceof Error)
+        return { name: value.name, message: redactor.redact(value.message) };
+    if (Array.isArray(value))
+        return value.map((v) => redactDeep(v, redactor));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = redactDeep(v, redactor);
+        return out;
+    }
+    return value;
+}
+export function createLogger(redactor, minLevel = 'info', sink) {
+    const write = sink ?? ((line, level) => {
+        const stream = level === 'error' || level === 'warn' ? process.stderr : process.stdout;
+        stream.write(line + '\n');
+    });
+    const emit = (level, msg, fields) => {
+        if (ORDER[level] < ORDER[minLevel])
+            return;
+        const rec = { ts: new Date().toISOString(), level, msg: redactor.redact(msg) };
+        if (fields)
+            Object.assign(rec, redactDeep(fields, redactor));
+        try {
+            write(JSON.stringify(rec), level);
+        }
+        catch {
+            // A field with a circular reference must not take the service down while reporting something else.
+            write(JSON.stringify({ ts: new Date().toISOString(), level, msg: 'log serialization failed' }), level);
+        }
+    };
+    return {
+        debug: (m, f) => emit('debug', m, f),
+        info: (m, f) => emit('info', m, f),
+        warn: (m, f) => emit('warn', m, f),
+        error: (m, f) => emit('error', m, f),
+    };
+}