super-dsh 0.1.3 → 0.1.5

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

@@ -0,0 +1,392 @@
+/**
+ * Per-world Remote stream mux server (AW-B DL6).
+ *
+ * Upstream's `RemoteStreamMuxServer` owns `/api/remote.mux` for the native
+ * gateway and is NOT reachable from outside its package (root exports omit it;
+ * `./src/*` cannot be imported at runtime). So this is our own wire-compatible
+ * implementation of the same protocol (dsh 0.1.7 `stream-protocol.ts`), bound
+ * to the ADDRESSED world's `openWireStream`:
+ *
+ *   browser → server   { type:'open', streamId, endpoint, payload }
+ *                      { type:'item', streamId, value? }   (uplink)
+ *                      { type:'end', streamId }            (uplink half-close)
+ *                      { type:'cancel', streamId }
+ *   server → browser   { type:'item', streamId, value }
+ *                      { type:'end', streamId }
+ *                      { type:'error', streamId, error:{code,message,details} }
+ *
+ * Dispatch semantics mirror upstream `RemoteStreamMuxConnection`: `item`,
+ * `end`, and `cancel` for a stream this connection no longer owns are dropped;
+ * a duplicate `open` is the one violation that closes the socket. Uplink items
+ * wait in a bounded inbox created before the opener resolves, so items sent
+ * right after `open` are never lost. Heartbeat: ping every interval, terminate
+ * after two missed pongs.
+ */
+/** Specifier is widened on purpose: `ws` is a runtime peer, not a typed dep. */
+const WS_MODULE = 'ws';
+const MAX_MISSED_HEARTBEATS = 2;
+const DEFAULT_HEARTBEAT_MS = 2_000;
+const DEFAULT_STREAM_INBOX_BYTES = 262_144;
+const UPLINK_DONE = { value: undefined, done: true };
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, keys) {
+    const own = Object.keys(value);
+    return own.length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+function validId(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/** An abort reason carrying wire failure fields (upstream `remoteErrorOf`). */
+function isRemoteFailure(reason) {
+    return isRecord(reason) && typeof reason['code'] === 'string';
+}
+/**
+ * Parse one browser text frame.
+ * @param text - complete WebSocket text message.
+ * @returns the validated request.
+ * @throws {Error} on a malformed frame.
+ */
+export function parseClientMessage(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new Error('world-mux: invalid client message');
+    }
+    if (!isRecord(raw))
+        throw new Error('world-mux: invalid client message');
+    if ((raw['type'] === 'cancel' || raw['type'] === 'end')
+        && exactKeys(raw, ['type', 'streamId']) && validId(raw['streamId'])) {
+        return { type: raw['type'], streamId: raw['streamId'] };
+    }
+    if (raw['type'] === 'item'
+        && (exactKeys(raw, ['type', 'streamId']) || exactKeys(raw, ['type', 'streamId', 'value']))
+        && validId(raw['streamId'])) {
+        return Object.hasOwn(raw, 'value')
+            ? { type: 'item', streamId: raw['streamId'], value: raw['value'] }
+            : { type: 'item', streamId: raw['streamId'] };
+    }
+    if (raw['type'] === 'open'
+        && exactKeys(raw, ['type', 'streamId', 'endpoint', 'payload'])
+        && validId(raw['streamId'])
+        && typeof raw['endpoint'] === 'string'
+        && raw['endpoint'].length > 0) {
+        return { type: 'open', streamId: raw['streamId'], endpoint: raw['endpoint'], payload: raw['payload'] };
+    }
+    throw new Error('world-mux: invalid client message');
+}
+/** Default failure mapper: keep the error code when it looks like one. */
+export function defaultFailure(error) {
+    if (isRecord(error)) {
+        const code = typeof error['code'] === 'string' ? error['code'] : undefined;
+        const message = typeof error['message'] === 'string' ? error['message'] : undefined;
+        if (code !== undefined) {
+            const details = isRecord(error['details']) ? error['details'] : {};
+            return { code, message: message ?? code, details };
+        }
+    }
+    return { code: 'gateway/stream-error', message: error instanceof Error ? error.message : String(error), details: {} };
+}
+/** One uplink violation: an abort reason that must reach the client as a failure frame. */
+function uplinkViolation(code, message, endpoint) {
+    return Object.assign(new Error(message), { code, details: { endpoint } });
+}
+/**
+ * Bounded single-consumer uplink queue of one logical stream, the source the
+ * world method reads as its uplink iterable. Mirrors upstream `UplinkInbox`:
+ * overflow, and an item after the client's `end`, fail the queue and abort the
+ * logical stream with a wire failure.
+ */
+class UplinkInbox {
+    maxBytes;
+    endpoint;
+    onViolation;
+    queue = [];
+    bytes = 0;
+    ended = false;
+    closed = false;
+    taken = false;
+    failure;
+    wake;
+    constructor(maxBytes, endpoint, onViolation) {
+        this.maxBytes = maxBytes;
+        this.endpoint = endpoint;
+        this.onViolation = onViolation;
+    }
+    push(value, frameBytes) {
+        if (this.failure !== undefined || this.closed)
+            return;
+        if (this.ended) {
+            this.violate(uplinkViolation('gateway/protocol', 'world-mux: Remote stream uplink item after end', this.endpoint));
+            return;
+        }
+        if (this.bytes + frameBytes > this.maxBytes) {
+            this.violate(uplinkViolation('gateway/uplink-overflow', `world-mux: Remote stream uplink exceeded ${String(this.maxBytes)} buffered bytes`, this.endpoint));
+            return;
+        }
+        this.queue.push({ value, bytes: frameBytes });
+        this.bytes += frameBytes;
+        this.signal();
+    }
+    /** Client half-close; idempotent. */
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.signal();
+    }
+    /** End the consumer's next read with `error`; idempotent, drops buffered items. */
+    fail(error) {
+        if (this.failure !== undefined)
+            return;
+        this.failure = error;
+        this.queue.length = 0;
+        this.bytes = 0;
+        this.signal();
+    }
+    [Symbol.asyncIterator]() {
+        if (this.taken)
+            throw new Error('world-mux: Remote stream uplink inbox already has a consumer');
+        this.taken = true;
+        return this;
+    }
+    async next() {
+        while (true) {
+            if (this.closed)
+                return UPLINK_DONE;
+            const entry = this.queue.shift();
+            if (entry !== undefined) {
+                this.bytes -= entry.bytes;
+                return { value: entry.value, done: false };
+            }
+            if (this.failure !== undefined)
+                throw this.failure;
+            if (this.ended)
+                return UPLINK_DONE;
+            if (this.wake !== undefined)
+                throw new Error('world-mux: Remote stream uplink inbox has one pending read');
+            await new Promise((resolve) => { this.wake = resolve; });
+        }
+    }
+    /** Consumer stopped reading: later items are dropped, a pending read ends. */
+    return() {
+        this.closed = true;
+        this.queue.length = 0;
+        this.bytes = 0;
+        this.signal();
+        return Promise.resolve(UPLINK_DONE);
+    }
+    violate(error) {
+        this.fail(error);
+        this.onViolation(error);
+    }
+    signal() {
+        const wake = this.wake;
+        this.wake = undefined;
+        wake?.();
+    }
+}
+/** One world's mux endpoint. */
+export class WorldMuxServer {
+    open;
+    options;
+    server;
+    ws;
+    heartbeat;
+    connections = new Set();
+    missed = new WeakMap();
+    closed = false;
+    constructor(open, options = {}) {
+        this.open = open;
+        this.options = options;
+    }
+    /** Take over one accepted upgrade request. */
+    async handleUpgrade(req, socket, head) {
+        const { server, ws } = await this.load();
+        server.handleUpgrade(req, socket, head, (client) => {
+            this.missed.set(client, 0);
+            client.on('pong', () => { this.missed.set(client, 0); });
+            this.startHeartbeat();
+            const done = this.runConnection(client, ws);
+            this.connections.add(done);
+            void done.then(() => { this.connections.delete(done); });
+        });
+    }
+    /** Terminate every socket and wait for the active streams to unwind. */
+    async close() {
+        this.closed = true;
+        clearInterval(this.heartbeat);
+        this.heartbeat = undefined;
+        const server = this.server;
+        if (server !== undefined) {
+            for (const client of server.clients)
+                client.terminate();
+            await new Promise((resolve) => { server.close(() => resolve()); });
+        }
+        await Promise.all([...this.connections]);
+    }
+    async load() {
+        if (this.server !== undefined && this.ws !== undefined)
+            return { server: this.server, ws: this.ws };
+        const mod = (await import(WS_MODULE));
+        const ws = typeof mod.WebSocketServer === 'function' ? mod : mod.default;
+        const server = new ws.WebSocketServer({ noServer: true });
+        this.server = server;
+        this.ws = ws;
+        return { server, ws };
+    }
+    async runConnection(client, ws) {
+        const streams = new Map();
+        let writes = Promise.resolve();
+        const send = (message) => {
+            let text;
+            try {
+                text = JSON.stringify(message);
+            }
+            catch (cause) {
+                return Promise.reject(new Error('world-mux: item is not JSON serializable', { cause }));
+            }
+            const delivery = writes.then(() => new Promise((resolve, reject) => {
+                if (client.readyState !== ws.WebSocket.OPEN) {
+                    reject(new Error('world-mux: socket is closed'));
+                    return;
+                }
+                client.send(text, (error) => { if (error)
+                    reject(error);
+                else
+                    resolve(); });
+            }));
+            writes = delivery.catch(() => undefined);
+            return delivery;
+        };
+        const failureOf = this.options.failure ?? defaultFailure;
+        const sendFailure = async (streamId, error) => {
+            if (client.readyState !== ws.WebSocket.OPEN)
+                return;
+            try {
+                await send({ type: 'error', streamId, error: failureOf(error) });
+            }
+            catch {
+                client.close(1011, 'Remote stream failure could not be delivered');
+            }
+        };
+        const pump = async (streamId, endpoint, payload, active) => {
+            let failed;
+            try {
+                const source = await this.open(endpoint, payload, active.inbox, active.abort);
+                for await (const value of source) {
+                    await send({ type: 'item', streamId, value });
+                }
+            }
+            catch (error) {
+                failed = { error };
+            }
+            // The downlink has settled; later uplink frames cannot change the outcome.
+            active.inbox.fail(new Error('world-mux: Remote stream ended'));
+            if (active.abort.signal.aborted) {
+                // A wire failure as the abort reason is this mux failing the stream (a
+                // rejected or overflowing uplink item, or an item after end); the client
+                // is still waiting for that terminal frame. Any other abort is a
+                // cancellation and stays silent.
+                const reason = active.abort.signal.reason;
+                if (isRemoteFailure(reason))
+                    await sendFailure(streamId, reason);
+                return;
+            }
+            if (failed !== undefined) {
+                await sendFailure(streamId, failed.error);
+                return;
+            }
+            try {
+                await send({ type: 'end', streamId });
+            }
+            catch (error) {
+                await sendFailure(streamId, error);
+            }
+        };
+        await new Promise((resolve) => {
+            client.once('close', () => { resolve(); });
+            client.on('error', () => { client.terminate(); });
+            client.on('message', (data, isBinary) => {
+                if (isBinary === true) {
+                    client.close(1003, 'text messages required');
+                    return;
+                }
+                const text = String(data);
+                let message;
+                try {
+                    message = parseClientMessage(text);
+                }
+                catch {
+                    client.close(1008, 'invalid Remote stream request');
+                    return;
+                }
+                if (message.type === 'open') {
+                    if (streams.has(message.streamId)) {
+                        client.close(1008, 'duplicate Remote stream id');
+                        return;
+                    }
+                    const abort = new AbortController();
+                    // Created before the opener resolves so items the client sends right
+                    // after `open` wait in the inbox instead of being lost.
+                    const inbox = new UplinkInbox(this.options.streamInboxBytes ?? DEFAULT_STREAM_INBOX_BYTES, message.endpoint, (error) => { abort.abort(error); });
+                    const active = {
+                        abort,
+                        inbox,
+                        stop: (reason) => {
+                            abort.abort(reason);
+                            inbox.fail(reason);
+                        },
+                        done: Promise.resolve(),
+                    };
+                    streams.set(message.streamId, active);
+                    const done = pump(message.streamId, message.endpoint, message.payload, active);
+                    active.done = done;
+                    void done.then(() => streams.delete(message.streamId), () => streams.delete(message.streamId));
+                    return;
+                }
+                // `item`, `end`, and `cancel` for a stream this connection no longer
+                // owns are dropped: a finished stream leaves the table while the
+                // client's in-flight frames are still arriving.
+                if (message.type === 'item') {
+                    streams.get(message.streamId)?.inbox.push(message.value, Buffer.byteLength(text, 'utf8'));
+                    return;
+                }
+                if (message.type === 'end') {
+                    streams.get(message.streamId)?.inbox.end();
+                    return;
+                }
+                streams.get(message.streamId)?.stop(new Error('world-mux: Remote stream cancelled'));
+            });
+        });
+        const active = [...streams.values()];
+        for (const stream of active)
+            stream.stop(new Error('world-mux: Remote stream socket closed'));
+        await Promise.all(active.map(stream => stream.done));
+    }
+    startHeartbeat() {
+        if (this.heartbeat !== undefined || this.closed)
+            return;
+        const interval = this.options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+        this.heartbeat = setInterval(() => {
+            const server = this.server;
+            if (server === undefined)
+                return;
+            for (const client of server.clients) {
+                if (client.readyState !== (this.ws?.WebSocket.OPEN ?? 1))
+                    continue;
+                const missed = this.missed.get(client) ?? 0;
+                if (missed >= MAX_MISSED_HEARTBEATS) {
+                    client.terminate();
+                    continue;
+                }
+                this.missed.set(client, missed + 1);
+                client.ping();
+            }
+        }, interval);
+        this.heartbeat.unref();
+    }
+}

package/{agent-hub → superd-hub}/dist/world-provision.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Resolve the running dsh installation's package.json — the anchor worlds
+ * resolve `@deepseek-ai` bundles and the fallback closure from.
+ *
+ * Precedence: `$SUPERD_DSH_ANCHOR` (the repo dev lines' contract — the
+ * launcher pins the checkout build), then a walk UP from the
+ * `@deepseek-ai/dsh-app-boot` this module resolved (the host always provides
+ * it) to the nearest ancestor package named `@deepseek-ai/dsh` — the
+ * packaged-install layout (`<install>/@deepseek-ai/dsh/node_modules/
+ * @deepseek-ai/dsh-app-boot`) lands on the install root in two hops. No
+ * machine-specific path ships in code.
+ * @throws when neither yields an installation (mis-launched composition).
+ */
+export declare function resolveInstallAnchor(host?: {
+    get(name: string): unknown;
+}): string;
 export interface ProvisionWorldOptions {
     /** Runtime key — also the mount label and the `agents/<key>` home segment. */
     key: string;
@@ -10,11 +26,11 @@ export interface ProvisionWorldOptions {
 }
 /**
  * Provision one world's nested profile (idempotent: rewrites profile files,
- * re-links packages — lstat-safe against dangling links). Returns the
- * `bareModuleBaseUrl` for {@link spawnWorld}, or null when unresolvable.
+ * re-links packages — lstat-safe against dangling links). Returns whether
+ * the layout landed.
  *
- * Never throws: any provisioning failure is logged and returns null so the
+ * Never throws: any provisioning failure is logged and returns false so the
  * calling world plugin degrades to a not-ready roster row instead of failing
  * the loader entry — a failed apply would take down the whole host boot.
  */
-export declare function provisionWorldProfile(opts: ProvisionWorldOptions): string | null;
+export declare function provisionWorldProfile(opts: ProvisionWorldOptions): boolean;

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

@@ -0,0 +1,203 @@
+/**
+ * Nested-world profile provisioning — the publish story.
+ *
+ * The dev line (test/smoke.mjs) hand-provisions every world's nested profile
+ * (`<home>/agents/<label>/profiles/web`) and the `@pgmi-builds/*` links its
+ * resolution needs. A foreign install has NO line bootstrap:
+ *
+ *   dsh plugin --profile <name> add super-dsh
+ *
+ * mounts the hub + adapter world plugins into the consumer's profile, and the
+ * spawn call sites (adapter world-plugins, hub join) must provision the same
+ * layout THEMSELVES or every world spawn fails on a missing profile.
+ *
+ * This module is the library form of that bootstrap, called by all six spawn
+ * sites. Layout invariants (super-dsh/AGENTS.md S7):
+ *
+ *   - `<worldHome>/profiles/web/package.json` — bundles `[dsh-base, dsh-web-app,
+ *     adapterPkg]`; the world tree is a full sibling root, nothing shared.
+ *   - `<worldHome>/profiles/web/cordis.patch.yml` — per-world home pinning:
+ *     every home-resolving DSH plugin reads THIS tree's nested root.
+ *   - `<worldHome>/profiles/web/node_modules/@pgmi-builds/{adapter,hub}` —
+ *     the plugin-add shape: with the host table widened (spawnWorld, spec
+ *     §2.1), these profile-local links serve the local-physical leg for the
+ *     world's own packages. No `@deepseek-ai` scope anywhere — those names
+ *     ride the host's installation entries.
+ *
+ * Link identity rule: both links point INSIDE the running line tree — the hub
+ * at this module's own package root, the adapter at its sibling
+ * `agent-<key>` directory — identical in the dev repo layout and inside the
+ * published single `super-dsh` package, so ctx0 and every world root share
+ * one hub/adapter instance with zero registry involvement.
+ *
+ * Returns whether the layout was provisioned; false (logged) when the
+ * adapter sibling does not exist next to the hub — a foreign composition
+ * this module does not own.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+const HUB_SCOPE = '@pgmi-builds';
+/** The profile bundles every world tree composes besides its adapter. */
+const WORLD_BASE_BUNDLES = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'];
+/**
+ * Resolve the running dsh installation's package.json — the anchor worlds
+ * resolve `@deepseek-ai` bundles and the fallback closure from.
+ *
+ * Precedence: `$SUPERD_DSH_ANCHOR` (the repo dev lines' contract — the
+ * launcher pins the checkout build), then a walk UP from the
+ * `@deepseek-ai/dsh-app-boot` this module resolved (the host always provides
+ * it) to the nearest ancestor package named `@deepseek-ai/dsh` — the
+ * packaged-install layout (`<install>/@deepseek-ai/dsh/node_modules/
+ * @deepseek-ai/dsh-app-boot`) lands on the install root in two hops. No
+ * machine-specific path ships in code.
+ * @throws when neither yields an installation (mis-launched composition).
+ */
+export function resolveInstallAnchor(host) {
+    // Spec §2.3: the host's launcher facts win — a world plugin runs in ctx0,
+    // where `profileContext` carries the exact anchor the live table was
+    // computed from. Env and the realpath walk remain for table-less harnesses.
+    const launcher = host?.get('profileContext');
+    if (launcher?.installAnchor !== undefined)
+        return launcher.installAnchor;
+    const fromEnv = process.env.SUPERD_DSH_ANCHOR;
+    if (fromEnv !== undefined && fromEnv !== '')
+        return fromEnv;
+    let dir = dirname(resolveHostPackageDir('@deepseek-ai/dsh-app-boot'));
+    while (true) {
+        const manifest = join(dir, 'package.json');
+        if (existsSync(manifest)) {
+            try {
+                const name = JSON.parse(readFileSync(manifest, 'utf8')).name;
+                if (name === '@deepseek-ai/dsh')
+                    return manifest;
+            }
+            catch { /* malformed intermediate manifest — keep walking */ }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error('super-dsh: cannot derive the dsh installation anchor (set SUPERD_DSH_ANCHOR)');
+        }
+        dir = parent;
+    }
+}
+/** First `node_modules` search-path candidate that exists for a specifier,
+ *  resolved to its REALPATH — farm and pnpm links must not leak into the
+ *  ancestor walk (the install tree only exists behind the symlink). */
+function resolveHostPackageDir(spec) {
+    const require = createRequire(import.meta.url);
+    // Interception first: under the launcher's resolution table the profile
+    // tree holds NO physical @deepseek-ai, but require.resolve goes through
+    // the patched Module._resolveFilename and lands on the installation's
+    // copy directly. resolve.paths() cannot see the table — it only lists
+    // physical walk-up candidates (the retired profiles-level farm is what
+    // used to plug this gap on consumer machines; 0.1.3-r prod evidence).
+    try {
+        return realpathSync(dirname(require.resolve(`${spec}/package.json`)));
+    }
+    catch { /* not intercepted or ./package.json not exported — walk */ }
+    for (const searchPath of require.resolve.paths(`${spec}/x`) ?? []) {
+        const candidate = join(searchPath, spec);
+        if (existsSync(join(candidate, 'package.json')))
+            return realpathSync(candidate);
+    }
+    throw new Error(`super-dsh: cannot resolve ${spec} from the running host (set SUPERD_DSH_ANCHOR)`);
+}
+/**
+ * Provision one world's nested profile (idempotent: rewrites profile files,
+ * re-links packages — lstat-safe against dangling links). Returns whether
+ * the layout landed.
+ *
+ * Never throws: any provisioning failure is logged and returns false so the
+ * calling world plugin degrades to a not-ready roster row instead of failing
+ * the loader entry — a failed apply would take down the whole host boot.
+ */
+export function provisionWorldProfile(opts) {
+    try {
+        return provisionWorldProfileUnchecked(opts);
+    }
+    catch (cause) {
+        console.error(`[super-dsh] provisioning world '${opts.key}' failed:`, cause);
+        return false;
+    }
+}
+function provisionWorldProfileUnchecked(opts) {
+    // Single-pack topology: this module lives at `<line>/superd-hub/dist/`, and
+    // every adapter is a SIBLING directory (`<line>/agent-<key>`) — the same
+    // layout in the repo (dev link: lines) and inside the published `super-dsh`
+    // package. The adapter link therefore points at the sibling; no registry
+    // resolution is involved anywhere.
+    const hubRoot = dirname(dirname(fileURLToPath(import.meta.url))); // <line>/superd-hub
+    const lineRoot = dirname(hubRoot); // monolith root / repo super-dsh/
+    const adapterDir = join(lineRoot, `agent-${opts.key}`);
+    if (!existsSync(join(adapterDir, 'package.json')))
+        return false;
+    const profileName = opts.profileName ?? 'web';
+    const profDir = join(opts.worldHome, 'profiles', profileName);
+    mkdirSync(profDir, { recursive: true });
+    writeFileSync(join(profDir, 'package.json'), JSON.stringify({
+        name: `superd-${opts.key}-world-profile`,
+        private: true,
+        dsh: { profile: { bundles: [...WORLD_BASE_BUNDLES, opts.adapterPkg] } },
+    }, null, 2) + '\n');
+    // Per-world home pinning (smoke.mjs parity): settings, credentials,
+    // attachments, shell env and skills all land inside `agents/<key>/`.
+    // (`agent-instructions` keeps its base `maxBytes` home — instruction
+    // discovery root, not agent data.)
+    //
+    // 0.1.7: the profile hmr row arms itself wherever a profileContext exists,
+    // and its config reload recomposes the tree from THE PROFILE LAYERS ALONE —
+    // spawn-time extraPatches do not survive it. The world posture is therefore
+    // PERSISTED in this layer (webserver disabled + ephemeral port, hmr itself
+    // off, and — T-D — the webui rows `web-runtime`/`client-hmr` off: a world's
+    // composition is a spawn-time fact and must not be re-derived), exactly
+    // mirroring worldMountPatches.
+    writeFileSync(join(profDir, 'cordis.patch.yml'), [
+        '# Per-world home pinning (dshHomePath is this tree\'s nested home).',
+        ...['settings', 'credentials', 'attachment-local', 'shell-env', 'skill-filesystem'].flatMap((id) => [`- id: ${id}`, '  config:', '    dshHome: !!js dshHomePath()']),
+        '# Zero-listener posture (0.1.7): persisted so hmr/launcher recomposition',
+        '# cannot re-enable the world\'s own listener (default port 3080).',
+        '- id: webserver',
+        '  disabled: true',
+        '  config:',
+        '    host: 127.0.0.1',
+        '    port: 0',
+        '- id: hmr',
+        '  disabled: true',
+        '# Webui-less posture (T-D): the world page rows stay off across any',
+        '# recomposition — worlds are pure data planes, `/hub` is the sole entry.',
+        '- id: web-runtime',
+        '  disabled: true',
+        '- id: client-hmr',
+        '  disabled: true',
+        '',
+    ].join('\n'));
+    // @pgmi-builds links, plugin-add shape: adapter + hub into the world
+    // profile's OWN node_modules (resolveBundleDir consults the profile
+    // directory; the local-physical leg of the widened host table consumes
+    // the same links for row imports — spec §2.1). Dangling links first
+    // (lstat: existsSync is false for them, which skipped rmSync and crashed
+    // symlinkSync with EEXIST after repo moves).
+    const links = [
+        [opts.adapterPkg.slice(HUB_SCOPE.length + 1), adapterDir],
+        ['superd-hub', hubRoot],
+    ];
+    const linkRoot = join(profDir, 'node_modules');
+    mkdirSync(join(linkRoot, HUB_SCOPE), { recursive: true });
+    for (const [name, target] of links) {
+        const dst = join(linkRoot, HUB_SCOPE, name);
+        const st = lstatSync(dst, { throwIfNoEntry: false });
+        if (st)
+            rmSync(dst, { recursive: true, force: true });
+        symlinkSync(target, dst);
+    }
+    // Retired machinery (spec §3): scrub the profiles-level farm this function
+    // wrote before 2026-09-25. Stale links there sit inside the widened
+    // local-physical walk and would shadow the host table's installation
+    // entries with frozen-generation targets.
+    const staleFarm = join(opts.worldHome, 'profiles', 'node_modules');
+    rmSync(join(staleFarm, '@deepseek-ai'), { recursive: true, force: true });
+    rmSync(join(staleFarm, HUB_SCOPE), { recursive: true, force: true });
+    return true;
+}