dsh-remote 0.8.51 → 0.8.53

package/README.en.md

@@ -285,6 +285,17 @@ Deploying to a product profile is a separate, explicit action (`./sync.sh`) for
 **`@` lists remote files but the built-in read tool cannot open them** — the harness's own file tools see the **local mirror**, which stays empty until `rw_sync` downloads it. Read remote files with `rw_read_file` or the sidebar remote tab.
 
 **A file link in a remote Session does not open** (issue #55) — fixed. When a link is clicked the harness turns it into `dsh-resource://file/session/<session>/<path>` and hands it to the built-in text preview, which reads the **local** filesystem; a remote Session's cwd is a **local mirror directory** (empty until `rw_sync`), so the open simply failed. The plugin now registers a higher-priority handler for that address and opens it over SFTP through the same editor as the sidebar "Remote Files" tab. The safety rule is deliberately conservative: it takes over only when the Session's cwd is **provably inside a mirror** and the mirror registry has loaded, so local Sessions — and the instant right after a page load — keep the built-in preview and no local file is ever mistaken for a remote one. The two cases that still cannot be mapped say so instead of showing a blank page: an address with no mirror mapping, and a Session whose workspace is not a remote mirror directory.
+Two exceptions (0.8.52+): `.md`/`.markdown` links are **not** taken over and stay with the built-in Markdown renderer (issue #64 — the remote editor would only show source, a net loss for Markdown; it reads the local mirror copy, so `rw_sync` first for the latest content). And images never had a renderer on either path anyway: the sidebar remote tree now renders png/jpg/gif/webp/svg/bmp inline (issue #66; files over 2MB fall back to the download button).
+
+**One SFTP timeout wedged every SFTP tool on that machine** (issue #65) — fixed (0.8.52+). A single operation hitting the 20s timeout used to poison the whole process for that machine (every later SFTP call paid its own 20s, while `rw_exec` stayed fine) until a disconnect/reconnect. Now a timeout kills the channel so later requests fail fast; the native backend tears the connection down and re-handshakes after two consecutive timeouts, and the openssh backend rebuilds its sftp child — a transient network blip no longer ends with "disconnect and reconnect". As a bonus, `rw_edit` now writes atomically (temp file + rename), so an interrupted write can no longer truncate the remote file to zero bytes, and the original permission bits are preserved.
+
+**The machine's IP / username changed — must every workspace be recreated?** (issue #67) — no (0.8.52+). Edit the machine's new address on the settings page and save, or call `rw_connect(machineId=…, host=…, username=…, port=…)` with the new address: every workspace mirror bound to that machine is **rebound in place** (its `.dsh-remote-meta.json` is rewritten) — local content is kept, no re-sync needed, and the save response says how many mirrors were rebound. The mirror directory name does not follow (live Sessions hold cwd paths inside it); the name is a display label only and does not affect connectivity.
+
+**Remote Sessions could not see the workspace AGENTS.md** (issue #68) — fixed (0.8.52+). The core instruction loader only knows the local filesystem, and a remote Session's cwd is the local mirror, so the remote repo's AGENTS.md never reached the model's context. Now, when `rw_pick_workspace` succeeds, the remote workspace gets a shallow scan (root + at most two levels down, matching `AGENTS.md`/`CLAUDE.md` only); the found files are synced into the local mirror under a three-way guard (root-level copies thus enter the core's own injection path, exactly like a local Session), and an index of paths + headings is rendered into the system prompt, telling the model to read nested instruction files with `rw_read_file` before editing. Full-tree recursion and plugin-side full-text injection are deliberately **not** done (the former would scan through multi-project roots; the latter would run a second injection pipeline in parallel with the core's).
+
+**Does reading a file in a remote subdirectory pull that subdirectory's AGENTS.md into context?** (issue #71) — yes (0.8.53+). #68 fixed only the static half (workspace shallow scan + index line); the dynamic half was still broken, because the core's incremental injection recognizes only `read`/`write`/`edit` with a `file_path` argument — `rw_read_file` matches on neither name nor argument — and it expands scopes using LOCAL paths, so a remote absolute path maps onto no mirror cwd. Any one of those three gaps was enough to stop the injection from ever happening. The plugin now hooks `rw_*` file touches itself on `tools/result`, takes the WHOLE ancestor chain from the touched directory up to the workspace root (not just the deepest level, matching local Sessions: reading `a/b/c.ts` brings in both `a/AGENTS.md` and `a/b/AGENTS.md`), stats each level, and injects the current contents as ONE user message. Boundaries that matter: the cwd's own level is not re-scanned (the core baseline covers it, so reading a file directly in the workspace root triggers no extra scan); delivery is deduplicated per session by content digest, so the same content is injected once; a remote edit is re-injected on the next touch; a previously injected file that disappears produces a "removed" notice; one batch has a 16 KB budget; and an offline machine degrades silently — it hangs neither the tool call nor the prompt assembly. The message carries the plugin's own `source.kind` (`dsh-remote-instructions`), while the core's state machine claims only its own `agent-instructions`, so the two injection paths cannot fight.
+
+**Can `rw_exec` take a per-call timeout, be cancelled, and move to the background like the built-in shell?** (issue #70) — yes (0.8.53+). The transport (`pool.exec`) already supported `timeoutMs` and `AbortSignal`; what was missing was the wiring, and all three pieces are now in place: (1) a `timeoutMs` argument (clamped to 1000-600000, defaulting to `commandTimeoutMs`) whose timeout message prints the value ACTUALLY APPLIED rather than the config value; (2) `exec.signal` is forwarded, so pressing "stop" really SIGTERMs the remote process and returns at once instead of waiting out the timeout; (3) `run_in_background: true` returns a job id immediately (read with the existing `job_output`, stop with `job_kill`), and a command that outlives its timeout is PROMOTED to a background job instead of being killed (`promoteOnTimeout`, on by default). Background execution and promotion need the core `jobs` service; a composition without it (minimal embedding, test double) degrades to foreground-only execution — the 0.8.52 behaviour — rather than failing to load.
 
 **The terminal in a remote Session is still the local one** (issue #55) — that is **by design, and a plugin cannot change it**, but there is an equivalent: DSH's sidebar terminal is core, its PTY comes from the **context-global** `subprocess` service, and its cwd is the Session's own workspace directory (the local mirror for a remote Session). A plugin can neither replace that service nor retarget the core terminal onto SSH. For a **genuine remote terminal** use the "Remote DSH Web UI" (above): it opens the **remote machine's own** DSH in this browser, and that interface's terminal runs on the remote host, with no extra configuration. To run a single remote command instead, use `rw_exec` (add `pty: true` for an interactive PTY).
 

package/README.md

@@ -274,6 +274,49 @@ scripts/dev-run.sh --status    # 是否在运行
 本地会话与页面刚加载的那一瞬间仍然走内置预览 —— 不会把本地文件误当成远程文件。
 两个仍然开不了的情况会给出明确提示而不是空白页：链接指向的是**绝对**远端路径之外无法映射的地址，
 或该会话的工作区不是一个远程镜像目录。
+两个例外（0.8.52+）：`.md`/`.markdown` 链接**不被接管**、交还内置 Markdown 渲染（issue #64——远程编辑器只能看
+源码，对 Markdown 是净损失；它读本地镜像副本，要最新内容先 `rw_sync`）；图片文件则在内置链路与远程链路
+都谈不上「渲染」，侧栏远程文件树现在直接内联显示 png/jpg/gif/webp/svg/bmp（issue #66，>2MB 退回下载按钮）。
+
+**SFTP 操作一旦超时就永远卡死**（issue #65）—— 已修（0.8.52+）。旧版里一次撞满 20s 超时的 SFTP 操作会把
+该机器在本进程内的全部 SFTP 工具拖到永久超时（`rw_exec` 却正常），只能断连重连。现在超时即置死该通道、
+后续请求立即失败；native 后端连续两次超时会废弃整条连接重新握手，openssh 后端会重建 sftp 子进程——
+一次网络抖动不再需要用「断开重连」来收场。顺带，`rw_edit` 改成了「临时文件 + rename」原子写，
+写一半超时不会再把远端文件截成 0 字节，原文件的权限位也会保留。
+
+**机器换了 IP / 用户名，工作区要全部重建吗？**（issue #67）—— 不用（0.8.52+）。在设置页编辑该机器的新
+地址并保存，或 `rw_connect(machineId=…, host=…, username=…, port=…)` 同传新地址：该机器名下所有工作区
+镜像会**原地重绑**（改写镜像的 `.dsh-remote-meta.json`），本地内容保留、无需重新同步，保存后会提示重绑了
+几个镜像。镜像目录名不会跟着改（活 session 的 cwd 在其中），目录名只是显示标签、不影响连接。
+
+**远程会话看不到工作区的 AGENTS.md**（issue #68）—— 已修（0.8.52+）。核心的指令加载只认本地文件系统，
+而远程会话的 cwd 是本地镜像，远端仓库的 AGENTS.md 以前永远进不了模型上下文。现在 `rw_pick_workspace`
+成功时会对远程工作区做浅扫（根 + 向下 ≤2 层，只匹配 `AGENTS.md`/`CLAUDE.md`），把命中的文件按三向安全
+规则同步进本地镜像（根级文件由此进入核心自己的注入链路，与本地会话一致），并把路径+标题索引渲染进
+system prompt，提示模型编辑前用 `rw_read_file` 阅读嵌套层的指令。全树递归扫描与插件侧全文注入都**刻意
+不做**（前者会扫穿多项目根目录，后者会与核心的注入管线并行打架）。
+
+**读了远程子目录的文件，子目录里的 AGENTS.md 会自动进上下文吗？**（issue #71）—— 会（0.8.53+）。
+#68 只修了静态部分（工作区浅扫 + 索引行）；动态部分当时还断着，原因是核心的增量注入只认
+`read`/`write`/`edit` 且只认 `file_path` 参数，而 `rw_read_file` 名字和参数都对不上，且它做作用域
+扩展时用的是**本地**路径——远程绝对路径映射不到镜像 cwd，三个断点任一都足以让注入永不发生。
+现在插件自己在 `tools/result` 里接 `rw_*` 文件触碰，取「被访问目录 → 工作区根」的**整条目录链**
+（不是最近一层，与本地会话一致：读 `a/b/c.ts` 会同时收 `a/AGENTS.md` 和 `a/b/AGENTS.md`），逐层
+`stat` 后把当前内容合成**一条** user message 注入。几个关键边界：cwd 自己那层不重扫（核心 baseline
+已覆盖，所以读工作区根下的文件不触发任何额外扫描）；按内容摘要 per-session 去重，同内容只注入一次；
+远端修改后下次触碰即重新注入；注入过的文件被删除会发一条「已移除」提示；单次注入有 16 KB 预算；
+机器离线时整条链路静默降级，既不挂工具调用也不挂 prompt 组装。注入消息用插件自己的
+`source.kind`（`dsh-remote-instructions`），核心的状态机只认领它自己的 `agent-instructions`，两条
+注入路径不会互相打架。
+
+**`rw_exec` 能像内置 shell 那样自定义超时/取消/转后台吗？**（issue #70）—— 能（0.8.53+）。
+底层 `pool.exec` 本来就支持 `timeoutMs` 与 `AbortSignal`，缺的是接线，现在补齐三件事：
+① `timeoutMs` 参数（clamp 到 1000–600000，缺省仍用 `commandTimeoutMs`，超时文案打印**实际生效**的值，
+不会印错成配置值）；② `exec.signal` 透传给 `pool.exec`——点「停止」会真的 SIGTERM 掉远端进程并立即
+返回，不用再等满超时；③ `run_in_background: true` 立即返回 job id（用现成的 `job_output` 读、
+`job_kill` 停），以及超时**转后台**而非直接杀（`promoteOnTimeout`，默认开）。后台/转后台依赖核心的
+`jobs` 服务；没有该服务的组合（最小嵌入、测试替身）自动退化为只有前台执行——即 0.8.52 的行为，
+不会因此加载失败。
 
 **远程会话里的终端还是本机的**（issue #55）—— 这是**设计如此，插件改不了**，但有等效方案。
 DSH 的侧栏终端是核心功能：它的 PTY 来自**全局唯一**的 `subprocess` 服务，cwd 取会话自己的

package/lib/client.js

@@ -179,6 +179,7 @@ window.__ModuleLoader__.load({
         'settings.feedback': '💬 反馈建议 / 提 issue',
         'settings.deleted': '已删除',
         'settings.saved': '已保存更新',
+        'settings.rebound': '已将 {n} 个本地工作区镜像重新绑定到新地址（内容保留，无需重新同步）',
         'settings.added': '已添加 — 可设为当前',
         'settings.secretStoreFailed': '密码未能写入系统密钥库（{msg}），已回退为明文保存在 machines.json，连接仍可用。',
         'settings.switched': '已切换为当前远程机',
@@ -467,6 +468,7 @@ window.__ModuleLoader__.load({
         'settings.feedback': '💬 Feedback / report issue',
         'settings.deleted': 'Deleted',
         'settings.saved': 'Saved',
+        'settings.rebound': 'Rebound {n} local workspace mirror(s) to the new address (content kept — no re-sync needed)',
         'settings.added': 'Added — you can set it as current',
         'settings.secretStoreFailed': 'The OS keychain refused the password ({msg}); it was saved as plaintext in machines.json and the machine still connects.',
         'settings.switched': 'Switched to current remote machine',
@@ -1190,6 +1192,9 @@ window.__ModuleLoader__.load({
           // Issue #30: "加密保存密码"失败时服务端回退明文并带警告 —— 不能再静默
           // 保存一台没有凭据的机器（那会让之后每次连接都失败且没有原因）。
           if (r && r.warning === 'secret-store-failed') setErr(tr('settings.secretStoreFailed', { msg: r.warningDetail || 'unknown' }))
+          // Issue #67: an edited address rebinds the machine's existing mirrors —
+          // say so, or the user cannot tell their workspaces came along.
+          else if (r && r.reboundMirrors) setMsg(tr('settings.saved') + ' — ' + tr('settings.rebound', { n: r.reboundMirrors }))
           else setMsg(form.id ? tr('settings.saved') : tr('settings.added'))
         }).catch((e) => setErr(String((e && e.message) || e))).finally(() => setBusy(false))
       }
@@ -3237,7 +3242,7 @@ window.__ModuleLoader__.load({
       React.useEffect(load, [path])
 
       const startEdit = () => {
-        if (!data || data.binary) return
+        if (!data || data.binary || data.image) return
         setDraft((data.content != null ? data.content : '').replace(/\n…\[truncated:.*$/, ''))
         setEdit(true); setErr('')
       }
@@ -3276,7 +3281,7 @@ window.__ModuleLoader__.load({
                 React.createElement('button', { type: 'button', className: 'dsh-rw-btn dsh-rw-primary', style: { ...primaryBtnS, padding: '2px 10px', fontSize: 12 }, onClick: saveRemote, disabled: saving || !dirty, title: tr('file.saveHint') }, saving ? tr('file.saving') : tr('file.saveToRemote')),
                 React.createElement('button', { type: 'button', className: 'dsh-rw-btn', style: { ...buttonS, padding: '2px 10px', fontSize: 12 }, onClick: () => { setEdit(false); setErr('') } }, tr('file.cancel')))
             : React.createElement(React.Fragment, null,
-                React.createElement('button', { type: 'button', className: 'dsh-rw-btn', style: { ...buttonS, padding: '2px 10px', fontSize: 12 }, onClick: startEdit, disabled: !data || data.binary }, tr('file.edit')),
+                React.createElement('button', { type: 'button', className: 'dsh-rw-btn', style: { ...buttonS, padding: '2px 10px', fontSize: 12 }, onClick: startEdit, disabled: !data || data.binary || data.image }, tr('file.edit')),
                 React.createElement('button', { type: 'button', className: 'dsh-rw-btn', style: { ...buttonS, padding: '2px 10px', fontSize: 12 }, onClick: downloadMirror, disabled: saving }, tr('file.download'))),
         ),
         React.createElement('div', { style: { flex: 1, overflow: 'auto', minHeight: 0, display: 'flex', flexDirection: 'column' } },
@@ -3285,7 +3290,10 @@ window.__ModuleLoader__.load({
             : (data && data.binary
                   ? React.createElement('div', { style: { padding: 12, fontSize: 13, color: T.warn } },
                       tr('file.binary', { size: (data.size != null ? data.size + ' bytes' : tr('file.unknownSize')) }))
-                  : (edit
+                  : data && data.image
+                    ? React.createElement('div', { style: { flex: 1, display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 12, minHeight: 0 } },
+                        React.createElement('img', { src: `data:${data.mime};base64,${data.content}`, alt: baseName, style: { maxWidth: '100%', maxHeight: '100%', objectFit: 'contain' } }))
+                    : (edit
                       ? React.createElement('textarea', {
                           value: draft,
                           onChange: (e) => setDraft(e.target.value),
@@ -3636,6 +3644,10 @@ window.__ModuleLoader__.load({
             canOpen: (address) => {
               const parsed = parseCoreFileAddress(address)
               if (!parsed) return false
+              // Let the built-in Markdown preview keep .md/.markdown files: it can
+              // render them, whereas the remote-link editor would only show source.
+              const name = String(parsed.path || '').split(/[\\/]/).pop()
+              if (/\.(md|markdown)$/i.test(name)) return false
               const cwd = sessionCwdFor(parsed.sessionId)
               // `MIRRORS.loaded` is checked so a cold start NEVER steals a local
               // link: an empty registry cannot prove a mirror, and guessing would

package/lib/exec-job.js

@@ -0,0 +1,221 @@
+// dsh-remote — remote command execution: per-call timeout, real cancellation,
+// and background jobs (issue #70).
+//
+// The transport (`SshPool.exec`) already supported `opts.timeoutMs` and
+// `opts.signal` — #70 was pure wiring on top of it:
+//
+//   1. `rw_exec` had no per-call `timeoutMs`, so a 10-minute build meant editing
+//      the machine-wide `commandTimeoutMs` config and editing it back.
+//   2. `exec.signal` was never forwarded, so pressing "stop" left the tool
+//      running until the full timeout elapsed (rw_search already forwarded it).
+//   3. A timeout always SIGTERM'd the command. There was no way to hand a long
+//      build to the background and collect it later, unlike the built-in shell.
+//
+// This module owns the pieces that are easy to get subtly wrong:
+//   • the timeout clamp and the "effective value" reported in the message (the
+//     old code printed the CONFIG value, which becomes a lie the moment a
+//     per-call override exists);
+//   • streaming taps, so a background job's output reaches its ring instead of
+//     only the return value;
+//   • the job lifecycle: register → wait → settle/remove, with cancellation
+//     flowing through the SAME AbortSignal the transport honors, so a kill
+//     actually stops the remote process rather than just abandoning the call.
+//
+// The core `jobs` service is optional. Without it (a minimal embedding, a test
+// double) everything degrades to foreground-only execution — the tool still
+// works, it just cannot be promoted.
+
+/** Per-call timeout bounds, matching the built-in shell tool's shape. */
+export const EXEC_TIMEOUT_MIN_MS = 1000
+export const EXEC_TIMEOUT_MAX_MS = 600000
+
+/**
+ * Resolve the effective timeout for one `rw_exec` call.
+ *
+ * A supplied value is clamped into [MIN, MAX]; an absent/invalid one falls back
+ * to the machine-wide `commandTimeoutMs` (itself clamped, so a bad config can
+ * never produce a nonsensical deadline).
+ *
+ * @param {unknown} value - the call's `timeoutMs` argument.
+ * @param {number} fallback - `config.commandTimeoutMs`.
+ * @returns {number} milliseconds to actually apply.
+ */
+export function resolveExecTimeout(value, fallback) {
+  const clamp = (n) => Math.min(Math.max(Math.round(n), EXEC_TIMEOUT_MIN_MS), EXEC_TIMEOUT_MAX_MS)
+  const n = Number(value)
+  if (Number.isFinite(n) && n > 0) return clamp(n)
+  const f = Number(fallback)
+  if (Number.isFinite(f) && f > 0) return clamp(f)
+  return clamp(20000)
+}
+
+/**
+ * Render a finished command into the tool's text form. Kept next to the timeout
+ * resolution so the "timed out after Nms" line can NEVER disagree with the
+ * deadline that was actually applied (issue #70 acceptance criterion 1).
+ *
+ * @param {{code: number|null, signal: string|null, stdout: string, stderr: string}} res
+ * @param {{timeoutMs: number, cancelled?: boolean}} opts
+ * @returns {string}
+ */
+export function formatExecResult(res, { timeoutMs, cancelled = false } = {}) {
+  const parts = []
+  if (res.stdout) parts.push(String(res.stdout).replace(/\s+$/, ''))
+  if (res.stderr) parts.push('-- stderr --\n' + String(res.stderr).replace(/\s+$/, ''))
+  if (!parts.length) parts.push('(no output)')
+  let text = parts.join('\n')
+  if (res.signal === 'TIMEOUT') text += `\n[command timed out after ${timeoutMs}ms]`
+  else if (cancelled || res.signal === 'ABORTED') text += '\n[cancelled — the remote command was stopped]'
+  else if (res.code !== 0) text += `\n[exit code: ${res.code}]`
+  return text
+}
+
+/**
+ * Register one remote command as a core background job.
+ *
+ * The producer owns execution: the command starts inside `run()` (so a
+ * preflight rejection leaves no SSH channel behind), its output is pushed into
+ * the job ring as it arrives, and `cancel` aborts the SAME AbortSignal the
+ * transport turns into a SIGTERM on the remote process. That last point is what
+ * makes `job_kill` real rather than cosmetic.
+ *
+ * Timeout ownership is subtle and got this wrong once: a JOB's deadline must
+ * not be enforced by the transport, because the whole point of a background
+ * job is to OUTLIVE the tool call that started it. Passing `timeoutMs` down
+ * would make the transport SIGTERM the command at the very moment the caller
+ * promotes it. So the transport gets a deadline only when this job is meant to
+ * be bounded on its own (`jobDeadlineMs`); the foreground/promotion decision is
+ * made by the CALLER's wait, not by the exec.
+ *
+ * @param {object} registry - the core `jobs` service (`ctx.jobs`).
+ * @param {object} spec
+ * @param {object} spec.pool - the machine's SshPool.
+ * @param {string} spec.command - the full command line to run.
+ * @param {string} [spec.label] - one-line model-facing label (defaults to command).
+ * @param {any} [spec.owner] - owning session id, when the caller has one.
+ * @param {number} [spec.jobDeadlineMs] - optional deadline enforced ON THE
+ *   COMMAND itself (omitted ⇒ the job runs until it finishes or is killed).
+ * @param {boolean} [spec.pty]
+ * @param {object} [spec.env]
+ * @returns {{id: string, cancel: Function}}
+ */
+export function startExecJob(registry, { pool, command, label, owner, jobDeadlineMs, pty, env }) {
+  let abort = null
+  let cancelled = null
+  const id = registry.start({
+    kind: 'rw-exec',
+    label: String(label || command || 'rw_exec'),
+    ...(owner ? { owner } : {}),
+    run: (job) => {
+      const ac = new AbortController()
+      abort = ac
+      const done = (async () => {
+        let res
+        try {
+          res = await pool.exec(command, {
+            // 0/undefined ⇒ no transport deadline: the job outlives the call.
+            ...(jobDeadlineMs ? { timeoutMs: jobDeadlineMs } : {}),
+            pty: !!pty,
+            env,
+            signal: ac.signal,
+            // Stream into the ring: a background job's value is its output, and
+            // the model reads it later through job_output, not from a return
+            // value it already lost.
+            onData: (channel, chunk) => {
+              const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk)
+              if (!text) return
+              try { job.append(text, { channel }) } catch { /* settled: ring closed */ }
+            },
+          })
+        } catch (err) {
+          return { status: 'failed', detail: String((err && err.message) || err) }
+        }
+        if (res.signal === 'ABORTED' || cancelled) return { status: 'killed', detail: cancelled || 'cancelled' }
+        if (res.signal === 'TIMEOUT') return { status: 'killed', detail: `timed out after ${jobDeadlineMs}ms` }
+        const code = res.code
+        return {
+          status: code === 0 ? 'completed' : 'failed',
+          detail: code === 0 ? 'exit code: 0' : `exit code: ${code}`,
+        }
+      })()
+      return {
+        done,
+        // Synchronous, idempotent, and it reaches the remote process: the
+        // transport turns this abort into `stream.signal('SIGTERM')`.
+        cancel: (reason) => {
+          if (cancelled === null) cancelled = String(reason || 'cancelled')
+          try { ac.abort() } catch { /* already aborted */ }
+        },
+      }
+    },
+  })
+  return {
+    id,
+    cancel: (reason) => {
+      if (cancelled === null) cancelled = String(reason || 'cancelled')
+      try { abort && abort.abort() } catch { /* not started yet */ }
+    },
+  }
+}
+
+/**
+ * Run one remote command in the FOREGROUND, optionally promoting it to the
+ * background when it outlives `timeoutMs`.
+ *
+ * Without a job registry this is a plain bounded exec. With one, the command is
+ * registered first so the caller can be handed a live id the moment it stops
+ * waiting — the built-in shell's "promote on timeout" contract.
+ *
+ * @returns {Promise<{promoted: boolean, jobId?: string, text: string}>}
+ */
+export async function execWithOptionalPromotion({
+  registry, pool, command, label, owner, timeoutMs, pty, env, signal,
+  formatResult,
+}) {
+  if (!registry) {
+    // No registry: no promotion is possible, so the timeout is the transport's
+    // job (bounded foreground execution, the pre-#70 behaviour).
+    const res = await pool.exec(command, { timeoutMs, pty: !!pty, env, signal })
+    return { promoted: false, text: formatResult(res, { timeoutMs }) }
+  }
+  // The transport gets NO deadline here on purpose: this command is registered
+  // as a job from the start, and the ONLY thing `timeoutMs` bounds is how long
+  // THIS CALL waits before handing it to the background. Giving the exec the
+  // same deadline would SIGTERM the command at the moment of promotion — the
+  // exact bug the issue #70 live E2E caught.
+  const job = startExecJob(registry, { pool, command, label, owner, pty, env })
+  let view
+  try {
+    view = await registry.wait(job.id, timeoutMs, owner, signal)
+  } catch {
+    // The WAIT was cancelled (the caller pressed stop), not necessarily the
+    // job: stop the job too, or the remote command keeps running behind a dead
+    // tool call.
+    try { registry.kill(job.id, owner, 'tool call aborted') } catch { /* already settled */ }
+    job.cancel('tool call aborted')
+    try { registry.remove(job.id, owner) } catch { /* settlement pending */ }
+    const aborted = { code: -1, signal: 'ABORTED', stdout: '', stderr: '' }
+    return { promoted: false, text: formatResult(aborted, { timeoutMs, cancelled: true }) }
+  }
+  if (view && (view.status === 'running' || view.status === 'stopping')) {
+    // Promotion: the command keeps running under the registry, the caller gets
+    // an id it can drain with job_output and stop with job_kill.
+    return {
+      promoted: true,
+      jobId: job.id,
+      text: `[still running after ${timeoutMs}ms; moved to background job ${job.id}]\n`
+        + `Read its output with job_output (job_id="${job.id}") and stop it with job_kill.`,
+    }
+  }
+  // Settled inside the deadline: collect the ring (the registry's own cursor)
+  // and drop the record — the model never saw the id, so it must not linger.
+  let text = ''
+  try {
+    const read = registry.read(job.id, owner)
+    text = (read.chunks || []).map((c) => c.text).join('')
+    if (read.result) text = text ? text + '\n' + read.result : read.result
+  } catch { /* fall through with an empty body */ }
+  try { registry.remove(job.id, owner) } catch { /* settlement pending */ }
+  const detail = (view && view.detail) || ''
+  return { promoted: false, text: formatResult({ code: 0, signal: null, stdout: text, stderr: '' }, { timeoutMs }) + (detail ? `\n[${detail}]` : '') }
+}