super-dsh 0.1.12 → 0.3.0

package/superd-hub/dist/client/mesh-groups.d.ts

@@ -9,8 +9,8 @@
  * stay correct even when the wire order changes or the roster is seeded
  * from a stale baked global.
  *
- * The label map comes from `fetchMachines()` (mesh-api.ts): machine label,
- * falling back to the name, falling back to the raw m4 —
+ * The label map comes from `fetchMachines()` (mesh-api.ts): the machine's
+ * `name` — its sole display identity — keyed by id;
  * {@link machineLabelsFrom} builds it, and a machine the registry no longer
  * knows simply keeps its raw m4 as the section label (never a crash).
  *
@@ -27,13 +27,13 @@ import type { AgentLink } from './roster.js';
 export declare const LOCAL_MACHINE_KEY = "local";
 /** The LOCAL section's fixed display label — this machine needs no registry row to be named. */
 export declare const LOCAL_MACHINE_LABEL = "This machine";
-/** One machine's section: its grouping key, its display label, and its rows in roster order. */
+/** One machine's section: its grouping key, its display label, and its rows in DSH-first alphabetical order. */
 export interface MachineAgentGroup {
     /** The grouping key: {@link LOCAL_MACHINE_KEY} or the owning machine's m4. */
     readonly key: string;
     /** The section heading: the machine's display label ({@link LOCAL_MACHINE_LABEL} for local, the raw key when no label is known). */
     readonly label: string;
-    /** This machine's roster rows, keeping the roster's own order. */
+    /** This machine's roster rows: DSH first, then alphabetical (spec hub-roster-identity §4). */
     readonly agents: readonly AgentLink[];
 }
 /**
@@ -41,10 +41,11 @@ export interface MachineAgentGroup {
  * roster rows: the LOCAL group first (label {@link LOCAL_MACHINE_LABEL};
  * rows whose `machine` is `'local'` or absent), then one group per remote
  * machine sorted by display label (code-unit order) with the machine key as
- * the tiebreak. Members keep the roster's given order inside their group;
- * groups only exist for machines actually present in the roster (no empty
- * local section when every row is federated). An unknown label map entry —
- * missing, or an empty string — falls back to the raw machine key.
+ * the tiebreak. Members are ordered DSH-first, then alphabetical, inside
+ * every group; groups only exist for machines actually present in the
+ * roster (no empty local section when every row is federated). An unknown
+ * label map entry — missing, or an empty string — falls back to the raw
+ * machine key.
  *
  * @param links - the roster rows (any order; the section order is derived, not inherited).
  * @param machineLabels - machine key (m4) → display label; the machines API answer via {@link machineLabelsFrom}.
@@ -53,9 +54,10 @@ export interface MachineAgentGroup {
 export declare function groupByMachine(links: readonly AgentLink[], machineLabels: Readonly<Record<string, string>>): MachineAgentGroup[];
 /**
  * The machines API answer → the grouping label map: every remote row's
- * `id → label` (mesh-api's coercion already collapsed an empty label to the
- * machine name) plus the self block's own `m4 → label`. An absent list is
- * the empty map — the caller's degrade-to-flat trigger, never a throw.
+ * `id → name` (the machine's sole display identity — the retired separate
+ * label column no longer exists on the wire) plus the self block's own
+ * `m4 → label`. An absent list is the empty map — the caller's
+ * degrade-to-flat trigger, never a throw.
  *
  * @param list - the coerced `fetchMachines()` answer, when it succeeded.
  * @returns machine key → display label (the raw key stays absent, not mapped).

package/superd-hub/dist/client/mesh-groups.js

@@ -6,15 +6,32 @@ export const LOCAL_MACHINE_LABEL = 'This machine';
 function isLocalMachine(machine) {
     return machine === undefined || machine === LOCAL_MACHINE_KEY;
 }
+/**
+ * One group's member order (spec hub-roster-identity §4, uniform for local
+ * and remote machines): the native DSH row first, then label code-unit order
+ * with the key as the tiebreak.
+ */
+function sortMembers(agents) {
+    return [...agents].sort((a, b) => {
+        const nativeA = (a.runtimeId ?? a.key) === 'native' ? 0 : 1;
+        const nativeB = (b.runtimeId ?? b.key) === 'native' ? 0 : 1;
+        if (nativeA !== nativeB)
+            return nativeA - nativeB;
+        if (a.label !== b.label)
+            return a.label < b.label ? -1 : 1;
+        return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+    });
+}
 /**
  * Group a roster into machine sections for the switch menu and the Hub
  * roster rows: the LOCAL group first (label {@link LOCAL_MACHINE_LABEL};
  * rows whose `machine` is `'local'` or absent), then one group per remote
  * machine sorted by display label (code-unit order) with the machine key as
- * the tiebreak. Members keep the roster's given order inside their group;
- * groups only exist for machines actually present in the roster (no empty
- * local section when every row is federated). An unknown label map entry —
- * missing, or an empty string — falls back to the raw machine key.
+ * the tiebreak. Members are ordered DSH-first, then alphabetical, inside
+ * every group; groups only exist for machines actually present in the
+ * roster (no empty local section when every row is federated). An unknown
+ * label map entry — missing, or an empty string — falls back to the raw
+ * machine key.
  *
  * @param links - the roster rows (any order; the section order is derived, not inherited).
  * @param machineLabels - machine key (m4) → display label; the machines API answer via {@link machineLabelsFrom}.
@@ -40,15 +57,18 @@ export function groupByMachine(links, machineLabels) {
         return typeof label === 'string' && label !== '' ? label : key;
     };
     const remote = [...byKey.entries()]
-        .map(([key, agents]) => ({ key, label: labelOf(key), agents }))
+        .map(([key, agents]) => ({ key, label: labelOf(key), agents: sortMembers(agents) }))
         .sort((a, b) => (a.label !== b.label ? (a.label < b.label ? -1 : 1) : (a.key < b.key ? -1 : a.key > b.key ? 1 : 0)));
-    return local.length > 0 ? [{ key: LOCAL_MACHINE_KEY, label: LOCAL_MACHINE_LABEL, agents: local }, ...remote] : remote;
+    return local.length > 0
+        ? [{ key: LOCAL_MACHINE_KEY, label: LOCAL_MACHINE_LABEL, agents: sortMembers(local) }, ...remote]
+        : remote;
 }
 /**
  * The machines API answer → the grouping label map: every remote row's
- * `id → label` (mesh-api's coercion already collapsed an empty label to the
- * machine name) plus the self block's own `m4 → label`. An absent list is
- * the empty map — the caller's degrade-to-flat trigger, never a throw.
+ * `id → name` (the machine's sole display identity — the retired separate
+ * label column no longer exists on the wire) plus the self block's own
+ * `m4 → label`. An absent list is the empty map — the caller's
+ * degrade-to-flat trigger, never a throw.
  *
  * @param list - the coerced `fetchMachines()` answer, when it succeeded.
  * @returns machine key → display label (the raw key stays absent, not mapped).
@@ -58,7 +78,7 @@ export function machineLabelsFrom(list) {
     if (list === undefined)
         return labels;
     for (const machine of list.machines) {
-        labels[machine.id] = machine.label !== '' ? machine.label : machine.name;
+        labels[machine.id] = machine.name;
     }
     if (list.self !== undefined)
         labels[list.self.id] = list.self.label;

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

@@ -1,22 +1,13 @@
-/**
- * Shared roster projection for the client half: the runtime list every Hub
- * switch surface (the HubPanelIcon chevron menu, the HubPage Agent Runtimes
- * rows — the sole agent-switch surface since the T-B RuntimeSeat retirement)
- * renders. Source of truth = the hub's read-only `/api/agent-runtime` face;
- * the baked `window.__DSH_AGENT_ROSTER__` global only seeds the first paint
- * (a world page's baked copy can be stale, so the wire answer is
- * authoritative).
- *
- * Node-safe by construction (no DOM globals, fetch only inside functions) —
- * the host tsc dual-emits this file to `dist/client/roster.js` so
- * test/client-mesh-groups.test.mjs can pin the coercion under `node --test`
- * (the mesh-api/mesh-groups precedent).
- *
- * @module superd-hub/client/roster
- */
 /** One runtime as the roster hands it over: key, display label, mount path, machine. */
 export interface AgentLink {
     readonly key: string;
+    /**
+     * The unified runtime identifier (adapter package name, `native` for DSH;
+     * spec hub-roster-identity §1) — the icon-matching key across machines.
+     * Optional at the parse boundary: an older host's rows lack it and the
+     * mark falls back to `runtimeIdOf(key)`.
+     */
+    readonly runtimeId?: string;
     readonly label: string;
     readonly path: string;
     /**

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

@@ -14,8 +14,9 @@
  *
  * @module superd-hub/client/roster
  */
+import { runtimeIdOf } from '../roster.js';
 /** The native runtime every composition can fall back to. */
-export const NATIVE_LINK = { key: 'native', label: 'DSH', path: '/', machine: 'local', ready: true, failed: false };
+export const NATIVE_LINK = { key: 'native', runtimeId: 'native', label: 'DSH', path: '/', machine: 'local', ready: true, failed: false };
 /** Labels for the read-only face's bare keys (it reports keys, not labels). */
 const FALLBACK_LABELS = {
     native: 'DSH',
@@ -40,11 +41,12 @@ function coerceAgents(raw) {
     for (const entry of raw) {
         if (typeof entry !== 'object' || entry === null)
             continue;
-        const { key, label, path, machine } = entry;
+        const { key, label, path, machine, runtimeId } = entry;
         if (typeof key !== 'string' || typeof path !== 'string')
             continue;
         links.push({
             key,
+            runtimeId: typeof runtimeId === 'string' && runtimeId !== '' ? runtimeId : undefined,
             label: typeof label === 'string' ? label : (FALLBACK_LABELS[key] ?? key),
             path,
             // Passthrough (mesh P2 Task 4): a string machine id rides verbatim
@@ -93,7 +95,7 @@ export async function fetchRoster() {
                 continue;
             links.push(key === 'native'
                 ? NATIVE_LINK
-                : { key, label: FALLBACK_LABELS[key] ?? key, path: `/${key}/`, machine: 'local', ready: key === 'native' });
+                : { key, runtimeId: runtimeIdOf(key), label: FALLBACK_LABELS[key] ?? key, path: `/${key}/`, machine: 'local', ready: key === 'native' });
         }
         if (links.length > 0)
             return links;

package/superd-hub/dist/fusion-transport.d.ts

@@ -24,8 +24,11 @@
  *          restored after, so an agent switch re-targets the same anchor;
  *       5. `Storage.prototype` get/set/removeItem — namespace read at call
  *          time: native = no prefix, foreign = `'<label>:'`.
- *   - one control-plane exemption: `/api/agent-runtime` is NEVER rewritten —
- *     the roster always talks to ctx0, so the user can always switch back.
+ *   - two control-plane exemptions: `/api/agent-runtime` is NEVER rewritten —
+ *     the roster always talks to ctx0, so the user can always switch back —
+ *     and neither is the hub's own `/api/superd` family (machines/a2a/exec),
+ *     so the Hub panel's machine map + roster grouping stay live while a
+ *     remote agent is active (2026-10-08 user report).
  * Native mode is zero-interference: every patched face passes its exact
  * arguments through untouched.
  *
@@ -43,11 +46,10 @@
  * Injection (the web-trust emission path, ordered AFTER it — spec §3.4 hard
  * constraint): the row is a `webserver/index-inject` head script pushed by the
  * `superd-fusion-transport` component, composed through the composite row
- * `super-dsh/fusion-transport` positioned after `super-dsh/web-trust`. Both
- * components defer their listener registration behind `inject(['webServer'])`,
- * so cordis's FIFO effect order guarantees trust pushes first and fusion
- * pushes last — the non-merging `if(!window.__DSH_TRANSPORT__)` verdict in the
- * trust script is always evaluated before anything could own that global.
+ * `super-dsh/fusion-transport` positioned after `better-dsh/web-trust`. Both
+ * components wait for `webServer`; Better Dash prepends its ownership script
+ * to the injection table, so asynchronous module loading cannot place it after
+ * the fusion script. The ownership verdict executes before application boot.
  * Row gate: the row config `enabled`, ON by default — the composite patch
  * composing this row is the switch. `enabled: false` (or `disabled: true`)
  * leaves the component dormant: no listener, no script, no flag global.
@@ -125,9 +127,8 @@ export declare const inject: string[];
 /**
  * Mount the fusion injection: one `webserver/index-inject` listener pushing
  * the rendered head script row — the same emission path as the web-trust
- * component, composed AFTER it (the composite row order is load order, and
- * both components register their listeners behind `inject(['webServer'])`, so
- * cordis's FIFO effect order pushes the fusion row last; spec §3.4) — plus
+ * component, composed AFTER it. Better Dash prepends its ownership verdict to the public injection table,
+ * so asynchronous module loading cannot invert the script order (spec §3.4), plus
  * the {@link FUSION_FLAG_GLOBAL} baked global row (Task 4): one gate, both
  * halves.
  *

package/superd-hub/dist/fusion-transport.js

@@ -24,8 +24,11 @@
  *          restored after, so an agent switch re-targets the same anchor;
  *       5. `Storage.prototype` get/set/removeItem — namespace read at call
  *          time: native = no prefix, foreign = `'<label>:'`.
- *   - one control-plane exemption: `/api/agent-runtime` is NEVER rewritten —
- *     the roster always talks to ctx0, so the user can always switch back.
+ *   - two control-plane exemptions: `/api/agent-runtime` is NEVER rewritten —
+ *     the roster always talks to ctx0, so the user can always switch back —
+ *     and neither is the hub's own `/api/superd` family (machines/a2a/exec),
+ *     so the Hub panel's machine map + roster grouping stay live while a
+ *     remote agent is active (2026-10-08 user report).
  * Native mode is zero-interference: every patched face passes its exact
  * arguments through untouched.
  *
@@ -43,11 +46,10 @@
  * Injection (the web-trust emission path, ordered AFTER it — spec §3.4 hard
  * constraint): the row is a `webserver/index-inject` head script pushed by the
  * `superd-fusion-transport` component, composed through the composite row
- * `super-dsh/fusion-transport` positioned after `super-dsh/web-trust`. Both
- * components defer their listener registration behind `inject(['webServer'])`,
- * so cordis's FIFO effect order guarantees trust pushes first and fusion
- * pushes last — the non-merging `if(!window.__DSH_TRANSPORT__)` verdict in the
- * trust script is always evaluated before anything could own that global.
+ * `super-dsh/fusion-transport` positioned after `better-dsh/web-trust`. Both
+ * components wait for `webServer`; Better Dash prepends its ownership script
+ * to the injection table, so asynchronous module loading cannot place it after
+ * the fusion script. The ownership verdict executes before application boot.
  * Row gate: the row config `enabled`, ON by default — the composite patch
  * composing this row is the switch. `enabled: false` (or `disabled: true`)
  * leaves the component dormant: no listener, no script, no flag global.
@@ -95,7 +97,13 @@ try {
 
   // ---- the one rewrite rule: '/api...' becomes '/hub/api...' + '?agent=<label>' ----
   const HUB = '/hub'
+  // Control planes: the roster AND the hub's own '/api/superd' family
+  // (machines/a2a/exec — mesh-rpc.ts) always talk to ctx0. A foreign plane
+  // answers neither (a peer's world has no mesh routes), so a rewritten
+  // machines GET 404s and the Hub panel loses its machine map + roster
+  // grouping the moment a remote agent is active (2026-10-08 user report).
   const CONTROL = '/api/agent-runtime'
+  const CONTROL_PREFIX = '/api/superd'
   const origin = () => {
     const loc = g.location
     if (loc !== undefined && typeof loc.origin === 'string' && loc.origin !== 'null') return loc.origin
@@ -110,8 +118,11 @@ try {
     }
   }
   const isApiPath = (path) => path === '/api' || path.startsWith('/api/')
-  // Control-plane exemption: the roster control plane always hits ctx0.
+  // Control-plane exemption: the roster and the '/api/superd' family always
+  // hit ctx0, so the switch surfaces and the Hub panel work while any agent
+  // is active.
   const isExempt = (path) => path === CONTROL || path.startsWith(CONTROL + '/')
+    || path === CONTROL_PREFIX || path.startsWith(CONTROL_PREFIX + '/')
   // Key compare matches the server demux shape: searchParams.get('agent')
   // looks up PERCENT-DECODED keys, so '%61gent=x' demuxes as agent=x and the
   // surgery must strip those spellings too (+' ' wins the '+' spelling).
@@ -343,9 +354,8 @@ export const inject = [];
 /**
  * Mount the fusion injection: one `webserver/index-inject` listener pushing
  * the rendered head script row — the same emission path as the web-trust
- * component, composed AFTER it (the composite row order is load order, and
- * both components register their listeners behind `inject(['webServer'])`, so
- * cordis's FIFO effect order pushes the fusion row last; spec §3.4) — plus
+ * component, composed AFTER it. Better Dash prepends its ownership verdict to the public injection table,
+ * so asynchronous module loading cannot invert the script order (spec §3.4), plus
  * the {@link FUSION_FLAG_GLOBAL} baked global row (Task 4): one gate, both
  * halves.
  *

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

@@ -35,7 +35,6 @@ export { agentLinks, agentRosterRow, AGENT_ROSTER_GLOBAL, type AgentLink } from
 export { createOwnershipIndex, type OwnershipIndex, type OwnershipRow } from './ownership.js';
 export { registerHostMount, takeHostMount, listHostMounts, noteWorldServer, worldServerOf, type HostMount } from './world-host.js';
 export { worldMountPatches, superdTrustedHosts, WORLD_WAVE1_DISABLED_ROWS, WORLD_WAVE2_DISABLED_ROWS, WORLD_MOUNT_PLUGIN, WORLD_MOUNT_ROW_ID, WORLD_HUB_PLUGIN, WORLD_HUB_ROW_ID, type WorldPatchLayer, } from './world-mount.js';
-export { buildTrustScript, deriveDefaultPageAuthorities, type BootScriptRow, type TrustConfig, } from './web-trust.js';
 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';

package/superd-hub/dist/index.js

@@ -35,7 +35,6 @@ export { agentLinks, agentRosterRow, AGENT_ROSTER_GLOBAL } from './agent-roster.
 export { createOwnershipIndex } from './ownership.js';
 export { registerHostMount, takeHostMount, listHostMounts, noteWorldServer, worldServerOf } from './world-host.js';
 export { worldMountPatches, superdTrustedHosts, WORLD_WAVE1_DISABLED_ROWS, WORLD_WAVE2_DISABLED_ROWS, WORLD_MOUNT_PLUGIN, WORLD_MOUNT_ROW_ID, WORLD_HUB_PLUGIN, WORLD_HUB_ROW_ID, } from './world-mount.js';
-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';

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

@@ -2,10 +2,13 @@
 export interface MachineRow {
     /** Machine id (m4) — minted by the owning machine, adopted as-is (D4). */
     id: string;
-    /** Operator-facing machine name on the remote. */
+    /**
+     * The machine's display name — the operator-facing identifier the adder
+     * chose (spec hub-roster-identity §4: exactly TWO identities exist, this
+     * name and the internal `id`; the retired separate `label` field of older
+     * registries loads tolerantly and disappears on the next save).
+     */
     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. */

package/superd-hub/dist/machines.js

@@ -25,8 +25,8 @@ 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' &&
+    return (typeof r.id === 'string' && r.id !== '' && typeof r.name === 'string' && r.name !== '' &&
+        typeof r.origin === 'string' && r.origin !== '' && 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));
@@ -69,7 +69,19 @@ export function loadMachines(home) {
     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) };
+    // Projected field-by-field: older registries carry the retired `label`
+    // column on their rows — tolerated at load (never a whole-file reject),
+    // gone from memory so the next save writes the clean shape.
+    return { self: { id: s.id, label: s.label }, remotes: o.remotes.filter(isMachineRow).map((r) => ({
+            id: r.id,
+            name: r.name,
+            origin: r.origin,
+            enabled: r.enabled,
+            addedAt: r.addedAt,
+            ...(r.token === undefined ? {} : { token: r.token }),
+            ...(r.cookie === undefined ? {} : { cookie: r.cookie }),
+            ...(r.execEnabled === undefined ? {} : { execEnabled: r.execEnabled }),
+        })) };
 }
 /** Persist the whole registry: recursive mkdir, tmp write, chmod 0600, atomic rename. */
 export function saveMachines(home, file) {

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

@@ -13,8 +13,8 @@
  *               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
+ *   roster.ts   one row per agent: `{key: a6, runtimeId: <package id>,
+ *               label, 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
@@ -62,11 +62,18 @@ export interface FederatedAgent {
      *  anything at the peer; {@link gatewayFor} falls back to the a6 there
      *  (T3-M1) rather than shipping `?agent=` on the wire. */
     key: string;
+    /**
+     * The peer's unified runtime identifier (adapter package name; spec
+     * hub-roster-identity §1). Absent from peers older than the field — the
+     * parse edge normalizes `key` so icon matching still speaks the common
+     * language.
+     */
+    runtimeId?: string;
     label: string;
     ready: boolean;
     failed: boolean;
 }
-/** The machine half of a federation fact (m4 + display name for label suffixes). */
+/** The machine half of a federation fact (m4 + display name for the UI's section heading). */
 export interface FederatedMachine {
     id: string;
     name: string;
@@ -79,15 +86,18 @@ export interface FederationWireDeps {
 }
 /**
  * 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
+ * whose key/runtimeId/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).
+ * native gateway face; see {@link gatewayFor}). The label is the PEER'S OWN
+ * runtime label, unsuffixed (2026-10-07 user ruling, spec
+ * hub-roster-identity §4): the machine context is the UI's group heading,
+ * not part of the runtime's name.
+ * @param machine - the peer's identity (m4 + name; the grouping's section label).
+ * @param agents - the probe's agent snapshot (a6 `id`, remote `key`, runtimeId, 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.

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

@@ -13,8 +13,8 @@
  *               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
+ *   roster.ts   one row per agent: `{key: a6, runtimeId: <package id>,
+ *               label, 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
@@ -51,7 +51,7 @@
  */
 import { createRemoteGateway } from './mesh-gateway.js';
 import { cookieOf, onMeshFederationEvent } from './mesh-link.js';
-import { registerAgent, unregisterAgent, listAgents, setReady } from './roster.js';
+import { registerAgent, unregisterAgent, listAgents, setReady, runtimeIdOf } 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. */
@@ -71,15 +71,18 @@ function dropA6(a6) {
 }
 /**
  * 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
+ * whose key/runtimeId/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).
+ * native gateway face; see {@link gatewayFor}). The label is the PEER'S OWN
+ * runtime label, unsuffixed (2026-10-07 user ruling, spec
+ * hub-roster-identity §4): the machine context is the UI's group heading,
+ * not part of the runtime's name.
+ * @param machine - the peer's identity (m4 + name; the grouping's section label).
+ * @param agents - the probe's agent snapshot (a6 `id`, remote `key`, runtimeId, 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.
@@ -90,13 +93,15 @@ export function federateAgents(machine, agents, gatewayOf) {
             continue;
         const desired = {
             key: agent.id,
-            label: `${agent.label} · ${machine.name}`,
+            runtimeId: agent.runtimeId ?? runtimeIdOf(agent.key),
+            label: agent.label,
             machine: machine.id,
             ready: agent.ready === true,
             failed: agent.failed === true,
         };
         const existing = listAgents().find((e) => e.key === agent.id);
         if (existing !== undefined
+            && existing.runtimeId === desired.runtimeId
             && existing.label === desired.label
             && existing.ready === desired.ready
             && (existing.failed ?? false) === desired.failed

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

@@ -25,6 +25,13 @@ import { type MachineRow, loadMachines, saveMachines } from './machines.js';
 export interface ProbeAgent {
     id: string;
     key: string;
+    /**
+     * The peer's unified runtime identifier (adapter package name; spec
+     * hub-roster-identity §1) — the common language icon matching consumes.
+     * Optional on the wire: peers older than the field answer without it, and
+     * the federation edge falls back to normalizing `key`.
+     */
+    runtimeId?: string;
     label: string;
     ready: boolean;
     failed: boolean;
@@ -47,6 +54,30 @@ export interface PairOutcome {
     machineId: string;
     row: MachineRow;
     probe: ProbeResult;
+    /** The mutual-pairing reverse leg's outcome — present exactly when the
+     *  pairing input carried a {@link MutualPairing} self-description. */
+    mutual?: MutualOutcome;
+}
+/**
+ * Reverse-leg payload (mutual pairing, 2026-10-08 user ruling "加了对方就等于
+ * 双方都加了"): after a successful pair the INITIATOR offers the peer its own
+ * pairing input, so one user action leaves BOTH machines holding each other.
+ * The peer processes the offer as an ordinary pair POST carrying
+ * `mutual: true` — pairing WITHOUT its own reverse leg, which stops the
+ * recursion by construction.
+ */
+export interface MutualPairing {
+    /** This machine's tokenized pairing URL as the peer should dial it. */
+    selfTokenUrl: string;
+    /** This machine's operator-facing name (hostname, port-qualified per instance). */
+    selfName: string;
+}
+/** The reverse leg's outcome. `ok` is also true when the peer answered
+ *  duplicate-machine-id — it already holds us, so mutual already holds. */
+export interface MutualOutcome {
+    ok: boolean;
+    /** Why the offer failed; absent on success. The pairing itself never fails with it. */
+    error?: string;
 }
 /** Test injection seam: fetch + registry load/save overrides. */
 export interface LinkDeps {
@@ -162,13 +193,16 @@ export declare function cookieOf(machineId: string, home?: string): string;
  * Full pairing: parse the pasted token URL → mint a cookie → probe the roster
  * → adopt the remote machine id (fail-loud on collision with self or an
  * existing remote) → persist the row with the retained token and minted
- * cookie → jar the cookie and mark the machine reachable. A failed mint/probe throws before
- * anything is persisted.
+ * cookie → jar the cookie and mark the machine reachable. When the input
+ * carries a {@link MutualPairing} self-description, the REVERSE LEG follows
+ * (best-effort, never fails the pairing): this machine offers its own pairing
+ * input to the peer over the just-minted cookie, so both sides end up holding
+ * each other — the "加了对方就等于双方都加了" ruling.
  */
 export declare function pairMachine(home: string, input: {
     name: string;
-    label?: string;
     tokenUrl: string;
+    mutual?: MutualPairing;
 }, deps?: LinkDeps): Promise<PairOutcome>;
 /**
  * Re-probe a paired machine: the jar's cookie, falling back to the cookie

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

@@ -138,6 +138,7 @@ function coerceAgent(v) {
     return {
         id: typeof a.id === 'string' ? a.id : '',
         key: typeof a.key === 'string' ? a.key : '',
+        runtimeId: typeof a.runtimeId === 'string' && a.runtimeId !== '' ? a.runtimeId : undefined,
         label: typeof a.label === 'string' ? a.label : '',
         ready: a.ready === true,
         failed: a.failed === true,
@@ -268,8 +269,11 @@ function persistRow(home, row, deps) {
  * Full pairing: parse the pasted token URL → mint a cookie → probe the roster
  * → adopt the remote machine id (fail-loud on collision with self or an
  * existing remote) → persist the row with the retained token and minted
- * cookie → jar the cookie and mark the machine reachable. A failed mint/probe throws before
- * anything is persisted.
+ * cookie → jar the cookie and mark the machine reachable. When the input
+ * carries a {@link MutualPairing} self-description, the REVERSE LEG follows
+ * (best-effort, never fails the pairing): this machine offers its own pairing
+ * input to the peer over the just-minted cookie, so both sides end up holding
+ * each other — the "加了对方就等于双方都加了" ruling.
  */
 export async function pairMachine(home, input, deps) {
     const fetchImpl = deps?.fetchImpl ?? globalThis.fetch;
@@ -287,7 +291,6 @@ export async function pairMachine(home, input, deps) {
     const row = {
         id: probe.machineId,
         name: input.name,
-        label: input.label ?? input.name,
         origin,
         token,
         cookie,
@@ -298,7 +301,49 @@ export async function pairMachine(home, input, deps) {
     cookieJar.set(row.id, cookie);
     recordStatus(row.id, 'reachable', undefined, versionWarningFor(probe.version, OWN_VERSION));
     emitFederation({ type: 'federated', machineId: row.id, machineName: row.name, origin, agents: probe.agents });
-    return { machineId: row.id, row, probe };
+    const outcome = { machineId: row.id, row, probe };
+    if (input.mutual !== undefined)
+        outcome.mutual = await reversePair(row, input.mutual, fetchImpl);
+    return outcome;
+}
+const REVERSE_TIMEOUT_MS = 10_000;
+/**
+ * The mutual-pairing reverse leg: offer THIS machine's pairing input to the
+ * just-paired peer over the cookie minted seconds ago (the peer then pairs
+ * back without its own reverse leg — the offer carries `mutual: true`). A
+ * duplicate-machine-id answer means the peer already holds us: mutual is
+ * already satisfied, reported as ok. EVERY failure lands on the outcome and
+ * never fails the pairing itself — the user sees it and can still add
+ * manually from the peer.
+ */
+async function reversePair(row, mutual, fetchImpl) {
+    let res;
+    try {
+        res = await fetchImpl(`${row.origin}/api/superd/machines`, {
+            method: 'POST',
+            headers: { cookie: row.cookie ?? '', 'content-type': 'application/json' },
+            body: JSON.stringify({ name: mutual.selfName, tokenUrl: mutual.selfTokenUrl, mutual: true }),
+            signal: AbortSignal.timeout(REVERSE_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        return { ok: false, error: `the peer did not answer the mutual-pairing offer — ${errMsg(err)}` };
+    }
+    if (res.status === 400) {
+        let error = '';
+        try {
+            const body = await res.json();
+            if (typeof body.error === 'string')
+                error = body.error;
+        }
+        catch { /* unreadable body */ }
+        if (error.includes('duplicate-machine-id'))
+            return { ok: true };
+        return { ok: false, error: error === '' ? `the peer answered ${res.status}` : error };
+    }
+    if (res.status >= 200 && res.status < 300)
+        return { ok: true };
+    return { ok: false, error: `the peer answered ${res.status}` };
 }
 /**
  * Re-probe a paired machine: the jar's cookie, falling back to the cookie