dsh-remote 0.8.52 → 0.8.53

package/README.en.md

@@ -293,6 +293,10 @@ Two exceptions (0.8.52+): `.md`/`.markdown` links are **not** taken over and sta
 
 **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).
 
 **Host key changed** — `/remote forget-key` (or Settings → machine → trust again).

package/README.md

@@ -296,6 +296,28 @@ scripts/dev-run.sh --status    # 是否在运行
 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 取会话自己的
 工作区目录（远程会话就是本地镜像），插件既不能替换那个服务、也不能把核心终端重定向到 SSH。

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}]` : '') }
+}

package/lib/index.js

@@ -39,6 +39,8 @@ import { createRemoteFileReference, installFileReferenceOverlay, DEFAULT_EXCLUDE
 import { getSecret, deleteSecret, platformBackend, persistPassword } from './credential.js'
 import { syncTree, pushTree, loadSyncState, saveSyncState, pushOneFile } from './sync.js'
 import { createInstructionIndex, formatInstructionIndex } from './instructions.js'
+import { resolveExecTimeout, formatExecResult, startExecJob, execWithOptionalPromotion } from './exec-job.js'
+import { createInjectionTracker, refreshTouched, buildInstructionMessage } from './instructions-dynamic.js'
 import { searchRemote } from './search.js'
 import { installTerminalShell } from './remote-shell.js'
 import { resolveMirror, poolKey, lookupSessionCwd, encodeSegmentSafe, readSessionHeaderCwd, requestSessionHint } from './binding.js'
@@ -1007,6 +1009,26 @@ export async function apply(ctx, config) {
       appendFileSync(auditFile(), line, 'utf8')
     } catch {}
   }
+
+  /**
+   * The core background-job registry, or null when this composition has none.
+   *
+   * Issue #70: `ctx.jobs` is an OPTIONAL service — a minimal embedding, a test
+   * double, or a plugin-only harness may mount no registry at all. Resolving it
+   * lazily (rather than as an injected dependency) keeps the plugin loadable
+   * there and degrades `rw_exec` to foreground-only, which is exactly the
+   * pre-#70 behaviour instead of a hard failure at load time.
+   *
+   * @returns {object|null} the registry, or null.
+   */
+  const jobRegistry = () => {
+    try {
+      const jobs = ctx.get('jobs')
+      return jobs && typeof jobs.start === 'function' ? jobs : null
+    } catch {
+      return null
+    }
+  }
   const readAudit = (limit) => {
     try {
       const text = readFileSync(auditFile(), 'utf8')
@@ -1133,6 +1155,35 @@ export async function apply(ctx, config) {
   // and lists them in the system-prompt section below. See lib/instructions.js.
   const instructionIndex = createInstructionIndex()
 
+  // Issue #71: per-session record of which remote instruction files were
+  // already delivered, plus the sweep throttle. See the tools/result hook below.
+  const instructionTracker = createInjectionTracker()
+
+  /**
+   * The core's user-message factory, when this composition exposes one.
+   *
+   * Issue #71's design leans on the message being a NORMAL user message with a
+   * plugin-owned `source.kind` (consumers fall through unknown kinds; the
+   * core's reconcile only claims `agent-instructions`). The factory lives in
+   * `@deepseek-ai/dsh-llm`, which is not a dependency of this plugin — so it is
+   * resolved opportunistically and a minimal object of the same shape is used
+   * when it is unavailable. The two are interchangeable for every consumer
+   * that matters here (the LLM request builder reads role + content).
+   *
+   * @returns {Function|null} the factory, or null to use the built-in shape.
+   */
+  const userMessageFactory = () => {
+    try {
+      const llm = ctx.get('llm')
+      const make = llm && typeof llm.createUserMessage === 'function'
+        ? llm.createUserMessage
+        : (llm && llm.default && typeof llm.default.createUserMessage === 'function' ? llm.default.createUserMessage : null)
+      return make ? (input) => make.call(llm, input) : null
+    } catch {
+      return null
+    }
+  }
+
   // Helpers shared by session-bound tools and the machine-scoped web routes take
   // the pool explicitly (`p`), defaulting to the active-machine pool so route
   // callers — which are machine-scoped by design — stay unchanged.
@@ -2406,12 +2457,15 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_exec',
       description:
-        'Run a shell command on the remote host. Use for anything that is not reading a file (build, test, grep, etc). Output is capped. Runs in the current remote workspace by default; pass cwd to run elsewhere. pty=true helps interactive commands (sudo prompts, REPLs); env sets environment variables.',
+        'Run a shell command on the remote host. Use for anything that is not reading a file (build, test, grep, etc). Output is capped. Runs in the current remote workspace by default; pass cwd to run elsewhere. pty=true helps interactive commands (sudo prompts, REPLs); env sets environment variables. timeoutMs (1000-600000) overrides the machine-wide commandTimeoutMs for this call only. A command that outlives its timeout is MOVED TO A BACKGROUND JOB instead of being killed (pass promoteOnTimeout=false to kill it instead); run_in_background=true returns immediately with a job id. Background jobs are read with job_output and stopped with job_kill.',
       parameters: {
         command: { type: 'string', required: true, description: 'Shell command (run on the remote host)' },
         cwd: { type: 'string', description: 'Working directory for the command (default: the current remote workspace)' },
         pty: { type: 'boolean', description: 'Allocate a pseudo-terminal (interactive commands, default false)' },
         env: { type: 'object', additionalProperties: true, description: 'Extra environment variables (string values)' },
+        timeoutMs: { type: 'integer', description: 'Timeout for THIS call in milliseconds (clamped to 1000-600000; default: the commandTimeoutMs config)' },
+        run_in_background: { type: 'boolean', description: 'Return a job id immediately and let the command run in the background (read it with job_output, stop it with job_kill)' },
+        promoteOnTimeout: { type: 'boolean', description: 'When the command outlives its timeout, move it to a background job instead of killing it (default true; needs the core jobs service)' },
       },
       output: textOut,
       async execute(args, exec) {
@@ -2434,18 +2488,40 @@ export async function apply(ctx, config) {
             full = `cd ${shq(cwd)} && ${cmd}`
           }
         }
+        // Issue #70: a per-call override, clamped, and the value we report is
+        // the one we actually applied (never the config value behind an
+        // override's back).
+        const timeoutMs = resolveExecTimeout(args.timeoutMs, config.commandTimeoutMs)
+        const registry = jobRegistry()
+        const owner = exec && exec.agent ? exec.agent.id : undefined
+        const promote = registry !== null && args.promoteOnTimeout !== false
         try {
-          const res = await b.pool.exec(full, { timeoutMs: config.commandTimeoutMs, pty: !!args.pty, env: args.env })
+          if (args.run_in_background) {
+            if (!registry) {
+              throw new Error('rw_exec: run_in_background needs the DSH jobs service, which this composition does not provide')
+            }
+            // A background job needs its OWN deadline, or nothing would ever
+            // stop a runaway command. `timeoutMs` becomes that deadline here
+            // (unlike the promote path, where it only bounds the caller's wait).
+            const job = startExecJob(registry, { pool: b.pool, command: full, label: cmd, owner, jobDeadlineMs: timeoutMs, pty: args.pty, env: args.env })
+            audit('exec-background', cmd, 0, b)
+            return {
+              text: `started in the background: jobId=${job.id}\n`
+                + `Read its output with job_output (job_id="${job.id}"); stop it with job_kill.\n`
+                + `(the job is killed if it outlives ${timeoutMs}ms)`,
+            }
+          }
+          if (promote) {
+            const r = await execWithOptionalPromotion({
+              registry, pool: b.pool, command: full, label: cmd, owner, timeoutMs,
+              pty: args.pty, env: args.env, signal: exec && exec.signal, formatResult: formatExecResult,
+            })
+            audit('exec', cmd, r.promoted ? 0 : 0, b)
+            return { text: r.text }
+          }
+          const res = await b.pool.exec(full, { timeoutMs, pty: !!args.pty, env: args.env, signal: exec && exec.signal })
           audit('exec', cmd, res.code, b)
-          const parts = []
-          if (res.stdout) parts.push(res.stdout.replace(/\s+$/, ''))
-          if (res.stderr) parts.push('-- stderr --\n' + 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 ${config.commandTimeoutMs}ms]`
-          else if (res.signal === 'ABORTED') text += '\n[cancelled — the remote command was stopped]'
-          else if (res.code !== 0) text += `\n[exit code: ${res.code}]`
-          return { text }
+          return { text: formatExecResult(res, { timeoutMs }) }
         } catch (err) {
           throw new Error(friendlyMessage(err, { host: b.host, port: b.port }))
         }
@@ -2787,6 +2863,75 @@ export async function apply(ctx, config) {
     })
   }
 
+  // ── dynamic remote instruction injection (issue #71) ──────────────────────
+  // #68 delivered the STATIC half (shallow scan + mirror + prompt index). The
+  // dynamic half the core does for local sessions was still missing, because
+  // the core's incremental path is keyed on (a) the tool names read/write/edit
+  // and (b) a `file_path` argument, and it expands scopes using LOCAL paths.
+  // `rw_read_file` is named differently, takes `path`, and its argument is a
+  // REMOTE absolute path — none of the three can ever line up.
+  //
+  // So the plugin does it itself, without touching core: after any successful
+  // rw_* file touch, take the touched path's whole ancestor chain below the
+  // workspace root, stat each level's AGENTS.md / CLAUDE.md, and hand the
+  // current contents to the model as ONE user message carrying our OWN source
+  // kind. Consumers fall through unknown kinds, and the core's reconcile only
+  // claims its own `agent-instructions` kind — which is exactly why the two
+  // injection paths cannot fight over the same inbox slot.
+  //
+  // Everything here is best-effort: the hook never rejects, never blocks the
+  // tool result, and treats an offline machine as "nothing to inject".
+  if (typeof ctx.on === 'function') {
+    ctx.on('tools/result', async (result, hookContext) => {
+      try {
+        const agent = hookContext && (hookContext.agent || (result && result.agent))
+        const name = String((hookContext && hookContext.name) || (result && result.name) || '')
+        // Only the tools that actually reach a remote file. `rw_exec` is
+        // deliberately excluded: a shell command's argument is not a path we
+        // can trust, and scanning arbitrary strings would be a guess.
+        const TOUCH_TOOLS = new Set(['rw_read_file', 'rw_write_file', 'rw_edit', 'rw_list_dir'])
+        if (!TOUCH_TOOLS.has(name)) return
+        if (!agent || !agent.session || !agent.inbox) return
+        const args = (hookContext && hookContext.arguments) || (result && result.arguments) || {}
+        const rawPath = String(args.path || args.file_path || '')
+        if (!rawPath) return
+        const cwd = agent.session.header && agent.session.header.cwd
+        if (!cwd) return
+        const { remotePath, machine, mirrorDir } = resolveMirrorForLocal(String(cwd))
+        if (!remotePath || !machine) return // a LOCAL session: the core owns it
+        const touched = normalizeRemotePath(rawPath)
+        // Reading the workspace root itself adds no chain (the core's baseline
+        // already covers `<root>/AGENTS.md`), so this is the "reading a file
+        // directly in the root triggers no extra scan" boundary from the issue.
+        const sessionId = agent.id || agent.session.id || 'unscoped'
+        if (instructionTracker.throttled(sessionId)) return
+        instructionTracker.swept(sessionId)
+        const pool = poolForMachine(machine)
+        // Never let a slow/offline machine hold the tool result: the sweep runs
+        // against a short-lived SFTP surface and any failure is swallowed.
+        const sftp = await pool.sftp()
+        const { items, removed } = await refreshTouched({
+          sftp, remoteRoot: remotePath, touched, mirrorDir, tracker: instructionTracker, sessionId,
+        })
+        if (!items.length && !removed.length) return
+        const platform = pool.platform
+        const msg = buildInstructionMessage(items, removed, {
+          // Items carry an ABSOLUTE `remote` path; removed entries carry a
+          // workspace-RELATIVE rel. Prefix only the latter — always joining
+          // would double the root prefix (caught by the issue #71 live E2E).
+          display: (p) => {
+            const s = String(p)
+            const abs = s.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(s)
+            return toDisplayPath(abs ? s : joinRemotePath(remotePath, s), platform)
+          },
+          createUserMessage: userMessageFactory(),
+        })
+        if (!msg) return
+        agent.inbox.prepend('next-step', msg)
+      } catch { /* best effort — an injection failure must never break the tool */ }
+    })
+  }
+
   // ── slash commands ─────────────────────────────────────────────────────────
   const commands = ctx.get('commands')
   if (commands !== undefined) {

package/lib/instructions-dynamic.js

@@ -0,0 +1,336 @@
+// dsh-remote — dynamic remote instruction injection (issue #71).
+//
+// Issue #68 gave a remote workspace a STATIC instruction index: the workspace
+// is shallow-scanned at pick/sync time, the files are mirrored locally, and the
+// prompt lists them. What remained missing is the DYNAMIC half the core does
+// for local sessions — three gaps, all plugin-side fixable:
+//
+//   1. The mirrored copies never refreshed, so a mid-session edit to a remote
+//      AGENTS.md was invisible until a manual rw_sync.
+//   2. The core's incremental injection only recognizes read/write/edit with a
+//      `file_path` argument. `rw_read_file` is named differently AND takes
+//      `path`, so a remote file touch never registered.
+//   3. The core expands scopes from cwd to the TOUCHED path — both local. A
+//      remote absolute path (`/root/proj/x.md`) can never map onto a local
+//      mirror cwd, so even a "touch" would expand nothing.
+//
+// This module closes all three without a single line of core change:
+//   • `noteTouchedPath` turns an rw_* file touch into the FULL ancestor chain
+//     below the workspace root (the same shape core's descendantDirsBetween
+//     produces — every level, not just the deepest);
+//   • `refreshTouched` stats each level's AGENTS.md/CLAUDE.md, pulls the ones
+//     that changed, and returns the chain's current contents;
+//   • `buildInstructionMessage` renders that into ONE user message whose source
+//     is our OWN kind, so the core's `agent-instructions` state machine never
+//     confuses it for its own (that is what keeps the two paths from fighting).
+//
+// Everything here is best-effort and synchronous-safe: an offline machine must
+// never hang a tool call or a prompt assembly, so every remote step is guarded
+// and every caller is expected to treat a rejection as "no injection".
+
+import { statSync, mkdirSync, writeFileSync, utimesSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import { joinRemotePath, relPathUnder } from './paths.js'
+import { INSTRUCTION_MAX_BYTES } from './instructions.js'
+
+/** The message source kind this plugin owns. Deliberately NOT the core's
+ *  `agent-instructions`: consumers fall through unknown kinds, and the core's
+ *  reconcile only claims messages carrying its own kind. */
+export const REMOTE_INSTRUCTIONS_KIND = 'dsh-remote-instructions'
+
+/** Total byte budget for one injected batch (the core's own budget is similar). */
+export const INSTRUCTION_MESSAGE_MAX_BYTES = 16 * 1024
+
+/** Per-session throttle for the stat-and-refresh sweep, in milliseconds. */
+export const REFRESH_THROTTLE_MS = 30 * 1000
+
+const keyOf = (size, mtime) => `${size}:${Math.floor(mtime || 0)}`
+
+/**
+ * Split a remote path into the ancestor directories strictly BELOW `root`,
+ * root-excluded — the core's `ancestorChain(cwd, dir).slice(1)` shape.
+ *
+ * Reading `<root>/a/b/c.ts` yields `['a', 'a/b']`, so `a/AGENTS.md` and
+ * `a/b/AGENTS.md` are both in scope while `<root>/AGENTS.md` (the baseline
+ * layer) is not re-scanned. A path at or above the root yields `[]`.
+ *
+ * @param {string} root - the workspace root (remote absolute path).
+ * @param {string} touched - the touched remote path.
+ * @returns {string[]} workspace-relative directory prefixes, shallow → deep.
+ */
+export function descendantDirs(root, touched) {
+  const rootRel = relPathUnder(String(root || ''), String(touched || ''))
+  if (!rootRel) return []
+  const parts = rootRel.split('/').filter(Boolean)
+  // The last part is the file itself; the chain stops at its directory.
+  parts.pop()
+  const out = []
+  let cur = ''
+  for (const part of parts) {
+    cur = cur ? `${cur}/${part}` : part
+    out.push(cur)
+  }
+  return out
+}
+
+/**
+ * Which instruction files a touch puts in scope, as workspace-relative paths:
+ * each directory in the chain contributes `AGENTS.md` and `CLAUDE.md`.
+ *
+ * @param {string} root - workspace root.
+ * @param {string} touched - touched path.
+ * @param {number} depth - how many trailing chain levels to include (0 = none,
+ *   which is what "touched a file directly in the root" means).
+ * @returns {string[]} candidate relative paths.
+ */
+export function instructionCandidates(root, touched, depth = Infinity) {
+  const dirs = descendantDirs(root, touched)
+  // `depth: 0` means "no chain level" (the touched file sits directly in the
+  // root): `slice(-0)` would return the WHOLE array, so this needs its own branch.
+  const chain = depth === 0 ? [] : (Number.isFinite(depth) ? dirs.slice(-depth) : dirs)
+  const out = []
+  for (const dir of chain) {
+    out.push(`${dir}/AGENTS.md`, `${dir}/CLAUDE.md`)
+  }
+  return out
+}
+
+/**
+ * A digest of an instruction's content, used to inject a given version once.
+ * Size + mtime is not enough: a same-size edit inside one second would slip
+ * through, and a spurious re-injection costs prompt budget.
+ *
+ * @param {Buffer|string} content
+ * @returns {string}
+ */
+export function contentDigest(content) {
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(String(content ?? ''), 'utf8')
+  // A 16-char prefix is plenty for "did this text change" within one session,
+  // and keeps the tracker's maps small.
+  return createHash('sha256').update(buf).digest('hex').slice(0, 16)
+}
+
+/**
+ * Per-session injection state: which (remote path → digest) pairs have already
+ * been delivered, plus the last sweep time for throttling.
+ *
+ * @returns {object} a tracker with `shouldInject`, `markInjected`, `removed`, and `throttled`.
+ */
+export function createInjectionTracker({ throttleMs = REFRESH_THROTTLE_MS } = {}) {
+  /** sessionId → { injected: Map<relPath, digest>, lastSweep: number } */
+  const sessions = new Map()
+  const stateFor = (sessionId) => {
+    const key = String(sessionId || 'unscoped')
+    let s = sessions.get(key)
+    if (!s) { s = { injected: new Map(), lastSweep: 0 }; sessions.set(key, s) }
+    return s
+  }
+  return {
+    /** Whether a sweep may run now (the throttle gate). */
+    throttled(sessionId, now = Date.now()) {
+      const s = stateFor(sessionId)
+      return now - s.lastSweep < throttleMs
+    },
+    /** Record that a sweep happened now. */
+    swept(sessionId, now = Date.now()) {
+      stateFor(sessionId).lastSweep = now
+    },
+    /** Whether this exact content has NOT been delivered to this session yet. */
+    shouldInject(sessionId, rel, digest) {
+      return stateFor(sessionId).injected.get(rel) !== digest
+    },
+    /** Mark one file's content as delivered. */
+    markInjected(sessionId, rel, digest) {
+      stateFor(sessionId).injected.set(rel, digest)
+    },
+    /** Every rel path this session has been given, for scoped reconciliation. */
+    injectedRels(sessionId) {
+      return stateFor(sessionId).injected.keys()
+    },
+    /**
+     * Files injected before that are gone from a sweep LIMITED to `covers`.
+     *
+     * Scoping matters in both directions: a file outside the swept chain was
+     * never examined, so it must keep its record (dropping it would re-inject
+     * live rules later and, worse, could report a live rule as removed).
+     *
+     * @param {string} sessionId
+     * @param {Set<string>} present - rel paths the sweep actually found.
+     * @param {(rel: string) => boolean} covers - whether the sweep covered a rel.
+     * @returns {string[]} rel paths to report as removed.
+     */
+    removedInScope(sessionId, present, covers) {
+      const s = stateFor(sessionId)
+      const out = []
+      for (const rel of [...s.injected.keys()]) {
+        if (typeof covers === 'function' && !covers(rel)) continue
+        if (present.has(rel)) continue
+        out.push(rel)
+        s.injected.delete(rel)
+      }
+      return out
+    },
+    /**
+     * Files that were injected before but no longer exist remotely — the model
+     * must be told, or it keeps following rules that were deleted.
+     * @returns {string[]} rel paths to report as removed.
+     */
+    removed(sessionId, stillPresent) {
+      return this.removedInScope(sessionId, stillPresent, null)
+    },
+    /** Forget a session entirely (its cwd changed, or it went away). */
+    reset(sessionId) {
+      sessions.delete(String(sessionId || 'unscoped'))
+    },
+    /** Every session currently tracked (diagnostics/tests). */
+    sessions() {
+      return [...sessions.keys()]
+    },
+  }
+}
+
+/**
+ * Fetch the CURRENT content of one instruction candidate from the remote and
+ * mirror it locally, three-way safe (a local edit is never clobbered).
+ *
+ * Returns null when the file does not exist remotely — that is a normal answer,
+ * not an error, since most directories carry no instruction file.
+ *
+ * @param {object} sftp - promisified sftp surface.
+ * @param {string} remoteRoot - workspace root.
+ * @param {string} rel - workspace-relative candidate path.
+ * @param {string} mirrorDir - local mirror root.
+ * @returns {Promise<{rel: string, remote: string, content: string, digest: string, mirrored: boolean}|null>}
+ */
+export async function fetchInstruction(sftp, remoteRoot, rel, mirrorDir) {
+  const remote = joinRemotePath(remoteRoot, rel)
+  let st
+  try { st = await sftp.stat(remote) } catch { return null }
+  if (!st || (typeof st.isDirectory === 'function' && st.isDirectory())) return null
+  const size = typeof st.size === 'number' ? st.size : 0
+  if (size > INSTRUCTION_MAX_BYTES) {
+    // Too large to inject whole: report the file, not its text.
+    return { rel, remote, content: '', digest: `oversize:${size}`, mirrored: false, oversizeBytes: size }
+  }
+  let buf
+  try { buf = await sftp.readFile(remote) } catch { return null }
+  const digest = contentDigest(buf)
+  let mirrored = false
+  if (mirrorDir) {
+    try {
+      const lp = path.join(mirrorDir, ...String(rel).split('/'))
+      let same = false
+      try {
+        const lst = statSync(lp)
+        same = lst.size === size && keyOf(lst.size, lst.mtimeMs / 1000) === keyOf(size, st.mtime)
+      } catch { same = false }
+      if (!same) {
+        mkdirSync(path.dirname(lp), { recursive: true })
+        writeFileSync(lp, buf)
+        try { utimesSync(lp, new Date((st.mtime || 0) * 1000), new Date((st.mtime || 0) * 1000)) } catch { /* cosmetic */ }
+      }
+      mirrored = true
+    } catch { /* a mirror failure must not lose the instruction itself */ }
+  }
+  return { rel, remote, content: buf.toString('utf8'), digest, mirrored }
+}
+
+/**
+ * Sweep the ancestor chain of a touched path and return the instructions that
+ * should enter the context now.
+ *
+ * @param {object} arg
+ * @param {object} arg.sftp
+ * @param {string} arg.remoteRoot - workspace root.
+ * @param {string} arg.touched - the touched remote path.
+ * @param {string} arg.mirrorDir - local mirror.
+ * @param {object} arg.tracker - from {@link createInjectionTracker}.
+ * @param {string} arg.sessionId
+ * @param {number} [arg.depth] - chain depth to consider (default: whole chain).
+ * @returns {Promise<{items: Array, removed: string[]}>} new/changed files and removals.
+ */
+export async function refreshTouched({ sftp, remoteRoot, touched, mirrorDir, tracker, sessionId, depth }) {
+  const candidates = instructionCandidates(remoteRoot, touched, depth)
+  if (!candidates.length) return { items: [], removed: [] }
+  const found = []
+  const present = new Set()
+  for (const rel of candidates) {
+    const got = await fetchInstruction(sftp, remoteRoot, rel, mirrorDir)
+    if (!got) continue
+    found.push(got)
+    present.add(got.rel)
+  }
+  const items = found.filter((f) => tracker.shouldInject(sessionId, f.rel, f.digest))
+  for (const f of items) tracker.markInjected(sessionId, f.rel, f.digest)
+  // Removal notices must be scoped to the directories THIS touch covers — both
+  // directions matter:
+  //   • a file that no longer exists anywhere in the covered chain is gone;
+  //   • a file outside the covered chain was simply never looked at, so its
+  //     absence from `present` says nothing (and must not delete its record,
+  //     or the model would be told a live rule vanished).
+  const dirs = descendantDirs(remoteRoot, touched)
+  if (!dirs.length) return { items, removed: [] }
+  const prefixes = dirs.map((d) => d + '/')
+  const covers = (rel) => prefixes.includes(rel.slice(0, rel.lastIndexOf('/') + 1))
+  // Only files INSIDE the covered chain can be judged by this sweep: a record
+  // for some other subtree was simply not examined, so its absence from
+  // `present` means nothing there.
+  const removed = tracker.removedInScope(sessionId, present, covers)
+  return { items, removed }
+}
+
+/**
+ * Render the injection batch into ONE user message.
+ *
+ * The shape mirrors what the core produces for its own incremental batches —
+ * a system-reminder-framed body with per-file sections — so the model reads the
+ * two identically while the SOURCE kind keeps them distinguishable.
+ *
+ * @param {Array} items - from {@link refreshTouched}.
+ * @param {string[]} removed - rel paths that no longer exist.
+ * @param {object} [opts]
+ * @param {number} [opts.maxBytes]
+ * @param {(p: string) => string} [opts.display] - path formatter for sections.
+ * @param {(text: string, source: object) => object} [opts.createUserMessage] -
+ *   the core message factory when available.
+ * @returns {object|null} a user message, or null when there is nothing to say.
+ */
+export function buildInstructionMessage(items, removed, opts = {}) {
+  const maxBytes = Number(opts.maxBytes) || INSTRUCTION_MESSAGE_MAX_BYTES
+  const display = typeof opts.display === 'function' ? opts.display : (p) => p
+  const factory = typeof opts.createUserMessage === 'function' ? opts.createUserMessage : null
+  if ((!items || !items.length) && (!removed || !removed.length)) return null
+  const blocks = []
+  let used = 0
+  const sent = []
+  const truncated = []
+  for (const item of items || []) {
+    const head = item.oversizeBytes
+      ? `### ${display(item.remote)}\n(too large to inject: ${item.oversizeBytes} bytes — read it with rw_read_file if you need its rules)`
+      : `### ${display(item.remote)}\n${item.content}`
+    const bytes = Buffer.byteLength(head, 'utf8')
+    if (used + bytes > maxBytes) { truncated.push(display(item.remote)); continue }
+    used += bytes
+    blocks.push(head)
+    sent.push(item.rel)
+  }
+  if (removed && removed.length) {
+    const line = `Removed on the remote host (no longer in effect): ${removed.map((r) => display(r)).join(', ')}`
+    if (used + Buffer.byteLength(line, 'utf8') <= maxBytes) blocks.push(line)
+  }
+  if (truncated.length) {
+    blocks.push(`Workspace instruction budget ${maxBytes} bytes: truncated ${truncated.join(', ')}`)
+  }
+  if (!blocks.length) return null
+  const text = [
+    '<system-reminder>',
+    'Remote workspace instructions for the directories you just touched. These are the CURRENT contents from the remote host, delivered because you accessed files under them.',
+    '',
+    blocks.join('\n\n'),
+    '</system-reminder>',
+  ].join('\n')
+  const source = { kind: REMOTE_INSTRUCTIONS_KIND, form: 'instructions', changes: sent.map((rel) => ({ path: rel, change: 'changed' })) }
+  const content = [{ type: 'text', text }]
+  return factory ? factory({ content, source }) : { role: 'user', content, source }
+}

package/lib/pool.js

@@ -520,6 +520,12 @@ export class SshPool {
   _execRaw(command, opts, stdinWriter) {
     const timeoutMs = (opts && opts.timeoutMs) || this.config.commandTimeoutMs
     const signal = opts && opts.signal
+    // Streaming tap for background jobs (issue #70): a promoted command's value
+    // is its LIVE output, which the job ring must receive as it arrives rather
+    // than only as a return value the caller already abandoned. Called with
+    // ('stdout'|'stderr', chunk); failures inside the tap must never break the
+    // command itself, so every call site guards it.
+    const onData = opts && typeof opts.onData === 'function' ? opts.onData : null
     return this.connect().then(
       (client) =>
         new Promise((resolve, reject) => {
@@ -614,9 +620,11 @@ export class SshPool {
               })
               stream.on('data', (d) => {
                 if (stdout.length < hardCap) stdout += d
+                if (onData) { try { onData('stdout', d) } catch { /* tap errors are not command errors */ } }
               })
               stream.stderr.on('data', (d) => {
                 if (stderr.length < hardCap) stderr += d
+                if (onData) { try { onData('stderr', d) } catch { /* tap errors are not command errors */ } }
               })
               stream.on('error', (e) => {
                 if (settled) return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote",
-  "version": "0.8.52",
+  "version": "0.8.53",
   "description": "Remote-work assistant for DeepSeek Harness: connect SSH (password/key/agent/keyboard-interactive/proxy jump), pick a remote workspace, operate on it with 22 rw_* tools (incl. rw_edit/rw_stat/rw_mkdir/rw_remove/rw_move/rw_forward), conflict-aware mirror sync, one-click remote dsh deploy + web UI attach, port forwarding, optional side-bar remote file editing, audit log, keychain passwords.",
   "license": "MIT",
   "author": "flymysql <flyphp@outlook.com>",