super-dsh 0.3.1 → 0.3.2-e

package/remote/plugin.d.ts

@@ -90,22 +90,403 @@ interface SshConnection {
   readonly key?: string;
   readonly proxyJump?: string;
 }
-/** One instance per Agent-owned driver; destroyed with its Agent/plugin owners. */
-declare class SshTargets {
-  private readonly targets;
-  register(label: string, connection: SshConnection): SshConnection;
-  get(label: string): SshConnection | undefined;
-  entries(): ReadonlyArray<readonly [string, SshConnection]>;
-  clear(): void;
-}
 /** Shared by execution, probes and file/relay consumers. extraArgs is trusted
- * internal SSH argv (e.g. forwarding), never a model-provided shell string. */
+ * internal SSH argv (e.g. forwarding), never a model-provided shell string.
+ * Identity assembly lives in ssh-argv.ts (the ONE policy — 2026-10-17 ruling);
+ * this wrapper only picks the tty/batch dialect base. */
 declare function sshArgv(connection: SshConnection, options?: {
   tty?: boolean;
   extraArgs?: readonly string[];
   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;
+}
+/** 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/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;
+}
+/** 账本条目（§5）：commandId / 摘要 / exit / 耗时；保留最近 20 条（user 定案）。 */
+interface LedgerEntry {
+  commandId: string;
+  jobId?: string;
+  summary: string;
+  exit: number | null;
+  durationMs: number;
+  running: boolean;
+}
+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;
+  /** P4/P5：当前占用前台的 detached job（background/超时 handoff）。非 null 时新命令拒绝（Q6）。 */
+  private detachedJob;
+  /** §3.2（2026-10-25）：当前占用会话的命令——dispatch 同步占位，settle/cleanup 释放；input 的唯一写入对象。 */
+  private activeCommand;
+  /** 账本（§5）：本会话最近 20 条命令（FIFO，超出丢最旧）。 */
+  private ledger;
+  /** 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;
+  /** job 通道收养后回填 jobId（timeout handoff 时 registry id ≠ commandId，账本如实记录两者）；运行中的命令同步携带（input 回执用）。 */
+  attachJob(commandId: string, jobId: string): void;
+  /** Workbench 身份（§3）：id + 可选 label + connection + byo 标记。 */
+  get identity(): {
+    id: string;
+    label?: string;
+    connection: string;
+    byo: boolean;
+    builtOn: boolean;
+  };
+  /** 账本快照（session card 面，只读）。 */
+  ledgerSnapshot(): readonly LedgerEntry[];
+  /** 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;
@@ -117,7 +498,12 @@ interface TransferReceipt {
   action: 'copy';
   src: string;
   dst: string;
-  verified: boolean;
+  route: 'hub-staged';
+  /** S4: tier actually performed — sha256 digests ran and matched, or explicitly skipped. */
+  verification: 'sha256' | 'not-applicable';
+  /** S3 unified failure envelope. */
+  ok: boolean;
+  reason?: 'digest-mismatch' | 'staging-error' | 'aborted';
   sourceDigest?: string;
   destinationDigest?: string;
   bytes: number;
@@ -127,20 +513,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';
@@ -154,8 +526,16 @@ interface NativeCopyReceipt {
   stdout: string[];
   stderr: string[];
   outputTruncated: boolean;
-  /** Native CLI success only — no independent digest was computed for this path. */
-  verified: false;
+  /** S3/S4 (spec §3.3): verification names the tier actually performed — native routes are exit-code-only (D1=A). */
+  verification: 'native-exit-only';
+  /** S3 unified failure envelope: all native exits zero. */
+  ok: boolean;
+  /** Failure class when ok is false. */
+  reason?: 'non-zero-exit' | 'aborted';
+  /** Human context, e.g. two-segment 'push not started: pull failed' (prose moved out of route, S8). */
+  note?: string;
+  /** D3 mkdir pre-hop outcome: true = created this call, false = already existed, 'n-a' = skipped or unavailable (detail in note). */
+  created?: true | false | 'n-a';
   /** Tool-owned staging/config release: released on normal/observed exit, unknown when a channel was lost. */
   cleanup: 'released' | 'unknown' | 'none-required';
 }
@@ -203,6 +583,10 @@ interface RsyncReceipt extends RunResult {
   transferredBytes?: number;
   /** Two-SSH route actually used, when applicable. */
   route?: 'local-ssh' | 'ssh-ssh-forward' | 'ssh-ssh-stdio';
+  /** S3/S4: exit-code-only tier (D1=A) + unified failure envelope. */
+  verification: 'native-exit-only';
+  ok: boolean;
+  reason?: 'non-zero-exit' | 'aborted';
 }
 /**
  * Native rsync with ordered caller options. Local↔SSH runs rsync directly with
@@ -213,30 +597,6 @@ interface RsyncReceipt extends RunResult {
  */
 declare function runRsync(request: RsyncRequest, source: RsyncEndpoint, destination: RsyncEndpoint, signal: AbortSignal, options?: RelayRsyncOptions): Promise<RsyncReceipt>;
 //#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;
-}
-/** 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 {
   stdin?: string;
@@ -260,7 +620,6 @@ interface ProbeOptions {
 //#endregion
 //#region src/remote/roster.d.ts
 interface RosterOptions {
-  byosshLabels?: readonly string[];
   /** 测试缝：替代 runOneShot 的容器扫描执行器。 */
   runner?: (argv: string[], opts?: OneShotOptions) => Promise<OneShotResult>;
   /** 测试缝：替代 ~/.ssh/config 读取。 */
@@ -283,10 +642,25 @@ interface RemoteCallResult {
   truncated?: number;
   outputStats?: StreamOutputStats;
   outputStatsUnavailable?: boolean;
-  /** `byop:<label>` 调用面：本会话的 label（模型自选、即复用入口）。transport target 会话不带。 */
+  /** §5.2 回执字段序：session（+label）→ connection → commandId → state 字段（cwd/envDelta/ttlSec/exit）。 */
   session?: string;
-  /** 引导/教学行（同 label 重复给 spawn 时的「可省略 spawn」提示等）；无则省略。 */
+  label?: string;
+  connection?: string;
+  /** (byo-pty)/(byo-ssh) 来源标注（创建回执与 roster/card；native 回执省略）。 */
+  byoTag?: 'byo-pty' | 'byo-ssh';
+  commandId?: string;
+  envDelta?: EnvDelta;
+  /** 引导/教学行；无则省略。 */
   notice?: string;
+  /** oneshot 监督路径的如实标注：`superd-run <ver> (<triple>)` 或 `posix-shim`（spec remote-rescope §5）。 */
+  runner?: string;
+  /** P4/P5（2026-10-19）：true = pty 命令仍在前台运行（回执 = handoff），ptyJob 随行供 job 通道接管。 */
+  running?: boolean;
+  ptyJob?: PtyRunningJob;
+  /** 本会话 idle TTL 剩余（秒）；回执即状态快照（P2/P3：状态留在上下文里）。 */
+  ttlSec?: number;
+  /** 预热（创建形无 cmd）回执 = true。 */
+  created?: boolean;
 }
 interface RemoteAuditRecord {
   target: string;
@@ -303,39 +677,54 @@ interface RemoteDriverOptions {
   getHub?: () => HubRemoteTransport | undefined;
   execTimeoutSec?: number;
   idleTtlSec?: number;
-  maxOutputChars?: number;
   onAudit?: (r: RemoteAuditRecord) => void;
   oneshotArgvFor?: (plan: TargetPlan, cmd: string, options: {
     cleanupTag?: string;
   }) => string[];
   ptyArgvFor?: (plan: TargetPlan) => string[];
   spawnArgvFor?: (spawnCommand: string) => string[];
+  /** 测试/验收缝：hub PTY 泵 argv（默认 buildHubPtyArgv + 宿主树 ws 解析）。 */
+  hubPtyArgvFor?: (endpoint: HubPtyEndpoint) => string[];
   probeRunner?: ProbeOptions['runner'];
-  /** 测试缝：roster 扫描执行器（bare-name 解析复用）。 */
+  /** 测试/验收缝：helper 资产来源（默认 lib 旁挂 helper-bin）；显式 null 强制 shim 路径。 */
+  helperAssetsFor?: () => HelperAssets | null;
+  /** 测试缝：roster 扫描执行器（裸名解析复用）。 */
   rosterRunner?: RosterOptions['runner'];
-  /** 测试缝：ssh config 读取（bare-name 解析复用）。 */
+  /** 测试缝：ssh config 读取（裸名解析复用）。 */
   sshConfigReader?: () => Promise<string>;
 }
-/** 双轨调度器（spec §七 Phase 2）：参数校验 → 路由 → oneshot 子进程 / pty 会话池。 */
+/** 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 sshTargets;
   private readonly pool;
+  private readonly labels;
   private readonly hubOwner;
   private readonly hubProviders;
   private readonly processes;
   private readonly starting;
   private readonly fileAbort;
   private disposed;
+  /** undefined = 未尝试；null = 资产缺失（shim-only）；registry = 每 target sticky 状态机。 */
+  private helpers;
+  private readonly runnerOf;
   private disposal;
+  private readonly ptyIdleTtlSec;
   constructor(opts?: RemoteDriverOptions);
   call(params: RemoteCallParams, callCtx?: {
     sessionKey?: string;
+    ptyBackground?: boolean;
+    commandId?: string;
   }): Promise<RemoteCallResult>;
-  /** Native-first copy routing (spec: remote-native-shortcut): CLI peers run
-   * their native CLI verbatim; only Hub↔local↔local stays on the staged tree
-   * lane with verify/mkdir. Mixed pairs (Hub↔CLI peer) are refused: Hub has no
-   * native CLI and the tree lane has no CLI options. */
+  /** 参数互斥矩阵（§2）：spawn/ssh 是 BYO 入口（参数在场即 BYO），只与对应形态的 target 配对。 */
+  private validate;
+  private execute;
+  /** Native-first copy routing (spec: remote-native-shortcut) — unchanged by the workbench round. */
   copy(request: CopyRequest & {
     argv?: unknown;
     pullArgv?: unknown;
@@ -347,160 +736,96 @@ declare class RemoteDriver {
     sessionKey?: string;
   }): Promise<RsyncReceipt>;
   /** Only called from JobSpec.run: admission precedes local file reads and discovery. */
-  start(input: RemoteInput, signal: AbortSignal): Promise<RemoteProcess>;
+  start(input: RemoteInput, signal: AbortSignal, callCtx?: {
+    sessionKey?: string;
+  }): Promise<RemoteProcess>;
   private startPrepared;
   private nativeProcess;
+  /** Helper bootstrap is best-effort and sticky: any failure parks null for this driver
+   * lifetime and the shim stays the path. First call to a target pays probe (+ upload). */
+  private ensureHelper;
+  private helperExec;
   private own;
-  /** Ruling 16/17：on-demand 探测 + 会话层，两行如实陈述。 */
-  /**
-   * Ruling P20 + PTY 候选表末位：裸名按名匹配——ssh config 字面 host → docker → incus（本地廉价扫描，
-   * 撞名 ssh 优先），三段全不中再看池内活 PTY label，最后才是默认 ssh（交原生错误）。
-   * 位置即优先级：现有三段一位不挪。选择器前缀的 target 不经此路径。
-   */
-  private resolveBareName;
-  /** Ruling P19：roster = 注意力入口——本地廉价扫描（ssh config/docker ps/incus list + 池内活会话），零拨号。
-   *  活的 pty 会话按调用方 agent session 过滤（2026-10-03 裁决）：ssh/docker/incus 是**公共静态配置**，
-   *  而活会话是**操作环境**——复用别的 agent 留下的 shell 等于继承未知状态，且两个 agent 各开一条线
-   *  的代价可忽略。BYO-PTY 天然是活的，于是自然落进这个 scope，无需另立规则。 */
+  /** 现场采集机器面并 merge 进本 session 注册表（ssh → docker → incus → hub，迟到者加前缀）。错误逐段吞掉（roster 另行如实呈现）。 */
+  private refreshMachines;
+  /** 池寻址：命中即回；miss 现场采集一次再寻址（docker 容器名不经 roster 也可达）。 */
+  private resolvePoolEntry;
+  private planOf;
+  /** ssh:<name> 的池感知解析：BYO 身份 → 其 connection；否则按 config 别名/主机名。 */
+  private sshPlanFor;
+  /** BYO ssh 注册（v2：无 spec 对比——label 占用即拒；注册成功才认领）。返回实际名（label 或 s-id）。 */
+  private registerByoSsh;
+  /** PTY 会话创建（native/spawn 同一形状）：上限 → label 认领 → 惰性会话（失败由 onDead 释放 label）。 */
+  private createSession;
+  private ttlMinutes;
+  /** connection 由 BYO ssh 身份建立 → card 面标 `(built on)`（与 roster 同词，R2 复核 P2-10）。 */
+  private isBuiltOn;
+  /** PTY 创建形唯一实现（execute 与 background 预建共用）：spawn BYO / ssh BYO / native `<transport>:pty`。 */
+  private createPtyLane;
+  /** background PTY lane：会话先占位（不拨号）再进官方 jobs registry——首回执必须能寻址；
+   * registry 拒绝时把新建的会话拆掉（复用形的会话绝不拆）。返回 undefined = 走普通 oneshot job。 */
+  preparePtyLane(params: RemoteCallParams, callCtx?: {
+    sessionKey?: string;
+  }): Promise<{
+    input: RemoteInput;
+    session: string;
+    connection: string;
+    label?: string;
+    cleanup: () => void;
+  } | undefined>;
+  /** `pty:<id|label>` 寻址：先 id 后 label；miss 给重建形式。 */
+  private resolvePty;
+  /** §6 close：默认撞 detached job 报错（列杀法）；force = 杀组+关闭（披露 killed）。幂等 not-found。 */
+  closePty(selector: string, sessionKey: string, force?: boolean): {
+    session: string;
+    connection: string;
+    closed: boolean;
+    reason?: string;
+    killed: string[];
+    message?: string;
+  };
+  /** job 通道收养回填（timeout handoff 时 registry id ≠ commandId，账本记录两者）。 */
+  attachPtyJob(commandId: string, jobId: string, sessionKey: string): void;
+  /** §3.1（2026-10-25）interactive-stdin：input 动作——向已有 live PTY 的当前运行命令
+   * 追加 stdin。只解析池内已存在的会话（pty:<id|label> / 裸 label 命中 pty 项），
+   * 不触发发现、拨号、创建或重连；machine target 与创建形（:pty 后缀，含 hub:<m4>:pty）
+   * 一律明确拒绝并给出可恢复指引。回执附 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;
+  /** session card 回执（`pty:<id|label>` 无 cmd）：connection/state/cwd + 最近 20 条账本（不带输出尾，§9 Q7）。 */
+  private cardReceipt;
+  private oneshot;
+  private hubOneshot;
+  private hubOneshotProcess;
+  /** Ruling P19 + §2.5：roster = 注意力入口——本地扫描刷新统一池，零拨号；机器面公共，会话面 caller-scoped。 */
   roster(callCtx?: {
     sessionKey?: string;
   }): Promise<string>;
+  /** status probe（target 无 cmd）：机器面 = probe + 该 connection 上的会话；pty selector = session card。 */
   status(target: string, callCtx?: {
     sessionKey?: string;
   }): Promise<string>;
-  /** PTY 状态行：纯池内读取，零拨号（label 从来不是可拨目标）。 */
-  private ptyStatus;
-  /** Ruling 13：审计 best-effort——钩子抛错不得影响命令路径（成功被毒化成失败+双重审计）。 */
+  /** Ruling 13：审计 best-effort——钩子抛错不得影响命令路径。 */
   private audit;
-  /** Registration never dials; response reveals labels only, not credentials. */
-  registerSsh(target: string, connection: SshConnection): string;
-  private byosshPlan;
-  /** Single target resolver for later copy/rsync; BYO identities cannot be
-   * independently re-resolved through the origin's alias table. */
+  /** Single target resolver for later copy/rsync; PTY sessions are not filesystem connections. */
   resolveConnectionTarget(target: string, callCtx?: {
     sessionKey?: string;
   }): Promise<TargetPlan>;
-  private route;
-  private execute;
-  /** BYO-PTY 通道：label 即池键（agent 前缀之外），spawn 只在 label 尚不存在时被接受。
-   * 三分支 —— 建（无会话）/ 复用（无 spawn，或有 spawn 且与创建来源相同）/ **冲突（有 spawn 且来源不同：不执行任何命令）**。 */
-  private ptyCall;
+  /** P2/P3：回执即状态快照——idle TTL 剩余随每次 pty 回执带回。 */
+  private ptyTtl;
   hasHub(): boolean;
   private requireHub;
   private assertOpen;
   dispose(): Promise<void>;
 }
 //#endregion
-//#region src/remote/hub-contract.d.ts
-interface RemoteInput {
-  target?: string;
-  spawn?: string;
-  ssh?: SshConnection;
-  cmd?: string;
-  script?: 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 {
@@ -539,7 +864,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;
@@ -552,4 +876,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, SshTargets, 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 };