super-dsh 0.1.6 → 0.1.10-e

package/superd-hub/dist/exec-pty-session.js

@@ -0,0 +1,234 @@
+// PTY session machinery — PORTED from better-dsh src/remote/pty-session.ts
+// (spec §8.2 / D12 "原样照抄"), with the ONE sanctioned adaptation: the
+// subprocess spawn is replaced by the PtyChannel seam (exec-pty-channel.ts) —
+// every state transition (init nonce handshake, FIFO dispatch, P8 two-stage
+// interrupt \x03 + injected 130-marker, 3s grace, group-kill fallback, idle
+// TTL, OUTPUT_HARD_CAP with surrogate-pair-safe slicing, I1 waiter hygiene)
+// is the ported logic, unchanged.
+import { buildInitCommand, createNonceFrameParser, genNonce, wrapPtyCommand } from './exec-pty-framing.js';
+/** spec §五.2 逐字。 */
+export const RECONNECT_NOTICE = '[remote: session reconnected to fresh shell; cwd reset to default]';
+const DEFAULT_INIT_TIMEOUT_SEC = 30;
+const INTERRUPT_GRACE_MS = 3_000;
+/** pty 收集内存安全帽（Ruling P15，与 oneshot HARD_CAP 对齐）：模型面只见尾窗，保留尾部。 */
+const OUTPUT_HARD_CAP = 4_000_000;
+export class PtySession {
+    opts;
+    state = 'cold';
+    startPromise = null;
+    queue = Promise.resolve();
+    idleTimer = null;
+    onChunk = null;
+    deathWaiters = [];
+    inFlight = 0;
+    lastSettleAt = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.opts.channel.onDead(() => this.markDead());
+    }
+    get sessionState() { return this.state; }
+    /** status 面快照：state + busy（有命令在跑）+ idleMs（上次 settle 至今）。 */
+    get snapshot() {
+        return { state: this.state, busy: this.inFlight > 0, idleMs: this.lastSettleAt > 0 ? Date.now() - this.lastSettleAt : null };
+    }
+    /** 同一会话命令严格串行（FIFO）；死亡/冷态先重启。 */
+    dispatch(cmd, dOpts = {}) {
+        const attempt = async () => {
+            const started = Date.now();
+            const reconnected = this.state === 'dead';
+            if (this.state !== 'ready')
+                await this.start();
+            this.inFlight++;
+            return await new Promise((resolve) => {
+                const nonce = genNonce();
+                let output = '';
+                let interrupted = false;
+                let settled = false;
+                let interruptTimer;
+                let killTimer;
+                const deathWaiter = () => finish({ output, exit: null, cwd: null, timedOut: interrupted });
+                const cleanup = () => {
+                    this.onChunk = null;
+                    // I1（终审）：已结算 dispatch 的死亡等待必须摘除——否则闭包钉住整段 output，
+                    // 长命会话每调用累积一个 waiter（init 路径的 filter 同款形态）
+                    this.deathWaiters = this.deathWaiters.filter((w) => w !== deathWaiter);
+                    if (interruptTimer !== undefined)
+                        clearTimeout(interruptTimer);
+                    if (killTimer !== undefined)
+                        clearTimeout(killTimer);
+                };
+                const finish = (r) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    this.inFlight--;
+                    this.lastSettleAt = Date.now();
+                    this.resetIdleTimer();
+                    resolve({ ...r, reconnected, durationMs: Date.now() - started });
+                };
+                const parser = createNonceFrameParser(nonce, {
+                    onOutput: (t) => {
+                        output += t;
+                        // C1（终审）：内存安全帽——无帽时一条 cat /dev/urandom 能在 120s 看门狗内
+                        // 吃垮宿主 daemon。帽上切片避开代理对（首字符为低位代理则让出一字符）。
+                        if (output.length > OUTPUT_HARD_CAP) {
+                            output = output.slice(output.length - OUTPUT_HARD_CAP);
+                            if (output.charCodeAt(0) >= 0xdc00 && output.charCodeAt(0) <= 0xdfff)
+                                output = output.slice(1);
+                        }
+                    },
+                    onFrame: ({ exit, cwd }) => finish({ output, exit, cwd, timedOut: interrupted }),
+                });
+                this.onChunk = (c) => parser.feed(c);
+                this.write(wrapPtyCommand(cmd, nonce));
+                if (dOpts.stdin !== undefined)
+                    this.write(dOpts.stdin); // Ruling 11: REPL 式紧随
+                interruptTimer = setTimeout(() => {
+                    interrupted = true;
+                    // P8 两段打断：\x03 中断前台作业后，交互 bash 会放弃当前命令行的剩余部分
+                    // （尾部 marker 不再执行）；紧随注入的同 nonce 130-marker 行在 bash 回到
+                    // 读取态后被执行。无论 bash 弃行还是续行，帧都在宽限内到达且 exit=130，
+                    // 会话存活；若命令 trap 掉 SIGINT，原 marker 先帧、注入行帧后字节被丢弃。
+                    this.write('\x03');
+                    this.write(`printf '\\033]133;D;${nonce};130;%s\\007' "$PWD"\n`);
+                    killTimer = setTimeout(() => {
+                        // Ruling 8 的 kill 兜底：宽限无帧 = 会话不可恢复，杀整组后收尸
+                        // （否则 trap-INT 的卡死进程永生，重连后旧组再不可达）
+                        this.opts.channel.kill();
+                        this.markDead();
+                        finish({ output, exit: null, cwd: null, timedOut: true });
+                    }, INTERRUPT_GRACE_MS);
+                }, dOpts.timeoutSec === undefined ? 120_000 : dOpts.timeoutSec * 1_000);
+                this.deathWaiters.push(deathWaiter);
+            });
+        };
+        const run = this.queue.then(attempt, attempt);
+        this.queue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** TTL / row teardown：尽力 exit，1s 后杀组，出池。 */
+    async dispose() {
+        if (this.state === 'disposed')
+            return;
+        this.clearIdleTimer();
+        this.state = 'disposed';
+        this.startPromise = null;
+        this.opts.channel.close();
+        this.opts.onDead?.();
+    }
+    write(s) {
+        this.opts.channel.write(s);
+    }
+    async start() {
+        if (this.state === 'disposed')
+            throw new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.key}' was disposed — the pool replaces disposed sessions; this reference is stale`);
+        if (this.startPromise === null) {
+            this.state = 'starting';
+            this.startPromise = this.doStart().catch((err) => {
+                this.startPromise = null;
+                this.markDead();
+                throw err;
+            });
+        }
+        return this.startPromise;
+    }
+    async doStart() {
+        const initTimeoutSec = this.opts.initTimeoutSec ?? DEFAULT_INIT_TIMEOUT_SEC;
+        const initNonce = genNonce();
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.opts.channel.kill();
+                reject(new Error(`[E_SESSION_START] remote pty session '${this.opts.key}' did not initialize in ${initTimeoutSec}s` +
+                    (this.diag().length > 0 ? `; transport stderr tail: ${this.diag()}` : '')));
+            }, initTimeoutSec * 1_000);
+            const waiter = () => {
+                clearTimeout(timer);
+                reject(new Error(`[E_SESSION_DIED] remote pty session '${this.opts.key}' died before initializing` +
+                    (this.diag().length > 0 ? `; transport stderr tail: ${this.diag()}` : '')));
+            };
+            this.deathWaiters.push(waiter);
+            const parser = createNonceFrameParser(initNonce, {
+                onFrame: () => {
+                    clearTimeout(timer);
+                    this.deathWaiters = this.deathWaiters.filter((w) => w !== waiter);
+                    if (this.state === 'disposed') {
+                        // dispose 竞态 init：不得复活已终态会话（否则重挂 idle timer + 幽灵 ready）
+                        reject(new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.key}' disposed during init`));
+                        return;
+                    }
+                    this.state = 'ready';
+                    this.resetIdleTimer();
+                    resolve();
+                },
+            });
+            this.onChunk = (c) => parser.feed(c);
+            this.opts.channel.open((chunk) => this.onChunk?.(chunk))
+                .catch((err) => {
+                clearTimeout(timer);
+                this.deathWaiters = this.deathWaiters.filter((w) => w !== waiter);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            });
+            this.write(buildInitCommand(initNonce));
+        });
+    }
+    diag() { return this.opts.channel.diag; }
+    markDead() {
+        if (this.state === 'disposed') {
+            // dispose 是终态：不再翻转 state，但在飞 dispatch 的死亡等待仍需立即结算
+            // （row teardown 不是超时——不得等 123s 看门狗，也不得错标 timedOut）
+            const waiters = this.deathWaiters;
+            this.deathWaiters = [];
+            for (const w of waiters)
+                w();
+            return;
+        }
+        this.state = 'dead';
+        this.startPromise = null;
+        this.clearIdleTimer();
+        const waiters = this.deathWaiters;
+        this.deathWaiters = [];
+        for (const w of waiters)
+            w();
+    }
+    resetIdleTimer() {
+        this.clearIdleTimer();
+        this.idleTimer = setTimeout(() => void this.dispose(), this.opts.idleTtlSec * 1_000);
+        this.idleTimer.unref();
+    }
+    clearIdleTimer() {
+        if (this.idleTimer !== null) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+    }
+}
+/** 会话池：键 → 会话。意外死亡的会话留在池内（下次 dispatch 带 reconnect 提示）。 */
+export class PtyPool {
+    defaults;
+    sessions = new Map();
+    constructor(defaults) {
+        this.defaults = defaults;
+    }
+    get size() { return this.sessions.size; }
+    /** status 面：键上的会话快照（无会话 = undefined → "none — dials on first exec"）。 */
+    inspect(key) {
+        return this.sessions.get(key)?.snapshot;
+    }
+    /** roster 面：池内全部会话。 */
+    list() {
+        return [...this.sessions.entries()].map(([key, s]) => ({ key, snapshot: s.snapshot }));
+    }
+    getOrCreate(key, channelOf) {
+        let s = this.sessions.get(key);
+        if (s === undefined || s.sessionState === 'disposed') {
+            s = new PtySession({ key, channel: channelOf(), ...this.defaults, onDead: () => this.sessions.delete(key) });
+            this.sessions.set(key, s);
+        }
+        return s;
+    }
+    async disposeAll() {
+        await Promise.all([...this.sessions.values()].map((s) => s.dispose()));
+        this.sessions.clear();
+    }
+}

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

@@ -0,0 +1,56 @@
+import type { A2aLogFn } from './a2a-log.js';
+/** Shared-channel Fetch route path this API owns. */
+export declare const EXEC_API_BASE = "/api/superd/exec";
+export interface OneShotExecInput {
+    cmd: string;
+    cwd?: string;
+    timeoutSec?: number;
+}
+export interface OneShotExecResult {
+    exit: number | null;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    truncated: boolean;
+    timedOut: boolean;
+    /**
+     * Why the process ended (0.1.7-e, first-person finding F1/F2: `exit:null`
+     * alone conflated spawn failure with signal death):
+     * `exited` — normal exit (exit carries the code);
+     * `signaled` — died by a signal we did not send (exit null);
+     * `timeout` — OUR two-stage kill fired (timedOut true);
+     * `spawn-error` — the process never started (bad cwd / ENOENT); the
+     *   diagnostic rides stderr as `exec: spawn failed — <reason>`.
+     */
+    outcome: 'exited' | 'signaled' | 'timeout' | 'spawn-error';
+}
+/** Per-stream tail window returned to the caller (spec §8.1: 30k). */
+export declare const EXEC_TAIL_WINDOW = 30000;
+/** Per-stream hard retention while running (spec §8.1: 4M ring). */
+export declare const EXEC_RING_HARD_CAP: number;
+export declare const EXEC_DEFAULT_TIMEOUT_SEC = 120;
+export declare const EXEC_MAX_TIMEOUT_SEC = 600;
+export type OneShotExecParsed = {
+    ok: true;
+    value: OneShotExecInput;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validate an exec request body (endpoint and tool share the exact rules):
+ * non-empty `cmd` (≤4096 chars), optional absolute `cwd`, optional integer
+ * `timeoutSec` in [1, 600].
+ */
+export declare function parseOneShotExecBody(body: unknown): OneShotExecParsed;
+/**
+ * Execute one command locally: `bash -lc <cmd>`, detached into its own
+ * process group so the timeout's group kill cannot leak to the hub process.
+ */
+export declare function runOneShotExec(input: OneShotExecInput, log?: A2aLogFn): Promise<OneShotExecResult>;
+/** Cross-machine wire leg: POST the exec request to a paired hub (cookie rides, a2a envelope pattern). */
+export declare function postOneShotExec(origin: string, input: OneShotExecInput, opts?: {
+    cookie?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<OneShotExecResult>;

package/superd-hub/dist/exec.js

@@ -0,0 +1,225 @@
+// One-shot remote execution (spec §8.1, P4): `bash -lc <cmd>` exactly once,
+// per-stream tail windows in the response, hard ring retention behind them,
+// two-stage group kill on timeout. This module is the EXECUTING side (used by
+// the /api/superd/exec endpoint) and the WIRE leg (used by the initiator-side
+// tool); it never decides policy — auth is the shared /api fence's, and the
+// initiator-side per-machine knob lives on the caller's registry row.
+//
+// Output discipline (better-dash lesson, spec §8.1): return the LAST 30k of
+// each stream, retain at most 4M per stream while running (the tail of a
+// capped ring is still the tail of the stream), mark `truncated` whenever a
+// stream's total exceeded what is returned. Kill discipline: SIGTERM to the
+// process GROUP, 2s grace, SIGKILL to the group — `bash -lc` children must
+// not outlive their parent's timeout.
+import { spawn } from 'node:child_process';
+/** Shared-channel Fetch route path this API owns. */
+export const EXEC_API_BASE = '/api/superd/exec';
+/** Per-stream tail window returned to the caller (spec §8.1: 30k). */
+export const EXEC_TAIL_WINDOW = 30_000;
+/** Per-stream hard retention while running (spec §8.1: 4M ring). */
+export const EXEC_RING_HARD_CAP = 4 * 1024 * 1024;
+export const EXEC_DEFAULT_TIMEOUT_SEC = 120;
+export const EXEC_MAX_TIMEOUT_SEC = 600;
+const CMD_MAX_CHARS = 4096;
+const KILL_GRACE_MS = 2_000;
+/**
+ * Validate an exec request body (endpoint and tool share the exact rules):
+ * non-empty `cmd` (≤4096 chars), optional absolute `cwd`, optional integer
+ * `timeoutSec` in [1, 600].
+ */
+export function parseOneShotExecBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        return { ok: false, error: 'exec: request body must be a JSON object' };
+    }
+    const raw = body;
+    if (typeof raw.cmd !== 'string' || raw.cmd.trim() === '') {
+        return { ok: false, error: 'exec: cmd must be a non-empty string' };
+    }
+    if (raw.cmd.length > CMD_MAX_CHARS) {
+        return { ok: false, error: `exec: cmd exceeds ${CMD_MAX_CHARS} characters` };
+    }
+    if (raw.cwd !== undefined && (typeof raw.cwd !== 'string' || !raw.cwd.startsWith('/') || raw.cwd.includes('\0'))) {
+        return { ok: false, error: 'exec: cwd must be an absolute path' };
+    }
+    if (raw.timeoutSec !== undefined && (typeof raw.timeoutSec !== 'number' || !Number.isInteger(raw.timeoutSec) || raw.timeoutSec < 1 || raw.timeoutSec > EXEC_MAX_TIMEOUT_SEC)) {
+        return { ok: false, error: `exec: timeoutSec must be an integer in [1, ${EXEC_MAX_TIMEOUT_SEC}]` };
+    }
+    const known = new Set(['cmd', 'cwd', 'timeoutSec']);
+    for (const key of Object.keys(raw)) {
+        if (!known.has(key))
+            return { ok: false, error: `exec: unknown field "${key}"` };
+    }
+    return {
+        ok: true,
+        value: {
+            cmd: raw.cmd,
+            ...(raw.cwd === undefined ? {} : { cwd: raw.cwd }),
+            ...(raw.timeoutSec === undefined ? {} : { timeoutSec: raw.timeoutSec }),
+        },
+    };
+}
+/**
+ * A capped tail-retaining accumulator: `total` counts every byte ever seen,
+ * `ring` keeps at most EXEC_RING_HARD_CAP of the most recent ones.
+ */
+class TailRing {
+    total = 0;
+    chunks = [];
+    retained = 0;
+    push(chunk) {
+        this.total += chunk.length;
+        this.chunks.push(chunk);
+        this.retained += chunk.length;
+        if (this.retained > EXEC_RING_HARD_CAP) {
+            let drop = this.retained - EXEC_RING_HARD_CAP;
+            while (drop > 0 && this.chunks.length > 0) {
+                const head = this.chunks[0];
+                if (head.length <= drop) {
+                    drop -= head.length;
+                    this.retained -= head.length;
+                    this.chunks.shift();
+                }
+                else {
+                    this.chunks[0] = head.subarray(drop);
+                    this.retained -= drop;
+                    drop = 0;
+                }
+            }
+        }
+    }
+    tail(maxBytes) {
+        if (this.retained <= maxBytes)
+            return Buffer.concat(this.chunks);
+        let skip = this.retained - maxBytes;
+        const out = [];
+        for (const chunk of this.chunks) {
+            if (skip >= chunk.length) {
+                skip -= chunk.length;
+                continue;
+            }
+            out.push(skip === 0 ? chunk : chunk.subarray(skip));
+            skip = 0;
+        }
+        return Buffer.concat(out);
+    }
+}
+/**
+ * Execute one command locally: `bash -lc <cmd>`, detached into its own
+ * process group so the timeout's group kill cannot leak to the hub process.
+ */
+export async function runOneShotExec(input, log) {
+    const started = Date.now();
+    const stdout = new TailRing();
+    const stderr = new TailRing();
+    const timeoutSec = input.timeoutSec ?? EXEC_DEFAULT_TIMEOUT_SEC;
+    let terminationRequested = false;
+    const child = spawn('bash', ['-lc', input.cmd], {
+        ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    let graceTimer;
+    const killTimer = setTimeout(() => {
+        terminationRequested = true;
+        try {
+            if (child.pid !== undefined)
+                process.kill(-child.pid, 'SIGTERM');
+        }
+        catch { /* already gone */ }
+        graceTimer = setTimeout(() => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, 'SIGKILL');
+            }
+            catch { /* already gone */ }
+        }, KILL_GRACE_MS);
+        if (graceTimer.unref)
+            graceTimer.unref();
+    }, timeoutSec * 1000);
+    if (killTimer.unref)
+        killTimer.unref();
+    let spawnError;
+    const exit = await new Promise((resolve) => {
+        child.once('close', (code) => resolve(code));
+        child.once('error', (err) => { spawnError = err.message; resolve(null); });
+    });
+    clearTimeout(killTimer);
+    if (graceTimer !== undefined)
+        clearTimeout(graceTimer);
+    const outText = stdout.tail(EXEC_TAIL_WINDOW).toString('utf8');
+    const errText = spawnError !== undefined
+        ? `exec: spawn failed — ${spawnError}${input.cwd === undefined ? '' : ` (cwd: ${input.cwd})`}`
+        : stderr.tail(EXEC_TAIL_WINDOW).toString('utf8');
+    const timedOut = terminationRequested;
+    const outcome = spawnError !== undefined
+        ? 'spawn-error'
+        : timedOut
+            ? 'timeout'
+            : exit === null
+                ? 'signaled'
+                : 'exited';
+    const result = {
+        exit,
+        stdout: outText,
+        stderr: errText,
+        durationMs: Date.now() - started,
+        truncated: stdout.total > EXEC_TAIL_WINDOW || stderr.total > EXEC_TAIL_WINDOW,
+        timedOut,
+        outcome,
+    };
+    log?.('info', 'exec.run', {
+        cmd: input.cmd,
+        exit: result.exit ?? 'none',
+        durationMs: result.durationMs,
+        ...(outcome === 'exited' ? {} : { outcome }),
+        ...(result.timedOut ? { timedOut: true } : {}),
+        ...(result.truncated ? { truncated: true } : {}),
+    });
+    return result;
+}
+/** Cross-machine wire leg: POST the exec request to a paired hub (cookie rides, a2a envelope pattern). */
+export async function postOneShotExec(origin, input, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const cookie = opts.cookie ?? '';
+    const budgetMs = (input.timeoutSec ?? EXEC_DEFAULT_TIMEOUT_SEC) * 1000 + 15_000;
+    let res;
+    try {
+        res = await fetchImpl(`${origin}${EXEC_API_BASE}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...(cookie === '' ? {} : { cookie }) },
+            body: JSON.stringify(input),
+            signal: AbortSignal.timeout(opts.timeoutMs ?? budgetMs),
+        });
+    }
+    catch (err) {
+        throw new Error(`exec: peer unreachable — ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const body = await res.json().catch(() => undefined);
+    if (res.status !== 200) {
+        const message = typeof body === 'object' && body !== null && typeof body.error === 'string'
+            ? body.error
+            : `exec: peer answered status ${res.status}`;
+        throw new Error(message);
+    }
+    if (typeof body !== 'object' || body === null)
+        throw new Error('exec: peer answered a non-object body');
+    const raw = body;
+    const exit = typeof raw.exit === 'number' || raw.exit === null ? raw.exit : null;
+    const timedOut = raw.timedOut === true;
+    const parsedOutcome = raw.outcome;
+    const outcome = parsedOutcome === 'exited' || parsedOutcome === 'signaled' || parsedOutcome === 'timeout' || parsedOutcome === 'spawn-error'
+        ? parsedOutcome
+        // a pre-0.1.7-e peer carries no outcome — derive the closest honest read
+        : timedOut ? 'timeout' : exit === null ? 'signaled' : 'exited';
+    return {
+        exit,
+        stdout: typeof raw.stdout === 'string' ? raw.stdout : '',
+        stderr: typeof raw.stderr === 'string' ? raw.stderr : '',
+        durationMs: typeof raw.durationMs === 'number' ? raw.durationMs : 0,
+        truncated: raw.truncated === true,
+        timedOut,
+        outcome,
+    };
+}

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

@@ -12,14 +12,36 @@
  * per-world mount registers through `carrier.ts` (AW-B tasks 2-9), which calls
  * the addressed world's own `typertGateway` instance directly — again without
  * any shared selection value.
+ *
+ * Mesh P2 Task 3 adds the federation wiring: mesh-link's machine lifecycle
+ * events drive mesh-federate's registrar (pair/reprobe success → converge the
+ * remote roster into the registries, probe failure → degrade, removal →
+ * defederate), and the `/hub` family's demux gains the federation table ahead
+ * of the local target registry (spec §3.2 dual-key: a6 canonical, label
+ * aliases compatible).
  */
 import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
 /** Stable Cordis plugin name. */
 export declare const name = "superd-hub";
+/** Row config schema (mesh P3 Task 5a): the periodic reprobe sweep's knob —
+ *  seconds between sweeps, default the user mandate's 5 minutes, floored at
+ *  60 by the schema AND clamped again in `startReprobeSweep` (a bare-library
+ *  caller cannot bypass the floor). Patch rows restate the whole config
+ *  object; schema defaults fill the un-configured one. */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    reprobeIntervalSec: z<number, number, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    reprobeIntervalSec: z<number, number, "defined">;
+}>>, "plain">;
+/** The row config's TypeScript face (the schema-declared knob). */
+export interface HubConfig {
+    reprobeIntervalSec?: number;
+}
 /**
  * The plugin form (row contract): applied when the row mounts.
  *
- * Three CTX0-owned contributions, none carrying any selection value:
+ * CTX0-owned contributions, none carrying any selection value:
  *   - the world inventory control plane (read-only);
  *   - the agent roster row baked into ctx0's own index, so the selector lists
  *     every mount path the hub currently serves;
@@ -28,6 +50,21 @@ export declare const name = "superd-hub";
  *     World trees compose this same row, but their `webServer` is the VIRTUAL
  *     per-world translation surface — the `/hub` family belongs to ctx0's
  *     real listener only (one family per process, demuxed by `?agent=`).
+ *   - the mesh federation wiring (mesh P2 Task 3): home resolved HERE at
+ *     registration time (mesh-rpc stays a pure route module; tests inject a
+ *     tmpdir home instead); the one-way seam is mesh-link's federation event
+ *     bus — mesh-federate subscribes, mesh-link never imports it.
+ *   - the periodic reprobe sweep (mesh P3 Task 5a I1-a, user mandate
+ *     "状态更新走单向 API + 5 分钟周期轮询"): every `reprobeIntervalSec`
+ *     (default 300, floor 60) one sweep re-probes every ENABLED remote —
+ *     success converges federation, failure degrades (both via the existing
+ *     mesh-link hooks). CTX0-ONLY, gated by the same WorldWebServer check as
+ *     the `/hub` family: world trees compose this row too (world-mount.ts
+ *     WORLD_HUB_ROW) and must never start their own sweep against the shared
+ *     machines registry.
+ * @param ctx - host plugin context.
+ * @param config - the row config (`reprobeIntervalSec`; schema defaults
+ *   apply when the row is composed without one).
  */
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context, config?: HubConfig): void;
 export default apply;

package/superd-hub/dist/gateway.js

@@ -1,14 +1,29 @@
+import z from '@deepseek-ai/schemastery';
 import { registerSelectorRpc, registryTargets } from './rpc.js';
+import { registerMeshRpc } from './mesh-rpc.js';
+import { startReprobeSweep } from './mesh-link.js';
+import { federatedGatewayOf, startMeshFederation } from './mesh-federate.js';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
 import { agentRosterRow } from './agent-roster.js';
 import { getTarget } from './targets.js';
 import { registerHubRoute } from './hub-route.js';
 import { WorldWebServer } from './world-web-server.js';
+import { registerPtyExecutor } from './exec-pty-rpc.js';
+import { consoleA2aLog } from './a2a-log.js';
 /** Stable Cordis plugin name. */
 export const name = 'superd-hub';
+/** Row config schema (mesh P3 Task 5a): the periodic reprobe sweep's knob —
+ *  seconds between sweeps, default the user mandate's 5 minutes, floored at
+ *  60 by the schema AND clamped again in `startReprobeSweep` (a bare-library
+ *  caller cannot bypass the floor). Patch rows restate the whole config
+ *  object; schema defaults fill the un-configured one. */
+export const Config = z.object({
+    reprobeIntervalSec: z.number().min(60).default(300),
+});
 /**
  * The plugin form (row contract): applied when the row mounts.
  *
- * Three CTX0-owned contributions, none carrying any selection value:
+ * CTX0-owned contributions, none carrying any selection value:
  *   - the world inventory control plane (read-only);
  *   - the agent roster row baked into ctx0's own index, so the selector lists
  *     every mount path the hub currently serves;
@@ -17,9 +32,27 @@ export const name = 'superd-hub';
  *     World trees compose this same row, but their `webServer` is the VIRTUAL
  *     per-world translation surface — the `/hub` family belongs to ctx0's
  *     real listener only (one family per process, demuxed by `?agent=`).
+ *   - the mesh federation wiring (mesh P2 Task 3): home resolved HERE at
+ *     registration time (mesh-rpc stays a pure route module; tests inject a
+ *     tmpdir home instead); the one-way seam is mesh-link's federation event
+ *     bus — mesh-federate subscribes, mesh-link never imports it.
+ *   - the periodic reprobe sweep (mesh P3 Task 5a I1-a, user mandate
+ *     "状态更新走单向 API + 5 分钟周期轮询"): every `reprobeIntervalSec`
+ *     (default 300, floor 60) one sweep re-probes every ENABLED remote —
+ *     success converges federation, failure degrades (both via the existing
+ *     mesh-link hooks). CTX0-ONLY, gated by the same WorldWebServer check as
+ *     the `/hub` family: world trees compose this row too (world-mount.ts
+ *     WORLD_HUB_ROW) and must never start their own sweep against the shared
+ *     machines registry.
+ * @param ctx - host plugin context.
+ * @param config - the row config (`reprobeIntervalSec`; schema defaults
+ *   apply when the row is composed without one).
  */
-export function apply(ctx) {
+export function apply(ctx, config) {
     registerSelectorRpc(ctx, registryTargets);
+    const home = resolveDshHome();
+    registerMeshRpc(ctx, { home });
+    ctx.effect(() => startMeshFederation({ home }), 'superd-hub: mesh federation wiring');
     const on = ctx.on;
     on?.call(ctx, 'webserver/index-inject', (table) => { table.push(agentRosterRow()); });
     ctx.inject(['webServer', 'connection'], (host) => {
@@ -32,13 +65,39 @@ export function apply(ctx) {
         // table — never a shared selection. The requestRejection face is the
         // ctx0 browser-trust fence: auth first, then Host/Origin — the family is
         // never weaker than the neighbors carrying identical traffic.
+        //
+        // Demux (mesh P2 Task 3, spec §3.2 dual-key): the mesh FEDERATION table
+        // first — an exact a6 match is the canonical spelling and beats label
+        // aliases — then the shared local target registry (local runtime keys;
+        // federated a6s are registered there too, so the fallback re-arms a
+        // registration whose memo was cleared independently). Local label aliases
+        // and `?agent=<a6>` therefore both demux; under the astronomically rare
+        // a6↔local-key collision the federation wins deterministically (documented
+        // in mesh-federate's header) instead of last-write-wins in the registry.
+        // I1(a) periodic reprobe sweep — CTX0-ONLY by the same gate as the
+        // `/hub` family below (world trees see a WorldWebServer and returned
+        // early): the machines registry is ctx0-owned, and a per-world timer
+        // would multiply probes against every paired remote. The effect's
+        // disposer IS the sweep disposer — the timer dies with the row
+        // (unref'd, overlap-skipping, per-machine errors swallowed; mesh-link).
+        ctx.effect(() => startReprobeSweep({ home, intervalSec: config?.reprobeIntervalSec, immediate: true }), 'superd-hub: mesh reprobe sweep');
         const dispose = registerHubRoute({
             real: real,
             authorize: (req, res) => connection.authorizeIndex(req, res),
             requestRejection: (req) => connection.requestRejection(req),
-            gatewayOf: (label) => getTarget(label)?.gateway,
+            gatewayOf: (label) => (federatedGatewayOf(label) ?? getTarget(label)?.gateway),
         });
         ctx.effect(() => dispose, 'superd-hub: /hub route family');
+        // P4 §8.2: the PTY executor's upgrade route — same gate as the /hub family
+        // (authorizeIndex cookie auth first, then the browser-trust fence). The
+        // dumb pump lives in exec-pty-rpc.ts; a2a-row owns the initiator half.
+        void registerPtyExecutor(real, {
+            authorize: (req, res) => connection.authorizeIndex(req, res),
+            requestRejection: (req) => connection.requestRejection(req),
+            log: consoleA2aLog(),
+        }).then((disposePty) => {
+            ctx.effect(() => disposePty, 'superd-hub: PTY executor upgrade route');
+        }, () => { });
     });
 }
 export default apply;