super-dsh 0.1.11 → 0.1.12

package/agent-codex/dist/codex-runtime-fetch.js

@@ -0,0 +1,293 @@
+/**
+ * codex-runtime-fetch.ts — the lazy, durable Codex runtime the app-server line
+ * falls back to when the operator has NO codex of their own.
+ *
+ * 2026-10-06 user ruling (amends the 2026-10-05 core-discovery order): the
+ * exact-pin `@openai/codex` package must NEVER ride the installation — it went
+ * out as a real `dependencies` entry in 0.1.11, so every registry consumer
+ * downloaded the pinned CLI binary package AND its six aliased platform
+ * binaries (linux-x64/arm64, darwin-x64/arm64, win32-x64/arm64) at install
+ * time. That is the omp-sdk/agy-sdk/codex-sdk rule violated one week after it
+ * was written: SDKs and binaries are second-class — anything a line needs, it
+ * fetches at RUNTIME into its world home, and installs stay clean (no
+ * postinstall, no allow-build, no dependency that ships a binary).
+ *
+ * So the discovery order in codex-runtime.ts is
+ *   CODEX_BIN → PATH CLI → desktop core → world-home runtime (this module),
+ * and this module is the only supplier of that last tier: on the first real
+ * prompt, when override, CLI and desktop all missed, the pinned
+ * `@openai/codex@0.160.0` tree is fetched into
+ *
+ *   <worldHome>/codex-runtime/
+ *     package.json                 written by us (private, never published)
+ *     node_modules/                `npm install --exact --ignore-scripts --omit=dev`
+ *     node_modules/@openai/codex/bin/codex.js   the entry discovery returns
+ *   <worldHome>/codex-runtime.json       marker — written LAST, after the smoke run
+ *   <worldHome>/codex-runtime.lock       atomic (mkdir) bootstrap lock
+ *   <worldHome>/codex-runtime.error.log  written ONLY by a failed fetch
+ *
+ * Why the world home rather than the package root: the package root is the
+ * installed tarball — read-only in every real consumer install, and shared by
+ * every world. The world home (`<dshHome>/agents/codex`) is per-runtime,
+ * writable, and already the home of this adapter's own DSH state.
+ *
+ * Readiness is the ENTRY FILE (checked on every discovery, zero network) plus
+ * the marker's package version: a pin bump in a future adapter must refetch,
+ * and the sync resolver alone would happily keep using the old tree.
+ *
+ * The npm invocation is deliberately `--ignore-scripts`: the codex packages
+ * ship their binaries inside the tarballs, so a fetch needs zero lifecycle
+ * scripts — exactly the property this ruling exists to protect.
+ */
+import { execFile } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { resolveCodexRuntime } from "./codex-runtime.js";
+/** The pinned Codex CLI package this line fetches (ships the app-server binary). */
+export const CODEX_RUNTIME_PACKAGE = "@openai/codex";
+/** Pin of {@link CODEX_RUNTIME_PACKAGE}; bumping it must refetch the tree. */
+export const CODEX_RUNTIME_VERSION = "0.160.0";
+/** The entry `resolveCodexRuntime` returns, relative to the runtime dir. */
+const CODEX_ENTRY_RELATIVE = ["node_modules", CODEX_RUNTIME_PACKAGE, "bin", "codex.js"];
+export function codexRuntimeLayout(worldHome) {
+    const dir = join(worldHome, "codex-runtime");
+    return {
+        dir,
+        manifest: join(dir, "package.json"),
+        entry: join(dir, ...CODEX_ENTRY_RELATIVE),
+        marker: join(worldHome, "codex-runtime.json"),
+        lock: join(worldHome, "codex-runtime.lock"),
+        errorLog: join(worldHome, "codex-runtime.error.log"),
+    };
+}
+/** Read the install marker; undefined when absent or unreadable. */
+export function readCodexRuntimeRecord(worldHome) {
+    const { marker } = codexRuntimeLayout(worldHome);
+    if (!existsSync(marker))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(marker, "utf8"));
+        return typeof parsed === "object" && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fast path: a fetched runtime exists, matches `identity`, and its entry file
+ * is still on disk. Everything else must (re)fetch or (re)discover.
+ */
+export function codexRuntimeCurrent(worldHome, identity) {
+    const record = readCodexRuntimeRecord(worldHome);
+    if (record === undefined)
+        return undefined;
+    if (record.pluginVersion !== identity.pluginVersion)
+        return undefined;
+    if (record.packageVersion !== identity.packageVersion)
+        return undefined;
+    if (!existsSync(codexRuntimeLayout(worldHome).entry))
+        return undefined;
+    return record;
+}
+/** The npm argv the runtime tree is installed with (kept pure for the test). */
+export function codexInstallArgv(packageVersion = CODEX_RUNTIME_VERSION) {
+    return [
+        "install",
+        "--save-exact",
+        "--ignore-scripts",
+        "--omit=dev",
+        `${CODEX_RUNTIME_PACKAGE}@${packageVersion}`,
+    ];
+}
+/** A held lock older than this is treated as abandoned and reclaimed. */
+const LOCK_STALE_MS = 30 * 60 * 1000;
+/** The smoke run's wall-clock cap: `--version` must never wedge a turn. */
+const SMOKE_TIMEOUT_MS = 60_000;
+const execFileAsync = promisify(execFile);
+/**
+ * The PRODUCTION {@link CodexRuntimeFetchDeps}: real npm/Node invocations plus
+ * the marker identity read from this package's own manifest. Kept IN THE
+ * MODULE so the manual pre-warm script and the first-prompt lazy fetch share
+ * ONE implementation — a second copy is exactly how the two paths would drift.
+ */
+export function createCodexRuntimeDeps(options = {}) {
+    const pluginDir = options.pluginDir ?? dirname(dirname(fileURLToPath(import.meta.url)));
+    return {
+        run: async (cmd, args, opts) => {
+            await execFileAsync(cmd, args, { cwd: opts?.cwd, env: options.env, maxBuffer: 64 * 1024 * 1024 });
+        },
+        smoke: async (cmd, args, opts) => {
+            const { stdout } = await execFileAsync(cmd, args, {
+                cwd: opts?.cwd,
+                env: options.env,
+                timeout: opts?.timeoutMs,
+                maxBuffer: 1024 * 1024,
+            });
+            return stdout;
+        },
+        pluginVersion: readPluginVersion(pluginDir),
+        log: (line) => process.stderr.write(`[agent-codex] ${line}\n`),
+        ...(options.env === undefined ? {} : { env: options.env }),
+    };
+}
+/** The version of the adapter package at `pluginDir` (the marker identity half). */
+export function readPluginVersion(pluginDir) {
+    const raw = readFileSync(join(pluginDir, "package.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version !== "string" || parsed.version === "") {
+        throw new Error(`codex: ${join(pluginDir, "package.json")} carries no version`);
+    }
+    return parsed.version;
+}
+/**
+ * Sync discovery across the whole ladder INCLUDING the fetched runtime; a
+ * miss throws (which is the fetch trigger, never surfaced to the user).
+ */
+function discoverWith(worldHome, deps) {
+    return resolveCodexRuntime({
+        ...(deps.discovery ?? {}),
+        ...(deps.env === undefined ? {} : { env: deps.env }),
+        packageEntryCandidates: [codexRuntimeLayout(worldHome).entry],
+    });
+}
+/**
+ * Return a usable Codex runtime for `<worldHome>`, fetching the pinned
+ * package first when the operator's own CODEX_BIN / PATH CLI / desktop core
+ * all miss.
+ *
+ * Idempotent: an operator-provided runtime short-circuits without touching
+ * the network, and so does a complete, matching fetched runtime. Concurrent
+ * callers: the bootstrap is guarded by a `mkdir` lock — a second caller that
+ * finds a FRESH lock throws a clear "fetch in progress" error, while an
+ * abandoned lock (older than {@link LOCK_STALE_MS}) is reclaimed so a crashed
+ * fetch cannot brick the line.
+ *
+ * Failures append to `<worldHome>/codex-runtime.error.log` and throw a single
+ * actionable error — never a partial runtime behind a success marker.
+ */
+export async function ensureCodexRuntime(worldHome, deps) {
+    const usable = (() => {
+        try {
+            return discoverWith(worldHome, deps);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    // An operator runtime (override/CLI/desktop) is always taken as-is; a fetched
+    // runtime is taken only when its pin still matches — a bumped pin refetches.
+    if (usable !== undefined && usable.source !== "package")
+        return usable;
+    const identity = { pluginVersion: deps.pluginVersion, packageVersion: CODEX_RUNTIME_VERSION };
+    if (usable !== undefined && codexRuntimeCurrent(worldHome, identity) !== undefined)
+        return usable;
+    const layout = codexRuntimeLayout(worldHome);
+    mkdirSync(worldHome, { recursive: true });
+    acquireLock(layout, deps);
+    try {
+        // Re-check inside the lock: a peer may have completed the fetch in the
+        // window between our check and the lock, in which case we pay nothing.
+        const raced = (() => {
+            try {
+                return discoverWith(worldHome, deps);
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        if (raced !== undefined && (raced.source !== "package" || codexRuntimeCurrent(worldHome, identity) !== undefined))
+            return raced;
+        try {
+            await buildRuntime(layout, deps, identity);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            const stamp = new Date().toISOString();
+            try {
+                appendFileSync(layout.errorLog, `[${stamp}] codex runtime fetch failed: ${detail}\n`);
+            }
+            catch {
+                /* the trace is best-effort; the throw below is the contract */
+            }
+            throw new Error(`codex: could not fetch the runtime (${CODEX_RUNTIME_PACKAGE}@${CODEX_RUNTIME_VERSION}) at ${layout.dir}: ${detail}. ` +
+                `Pre-warm it by hand with \`npm run fetch-codex-runtime\`, or install a Codex CLI and set CODEX_BIN. Trace: ${layout.errorLog}`);
+        }
+        const resolved = discoverWith(worldHome, deps);
+        deps.log(`codex: runtime ready at ${layout.dir} (${CODEX_RUNTIME_PACKAGE}@${CODEX_RUNTIME_VERSION})`);
+        return resolved;
+    }
+    finally {
+        rmSync(layout.lock, { recursive: true, force: true });
+    }
+}
+/** The idempotent build steps; the marker is written last, after the smoke run. */
+async function buildRuntime(layout, deps, identity) {
+    mkdirSync(layout.dir, { recursive: true });
+    // npm needs a manifest to own the tree; `private` + a throwaway version keep
+    // it unambiguously not-a-publishable-package, and an existing one is left
+    // alone so a later install can still be reproduced by hand.
+    if (!existsSync(layout.manifest)) {
+        writeFileSync(layout.manifest, JSON.stringify({ name: "codex-runtime", private: true, version: "0.0.0" }, null, 2) + "\n");
+    }
+    deps.log(`codex: fetching ${CODEX_RUNTIME_PACKAGE}@${CODEX_RUNTIME_VERSION} into ${layout.dir}`);
+    await deps.run("npm", codexInstallArgv(), { cwd: layout.dir });
+    if (!existsSync(layout.entry)) {
+        throw new Error(`npm install produced no ${layout.entry} (the package layout changed?)`);
+    }
+    // Smoke step: run the fetched entry's `--version`. This exercises the real
+    // platform-binary pick the entry performs at run time — a tree whose binary
+    // does not match this host fails HERE, at the fetch, with a trace on disk,
+    // instead of at the first prompt inside the agent's cold-start error path.
+    // The entry is resolved ABSOLUTE before the cwd switch — the smoke run
+    // changes the working directory, and a relative worldHome would otherwise
+    // re-resolve against it (same trap as the `-c model_catalog_json` lesson).
+    const smokeEntry = resolve(layout.entry);
+    deps.log(`codex: smoke-running ${CODEX_RUNTIME_PACKAGE}@${CODEX_RUNTIME_VERSION} --version`);
+    const stdout = await deps.smoke(process.execPath, [smokeEntry, "--version"], { cwd: layout.dir, timeoutMs: SMOKE_TIMEOUT_MS });
+    const smokeVersion = stdout.trim().split("\n")[0]?.trim() ?? "";
+    if (smokeVersion === "") {
+        throw new Error(`smoke run of ${layout.entry} --version produced no output`);
+    }
+    // Marker LAST — a crash before this point leaves an incomplete runtime that
+    // the next call heals, never a false success.
+    const record = {
+        ...identity,
+        entryPath: layout.entry,
+        smokeVersion,
+        installedAt: new Date().toISOString(),
+    };
+    writeFileSync(layout.marker, JSON.stringify(record, null, 2) + "\n");
+    rmSync(layout.errorLog, { force: true });
+}
+/**
+ * mkdir-based mutex. Returns owning the lock; throws when a fresh lock is held
+ * by someone else; reclaims a lock older than {@link LOCK_STALE_MS}.
+ */
+function acquireLock(layout, deps) {
+    for (;;) {
+        try {
+            mkdirSync(layout.lock);
+            return;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        let ageMs;
+        try {
+            ageMs = Date.now() - statSync(layout.lock).mtimeMs;
+        }
+        catch {
+            continue; // released between the mkdir attempt and the stat — retry now
+        }
+        if (ageMs > LOCK_STALE_MS) {
+            deps.log(`codex: reclaiming stale runtime lock (age ${Math.round(ageMs / 1000)}s)`);
+            rmSync(layout.lock, { recursive: true, force: true });
+            continue;
+        }
+        throw new Error(`codex: another runtime fetch is already in progress (lock ${layout.lock}). ` +
+            `Retry once it finishes; if no fetch is running, remove that lock directory.`);
+    }
+}

package/agent-codex/dist/codex-runtime.js

@@ -1,6 +1,5 @@
 /** Resolve an installed Codex runtime at first use, without modifying its home. */
 import { accessSync, constants, realpathSync, statSync } from "node:fs";
-import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { posix, win32 } from "node:path";
 function readableFile(path) {
@@ -66,6 +65,7 @@ export function resolveCodexRuntime(options = {}) {
         env,
         homeDir: options.homeDir ?? homedir(),
         ...(options.desktopCandidates === undefined ? {} : { desktopCandidates: options.desktopCandidates }),
+        ...(options.packageEntryCandidates === undefined ? {} : { packageEntryCandidates: options.packageEntryCandidates }),
         isFile,
         isExecutable,
         realpath: options.realpath ?? realpathSync,
@@ -84,7 +84,6 @@ export function resolveCodexRuntime(options = {}) {
             }
             return undefined;
         }),
-        resolvePackageEntry: options.resolvePackageEntry ?? (() => createRequire(import.meta.url).resolve("@openai/codex/bin/codex.js")),
     };
     const usable = (command) => !shellWrapper(command) && isFile(command) && (isNodeScript(command, discovery) || isExecutable(command));
     const selected = (command, source) => ({ command, nodeScript: isNodeScript(command, discovery), source });
@@ -97,22 +96,23 @@ export function resolveCodexRuntime(options = {}) {
             throw new Error(`CODEX_BIN ${override} is not a readable JavaScript entry or executable Codex runtime. Fix CODEX_BIN or remove the override.`);
         return selected(command, "override");
     }
+    const cli = discovery.findCommand("codex");
+    if (cli !== undefined && usable(cli))
+        return selected(cli, "cli");
     for (const candidate of desktopPaths(discovery)) {
         if (!shellWrapper(candidate) && isFile(candidate) && isExecutable(candidate))
             return selected(candidate, "desktop");
     }
-    const cli = discovery.findCommand("codex");
-    if (cli !== undefined && usable(cli))
-        return selected(cli, "cli");
-    try {
-        const entry = discovery.resolvePackageEntry();
-        if (isFile(entry))
+    // Last resort only: the runtime the fetch layer materialized into the world
+    // home. It cannot pre-exist on a clean install — the fetch only runs when the
+    // override, CLI and desktop all missed, so checking it last is exact.
+    for (const entry of discovery.packageEntryCandidates ?? []) {
+        if (!shellWrapper(entry) && isFile(entry))
             return { command: entry, nodeScript: true, source: "package" };
     }
-    catch {
-        // Installation fallback only; authentication/generation never reaches here.
-    }
-    throw new Error("cannot locate a Codex runtime: install Codex desktop or a user CLI on PATH, restore the exact-pin @openai/codex package, or set CODEX_BIN to its executable or JavaScript entry.");
+    throw new Error("cannot locate a Codex runtime: install a Codex CLI (or the desktop app) on PATH, " +
+        "set CODEX_BIN to its executable or JavaScript entry, " +
+        "or let the adapter fetch the pinned @openai/codex package into the world home at first prompt.");
 }
 /** Compatibility interface for callers that need only the selected path. */
 export function resolveCodexCommand(options = {}) {

package/agent-codex/dist/index.js

@@ -20,6 +20,7 @@ import { OPENAI_OAUTH_ID, readEffectiveProviderStore } from "./codex-oauth.js";
  * record and fails closed when the thread is unknown. The rollout scan, the
  * adapter-owned session list and the transcript replay are gone.
  */
+import { bindForeignHub } from '@pgmi-builds/superd-hub/foreign-hub';
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
@@ -411,6 +412,9 @@ export class CodexProvider extends Service {
         this.routes.replace([...ids]);
         trace(`routes replaced: ${ids.join(", ") || "none"}`);
     }
+    hubFor(sessionId) {
+        return bindForeignHub('codex', sessionId, this.home, () => this.runtime.ctx.agents.get(sessionId));
+    }
     async createAgent(ownerCtx, options) {
         const loopCtx = this.runtime.ctx;
         const id = options.sessionId;
@@ -444,7 +448,7 @@ export class CodexProvider extends Service {
         // app-server child is NOT spawned here (lazy-spawn gate, rules §14-i) —
         // create() is pure construction, and the process materializes on the first
         // real prompt.
-        const client = CodexAppServerClient.create({ cwd: spawnCwd, approvalPolicy, sandboxMode });
+        const client = CodexAppServerClient.create({ cwd: spawnCwd, approvalPolicy, sandboxMode, worldHome: this.home, hub: this.hubFor(id) });
         // The session's route is NOT pinned here any more (2026-10-04): the agent
         // resolves it per turn from DSH's own model-selection state, and a launch
         // costs nothing until the first real prompt. `setupAndPublish` still seeds a
@@ -499,7 +503,7 @@ export class CodexProvider extends Service {
         if (record === undefined) {
             throw new CodexResumeError("SESSION_MAP_MISS", `cannot resume session "${id}": no Codex thread is recorded for this Dash session id`);
         }
-        if (record.threadId === null) {
+        if (record.threadId === null && (await readStoredEvents(persistence, id, options.signal)).some(event => event.type === "turn/start" || event.type === "user/message" || event.type === "assistant/message")) {
             // C2: never auto-start a fresh thread — the session's history is in the
             // (missing) native thread, not in a blank one.
             throw new CodexResumeError("NATIVE_THREAD_NEVER_STARTED", `cannot resume session "${id}": its Codex thread was never started (no thread id recorded)`);
@@ -514,7 +518,7 @@ export class CodexProvider extends Service {
         // `<worldHome>/.codex` home (never migrated) and pruned rollouts alike.
         // Without this gate the failure would surface only at the first turn
         // (resumeThread is zero-IO).
-        if (readRolloutHead(resolveCodexHome(), record.threadId) === undefined) {
+        if (record.threadId !== null && readRolloutHead(resolveCodexHome(), record.threadId) === undefined) {
             throw new CodexResumeError("ROLLOUT_MISSING", `cannot resume session "${id}": no rollout for Codex thread ${record.threadId} exists in the current Codex home (${resolveCodexHome()})`);
         }
         // Spawn cwd comes from the recorded pairing — re-realpath and re-verify so
@@ -541,9 +545,11 @@ export class CodexProvider extends Service {
         // rollout). No process is spawned here — lazy-spawn gate, rules §14-i.
         const client = CodexAppServerClient.create({
             cwd: spawnCwd,
-            resumeThreadId: record.threadId,
+            ...(record.threadId === null ? {} : { resumeThreadId: record.threadId }),
             approvalPolicy,
             sandboxMode,
+            worldHome: this.home,
+            hub: this.hubFor(id),
         });
         let handle;
         let stored;

package/agent-codex/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@pgmi-builds/agent-codex",
   "version": "0.1.0",
-  "description": "Codex provider for DeepSeek Harness (dsh) — an AgentFactory that drives a `codex app-server` child process (stdio JSONL JSON-RPC) per session and bridges its thread/turn surface, approvals and permission policy into Dash Agent/Session contracts.",
+  "description": "Codex provider for DeepSeek Harness (dsh) — an AgentFactory that drives a `codex app-server` child process (stdio JSONL JSON-RPC) per session and bridges its thread/turn surface, approvals and permission policy into Dash Agent/Session contracts. Declares NO codex dependency and ships NO postinstall (2026-10-06 ruling): the operator's own CODEX_BIN / PATH CLI / desktop core is discovered at first prompt, and only when all three miss is the pinned `@openai/codex` package fetched at RUNTIME into the world home (src/codex-runtime-fetch.ts, `npm run fetch-codex-runtime`).",
+
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
@@ -9,9 +10,11 @@
   },
   "files": [
     "dist",
+    "scripts",
     "cordis.patch.yml",
     "README.md"
   ],
+
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -19,12 +22,14 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "fetch-codex-runtime": "node scripts/fetch-codex-runtime.mjs"
   },
+
   "dependencies": {
-    "@openai/codex": "0.160.0",
     "zod": "4.4.3"
   },
+
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-agent": ">=0.1.5-0 <0.3.0-0",

package/agent-codex-sdk/dist/sdk-runtime.js

@@ -110,7 +110,7 @@ const LOCK_STALE_MS = 30 * 60 * 1000;
 export function sdkInstallArgv(packageVersion = SDK_PACKAGE_VERSION) {
     return [
         "install",
-        "--exact",
+        "--save-exact",
         "--ignore-scripts",
         "--omit=dev",
         `${SDK_PACKAGE}@${packageVersion}`,

package/agent-hermes/dist/hermes-client.js

@@ -60,10 +60,12 @@
  * as are `HERMES_CWD`/`HERMES_TUI_GATEWAY_URL`/`HERMES_TUI_SIDECAR_URL`
  * (keep the spawned stdio transport the only transport).
  */
-import { spawn } from "node:child_process";
+import { spawn, execFile } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { delimiter, resolve } from "node:path";
+import { delimiter, resolve, join } from "node:path";
+import { promisify } from "node:util";
+import { prepareHermesNativePlugin } from "@pgmi-builds/superd-hub/foreign-native";
 import { createInterface } from "node:readline";
 import { projectGatewayEvent } from "./hermes-events.js";
 const READY_TIMEOUT_MS = 15_000; // TUI parity (STARTUP_TIMEOUT_MS)
@@ -217,13 +219,19 @@ export class HermesGatewayClient {
      * materialized within the grace. Agent-held clients never arm it (ruling 4).
      */
     #spawnGraceTimer = null;
+    #hubPreparation;
+    #hubSession;
     constructor(opts) {
         this.#requestTimeoutMs = opts.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
         this.#approvalTimeoutMs = opts.approvalTimeoutMs ?? APPROVAL_TIMEOUT_MS;
         this.#lazy = opts.lazy === true;
         this.#spawnOpts = opts;
-        if (!this.#lazy)
-            this.#materializeChild();
+        if (!this.#lazy) {
+            if (opts.hub === undefined)
+                this.#materializeChild();
+            else
+                void this.ensureStarted().catch(() => { });
+        }
     }
     /** Captured spawn options for deferred materialization (lazy clients). */
     #spawnOpts;
@@ -237,6 +245,10 @@ export class HermesGatewayClient {
         const root = resolveHermesRoot();
         const python = resolveHermesPython(root);
         const env = { ...(opts.env ?? process.env) };
+        if (this.#hubSession !== undefined)
+            env.SUPERD_HUB_SESSION = this.#hubSession;
+        else
+            delete env.SUPERD_HUB_SESSION;
         // Native `.env` fill (dotenv convention: existing env WINS). The omp and
         // pi runtimes load their own native `.env`; the hermes gateway child does
         // not, and the harness env carries no provider keys — without this fill
@@ -399,6 +411,23 @@ export class HermesGatewayClient {
      *  A lazy client materializes its python child HERE (full-lazy ruling:
      *  view-time resume spawns nothing). */
     ensureStarted() {
+        const hub = this.#spawnOpts.hub;
+        if (hub !== undefined) {
+            if (this.#hubPreparation === undefined) {
+                this.#hubPreparation = (async () => {
+                    if (this.#closed)
+                        throw new Error('hermes gateway client closed');
+                    const prepare = this.#spawnOpts.prepareHub ?? prepareHermesHub;
+                    this.#hubSession = await prepare(hub);
+                    if (this.#closed)
+                        throw new Error('hermes gateway client closed');
+                })().catch(error => { this.#fail(error instanceof Error ? error : new Error(String(error))); throw error; });
+            }
+            return this.#hubPreparation.then(() => this.#startPrepared());
+        }
+        return this.#startPrepared();
+    }
+    #startPrepared() {
         if (this.#readyPromise === null) {
             if (this.#closed || this.#failure !== null) {
                 return Promise.reject(this.#failure ?? new Error("hermes gateway client closed"));
@@ -528,6 +557,7 @@ export class HermesGatewayClient {
         if (this.#closed)
             return;
         this.#closed = true;
+        this.#spawnOpts.hub?.dispose();
         this.#clearSpawnGrace();
         // Fire-and-forget best effort: write the request directly (the RPC path
         // would refuse under #closed and nothing will read the response anyway).
@@ -933,7 +963,7 @@ export class HermesGatewayClient {
             clearTimeout(this.#readyTimer);
             this.#readyTimer = null;
         }
-        if (!this.#readySettled) {
+        if (!this.#readySettled && this.#readyPromise !== null) {
             this.#readySettled = true;
             this.#readyReject(error);
         }
@@ -999,3 +1029,12 @@ export class HermesGatewayClient {
         }
     }
 }
+async function prepareHermesHub(binding) {
+    const root = resolveHermesRoot();
+    const python = resolveHermesPython(root);
+    return prepareHermesNativePlugin(binding, join(homedir(), '.hermes'), async (key) => {
+        const env = { ...process.env, PYTHONPATH: root };
+        delete env.HERMES_HOME;
+        await promisify(execFile)(python, ['-m', 'hermes_cli.main', 'plugins', 'enable', key], { cwd: root, env, timeout: 30_000 });
+    });
+}

package/agent-hermes/dist/index.js

@@ -26,6 +26,7 @@ import { join } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
 import { installModelSelection } from "@deepseek-ai/dsh-agent";
 import { SessionLogOffset, SessionPreparation, interruptedTurnClosers, } from "@deepseek-ai/dsh-session";
+import { bindForeignHub } from "@pgmi-builds/superd-hub/foreign-hub";
 import { HermesGatewayClient, HERMES_SPAWN_GRACE_MS } from "./hermes-client.js";
 import { HermesAgent } from "./agent.js";
 import { HermesLlmAdapter, HERMES_PROVIDER_ID } from "./adapter.js";
@@ -296,6 +297,9 @@ export class HermesProvider extends Service {
             this.runtime.ctx.logger.warn(`hermes-provider: model route swap failed: ${String(error)}`);
         });
     }
+    hubFor(sessionId) {
+        return bindForeignHub('hermes', sessionId, this.home, () => this.runtime.ctx.agents.get(sessionId));
+    }
     async createAgent(ownerCtx, options) {
         const loopCtx = this.runtime.ctx;
         const id = options.sessionId;
@@ -316,7 +320,7 @@ export class HermesProvider extends Service {
         // Agent-held client: the spawn-grace reaper is NEVER armed here (2026-09-17
         // ruling 4 — the session may legitimately materialize far beyond any
         // grace; disposal is the agent lifecycle's job, not a timer's).
-        const client = HermesGatewayClient.spawn({ cwd: spawnCwd, lazy: true }); // full-lazy ruling 2026-09-18: view/create-time spawns NOTHING;
+        const client = HermesGatewayClient.spawn({ cwd: spawnCwd, lazy: true, hub: this.hubFor(id) }); // full-lazy ruling 2026-09-18: view/create-time spawns NOTHING;
         const preparation = SessionPreparation.create(loopCtx.sessions.prepare(id, {
             ...(options.seed === undefined ? {} : { seed: options.seed }),
             ...(meta === undefined ? {} : { meta }),
@@ -360,7 +364,9 @@ export class HermesProvider extends Service {
         if (record === undefined) {
             throw new Error(`cannot resume session "${id}": no Hermes gateway session is recorded for this Dash session id`);
         }
-        if (record.gatewayStoredSessionId === null || record.gatewayStoredSessionId === undefined) {
+        const persistence = this.requirePersistence("resume");
+        if ((record.gatewayStoredSessionId === null || record.gatewayStoredSessionId === undefined)
+            && (await readStoredEvents(persistence, id, options.signal)).some(event => event.type === "turn/start" || event.type === "user/message" || event.type === "assistant/message")) {
             throw new Error(`cannot resume session "${id}": no durable gateway session id is recorded (this record predates durable-id capture; re-create the session)`);
         }
         // Spawn cwd comes from the recorded pairing — re-realpath and re-verify.
@@ -368,7 +374,6 @@ export class HermesProvider extends Service {
         if (spawnCwd === undefined) {
             throw new Error(`cannot resume session "${id}": its recorded working directory no longer exists`);
         }
-        const persistence = this.requirePersistence("resume");
         // Preset (record-only): env override, else the recorded preset, else the
         // persisted session log, else the permission service's default.
         const envMode = envApprovalMode();
@@ -380,7 +385,7 @@ export class HermesProvider extends Service {
         trace(`resume id=${id} spawnCwd=${spawnCwd} preset=${preset ?? "none"}`);
         // Spawn the gateway child (no session bound); the FIRST prompt re-attaches
         // via resumeSession(record.gatewayStoredSessionId) — the DURABLE key.
-        const client = HermesGatewayClient.spawn({ cwd: spawnCwd, lazy: true }); // full-lazy ruling 2026-09-18: view/create-time spawns NOTHING;
+        const client = HermesGatewayClient.spawn({ cwd: spawnCwd, lazy: true, hub: this.hubFor(id) }); // full-lazy ruling 2026-09-18: view/create-time spawns NOTHING;
         let handle;
         let stored;
         let preparation;
@@ -403,7 +408,7 @@ export class HermesProvider extends Service {
             this.followGatewaySessionId(id, client);
             handedOff = true;
             const agentOptions = await this.sessionAgentOptions(options.agentOptions);
-            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "resume", { enterSession: true, preparation }, stored, this.agentRuntime(client, spawnCwd, record.gatewayStoredSessionId));
+            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "resume", { enterSession: true, preparation }, stored, this.agentRuntime(client, spawnCwd, record.gatewayStoredSessionId ?? undefined));
         }
         catch (error) {
             trace(`resume ${id} THREW: ${String(error)} | stack=${error instanceof Error ? error.stack?.slice(0, 400) : "n/a"}`);