super-dsh 0.3.0-e → 0.3.0-g

package/superd-hub/dist/companions.js

@@ -0,0 +1,209 @@
+/** Companion intent and the single native installation operation. */
+import { createHash } from 'node:crypto';
+import { readFile, mkdir, unlink, rmdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+// done marks a CONFIRMED first use (Better observed installed). A receipt with attempted
+// but neither done nor error is an interrupted first use — e.g. killed by the restart
+// that installing Super itself triggers — and must re-arm, not suppress, the retry.
+const message = (error) => error instanceof Error ? error.message : String(error);
+async function optionalJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function nativeFailure(result) {
+    if ((result.application === 'applied' || result.application === 'restart-required') && result.error === undefined
+        && (result.packageResult === undefined || result.packageResult.exitCode === 0))
+        return undefined;
+    return [result.application, result.error?.code, result.error?.diagnostic,
+        result.packageResult?.kind, result.packageResult?.logPath].filter(Boolean).join(': ');
+}
+/** One controller per native profile; no package, registry, HMR or selection writer of its own. */
+export class BetterDashCompanion {
+    version;
+    manager;
+    directory;
+    receipt;
+    legacy;
+    initialized;
+    intent = { attempted: false };
+    active;
+    stopped = false;
+    restartNotice;
+    constructor(profile, version, manager) {
+        this.version = version;
+        this.manager = manager;
+        const key = createHash('sha256').update(profile.dir).digest('hex') + '.json';
+        this.directory = join(profile.home, 'superd', 'companions');
+        this.receipt = join(this.directory, key);
+        this.legacy = join(profile.home, 'companion-registration', key);
+    }
+    initialize() {
+        return this.initialized ??= (async () => {
+            const saved = await optionalJson(this.receipt);
+            if (saved !== undefined) {
+                // Never-resurrect applies only to a CONFIRMED first use or a recorded
+                // failure; an interrupted first use (no done, no error) re-arms.
+                this.intent = saved.attempted && saved.done !== true && saved.error === undefined
+                    ? { attempted: false } : saved;
+                await this.cleanLegacy();
+                return;
+            }
+            const old = await optionalJson(this.legacy);
+            // Any old registration was first use. An absent Better now means removal,
+            // including when Super has since changed version; never resurrect it.
+            if (old?.['super-dsh:better-dsh'] !== undefined) {
+                this.intent = { attempted: true };
+                await this.save();
+                await this.cleanLegacy();
+            }
+        })();
+    }
+    async cleanLegacy() {
+        try {
+            await unlink(this.legacy);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        try {
+            await rmdir(dirname(this.legacy));
+        }
+        catch (error) {
+            if (!['ENOENT', 'ENOTEMPTY'].includes(error.code ?? ''))
+                throw error;
+        }
+    }
+    async save() {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        await writeFileAtomic(this.receipt, JSON.stringify(this.intent) + '\n', { mode: 0o600 });
+    }
+    async getBetterDash() {
+        const status = { installed: false, installing: this.active !== undefined, requestedVersion: this.version };
+        try {
+            await this.initialize();
+            const manager = this.manager();
+            if (manager === undefined)
+                throw new Error('Native Plugin Manager is unavailable; enable it and retry Install in Settings.');
+            const better = (await manager.listBundles()).find(bundle => bundle.name === 'better-dsh' && bundle.installed);
+            if (better !== undefined) {
+                status.installed = true;
+                if (better.version !== undefined)
+                    status.version = better.version;
+                status.enabled = better.enabled;
+                // An installed dependency alone does not prove application succeeded:
+                // native configure can fail after writing that dependency. Only a
+                // missing -> installed recovery clears a previous failure here.
+                if (this.active === undefined && this.intent.attempted
+                    && (this.intent.done !== true || (this.intent.error !== undefined && this.intent.missingAfterFailure === true))) {
+                    this.intent.done = true;
+                    delete this.intent.error;
+                    delete this.intent.missingAfterFailure;
+                    await this.save();
+                }
+            }
+            else {
+                this.restartNotice = undefined;
+                if (this.active === undefined && this.intent.error !== undefined && this.intent.missingAfterFailure !== true) {
+                    this.intent.missingAfterFailure = true;
+                    await this.save();
+                }
+            }
+            const error = this.intent.error ?? this.restartNotice;
+            if (error !== undefined)
+                status.error = error;
+        }
+        catch (error) {
+            status.error = message(error);
+        }
+        return status;
+    }
+    ensureAutomatic() { return this.run(false); }
+    installBetterDash() { return this.run(true); }
+    run(manual) {
+        if (this.active !== undefined)
+            return this.active;
+        const task = this.install(manual).catch(async (error) => {
+            this.intent.error = `Better Dash installation failed: ${message(error)}. Check Better Dash in Plugin Manager; if missing, retry Install in Settings.`;
+            const status = await this.getBetterDash();
+            this.intent.missingAfterFailure = !status.installed;
+            try {
+                await this.save();
+            }
+            catch { /* Report the operation error even when persistence is unavailable. */ }
+            return status;
+        }).then(status => ({ ...status, installing: false })).finally(() => { this.active = undefined; });
+        this.active = task;
+        return task;
+    }
+    async install(manual) {
+        await this.initialize();
+        const before = await this.getBetterDash();
+        if (this.stopped)
+            return before;
+        if (before.installed) {
+            this.intent.attempted = true;
+            this.intent.done = true;
+            if (this.intent.missingAfterFailure === true) {
+                delete this.intent.error;
+                delete this.intent.missingAfterFailure;
+            }
+            await this.save();
+            return this.getBetterDash(); // Native disablement and installed versions belong to the user.
+        }
+        // Native changed notifications enter through this operation, so its
+        // read is active and deliberately cannot update the receipt itself.
+        // Record removal here even when first-use installation is already done.
+        if (this.intent.error !== undefined && this.intent.missingAfterFailure !== true) {
+            this.intent.missingAfterFailure = true;
+            await this.save();
+        }
+        if (!manual && this.intent.attempted)
+            return before;
+        this.intent = { attempted: true };
+        await this.save(); // First use is durable before native HMR can unload this row.
+        const manager = this.manager();
+        if (manager === undefined)
+            throw new Error('Native Plugin Manager is unavailable');
+        if (this.version === 'unknown' || this.version.trim() === '')
+            throw new Error('The installed Super Dash package version could not be read');
+        const failures = [];
+        for (const spec of [`better-dsh@${this.version}`, 'better-dsh@latest', 'better-dsh']) {
+            if (this.stopped)
+                break;
+            try {
+                const result = await manager.installBundle(spec);
+                const failure = nativeFailure(result);
+                if (failure === undefined) {
+                    const after = await this.getBetterDash();
+                    if (after.installed) {
+                        this.intent.done = true;
+                        delete this.intent.error;
+                        delete this.intent.missingAfterFailure;
+                        this.restartNotice = result.application === 'restart-required'
+                            ? 'Better Dash is installed; restart DSH to apply the native change.' : undefined;
+                        await this.save();
+                        return this.getBetterDash();
+                    }
+                    failures.push(`${spec}: native manager reported ${result.application}, but Better Dash is not installed`);
+                }
+                else
+                    failures.push(`${spec}: ${failure}`);
+            }
+            catch (error) {
+                failures.push(`${spec}: ${message(error)}`);
+            }
+        }
+        throw new Error(failures.join('; ') || 'Super Dash companion component was unloaded');
+    }
+    /** Read-only observation: an intermediate native event must never trigger reinstatement. */
+    async observeNativeChange() { return this.getBetterDash(); }
+    dispose() { this.stopped = true; }
+}

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

@@ -1,3 +1,4 @@
+import type { OutputStats } from '../../remote/plugin.js';
 /** 收帧帧体：退出码 + 只读回传的 cwd（Non-Goal ②：报告不重建）。 */
 export interface PtyFrame {
     exit: number;
@@ -11,9 +12,10 @@ export declare function wrapPtyCommand(cmd: string, nonce: string): string;
 export declare function buildInitCommand(nonce: string): string;
 export declare function stripAnsi(s: string): string;
 export declare function normalizePtyText(s: string): string;
-export declare function tailWindow(text: string, cap: number): {
+export declare function tailWindow(text: string, cap: number, stats?: OutputStats): {
     text: string;
     truncated?: number;
+    stats?: OutputStats;
 };
 export interface FrameParserEvents {
     /** 输出文本：feed 路径经 normalize（剥 ANSI/规整换行）；flush 路径为**裸放出**（残余字节原样，勿假设已剥洗）。 */

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

@@ -23,10 +23,18 @@ export function stripAnsi(s) {
 export function normalizePtyText(s) {
     return stripAnsi(s).replace(/\r\n/g, '\n').replace(/\r/g, '');
 }
-export function tailWindow(text, cap) {
-    if (text.length <= cap)
-        return { text };
-    return { text: `[truncated: showing last ${cap} of ${text.length} chars]\n${text.slice(text.length - cap)}`, truncated: text.length };
+export function tailWindow(text, cap, stats) {
+    let tail = text.slice(-cap);
+    if (tail.charCodeAt(0) >= 0xdc00 && tail.charCodeAt(0) <= 0xdfff)
+        tail = tail.slice(1);
+    const returned = stats?.unit === 'bytes' ? Buffer.byteLength(tail) : tail.length;
+    const total = stats?.total ?? text.length;
+    const updated = stats === undefined ? {} : { stats: { ...stats, returned } };
+    if (total <= returned)
+        return { text: tail, ...updated };
+    const unit = stats?.unit === 'bytes' ? 'bytes' : 'chars';
+    const eviction = stats !== undefined && stats.dropped > 0 ? `; retained ${stats.retained}, dropped head ${stats.dropped}, retention limit ${stats.retentionLimit} ${stats.unit === 'bytes' ? 'bytes' : 'UTF-16 code units'}` : '';
+    return { text: `[truncated: showing last ${returned} of ${total} ${unit}${eviction}]\n${tail}`, truncated: total, ...updated };
 }
 const FRAME_BODY_RE = /^(\d+);([^\x07\x1b]*)(?:\x07|\x1b\\)/; // cwd 是尾字段：合法路径可含 `;`，只有 BEL/ESC 终止它
 /**

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

@@ -1,3 +1,4 @@
+import { type StreamOutputStats } from '../../remote/plugin.js';
 import type { PtyChannel } from './exec-pty-channel.js';
 /** spec §五.2 逐字。 */
 export declare const RECONNECT_NOTICE = "[remote: session reconnected to fresh shell; cwd reset to default]";
@@ -15,6 +16,7 @@ export interface PtyDispatchOptions {
 }
 export interface PtyDispatchResult {
     output: string;
+    outputStats?: StreamOutputStats;
     exit: number | null;
     cwd: string | null;
     timedOut: boolean;

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

@@ -1,3 +1,4 @@
+import { Utf16TailRing } from '../../remote/plugin.js';
 // 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) —
@@ -41,12 +42,12 @@ export class PtySession {
             this.inFlight++;
             return await new Promise((resolve) => {
                 const nonce = genNonce();
-                let output = '';
+                const ring = new Utf16TailRing(OUTPUT_HARD_CAP);
                 let interrupted = false;
                 let settled = false;
                 let interruptTimer;
                 let killTimer;
-                const deathWaiter = () => finish({ output, exit: null, cwd: null, timedOut: interrupted });
+                const deathWaiter = () => finish({ output: ring.text, exit: null, cwd: null, timedOut: interrupted });
                 const cleanup = () => {
                     this.onChunk = null;
                     // I1（终审）：已结算 dispatch 的死亡等待必须摘除——否则闭包钉住整段 output，
@@ -65,20 +66,13 @@ export class PtySession {
                     this.inFlight--;
                     this.lastSettleAt = Date.now();
                     this.resetIdleTimer();
-                    resolve({ ...r, reconnected, durationMs: Date.now() - started });
+                    resolve({ ...r, outputStats: { stdout: ring.stats() }, 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);
-                        }
+                        ring.push(t);
                     },
-                    onFrame: ({ exit, cwd }) => finish({ output, exit, cwd, timedOut: interrupted }),
+                    onFrame: ({ exit, cwd }) => finish({ output: ring.text, exit, cwd, timedOut: interrupted }),
                 });
                 this.onChunk = (c) => parser.feed(c);
                 this.write(wrapPtyCommand(cmd, nonce));
@@ -97,7 +91,7 @@ export class PtySession {
                         // （否则 trap-INT 的卡死进程永生，重连后旧组再不可达）
                         this.opts.channel.kill();
                         this.markDead();
-                        finish({ output, exit: null, cwd: null, timedOut: true });
+                        finish({ output: ring.text, exit: null, cwd: null, timedOut: true });
                     }, INTERRUPT_GRACE_MS);
                 }, dOpts.timeoutSec === undefined ? 120_000 : dOpts.timeoutSec * 1_000);
                 this.deathWaiters.push(deathWaiter);

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

@@ -1,8 +1,10 @@
+import { type StreamOutputStats } from '../../remote/plugin.js';
 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;
+    stdin?: string;
     cwd?: string;
     timeoutSec?: number;
 }
@@ -12,6 +14,7 @@ export interface OneShotExecResult {
     stderr: string;
     durationMs: number;
     truncated: boolean;
+    outputStats?: StreamOutputStats;
     timedOut: boolean;
     /**
      * Why the process ended (0.1.7-e, first-person finding F1/F2: `exit:null`
@@ -24,9 +27,9 @@ export interface OneShotExecResult {
      */
     outcome: 'exited' | 'signaled' | 'timeout' | 'spawn-error';
 }
-/** Per-stream tail window returned to the caller (spec §8.1: 30k). */
+/** Per-stream returned tail: at most 30,000 bytes, beginning on a UTF8 boundary. */
 export declare const EXEC_TAIL_WINDOW = 30000;
-/** Per-stream hard retention while running (spec §8.1: 4M ring). */
+/** Hub oneshot per-stream raw-byte retention: 4MiB, distinct from native/PTy UTF16 caps. */
 export declare const EXEC_RING_HARD_CAP: number;
 export declare const EXEC_DEFAULT_TIMEOUT_SEC = 120;
 export declare const EXEC_MAX_TIMEOUT_SEC = 600;

package/superd-hub/dist/exec.js

@@ -12,11 +12,12 @@
 // process GROUP, 2s grace, SIGKILL to the group — `bash -lc` children must
 // not outlive their parent's timeout.
 import { spawn } from 'node:child_process';
+import { ByteTailRing } from '../../remote/plugin.js';
 /** 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). */
+/** Per-stream returned tail: at most 30,000 bytes, beginning on a UTF8 boundary. */
 export const EXEC_TAIL_WINDOW = 30_000;
-/** Per-stream hard retention while running (spec §8.1: 4M ring). */
+/** Hub oneshot per-stream raw-byte retention: 4MiB, distinct from native/PTy UTF16 caps. */
 export const EXEC_RING_HARD_CAP = 4 * 1024 * 1024;
 export const EXEC_DEFAULT_TIMEOUT_SEC = 120;
 export const EXEC_MAX_TIMEOUT_SEC = 600;
@@ -44,7 +45,9 @@ export function parseOneShotExecBody(body) {
     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']);
+    if (raw.stdin !== undefined && typeof raw.stdin !== 'string')
+        return { ok: false, error: 'exec: stdin must be a string' };
+    const known = new Set(['cmd', 'cwd', 'timeoutSec', 'stdin']);
     for (const key of Object.keys(raw)) {
         if (!known.has(key))
             return { ok: false, error: `exec: unknown field "${key}"` };
@@ -53,71 +56,29 @@ export function parseOneShotExecBody(body) {
         ok: true,
         value: {
             cmd: raw.cmd,
+            ...(raw.stdin === undefined ? {} : { stdin: raw.stdin }),
             ...(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 stdout = new ByteTailRing(EXEC_RING_HARD_CAP);
+    const stderr = new ByteTailRing(EXEC_RING_HARD_CAP);
     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'],
+        stdio: ['pipe', 'pipe', 'pipe'],
     });
+    child.stdin.on('error', () => { });
+    child.stdin.end(input.stdin);
     child.stdout.on('data', (chunk) => stdout.push(chunk));
     child.stderr.on('data', (chunk) => stderr.push(chunk));
     let graceTimer;
@@ -148,10 +109,11 @@ export async function runOneShotExec(input, log) {
     clearTimeout(killTimer);
     if (graceTimer !== undefined)
         clearTimeout(graceTimer);
-    const outText = stdout.tail(EXEC_TAIL_WINDOW).toString('utf8');
+    const outTail = stdout.tail(EXEC_TAIL_WINDOW), errTail = stderr.tail(EXEC_TAIL_WINDOW);
+    const outText = outTail.toString('utf8');
     const errText = spawnError !== undefined
         ? `exec: spawn failed — ${spawnError}${input.cwd === undefined ? '' : ` (cwd: ${input.cwd})`}`
-        : stderr.tail(EXEC_TAIL_WINDOW).toString('utf8');
+        : errTail.toString('utf8');
     const timedOut = terminationRequested;
     const outcome = spawnError !== undefined
         ? 'spawn-error'
@@ -165,7 +127,8 @@ export async function runOneShotExec(input, log) {
         stdout: outText,
         stderr: errText,
         durationMs: Date.now() - started,
-        truncated: stdout.total > EXEC_TAIL_WINDOW || stderr.total > EXEC_TAIL_WINDOW,
+        truncated: stdout.total > outTail.length || stderr.total > errTail.length,
+        outputStats: { stdout: stdout.stats(outTail.length), stderr: stderr.stats(errTail.length) },
         timedOut,
         outcome,
     };
@@ -221,5 +184,22 @@ export async function postOneShotExec(origin, input, opts = {}) {
         truncated: raw.truncated === true,
         timedOut,
         outcome,
+        ...(parseOutputStats(raw.outputStats) === undefined ? {} : { outputStats: parseOutputStats(raw.outputStats) }),
+    };
+}
+/** Older peers omit metrics: do not derive exact totals from their returned tail. */
+function parseOutputStats(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const raw = value;
+    const valid = (stats) => {
+        if (typeof stats !== 'object' || stats === null)
+            return false;
+        const s = stats;
+        return (s.unit === 'bytes' || s.unit === 'utf16') && [s.total, s.retained, s.dropped, s.returned, s.retentionLimit].every(n => Number.isSafeInteger(n) && n >= 0)
+            && s.total === s.retained + s.dropped && s.retained <= s.retentionLimit && s.returned <= s.retained;
     };
+    if (!valid(raw.stdout) || (raw.stderr !== undefined && !valid(raw.stderr)))
+        return undefined;
+    return { stdout: raw.stdout, ...(raw.stderr === undefined ? {} : { stderr: raw.stderr }) };
 }

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

@@ -132,6 +132,7 @@ try {
   // is active.
   const isExempt = (path) => path === CONTROL || path.startsWith(CONTROL + '/')
     || path === CONTROL_PREFIX || path.startsWith(CONTROL_PREFIX + '/')
+    || path === '/api/superdCompanions' || path.startsWith('/api/superdCompanions/')
   // Key compare matches the server demux shape: searchParams.get('agent')
   // looks up PERCENT-DECODED keys, so '%61gent=x' demuxes as agent=x and the
   // surgery must strip those spellings too (+' ' wins the '+' spelling).

package/superd-hub/dist/gateway.js

@@ -1,3 +1,5 @@
+import { registerRemoteFileRpc } from './remote-file-rpc.js';
+import { installHubRemoteTransport } from './remote-row.js';
 import z from '@deepseek-ai/schemastery';
 import { registerSelectorRpc, registryTargets } from './rpc.js';
 import { registerMeshRpc } from './mesh-rpc.js';
@@ -60,6 +62,7 @@ export function apply(ctx, config) {
         const real = host.get('webServer');
         if (real instanceof WorldWebServer)
             return;
+        installHubRemoteTransport(host, { home });
         registerPairingAuth(host);
         const connection = host.get('connection');
         // The gate is ctx0's authorize source (connection.authorizeIndex); the
@@ -82,24 +85,34 @@ export function apply(ctx, config) {
         // 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({
+        host.effect(() => startReprobeSweep({ home, intervalSec: config?.reprobeIntervalSec, immediate: true }), 'superd-hub: mesh reprobe sweep');
+        host.effect(() => registerHubRoute({
             real: real,
             authorize: (req, res) => connection.authorizeIndex(req, res),
             requestRejection: (req) => connection.requestRejection(req),
             gatewayOf: (label) => (federatedGatewayOf(label) ?? getTarget(label)?.gateway),
-        });
-        ctx.effect(() => dispose, 'superd-hub: /hub route family');
+        }), '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, {
+        // dumb pump lives in exec-pty-rpc.ts; remote-provider owns the shared initiator implementation.
+        // The async effect belongs to this Connection injection: disposal waits
+        // for setup and releases its route even when setup finishes during unload.
+        host.effect(() => registerRemoteFileRpc(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');
-        }, () => { });
+            requestRejection: req => connection.requestRejection(req),
+        }), 'superd-hub: binary file upgrade route');
+        host.effect(async () => {
+            try {
+                return await registerPtyExecutor(real, {
+                    authorize: (req, res) => connection.authorizeIndex(req, res),
+                    requestRejection: (req) => connection.requestRejection(req),
+                    log: consoleA2aLog(),
+                });
+            }
+            catch {
+                return () => { };
+            }
+        }, 'superd-hub: PTY executor upgrade route');
     });
 }
 export default apply;

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

@@ -18,6 +18,7 @@ export interface HubToolExecFace {
      */
     pty(sessionKey: string, machine: string, cmd: string, opts?: {
         timeoutSec?: number;
+        stdin?: string;
     }): Promise<import('./exec-pty-session.js').PtyDispatchResult>;
 }
 import type { A2aAddress, A2aInitiator, A2aService } from './a2a-service.js';
@@ -71,6 +72,8 @@ export interface HubRosterView {
 }
 /** Everything the factory needs, all injected (pure module — see header). */
 export interface HubToolDeps {
+    /** Explicit compatibility opt-in, never applied to receiving peer executors. */
+    localExec?: boolean;
     /** The A2A conversation service (T2 core behind T3's host assembly). */
     service: HubToolService;
     /** T3's delivery face: live-agent routing + the bounded unread buffer. */