better-dsh 0.3.2 → 0.3.3

package/docs/remote-tools.md

@@ -4,31 +4,47 @@ Better Dash and Super Dash each provide the native `remote` tool and REPL route.
 
 ## Choose a call
 
+`remote` declares its action; `remote_transfer` declares its mode. Nothing dispatches on which fields happen to be present.
+
 | Goal | Input |
 | --- | --- |
-| List locally known targets without dialing | `{}` |
-| Probe one target | `{target:"ssh:alias"}` |
-| Register an Agent-local SSH identity (no dialing) | `{target:"ssh:build",ssh:{host:"host",user:"user",key:"/origin/key"}}`; omit `target` for an auto id (`ssh-xxxx`) |
-| Stateless command and stdin over an identity | `{target:"ssh:build",cmd:"cat",stdin:"hello"}` |
-| Stream a local script to fixed `bash -s` | `{target:"ssh:alias",scriptPath:"/absolute/script.sh"}` |
-| Create a persistent shell (tab semantics) | `{target:"ssh:alias:pty",cmd:"cd /tmp; export CHECK=ready"}`; append `:label` (`ssh:alias:pty:build`) to name it |
-| Reuse a persistent shell | `{target:"pty:<id\|label>",cmd:"…"}` |
-| Session card (state + ledger, no command) | `{target:"pty:<id\|label>"}` |
-| Create a BYO PTY from a spawn command | `{spawn:"docker exec -it img bash",target:"pty:build",cmd:"…"}`; later `{target:"pty:build",cmd:"…"}` |
-| Background job (oneshot or PTY) | `{target:"ssh:alias",cmd:"long-command",run_in_background:true}` |
-| Close a PTY session | `{action:"close",target:"pty:<id\|label>",force:true}` |
-| Native CLI copy | `{action:"copy",src:"/absolute/source",dst:"ssh:alias:/absolute/destination",argv:["-p"]}` |
-| Native rsync | `{action:"rsync",src:"/absolute/source/",dst:"ssh:alias:/existing/destination/",argv:["-a","--partial","--dry-run"]}` |
-
-`mode` no longer exists: append `:pty` to a transport target to create, address a live shell as `pty:<id|label>`. `scriptPath` cannot combine with cmd/stdin/spawn/PTY. 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.
-
-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 kills the group and reports `killed`. A busy session rejects new commands instead of queueing; open another PTY or use a oneshot. 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` selects the Hub lane's PTY but exposes no session id, label, parallelism or background works there.
-
-Native/PTY output retains at most 4,000,000 UTF-16 units per stream; Hub oneshot retains 4 MiB bytes. Normal returned tails are smaller. Read `outputStats` units and dropped/returned counters rather than treating character counts as bytes. Discarded output is not recoverable after restart.
+| List locally known targets without dialing | `remote {action:"status"}` |
+| Probe one target / show a session card | `remote {action:"status",target:"ssh:alias"}`, `remote {action:"status",target:"pty:<id\|label>"}` |
+| 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 |
+| 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 |
+| 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"]}` |
+
+## PTY is a persistent, interactive terminal session
+
+Prefer the PTY lane. A PTY dispatch returns synchronously with the same receipt a oneshot returns — output text, exit code, duration — and only adds state: `session`, `cwd`, `envDelta`, `commandId`, `ttlSec`. Nothing is withheld at read time; the terminal merges stderr into the output stream, which is the only receipt difference. What the session buys is durability: cwd, exported environment, shell variables, activated virtualenvs, aliases and an open REPL survive between calls, so a multi-step task becomes N cheap calls instead of N stateless logins, and a command that outlives its timeout hands off to a pollable job instead of being killed. It is also the only interactive lane: a running command can be observed and then fed more stdin (`input`), which a oneshot never offers.
+
+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.
+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.
+
+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.
+
+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.
 
 ## File operations: native CLI semantics
 
-`remote` addresses targets once (`ssh:<name>`, `ssh:<label>` for a BYO identity, `docker:<name>`, `incus:<name>`, `hub:<machine>`, local paths) and hands the actual transfer to the native CLI. `argv` is an ordered array of native option tokens — one element = one argv token, appended verbatim before the parsed `src`/`dst`. There is no option whitelist, no shell parsing, and no forced defaults: no hidden `--dry-run`, no forced archive/timeout, no automatic verification. A dry run means passing `--dry-run` yourself; unknown or incompatible options fail in the native CLI and its exit code and stderr come back as-is. Success of a native command is never reported as independently verified — `verified:false` on native copy receipts means exactly that.
+`remote_transfer` addresses targets once (`ssh:<name>`, `ssh:<label>` for a BYO identity, `docker:<name>`, `incus:<name>`, `hub:<machine>`, local paths) and hands the actual transfer to the native CLI. `mode:"copy"|"rsync"` is required and spans only transfer fields. `argv` is an ordered array of native option tokens — one element = one argv token, appended verbatim before the parsed `src`/`dst`. There is no option whitelist, no shell parsing, and no forced defaults: no hidden `--dry-run`, no forced archive/timeout, no automatic verification. A dry run means passing `--dry-run` yourself; unknown or incompatible options fail in the native CLI and its exit code and stderr come back as-is. Success of a native command is never reported as independently verified — `verified:false` on native copy receipts means exactly that.
 
 ### copy routes
 

package/docs/specs/remote-tool-enhancement/spec.md

@@ -2,6 +2,7 @@
 
 - 日期：2026-10-10（Asia/Hong_Kong）
 - 状态：2026-10-10 user 已审阅并明确授权执行；Task0–7 已独立审阅通过；Task8 完整双包消费者验收进行中，L 实装暴露的 worker/SSH cleanup 缺陷已进入修复验证。用户亲验与发布尚未放行。
+- 2026-10-25 surface 修订（user 指令，本轮实现）：`remote` 的判别字段改为**必填** `action: exec|add|close|status`；文件传输字段（`src`/`dst`/`argv`/`pullArgv`/`pushArgv`/`verify`/`mkdir`）迁到独立工具 `remote_transfer`，判别字段为**必填** `mode: copy|rsync`。`add` 只注册 BYO 身份/终端，不执行命令；`exec` 必填 `target` 且必须执行东西（warm 会话用 `cmd:"true"`）。工具简介把 PTY 重新定位为「stateful oneshot」并鼓励优先使用。下文 §5 的旧 `action:"copy"|"rsync"` 调用形与「无 action」形仅作历史。
 - 0.3.2-b 对齐（2026-10-19）：`script` 已定名 `scriptPath`；`mode` 字段已移除（用 `<transport>:pty[:label]` 创建、`pty:<id|label>` 复用）；`byossh:`/`byop:` 前缀已移除（`ssh`/`spawn` 参数在场即 BYO）。下文旧调用形仅作历史。
 - 输入：[2026-10-09 方向稿](../../10_plans/2026-10-09-remote-tool-optimization-directions.md)及 2026-10-10 会话裁决。
 - 执行计划：[2026-10-10-remote-tool-enhancement.md](../../superpowers/plans/2026-10-10-remote-tool-enhancement.md)。本规格优先于方向稿的冲突条款。

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/hub-pty-pump.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Hub PTY pump — the DUMB child of the canonical PTY session over a Hub
+// machine (0.3.2-c). The session (better-dsh/src/remote/pty-session.ts)
+// spawns `script -qfec 'stty -echo; … exec node <this file>' /dev/null`, so
+// this process's stdin/stdout ride a host-side PTY; we forward those bytes
+// over one WebSocket to the peer hub's dumb PTY executor
+// (/api/superd/exec/pty: one WS = one `script -qfec bash /dev/null`, text
+// frames = stream bytes, {"op":…} JSON frames = transport control, WS close
+// = peer group-kill). All session intelligence (nonce framing, init
+// handshake, env E-frames, two-stage interrupt, idle TTL) is in-band bytes
+// produced by the SESSION — this pump never parses the stream, only the
+// peer's control frames.
+//
+// Connection facts arrive via environment (never argv — credentials must not
+// show up in `ps`):
+//   SUPERD_HUB_PTY_URL     wss://…/api/superd/exec/pty (peer executor)
+//   SUPERD_HUB_PTY_COOKIE  pairing cookie for the upgrade request
+//   SUPERD_HUB_PTY_WS      ABSOLUTE path to a usable `ws` module (resolved by
+//                          the caller before spawning; no resolution gamble
+//                          here — a missing module is a creation-time error)
+//
+// Verbatim-asset discipline (helper-bin precedent): this file is copied
+// byte-for-byte into lib/remote/ and the Super closure; no build step
+// transforms it. Crash-proof by construction (mesh-gateway lesson): the
+// 'error' listener is registered before anything can reject, and post-close
+// sends are swallowed — the session's death path owns the teardown.
+const PUMP_ENV_PREFIX = 'SUPERD_HUB_PTY_'
+const [url, cookie, wsPath] = ['URL', 'COOKIE', 'WS'].map((k) => process.env[`SUPERD_HUB_PTY_${k}`])
+
+// cookie may be legitimately empty (an unauthenticated test lane sends no header);
+// the endpoint URL and the ws module path are the hard requirements.
+if (url === undefined || url === '' || wsPath === undefined || wsPath === '') {
+  process.stderr.write(`hub-pty-pump: missing environment (${PUMP_ENV_PREFIX}URL/WS)\n`)
+  process.exit(1)
+}
+
+let WebSocket
+try {
+  const require = (await import('node:module')).createRequire(import.meta.url)
+  const mod = require(wsPath)
+  WebSocket = typeof mod === 'function' ? mod : mod.default
+} catch (err) {
+  process.stderr.write(`hub-pty-pump: cannot load ws module at ${wsPath} — ${err instanceof Error ? err.message : String(err)}\n`)
+  process.exit(1)
+}
+if (typeof WebSocket !== 'function') {
+  process.stderr.write('hub-pty-pump: the ws module did not yield a WebSocket constructor\n')
+  process.exit(1)
+}
+
+const socket = new WebSocket(url, { headers: cookie ? { cookie } : {} })
+let opened = false
+let forward = true
+
+socket.on('error', (err) => {
+  // Always-on listener: an ECONNREFUSED or a rejected 401 upgrade must be a
+  // reported death, never an uncaught exception.
+  process.stderr.write(`hub-pty-pump: ${opened ? 'socket error' : 'connect failed'} — ${err instanceof Error ? err.message : String(err)}\n`)
+})
+socket.on('open', () => { opened = true; pumpStdin() })
+socket.on('message', (data) => {
+  if (!forward) return
+  const text = typeof data === 'string' ? data : Array.isArray(data) ? Buffer.concat(data).toString('utf8') : Buffer.from(data).toString('utf8')
+  // Transport control frames (peer: {"op":"exit"} / {"op":"spawn-error"}) are
+  // addressed to THIS pump, not to the shell stream — the exit frame is
+  // followed by a socket close, which settles us below.
+  if (text.startsWith('{"op":')) {
+    try {
+      const parsed = JSON.parse(text)
+      if (typeof parsed.op === 'string') {
+        if (parsed.op === 'spawn-error' && typeof parsed.error === 'string') process.stderr.write(`hub-pty-pump: peer could not spawn the terminal — ${parsed.error}\n`)
+        return
+      }
+    } catch { /* not JSON after all: fall through and forward */ }
+  }
+  process.stdout.write(text)
+})
+socket.on('close', () => {
+  forward = false
+  // Before open this is a failed connection (diag already on stderr); after
+  // open it is the peer session ending — either way the child exiting is the
+  // session's dead signal.
+  process.exit(opened ? 0 : 1)
+})
+
+function pumpStdin() {
+  process.stdin.setEncoding('utf8')
+  process.stdin.on('data', (chunk) => {
+    if (!opened) return
+    try { socket.send(chunk) } catch { /* closing: the close handler exits us */ }
+  })
+  // The session's kill path tears down the process group; a plain stdin end
+  // (no kill) still means nobody will type more — close politely so the peer
+  // reaps its side.
+  process.stdin.on('end', () => { try { socket.close() } catch { /* already closing */ } })
+  process.stdin.on('error', () => { /* EPIPE on teardown: the close path owns the exit */ })
+}