better-dsh 0.3.0-g → 0.3.0-r

package/docs/remote-tools.md

@@ -13,40 +13,44 @@ Better Dash and Super Dash each provide the native `remote` tool and REPL route.
 | Stream a local script to fixed `bash -s` | `{target:"ssh:alias",script:"/absolute/script.sh"}` |
 | Persistent shell | `{target:"ssh:alias",mode:"pty",cmd:"cd /tmp; export CHECK=ready"}` |
 | Official background job | `{target:"ssh:alias",cmd:"long-command",run_in_background:true}` |
-| Binary file/tree copy | `{action:"copy",src:"/absolute/source",dst:"ssh:alias:/absolute/destination",verify:true,mkdir:true}` |
-| Preview native SSH delta sync | `{action:"rsync",src:"/absolute/source/",dst:"ssh:alias:/existing/destination/",dryRun:true,delete:false}` |
+| 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"]}` |
 
 `script` cannot combine with cmd/stdin/spawn/PTY. Direct local command execution is not provided; use native local shell tools. Background jobs are oneshot-only, require the official jobs service/controller, and are read/killed with `job_output`/`job_kill`; they have no default foreground timeout. An explicit timeout still applies. 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.
 
 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.
 
-## File safety and prerequisites
+## File operations: native CLI semantics
 
-Copy supports local, SSH/byossh, Docker, Incus and authenticated Hub binary transports, not arbitrary BYO-PTY shells. CLI endpoints require the receiving-owner prerequisites below; Hub uses native Node. Copy fully stages on the origin before delivery, merges directories without deleting extras, and verifies SHA-256 over transferred entries only. `verify:false` skips the independent verification claim. Successful staging is removed; failure receipts identify retained diagnostic payload. Unsafe archive paths/types and symlink escapes (including preserved destination ancestors) are rejected.
+`remote` addresses targets once (`ssh:<name>`, `byossh:<label>`, `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.
 
-Rsync is SSH-only (one endpoint may be local), with no copy fallback. Dry-run is the default; deletion is opt-in. The origin needs Bash/native rsync. SSH peers need Bash ≥4.1, Python ≥3.7 (macOS ≥3.10), Unix `fcntl.flock`, and a shared non-adjustable cross-process monotonic clock. Nothing auto-installs prerequisites. Two-remote source additionally needs native `find`. Its task-owned Python loopback proxy uses authenticated SSH stdio and an origin bridge into the destination `-L` tunnel; no source remote-forwarding permission, Linux `/proc`, pidfd or privileged sshd access is required. The full route must produce a real rsync greeting before transfer; no origin Python prerequisite is added. A normal two-remote operation uses 12 SSH startups (prerequisite/inspection, destination daemon+tunnel, source proxy owner/work and native sender); ambiguous admission can add authenticated cleanup reconnects, never transfer retries.
+### copy routes
 
-Two-remote relay uses an existing non-symlink destination directory; unsupported file/new/ambiguous paths and source symlinks are refused before transfer. Ordinary local↔SSH legs retain native path/link semantics. Native rsync stats/itemized changes report real delta behavior. Cancellation/disposal waits for owned cleanup. A startup channel lost before receipt may require restored authenticated connectivity to observe cleanup; recovery never restarts the transfer. Ordinary receiver progress is required, not a hard-real-time guarantee on a frozen host.
+| Route | Command | Notes |
+| --- | --- | --- |
+| local↔SSH | `scp` | default SFTP; caller may pass `-O` explicitly |
+| SSH↔SSH | `scp -3` (data through the origin) | both identities stay on the origin; differing BYO identities are separated by a temporary origin-only SSH config, removed afterwards. `scp -R` is refused before start: it would authenticate from the source host |
+| local↔Docker | `docker cp` | |
+| local↔Incus | `incus file push/pull` | |
+| other cross-endpoint pairs (SSH↔Docker, Docker↔Incus, …) | two native commands with origin staging | each half takes its own options via `pullArgv`/`pushArgv` (mutually exclusive with `argv`); the receipt states both commands |
+| Hub↔local↔local | existing staged archive lane | the only lane where `verify`/`mkdir` apply; it keeps SHA-256 verification and destination-parent creation. CLI-option fields are rejected on this lane |
 
-Hub addresses use `hub:<machine-id>` only when the optional provider is present; paired remote machines never mean self. Hub errors do not fall back to SSH. The runtime tool description carries the detailed current call and recovery contract.
+The native CLIs do not create destination parents or verify results on their own; receipts report each command's exit, stdout/stderr and the sanitized argv. Two-segment routes stage in an origin scratch directory that is removed on normal exit (`cleanup:"released"`); an interrupted channel is reported as `cleanup:"unknown"`.
 
-### Owned SSH command requirements
+### rsync routes
 
-Foreground/background SSH and BYO-SSH oneshots, including scripts and literal stdin, use the same portable receiving owner. Remote requirements are Bash 4.1+, Python 3.7+ (macOS 3.10+ for the shared cross-process monotonic epoch), Unix `fcntl.flock`, and `mktemp`, `mv`, `rm`, `sleep`. Ordinary commands do **not** require rsync. No origin Python or Linux/pidfd requirement is added; PTY/BYO-PTY is unchanged.
+rsync supports SSH/byossh endpoints with at most one local endpoint. Local↔SSH runs `rsync` on the origin with the endpoint's SSH identity wired through `RSYNC_RSH`; an explicit `-e`/`--rsh` in `argv` replaces that wiring per rsync's own rules (the command must then carry its own port/key/config). Nothing else is injected — no archive, no timeout, no dry-run, no remote owner, no `--rsync-path`.
 
-Each oneshot uses three SSH startups: clock-only prerequisite, receiving control owner, and the work channel with untouched stdin/stdout/stderr. Native connection identity, port, key and ProxyJump stay canonical; agent forwarding and reusable multiplexing are disabled for these owned connections. Cleanup waits for the receiving helper and work process group, not merely local SSH exit. The existing 8-second receiving lease, counted 2-second renewals and 3.5-second ordinary-scheduling cleanup allowance also cover the gate. Ambiguous lost startup needs an authenticated same-identity observer; restore connectivity if cleanup observation remains pending. This assumes a progressing receiver, not hard real-time scheduling.
+SSH↔SSH prefers the native forwarding route: the destination runs a temporary loopback-only rsync daemon, `ssh -L` brings it to an origin port, `ssh -R` carries it onto the source's loopback, and the source's own native rsync client performs one protocol conversation through the chain. The origin only forwards rsync protocol bytes; the destination's existing file data feeds real delta matching (`--stats` shows Matched data dominating for a small change on a large file). If an endpoint refuses TCP forwarding (`AllowTcpForwarding no`), a standard-stream route would be attempted; on the current OpenSSH/rsync combination (10.2 / 3.4.1) that route reports itself unavailable — the error says so and nothing is copied. rsync never falls back to a full copy or to Python.
 
-After cleanup proof the separate work stream gets up to 2500ms for final drain. If unavailable, the result explicitly diagnoses potentially incomplete output; counters only count received data. A successful normal completion drains the full work stream. No new registry, availability poller or job completion notifier is introduced.
+Tool-owned daemons/forwards/SSH sessions are torn down on normal exit and observable cancellation; a lost channel is reported with `cleanup:"unknown"` rather than a false success claim.
 
-### Container oneshot ownership
+### Prerequisites
 
-Docker/Incus oneshots require the same Bash/Python/fcntl/shared-monotonic/core-utility receiver prerequisites and three native exec startups. Linux containers also require Python stdlib ctypes and permitted unprivileged PR_SET_CHILD_SUBREAPER; the helper reaps only its own/adopted descendants before settlement, including ordinary non-reaping PID1 containers. Nothing installs or changes images, privileges or configuration. PTY is unchanged.
+File operations require the corresponding CLI on the origin (`scp`, `rsync`, `docker`, `incus`) and on the SSH/container endpoints that execute it (`rsync` for rsync routes; none beyond the container's own CLI for docker/incus copy). No remote Python, Node or worker is deployed for file transfers. The dual-SSH forwarding route requires `AllowTcpForwarding` on both endpoints. BYO-PTY is not a file endpoint.
 
+## One-shot command requirements
 
-### CLI binary receiving ownership (consumer correction, Ruling26)
+One-shot SSH/byossh commands (foreground, background, script and literal stdin) run through ONE native SSH exec: the command executes under bash with a small POSIX wrapper whose TERM/HUP trap kills the command's whole process group, so backgrounded children do not outlive the session teardown. Remote prerequisites: bash (POSIX) — **no Python, no owner/lease protocol, no flock/monotonic clock, no extra sessions**. On normal completion the wrapper's EXIT trap reaps the command's whole process group (backgrounded children included — they neither outlive the call nor hold the channel open), and the exit code passes through verbatim. On timeout/cancellation the local transport dies at once and a dedicated cleanup session reads the pidfile the wrapper left and kills the group (TERM→KILL); sshd delivers no signal to a no-PTY session, so this explicit cleanup is the remote kill path.
 
-Actual N native SSH copy cancellation settled while the remote import process and its unnamed staging file remained live under a finite work-channel EOF hold. CLI export/import/digest now reuse the canonical portable receiving owner, with raw binary work streams and the same counted lease, admission gate and authenticated recovery. Cancellation/failure waits for receiving helper/group/temp cleanup before local transport teardown/settlement. Normal success must completely drain the binary stream; the oneshot text lane's 2500ms incomplete-output rule does not apply. Archive validation, selected manifest digests, merge/no-delete behavior and canonical SSH identity/ProxyJump are unchanged. Local and Hub file lanes are unchanged.
-
-This intentionally replaces the former Python-only minimum for CLI peers: Bash4.1+, Python3.7+ (macOS3.10+), Unix fcntl.flock/shared non-adjustable cross-process monotonic clock, mktemp/mv/rm/sleep; Linux containers also need stdlib ctypes and permitted unprivileged PR_SET_CHILD_SUBREAPER. No rsync or origin Python requirement, auto-install, second registry, fallback, peer polling or increased lease. Minimal Python-only peers no longer support this CLI lane; use a supported peer or authenticated Hub.
-
-Each remote export/import/digest costs three native transport starts: clock, independent owner/control, literal binary work. Thus verified local→CLI or CLI→local costs six; CLI→CLI twelve. verify:false skips digest operations, reducing counts to three/three/six. Local/Hub operations do not contribute CLI starts. Fault recovery may add same-identity authenticated cleanup starts and may remain pending until genuine cleanup observation is possible. Artifact O must re-prove installed cancellation and complete binary integrity; N failures remain historical evidence.
+Docker/Incus one-shots use the same pure-CLI lane (`docker exec` / `incus exec` with the same wrapper); container prerequisites are the container's own bash. PTY paths are unchanged (`ssh -tt bash`, docker via script(1), incus interactive) and never required Python.

package/lib/client/index.js

@@ -64,7 +64,7 @@ const zh = {
 };
 
 //#endregion
-//#region \0dsh-css:/home/u1/workspaces/superd/better-dsh/src/failover/client/FailoverRow.module.css.mjs
+//#region \0dsh-css:/home/u1/workspaces/superd/.worktrees/remote-native-shortcut/better-dsh/src/failover/client/FailoverRow.module.css.mjs
 const css$1 = "\n._440e1d7b_row {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 12px 0;\n}\n\n._a4f2ceec_rowText {\n  flex: 1;\n  min-width: 0;\n  display: flex;\n  flex-direction: column;\n  gap: 4px;\n}\n\n._9865b509_title {\n  font-weight: 600;\n  font-size: 14px;\n}\n\n\n._3cfec826_slots {\n  display: flex;\n  flex-direction: column;\n  align-items: flex-end;\n  gap: 6px;\n}\n\n._11c2662d_select {\n  width: 280px;\n  max-width: 100%;\n  min-width: 0;\n}\n\n._b7c358f9_alert {\n  color: var(--dsw-alias-danger, #c0392b);\n  font-size: 12px;\n}\n";
 const tagId$1 = "better-dsh/FailoverRow.module.css";
 if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId$1) + "]") === null) {
@@ -463,7 +463,7 @@ const zh$1 = {
 };
 
 //#endregion
-//#region \0dsh-css:/home/u1/workspaces/superd/better-dsh/src/compaction/client/CompactionRow.module.css.mjs
+//#region \0dsh-css:/home/u1/workspaces/superd/.worktrees/remote-native-shortcut/better-dsh/src/compaction/client/CompactionRow.module.css.mjs
 const css = "\n\n\n._13e3747c_thresholdRow {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 16px 0;\n  border-bottom: 0.5px solid var(--dsw-alias-border-l2);\n}\n\n._8ad3ff3f_thresholdText {\n  flex: 1;\n  min-width: 0;\n  display: flex;\n  flex-direction: column;\n  gap: 4px;\n  padding-right: 48px;\n}\n\n._9ffb627e_thresholdTitle {\n  font-size: 14px;\n  font-weight: 400;\n  line-height: 22px;\n  color: var(--dsw-alias-label-primary);\n}\n\n._01bea389_thresholdDesc {\n  font-size: 12px;\n  font-weight: 400;\n  line-height: 18px;\n  color: var(--dsw-alias-label-tertiary);\n}\n\n._7f9578de_thresholdError {\n  font-size: 12px;\n  font-weight: 400;\n  line-height: 18px;\n  color: var(--dsw-alias-danger, #c0392b);\n}\n\n\n._cddd78cd_thresholdControl {\n  display: inline-flex;\n  align-items: center;\n  gap: 8px;\n}\n\n._6058fea9_thresholdStepper {\n  position: relative; \n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  min-width: 72px;\n  height: 36px;\n  border-radius: 18px;\n  background: var(--dsw-alias-bg-module-platform);\n}\n\n._39d30469_thresholdValue {\n  min-width: 18px;\n  text-align: center;\n  font-size: 14px;\n  line-height: 22px;\n  font-variant-numeric: tabular-nums;\n  color: var(--dsw-alias-label-primary);\n}\n\n._68bd35c6_thresholdUnit {\n  font-size: 14px;\n  line-height: 22px;\n  color: var(--dsw-alias-label-secondary);\n}\n\n\n._904da366_thresholdArrows {\n  position: absolute;\n  right: 8px;\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  opacity: 0;\n}\n\n._6058fea9_thresholdStepper:hover ._904da366_thresholdArrows,\n._6058fea9_thresholdStepper:focus-within ._904da366_thresholdArrows {\n  opacity: 1;\n}\n\n\n._ae9106b1_thresholdArrow {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 17px;\n  height: 12px;\n  padding: 0;\n  border: none;\n  border-radius: 3px;\n  background: color-mix(in srgb, var(--dsw-alias-bg-layer-1) 75%, transparent);\n  color: var(--dsw-alias-label-primary);\n  cursor: pointer;\n}\n\n._ae9106b1_thresholdArrow:hover:not(:disabled) {\n  background: var(--dsw-alias-bg-layer-1);\n}\n\n._ae9106b1_thresholdArrow:disabled {\n  color: var(--dsw-alias-label-caption);\n  cursor: default;\n}\n";
 const tagId = "better-dsh/CompactionRow.module.css";
 if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {

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

@@ -6,7 +6,7 @@ import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
 import { FsError } from "@deepseek-ai/dsh-fs";
 import { writableRoots } from "@deepseek-ai/dsh-sandbox";
 
-//#region ../upstream/deepseek-harness/packages/fs/fs-sandbox/lib/index.js
+//#region ../../../upstream/deepseek-harness/packages/fs/fs-sandbox/lib/index.js
 /**
 * Path-containment mechanics for the filesystem sandbox. Canonical spellings
 * take the fast lexical path; filesystem identity supplies the conservative

package/lib/mobile/plugin.d.ts

@@ -1,5 +1,5 @@
 import { t as Schema } from "../index-DTDXUe6m.js";
-import { r as MobileConfig } from "../web-trust-RwK0P74B.js";
+import { r as MobileConfig } from "../web-trust-CwZrTBcl.js";
 import { Context } from "@deepseek-ai/cordis";
 
 //#region src/mobile/plugin.d.ts

package/lib/remote/plugin.d.ts

@@ -6,7 +6,6 @@ import { StandardSchemaV1 } from "../../third_party/schemastery/node_modules/@st
 import { JobId, JobRegistry } from "@deepseek-ai/dsh-jobs";
 
 //#region src/remote/ssh-targets.d.ts
-/** Origin-owned identity reference, never key contents or a persistent credential store. */
 interface SshConnection {
   readonly host: string;
   readonly user?: string;
@@ -51,71 +50,91 @@ interface TransferReceipt {
   error?: string;
 }
 //#endregion
-//#region src/remote/ssh-relay.d.ts
-type SshBuilder = typeof sshArgv;
-interface CommandResult {
+//#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';
+  src: string;
+  dst: string;
+  /** Native route actually used, stated as a fact (two-command routes never masquerade as one CLI). */
+  route: string;
+  /** Native argv actually executed per command, one token per element, no shell joining. */
+  argv: string[][];
+  exits: (number | null)[];
+  stdout: string[];
+  stderr: string[];
+  outputTruncated: boolean;
+  /** Native CLI success only — no independent digest was computed for this path. */
+  verified: false;
+  /** Tool-owned staging/config release: released on normal/observed exit, unknown when a channel was lost. */
+  cleanup: 'released' | 'unknown' | 'none-required';
+}
+interface RunResult {
   exit: number | null;
   stdout: string;
   stderr: string;
   outputTruncated: boolean;
 }
-interface RelayOptions {
-  ssh?: SshBuilder;
+//#endregion
+//#region src/remote/ssh-rsync-native-relay.d.ts
+interface RelayRsyncOptions {
+  /** Test seam: wraps every spawned SSH/daemon argv (fixture isolation). */
+  wrapArgv?: (argv: string[]) => string[];
+  /** Test seam: fixed daemon port instead of ephemeral allocation. */
   ports?: {
-    destination: number;
-    origin: number;
-    source: number;
+    daemon: number;
   };
+  /** Test seam: skip route A (simulate denied forwarding). */
+  forceStdioRoute?: boolean;
 }
-interface Relay {
-  url: string;
-  /** Runs sender under a lease-owned remote supervisor, never downstream SSH. */
-  run(argv: string[]): Promise<CommandResult>;
-}
-declare function withSshRelay<T>(source: SshConnection, destination: SshConnection, targetPath: string, signal: AbortSignal, run: (relay: Relay) => Promise<T>, options?: RelayOptions): Promise<T>;
 //#endregion
 //#region src/remote/rsync.d.ts
 interface RsyncRequest {
   src: string;
   dst: string;
-  dryRun?: boolean;
-  delete?: boolean;
-  excludes?: readonly string[];
-  preserve?: boolean;
+  argv?: string[];
 }
 interface RsyncEndpoint {
   path: string;
   connection?: SshConnection;
 }
-interface RsyncReceipt extends CommandResult {
+interface RsyncReceipt extends RunResult {
   action: 'rsync';
   src: string;
   dst: string;
-  dryRun: boolean;
-  delete: boolean;
-  preserve: boolean;
-  itemizedChanges: string[];
+  argv: string[];
+  command: string;
+  /** Populated only when the CLI actually printed --stats output. */
+  itemizedChanges?: string[];
   literalBytes?: number;
   matchedBytes?: number;
   sentBytes?: number;
   receivedBytes?: number;
   transferredBytes?: number;
+  /** Two-SSH route actually used, when applicable. */
+  route?: 'local-ssh' | 'ssh-ssh-forward' | 'ssh-ssh-stdio';
 }
-declare function runRsync(request: RsyncRequest, source: RsyncEndpoint, destination: RsyncEndpoint, signal: AbortSignal, options?: RelayOptions): Promise<RsyncReceipt>;
-//#endregion
-//#region src/remote/target.d.ts
-/** 解析后的传输计划：三种 CLI 传输之一。 */
-type TargetPlan = {
-  kind: 'ssh';
-  host: string;
-  connection?: SshConnection;
-} | {
-  kind: 'docker';
-  container: string;
-} | {
-  kind: 'incus';
-  container: string;
-};
+/**
+ * Native rsync with ordered caller options. Local↔SSH runs rsync directly with
+ * the endpoint's SSH identity wired as RSYNC_RSH; explicit -e/--rsh in argv
+ * overrides that wiring per rsync's own rules (the receipt shows the argv).
+ * SSH↔SSH delegates to the native relay routes (forwarding first, stdio second).
+ * No option is injected: no archive, no timeout, no dry-run, no remote owner.
+ */
+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;
@@ -126,9 +145,11 @@ interface ProcessOptions {
   /** 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'>): {
+declare function startBinaryProcess(argv: string[], options?: Pick<ProcessOptions, 'cwd' | 'timeoutSec' | 'env'>): {
   stdout: Readable;
   stderr: Readable;
   stdin: Writable;
@@ -200,13 +221,16 @@ interface RemoteAuditRecord {
 }
 interface RemoteDriverOptions {
   /** Fixture transport seam; normal consumers use the canonical native SSH builder. */
-  rsyncSshArgv?: SshBuilder;
+  /** Fixture transport seam for native copy CLIs (scp/docker/incus argv isolation). */
+  nativeArgvFor?: (argv: string[]) => string[];
   getHub?: () => HubRemoteTransport | undefined;
   execTimeoutSec?: number;
   idleTtlSec?: number;
   maxOutputChars?: number;
   onAudit?: (r: RemoteAuditRecord) => void;
-  oneshotArgvFor?: (plan: TargetPlan, cmd: string) => string[];
+  oneshotArgvFor?: (plan: TargetPlan, cmd: string, options: {
+    cleanupTag?: string;
+  }) => string[];
   ptyArgvFor?: (plan: TargetPlan) => string[];
   spawnArgvFor?: (spawnCommand: string) => string[];
   probeRunner?: ProbeOptions['runner'];
@@ -231,9 +255,17 @@ declare class RemoteDriver {
   call(params: RemoteCallParams, callCtx?: {
     sessionKey?: string;
   }): Promise<RemoteCallResult>;
-  copy(request: CopyRequest, signal: AbortSignal, callCtx?: {
+  /** 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. */
+  copy(request: CopyRequest & {
+    argv?: unknown;
+    pullArgv?: unknown;
+    pushArgv?: unknown;
+  }, signal: AbortSignal, callCtx?: {
     sessionKey?: string;
-  }): Promise<TransferReceipt>;
+  }): Promise<TransferReceipt | NativeCopyReceipt>;
   rsync(request: RsyncRequest, signal: AbortSignal, callCtx?: {
     sessionKey?: string;
   }): Promise<RsyncReceipt>;
@@ -443,4 +475,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, withSshRelay };
+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 };