dsh-remote 0.8.51 → 0.8.53

package/lib/index.js

@@ -38,6 +38,9 @@ import { importableEntries, sshConfigPath, readSshConfigText, resolveMachineSshC
 import { createRemoteFileReference, installFileReferenceOverlay, DEFAULT_EXCLUDED_DIRECTORIES } from './file-reference.js'
 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'
@@ -1006,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')
@@ -1124,6 +1147,43 @@ export async function apply(ctx, config) {
     autoPushWatchers.clear()
   }, 'dsh-remote.autopush')
 
+  // ── remote instruction-file index (issue #68) ────────────────────────────
+  // The core AGENTS.md loader only sees the LOCAL mirror, so a remote repo's
+  // instruction files never reach the model's context. This index shallow-
+  // scans a bound workspace (root + ≤2 levels, AGENTS.md / CLAUDE.md only),
+  // mirrors the finds into the local mirror (where the core loader looks),
+  // 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.
@@ -1225,6 +1285,106 @@ export async function apply(ctx, config) {
     }
     return out
   }
+
+  /**
+   * Rebind every mirror recorded for one machine identity to a NEW identity
+   * (issue #67): when a machine's IP/user/port changes, its workspaces must
+   * follow instead of being recreated. The mirror's `.dsh-remote-meta.json` is
+   * the authoritative binding — session routing (bindingFor), pool keying
+   * (poolForMachine) and the sidebar badges all read identity FROM THE META,
+   * not from the directory name — so rewriting the meta re-points every live
+   * session at the new address while the local mirror content stays put.
+   *
+   * The host directory itself is deliberately NOT renamed: live sessions hold
+   * cwd paths inside it, and a rename would dangle them into "session is
+   * LOCAL" refusals (on Windows the rename usually fails outright while a
+   * shell sits inside). The directory name is a display label only; a stale
+   * label after a rebind is the documented cost of keeping sessions alive.
+   *
+   * Matching covers both machine kinds: an ALIAS machine's mirrors are found
+   * through the recorded `alias` (their meta host is the resolved address at
+   * creation time), a literal machine's through host+port+username.
+   *
+   * @param {object} prev - the machine record BEFORE the identity change.
+   * @param {object} next - the machine record AFTER it.
+   * @returns {number} how many mirrors were rebound.
+   */
+  const rebindMirrors = (prev, next) => {
+    if (!prev || !next) return 0
+    const prevAlias = aliasOf(prev)
+    const prevId = identityOf(prev)
+    const prevRaw = { host: String(prev.host || ''), port: Number(prev.port) || 22, username: String(prev.username || '') }
+    const nextAlias = aliasOf(next)
+    const nextEff = withSshConfig(next) || next
+    const nextId = {
+      host: String(nextEff.host || next.host || ''),
+      port: Number(nextEff.port || next.port) || 22,
+      username: String(nextEff.username || next.username || ''),
+    }
+    const nextRaw = { host: String(next.host || ''), port: Number(next.port) || 22, username: String(next.username || '') }
+    const sameIdentity = (a, b) => a.host === b.host && a.port === b.port && a.username === b.username
+    if (!prevAlias && sameIdentity(prevId, nextId) && sameIdentity(prevRaw, nextRaw)) return 0
+    if (prevAlias && prevAlias === nextAlias) return 0
+    const root = remoteWorkspacesRoot()
+    let rebound = 0
+    let hostDirs = []
+    try { hostDirs = readdirSync(root) } catch { return 0 }
+    for (const hostDir of hostDirs) {
+      const hostPath = path.join(root, hostDir)
+      if (!statSync(hostPath, { throwIfNoEntry: false })?.isDirectory?.()) continue
+      let entries = []
+      try { entries = readdirSync(hostPath) } catch { continue }
+      for (const entry of entries) {
+        const metaPath = path.join(hostPath, entry, '.dsh-remote-meta.json')
+        let meta = null
+        try { meta = JSON.parse(readFileSync(metaPath, 'utf8')) } catch { continue }
+        if (!meta || !meta.host) continue
+        const byAlias = prevAlias && String(meta.alias || '') === prevAlias
+        // A meta records the RESOLVED identity at pick time, but that identity
+        // can also have been written raw — match on either form of the old
+        // identity so a rebind still finds mirrors recorded before a later
+        // ssh-config resolution rewrote what "this machine" meant.
+        const metaId = { host: String(meta.host), port: Number(meta.port) || 22, username: String(meta.username || '') }
+        const byIdentity = sameIdentity(metaId, prevId) || sameIdentity(metaId, prevRaw)
+        if (!byAlias && !byIdentity) continue
+        const updated = { ...meta }
+        if (nextAlias) {
+          // Alias machine: the recorded alias is what future resolution keys
+          // on; the resolved address refreshes only when it actually resolved
+          // (an unmatched alias keeps the old literal values rather than
+          // stamping the alias NAME into the address fields).
+          updated.alias = nextAlias
+          if (nextEff.sshConfigMatched || nextEff.sshAlias) {
+            updated.host = nextId.host
+            updated.port = nextId.port
+            updated.username = nextId.username
+          }
+        } else {
+          delete updated.alias
+          updated.host = nextRaw.host
+          updated.port = nextRaw.port
+          updated.username = nextRaw.username
+        }
+        updated.reboundAt = new Date().toISOString()
+        try {
+          writeFileSync(metaPath, JSON.stringify(updated, null, 2))
+          rebound++
+        } catch { /* leave that mirror as-is */ }
+      }
+    }
+    if (rebound) {
+      // The old identity's pooled connection dials an address the user just
+      // abandoned: drop it so nothing keeps a dead SSH session warm. The new
+      // identity gets its pool lazily on the next tool call.
+      const stale = machinePools.get(poolKey(prevId))
+      if (stale) {
+        machinePools.delete(poolKey(prevId))
+        try { stale.close() } catch { /* already gone */ }
+      }
+    }
+    return rebound
+  }
+
   if (config.autoPush && wsPath()) {
     startAutoPush(mirrorDirFor(wsPath(), config.host, config.username, config.port))
   }
@@ -1614,10 +1774,10 @@ export async function apply(ctx, config) {
     defineTool({
       name: 'rw_connect',
       description:
-        'Connect SSH to a remote host for remote workspace work. Two ways (issue #48): (1) pass machineId to connect with a machine ALREADY SAVED in the registry (list them with rw_machines) — every stored setting applies: password/keychain password, privateKeyPath + passphrase, useAgent, keyboardInteractive, proxy, hostKeyMode, backend, and ~/.ssh/config aliases; or (2) pass host plus any of username/port/password/privateKeyPath/passphrase/useAgent/keyboardInteractive/hostKeyMode/backend/name. Defaults to saving the machine to the registry (save=false keeps it as a temporary connection). Once connected, call rw_pick_workspace to pick the workspace directory this session should work in. With useSshConfig=true, `host` is an ALIAS from ~/.ssh/config and every value (HostName/user/port/IdentityFile/ProxyJump) is read from that file at connect time. For a host that only accepts GSSAPI/Kerberos (issue #51), pass backend="openssh" (with useSshConfig=true) so the local ssh — which holds your kinit ticket — performs the login. A failed connection is reported as an error message — it never takes the plugin down.',
+        'Connect SSH to a remote host for remote workspace work. Two ways (issue #48): (1) pass machineId to connect with a machine ALREADY SAVED in the registry (list them with rw_machines) — every stored setting applies: password/keychain password, privateKeyPath + passphrase, useAgent, keyboardInteractive, proxy, hostKeyMode, backend, and ~/.ssh/config aliases; or (2) pass host plus any of username/port/password/privateKeyPath/passphrase/useAgent/keyboardInteractive/hostKeyMode/backend/name. Defaults to saving the machine to the registry (save=false keeps it as a temporary connection). Once connected, call rw_pick_workspace to pick the workspace directory this session should work in. With useSshConfig=true, `host` is an ALIAS from ~/.ssh/config and every value (HostName/user/port/IdentityFile/ProxyJump) is read from that file at connect time. For a host that only accepts GSSAPI/Kerberos (issue #51), pass backend="openssh" (with useSshConfig=true) so the local ssh — which holds your kinit ticket — performs the login. A failed connection is reported as an error message — it never takes the plugin down. Rebinding (issue #67): pass machineId TOGETHER with a new host/username/port to update that saved machine in place — every workspace mirror bound to its old address is re-pointed (local content kept, no re-sync) instead of forcing new workspaces.',
       parameters: {
         host: { type: 'string', description: 'Remote host IP or hostname (or a ~/.ssh/config alias with useSshConfig=true). Required unless machineId is given.' },
-        machineId: { type: 'string', description: 'Connect with a saved machine from the registry (see rw_machines): all its stored settings apply and it becomes the current machine. host/other fields are not needed.' },
+        machineId: { type: 'string', description: 'Connect with a saved machine from the registry (see rw_machines): all its stored settings apply and it becomes the current machine. host/other fields are not needed — EXCEPT for rebinding (issue #67): combine machineId with a new host/username/port to update the machine in place and re-point its existing workspace mirrors.' },
         username: { type: 'string', description: 'SSH user (default from config or root)' },
         port: { type: 'integer', description: 'SSH port (default 22)' },
         password: { type: 'string', description: 'SSH password (prefer SSH key when possible)' },
@@ -1634,6 +1794,9 @@ export async function apply(ctx, config) {
       },
       output: textOut,
       async execute(args) {
+        // Issue #67: set by the machineId+overrides path, prepended to the
+        // success line so the rebind is visible in the tool result.
+        let reboundNote = ''
         const mid = String(args.machineId || '').trim()
         if (mid) {
           // Connect with an ALREADY SAVED machine (issue #48): the registry
@@ -1641,6 +1804,25 @@ export async function apply(ctx, config) {
           // keychain-backed passwords, stored passphrases, proxies, aliases.
           const i = machineIndex(mid)
           if (i < 0) throw new Error(`rw_connect: no saved machine "${mid}" — list saved machines with rw_machines`)
+          // Issue #67: passing host/username/port ALONGSIDE a machineId rebinds
+          // the saved machine in place — the fix for "the IP changed, do not
+          // make me recreate every workspace". The record keeps its id (and
+          // every credential), and each mirror bound to the old identity is
+          // re-pointed so live sessions keep working against the new address.
+          const prev = machines[i]
+          const overrides = {}
+          if (args.host !== undefined && String(args.host).trim()) overrides.host = String(args.host).trim()
+          if (args.username !== undefined && String(args.username).trim()) overrides.username = String(args.username).trim()
+          if (args.port !== undefined && Number(args.port)) overrides.port = Number(args.port)
+          let rebound = 0
+          if (Object.keys(overrides).length) {
+            const next = { ...prev, ...overrides }
+            try { rebound = rebindMirrors(prev, next) } catch { /* best effort */ }
+            machines[i] = next
+          }
+          if (rebound) {
+            reboundNote = `Rebound ${rebound} workspace mirror(s) from ${prev.username}@${prev.host}:${prev.port} to the new address (local content kept — no re-sync needed).\n`
+          }
           store.currentId = machines[i].id
           ephemeral = null
           saveMachines(machines, store.currentId)
@@ -1749,7 +1931,7 @@ export async function apply(ctx, config) {
           const via = active && active.sshAlias
             ? `\n(ssh-config alias "${active.sshAlias}" → ${effUser}@${effHost}:${effPort}` + (active.sshConfigWarnings && active.sshConfigWarnings.length ? `; ${active.sshConfigWarnings.join(' ')}` : '') + ')'
             : ''
-          return { text: `Connected to ${effHost} as ${effUser}.${via}\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
+          return { text: `${reboundNote}Connected to ${effHost} as ${effUser}.${via}\n\npick a workspace with rw_pick_workspace (path=<abs>).` }
         } catch (err) {
           throw new Error(friendlyMessage(err, { host: effHost, port: effPort }))
         }
@@ -1825,6 +2007,12 @@ export async function apply(ctx, config) {
         if (!b.bound) persistWorkspace(p)
         const local = ensureMirror(p, b.host, b.username, b.port, { alias: b.alias || "" })
         startAutoPush(local)
+        // Issue #68: discover the workspace's AGENTS.md / CLAUDE.md NOW — the
+        // first prompt assembly can come before any rw_sync, and the mirror
+        // copy must already be in place for the core instruction loader to
+        // pick it up. Awaited (the scan is a handful of shallow readdirs) but
+        // fully best-effort: a scan failure never fails the pick.
+        try { await instructionIndex.refresh({ pool: b.pool, ws: p, mirrorDir: local, force: true }) } catch { /* best effort */ }
         // The closing hint depends on where THIS session stands (issue #63):
         // in a LOCAL session "Run rw_sync" is a dead instruction — rw_sync
         // refuses a local session — so say the mirror must be OPENED first.
@@ -1878,11 +2066,21 @@ export async function apply(ctx, config) {
           }
           return { text }
         }
+        // Issue #68: a real sync can pull in (or obsolete) instruction files —
+        // refresh the prompt index afterwards. Kept inside the task body so a
+        // background sync refreshes when IT finishes, not when it is queued.
+        const runSyncAndIndex = async () => {
+          const r = await runSync()
+          if (!args.dryRun) {
+            try { await instructionIndex.refresh({ pool: b.pool, ws: p, mirrorDir: local, force: true }) } catch { /* best effort */ }
+          }
+          return r
+        }
         if (args.async) {
-          const t = tasks.start('sync', `sync ${p}`, runSync)
+          const t = tasks.start('sync', `sync ${p}`, runSyncAndIndex)
           return { text: `sync started in background: taskId=${t.id} (GET /dsh-remote/task?id=${t.id} for progress)` }
         }
-        return runSync()
+        return runSyncAndIndex()
       },
     }),
 
@@ -2137,7 +2335,26 @@ export async function apply(ctx, config) {
         if (st1.size !== st0.size || st1.mtime !== st0.mtime) {
           throw new Error(`rw_edit: ${p} changed on the remote while editing (conflict) — re-read and retry`)
         }
-        await sftp.writeFile(p, encodeText(out, args.encoding || config.encoding))
+        // Atomic write: stage to a temp file and rename over the target so a
+        // mid-write failure cannot truncate the original (issue #65). Same
+        // directory keeps the rename on one filesystem.
+        const tmpPath = `${p}.dsh-remote-edit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.tmp`
+        try {
+          await sftp.writeFile(tmpPath, encodeText(out, args.encoding || config.encoding))
+          // renameOverwrite, not rename: the target EXISTS by definition here,
+          // and plain SSH_FXP_RENAME refuses to replace it (issue #65).
+          await sftp.renameOverwrite(tmpPath, p)
+          // The rename swaps in a FRESH inode, so the original permission bits
+          // (an executable script's +x, a 0600 secret) would silently reset to
+          // the umask default. Restore them; a chmod failure must not fail the
+          // edit itself — the content is already safely in place.
+          if (st0 && typeof st0.mode === 'number') {
+            try { await sftp.setstat(p, { mode: st0.mode & 0o7777 }) } catch { /* best effort */ }
+          }
+        } catch (err) {
+          try { await sftp.unlink(tmpPath) } catch { /* best effort */ }
+          throw err
+        }
         audit('edit', `edit ${p} (${n} occurrence(s))`, 0, b)
         return { ok: true, bytes: Buffer.byteLength(out), text: `edited ${p}: replaced ${n} occurrence(s)` }
       },
@@ -2240,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) {
@@ -2268,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 }))
         }
@@ -2549,7 +2791,7 @@ export async function apply(ctx, config) {
       const session = agent && agent.session
       const cwd = session && session.header && session.header.cwd
       if (!cwd) return '' // no session cwd → nothing to map → stay quiet
-      const { remotePath, machine } = resolveMirrorForLocal(cwd)
+      const { remotePath, machine, mirrorDir } = resolveMirrorForLocal(cwd)
       if (!remotePath) return '' // this session is NOT a remote session (issue #13)
       // Name the machine the MIRROR records, not the active one: pairing this
       // session's remote path with whichever machine happens to be active
@@ -2562,6 +2804,17 @@ export async function apply(ctx, config) {
       const fwd = forwards.list().filter((f) => f.active).map((f) => `${f.direction}:127.0.0.1:${f.listenPort}→${f.targetHost}:${f.targetPort}`)
       let extra = ''
       if (fwd.length) extra = `\nActive port forwards: ${fwd.join(', ')}`
+      // Issue #68: surface the workspace's AGENTS.md / CLAUDE.md. The scan is
+      // lazy (fire-and-forget on first assembly; negative-cached on failure),
+      // so the index appears from the NEXT assembly once known — rw_pick_workspace
+      // scans eagerly, so a picked workspace normally has it from the start.
+      if (machine && mirrorDir) {
+        instructionIndex.note({ pool: poolForMachine(machine), ws: remotePath, mirrorDir })
+        const instr = instructionIndex.get(mirrorDir)
+        if (instr && instr.files && instr.files.length) {
+          extra += `\n${formatInstructionIndex(instr.files, (p) => toDisplayPath(p, platform))}`
+        }
+      }
       // Issue #39: `@` mentions are resolved from the REMOTE tree by
       // lib/file-reference.js, so the model must know they are remote-relative
       // and that the built-in read tool sees only the local mirror.
@@ -2610,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) {
@@ -3193,6 +3515,14 @@ export async function apply(ctx, config) {
               // alone, so a fresh registry stays "no choice yet" (not an
               // explicit none) and a previously-cleared registry stays cleared.
               saveMachines(machines, store.currentId, false)
+              // Issue #67: an EDITED connection identity (host/user/port) must
+              // carry the machine's existing workspaces over — without this the
+              // mirrors stayed bound to the old address and the user had to
+              // create (and re-sync) a brand-new workspace for the new IP.
+              let reboundMirrors = 0
+              if (i >= 0 && prev) {
+                try { reboundMirrors = rebindMirrors(prev, rec) } catch { /* best effort */ }
+              }
               // Issue #50: host/user/port/key have ONE home — ~/.ssh/config.
               // Saving a literal machine upserts a marker-tagged Host block,
               // so the file and the registry can never drift; the record's
@@ -3234,6 +3564,7 @@ export async function apply(ctx, config) {
                 machine: sanitizeMachine(rec),
                 machines: machinesForClient(),
                 currentId: store.currentId,
+                ...(reboundMirrors ? { reboundMirrors } : {}),
                 ...(warning ? { warning, warningDetail } : {}),
                 ...(sshConfigWarning ? { sshConfigWarning } : {}),
               })