dsh-remote 0.8.51 → 0.8.53

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/instructions.js

@@ -0,0 +1,288 @@
+// dsh-remote — remote instruction-file index (issue #68).
+//
+// The core instruction loader (@deepseek-ai/dsh-agent-instructions) discovers
+// AGENTS.md through the LOCAL filesystem only: from two user-global roots plus
+// the projectRoot→cwd ancestor chain. A remote session's cwd is the local
+// MIRROR of the remote workspace, and that mirror stays empty until rw_sync —
+// so a 20 KB AGENTS.md that governs the remote repo never enters the model's
+// context, while the same file is auto-injected in a local session. File
+// ACCESS was never the problem (rw_read_file reads it fine); what is missing
+// is the model knowing it should.
+//
+// This module closes the gap on the plugin side, along the two cheapest axes
+// the issue lists (the third — a remote ctx.fs provider — belongs to core):
+//
+//   1. INDEX in the system prompt: a shallow scan of the remote workspace
+//      (root + at most two directory levels down, AGENTS.md / CLAUDE.md only)
+//      is rendered into the dsh-remote prompt section as a path list with
+//      headings, telling every new session the files exist and to read them
+//      with rw_read_file before editing that tree. This is an INDEX, not a
+//      second injection pipeline — the full text stays out of the prompt and
+//      out of any parallel baseline, exactly as the issue demands.
+//   2. MIRROR the found files into the local mirror at their relative paths
+//      (three-way safe — a local edit is never clobbered, see below). A
+//      root-level AGENTS.md then sits exactly where the CORE loader looks in
+//      a local session, so the normal baseline/incremental machinery picks it
+//      up unchanged; no plugin-side injection logic runs in parallel with it.
+//
+// Deliberate non-goals (the issue's "请不要做"):
+//   - NO unbounded recursion of the remote root (multi-project roots like
+//     /root would scan forever): the walk is depth- and count-capped.
+//   - NO full-text injection from the plugin.
+
+import { existsSync, mkdirSync, statSync, writeFileSync, utimesSync } from 'node:fs'
+import path from 'node:path'
+import { joinRemotePath, relPathUnder } from './paths.js'
+import { loadSyncState, saveSyncState } from './sync.js'
+
+/** File names treated as agent instruction files (compared case-insensitively;
+ *  the mirrored copy keeps the remote's exact casing). */
+export const INSTRUCTION_NAMES = ['agents.md', 'claude.md']
+
+/** An instruction file bigger than this is indexed (path + note) but not read. */
+export const INSTRUCTION_MAX_BYTES = 256 * 1024
+
+/** Caps that keep the shallow scan shallow. */
+export const INSTRUCTION_MAX_FILES = 20
+export const INSTRUCTION_MAX_DIRS = 60
+export const INSTRUCTION_MAX_DEPTH = 2 // 0 = workspace root, 1 = sub/, 2 = sub/sub/
+
+/** Directories that never contain a project's governing instructions. */
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.svn', '.hg', 'dist', 'build', 'out',
+  '.next', '.nuxt', '.cache', '.turbo', 'coverage', 'target', 'vendor',
+])
+
+export const isInstructionName = (name) => INSTRUCTION_NAMES.includes(String(name || '').toLowerCase())
+
+/** Pull the first Markdown headings out of an instruction file, for the index. */
+export function extractHeadings(text, max = 8) {
+  const out = []
+  for (const line of String(text || '').split('\n')) {
+    const m = /^#{1,3}\s+(.+?)\s*#*\s*$/.exec(line)
+    if (!m) continue
+    out.push(m[1].slice(0, 60))
+    if (out.length >= max) break
+  }
+  return out
+}
+
+/**
+ * Shallow-scan a remote workspace for instruction files: the root directory
+ * plus up to INSTRUCTION_MAX_DEPTH levels of subdirectories, matching
+ * AGENTS.md / CLAUDE.md basenames. Bounded by INSTRUCTION_MAX_DIRS readdirs
+ * and INSTRUCTION_MAX_FILES files; anything past the caps is silently
+ * skipped (the index is a hint, not an inventory).
+ *
+ * @param {object} sftp - the promisified sftp surface (readdir/stat/readFile).
+ * @param {string} remoteRoot - absolute remote workspace path (normalized).
+ * @returns {Promise<Array<{rel: string, remote: string, size: number, mtime: number, content: Buffer|null, headings: string[]}>>}
+ *   `content`/`headings` are null/empty for files over INSTRUCTION_MAX_BYTES.
+ */
+export async function scanInstructionFiles(sftp, remoteRoot, opts = {}) {
+  const maxDepth = Math.max(0, Math.min(Number(opts.maxDepth ?? INSTRUCTION_MAX_DEPTH) || 0, 4))
+  const maxDirs = Math.max(1, Number(opts.maxDirs ?? INSTRUCTION_MAX_DIRS) || INSTRUCTION_MAX_DIRS)
+  const maxFiles = Math.max(1, Number(opts.maxFiles ?? INSTRUCTION_MAX_FILES) || INSTRUCTION_MAX_FILES)
+  const files = []
+  // Breadth-first so a wide root cannot push the walk deep before the shallow
+  // (more commonly governing) files are seen.
+  const queue = [{ dir: remoteRoot, depth: 0 }]
+  let dirsScanned = 0
+  while (queue.length && files.length < maxFiles && dirsScanned < maxDirs) {
+    const { dir, depth } = queue.shift()
+    dirsScanned++
+    let entries = []
+    try { entries = (await sftp.readdir(dir)) || [] } catch { continue }
+    for (const e of entries) {
+      const name = String(e.filename || '')
+      if (!name || name === '.' || name === '..' || name.startsWith('.')) {
+        // Hidden entries are skipped wholesale EXCEPT the names themselves
+        // never start with a dot, so nothing is lost.
+        continue
+      }
+      const isDir = !!(e.attrs && typeof e.attrs.isDirectory === 'function' && e.attrs.isDirectory())
+      const isLink = !!(e.attrs && typeof e.attrs.isSymbolicLink === 'function' && e.attrs.isSymbolicLink())
+      if (isDir) {
+        // Symlinked dirs are not followed: the walk stays inside the workspace
+        // tree and cannot loop through a link back to an ancestor.
+        if (isLink) continue
+        if (depth < maxDepth && !SKIP_DIRS.has(name.toLowerCase()) && queue.length + dirsScanned < maxDirs) {
+          queue.push({ dir: joinRemotePath(dir, name), depth: depth + 1 })
+        }
+        continue
+      }
+      if (!isInstructionName(name)) continue
+      const remote = joinRemotePath(dir, name)
+      const rel = relPathUnder(remoteRoot, remote) || name
+      let st = null
+      try { st = await sftp.stat(remote) } catch { continue }
+      const size = st && typeof st.size === 'number' ? st.size : 0
+      const mtime = st && typeof st.mtime === 'number' ? st.mtime : 0
+      let content = null
+      let headings = []
+      if (size <= INSTRUCTION_MAX_BYTES) {
+        try {
+          content = await sftp.readFile(remote)
+          headings = extractHeadings(content.toString('utf8'))
+        } catch { content = null }
+      }
+      files.push({ rel, remote, size, mtime, content, headings })
+      if (files.length >= maxFiles) break
+    }
+  }
+  return files
+}
+
+// The three-way keys mirror lib/sync.js exactly (size + whole-second mtime):
+// a file this module places into the mirror must be indistinguishable from
+// one rw_sync pulled, or the next sync would report a phantom conflict.
+const keyOf = (size, mtime) => `${size}:${Math.floor(mtime || 0)}`
+const localKeyOf = (st) => (st ? keyOf(st.size, st.mtimeMs / 1000) : null)
+
+/**
+ * Write scanned instruction files into the local mirror at their workspace-
+ * relative paths, three-way safe against `.dsh-remote-sync-state.json`:
+ *
+ *   - local missing                        → write (+ align mtime, record state)
+ *   - local identical to remote            → keep (record state if absent)
+ *   - remote changed, local untouched (L==S) → write (a plain pull)
+ *   - local edited (L!=S), remote unchanged → SKIP — a local edit is never
+ *     clobbered; rw_sync surfaces it as a conflict like any other file
+ *   - both changed / unknown local content → SKIP (rw_sync arbitrates)
+ *
+ * @returns {{written: string[], present: Set<string>}} rel paths written now,
+ *   and every rel that exists locally afterwards (for the index's "mirrored"
+ *   badge).
+ */
+export function syncInstructionsToMirror(files, mirrorDir) {
+  const written = []
+  const present = new Set()
+  if (!mirrorDir || !Array.isArray(files) || !files.length) return { written, present }
+  const state = loadSyncState(mirrorDir)
+  let stateDirty = false
+  for (const f of files) {
+    if (!f || !f.rel || !f.content) continue
+    const lp = path.join(mirrorDir, ...String(f.rel).split('/'))
+    const rk = keyOf(f.size, f.mtime)
+    const sk = state[f.rel] ? keyOf(state[f.rel].size, state[f.rel].mtime) : null
+    let lk = null
+    try { lk = existsSync(lp) ? localKeyOf(statSync(lp)) : null } catch { lk = null }
+    if (lk === rk) {
+      // Identical bytes in place already (same size AND mtime second) — only
+      // make sure the snapshot knows about it.
+      present.add(f.rel)
+      if (!sk) { state[f.rel] = { size: f.size, mtime: f.mtime }; stateDirty = true }
+      continue
+    }
+    const canWrite = lk === null || (sk !== null && rk !== sk && lk === sk)
+    if (!canWrite) continue
+    try {
+      mkdirSync(path.dirname(lp), { recursive: true })
+      writeFileSync(lp, f.content)
+      // Align the local mtime to the remote's so the next rw_sync sees
+      // L==R==S and skips the file instead of flagging a local modification.
+      try { utimesSync(lp, new Date(f.mtime * 1000), new Date(f.mtime * 1000)) } catch { /* cosmetic */ }
+      state[f.rel] = { size: f.size, mtime: f.mtime }
+      stateDirty = true
+      written.push(f.rel)
+      present.add(f.rel)
+    } catch { /* a mirror write failure must not break the index */ }
+  }
+  if (stateDirty) {
+    try { saveSyncState(mirrorDir, state) } catch { /* best effort */ }
+  }
+  return { written, present }
+}
+
+/**
+ * Render the prompt-section index of remote instruction files. Paths are
+ * shown through `display` (the platform-aware display formatter), headings
+ * give the model a content hint without injecting the full text.
+ */
+export function formatInstructionIndex(files, display = (p) => p) {
+  const lines = files.slice(0, 10).map((f) => {
+    const h = f.headings && f.headings.length ? ` (headings: ${f.headings.slice(0, 6).join(' / ')})` : ''
+    const over = f.size > INSTRUCTION_MAX_BYTES ? ` (${Math.round(f.size / 1024)} KB)` : ''
+    const mirrored = f.mirrored ? '; synced into the local mirror' : ''
+    return `- ${display(f.remote)}${h}${over}${mirrored}`
+  })
+  return (
+    'Remote instruction files found in this workspace (they govern how to work in their directories; '
+    + 'root-level copies were synced into the local mirror, but nested ones are NOT auto-injected — '
+    + 'read them with rw_read_file before editing that tree):\n'
+    + lines.join('\n')
+  )
+}
+
+/**
+ * Per-process index of remote instruction scans, keyed by mirror directory.
+ * Deduplicates in-flight scans, negative-caches failures for a minute (an
+ * offline machine must not turn every prompt assembly into a connect
+ * attempt), and never throws — the index is strictly best-effort.
+ */
+export function createInstructionIndex() {
+  const cache = new Map() // resolvedMirrorDir → { scannedAt, files } | { failedAt }
+  const inflight = new Map() // resolvedMirrorDir → Promise
+  const RETRY_AFTER_MS = 60 * 1000
+
+  const keyOfDir = (mirrorDir) => {
+    try { return path.resolve(String(mirrorDir)) } catch { return String(mirrorDir || '') }
+  }
+
+  /**
+   * Scan (or return the cached scan of) one mirror's remote workspace.
+   * @param {{pool: {sftp: Function}, ws: string, mirrorDir: string, force?: boolean}} arg
+   * @returns {Promise<{scannedAt: number, files: Array}|null>}
+   */
+  const refresh = ({ pool, ws, mirrorDir, force = false }) => {
+    if (!pool || typeof pool.sftp !== 'function' || !ws || !mirrorDir) return Promise.resolve(null)
+    const key = keyOfDir(mirrorDir)
+    const cur = cache.get(key)
+    if (!force && cur && cur.files) return Promise.resolve(cur)
+    if (!force && cur && cur.failedAt && Date.now() - cur.failedAt < RETRY_AFTER_MS) return Promise.resolve(null)
+    if (inflight.has(key)) return inflight.get(key)
+    const job = (async () => {
+      try {
+        const sftp = await pool.sftp()
+        const files = await scanInstructionFiles(sftp, ws)
+        const synced = syncInstructionsToMirror(files, mirrorDir)
+        const entry = {
+          scannedAt: Date.now(),
+          files: files.map((f) => ({
+            rel: f.rel,
+            remote: f.remote,
+            size: f.size,
+            headings: f.headings,
+            mirrored: synced.present.has(f.rel),
+          })),
+        }
+        cache.set(key, entry)
+        return entry
+      } catch {
+        // Negative-cache: the machine may simply be offline; retry at most
+        // once a minute, not once per prompt assembly.
+        cache.set(key, { failedAt: Date.now() })
+        return null
+      } finally {
+        inflight.delete(key)
+      }
+    })()
+    inflight.set(key, job)
+    return job
+  }
+
+  /** The cached index for a mirror, or null when unknown/failed. */
+  const get = (mirrorDir) => {
+    const e = cache.get(keyOfDir(mirrorDir))
+    return e && e.files ? e : null
+  }
+
+  /** Fire-and-forget refresh for prompt-assembly time: starts a scan only
+   *  when nothing is known about the mirror yet (recent failures included). */
+  const note = ({ pool, ws, mirrorDir }) => {
+    if (cache.has(keyOfDir(mirrorDir))) return
+    refresh({ pool, ws, mirrorDir }).catch(() => { /* guarded inside */ })
+  }
+
+  return { refresh, get, note, _cache: cache }
+}

package/lib/openssh.js

@@ -785,7 +785,16 @@ export class SystemOpenSshPool {
         throw new Error('ssh target changed while opening sftp')
       }
       this._sftpChild = child
-      return buildSftpSurface(sftp, { commandTimeoutMs: this.config.commandTimeoutMs })
+      return buildSftpSurface(sftp, {
+        commandTimeoutMs: this.config.commandTimeoutMs,
+        onTimeout: () => {
+          // A timed-out SFTP session is dead: kill the child and drop the cached
+          // session so the next call re-handshakes instead of queueing behind the
+          // wedged one (issue #65).
+          try { child.kill() } catch { /* already gone */ }
+          drop()
+        },
+      })
     })
     // Never cache a rejected open: the next call must retry rather than get the
     // same error back forever (a failed handshake is usually transient).