super-dsh 0.3.1 → 0.3.2

package/client/index.js

@@ -898,6 +898,16 @@ function machineLabelsFrom(list) {
 * roster-probe failure → revert to native + a visible toast, never a page
 * lock).
 *
+* Live-install staleness (2026-10-18): the fusion flag global and the
+* transport script are baked into the SERVED index, so a page that booted
+* before super-dsh was installed runs the freshly hot-loaded client half
+* against a stale page — `fusionPage()` reads false and every switch
+* affordance stays hidden until a manual restart. {@link fusionReloadDecision}
+* is the pure decision behind the client half's heal: one roster answer later,
+* reload the page once. The transport must precede app boot (its upload hook
+* `__DSH_FILE_UPLOAD__` is read at construction), so a client-side flag flip
+* can never arm a stale page honestly — the page must be re-served.
+*
 * Host-half on purpose: plain TS with every effect injected through
 * {@link SwitchHost} — no DOM, no client imports — so `test/client-switch.test.mjs`
 * imports it from `dist/` like every other host module. The client half
@@ -1343,6 +1353,22 @@ function switchAffordance(fusion) {
 		hint: FUSION_OFF_HINT
 	};
 }
+/** The sessionStorage marker guarding the stale-page reload: one per tab session. */
+const FUSION_RELOAD_MARKER = "superd.fusion-armed.reload";
+/**
+* The live-install staleness decision (host-half pure so the node tests pin
+* the table from `dist/`). The host's `hub.fusion` field is the ONLY thing
+* that distinguishes a page-booted-before-install from a deliberately
+* flag-off deployment — without it the reload would loop forever on every
+* `enabled: false` composition (the client half loads there too).
+*/
+function fusionReloadDecision(input) {
+	if (input.flagPresent) return "armed";
+	if (input.markerPresent) return "already-reloaded";
+	if (input.hubFusion === true) return "reload";
+	if (input.hubFusion === false) return "row-off";
+	return "host-silent";
+}
 /**
 * The active agent's display name for the Hub row's right-edge selector: the
 * roster label of the atom's `activeAgent` key — the name the selector's
@@ -1621,6 +1647,53 @@ function createReadinessWaiter(faces, options = {}) {
 function fusionPage() {
 	return globalThis.__SUPERD_UI_FUSION__ === true;
 }
+/**
+* The sessionStorage marker read (undefined-safe: a storage failure is
+* `false` — the probe then reloads without the loop guard, which only
+* matters for a host that reports fusion but never bakes the flag).
+*/
+function staleReloadMarker() {
+	try {
+		return globalThis.sessionStorage?.getItem(FUSION_RELOAD_MARKER) !== null;
+	} catch {
+		return false;
+	}
+}
+/**
+* Live-install staleness probe (2026-10-18): the ONE call the client entry
+* makes when the page does not carry the fusion flag. A flag-absent page is
+* either a pre-install page (the client half hot-loaded into HTML served
+* before the row mounted — the fresh-install case where the Hub row renders
+* but every switch affordance stays hidden until a manual restart) or a
+* deliberate flag-off deployment (T-E). The roster's additive `hub.fusion`
+* answers which; on an armed host the page re-boots ONCE — the marker keeps
+* a misbehaving host from ever looping the tab. Every failure mode (fetch
+* error, non-OK, old host without the field) degrades to no action: the
+* flag-off shapes below are the honest rendering of an unanswered probe.
+*
+* Fire-and-forget by contract — never throws, never blocks the apply.
+*/
+function probeStaleFusionPage() {
+	(async () => {
+		let hubFusion;
+		try {
+			const response = await fetch("/api/agent-runtime", { credentials: "same-origin" });
+			if (!response.ok) return;
+			hubFusion = (await response.json()).hub?.fusion;
+		} catch {
+			return;
+		}
+		if (fusionReloadDecision({
+			flagPresent: fusionPage(),
+			markerPresent: staleReloadMarker(),
+			hubFusion
+		}) !== "reload") return;
+		try {
+			globalThis.sessionStorage?.setItem(FUSION_RELOAD_MARKER, "1");
+		} catch {}
+		globalThis.location?.reload();
+	})();
+}
 /** The page atom, when the page carries one (it always does on a fusion page). */
 function uiState() {
 	const state = globalThis.__SUPERD_UI_STATE__;
@@ -3880,6 +3953,38 @@ function HubPage() {
 	});
 }
 
+//#endregion
+//#region src/client/pill-geometry.ts
+/**
+* Derive the scroll-invariant offsets from one same-frame measurement.
+* Measuring the DELTAS (not absolute coordinates) is the whole point: they
+* survive any scroll of any ancestor, so nothing needs to re-run while the
+* sidebar scrolls.
+*/
+function measurePillBox(input) {
+	return {
+		dx: input.row.right - input.wrap.left,
+		cy: (input.row.top + input.row.bottom) / 2 - input.wrap.top
+	};
+}
+/** The row's own horizontal padding (native `.panelRow`): the selector's inset. */
+const PILL_ROW_INSET = 8;
+/**
+* The pill's placement, wrapper-relative: its right edge sits `inset` px
+* inside the row's right edge, vertically centered on the row
+* (`translateY(-50%)`). `selectorWidth` is the render-time pill width (the
+* mark is present only while an agent is active), so it stays a render
+* concern; the measured box is not.
+*/
+function pillStyle(box, selectorWidth, inset = PILL_ROW_INSET) {
+	return {
+		position: "absolute",
+		left: box.dx - inset - selectorWidth,
+		top: box.cy,
+		transform: "translateY(-50%)"
+	};
+}
+
 //#endregion
 //#region src/client/HubPanelIcon.tsx
 /** Runtime-mark edge inside the selector, and the chevron's own default edge. */
@@ -3893,8 +3998,6 @@ const CHEVRON_SIZE = 14;
 const SELECTOR_HEIGHT = 28;
 const SELECTOR_PAD = 8;
 const SELECTOR_GAP = 4;
-/** The row's own horizontal padding (native `.panelRow`): the selector's inset. */
-const ROW_INSET = 8;
 function HubPanelIcon({ size }) {
 	const wide = size <= 16;
 	const rootRef = react.useRef(null);
@@ -3917,16 +4020,25 @@ function HubPanelIcon({ size }) {
 	}, [fusion]);
 	const measure = react.useCallback(() => {
 		const row = rootRef.current?.closest("button") ?? null;
-		if (row === null) {
+		const wrap = selectorRef.current?.parentElement ?? null;
+		if (row === null || wrap === null) {
 			setBox(null);
 			return;
 		}
-		const rect = row.getBoundingClientRect();
-		setBox((prev) => prev !== null && prev.top === rect.top && prev.bottom === rect.bottom && prev.right === rect.right ? prev : {
-			top: rect.top,
-			bottom: rect.bottom,
-			right: rect.right
+		const rowRect = row.getBoundingClientRect();
+		const wrapRect = wrap.getBoundingClientRect();
+		const next = measurePillBox({
+			row: {
+				top: rowRect.top,
+				bottom: rowRect.bottom,
+				right: rowRect.right
+			},
+			wrap: {
+				left: wrapRect.left,
+				top: wrapRect.top
+			}
 		});
+		setBox((prev) => prev !== null && prev.dx === next.dx && prev.cy === next.cy ? prev : next);
 	}, []);
 	react.useLayoutEffect(() => {
 		if (!wide || !switchUi.available) return;
@@ -4036,7 +4148,7 @@ function HubPanelIcon({ size }) {
 		children: [
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(HubGlyph, { size }),
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SuperdToastHost, {}),
-			wide && box !== null && switchUi.available && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__deepseek_ai_dsh_client_ui_primitives.Menu, {
+			wide && switchUi.available && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__deepseek_ai_dsh_client_ui_primitives.Menu, {
 				open,
 				onClose: () => {
 					setOpen(false);
@@ -4057,10 +4169,11 @@ function HubPanelIcon({ size }) {
 					"aria-expanded": open,
 					title: activeLabel === void 0 ? "Agent selector" : `Agent selector: ${activeLabel}`,
 					style: {
-						position: "fixed",
-						left: box.right - ROW_INSET - selectorWidth,
-						top: box.top + (box.bottom - box.top) / 2,
-						transform: "translateY(-50%)",
+						...pillStyle(box ?? {
+							dx: 0,
+							cy: 0
+						}, selectorWidth),
+						visibility: box === null ? "hidden" : "visible",
 						display: "inline-flex",
 						alignItems: "center",
 						justifyContent: "center",
@@ -4105,9 +4218,17 @@ const inject = ["slots"];
 * absent (a composition without the sidebar renders nothing — every seat
 * here is an optional occupant by contract).
 *
-* @param ctx - client root context.
+* Live-install staleness: the fusion flag is baked into the SERVED index, so
+* a page that booted before super-dsh was installed carries no flag even
+* though this very apply is the hot-loaded client half — the Hub row would
+* render with every switch affordance hidden until a manual restart. When
+* the flag is absent the entry probes the roster's `hub.fusion` once and
+* re-boots the page on an armed host (switch.ts `probeStaleFusionPage`; the
+* sessionStorage marker bounds it to one reload per tab session). A flag-off
+* deployment answers `false` and keeps the T-E inert shape with no reload.
 */
 function apply(ctx) {
+	if (!fusionPage()) probeStaleFusionPage();
 	ctx.inject(["slots"], (raw) => {
 		const scope = raw;
 		scope.effect(() => scope.slots.inject("main", () => scope.slots.register({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-dsh",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Super D for the DeepSeek Harness (DSH) — one dsh plugin that mounts the superd hub (runtime selector, roster, per-runtime agents) and joins local foreign-agent runtimes (OMP, Codex, Claude, Pi, Hermes, Antigravity) into the DSH Web UI. Each runtime keeps its native home and session store; the hub only bridges.",
   "type": "module",
   "license": "MIT",

package/remote/helper-bin/MANIFEST.json

@@ -0,0 +1,35 @@
+{
+  "format": 1,
+  "name": "superd-run",
+  "ver": "0.3.1-d.b596",
+  "protocol": 1,
+  "targets": {
+    "aarch64-apple-darwin": {
+      "file": "superd-run",
+      "bytes": 337808,
+      "sha256": "a8fd11a5e6a2cb146deb599414434a299ebf78c53cfc1d3e5f42617ee11c1706"
+    },
+    "aarch64-unknown-linux-musl": {
+      "file": "superd-run",
+      "bytes": 397592,
+      "sha256": "3a8660fa099f1e71de6e08313ee2aaace00503f74365475ee46e2d2a89228397"
+    },
+    "x86_64-pc-windows-gnu": {
+      "file": "superd-run.exe",
+      "bytes": 337408,
+      "sha256": "1372450238c5bda702b4529f4148aa79e80a255c3c125d1a6229afd4693e9d90"
+    },
+    "x86_64-unknown-linux-musl": {
+      "file": "superd-run",
+      "bytes": 447152,
+      "sha256": "05b428657942abf22a0ad609433d5cab6b6182fe389851345459a0274b5a6533"
+    }
+  },
+  "sources": {
+    "Cargo.toml": "129ab8360e9da872f9dfd6e713d81fe1389735a74d781f3d9c15e110f92d2757",
+    "build.rs": "c4fb356956b1ec700e99bdeca07d657a7d3b2a4026582db136411676da3d125e",
+    "src/main.rs": "47f1648ea1abc30583839edab219a9062c83d57be981c0505ab6bf79c6fbff54",
+    "src/unix.rs": "56c5f523b7b1a9efd50ef24ccdabc024bc065dd2f904fdbecdf0ca49fe7f3393",
+    "src/windows.rs": "6c1537424b1adc05ed17c7cf8bf376fb5711602b9da1697d596155bf21d541da"
+  }
+}

package/remote/helper-bin/aarch64-apple-darwin/BUILT-VER

@@ -0,0 +1 @@
+0.3.1-d.b596

package/remote/helper-bin/aarch64-unknown-linux-musl/BUILT-VER

@@ -0,0 +1 @@
+0.3.1-d.b596

package/remote/helper-bin/x86_64-pc-windows-gnu/BUILT-VER

@@ -0,0 +1 @@
+0.3.1-d.b596

package/remote/helper-bin/x86_64-unknown-linux-musl/BUILT-VER

@@ -0,0 +1 @@
+0.3.1-d.b596

package/remote/plugin.d.ts

@@ -90,16 +90,10 @@ 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[];
@@ -117,7 +111,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;
@@ -154,8 +153,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 +210,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,6 +224,58 @@ 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;
+  }>;
+}
+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 {
@@ -260,7 +323,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 +345,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;
@@ -311,31 +388,39 @@ interface RemoteDriverOptions {
   ptyArgvFor?: (plan: TargetPlan) => string[];
   spawnArgvFor?: (spawnCommand: string) => 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 会话池。 */
+/** 双轨调度器：参数校验 → 目标语法（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,44 +432,80 @@ 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;
+  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;
@@ -397,13 +518,13 @@ interface RemoteInput {
   spawn?: string;
   ssh?: SshConnection;
   cmd?: string;
-  script?: string;
+  scriptPath?: string;
   stdin?: string;
   mode?: 'oneshot' | 'pty';
   timeout?: number;
 }
 interface PreparedRemoteInput {
-  target: string;
+  target?: string;
   spawn?: string;
   ssh?: SshConnection;
   cmd: string;
@@ -552,4 +673,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 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 };