super-dsh 0.1.6 → 0.1.10-e

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

@@ -14,6 +14,7 @@
  * retired `mountWorld` no-op are gone (git history keeps them), and worlds
  * compose as pure data planes (no webui rows).
  */
+export { handleMeshMachines, registerMeshRpc, MESH_API_BASE, type MeshDeps, type MachinePublicRow } from './mesh-rpc.js';
 export { handleAgentRuntime, registerSelectorRpc, AGENT_RUNTIME_RPC_PATH, registryTargets, type RuntimeTargetSource } from './rpc.js';
 export { registerForeignTarget, unregisterForeignTarget, getTarget, listRuntimeKeys, type ForeignTarget, type GatewayFace } from './targets.js';
 export { registerAgent, unregisterAgent, setReady, setFailed, listAgents, onRosterChanged, type RosterEntry } from './roster.js';
@@ -22,10 +23,14 @@ export { provisionWorldProfile, resolveInstallAnchor, type ProvisionWorldOptions
 export { WorldWebServer, stripLabelFromUrl, type WorldWebRoute, type WorldWebUpgradeRoute, type RealWebServerFace } from './world-web-server.js';
 export { parseClientRequest, serverResponse, serverError, serverResult, wireErrorOf, EnvelopeError, type ClientRequestEnvelope, type WireError } from './envelope.js';
 export { WorldMuxServer, parseClientMessage, defaultFailure, type MuxOpen, type MuxFailure, type WorldMuxOptions } from './world-mux.js';
+export { createRemoteGateway, defaultWsFactory, type RemoteGateway, type RemoteGatewayOptions, type MuxClientSocket } from './mesh-gateway.js';
+export { federateAgents, defederateMachine, defederateStaleMachine, degradeMachine, federatedGatewayOf, startMeshFederation, type FederatedAgent, type FederatedMachine, type FederationWireDeps, } from './mesh-federate.js';
+export { cookieOf, onMeshFederationEvent, emitMachineRemoved, versionWarningFor, runReprobeSweep, startReprobeSweep, REPROBE_SWEEP_DEFAULT_SEC, REPROBE_SWEEP_MIN_SEC, type MeshFederationEvent, type ProbeAgent, type ProbeResult, type PairOutcome, type MachineStatusEntry, type ReprobeSweepDeps, } from './mesh-link.js';
 export { forwardApiCall, forwardWorldFetch, worldMuxOf, writeJson, type CarrierGatewayFace, type ForwardOptions } from './carrier.js';
 export { registerHubRoute, HUB_MOUNT_PATH, HUB_MUX_PATH, type HubRouteOptions } from './hub-route.js';
 export { renderFusionTransport, FUSION_FLAG_GLOBAL, type FusionConfig } from './fusion-transport.js';
 export { createSwitchController, parseLandingTarget, namespacedKey, storageNamespace, seatClickDecision, NATIVE_AGENT, SESSIONS_CURRENT_KEY, SWITCH_FALLBACK_MS, type SwitchHost, type SwitchController, type SwitchOptions, type SeatClickInput, type SeatClickDecision } from './switch-core.js';
+export { ensureAgentId, agentIdMap, type AgentIdMap } from './agent-ids.js';
 export { agentLinks, agentRosterRow, AGENT_ROSTER_GLOBAL, type AgentLink } from './agent-roster.js';
 export { createOwnershipIndex, type OwnershipIndex, type OwnershipRow } from './ownership.js';
 export { registerHostMount, takeHostMount, listHostMounts, noteWorldServer, worldServerOf, type HostMount } from './world-host.js';
@@ -34,4 +39,13 @@ export { buildTrustScript, deriveDefaultPageAuthorities, type BootScriptRow, typ
 export { withSystemHead, type HeadAwareSessionFace, type HeadPlaceholder, type WithSystemHead } from './system-head.js';
 export { default as worldApply, name as worldPluginName, type Config as WorldEntryConfig } from './world-entry.js';
 export { default as joinApply, name as worldJoinPluginName, type Config as WorldJoinConfig } from './world-join.js';
-export { default } from './gateway.js';
+export { createA2aService, A2A_MESSAGE_TEMPLATE, A2A_UNTITLED, A2A_BUFFER_MAX, A2A_NO_SESSION_CLOSE_REASON, A2A_NO_TURN_ACTIVE_NOTE, renderA2aEnvelope, loadConversations, saveConversations, shortIdFor, isDegenerateShortId, migrateConversations, type A2aService, subscribeSessionCompletion, sessionRpc, turnLivenessOf, addressErrorBody, type A2aSessionSource, type A2aGateway, type A2aAddress, type A2aInitiator, type A2aDelivery, type A2aSendRequest, type A2aReceipt, type A2aReceiptOutcome, type A2aReceiptError, type A2aConversationRef, type A2aCompletion, type A2aCompletionCb, type A2aErrorCb, type A2aSubscribeOptions, type A2aStopScope, type A2aStopResult, type A2aBufferedMessage, type A2aBufferInput, type ConversationRow, type ConversationsFile, } from './a2a-service.js';
+export { A2A_WIRE_VERSION, A2A_TITLE_PLACEHOLDER, A2A_ENDPOINT_PATH, A2A_OUTBOX_PATH, A2A_WIRE_TIMEOUT_MS, A2aAddressError, a2aWireFrameOf, isA2aEnvelope, isA2aWireFrame, decodeA2aWireFrame, normalizeA2aTitle, a2aAddressOf, postA2aEnvelope, fetchA2aOutbox, type A2aWireTarget, type A2aWireOrigin, type A2aWireDelivery, type A2aNewConversationEnvelope, type A2aMessageEnvelope, type A2aStopEnvelope, type A2aReplyEnvelope, type A2aNoticeEnvelope, type A2aEnvelope, type A2aWireFrame, type A2aSendReceipt, type A2aStopReceipt, type A2aWireReceipt, type A2aWireOptions, } from './a2a-wire.js';
+export { createA2aIngest, type A2aIngest, type A2aIngestDeps, type A2aReturnRoute, } from './a2a-ingest.js';
+export { loadAgentStatus, recordMachineCollection, recordMachineFailure, collectRemoteMachine, collectLocalMachine, pullOutboxFor, statusSweepLegs, federatedFaceOf, AGENT_STATUS_ROWS_MAX, type AgentStatusRow, type AgentStatusAgent, type AgentStatusMachine, type AgentStatusFile, type RemoteFaceOf, type StatusSweepLegs, } from './agent-status.js';
+export { registerA2aRpc, handleA2aIngestPost, handleA2aOutboxGet, } from './mesh-rpc.js';
+export { deliverReply, deliverNotice, wireCompletionToDelivery, renderA2aRelayText, boundNoticeSummary, A2A_NOTICE_SUMMARY_MAX, type A2aRelaySource, type A2aNoticeSource, type A2aNoticeReason, type A2aDeliveredMessage, type A2aAgentHandle, type A2aDeliveryCtx, type A2aReplyMeta, type A2aNoticeMeta, type A2aReplyDelivery, type A2aDeliveryOutcome, type A2aCompletionSource, } from './a2a-delivery.js';
+export { resolveA2aGatewayFor, localA2aInitiator, createA2aHost, bridgeTypertGateway, type A2aHostOptions, type RawTypertGatewayFace, } from './a2a-host.js';
+export { createSuperdHubTool, parseAgentAddress, RECENT_CONVERSATIONS_MAX, AGENT_STATUS_WINDOW_MAX, HUB_A2A_TITLE_MARKER, UNHOSTED_TITLE, shapeAgentStatusWindow, type AgentStatusEntryRow, EXEC_PLACEHOLDER_NOTE, type HubToolDeps, type HubToolService, type HubRosterView, type HubMachineEntry, type HubAgentEntry, } from './hub-tool.js';
+export { wireHubToolRow, name as a2aRowName, default as a2aRow, type HubToolRowOptions, } from './a2a-row.js';
+export { default, type HubConfig } from './gateway.js';

package/superd-hub/dist/index.js

@@ -14,6 +14,7 @@
  * retired `mountWorld` no-op are gone (git history keeps them), and worlds
  * compose as pure data planes (no webui rows).
  */
+export { handleMeshMachines, registerMeshRpc, MESH_API_BASE } from './mesh-rpc.js';
 export { handleAgentRuntime, registerSelectorRpc, AGENT_RUNTIME_RPC_PATH, registryTargets } from './rpc.js';
 export { registerForeignTarget, unregisterForeignTarget, getTarget, listRuntimeKeys } from './targets.js';
 export { registerAgent, unregisterAgent, setReady, setFailed, listAgents, onRosterChanged } from './roster.js';
@@ -22,10 +23,14 @@ export { provisionWorldProfile, resolveInstallAnchor } from './world-provision.j
 export { WorldWebServer, stripLabelFromUrl } from './world-web-server.js';
 export { parseClientRequest, serverResponse, serverError, serverResult, wireErrorOf, EnvelopeError } from './envelope.js';
 export { WorldMuxServer, parseClientMessage, defaultFailure } from './world-mux.js';
+export { createRemoteGateway, defaultWsFactory } from './mesh-gateway.js';
+export { federateAgents, defederateMachine, defederateStaleMachine, degradeMachine, federatedGatewayOf, startMeshFederation, } from './mesh-federate.js';
+export { cookieOf, onMeshFederationEvent, emitMachineRemoved, versionWarningFor, runReprobeSweep, startReprobeSweep, REPROBE_SWEEP_DEFAULT_SEC, REPROBE_SWEEP_MIN_SEC, } from './mesh-link.js';
 export { forwardApiCall, forwardWorldFetch, worldMuxOf, writeJson } from './carrier.js';
 export { registerHubRoute, HUB_MOUNT_PATH, HUB_MUX_PATH } from './hub-route.js';
 export { renderFusionTransport, FUSION_FLAG_GLOBAL } from './fusion-transport.js';
 export { createSwitchController, parseLandingTarget, namespacedKey, storageNamespace, seatClickDecision, NATIVE_AGENT, SESSIONS_CURRENT_KEY, SWITCH_FALLBACK_MS } from './switch-core.js';
+export { ensureAgentId, agentIdMap } from './agent-ids.js';
 export { agentLinks, agentRosterRow, AGENT_ROSTER_GLOBAL } from './agent-roster.js';
 export { createOwnershipIndex } from './ownership.js';
 export { registerHostMount, takeHostMount, listHostMounts, noteWorldServer, worldServerOf } from './world-host.js';
@@ -34,4 +39,15 @@ export { buildTrustScript, deriveDefaultPageAuthorities, } from './web-trust.js'
 export { withSystemHead } from './system-head.js';
 export { default as worldApply, name as worldPluginName } from './world-entry.js';
 export { default as joinApply, name as worldJoinPluginName } from './world-join.js';
+export { createA2aService, A2A_MESSAGE_TEMPLATE, A2A_UNTITLED, A2A_BUFFER_MAX, A2A_NO_SESSION_CLOSE_REASON, A2A_NO_TURN_ACTIVE_NOTE, renderA2aEnvelope, loadConversations, saveConversations, shortIdFor, isDegenerateShortId, migrateConversations, 
+// (A2aAddressError re-exported via the a2a-wire block below — postoffice R1)
+subscribeSessionCompletion, sessionRpc, turnLivenessOf, addressErrorBody, } from './a2a-service.js';
+export { A2A_WIRE_VERSION, A2A_TITLE_PLACEHOLDER, A2A_ENDPOINT_PATH, A2A_OUTBOX_PATH, A2A_WIRE_TIMEOUT_MS, A2aAddressError, a2aWireFrameOf, isA2aEnvelope, isA2aWireFrame, decodeA2aWireFrame, normalizeA2aTitle, a2aAddressOf, postA2aEnvelope, fetchA2aOutbox, } from './a2a-wire.js';
+export { createA2aIngest, } from './a2a-ingest.js';
+export { loadAgentStatus, recordMachineCollection, recordMachineFailure, collectRemoteMachine, collectLocalMachine, pullOutboxFor, statusSweepLegs, federatedFaceOf, AGENT_STATUS_ROWS_MAX, } from './agent-status.js';
+export { registerA2aRpc, handleA2aIngestPost, handleA2aOutboxGet, } from './mesh-rpc.js';
+export { deliverReply, deliverNotice, wireCompletionToDelivery, renderA2aRelayText, boundNoticeSummary, A2A_NOTICE_SUMMARY_MAX, } from './a2a-delivery.js';
+export { resolveA2aGatewayFor, localA2aInitiator, createA2aHost, bridgeTypertGateway, } from './a2a-host.js';
+export { createSuperdHubTool, parseAgentAddress, RECENT_CONVERSATIONS_MAX, AGENT_STATUS_WINDOW_MAX, HUB_A2A_TITLE_MARKER, UNHOSTED_TITLE, shapeAgentStatusWindow, EXEC_PLACEHOLDER_NOTE, } from './hub-tool.js';
+export { wireHubToolRow, name as a2aRowName, default as a2aRow, } from './a2a-row.js';
 export { default } from './gateway.js';

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

@@ -0,0 +1,45 @@
+/** One remote machine added by pairing (D1: cookie-grade token kept for re-mint). */
+export interface MachineRow {
+    /** Machine id (m4) — minted by the owning machine, adopted as-is (D4). */
+    id: string;
+    /** Operator-facing machine name on the remote. */
+    name: string;
+    /** Display label for the machines UI. */
+    label: string;
+    /** Base origin of the remote hub (`http://host:port`). */
+    origin: string;
+    /** Retained auth token for cookie re-mint; same sensitivity as the cookie itself. */
+    token?: string;
+    /** Last minted request cookie (spec §4): persisted so hub restarts keep the remote's 30-day session instead of forcing a re-mint on every boot. */
+    cookie?: string;
+    enabled: boolean;
+    /** P4 exec knob on the INITIATOR side (spec §5): undefined/true = this machine's agents may exec there; false = the tool leg refuses. */
+    execEnabled?: boolean;
+    /** Epoch ms when this row was added. */
+    addedAt: number;
+}
+/** The whole registry file. `self.id === ''` means not yet minted. */
+export interface MachinesFile {
+    self: {
+        id: string;
+        label: string;
+    };
+    remotes: MachineRow[];
+}
+/** Mint a random short id over [a-z0-9], re-minting on collision with `taken`; loud after 32 attempts. */
+export declare function mintShortId(len: 4 | 6, taken: Iterable<string>): string;
+/** Read the registry; a missing or unreadable/corrupt file degrades to the empty shape (never throws). */
+export declare function loadMachines(home: string): MachinesFile;
+/** Persist the whole registry: recursive mkdir, tmp write, chmod 0600, atomic rename. */
+export declare function saveMachines(home: string, file: MachinesFile): void;
+/** Lazily mint + persist the self identity; an already-minted self is returned unchanged. */
+export declare function ensureSelf(home: string, fallbackLabel: string): {
+    id: string;
+    label: string;
+};
+/** Snapshot copy of the remote rows — callers can hold it without aliasing the store. */
+export declare function listRemotes(home: string): MachineRow[];
+/** Insert or overwrite (same id) one remote row; full read-modify-write persistence. */
+export declare function upsertRemote(home: string, row: MachineRow): void;
+/** Drop one remote row; returns false when the id was not present. */
+export declare function removeRemote(home: string, id: string): boolean;

package/superd-hub/dist/machines.js

@@ -0,0 +1,125 @@
+/**
+ * Machine registry (mesh P1, spec §3.1/§3.3): the persisted identity of
+ * THIS machine (`self`, owner-minted m4 per D4) plus the remote machine
+ * rows created by pairing.
+ *
+ * Pure module — no cordis dependencies. All state lives in
+ * `<home>/superd/machines.json` (0600, atomic tmp+rename writes); every
+ * mutation is a read-modify-write of the whole file with no in-process
+ * cache, which is sufficient at P1 machine counts. A missing or
+ * unreadable file reads as the empty shape (`self.id === ''` = not yet
+ * minted); `ensureSelf` mints lazily on first need and never re-mints.
+ */
+import { randomInt } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const MINT_MAX_ATTEMPTS = 32;
+function machinesPath(home) {
+    return join(home, 'superd', 'machines.json');
+}
+function emptyMachines() {
+    return { self: { id: '', label: '' }, remotes: [] };
+}
+function isMachineRow(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const r = v;
+    return (typeof r.id === 'string' && typeof r.name === 'string' && typeof r.label === 'string' &&
+        typeof r.origin === 'string' && typeof r.enabled === 'boolean' && typeof r.addedAt === 'number' &&
+        (r.token === undefined || typeof r.token === 'string') &&
+        (r.cookie === undefined || typeof r.cookie === 'string') &&
+        (r.execEnabled === undefined || r.execEnabled === true || r.execEnabled === false));
+}
+/** Mint a random short id over [a-z0-9], re-minting on collision with `taken`; loud after 32 attempts. */
+export function mintShortId(len, taken) {
+    const used = new Set(taken);
+    for (let attempt = 0; attempt < MINT_MAX_ATTEMPTS; attempt++) {
+        let id = '';
+        for (let i = 0; i < len; i++)
+            id += ID_ALPHABET[randomInt(ID_ALPHABET.length)];
+        if (!used.has(id))
+            return id;
+    }
+    throw new Error(`machines: short-id space exhausted after ${MINT_MAX_ATTEMPTS} attempts (len=${len})`);
+}
+/** Read the registry; a missing or unreadable/corrupt file degrades to the empty shape (never throws). */
+export function loadMachines(home) {
+    let raw;
+    try {
+        raw = readFileSync(machinesPath(home), 'utf8');
+    }
+    catch {
+        return emptyMachines();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return emptyMachines();
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return emptyMachines();
+    const o = parsed;
+    const self = o.self;
+    if (typeof self !== 'object' || self === null)
+        return emptyMachines();
+    const s = self;
+    if (typeof s.id !== 'string' || typeof s.label !== 'string' || !Array.isArray(o.remotes)) {
+        return emptyMachines();
+    }
+    return { self: { id: s.id, label: s.label }, remotes: o.remotes.filter(isMachineRow) };
+}
+/** Persist the whole registry: recursive mkdir, tmp write, chmod 0600, atomic rename. */
+export function saveMachines(home, file) {
+    if (typeof file.self?.id !== 'string' || typeof file.self?.label !== 'string' || !Array.isArray(file.remotes)) {
+        throw new TypeError('machines: save rejected — file must be {self: {id, label}, remotes: []}');
+    }
+    for (const r of file.remotes) {
+        if (typeof r?.id !== 'string' || r.id === '' || typeof r.name !== 'string' || r.name === '' ||
+            typeof r.origin !== 'string' || r.origin === '') {
+            throw new TypeError('machines: save rejected — row id/name/origin must be non-empty strings');
+        }
+    }
+    const dir = join(home, 'superd');
+    mkdirSync(dir, { recursive: true });
+    const target = machinesPath(home);
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, target);
+}
+/** Lazily mint + persist the self identity; an already-minted self is returned unchanged. */
+export function ensureSelf(home, fallbackLabel) {
+    const file = loadMachines(home);
+    if (file.self.id !== '')
+        return file.self;
+    const taken = new Set([...file.remotes.map((r) => r.id)]);
+    const self = { id: mintShortId(4, taken), label: fallbackLabel };
+    saveMachines(home, { self, remotes: file.remotes });
+    return self;
+}
+/** Snapshot copy of the remote rows — callers can hold it without aliasing the store. */
+export function listRemotes(home) {
+    return loadMachines(home).remotes.map((r) => ({ ...r }));
+}
+/** Insert or overwrite (same id) one remote row; full read-modify-write persistence. */
+export function upsertRemote(home, row) {
+    const file = loadMachines(home);
+    const idx = file.remotes.findIndex((r) => r.id === row.id);
+    if (idx === -1)
+        file.remotes.push({ ...row });
+    else
+        file.remotes[idx] = { ...row };
+    saveMachines(home, file);
+}
+/** Drop one remote row; returns false when the id was not present. */
+export function removeRemote(home, id) {
+    const file = loadMachines(home);
+    const remotes = file.remotes.filter((r) => r.id !== id);
+    if (remotes.length === file.remotes.length)
+        return false;
+    saveMachines(home, { self: file.self, remotes });
+    return true;
+}

package/superd-hub/dist/mesh-federate.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Federation registrar (machine-mesh P2 Task 3): adopts a paired machine's
+ * PROBED roster into the LOCAL registries, so a remote agent is addressable
+ * and visible exactly like a local world:
+ *
+ *   targets.ts  `registerForeignTarget({key: a6, gateway})` — the a6-keyed
+ *               wire gateway (Task 2's `createRemoteGateway`), so the `/hub`
+ *               family demuxes `?agent=<a6>` to the peer's `/hub` family
+ *               carrying the remote RUNTIME key (`?agent=codex` at the peer).
+ *               The peer's NATIVE agent row federates the same way — its
+ *               row carries a minted a6 plus `key:'native'`, and its gateway
+ *               is built with the NATIVE face (Task 2's `face` option): the
+ *               peer's ctx0 `/api` surface, no demux key — exactly how a
+ *               browser ON the peer consumes its native DSH (the `/hub`
+ *               family would 404 `?agent=native` as foreign-only).
+ *   roster.ts   one row per agent: `{key: a6, label: '<Label> · <machine
+ *               name>', machine: m4, ready, failed}` — `machine` set marks
+ *               the row federated; `agentLinks` projects it into the UI rows.
+ *
+ * The a6 IS the local registration key (spec §3.2): runtime keys are NOT
+ * reused across machines (a remote `codex` would collide with — and silently
+ * replace — the local codex world), while a6s are owner-minted 6-char ids
+ * adopted verbatim. EVERY row federates, the peer's native included — the
+ * face selector is `agent.key === 'native'`, never an a6 test (only
+ * `'native'` is pre-screened as a hard reserve). Cross-machine a6 collision
+ * (two peers minting the same id, p ≈ 36⁻¹² per pair) and a6-vs-local-key
+ * collision (p ≈ 36⁻⁶ per adoption) are accepted at P2 machine counts — the
+ * registry replaces last-write-wins, same ruling as spec §3.1's m4 collision
+ * roughness.
+ *
+ * ## Import direction (frozen): mesh-federate → {mesh-link, mesh-gateway,
+ * ## roster, targets} — NEVER the reverse. mesh-link emits machine lifecycle
+ * ## events (`onMeshFederationEvent`: federated / degraded / defederated);
+ * ## this module subscribes at wiring time ({@link startMeshFederation},
+ * ## called once from gateway.ts apply). mesh-rpc's DELETE path announces
+ * ## removals through mesh-link's {@link emitMachineRemoved} — no route-module
+ * ## federation logic anywhere.
+ *
+ * ## Gateway memo — one `RemoteGateway` per (m4, a6), built by the wiring's
+ * ## factory, keyed by a6. Reused across probe events (identity-stable: a
+ * ## reprobe does not rebuild a live gateway); rebuilt when the peer facts
+ * ## change (origin moved, remote runtime key re-minted); disposed and
+ * ## forgotten on defederate. The cookie is NOT memoized — the gateway reads
+ * ## it per call through `cookieOf(m4, home)` (jar-fronted), so a re-minted
+ * ## cookie is picked up by the NEXT call with zero rebuilds.
+ *
+ * ## Degrade semantics (spec §6.3): a failed probe KEEPS the machine's rows
+ * ## and flips `ready` false — visible but not servable. Defederate (machine
+ * ## removal) and stale-convergence (an agent vanished from the peer's
+ * ## roster) are the only row-removing paths.
+ */
+import { type MuxClientSocket } from './mesh-gateway.js';
+import { type GatewayFace } from './targets.js';
+/** One remote agent as adopted from a probe — mesh-link's `ProbeAgent` shape
+ *  (kept structural so callers and tests can pass plain objects). */
+export interface FederatedAgent {
+    /** The remote-owner-minted a6 — the LOCAL registration key. */
+    id: string;
+    /** The remote RUNTIME key (`codex`, `omp`, …) — the peer's `?agent=` demux
+     *  key on the wire; `'native'` selects the NATIVE face (peer ctx0 `/api`, no
+     *  demux key) in the wiring's gateway factory. An EMPTY key cannot address
+     *  anything at the peer; {@link gatewayFor} falls back to the a6 there
+     *  (T3-M1) rather than shipping `?agent=` on the wire. */
+    key: string;
+    label: string;
+    ready: boolean;
+    failed: boolean;
+}
+/** The machine half of a federation fact (m4 + display name for label suffixes). */
+export interface FederatedMachine {
+    id: string;
+    name: string;
+}
+/** Wiring deps: the hub home (cookie row fallback) + test seams for the wire. */
+export interface FederationWireDeps {
+    home: string;
+    fetchImpl?: typeof fetch;
+    wsFactory?: (url: string, headers: Record<string, string>) => MuxClientSocket;
+}
+/**
+ * Register one machine's probed agents — IDEMPOTENT replace per a6: a row
+ * whose key/label/machine/ready/failed all match the live registry is left
+ * untouched (zero roster churn on repeated probes); a changed row is
+ * unregistered then re-registered (`registerAgent` throws on duplicate keys —
+ * federate always unregisters first, so repeated probes never throw).
+ * Agents with an empty id (unkeyable) are skipped; EVERY keyed row
+ * federates — the peer's native row included (its `key:'native'` selects the
+ * native gateway face; see {@link gatewayFor}).
+ * @param machine - the peer's identity (m4 + name; the name lands in every label suffix).
+ * @param agents - the probe's agent snapshot (a6 `id`, remote `key`, label, ready, failed).
+ * @param gatewayOf - gateway factory receiving the FULL agent row (the wiring
+ * derives the face from `agent.key`; tests inject fakes) — called once per
+ * (re)registration and once per converged-row target re-arm.
+ */
+export declare function federateAgents(machine: FederatedMachine, agents: FederatedAgent[], gatewayOf: (agent: FederatedAgent) => GatewayFace): void;
+/**
+ * Drop EVERY federated row of one machine (mesh-rpc DELETE / unpair): roster
+ * rows, target registrations, and the memoized wire gateways (disposed —
+ * in-flight streams fail `gateway/disposed` per Task 2's contract).
+ */
+export declare function defederateMachine(m4: string): void;
+/**
+ * Roster convergence: unregister the machine's rows whose a6s are ABSENT from
+ * the peer's latest probe (the agent was removed/renamed remotely) — live
+ * agents are left to {@link federateAgents}.
+ * @param m4 - the machine id.
+ * @param liveA6s - the a6 set of the latest successful probe.
+ */
+export declare function defederateStaleMachine(m4: string, liveA6s: ReadonlySet<string>): void;
+/**
+ * Degrade one machine's rows after a failed probe (unreachable peer or
+ * auth-expired cookie): rows are KEPT, `ready` flipped false, `failed`
+ * untouched — visible but not servable (spec §6.3; the orchestra downgrade).
+ * Rows already degraded are left alone (no roster churn); local rows are
+ * never touched.
+ */
+export declare function degradeMachine(m4: string): void;
+/**
+ * The federated gateway of one a6 — the `/hub` demux's federation-table step
+ * (exact a6 match; the same pair `federateAgents` registers into the shared
+ * target registry, so the two sources never disagree). Undefined for local
+ * labels and unknown/defederated a6s.
+ */
+export declare function federatedGatewayOf(a6: string): GatewayFace | undefined;
+/**
+ * Wire the registrar to mesh-link's machine lifecycle events (called ONCE at
+ * plugin activation — gateway.ts apply):
+ *
+ *  - `federated` → {@link federateAgents} (converge onto the probe snapshot)
+ *    + {@link defederateStaleMachine} (drop vanished agents);
+ *  - `degraded` → {@link degradeMachine} (rows kept, ready=false);
+ *  - `defederated` → {@link defederateMachine} (mesh-rpc DELETE).
+ *
+ * Re-probing a machine after a hub restart rebuilds its federation from the
+ * probe alone — the events are the single rebuild path.
+ * @returns the disposer (unsubscribes; registered rows are left as-is).
+ */
+export declare function startMeshFederation(deps: FederationWireDeps): () => void;

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

@@ -0,0 +1,223 @@
+/**
+ * Federation registrar (machine-mesh P2 Task 3): adopts a paired machine's
+ * PROBED roster into the LOCAL registries, so a remote agent is addressable
+ * and visible exactly like a local world:
+ *
+ *   targets.ts  `registerForeignTarget({key: a6, gateway})` — the a6-keyed
+ *               wire gateway (Task 2's `createRemoteGateway`), so the `/hub`
+ *               family demuxes `?agent=<a6>` to the peer's `/hub` family
+ *               carrying the remote RUNTIME key (`?agent=codex` at the peer).
+ *               The peer's NATIVE agent row federates the same way — its
+ *               row carries a minted a6 plus `key:'native'`, and its gateway
+ *               is built with the NATIVE face (Task 2's `face` option): the
+ *               peer's ctx0 `/api` surface, no demux key — exactly how a
+ *               browser ON the peer consumes its native DSH (the `/hub`
+ *               family would 404 `?agent=native` as foreign-only).
+ *   roster.ts   one row per agent: `{key: a6, label: '<Label> · <machine
+ *               name>', machine: m4, ready, failed}` — `machine` set marks
+ *               the row federated; `agentLinks` projects it into the UI rows.
+ *
+ * The a6 IS the local registration key (spec §3.2): runtime keys are NOT
+ * reused across machines (a remote `codex` would collide with — and silently
+ * replace — the local codex world), while a6s are owner-minted 6-char ids
+ * adopted verbatim. EVERY row federates, the peer's native included — the
+ * face selector is `agent.key === 'native'`, never an a6 test (only
+ * `'native'` is pre-screened as a hard reserve). Cross-machine a6 collision
+ * (two peers minting the same id, p ≈ 36⁻¹² per pair) and a6-vs-local-key
+ * collision (p ≈ 36⁻⁶ per adoption) are accepted at P2 machine counts — the
+ * registry replaces last-write-wins, same ruling as spec §3.1's m4 collision
+ * roughness.
+ *
+ * ## Import direction (frozen): mesh-federate → {mesh-link, mesh-gateway,
+ * ## roster, targets} — NEVER the reverse. mesh-link emits machine lifecycle
+ * ## events (`onMeshFederationEvent`: federated / degraded / defederated);
+ * ## this module subscribes at wiring time ({@link startMeshFederation},
+ * ## called once from gateway.ts apply). mesh-rpc's DELETE path announces
+ * ## removals through mesh-link's {@link emitMachineRemoved} — no route-module
+ * ## federation logic anywhere.
+ *
+ * ## Gateway memo — one `RemoteGateway` per (m4, a6), built by the wiring's
+ * ## factory, keyed by a6. Reused across probe events (identity-stable: a
+ * ## reprobe does not rebuild a live gateway); rebuilt when the peer facts
+ * ## change (origin moved, remote runtime key re-minted); disposed and
+ * ## forgotten on defederate. The cookie is NOT memoized — the gateway reads
+ * ## it per call through `cookieOf(m4, home)` (jar-fronted), so a re-minted
+ * ## cookie is picked up by the NEXT call with zero rebuilds.
+ *
+ * ## Degrade semantics (spec §6.3): a failed probe KEEPS the machine's rows
+ * ## and flips `ready` false — visible but not servable. Defederate (machine
+ * ## removal) and stale-convergence (an agent vanished from the peer's
+ * ## roster) are the only row-removing paths.
+ */
+import { createRemoteGateway } from './mesh-gateway.js';
+import { cookieOf, onMeshFederationEvent } from './mesh-link.js';
+import { registerAgent, unregisterAgent, listAgents, setReady } from './roster.js';
+import { registerForeignTarget, unregisterForeignTarget, getTarget } from './targets.js';
+const gatewayMemo = new Map();
+/** Roster rows of one machine (its a6s), from the live registry. */
+function rowsOf(m4) {
+    return listAgents().filter((e) => (e.machine ?? 'local') === m4);
+}
+/** Unregister one federated a6 from both registries + drop its memo gateway. */
+function dropA6(a6) {
+    if (listAgents().some((e) => e.key === a6))
+        unregisterAgent(a6); // guard: unregister no-ops still emit roster churn
+    unregisterForeignTarget(a6);
+    const memo = gatewayMemo.get(a6);
+    if (memo !== undefined) {
+        gatewayMemo.delete(a6);
+        memo.gateway.dispose();
+    }
+}
+/**
+ * Register one machine's probed agents — IDEMPOTENT replace per a6: a row
+ * whose key/label/machine/ready/failed all match the live registry is left
+ * untouched (zero roster churn on repeated probes); a changed row is
+ * unregistered then re-registered (`registerAgent` throws on duplicate keys —
+ * federate always unregisters first, so repeated probes never throw).
+ * Agents with an empty id (unkeyable) are skipped; EVERY keyed row
+ * federates — the peer's native row included (its `key:'native'` selects the
+ * native gateway face; see {@link gatewayFor}).
+ * @param machine - the peer's identity (m4 + name; the name lands in every label suffix).
+ * @param agents - the probe's agent snapshot (a6 `id`, remote `key`, label, ready, failed).
+ * @param gatewayOf - gateway factory receiving the FULL agent row (the wiring
+ * derives the face from `agent.key`; tests inject fakes) — called once per
+ * (re)registration and once per converged-row target re-arm.
+ */
+export function federateAgents(machine, agents, gatewayOf) {
+    for (const agent of agents) {
+        if (agent.id === '')
+            continue;
+        const desired = {
+            key: agent.id,
+            label: `${agent.label} · ${machine.name}`,
+            machine: machine.id,
+            ready: agent.ready === true,
+            failed: agent.failed === true,
+        };
+        const existing = listAgents().find((e) => e.key === agent.id);
+        if (existing !== undefined
+            && existing.label === desired.label
+            && existing.ready === desired.ready
+            && (existing.failed ?? false) === desired.failed
+            && (existing.machine ?? 'local') === machine.id) {
+            // Converged — but never trust a half-state: the roster row may survive
+            // a target that something else dropped. Re-arm the registration only.
+            if (getTarget(agent.id) === undefined)
+                registerForeignTarget({ key: agent.id, gateway: gatewayOf(agent) });
+            continue;
+        }
+        if (existing !== undefined)
+            unregisterAgent(agent.id); // defeats registerAgent's duplicate-key throw
+        unregisterForeignTarget(agent.id); // explicit replace, not map-overwrite
+        registerForeignTarget({ key: agent.id, gateway: gatewayOf(agent) });
+        registerAgent(desired);
+    }
+}
+/**
+ * Drop EVERY federated row of one machine (mesh-rpc DELETE / unpair): roster
+ * rows, target registrations, and the memoized wire gateways (disposed —
+ * in-flight streams fail `gateway/disposed` per Task 2's contract).
+ */
+export function defederateMachine(m4) {
+    for (const row of rowsOf(m4))
+        dropA6(row.key);
+    // Belt: memo entries whose roster rows vanished independently still die with the machine.
+    for (const [a6, memo] of [...gatewayMemo]) {
+        if (memo.machineId === m4)
+            dropA6(a6);
+    }
+}
+/**
+ * Roster convergence: unregister the machine's rows whose a6s are ABSENT from
+ * the peer's latest probe (the agent was removed/renamed remotely) — live
+ * agents are left to {@link federateAgents}.
+ * @param m4 - the machine id.
+ * @param liveA6s - the a6 set of the latest successful probe.
+ */
+export function defederateStaleMachine(m4, liveA6s) {
+    for (const row of rowsOf(m4)) {
+        if (!liveA6s.has(row.key))
+            dropA6(row.key);
+    }
+}
+/**
+ * Degrade one machine's rows after a failed probe (unreachable peer or
+ * auth-expired cookie): rows are KEPT, `ready` flipped false, `failed`
+ * untouched — visible but not servable (spec §6.3; the orchestra downgrade).
+ * Rows already degraded are left alone (no roster churn); local rows are
+ * never touched.
+ */
+export function degradeMachine(m4) {
+    for (const row of rowsOf(m4)) {
+        if (row.ready !== false)
+            setReady(row.key, false);
+    }
+}
+/**
+ * The federated gateway of one a6 — the `/hub` demux's federation-table step
+ * (exact a6 match; the same pair `federateAgents` registers into the shared
+ * target registry, so the two sources never disagree). Undefined for local
+ * labels and unknown/defederated a6s.
+ */
+export function federatedGatewayOf(a6) {
+    return gatewayMemo.get(a6)?.gateway;
+}
+/** The wiring's gateway factory: memoized per a6, rebuilt on peer-fact
+ * change (origin, remote runtime key, or face flip). The FACE is selected
+ * from the agent ROW — `key === 'native'` → the peer's ctx0 `/api` surface,
+ * anything else → the `/hub` family with the runtime-key demux. */
+function gatewayFor(event, agent, deps) {
+    const a6 = agent.id;
+    const face = agent.key === 'native' ? 'native' : 'foreign';
+    // T3-M1: an empty remote key must not ride the wire as `?agent=` (the
+    // nullish class miss — '' is not nullish); fall back to the a6 so the
+    // registration stays addressable and the wrong key fails LOUDLY at the
+    // peer (its demux 404s the unknown key) instead of silently here.
+    const agentKey = agent.key !== '' ? agent.key : agent.id;
+    const memo = gatewayMemo.get(a6);
+    if (memo !== undefined && memo.machineId === event.machineId && memo.origin === event.origin && memo.agentKey === agentKey && memo.face === face) {
+        return memo.gateway;
+    }
+    if (memo !== undefined) {
+        gatewayMemo.delete(a6);
+        memo.gateway.dispose();
+    }
+    const gateway = createRemoteGateway({
+        origin: event.origin,
+        agentKey,
+        face,
+        cookie: () => cookieOf(event.machineId, deps.home),
+        fetchImpl: deps.fetchImpl,
+        wsFactory: deps.wsFactory,
+    });
+    gatewayMemo.set(a6, { gateway, machineId: event.machineId, origin: event.origin, agentKey, face });
+    return gateway;
+}
+/**
+ * Wire the registrar to mesh-link's machine lifecycle events (called ONCE at
+ * plugin activation — gateway.ts apply):
+ *
+ *  - `federated` → {@link federateAgents} (converge onto the probe snapshot)
+ *    + {@link defederateStaleMachine} (drop vanished agents);
+ *  - `degraded` → {@link degradeMachine} (rows kept, ready=false);
+ *  - `defederated` → {@link defederateMachine} (mesh-rpc DELETE).
+ *
+ * Re-probing a machine after a hub restart rebuilds its federation from the
+ * probe alone — the events are the single rebuild path.
+ * @returns the disposer (unsubscribes; registered rows are left as-is).
+ */
+export function startMeshFederation(deps) {
+    return onMeshFederationEvent((event) => {
+        if (event.type === 'federated') {
+            federateAgents({ id: event.machineId, name: event.machineName }, event.agents, (agent) => gatewayFor(event, agent, deps));
+            defederateStaleMachine(event.machineId, new Set(event.agents.map((a) => a.id)));
+        }
+        else if (event.type === 'degraded') {
+            degradeMachine(event.machineId);
+        }
+        else {
+            defederateMachine(event.machineId);
+        }
+    });
+}