super-dsh 0.3.2 → 0.3.3-c

package/remote/plugin.d.ts

@@ -100,6 +100,390 @@ declare function sshArgv(connection: SshConnection, options?: {
   command?: string;
 }): string[];
 //#endregion
+//#region src/remote/hub-contract.d.ts
+/** Owned structural boundary. Better never imports or depends on Super. */
+interface RemoteInput {
+  target?: string;
+  spawn?: string;
+  ssh?: SshConnection;
+  cmd?: string;
+  scriptPath?: string;
+  stdin?: string;
+  mode?: 'oneshot' | 'pty';
+  timeout?: number;
+}
+interface PreparedRemoteInput {
+  target?: string;
+  spawn?: string;
+  ssh?: SshConnection;
+  cmd: string;
+  stdin?: string;
+  mode?: 'oneshot' | 'pty';
+  timeout?: number;
+}
+/** Counters exclude diagnostic banners. dropped is ring eviction; total-returned is all omitted output. */
+type OutputStats = {
+  unit: 'utf16' | 'bytes';
+  total: number;
+  retained: number;
+  dropped: number;
+  returned: number;
+  retentionLimit: number;
+};
+type StreamOutputStats = {
+  stdout: OutputStats;
+  stderr?: OutputStats;
+};
+interface RemoteProcess {
+  cancel(reason?: string): void;
+  done: Promise<{
+    exit: number | null;
+    timedOut: boolean;
+    durationMs: number;
+    cancelled?: boolean;
+  }>;
+  /** diagnostic is executor-generated text, not process output; excluded from byte cursor and counters. */
+  read(channel: 'stdout' | 'stderr', fromByte: number): {
+    text: string;
+    nextOffset: number;
+    lossy: boolean;
+    stats?: OutputStats;
+    diagnostic?: string;
+  };
+}
+interface BinaryFileEndpoint {
+  exportTree(path: string, signal: AbortSignal): Promise<NodeJS.ReadableStream>;
+  importTree(path: string, source: NodeJS.ReadableStream, options: {
+    mkdir: boolean;
+    signal: AbortSignal;
+  }): Promise<void>;
+  digest(path: string, signal: AbortSignal, selection?: readonly string[]): Promise<{
+    sha256: string;
+    bytes: number;
+    entries: number;
+  }>;
+}
+interface HubTarget {
+  id: string;
+  label: string;
+  execEnabled: boolean;
+}
+interface HubRemoteTransport {
+  protocol: 1;
+  listTargets(): readonly HubTarget[];
+  start(machine: string, input: PreparedRemoteInput, owner: string): Promise<RemoteProcess>;
+  /** Hub PTY 端点（0.3.2-c）：url = ws(s)://<origin>/api/superd/exec/pty；cookie = pairing 凭据；
+   *  wsPath = transport 侧（superd-hub 上下文，分叉的 proven 解析链）解析好的 ws 模块绝对路径。 */
+  ptyEndpoint(machine: string): {
+    url: string;
+    cookie: string;
+    wsPath: string;
+  };
+  fileEndpoint(machine: string): BinaryFileEndpoint;
+  releaseOwner(owner: string): Promise<void>;
+}
+//#endregion
+//#region src/remote/output-ring.d.ts
+/** Byte-addressed decoded output: mid-codepoint cursors skip forward and explicitly report loss. */
+declare function readUtf8Tail(bytes: Buffer, totalBytes: number, fromByte: number): {
+  text: string;
+  nextOffset: number;
+  lossy: boolean;
+};
+/** Native/PTY retention is UTF16 units; cursor offsets remain real UTF8 bytes. Input is decoded text. */
+declare class Utf16TailRing {
+  readonly capacity: number;
+  text: string;
+  total: number;
+  private totalBytes;
+  constructor(capacity?: number);
+  push(text: string): void;
+  stats(returned?: number): OutputStats;
+  read(fromByte: number): ReturnType<typeof readUtf8Tail>;
+}
+/** Raw byte retention for Hub oneshot. Tail/read starts skip partial UTF8 prefixes, never invent replacement characters. */
+declare class ByteTailRing {
+  readonly capacity: number;
+  total: number;
+  private chunks;
+  private retained;
+  constructor(capacity?: number);
+  push(chunk: Buffer): void;
+  tail(maxBytes?: number): Buffer;
+  stats(returned?: number): OutputStats;
+  read(fromByte: number): ReturnType<typeof readUtf8Tail>;
+}
+//#endregion
+//#region src/remote/process.d.ts
+declare const PROCESS_CLEANUP_BOUND_MS: number;
+interface ProcessOptions {
+  stdin?: string;
+  timeoutSec?: number;
+  cwd?: string;
+  /** Hub retains raw bytes; native transports retain decoded UTF16 units. */
+  unit?: 'bytes' | 'utf16';
+  onOutput?: () => void;
+  /** Overlay on process.env (tool-built values only, e.g. RSYNC_RSH). */
+  env?: NodeJS.ProcessEnv;
+  /** Task E（SSH MUX）：取消（timeout 或显式 cancel）即同步回调，不等 close。mux master 会经
+   *  fd-passing 持有被杀客户端的会话 fd 直到远端会话结束——若远端清理 killer 等 close 后才发射，
+   *  就成了「close 等远端结束、远端结束等 killer」死锁。此处先行启动 killer 才能解开 close。至多一次。 */
+  onCancel?: () => void;
+}
+/** Real detached process. Completion includes group cleanup, even after its leader closes. */
+declare function startBinaryProcess(argv: string[], options?: Pick<ProcessOptions, 'cwd' | 'timeoutSec' | 'env' | 'onCancel'>): {
+  stdout: Readable;
+  stderr: Readable;
+  stdin: Writable;
+  cancel(): void;
+  done: RemoteProcess['done'];
+  diagnostic(): string | undefined;
+};
+/** Text adapter over the same owned process-group lifecycle as binary pipelines. */
+declare function startOneShot(argv: string[], options?: ProcessOptions): RemoteProcess;
+//#endregion
+//#region src/remote/nonce-framing.d.ts
+/** 0.3.2-e：自有 30K 返回窗口已删（原生 agent runtime 的 spill/输出保护接管模型上下文
+ * 尺寸）。本 helper 只做 retention 披露：ring 留存（4M UTF-16 / 4MiB bytes）未驱逐时
+ * 全量透传（returned=retained，无 banner）；驱逐（dropped>0，仅 >4M 输出发生）时打一行
+ * banner 且 truncated=原始总量。text 已是 ring 尾部，不再二次裁剪。 */
+declare function disclose(text: string, stats?: OutputStats): {
+  text: string;
+  truncated?: number;
+  stats?: OutputStats;
+};
+interface EnvDelta {
+  added: string[];
+  changed: string[];
+  removed: string[];
+}
+//#endregion
+//#region src/remote/pty-session.d.ts
+interface PtySessionOptions {
+  key: string;
+  argv: string[];
+  /** Workbench 身份（§3）：自动 id（p-xxxx）+ 可选 label + connection 展示名（ssh:dev4 / docker:c / BYOP）。 */
+  id: string;
+  label?: string;
+  connection: string;
+  byo?: boolean;
+  /** connection 来自 BYO ssh 身份（card 面标 `(built on)`，与 roster 同词）。 */
+  builtOn?: boolean;
+  /** spawn 原文（BYO 会话存档；v2 无 spec 对比——不再参与复用判定，仅供回执/账本溯源）。 */
+  origin?: string;
+  idleTtlSec: number;
+  initTimeoutSec?: number;
+  /** 池回调：会话彻底出池（dispose）时触发；进程意外死亡不出池（Ruling 7）。 */
+  onDead?: () => void;
+}
+interface PtyDispatchOptions {
+  stdin?: string;
+  timeoutSec?: number; /** 账本键：driver 分配（background 通道预传入 registry jobId；同步命令同格式本地生成）——一个命令永远只有一个 id。 */
+  commandId: string; /** P5：立即回执 running job，不等帧（run_in_background 与超时 handoff 共用同一条 job 通道）。 */
+  background?: boolean; /** background 通道预传入的 registry jobId（此时与 commandId 字面相等）：账本与 input 回执如实携带，免 driver 侧二次回填。 */
+  jobId?: string;
+}
+/** §3.3（2026-10-25）interactive-stdin：input 动作的选项与回执（写入成功才回执）。 */
+interface PtyInputOptions {
+  stdin: string;
+  commandId?: string;
+}
+interface PtyInputReceipt {
+  /** 模型面会话名（pty:<id>）。 */
+  session: string;
+  commandId: string;
+  /** 存在官方 job 时才有（background 预传 / timeout handoff 收养回填）。 */
+  jobId?: string;
+  /** 实际写入的 UTF-8 字节数。 */
+  writtenBytes: number;
+}
+/** detached job 的完成结果（frame 或会话死亡时结算；与 dispatch 回执同构）。 */
+interface PtyJobResult {
+  output: string;
+  outputStats?: StreamOutputStats;
+  exit: number | null;
+  cwd: string | null;
+  timedOut: boolean;
+  commandId: string;
+  envDelta?: EnvDelta;
+}
+/** P4/P5（2026-10-19）running job 句柄：byte-cursor 增量读 + P8 显式中断 + 完成时帧结算。 */
+interface PtyRunningJob {
+  /** 账本键：与 jobId 同构（background 通道预传入 registry id；同步完成命令用同格式生成 id）。 */
+  commandId: string;
+  /** Byte-cursor incremental read over the command's merged output (tail-ring retention; lossy reports eviction). */
+  read: (fromByte: number) => {
+    text: string;
+    nextOffset: number;
+    lossy: boolean;
+  };
+  stats: () => OutputStats;
+  /** P8 两段式 ^C 中断（会话存活；trap-INT 走宽限 group-kill 兜底）。 */
+  interrupt: () => void;
+  /** Settles on the exit frame, or with exit null when the session dies. */
+  done: Promise<PtyJobResult>;
+}
+interface PtyDispatchResult {
+  output: string;
+  outputStats?: StreamOutputStats;
+  exit: number | null;
+  cwd: string | null;
+  timedOut: boolean;
+  reconnected: boolean;
+  durationMs: number;
+  commandId: string;
+  /** env delta（E 帧侧信道）：只回名字 + 变动标记，值不回传；init 侧信道失败时省略。 */
+  envDelta?: EnvDelta;
+  /** P4/P5：true = 命令仍在前台运行，本回执是 handoff（job 句柄随行）。 */
+  running?: boolean;
+  job?: PtyRunningJob;
+}
+type PtyState = 'cold' | 'starting' | 'ready' | 'dead' | 'disposed';
+/** 会话运行时快照（status 面消费，Ruling 16 词汇源）。 */
+interface SessionSnapshot {
+  state: PtyState;
+  busy: boolean;
+  idleMs: number | null;
+  pid: number | null;
+}
+declare class PtySession {
+  private readonly opts;
+  private proc;
+  private state;
+  private startPromise;
+  private idleTimer;
+  private onChunk;
+  private deathWaiters;
+  private diag;
+  private inFlight;
+  private cmdSeq;
+  /** P4/P5：当前占用前台的 detached job（background/超时 handoff）。非 null 时新命令拒绝（Q6）。 */
+  private detachedJob;
+  /** §3.2（2026-10-25）：当前占用会话的命令——dispatch 同步占位，settle/cleanup 释放；input 的唯一写入对象。 */
+  private activeCommand;
+  /** env 侧信道基线（init E 帧）；undefined = 侧信道不可用（不报假 delta）。 */
+  private envBaseline;
+  /** idle 起点（ready / settle 时重置）；null = 尚无 idle 时钟（cold 或已 dispose）。 */
+  private idleSince;
+  /** 意外死亡后的回收定时器（R2）：ready 过的会话先留池供 reconnect，超时仍无人寻址则出池。 */
+  private deathTimer;
+  private lastCwdSeen;
+  /** 是否曾成功初始化（ready 过）。决定死亡语义：ready 过 → reconnect（留池）；从未 ready → 出池（见 start()）。 */
+  private everReady;
+  private disposal;
+  private procClose;
+  private groupCleanup;
+  constructor(opts: PtySessionOptions);
+  get sessionState(): PtyState;
+  /** 池键（driver 的 ttl/inspect 用）。 */
+  get key(): string;
+  /** 最近帧 cwd（card 面）；从未执行过 = null。 */
+  get lastCwd(): string | null;
+  /** 占用前台的 detached job 的 commandId（无 = null；close 拒绝与 busy 文案共用）。 */
+  get detachedCommandId(): string | null;
+  /** handoff/card 面（2026-11-01 默认 PTY 轮）：当前占用会话的命令与可选 job 句柄；无 = null。 */
+  get active(): {
+    commandId: string;
+    jobId?: string;
+  } | null;
+  /** job 通道收养后回填 jobId（timeout handoff 时 registry id ≠ commandId）；运行中的命令同步携带（stdin-only 写入回执用）。 */
+  attachJob(commandId: string, jobId: string): void;
+  /** Workbench 身份（§3）：id + 可选 label + connection + byo 标记。 */
+  get identity(): {
+    id: string;
+    label?: string;
+    connection: string;
+    byo: boolean;
+    builtOn: boolean;
+  };
+  /** spawn 创建原文（仅 BYO 会话；v2 起仅存档，不参与复用判定）。 */
+  get origin(): string | undefined;
+  /** status 面快照：state + busy（有命令在跑）+ idleMs（上次 settle 至今）+ pid（进程组头，kill 兜底可观测）。 */
+  get snapshot(): SessionSnapshot;
+  /** 预热创建（创建形无 cmd）：真正拨号到 init 帧——「会话已就绪」必须是真的，
+   * 而且只有 ready 过才挂 idle 回收（cold 会话没有 timer，会永远占配额）。 */
+  warm(): Promise<void>;
+  /** 同一会话命令占位制（2026-10-25 interactive-stdin 轮）：dispatch 入口**同步**建立
+   * 命令占位（activeCommand + inFlight + 账本条目）——上一条命令仍在运行（同步等待 /
+   * 等输入 / detached job）时新 cmd 立即 E_SESSION_BUSY；原「纯同步并发排 FIFO」语义
+   * 废除（排队会让等输入的命令与补输入动作互相卡死，也给 busy 留下绕行窗口）。
+   * P4/P5：超时不杀命令而是 handoff 成 running job；background 立即回执；P8 显式
+   * interrupt 保留在 job.interrupt；死亡/冷态先重启（reconnect 语义不变）。 */
+  dispatch(cmd: string, dOpts: PtyDispatchOptions): Promise<PtyDispatchResult>;
+  /** §3.1（2026-10-25）interactive-stdin：向当前运行中的命令追加 stdin——只写既有通道
+   * 与身份，不新建命令、账本条目或输出游标；不重连、不重放（dead/disposed 明确拒绝）。
+   * 校验与写入全同步：多次 input 按调用顺序整段写入不交错；写入失败如实抛错（私有
+   * write() 的静默忽略不适用于回执语义）。stdin:"" 是零字节写入，不是 EOF。 */
+  input(options: PtyInputOptions): Promise<PtyInputReceipt>;
+  /** TTL / row teardown：尽力 exit，1s 后杀组，出池。 */
+  dispose(): Promise<void>;
+  private write;
+  private start;
+  private doStart;
+  private markDead;
+  private resetIdleTimer;
+  private clearIdleTimer;
+  /** 意外死亡后的回收：留池只换取一次 reconnect 机会，不得超过一段 idle TTL（R2 复核 P0）。
+   * 否则死会话永久占 label + 永久计入 10 配额，Agent 再也开不出新会话。 */
+  private armDeathReaper;
+  private clearDeathTimer;
+  private killTree;
+  /** A direct child's close is not proof that its detached process group is gone. */
+  private reapGroup;
+}
+//#endregion
+//#region src/remote/target.d.ts
+/** 解析后的传输计划：三种 CLI 传输之一。 */
+type TargetPlan = {
+  kind: 'ssh';
+  host: string;
+  connection?: SshConnection;
+} | {
+  kind: 'docker';
+  container: string;
+} | {
+  kind: 'incus';
+  container: string;
+};
+//#endregion
+//#region src/remote/helper.d.ts
+interface HelperManifest {
+  format: 1;
+  name: string;
+  ver: string;
+  protocol: number;
+  targets: Record<string, {
+    file: string;
+    bytes: number;
+    sha256: string;
+  }>;
+}
+interface HelperAssets {
+  dir: string;
+  manifest: HelperManifest;
+}
+//#endregion
+//#region src/remote/transports.d.ts
+/** Hub PTY 端点事实（ptyEndpoint 的返回形；结构类型，不引 superd-hub）。wsPath 由 transport
+ *  侧解析成绝对路径（superd-hub 上下文 = 分叉验证过的解析链；闭包/泵内绝不做按名解析赌注）。 */
+interface HubPtyEndpoint {
+  url: string;
+  cookie: string;
+  wsPath: string;
+}
+/** Hub PTY（0.3.2-c；0.3.2-d F4 修正）：会话子进程 = 本地 `script` PTY 托管的 WS 字节泵
+ *  （hub-pty-pump.mjs）。与 docker exec 的嵌套 PTY 同形，但泵是哑 node 子进程、不像
+ *  `ssh -tt` / `docker exec -it` 那样作为前台子进程自己把本地 tty 置 raw——所以本地包装必须
+ *  `stty raw`：canonical+ISIG 下 0x03 在本地变 SIGINT 杀泵、0x04 变 EOF 结束泵 stdin
+ *  （F4：input ^C/^D 与 job_kill 会打死整条会话）。raw 只作用于本地半段；对端 script PTY
+ *  保持 canonical，^C/^D 在对端产生 SIGINT/EOF 正是我们要的语义（字节原样过线，解释权在
+ *  对端）。kill 链 session 组杀 → 泵死 → WS 关 → 对端组杀，双向自然闭合。连接事实走 wrapper
+ *  内 env 赋值（cookie 不进 argv、不落 ps）。 */
+declare function buildHubPtyArgv(endpoint: HubPtyEndpoint, assets: {
+  pumpPath: string;
+  nodePath?: string;
+}): string[];
+//#endregion
 //#region src/remote/copy.d.ts
 interface CopyRequest {
   src: string;
@@ -126,20 +510,6 @@ interface TransferReceipt {
   error?: string;
 }
 //#endregion
-//#region src/remote/target.d.ts
-/** 解析后的传输计划：三种 CLI 传输之一。 */
-type TargetPlan = {
-  kind: 'ssh';
-  host: string;
-  connection?: SshConnection;
-} | {
-  kind: 'docker';
-  container: string;
-} | {
-  kind: 'incus';
-  container: string;
-};
-//#endregion
 //#region src/remote/native-copy.d.ts
 interface NativeCopyReceipt {
   action: 'copy';
@@ -224,81 +594,40 @@ interface RsyncReceipt extends RunResult {
  */
 declare function runRsync(request: RsyncRequest, source: RsyncEndpoint, destination: RsyncEndpoint, signal: AbortSignal, options?: RelayRsyncOptions): Promise<RsyncReceipt>;
 //#endregion
-//#region src/remote/helper.d.ts
-interface HelperManifest {
-  format: 1;
-  name: string;
-  ver: string;
-  protocol: number;
-  targets: Record<string, {
-    file: string;
-    bytes: number;
-    sha256: string;
+//#region src/remote/ssh-mux.d.ts
+interface SshMuxIdentity {
+  /** 原始 target 串（如 `ssh:dev4` / `dev4`）——同一 effective 身份不同拼法也不串 socket。 */
+  target: string;
+  connection: SshConnection;
+}
+interface SshMuxOptions {
+  persistSec?: number;
+  /** socket 目录根（默认 os.tmpdir()）；测试注入口。 */
+  rootDir?: string;
+  runner?: (argv: string[], opts?: {
+    timeoutSec?: number;
+  }) => Promise<{
+    exit: number | null;
   }>;
 }
-interface HelperAssets {
-  dir: string;
-  manifest: HelperManifest;
-}
-//#endregion
-//#region src/remote/nonce-framing.d.ts
-interface EnvDelta {
-  added: string[];
-  changed: string[];
-  removed: string[];
-}
-//#endregion
-//#region src/remote/pty-session.d.ts
-/** detached job 的完成结果（frame 或会话死亡时结算；与 dispatch 回执同构）。 */
-interface PtyJobResult {
-  output: string;
-  outputStats?: StreamOutputStats;
-  exit: number | null;
-  cwd: string | null;
-  timedOut: boolean;
-  commandId: string;
-  envDelta?: EnvDelta;
-}
-/** P4/P5（2026-10-19）running job 句柄：byte-cursor 增量读 + P8 显式中断 + 完成时帧结算。 */
-interface PtyRunningJob {
-  /** 账本键：与 jobId 同构（background 通道预传入 registry id；同步完成命令用同格式生成 id）。 */
-  commandId: string;
-  /** Byte-cursor incremental read over the command's merged output (tail-ring retention; lossy reports eviction). */
-  read: (fromByte: number) => {
-    text: string;
-    nextOffset: number;
-    lossy: boolean;
-  };
-  stats: () => OutputStats;
-  /** P8 两段式 ^C 中断（会话存活；trap-INT 走宽限 group-kill 兜底）。 */
-  interrupt: () => void;
-  /** Settles on the exit frame, or with exit null when the session dies. */
-  done: Promise<PtyJobResult>;
-}
-//#endregion
-//#region src/remote/process.d.ts
-declare const PROCESS_CLEANUP_BOUND_MS: number;
-interface ProcessOptions {
-  stdin?: string;
-  timeoutSec?: number;
-  cwd?: string;
-  /** Hub retains raw bytes; native transports retain decoded UTF16 units. */
-  unit?: 'bytes' | 'utf16';
-  onOutput?: () => void;
-  /** Overlay on process.env (tool-built values only, e.g. RSYNC_RSH). */
-  env?: NodeJS.ProcessEnv;
+/** 每 Agent 一个（driver 私有）：tool-owned 0700 socket 目录 + 按连接身份的 socket 名。
+ *  目录名含随机 owner 后缀，跨 Agent 天然不共享；dispose 逐 socket `-O exit` 后整目录删除。 */
+declare class SshMux {
+  private readonly persistSec;
+  private readonly rootDir;
+  private readonly runner;
+  private readonly owner;
+  private readonly sockets;
+  private dir;
+  private disposal;
+  constructor(options?: SshMuxOptions);
+  /** 注入 SSH argv 的 MUX 选项（trusted internal argv，非模型输入）。目录懒建（纯 docker/hub
+   *  Agent 永不触盘）；超限/已 dispose 返回 [] = 诚实退化为普通连接。 */
+  argvFor(identity: SshMuxIdentity): string[];
+  /** Teardown：先 `-O exit` 逐 socket 礼貌拆除 master（不拨号、5s 上限、错误全吞——
+   *  master 已死/残 socket 属正常），再删目录。单飞（重复调用同一 Promise）。 */
+  dispose(): Promise<void>;
 }
-/** Real detached process. Completion includes group cleanup, even after its leader closes. */
-declare function startBinaryProcess(argv: string[], options?: Pick<ProcessOptions, 'cwd' | 'timeoutSec' | 'env'>): {
-  stdout: Readable;
-  stderr: Readable;
-  stdin: Writable;
-  cancel(): void;
-  done: RemoteProcess['done'];
-  diagnostic(): string | undefined;
-};
-/** Text adapter over the same owned process-group lifecycle as binary pipelines. */
-declare function startOneShot(argv: string[], options?: ProcessOptions): RemoteProcess;
 //#endregion
 //#region src/remote/oneshot.d.ts
 interface OneShotOptions {
@@ -319,6 +648,8 @@ interface ProbeOptions {
   connectTimeoutSec?: number;
   hardTimeoutSec?: number;
   runner?: (argv: string[], opts?: OneShotOptions) => Promise<OneShotResult>;
+  /** Task E：SSH 探测与 oneshot 执行链共用 MUX（同一身份 → 同一 master，探测零额外握手）。 */
+  muxArgvFor?: (plan: TargetPlan) => readonly string[];
 }
 //#endregion
 //#region src/remote/roster.d.ts
@@ -380,25 +711,39 @@ interface RemoteDriverOptions {
   getHub?: () => HubRemoteTransport | undefined;
   execTimeoutSec?: number;
   idleTtlSec?: number;
-  maxOutputChars?: number;
   onAudit?: (r: RemoteAuditRecord) => void;
   oneshotArgvFor?: (plan: TargetPlan, cmd: string, options: {
     cleanupTag?: string;
+    muxArgv?: readonly string[];
   }) => string[];
   ptyArgvFor?: (plan: TargetPlan) => string[];
   spawnArgvFor?: (spawnCommand: string) => string[];
+  /** 测试/验收缝：hub PTY 泵 argv（默认 buildHubPtyArgv + 宿主树 ws 解析）。 */
+  hubPtyArgvFor?: (endpoint: HubPtyEndpoint) => string[];
   probeRunner?: ProbeOptions['runner'];
   /** 测试/验收缝：helper 资产来源（默认 lib 旁挂 helper-bin）；显式 null 强制 shim 路径。 */
   helperAssetsFor?: () => HelperAssets | null;
+  /** 测试/验收缝：SSH oneshot MUX 状态（默认每 driver 一个 SshMux = 每 Agent 隔离）。 */
+  sshMux?: SshMux;
   /** 测试缝：roster 扫描执行器（裸名解析复用）。 */
   rosterRunner?: RosterOptions['runner'];
   /** 测试缝：ssh config 读取（裸名解析复用）。 */
   sshConfigReader?: () => Promise<string>;
 }
+/** hub PTY 泵资产：pump 与本模块同目录（npm 包与 Super 闭包同构，helper.ts 同款纪律）。
+ *  ws 模块路径由 transport 侧（superd-hub 上下文，分叉的 proven 解析链）解析后经
+ *  ptyEndpoint 传入——闭包自身子树无可解析的 ws，按名解析不在闭包里做（0.3.2-c 定稿）。 */
+declare function hubPtyAssets(): {
+  pumpPath: string;
+};
 /** 双轨调度器：参数校验 → 目标语法（parseTargetForm）→ 统一 label 池 → oneshot 子进程 / pty 会话池。 */
 declare class RemoteDriver {
   private readonly opts;
   private readonly pool;
+  /** 默认 PTY 槽（spec remote-default-pty §1）：sessionKey → 归一 machineKey → pool key。
+   * 会话本体是普通 PtySession（id 创建即认领，roster 全可见）；槽登记在 dispose/TTL 后悬空，
+   * 取槽时经 pool.get（disposed 视同出池）惰性清理。 */
+  private readonly defaultSlots;
   private readonly labels;
   private readonly hubOwner;
   private readonly hubProviders;
@@ -411,6 +756,7 @@ declare class RemoteDriver {
   private readonly runnerOf;
   private disposal;
   private readonly ptyIdleTtlSec;
+  private readonly mux;
   constructor(opts?: RemoteDriverOptions);
   call(params: RemoteCallParams, callCtx?: {
     sessionKey?: string;
@@ -449,6 +795,10 @@ declare class RemoteDriver {
   private planOf;
   /** ssh:<name> 的池感知解析：BYO 身份 → 其 connection；否则按 config 别名/主机名。 */
   private sshPlanFor;
+  /** Task E MUX 身份：仅 SSH plan 注入（docker/incus/hub 返回 undefined）。身份键 = 原始
+   * target 串 + 有效连接字段（host/user/port/key/ProxyJump）——同身份共享 master，跨身份
+   * 不串 socket；目录/寿命/拆除全部由 SshMux 自持。 */
+  private muxArgvFor;
   /** BYO ssh 注册（v2：无 spec 对比——label 占用即拒；注册成功才认领）。返回实际名（label 或 s-id）。 */
   private registerByoSsh;
   /** PTY 会话创建（native/spawn 同一形状）：上限 → label 认领 → 惰性会话（失败由 onDead 释放 label）。 */
@@ -456,8 +806,36 @@ declare class RemoteDriver {
   private ttlMinutes;
   /** connection 由 BYO ssh 身份建立 → card 面标 `(built on)`（与 roster 同词，R2 复核 P2-10）。 */
   private isBuiltOn;
-  /** PTY 创建形唯一实现（execute 与 background 预建共用）：spawn BYO / ssh BYO / native `<transport>:pty`。 */
+  /** PTY 创建形唯一实现（execute 与 background 预建共用）：spawn BYO（spec 2026-11-01：native `:pty`/hub-pty 创建语法已删，machine 会话经默认槽 + handoff）。 */
   private createPtyLane;
+  /** 池条目的槽键归一：同一实体（host/container/machine 身份）跨裸名/前缀/撞名前缀共享同一默认槽。 */
+  private machineKeyOfEntry;
+  /** 默认槽的 machine 规格：归一 key + 创建 argv + 展示 connection（hub 每次经 ptyEndpoint 重验 pairing，P10）。 */
+  private machineSlotSpec;
+  /** 取/懒建 machine 的默认 PTY 槽：dead/disposed 槽惰性重建；id 创建即认领（roster 全可见 + 防撞）。 */
+  private defaultSlot;
+  private releaseDefaultSlot;
+  /** 按池键反查并解绑默认槽（background 提交即 handoff 用）；非槽会话无操作。 */
+  private releaseSlotByPoolKey;
+  /** roster/status 面：本 session 的默认槽标注（session id → machineKey；悬空条目过滤）。 */
+  private defaultMarks;
+  /** spec §1 handoff（2026-11-01 二/三轮裁决）：把 machine 默认 PTY 解绑成可寻址 pty:<id>——同引用移动
+   * （不重启、不复制输出流）；fresh（尚无默认槽）= 后台创建空闲 shell 再隔离（默认 PTY 思维模型恒
+   * ready，创建时机是实现细节）；busy = 附当前命令与 job 句柄。machine 下次 exec 按需新建默认 PTY。 */
+  handoff(target: string, callCtx?: {
+    sessionKey?: string;
+  }): Promise<RemoteCallResult>;
+  /** close 统一入口（spec §1 + 三轮补充裁决）：machine target 只关默认槽；pty selector 关该会话；
+   * 不存在 job 定位——取消运行中命令的唯一入口是官方 job_kill。 */
+  close(target: string, sessionKey: string, force?: boolean): Promise<{
+    session: string;
+    connection: string;
+    closed: boolean;
+    reason?: string;
+    killed: string[];
+    message?: string;
+  }>;
+  private closeDefault;
   /** background PTY lane：会话先占位（不拨号）再进官方 jobs registry——首回执必须能寻址；
    * registry 拒绝时把新建的会话拆掉（复用形的会话绝不拆）。返回 undefined = 走普通 oneshot job。 */
   preparePtyLane(params: RemoteCallParams, callCtx?: {
@@ -482,6 +860,15 @@ declare class RemoteDriver {
   };
   /** job 通道收养回填（timeout handoff 时 registry id ≠ commandId，账本记录两者）。 */
   attachPtyJob(commandId: string, jobId: string, sessionKey: string): void;
+  /** spec remote-default-pty §1（2026-11-01）：exec stdin-only 写入核心——向已有 live PTY 的当前运行命令
+   * 追加 exact-byte stdin。寻址：pty:<id|label> / 裸 label 命中 pty 项 / machine target（其默认槽的
+   * 当前命令，无槽不懒建、如实报错）。不触发拨号、创建或重连；回执附 connection/label 供工具层渲染。 */
+  input(target: string, options: PtyInputOptions, callCtx?: {
+    sessionKey?: string;
+  }): Promise<PtyInputReceipt & {
+    connection: string;
+    label?: string;
+  }>;
   private dispatchPty;
   /** 预热（创建形无 cmd）回执：§3——无 commandId/envDelta；timeout 忽略。 */
   private warmReceipt;
@@ -512,116 +899,6 @@ declare class RemoteDriver {
   dispose(): Promise<void>;
 }
 //#endregion
-//#region src/remote/hub-contract.d.ts
-interface RemoteInput {
-  target?: string;
-  spawn?: string;
-  ssh?: SshConnection;
-  cmd?: string;
-  scriptPath?: string;
-  stdin?: string;
-  mode?: 'oneshot' | 'pty';
-  timeout?: number;
-}
-interface PreparedRemoteInput {
-  target?: string;
-  spawn?: string;
-  ssh?: SshConnection;
-  cmd: string;
-  stdin?: string;
-  mode?: 'oneshot' | 'pty';
-  timeout?: number;
-}
-/** Counters exclude diagnostic banners. dropped is ring eviction; total-returned is all omitted output. */
-type OutputStats = {
-  unit: 'utf16' | 'bytes';
-  total: number;
-  retained: number;
-  dropped: number;
-  returned: number;
-  retentionLimit: number;
-};
-type StreamOutputStats = {
-  stdout: OutputStats;
-  stderr?: OutputStats;
-};
-interface RemoteProcess {
-  cancel(reason?: string): void;
-  done: Promise<{
-    exit: number | null;
-    timedOut: boolean;
-    durationMs: number;
-    cancelled?: boolean;
-  }>;
-  /** diagnostic is executor-generated text, not process output; excluded from byte cursor and counters. */
-  read(channel: 'stdout' | 'stderr', fromByte: number): {
-    text: string;
-    nextOffset: number;
-    lossy: boolean;
-    stats?: OutputStats;
-    diagnostic?: string;
-  };
-}
-interface BinaryFileEndpoint {
-  exportTree(path: string, signal: AbortSignal): Promise<NodeJS.ReadableStream>;
-  importTree(path: string, source: NodeJS.ReadableStream, options: {
-    mkdir: boolean;
-    signal: AbortSignal;
-  }): Promise<void>;
-  digest(path: string, signal: AbortSignal, selection?: readonly string[]): Promise<{
-    sha256: string;
-    bytes: number;
-    entries: number;
-  }>;
-}
-interface HubTarget {
-  id: string;
-  label: string;
-  execEnabled: boolean;
-}
-interface HubRemoteTransport {
-  protocol: 1;
-  listTargets(): readonly HubTarget[];
-  start(machine: string, input: PreparedRemoteInput, owner: string): Promise<RemoteProcess>;
-  pty(machine: string, cmd: string, owner: string, options: {
-    stdin?: string;
-    timeout?: number;
-  }): Promise<RemoteCallResult>;
-  fileEndpoint(machine: string): BinaryFileEndpoint;
-  releaseOwner(owner: string): Promise<void>;
-}
-//#endregion
-//#region src/remote/output-ring.d.ts
-/** Byte-addressed decoded output: mid-codepoint cursors skip forward and explicitly report loss. */
-declare function readUtf8Tail(bytes: Buffer, totalBytes: number, fromByte: number): {
-  text: string;
-  nextOffset: number;
-  lossy: boolean;
-};
-/** Native/PTY retention is UTF16 units; cursor offsets remain real UTF8 bytes. Input is decoded text. */
-declare class Utf16TailRing {
-  readonly capacity: number;
-  text: string;
-  total: number;
-  private totalBytes;
-  constructor(capacity?: number);
-  push(text: string): void;
-  stats(returned?: number): OutputStats;
-  read(fromByte: number): ReturnType<typeof readUtf8Tail>;
-}
-/** Raw byte retention for Hub oneshot. Tail/read starts skip partial UTF8 prefixes, never invent replacement characters. */
-declare class ByteTailRing {
-  readonly capacity: number;
-  total: number;
-  private chunks;
-  private retained;
-  constructor(capacity?: number);
-  push(chunk: Buffer): void;
-  tail(maxBytes?: number): Buffer;
-  stats(returned?: number): OutputStats;
-  read(fromByte: number): ReturnType<typeof readUtf8Tail>;
-}
-//#endregion
 //#region src/remote/jobs.d.ts
 declare module '@deepseek-ai/dsh-jobs' {
   interface JobKindMap {
@@ -660,7 +937,6 @@ declare const inject: string[];
 interface RemoteRowConfig {
   execTimeoutSec: number;
   idleTtlSec: number;
-  maxOutputChars: number;
 }
 type RemoteConfigValidator = ((value?: unknown) => RemoteRowConfig) & StandardSchemaV1<unknown, RemoteRowConfig> & NativeConfigSchema;
 declare const Config: RemoteConfigValidator;
@@ -673,4 +949,4 @@ declare const _default: {
   apply: (ctx: Context, config: RemoteRowConfig) => (() => void);
 };
 //#endregion
-export { type BinaryFileEndpoint, ByteTailRing, Config, FILE_FRAME_BYTES, FILE_MAX_ENTRIES, FILE_MAX_METADATA, type HubRemoteTransport, type HubTarget, type OutputStats, PROCESS_CLEANUP_BOUND_MS, type PreparedRemoteInput, RemoteConfigValidator, type RemoteInput, type RemoteProcess, RemoteRowConfig, type RsyncEndpoint, type RsyncReceipt, type RsyncRequest, type SshConnection, type StreamOutputStats, Utf16TailRing, apply, checkAbsolute, checkSelection, _default as default, inject, localFileEndpoint, name, readUtf8Tail, runFileWorker, runRsync, sshArgv, startBinaryProcess, startOneShot, startRemoteJob };
+export { type BinaryFileEndpoint, ByteTailRing, Config, FILE_FRAME_BYTES, FILE_MAX_ENTRIES, FILE_MAX_METADATA, type HubPtyEndpoint, type HubRemoteTransport, type HubTarget, type OutputStats, PROCESS_CLEANUP_BOUND_MS, type PreparedRemoteInput, type PtyDispatchResult, PtySession, RemoteConfigValidator, type RemoteInput, type RemoteProcess, RemoteRowConfig, type RsyncEndpoint, type RsyncReceipt, type RsyncRequest, type SshConnection, type StreamOutputStats, Utf16TailRing, apply, buildHubPtyArgv, checkAbsolute, checkSelection, _default as default, disclose, hubPtyAssets, inject, localFileEndpoint, name, readUtf8Tail, runFileWorker, runRsync, sshArgv, startBinaryProcess, startOneShot, startRemoteJob };