super-dsh 0.1.5 → 0.1.9

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

@@ -23,16 +23,32 @@ export interface RuntimeTargetSource {
 }
 /** The live registry view: native plus every registered foreign context. */
 export declare const registryTargets: RuntimeTargetSource;
+/** Injection seam for the roster/hub identity: the hub home backing the a6
+ * id store and the machines registry. Defaults to `resolveDshHome()`
+ * (registerSelectorRpc passes no deps — the same home the rest of this
+ * process uses); unit tests inject a tmpdir so nothing ever touches an
+ * ambient/prod DSH_HOME. */
+export interface AgentRuntimeDeps {
+    home?: string;
+}
 /**
  * The control-plane handler: world inventory only.
+ *
+ * ADDITIVE contract (mesh P1): the GET body gained `hub: {machineId, label,
+ * version}` and every `agents` row gained `id` (a6); `available` and all
+ * pre-existing agents fields are unchanged — old clients ignore the new
+ * fields, new clients read them.
  * @param request - the incoming `/api/agent-runtime` request.
  * @param source - live runtime registry view.
+ * @param deps - optional home override; defaults to `resolveDshHome()`.
  * @returns the JSON response.
  */
-export declare function handleAgentRuntime(request: Request, source: RuntimeTargetSource): Promise<Response>;
+export declare function handleAgentRuntime(request: Request, source: RuntimeTargetSource, deps?: AgentRuntimeDeps): Promise<Response>;
 /**
  * Register the control-plane RPC face 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).
+ * `connection` service is absent (e.g. fake-ctx unit tests). The route answers
+ * with the DEFAULT home (`resolveDshHome()` at request time); callers needing
+ * a pinned home invoke handleAgentRuntime directly with deps.
  */
 export declare function registerSelectorRpc(ctx: Context, source: RuntimeTargetSource): void;

package/superd-hub/dist/rpc.js

@@ -1,11 +1,20 @@
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { PACK_VERSION } from './pack-version.js';
 import { listRuntimeKeys } from './targets.js';
 import { agentLinks } from './agent-roster.js';
+import { ensureSelf } from './machines.js';
 /** The shared-channel Fetch route path this RPC face owns. */
 export const AGENT_RUNTIME_RPC_PATH = '/api/agent-runtime';
 /** The live registry view: native plus every registered foreign context. */
 export const registryTargets = {
     listRuntimes: listRuntimeKeys,
 };
+/** The version this hub SERVES as `hub.version` — the super-dsh PACK version
+ * (D6): the subpackage's own 0.1.0 never moves, so peers comparing against it
+ * could never see a mismatch. The pack manifest ships exactly two hops above
+ * the compiled output in every layout (see pack-version.ts); 'unknown' when
+ * unreadable — an honest non-number, not a fake one. */
+const HUB_VERSION = PACK_VERSION;
 function json(status, body) {
     return new Response(JSON.stringify(body), {
         status,
@@ -14,16 +23,35 @@ function json(status, body) {
 }
 /**
  * The control-plane handler: world inventory only.
+ *
+ * ADDITIVE contract (mesh P1): the GET body gained `hub: {machineId, label,
+ * version}` and every `agents` row gained `id` (a6); `available` and all
+ * pre-existing agents fields are unchanged — old clients ignore the new
+ * fields, new clients read them.
  * @param request - the incoming `/api/agent-runtime` request.
  * @param source - live runtime registry view.
+ * @param deps - optional home override; defaults to `resolveDshHome()`.
  * @returns the JSON response.
  */
-export async function handleAgentRuntime(request, source) {
+export async function handleAgentRuntime(request, source, deps) {
     const available = source.listRuntimes();
     if (request.method === 'GET' || request.method === 'HEAD') {
         // The selector asks this face for the roster: keys AND the mount path each
-        // key is addressed by. Read-only — the roster carries no selection.
-        return json(200, { available, agents: agentLinks() });
+        // key is addressed by. Read-only — the roster carries no selection. The
+        // hub block (this machine's m4 + label + hub version) rides along for the
+        // multi-machine UI; the a6 row ids ride on every agents row.
+        const home = deps?.home ?? resolveDshHome();
+        const self = ensureSelf(home, 'local');
+        // Self-description discipline (2026-09-28 user ruling): a peer's discovery
+        // probe (`?mesh=1`) receives THIS machine's own rows only — a hub never
+        // re-broadcasts other remotes' agents to its peers (hub-to-hub is P2P;
+        // the requester fans out one probe per paired machine and merges itself).
+        // The plain browser GET keeps the full roster — the local UI's machine
+        // grouping consumes exactly that.
+        const links = new URL(request.url).searchParams.get('mesh') === '1'
+            ? agentLinks(home).filter((l) => l.machine === 'local')
+            : agentLinks(home);
+        return json(200, { available, agents: links, hub: { machineId: self.id, label: self.label, version: HUB_VERSION } });
     }
     // A POST that used to switch a global selector has no meaning any more:
     // the addressed world is the mount path of the request, not a shared value.
@@ -35,7 +63,9 @@ export async function handleAgentRuntime(request, source) {
 /**
  * Register the control-plane RPC face 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).
+ * `connection` service is absent (e.g. fake-ctx unit tests). The route answers
+ * with the DEFAULT home (`resolveDshHome()` at request time); callers needing
+ * a pinned home invoke handleAgentRuntime directly with deps.
  */
 export function registerSelectorRpc(ctx, source) {
     ctx.inject(['connection'], (connCtx) => {

package/superd-hub/dist/spawn-world.js

@@ -71,7 +71,9 @@ async function publishWorldInHostResolutionTurn(packages, launcher, opts, worldP
     const declarer = join(worldProfileDir, 'package.json');
     const worldScope = join(worldProfileDir, 'node_modules', '@pgmi-builds');
     const baseNames = new Set(base.entries.map((entry) => entry.name));
-    for (const name of readdirSync(worldScope, { withFileTypes: true })) {
+    // R0 scan guard: a dsh-base world has NO farm — a missing scope is not a
+    // publish failure, just nothing to add (existsSync before readdirSync).
+    for (const name of existsSync(worldScope) ? readdirSync(worldScope, { withFileTypes: true }) : []) {
         if (!name.isDirectory() && !name.isSymbolicLink())
             continue;
         const pkgName = `@pgmi-builds/${name.name}`;

package/superd-hub/dist/switch-core.d.ts

@@ -457,8 +457,13 @@ export interface HubRosterRow {
     readonly label: string;
     /** The row's mount path. */
     readonly path: string;
-    /** Machine the runtime comes from (the roster parser guarantees it — `'local'` when an older host shape omitted it). */
-    readonly machine: string;
+    /**
+     * Machine the runtime comes from (mesh P2): `'local'` for this machine's
+     * rows, the owning machine's m4 for federated rows. Optional — the wire
+     * may omit it and the grouping now lives client-side (mesh-groups.ts,
+     * fed the machines API's label map).
+     */
+    readonly machine?: string;
 }
 /**
  * The active agent's display name for the Hub row's right-edge selector: the
@@ -470,25 +475,6 @@ export interface HubRosterRow {
  * Host-half pure logic so `test/client-switch.test.mjs` pins it from `dist/`.
  */
 export declare function activeAgentName(activeAgent: string | undefined, roster: readonly HubRosterRow[]): string | undefined;
-/** Which machine one roster row groups under: the row's own machine (parser-guaranteed). */
-export declare function machineGroup(row: HubRosterRow): string;
-/** One machine's group of roster rows, in roster order. */
-export interface MachineGroup {
-    /** The grouping key (the members' shared `machine`). */
-    readonly machine: string;
-    /** The rows of this machine, keeping the roster's own order. */
-    readonly agents: readonly HubRosterRow[];
-}
-/**
- * Group a roster by machine for the HubPanelIcon chevron menu's native
- * workspace-list look: one group per distinct `machineGroup` key, groups in
- * first-appearance order, members keeping the roster's order inside their
- * group. A single-group roster (today's local-only shape) renders exactly
- * like the old flat list minus the card border.
- *
- * Host-half pure logic so `test/client-switch.test.mjs` pins it from `dist/`.
- */
-export declare function machineGroups(rows: readonly HubRosterRow[]): readonly MachineGroup[];
 /**
  * What the machine hands the host's gate composition (T-G): the machine-side
  * ingredients of {@link LandingGateOptions}. Structurally a full
@@ -628,3 +614,94 @@ export interface SwitchController {
  * switch's pointer-restored view).
  */
 export declare function createSwitchController(host: SwitchHost, options?: SwitchOptions): SwitchController;
+/** What attemptSwitch does with a roster row: run the machine / report failure / wait for readiness / fail fast on a degraded federated row. */
+export type PreFlightDecision = 'run' | 'failed' | 'wait' | 'machine-down';
+/**
+ * The roster fields the pre-flight reads (the projection carries both since
+ * C1 task 3; `machine` since the mesh P2 roster dimension).
+ */
+export interface PreFlightRow {
+    ready?: boolean;
+    failed?: boolean;
+    /**
+     * Owning machine (m4) for FEDERATED rows — `'local'` or absent means this
+     * machine's own world (the C1 spawn-wait semantics). The client's
+     * `AgentLink` satisfies this structurally; the field decides the I1(c)
+     * fail-fast branch.
+     */
+    machine?: string;
+}
+/**
+ * The pure pre-flight decision. `native` always runs; an absent row (roster
+ * fetch failed, or the key is not listed) also runs — the machine's roster
+ * probe is the authority on unknown targets, exactly as before C1. A
+ * not-ready FEDERATED row (`machine` set and not `'local'`) decides
+ * `'machine-down'` — an immediate actionable failure, never a wait loop
+ * (the hub's probe already knows the machine is unreachable or its auth
+ * expired); `failed` keeps precedence everywhere (a peer-reported spawn
+ * rejection still reports as failed).
+ */
+export declare function decidePreFlight(label: string, row: PreFlightRow | undefined): PreFlightDecision;
+/** Bound on the machine-down branch's enrichment fetch (mesh P3 Task 5a:
+ *  the parked P2 minor — an unbounded `fetchMachines` await — folds here; a
+ *  hung hub answer must never swallow the toast). */
+export declare const MACHINE_DOWN_ENRICH_MS = 3000;
+/** The machines-face slice the machine-down feedback reads (the client's
+ *  `fetchMachines()` satisfies this structurally). */
+export interface MachineDownMachinesFace {
+    machines: readonly {
+        id: string;
+        label: string;
+        status: string;
+    }[];
+}
+/** The branch's injected faces — the browser wiring supplies the real
+ *  fetch/reprobe/toast; tests fake all of them. */
+export interface MachineDownFaces {
+    /** Same-origin GET of the hub machine list (enrichment only). */
+    fetchMachines(): Promise<MachineDownMachinesFace>;
+    /** The I1(b) light probe: POST `{op: 'reprobe', id}` — fire-and-forget. */
+    reprobe(id: string): Promise<void>;
+    toast(message: string): void;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+/**
+ * The machine-down branch's pure half (I1(c) feedback + I1(b) light probe,
+ * mesh P3 Task 5a): enrich the toast through the machines face — BOUNDED at
+ * {@link MACHINE_DOWN_ENRICH_MS} — then, after toasting, fire ONE reprobe
+ * for the row's machine and forget it: a stale-unreachable machine gets a
+ * fresh attempt per failed click, so the NEXT click can succeed without
+ * waiting for the hub's 5-minute sweep. Never blocks the UI path (the whole
+ * body is detached), never surfaces a reprobe failure (the sweep retries).
+ */
+export declare function runMachineDownFeedback(label: string, row: PreFlightRow & {
+    label?: string;
+}, faces: MachineDownFaces): void;
+/** Default bound on one readiness wait (the page never locks behind a stuck world). */
+export declare const WAIT_BOUND_MS = 120000;
+/** Default poll interval for one readiness wait. */
+export declare const WAIT_POLL_MS = 1000;
+/** The waiter's injected faces (tests drive time and the roster by hand). */
+export interface ReadinessWaiterFaces {
+    /** Read the target's roster row; undefined on any failure. */
+    fetchRow(): Promise<PreFlightRow | undefined>;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+/** One bounded readiness wait. */
+export interface ReadinessWaiter {
+    /** Resolves when the row flips ready ('ready'), reports failure ('failed'), the bound expires ('bound'), or the waiter is cancelled ('cancelled'). */
+    wait(label: string): Promise<'ready' | 'failed' | 'bound' | 'cancelled'>;
+    /** A newer switch attempt cancels a pending wait (it resolves 'cancelled'). */
+    cancel(): void;
+}
+/**
+ * Build a bounded readiness waiter over injected faces. The poll re-reads
+ * the roster row every {@link ReadinessWaiterOptions.pollMs}; `failed`
+ * short-circuits immediately; the bound always terminates the wait.
+ */
+export declare function createReadinessWaiter(faces: ReadinessWaiterFaces, options?: {
+    boundMs?: number;
+    pollMs?: number;
+}): ReadinessWaiter;

package/superd-hub/dist/switch-core.js

@@ -502,34 +502,6 @@ export function activeAgentName(activeAgent, roster) {
         return undefined;
     return roster.find((row) => row.key === activeAgent)?.label ?? activeAgent;
 }
-/** Which machine one roster row groups under: the row's own machine (parser-guaranteed). */
-export function machineGroup(row) {
-    return row.machine;
-}
-/**
- * Group a roster by machine for the HubPanelIcon chevron menu's native
- * workspace-list look: one group per distinct `machineGroup` key, groups in
- * first-appearance order, members keeping the roster's order inside their
- * group. A single-group roster (today's local-only shape) renders exactly
- * like the old flat list minus the card border.
- *
- * Host-half pure logic so `test/client-switch.test.mjs` pins it from `dist/`.
- */
-export function machineGroups(rows) {
-    const groups = [];
-    const byMachine = new Map();
-    for (const row of rows) {
-        const machine = machineGroup(row);
-        let group = byMachine.get(machine);
-        if (group === undefined) {
-            group = { machine, agents: [] };
-            byMachine.set(machine, group);
-            groups.push(group);
-        }
-        group.agents.push(row);
-    }
-    return groups;
-}
 /**
  * Build the switch machine over an injected {@link SwitchHost}.
  *
@@ -732,3 +704,126 @@ export function createSwitchController(host, options = {}) {
         },
     };
 }
+/**
+ * The pure pre-flight decision. `native` always runs; an absent row (roster
+ * fetch failed, or the key is not listed) also runs — the machine's roster
+ * probe is the authority on unknown targets, exactly as before C1. A
+ * not-ready FEDERATED row (`machine` set and not `'local'`) decides
+ * `'machine-down'` — an immediate actionable failure, never a wait loop
+ * (the hub's probe already knows the machine is unreachable or its auth
+ * expired); `failed` keeps precedence everywhere (a peer-reported spawn
+ * rejection still reports as failed).
+ */
+export function decidePreFlight(label, row) {
+    if (label === NATIVE_AGENT)
+        return 'run';
+    if (row === undefined)
+        return 'run';
+    if (row.failed === true)
+        return 'failed';
+    if (row.ready !== true) {
+        // I1(c): a federated not-ready row is DEGRADED, not spawning — fail fast.
+        if (row.machine !== undefined && row.machine !== 'local')
+            return 'machine-down';
+        return 'wait';
+    }
+    return 'run';
+}
+// ---- I1(b): the machine-down feedback (preflight light probe) ----------------
+/** Bound on the machine-down branch's enrichment fetch (mesh P3 Task 5a:
+ *  the parked P2 minor — an unbounded `fetchMachines` await — folds here; a
+ *  hung hub answer must never swallow the toast). */
+export const MACHINE_DOWN_ENRICH_MS = 3_000;
+/**
+ * The machine-down branch's pure half (I1(c) feedback + I1(b) light probe,
+ * mesh P3 Task 5a): enrich the toast through the machines face — BOUNDED at
+ * {@link MACHINE_DOWN_ENRICH_MS} — then, after toasting, fire ONE reprobe
+ * for the row's machine and forget it: a stale-unreachable machine gets a
+ * fresh attempt per failed click, so the NEXT click can succeed without
+ * waiting for the hub's 5-minute sweep. Never blocks the UI path (the whole
+ * body is detached), never surfaces a reprobe failure (the sweep retries).
+ */
+export function runMachineDownFeedback(label, row, faces) {
+    void (async () => {
+        let machineName = row.machine;
+        let status;
+        const enriched = await new Promise((resolve) => {
+            const bound = faces.setTimeout(() => resolve(undefined), MACHINE_DOWN_ENRICH_MS);
+            faces.fetchMachines().then((list) => { faces.clearTimeout(bound); resolve(list); }, () => { faces.clearTimeout(bound); resolve(undefined); });
+        });
+        if (enriched !== undefined) {
+            const found = enriched.machines.find((entry) => entry.id === row.machine);
+            if (found !== undefined) {
+                machineName = found.label;
+                if (found.status === 'unreachable' || found.status === 'auth-expired')
+                    status = found.status;
+            }
+        }
+        const who = row.label ?? label;
+        const machine = machineName ?? 'its machine';
+        faces.toast(status === undefined
+            ? `Super D: ${who} is unavailable — machine ${machine} is not ready. Reprobe or re-add it in the Hub machines panel.`
+            : `Super D: ${who} is unavailable — machine ${machine} reports ${status}. Reprobe or re-add it in the Hub machines panel.`);
+        // I1(b): exactly ONE fresh attempt per failed click — keyed by the row's
+        // machine id (the machine-down decision guarantees it is set; a malformed
+        // row simply skips the light probe).
+        if (row.machine !== undefined)
+            faces.reprobe(row.machine).catch(() => { });
+    })();
+}
+/** Default bound on one readiness wait (the page never locks behind a stuck world). */
+export const WAIT_BOUND_MS = 120_000;
+/** Default poll interval for one readiness wait. */
+export const WAIT_POLL_MS = 1_000;
+/**
+ * Build a bounded readiness waiter over injected faces. The poll re-reads
+ * the roster row every {@link ReadinessWaiterOptions.pollMs}; `failed`
+ * short-circuits immediately; the bound always terminates the wait.
+ */
+export function createReadinessWaiter(faces, options = {}) {
+    const boundMs = options.boundMs ?? WAIT_BOUND_MS;
+    const pollMs = options.pollMs ?? WAIT_POLL_MS;
+    let pending;
+    let pollHandle;
+    let boundHandle;
+    let settled = false;
+    const settle = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        if (pollHandle !== undefined)
+            faces.clearTimeout(pollHandle);
+        if (boundHandle !== undefined)
+            faces.clearTimeout(boundHandle);
+        pending?.(outcome);
+        pending = undefined;
+    };
+    return {
+        wait(label) {
+            return new Promise((resolve) => {
+                pending = resolve;
+                boundHandle = faces.setTimeout(() => { settle('bound'); }, boundMs);
+                const tick = () => {
+                    if (settled)
+                        return;
+                    void faces.fetchRow().then((row) => {
+                        if (settled)
+                            return;
+                        if (row?.failed === true) {
+                            settle('failed');
+                            return;
+                        }
+                        if (row?.ready === true) {
+                            settle('ready');
+                            return;
+                        }
+                        pollHandle = faces.setTimeout(tick, pollMs);
+                    }, () => { if (!settled)
+                        pollHandle = faces.setTimeout(tick, pollMs); });
+                };
+                tick();
+            });
+        },
+        cancel() { settle('cancelled'); },
+    };
+}

package/superd-hub/dist/system-head.d.ts

@@ -10,16 +10,10 @@
  * (before any step) — so every bridge-written log violated one rule or the
  * other and became unresumable across restarts.
  *
- * The native loop never hits this because it opens the step before writing
- * anything: `turn/start → step/start → system/message → user/message …`,
- * and later prompt changes REPLACE the protected head (the operation
- * compaction also uses). This module gives bridge adapters that posture with
- * a one-line wrap:
- *
- *   this.session = withSystemHead(session, () => createSystemMessage(""))
- *
- * The wrap is a transparent Proxy that tracks the open turn/step (exactly as
- * the v4 reader does) and intervenes minimally:
+ * The wrap installs the co-writer as OWN PROPERTIES on the session object
+ * itself (an `append` own-property shadow over the prototype method, plus
+ * `stampSystemPrompt`) and tracks the open turn/step (exactly as the v4
+ * reader does), intervening minimally:
  *
  *   - the FIRST `user/message` append on a still-headless, still-empty
  *     surface first opens the turn's next step (when a turn is open but no
@@ -35,6 +29,18 @@
  *     queued and flushed inside the next step the adapter opens;
  *   - everything else delegates unchanged.
  *
+ * IDENTITY IS THE CONTRACT (2026-09-28, D1): the wrap must return the session
+ * object ITSELF, never a wrapper. Upstream identity-checks live sessions by
+ * object equality — `session-title`'s `rename()` refuses unless
+ * `ctx.sessions.get(session.id) === session` (session-title/src/index.ts),
+ * and adapters register the RAW prepared session with `sessions.enter()` /
+ * `announce()` (e.g. agent-pi/src/index.ts). An earlier revision returned a
+ * transparent `Proxy`; every world-context rename then failed with
+ * `session "<id>" is not live in this store` because the Agent handle's
+ * `session` (the Proxy) was never the store-registered object. Returning the
+ * same object keeps `agent.session === ctx.sessions.get(id)` true, so the
+ * whole upstream session plane (rename included) sees one identity.
+ *
  * A surface that already starts with a user message and has no head (legacy
  * logs) stays headless — valid — and is never stamped: appending a head
  * there is exactly the corruption this module exists to prevent.
@@ -54,7 +60,7 @@ export interface HeadAwareSessionFace {
 }
 /** Builds the placeholder head message (adapters pass their createSystemMessage). */
 export type HeadPlaceholder = () => unknown;
-/** One co-written session: transparent delegation + head bookkeeping. */
+/** One co-written session: the session itself, carrying head bookkeeping (object identity preserved — see the module note). */
 export type WithSystemHead<S> = S & {
     /** Append-or-replace the protected head with the runtime's system prompt. */
     stampSystemPrompt(turn: number, step: number, message: unknown): void;
@@ -64,6 +70,10 @@ export type WithSystemHead<S> = S & {
  * @param session - the adapter's real Session.
  * @param placeholder - builds the placeholder head message when the first
  *   user message arrives on an empty surface.
- * @returns the session (transparently delegated) with `stampSystemPrompt`.
+ * @returns the SAME session object with the co-writer installed as own
+ *   properties (`append` shadow + `stampSystemPrompt`). Identity is the
+ *   contract (D1): upstream liveness checks compare
+ *   `ctx.sessions.get(id) === agent.session`, so the returned object must be
+ *   the one registered with `sessions.enter()` — never a wrapper.
  */
 export declare function withSystemHead<S extends HeadAwareSessionFace>(session: S, placeholder: HeadPlaceholder): WithSystemHead<S>;