better-dsh 0.3.2-e → 0.3.3-b

package/docs/remote-tools.md

@@ -13,10 +13,10 @@ Better Dash and Super Dash each provide the native `remote` tool and REPL route.
 | Register an Agent-local SSH identity (no dialing) | `remote {action:"add",target:"ssh:build",ssh:{host:"host",user:"user",key:"/origin/key"}}`; omit `target` for an auto id (`ssh-xxxx`) |
 | Register a BYO PTY from a spawn command | `remote {action:"add",spawn:"docker exec -it img bash",target:"pty:build"}`; then address it like any session |
 | Stateless command and stdin over an identity | `remote {action:"exec",target:"ssh:build",cmd:"cat",stdin:"hello"}` |
-| Stream a local script to fixed `bash -s` | `remote {action:"exec",target:"ssh:alias",scriptPath:"/absolute/script.sh"}` |
-| Create a persistent shell (tab semantics) | `remote {action:"exec",target:"ssh:alias:pty",cmd:"cd /tmp; export CHECK=ready"}`; append `:label` (`ssh:alias:pty:build`) to name it |
+| Run a local script as one `bash -c` command (stdin = the script's own input) | `remote {action:"exec",target:"ssh:alias",scriptPath:"/absolute/script.sh",stdin:"payload\n"}` |
+| Use a machine's persistent shell (default PTY) | `remote {action:"exec",target:"ssh:alias",cmd:"cd /tmp; export CHECK=ready"}` — consecutive execs reuse one shell (cwd/env persist) |
 | Reuse a persistent shell | `remote {action:"exec",target:"pty:<id\|label>",cmd:"…"}` |
-| Answer a prompt / feed a running command (password, OTP, token, choice, REPL line, `\u0003`/`\u0004`) | `remote {action:"input",target:"pty:<id\|label>",stdin:"the-answer\n"}` — optional `commandId` guards against stale prompts |
+| Answer a prompt / feed a running command (password, OTP, token, choice, REPL line, `\u0003`/`\u0004`) | `remote {action:"exec",target:"pty:<id\|label>",stdin:"the-answer\n"}` (stdin-only raw write) — optional `commandId` guards against stale prompts |
 | Close a PTY session | `remote {action:"close",target:"pty:<id\|label>",force:true}` |
 | Native CLI copy | `remote_transfer {mode:"copy",src:"/absolute/source",dst:"ssh:alias:/absolute/destination",argv:["-p"]}` |
 | Native rsync | `remote_transfer {mode:"rsync",src:"/absolute/source/",dst:"ssh:alias:/existing/destination/",argv:["-a","--partial","--dry-run"]}` |
@@ -29,16 +29,16 @@ Interactive flow — see a prompt, answer it, read the response:
 
 1. Start the program: `exec` with `cmd` (foreground, `run_in_background`, or after a timeout handoff — identity is preserved either way). The running receipt carries the output so far plus `session` / `commandId` / `jobId`.
 2. Watch for the prompt in that output; use `job_output <jobId>` when you need more.
-3. Send the answer: `{action:"input", target:"pty:<id|label>", stdin:"the-answer\n"}`. `stdin` passes through verbatim — include the trailing `\n` to submit a line; `\u0003` is Ctrl-C and `\u0004` is Ctrl-D as raw characters; a literal backslash-x-0-4 stays four characters; `""` writes zero bytes (not EOF). The optional `commandId` must equal the running command's id; a stale id refuses the write instead of feeding the next command.
+3. Send the answer: `{action:"exec", target:"pty:<id|label>", stdin:"the-answer\n"}` (stdin alone = raw write; the `input` action is gone). `stdin` passes through verbatim — include the trailing `\n` to submit a line; `\u0003` is Ctrl-C and `\u0004` is Ctrl-D as raw characters; a literal backslash-x-0-4 stays four characters; `""` writes zero bytes (not EOF). The optional `commandId` must equal the running command's id; a stale id refuses the write instead of feeding the next command.
 4. Read the response with `job_output` on the SAME job. The input receipt only confirms N bytes were written — it never means the password was accepted or the login succeeded; judge from the program's output and the job's exit.
 
 Honest limits of the input lane: Ctrl-D is not a universal EOF (on a line without a trailing newline it first delivers that text — send it again on the emptied line to end a reader like `cat`); Ctrl-C only interrupts where the terminal mode allows; `job_kill` remains the explicit cancel; `input` never creates, dials, reconnects or replays — address a live session as `pty:<id|label>`, any transport. A command waiting for input IS the busy state — a new `cmd` gets `[E_SESSION_BUSY]`; feed the running command instead of queueing a second one. On a oneshot, `stdin` is startup-only: known data may ride the initial `exec`, but a oneshot cannot be fed after it starts and its timeout still cancels the whole group — a prompt there means cancel and switch to PTY. Heredocs and input redirection remain valid bulk-input alternatives; there is no global stdin ban. Cancelling is reliable (0.3.2-d): `job_kill` writes its status marker after the terminal's ^C input flush, so even a cancel that follows a bare Ctrl-C settles `killed · exit 130` with the session alive — and hub-lane control bytes cross the local raw half as bytes, interpreted by the peer pty, so ^C/^D behave like every other transport.
 
 Use the stateless oneshot when a step is genuinely one-shot (a probe, a pipeline stage, a supervised build you will not revisit) or when the `runner` supervision guarantee matters. On dumb-pipe transports the supervisor is the pinned `superd-run` helper (or its POSIX wrapper) — receipts say which ran. On the Hub lane the peer IS our own server: supervision is native there (`bash -lc` in a detached group, TERM→2s→KILL, output rings, lease lifecycle) and receipts say `hub-lease`; the helper is a dumb-pipe artifact and is never uploaded over the Hub. Note that `exec` always executes something: a warm session is created by running a command (`true` is enough), never by omitting `cmd`.
 
-There is no `mode` field: append `:pty` to a transport target to create, address a live shell as `pty:<id|label>`. `add` only registers (BYO identity or BYO PTY) and never runs a command. `scriptPath` cannot combine with cmd/stdin/PTY and is `exec`-only. Direct local command execution is not provided; use native local shell tools. Background jobs require the official jobs service/controller and are read/killed with `job_output`/`job_kill`; on PTY lanes a background job's jobId is the commandId (a timeout handoff keeps them as separate ledger fields). SSH keys/config stay on the origin; BYO identities are not persisted across new/cold Agents. PTY backlog recovery and live probes are not part of this release.
+A machine target defaults to its reusable PTY; `mode:"oneshot"` selects the isolated stateless lane. The old `:pty` creation suffix and the `input` action are gone — multiple addressable shells come from `handoff {target:<machine>}` (detaches the default as `pty:<id>`), and prompt input is `exec` with `stdin` alone. `add` only registers (BYO identity or BYO PTY) and never runs a command. `scriptPath` is an alternative to `cmd` and may carry `stdin` (startup input rides after the script bytes) in both lanes. Direct local command execution is not provided; use native local shell tools. Background jobs require the official jobs service/controller and are read/killed with `job_output`/`job_kill`; on PTY lanes a background job's jobId is the commandId (a timeout handoff keeps them distinct until adoption backfills the job). SSH keys/config stay on the origin; BYO identities are not persisted across new/cold Agents. PTY backlog recovery and live probes are not part of this release.
 
-PTY state is durable and readable: every dispatch returns exit, cwd and `envDelta` (variable names and change markers only — values never leave the endpoint; fetch them yourself if needed). `close` is idempotent (`closed:false, reason:"not-found"|"already-closed-or-reaped"`); a session with a running job refuses close unless `force:true`, which first interrupts the running command — its job settles in the killed family (`interrupted: exit 130`, or `session closed` when the frame cannot arrive) — and then kills the group. A busy session rejects new commands instead of queueing (`[E_SESSION_BUSY]` names the running id and the ways out: `input` more stdin, `job_output`, `job_kill`, or another session/oneshot); open another PTY or use a oneshot for parallel work. Idle PTYs are reaped after 15 minutes; an Agent holds at most 10 live sessions across connections, and dead sessions do not count. `hub:<m4>:pty[:label]` opens the same session shape over the Hub WebSocket lane — identity, labels, input, parallelism and background work exactly like ssh/docker/incus/BYO.
+PTY state is durable and readable: every dispatch returns exit, cwd and `envDelta` (variable names and change markers only — values never leave the endpoint; fetch them yourself if needed). `close` is idempotent (`closed:false, reason:"not-found"|"already-closed-or-reaped"`); a session with a running job refuses close unless `force:true`, which first interrupts the running command — its job settles in the killed family (`interrupted: exit 130`, or `session closed` when the frame cannot arrive) — and then kills the group. A busy session rejects new commands instead of queueing (`[E_SESSION_BUSY]` names the running id and the ways out: exec stdin-only, `job_output`, `job_kill`, handoff, or another session/oneshot); open another PTY or use a oneshot for parallel work. Idle PTYs are reaped after 15 minutes; an Agent holds at most 30 live sessions across connections (defaults and handed-off shells included; dead sessions do not count; the limit is disclosed only when reached). `hub:<m4>` as a machine target carries the same default-PTY semantics over the Hub WebSocket lane — identity, labels, stdin-only writes, parallelism and background work exactly like ssh/docker/incus/BYO.
 
 Output returns IN FULL up to retention (0.3.2-e: the self-made 30K returned-tail window is removed — model-context sizing is the native agent runtime's job, e.g. the DSH spill policy or a foreign runtime's own guard). Native/PTY retains at most 4,000,000 UTF-16 units per stream; Hub oneshot 4 MiB bytes. Beyond retention the returned text is the retained tail, headed by a one-line disclosure banner, with `outputStats` giving total/retained/dropped/returned and `truncated` set to the original total. Read `outputStats` units and dropped/returned counters rather than treating character counts as bytes. Discarded output is not recoverable after restart.
 

package/lib/fs-aware/sandbox-plugin.js

@@ -87,9 +87,9 @@ async function isPathUnder(path$1, root, caseSensitive = process.platform !== "w
 *
 * Per-call policy: `read-only` denies every mutation; `workspace-write` allows
 * a mutation only when the target canonicalizes under the policy's workspace
-* root or a platform temp area from the shared `writableRoots` policy;
-* `danger-full-access` delegates unfenced. A denial throws the structured
-* `FS_SANDBOX_DENIED`.
+* root, an explicit additional writable root, or a platform temp area from the
+* shared `writableRoots` policy; `danger-full-access` delegates unfenced. A
+* denial throws the structured `FS_SANDBOX_DENIED`.
 *
 * @module @deepseek-ai/dsh-fs-sandbox
 */

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import { t as Schema } from "./index2.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import { ToolDefinition, ToolExecutionInput, ToolRunContext, ToolRuntime } from "@deepseek-ai/dsh-tools";
+import { ToolExecutionPipeline } from "@deepseek-ai/dsh-tools/pipeline";
 import { ContentBlock, HarnessError } from "@deepseek-ai/dsh-llm";
 import { Scoped } from "@deepseek-ai/dsh-scope";
 import { Agent } from "@deepseek-ai/dsh-agent";
@@ -622,10 +623,10 @@ declare module '@deepseek-ai/cordis' {
 }
 /**
  * Capabilities the `eval` bridge closes over, mirroring upstream's
- * `RunCodeBridgeOptions` (the `requireRuntime` idiom): the registry-private
- * staged scheduler travels through the exported `TOOL_RUNTIME_SCHEDULER`
- * symbol-keyed property rather than a closure, because — unlike upstream —
- * the registry does not mint this tool for us.
+ * `RunCodeBridgeOptions` (the `requireRuntime` idiom): sub-dispatch rides a
+ * plugin-built `ToolExecutionPipeline` (0.2.2) rather than the pre-0.2.2
+ * registry-private staged scheduler, because — unlike upstream's PTC
+ * executor — the registry does not mint this tool for us.
  */
 interface RunCellBridgeOptions {
   /** Resolves `ctx.replRuntime` or throws the loud misconfiguration error (use-time read). */
@@ -649,17 +650,20 @@ interface RunCellBridgeOptions {
 /**
  * Build the `eval` {@link ToolDefinition}: required `cell` and
  * `description` parameters, executed through the dispatch bridge described
- * in the module doc. Sub-calls ride the registry's exported staged scheduler
- * (`prepare`/`dispatch`/`finalize`/`finish`) under the native concurrency
- * contract; each sub-dispatch is logged for reconstruction
- * (`tool/ptc-dispatch-start` / `tool/ptc-dispatch`) while only the outer
- * curated result enters model history.
- * @param registry - the host tool registry (sub-calls go through its staged
- *   scheduler, bindings cover its registered tools).
+ * in the module doc. Sub-calls ride the plugin-built staged pipeline
+ * (`prepare`/`dispatch`/`complete` — the 0.2.2 `ToolExecutionPipeline`, the
+ * sanctioned successor of the retired `TOOL_RUNTIME_SCHEDULER` symbol) under
+ * the native concurrency contract; each sub-dispatch is logged for
+ * reconstruction (`tool/ptc-dispatch-start` / `tool/ptc-dispatch`) while only
+ * the outer curated result enters model history.
+ * @param registry - the host tool registry (bindings cover its registered
+ *   tools; schema projection reads it live).
+ * @param pipeline - the staged invocation pipeline built over the same
+ *   registry's mounting context (sub-calls dispatch through it).
  * @param options - the bridge capabilities described above.
  * @returns the registry-ready definition.
  */
-declare function createRunCellTool(registry: ToolRuntime, options: RunCellBridgeOptions): ToolDefinition;
+declare function createRunCellTool(registry: ToolRuntime, pipeline: ToolExecutionPipeline, options: RunCellBridgeOptions): ToolDefinition;
 declare function apply(ctx: Context, config: Config): void;
 declare const _default: {
   name: string;

package/lib/index.js

@@ -2,7 +2,6 @@ import { t as Schema } from "./lib.js";
 import { a as RESERVED_ERROR_MEMBERS, i as RESERVED_BINDING_GLOBALS, n as DUNDER_MEMBER, o as ReplRuntime, r as PORTABLE_RESERVED_WORDS, t as isFlatBindableName } from "./py-sdk2.js";
 import { n as resolveKernelEnv } from "./kernel-env2.js";
 import { t as captureAllTools } from "./native-capture.js";
-import { createRequire } from "node:module";
 import { Context } from "@deepseek-ai/cordis";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
@@ -11,7 +10,8 @@ import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
-import { TOOL_RUNTIME_SCHEDULER, defineTool } from "@deepseek-ai/dsh-tools";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { ToolExecutionPipeline } from "@deepseek-ai/dsh-tools/pipeline";
 import * as dshLlm from "@deepseek-ai/dsh-llm";
 import { BlockAssembler, HarnessError, createUserMessage } from "@deepseek-ai/dsh-llm";
 import { scopeTarget } from "@deepseek-ai/dsh-scope";
@@ -2165,17 +2165,20 @@ function renderValue(value) {
 /**
 * Build the `eval` {@link ToolDefinition}: required `cell` and
 * `description` parameters, executed through the dispatch bridge described
-* in the module doc. Sub-calls ride the registry's exported staged scheduler
-* (`prepare`/`dispatch`/`finalize`/`finish`) under the native concurrency
-* contract; each sub-dispatch is logged for reconstruction
-* (`tool/ptc-dispatch-start` / `tool/ptc-dispatch`) while only the outer
-* curated result enters model history.
-* @param registry - the host tool registry (sub-calls go through its staged
-*   scheduler, bindings cover its registered tools).
+* in the module doc. Sub-calls ride the plugin-built staged pipeline
+* (`prepare`/`dispatch`/`complete` — the 0.2.2 `ToolExecutionPipeline`, the
+* sanctioned successor of the retired `TOOL_RUNTIME_SCHEDULER` symbol) under
+* the native concurrency contract; each sub-dispatch is logged for
+* reconstruction (`tool/ptc-dispatch-start` / `tool/ptc-dispatch`) while only
+* the outer curated result enters model history.
+* @param registry - the host tool registry (bindings cover its registered
+*   tools; schema projection reads it live).
+* @param pipeline - the staged invocation pipeline built over the same
+*   registry's mounting context (sub-calls dispatch through it).
 * @param options - the bridge capabilities described above.
 * @returns the registry-ready definition.
 */
-function createRunCellTool(registry, options) {
+function createRunCellTool(registry, pipeline, options) {
 	const { requireRuntime, maxParallel, shapeDispatchLog, warn } = options;
 	return defineTool({
 		name: EVAL_NAME,
@@ -2320,16 +2323,6 @@ function createRunCellTool(registry, options) {
 					parent: exec.token,
 					signal: runController.signal
 				};
-				const scheduler = registry[TOOL_RUNTIME_SCHEDULER];
-				if (scheduler === void 0) {
-					let resolvedFrom;
-					try {
-						resolvedFrom = createRequire(import.meta.url).resolve("@deepseek-ai/dsh-tools");
-					} catch {
-						resolvedFrom = "(unresolvable from the plugin position)";
-					}
-					throw new Error(`${EVAL_NAME}: the tools service mounted by this composition lacks the TOOL_RUNTIME_SCHEDULER symbol as this plugin sees it — REPL sub-dispatch cannot run. Most likely a dual-copy dsh-tools: the symbol keying the mounted ToolRuntime instance is not the symbol this plugin imported (named methods like executionMode keep working across copies; only the symbol-keyed field goes missing). This plugin resolves @deepseek-ai/dsh-tools from: ${resolvedFrom}. Check the deployed plugin's node_modules for stray @deepseek-ai entries (only schemastery and cosmokit belong there)`);
-				}
 				const outcome = await new Promise((resolve$1, reject) => {
 					let parked;
 					const settle = (result) => {
@@ -2375,7 +2368,7 @@ function createRunCellTool(registry, options) {
 					pendingQueue.push({
 						flight: Promise.resolve(),
 						settled: false,
-						classify: () => registry.executionMode(input).kind,
+						classify: () => pipeline.executionMode(input).kind,
 						abandon: () => {
 							reject(/* @__PURE__ */ new Error(`${EVAL_NAME} run is over (${String(runController.signal.reason)}); ${name$1} tool call abandoned`));
 						},
@@ -2393,9 +2386,9 @@ function createRunCellTool(registry, options) {
 								arguments: normalized.logged
 							});
 							try {
-								const prepared = await scheduler.prepare(input);
+								const prepared = await pipeline.prepare(input);
 								if (prepared.kind === "dispatch") {
-									this.flight = scheduler.dispatch(prepared.exec).then((dispatchOutcome) => {
+									this.flight = pipeline.dispatch(prepared.exec).then((dispatchOutcome) => {
 										parked = {
 											kind: dispatchOutcome.kind,
 											exec: prepared.exec,
@@ -2422,7 +2415,7 @@ function createRunCellTool(registry, options) {
 						async commit() {
 							if (parked === void 0) return;
 							try {
-								const result = parked.kind === "post-result" ? await scheduler.finalize(parked.exec, parked.result) : scheduler.finish(parked.exec, parked.result);
+								const result = await pipeline.complete(parked.exec, parked);
 								for (const context of result.additionalContexts ?? []) exec.deferContext(context);
 								if (result.concludesTurn) exec.concludeTurn();
 								settle(result);
@@ -2552,7 +2545,8 @@ function apply(ctx, config) {
 			}
 			return runtimeCtx.get("workflowEngine");
 		};
-		runtimeCtx.tools.register(createRunCellTool(registry, {
+		const pipeline = new ToolExecutionPipeline(runtimeCtx);
+		runtimeCtx.tools.register(createRunCellTool(registry, pipeline, {
 			requireRuntime,
 			maxParallel,
 			shapeDispatchLog,

package/lib/remote/plugin.d.ts

@@ -148,9 +148,13 @@ interface ProcessOptions {
   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'>): {
+declare function startBinaryProcess(argv: string[], options?: Pick<ProcessOptions, 'cwd' | 'timeoutSec' | 'env' | 'onCancel'>): {
   stdout: Readable;
   stderr: Readable;
   stdin: Writable;
@@ -257,15 +261,6 @@ interface PtyDispatchResult {
   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 {
@@ -284,12 +279,11 @@ declare class PtySession {
   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;
-  /** 账本（§5）：本会话最近 20 条命令（FIFO，超出丢最旧）。 */
-  private ledger;
   /** env 侧信道基线（init E 帧）；undefined = 侧信道不可用（不报假 delta）。 */
   private envBaseline;
   /** idle 起点（ready / settle 时重置）；null = 尚无 idle 时钟（cold 或已 dispose）。 */
@@ -310,7 +304,12 @@ declare class PtySession {
   get lastCwd(): string | null;
   /** 占用前台的 detached job 的 commandId（无 = null；close 拒绝与 busy 文案共用）。 */
   get detachedCommandId(): string | null;
-  /** job 通道收养后回填 jobId（timeout handoff 时 registry id ≠ commandId，账本如实记录两者）；运行中的命令同步携带（input 回执用）。 */
+  /** 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(): {
@@ -320,8 +319,6 @@ declare class PtySession {
     byo: boolean;
     builtOn: boolean;
   };
-  /** 账本快照（session card 面，只读）。 */
-  ledgerSnapshot(): readonly LedgerEntry[];
   /** spawn 创建原文（仅 BYO 会话；v2 起仅存档，不参与复用判定）。 */
   get origin(): string | undefined;
   /** status 面快照：state + busy（有命令在跑）+ idleMs（上次 settle 至今）+ pid（进程组头，kill 兜底可观测）。 */
@@ -520,6 +517,41 @@ interface RsyncReceipt extends RunResult {
  */
 declare function runRsync(request: RsyncRequest, source: RsyncEndpoint, destination: RsyncEndpoint, signal: AbortSignal, options?: RelayRsyncOptions): Promise<RsyncReceipt>;
 //#endregion
+//#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;
+  }>;
+}
+/** 每 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>;
+}
+//#endregion
 //#region src/remote/oneshot.d.ts
 interface OneShotOptions {
   stdin?: string;
@@ -539,6 +571,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
@@ -603,6 +637,7 @@ interface RemoteDriverOptions {
   onAudit?: (r: RemoteAuditRecord) => void;
   oneshotArgvFor?: (plan: TargetPlan, cmd: string, options: {
     cleanupTag?: string;
+    muxArgv?: readonly string[];
   }) => string[];
   ptyArgvFor?: (plan: TargetPlan) => string[];
   spawnArgvFor?: (spawnCommand: string) => string[];
@@ -611,6 +646,8 @@ interface RemoteDriverOptions {
   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 读取（裸名解析复用）。 */
@@ -626,6 +663,10 @@ declare function hubPtyAssets(): {
 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;
@@ -638,6 +679,7 @@ declare class RemoteDriver {
   private readonly runnerOf;
   private disposal;
   private readonly ptyIdleTtlSec;
+  private readonly mux;
   constructor(opts?: RemoteDriverOptions);
   call(params: RemoteCallParams, callCtx?: {
     sessionKey?: string;
@@ -676,6 +718,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）。 */
@@ -683,8 +729,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?: {
@@ -709,10 +783,9 @@ declare class RemoteDriver {
   };
   /** 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 供工具层渲染。 */
+  /** 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 & {