super-dsh 0.1.5 → 0.1.9

package/superd-hub/dist/mesh-rpc.js

@@ -0,0 +1,250 @@
+import { ensureSelf, listRemotes, removeRemote } from './machines.js';
+import { machineStatus, pairMachine, reprobeMachine, emitMachineRemoved } from './mesh-link.js';
+import { A2A_ENDPOINT_PATH, A2A_OUTBOX_PATH, A2A_WIRE_VERSION, decodeA2aWireFrame } from './a2a-wire.js';
+import { EXEC_API_BASE, parseOneShotExecBody, runOneShotExec } from './exec.js';
+/** The shared-channel Fetch route path this API owns. */
+export const MESH_API_BASE = '/api/superd/machines';
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+/** Project one persisted row to its public wire shape (allowlist — never
+ *  token, never cookie) and join the mesh-link status entry by id. */
+function publicRow(row) {
+    return projectRow(row, machineStatus());
+}
+function projectRow(row, status) {
+    const entry = status.get(row.id);
+    if (entry === undefined)
+        return { id: row.id, name: row.name, label: row.label, origin: row.origin, enabled: row.enabled, addedAt: row.addedAt, status: 'pending' };
+    const out = { id: row.id, name: row.name, label: row.label, origin: row.origin, enabled: row.enabled, addedAt: row.addedAt, status: entry.status, lastProbeAt: entry.lastProbeAt };
+    if (entry.error !== undefined)
+        out.error = entry.error;
+    if (entry.versionWarning !== undefined)
+        out.versionWarning = entry.versionWarning;
+    return out;
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function readJsonBody(request) {
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch (err) {
+        throw new Error(`mesh-api: request body is not valid JSON — ${errMsg(err)}`);
+    }
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        throw new Error('mesh-api: request body must be a JSON object');
+    }
+    return body;
+}
+/**
+ * The mesh-machines handler: GET list / POST pair-or-reprobe / DELETE remove.
+ * @param request - the incoming `/api/superd/machines` request.
+ * @param deps - home + optional fetch override (tests inject a fixture).
+ * @returns the JSON response.
+ */
+export async function handleMeshMachines(request, deps) {
+    const method = request.method;
+    if (method === 'GET')
+        return handleList(deps);
+    if (method === 'POST')
+        return handlePost(request, deps);
+    if (method === 'DELETE')
+        return handleRemove(request, deps);
+    return json(405, { error: `mesh-api: method ${method} is not supported on ${MESH_API_BASE}` });
+}
+/** GET: self (lazily minted on first need, spec §3.1) + every remote row in
+ *  its public projection, status joined from the mesh-link table. */
+function handleList(deps) {
+    const self = ensureSelf(deps.home, 'local');
+    const status = machineStatus();
+    const machines = listRemotes(deps.home).map((row) => projectRow(row, status));
+    return json(200, { self, machines });
+}
+/** POST: body-dispatched — `{op: 'reprobe', id}` re-probes, anything else is
+ *  a pairing input `{name, label?, tokenUrl}`. */
+async function handlePost(request, deps) {
+    let body;
+    try {
+        body = await readJsonBody(request);
+    }
+    catch (err) {
+        return json(400, { error: errMsg(err) });
+    }
+    if (typeof body.op === 'string' && body.op !== '') {
+        if (body.op !== 'reprobe')
+            return json(400, { error: `mesh-api: unknown op "${body.op}"` });
+        const id = typeof body.id === 'string' && body.id !== '' ? body.id : '';
+        if (id === '')
+            return json(400, { error: 'mesh-api: reprobe body must be {op: "reprobe", id} with a non-empty id' });
+        let probe;
+        try {
+            probe = await reprobeMachine(deps.home, id, { fetchImpl: deps.fetchImpl });
+        }
+        catch (err) {
+            return json(400, { error: errMsg(err) });
+        }
+        // A settled probe outcome (even unreachable/auth-expired) is an answer,
+        // not an operation failure — the status table records it either way.
+        return json(200, { probe });
+    }
+    const name = typeof body.name === 'string' && body.name !== '' ? body.name : '';
+    const tokenUrl = typeof body.tokenUrl === 'string' && body.tokenUrl !== '' ? body.tokenUrl : '';
+    if (name === '' || tokenUrl === '') {
+        return json(400, { error: 'mesh-api: pair body must be {name, label?, tokenUrl} with non-empty name and tokenUrl' });
+    }
+    const label = typeof body.label === 'string' && body.label !== '' ? body.label : undefined;
+    let outcome;
+    try {
+        outcome = await pairMachine(deps.home, { name, label, tokenUrl }, { fetchImpl: deps.fetchImpl });
+    }
+    catch (err) {
+        // mesh-link errors are actionable and token-redacted (Task 2 fix round 1).
+        return json(400, { error: errMsg(err) });
+    }
+    return json(201, { machine: publicRow(outcome.row) });
+}
+/** DELETE: drop one remote row by `?id=`; `{removed: false}` for unknown ids. */
+function handleRemove(request, deps) {
+    const id = new URL(request.url).searchParams.get('id') ?? '';
+    if (id === '')
+        return json(400, { error: `mesh-api: DELETE on ${MESH_API_BASE} requires a non-empty ?id= query parameter` });
+    const removed = removeRemote(deps.home, id);
+    if (removed)
+        emitMachineRemoved(id); // federation bus: the registrar drops every row of the machine
+    return json(200, { removed });
+}
+/**
+ * Register the mesh-machines API on the shared `/api` connection channel
+ * (behind the standard browser-trust + auth fence). No-op when the
+ * `connection` service is absent (e.g. fake-ctx unit tests).
+ */
+export function registerMeshRpc(ctx, deps) {
+    ctx.inject(['connection'], (connCtx) => {
+        const fetchFace = Reflect.get(connCtx, 'connection')?.fetch;
+        if (fetchFace === undefined)
+            return; // connection not actually present (test ctx)
+        connCtx.effect(() => fetchFace.register({
+            path: MESH_API_BASE,
+            methods: [...ROUTE_METHODS],
+            requestBody: 'buffered',
+            fetch: (request) => handleMeshMachines(request, deps),
+        }), 'superd-hub: /api/superd/machines route');
+    });
+}
+/** Every method our exact paths claim on the shared `/api` channel — unknown
+ * methods land in the HANDLER's honest 405 (a PUT on a known path is "method
+ * not supported", not a fall-through host 404; 2026-09-29 field finding:
+ * PUT /api/superd/machines answered 404 because the registration only
+ * claimed GET/POST/DELETE). */
+const ROUTE_METHODS = ['GET', 'POST', 'DELETE', 'PUT', 'PATCH', 'HEAD'];
+// ---------------------------------------------------------------- a2a (postoffice R3)
+// (A2aRpcDeps retired in R4 — registerA2aRpc takes the SHARED ingest instance)
+/**
+ * POST /api/superd/a2a — body = one v1 wire frame `{v: 1, envelope}` → the
+ * envelope's receipt (new/message: send receipt; stop: stop receipt;
+ * reply/notice: the local delivery outcome). Malformed frames are 400s with
+ * the decoder's named reason.
+ */
+export async function handleA2aIngestPost(request, ingest) {
+    if (request.method !== 'POST') {
+        return json(405, { error: `mesh-api: method ${request.method} is not supported on ${A2A_ENDPOINT_PATH} (use POST)` });
+    }
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch (err) {
+        return json(400, { error: `mesh-api: a2a body is not valid JSON — ${err instanceof Error ? err.message : String(err)}` });
+    }
+    const decoded = decodeA2aWireFrame(body);
+    if (!decoded.ok)
+        return json(400, { error: decoded.error });
+    const receipt = await ingest.ingest(decoded.envelope);
+    return json(200, receipt);
+}
+/**
+ * GET /api/superd/a2a/outbox?machine=<m4> — claim & clear the buffered
+ * envelopes addressed to the claiming machine (declarative claim, D1).
+ */
+export function handleA2aOutboxGet(request, ingest) {
+    if (request.method !== 'GET') {
+        return json(405, { error: `mesh-api: method ${request.method} is not supported on ${A2A_OUTBOX_PATH} (use GET)` });
+    }
+    const machine = new URL(request.url).searchParams.get('machine') ?? '';
+    if (machine === '') {
+        return json(400, { error: 'mesh-api: a2a outbox claim requires a non-empty ?machine= query parameter' });
+    }
+    return json(200, { v: A2A_WIRE_VERSION, envelopes: ingest.claimOutbox(machine) });
+}
+/**
+ * Register the a2a endpoints (POST /api/superd/a2a + GET .../outbox) on the
+ * shared `/api` connection channel — same fence as the machines route. The
+ * ingest instance is SHARED (R4): the initiator service's self-routing leg
+ * calls the very same handler these routes call. No-op when `connection` is
+ * absent.
+ */
+export function registerA2aRpc(ctx, ingest) {
+    ctx.inject(['connection'], (connCtx) => {
+        const fetchFace = Reflect.get(connCtx, 'connection')?.fetch;
+        if (fetchFace === undefined)
+            return; // connection not actually present (test ctx)
+        // (the ingest instance is injected — one instance shared with the service)
+        connCtx.effect(() => fetchFace.register({
+            path: A2A_ENDPOINT_PATH,
+            methods: [...ROUTE_METHODS],
+            requestBody: 'buffered',
+            fetch: (request) => handleA2aIngestPost(request, ingest),
+        }), 'superd-hub: /api/superd/a2a route');
+        connCtx.effect(() => fetchFace.register({
+            path: A2A_OUTBOX_PATH,
+            methods: [...ROUTE_METHODS],
+            requestBody: 'buffered',
+            fetch: (request) => Promise.resolve(handleA2aOutboxGet(request, ingest)),
+        }), 'superd-hub: /api/superd/a2a/outbox route');
+    });
+}
+// ---------------------------------------------------------------- exec (P4, spec §8.1)
+/**
+ * POST /api/superd/exec — one-shot `bash -lc <cmd>` on THIS machine (spec
+ * §8.1): tail-windowed stdout/stderr, two-stage group kill on timeout. The
+ * auth trust boundary is the shared `/api` fence (same as machines/a2a);
+ * the initiator-side per-machine knob (`execEnabled`) lives on the CALLER's
+ * registry row, not here.
+ */
+export async function handleExecPost(request, log) {
+    if (request.method !== 'POST') {
+        return json(405, { error: `mesh-api: method ${request.method} is not supported on ${EXEC_API_BASE} (use POST)` });
+    }
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch (err) {
+        return json(400, { error: `mesh-api: exec body is not valid JSON — ${err instanceof Error ? err.message : String(err)}` });
+    }
+    const parsed = parseOneShotExecBody(body);
+    if (!parsed.ok)
+        return json(400, { error: `mesh-api: ${parsed.error}` });
+    const result = await runOneShotExec(parsed.value, log);
+    return json(200, result);
+}
+/** Register the exec endpoint on the shared `/api` connection channel. */
+export function registerExecRpc(ctx, log) {
+    ctx.inject(['connection'], (connCtx) => {
+        const fetchFace = Reflect.get(connCtx, 'connection')?.fetch;
+        if (fetchFace === undefined)
+            return; // connection not actually present (test ctx)
+        connCtx.effect(() => fetchFace.register({
+            path: EXEC_API_BASE,
+            methods: [...ROUTE_METHODS],
+            requestBody: 'buffered',
+            fetch: (request) => handleExecPost(request, log),
+        }), 'superd-hub: /api/superd/exec route');
+    });
+}

package/superd-hub/dist/mux-client.d.ts

@@ -0,0 +1,71 @@
+/** Every client→server stream frame (control replies like `pong` excluded). */
+export type MuxClientFrame = {
+    type: 'open';
+    streamId: number;
+    endpoint: string;
+    payload: unknown;
+} | {
+    type: 'item';
+    streamId: number;
+    value?: unknown;
+} | {
+    type: 'end';
+    streamId: number;
+} | {
+    type: 'cancel';
+    streamId: number;
+};
+/** The injected text-socket seam (Task 2 adapts `ws` to this shape). */
+export interface MuxClientSocket {
+    send(data: string): void;
+    onMessage(cb: (data: string) => void): void;
+    onClose(cb: () => void): void;
+    close(): void;
+}
+/** The frozen openStream handle (Task 2 builds on this exact shape). */
+export interface MuxStreamHandle {
+    /** Server items until `end`/`error`/socket close (see the header rulings). */
+    items: AsyncIterable<unknown>;
+    /** Uplink channel: one `next(value)` read = one item frame, zero buffering. */
+    upstream: AsyncIterable<unknown>;
+    /** Uplink half-close: sends `{type:'end'}` once; downlink stays live. */
+    end(): void;
+    /** Cancel the logical stream: one `{type:'cancel'}` frame, local retirement. */
+    cancel(): void;
+}
+/** Options. */
+export interface MuxClientOptions {
+    /** Server ping cadence used for the silence window (2 × this); upstream default 2s. */
+    heartbeatIntervalMs?: number;
+}
+/** A stream/transport failure carrying wire failure fields (or a local cut code). */
+export declare class MuxClientError extends Error {
+    readonly code: string;
+    readonly details: object;
+    constructor(code: string, message: string, details?: object);
+}
+/** The mux client half: pure protocol, socket injected. */
+export declare class MuxClient {
+    private readonly socket;
+    private readonly heartbeatIntervalMs;
+    private nextId;
+    private readonly streams;
+    private state;
+    private watchdog;
+    constructor(socket: MuxClientSocket, options?: MuxClientOptions);
+    /** Open one logical stream; the handle's lanes are documented in the header. */
+    openStream(endpoint: string, payload: unknown): MuxStreamHandle;
+    /** Close every stream and the socket. Idempotent; no cancel frames (the server unwinds on socket close). */
+    dispose(): void;
+    private endUplink;
+    private retire;
+    /** Serialize one frame; the wire id is the stringified numeric counter. */
+    private sendFrame;
+    private onData;
+    /** The 1008 mirror: an unusable server frame closes the socket. */
+    private protocolViolation;
+    /** Fail every live stream, drop the table, optionally close the socket. */
+    private teardown;
+    private armWatchdog;
+    private clearWatchdog;
+}

package/superd-hub/dist/mux-client.js

@@ -0,0 +1,281 @@
+/** A stream/transport failure carrying wire failure fields (or a local cut code). */
+export class MuxClientError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'MuxClientError';
+        this.code = code;
+        this.details = details;
+    }
+}
+const DEFAULT_HEARTBEAT_MS = 2_000;
+const MAX_SILENT_PERIODS = 2;
+const DONE = { value: undefined, done: true };
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, keys) {
+    const own = Object.keys(value);
+    return own.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+function validId(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Downlink lane of one stream: server items until a terminal frame or a local
+ * cut. Mirrors the upstream client's `StreamInbox` semantics — a wire `error`
+ * drains queued items first and then throws; local cuts drop the queue.
+ */
+class DownlinkQueue {
+    queue = [];
+    failure;
+    thrown = false;
+    done = false;
+    waiters = [];
+    push(value) {
+        if (this.done || this.failure !== undefined)
+            return;
+        this.queue.push(value);
+        this.signal();
+    }
+    /** Terminal server `end` frame: queued items drain, then the iterable finishes. */
+    settleEnd() {
+        if (this.done || this.failure !== undefined)
+            return;
+        this.done = true;
+        this.signal();
+    }
+    /** Server `error` frame: queued items drain, then the iterable throws it. */
+    settleFailure(error) {
+        if (this.done || this.failure !== undefined)
+            return;
+        this.failure = error;
+        this.signal();
+    }
+    /** Local cancellation: queued items are dropped, the iterable finishes. */
+    abort() {
+        if (this.done || this.failure !== undefined)
+            return;
+        this.queue.length = 0;
+        this.done = true;
+        this.signal();
+    }
+    /** Local cut (socket close, silence, dispose): drop the queue, throw now. */
+    fail(error) {
+        if (this.failure !== undefined)
+            return;
+        this.queue.length = 0;
+        this.done = true;
+        this.failure = error;
+        this.signal();
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    async next() {
+        while (true) {
+            if (this.queue.length > 0)
+                return { value: this.queue.shift(), done: false };
+            if (this.failure !== undefined && !this.thrown) {
+                this.thrown = true;
+                throw this.failure;
+            }
+            if (this.done || this.thrown)
+                return DONE;
+            await new Promise((resolve) => { this.waiters.push(resolve); });
+        }
+    }
+    signal() {
+        const waiters = [...this.waiters];
+        this.waiters.length = 0;
+        for (const wake of waiters)
+            wake();
+    }
+}
+/** The mux client half: pure protocol, socket injected. */
+export class MuxClient {
+    socket;
+    heartbeatIntervalMs;
+    nextId = 1;
+    streams = new Map();
+    state = 'open';
+    watchdog;
+    constructor(socket, options = {}) {
+        this.socket = socket;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+        socket.onMessage((data) => { this.onData(data); });
+        socket.onClose(() => {
+            this.teardown(new MuxClientError('gateway/socket-closed', 'mux-client: the server closed the socket'));
+        });
+        this.armWatchdog();
+    }
+    /** Open one logical stream; the handle's lanes are documented in the header. */
+    openStream(endpoint, payload) {
+        if (this.state !== 'open')
+            throw new MuxClientError('gateway/disposed', 'mux-client: disposed');
+        const id = this.nextId;
+        this.nextId += 1;
+        const stream = { downlink: new DownlinkQueue(), ended: false, retired: false };
+        this.streams.set(String(id), stream);
+        this.sendFrame({ type: 'open', streamId: id, endpoint, payload });
+        const key = String(id);
+        const live = () => this.state === 'open' && !stream.retired;
+        const upstream = {
+            [Symbol.asyncIterator]: () => ({
+                next: (value) => {
+                    if (!live() || stream.ended)
+                        return Promise.resolve(DONE);
+                    this.sendFrame(value === undefined
+                        ? { type: 'item', streamId: id }
+                        : { type: 'item', streamId: id, value });
+                    return Promise.resolve({ value: undefined, done: false });
+                },
+                return: () => {
+                    this.endUplink(id, stream);
+                    return Promise.resolve(DONE);
+                },
+            }),
+        };
+        return {
+            items: stream.downlink,
+            upstream,
+            end: () => { this.endUplink(id, stream); },
+            cancel: () => {
+                if (!live())
+                    return;
+                this.retire(key, stream);
+                stream.downlink.abort();
+                this.sendFrame({ type: 'cancel', streamId: id });
+            },
+        };
+    }
+    /** Close every stream and the socket. Idempotent; no cancel frames (the server unwinds on socket close). */
+    dispose() {
+        this.teardown(new MuxClientError('gateway/disposed', 'mux-client: disposed'), true);
+    }
+    endUplink(id, stream) {
+        if (this.state !== 'open' || stream.retired || stream.ended)
+            return;
+        stream.ended = true;
+        this.sendFrame({ type: 'end', streamId: id });
+    }
+    retire(key, stream) {
+        stream.retired = true;
+        this.streams.delete(key);
+    }
+    /** Serialize one frame; the wire id is the stringified numeric counter. */
+    sendFrame(frame) {
+        const wire = { type: frame.type, streamId: String(frame.streamId) };
+        if (frame.type === 'open') {
+            wire['endpoint'] = frame.endpoint;
+            wire['payload'] = frame.payload;
+        }
+        if (frame.type === 'item' && frame.value !== undefined)
+            wire['value'] = frame.value;
+        this.socket.send(JSON.stringify(wire));
+    }
+    onData(data) {
+        if (this.state !== 'open')
+            return;
+        this.armWatchdog(); // any received frame is liveness
+        let raw;
+        try {
+            raw = JSON.parse(data);
+        }
+        catch {
+            this.protocolViolation('malformed server frame');
+            return;
+        }
+        if (!isRecord(raw)) {
+            this.protocolViolation('malformed server frame');
+            return;
+        }
+        if (raw['type'] === 'ping') {
+            if (!exactKeys(raw, ['type'])) {
+                this.protocolViolation('malformed ping frame');
+                return;
+            }
+            this.socket.send('{"type":"pong"}');
+            return;
+        }
+        if (raw['type'] === 'item') {
+            if (!(exactKeys(raw, ['type', 'streamId']) || exactKeys(raw, ['type', 'streamId', 'value']))
+                || !validId(raw['streamId'])) {
+                this.protocolViolation('malformed item frame');
+                return;
+            }
+            const stream = this.streams.get(raw['streamId']);
+            if (stream === undefined)
+                return; // late frame: stream retired, drop
+            stream.downlink.push(Object.hasOwn(raw, 'value') ? raw['value'] : undefined);
+            return;
+        }
+        if (raw['type'] === 'end') {
+            if (!exactKeys(raw, ['type', 'streamId']) || !validId(raw['streamId'])) {
+                this.protocolViolation('malformed end frame');
+                return;
+            }
+            const stream = this.streams.get(raw['streamId']);
+            if (stream === undefined)
+                return;
+            this.retire(raw['streamId'], stream);
+            stream.downlink.settleEnd();
+            return;
+        }
+        if (raw['type'] === 'error') {
+            const failure = failureOf(raw['error']);
+            if (failure === undefined || !exactKeys(raw, ['type', 'streamId', 'error']) || !validId(raw['streamId'])) {
+                this.protocolViolation('malformed error frame');
+                return;
+            }
+            const stream = this.streams.get(raw['streamId']);
+            if (stream === undefined)
+                return;
+            this.retire(raw['streamId'], stream);
+            stream.downlink.settleFailure(new MuxClientError(failure.code, failure.message, failure.details));
+            return;
+        }
+        this.protocolViolation(`out-of-protocol server frame (${String(raw['type'])})`);
+    }
+    /** The 1008 mirror: an unusable server frame closes the socket. */
+    protocolViolation(detail) {
+        this.teardown(new MuxClientError('gateway/protocol', `mux-client: ${detail} — closing the socket`), true);
+    }
+    /** Fail every live stream, drop the table, optionally close the socket. */
+    teardown(error, close = false) {
+        if (this.state !== 'open')
+            return;
+        this.state = 'closed';
+        this.clearWatchdog();
+        for (const stream of this.streams.values()) {
+            stream.retired = true;
+            stream.downlink.fail(error);
+        }
+        this.streams.clear();
+        if (close)
+            this.socket.close();
+    }
+    armWatchdog() {
+        this.clearWatchdog();
+        const timer = setTimeout(() => {
+            this.teardown(new MuxClientError('gateway/heartbeat-silence', `mux-client: no frames for ${String(this.heartbeatIntervalMs * MAX_SILENT_PERIODS)}ms`), true);
+        }, this.heartbeatIntervalMs * MAX_SILENT_PERIODS);
+        this.watchdog = timer;
+    }
+    clearWatchdog() {
+        if (this.watchdog === undefined)
+            return;
+        clearTimeout(this.watchdog);
+        this.watchdog = undefined;
+    }
+}
+/** Validate a wire failure body (`MuxFailure` shape); undefined when malformed. */
+function failureOf(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (typeof value['code'] !== 'string' || typeof value['message'] !== 'string')
+        return undefined;
+    const details = value['details'];
+    return { code: value['code'], message: value['message'], details: isRecord(details) ? details : {} };
+}

package/superd-hub/dist/pack-version.d.ts

@@ -0,0 +1,2 @@
+/** The super-dsh pack version, or 'unknown' when the manifest cannot be read. */
+export declare const PACK_VERSION: string;

package/superd-hub/dist/pack-version.js

@@ -0,0 +1,30 @@
+/**
+ * The super-dsh PACK version (D6 fix): `super-dsh/package.json`'s version —
+ * the number `dsh plugin add` actually versions and the only one that moves
+ * with releases. The hub SUBPACKAGE's own manifest is a constant 0.1.0, which
+ * made both the served `hub.version` and the I2 comparator dead code exactly
+ * in the case they exist for (a stale peer pack).
+ *
+ * Depth contract: this module compiles to `<pack root>/superd-hub/dist/`, so
+ * the pack manifest is exactly two hops up — `../../package.json`. Verified
+ * against the built tree in BOTH shapes: repo (`super-dsh/superd-hub/dist/`
+ * → `super-dsh/package.json`) and the packed tarball (`package/superd-hub/dist/`
+ * → `package/package.json`; npm always includes the root manifest).
+ *
+ * Unparsable or missing → 'unknown' (warn honestly: the I2 comparator treats
+ * an unreadable version as a compatibility fact, which is the truth).
+ */
+import { createRequire } from 'node:module';
+function readPackVersion() {
+    try {
+        const pkg = createRequire(import.meta.url)('../../package.json');
+        if (typeof pkg.version === 'string' && pkg.version !== '')
+            return pkg.version;
+        return 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** The super-dsh pack version, or 'unknown' when the manifest cannot be read. */
+export const PACK_VERSION = readPackVersion();

package/superd-hub/dist/roster.d.ts

@@ -15,6 +15,14 @@ export interface RosterEntry {
     label: string;
     /** True once the adapter's world context is spawned and its target registered. */
     ready: boolean;
+    /**
+     * Owning machine id (m4) for FEDERATED rows (mesh P2 Task 3); absent = this
+     * machine's local world. The a6-keyed row's owner; `agentLinks` projects it
+     * onto AgentLink.machine and derives remote grouping/ordering from it.
+     */
+    machine?: string;
+    /** True once the world's spawn REJECTED (world-join catch) — stays mounted for diagnosis. */
+    failed?: boolean;
 }
 /** Register an agent. Duplicate keys are a plugin bug — throw loud. */
 export declare function registerAgent(entry: RosterEntry): void;
@@ -22,6 +30,8 @@ export declare function registerAgent(entry: RosterEntry): void;
 export declare function unregisterAgent(key: string): void;
 /** Flip readiness (world spawned / disposed). Unknown keys are a plugin bug. */
 export declare function setReady(key: string, ready: boolean): void;
+/** Flip failure (world spawn rejected). Unknown keys are a plugin bug. */
+export declare function setFailed(key: string, failed: boolean): void;
 /** Snapshot copy — callers can hold it without aliasing the roster. */
 export declare function listAgents(): RosterEntry[];
 /** Subscribe to roster changes; returns an unsubscribe function. */

package/superd-hub/dist/roster.js

@@ -9,7 +9,7 @@ function emit() {
 export function registerAgent(entry) {
     if (entries.has(entry.key))
         throw new Error(`roster: duplicate agent key ${entry.key}`);
-    entries.set(entry.key, { ...entry });
+    entries.set(entry.key, { ...entry, failed: entry.failed ?? false });
     emit();
 }
 /** Drop an agent (adapter plugin disposed). */
@@ -25,6 +25,14 @@ export function setReady(key, ready) {
     e.ready = ready;
     emit();
 }
+/** Flip failure (world spawn rejected). Unknown keys are a plugin bug. */
+export function setFailed(key, failed) {
+    const e = entries.get(key);
+    if (!e)
+        throw new Error(`roster: unknown agent ${key}`);
+    e.failed = failed;
+    emit();
+}
 /** Snapshot copy — callers can hold it without aliasing the roster. */
 export function listAgents() {
     return [...entries.values()].map((e) => ({ ...e }));