dsh-ris-yds 1.0.0 → 1.1.0

package/lib/proc.js

@@ -0,0 +1,270 @@
+// Cross-platform process helpers.
+//
+// The Linux implementations read /proc/<pid>/cmdline to prove a pidfile still
+// points at OUR process; Windows has no /proc, so the same check must come from
+// the Win32 process table (PowerShell CIM). Without this, `yds status` reported
+// "not running" on Windows, `yds start` spawned a second YMS and `yds stop`
+// could never find the forwarder (review: Windows P0).
+//
+// Identity checks are THREE-valued on purpose (review D-P1-6): "ours", "gone" and
+// "could not tell". Collapsing "could not tell" into "not ours" deleted the pidfile
+// after a transient PowerShell/EPERM failure, which is exactly how a second YMS got
+// started on top of a live one. Callers must only act destructively on `dead`, only
+// signal on `ours`, and keep the pidfile when the answer is `unknown`.
+
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+
+const DEFAULT_PLATFORM = process.platform
+const WINDOWS_PROBE_OK = 'YDS_PROBE_OK'
+const WINDOWS_PROBE_ABSENT = 'YDS_PROBE_ABSENT'
+
+// One PowerShell per identity check costs ~0.5 s on Windows, and `yds status` /
+// `yds start` run several checks back to back (pidfile + forwarder). Keep the answers
+// for a few seconds so those paths do not spawn four processes (review D-P2-3). The
+// cache is only used on the real Windows probe (injected executors stay uncached so
+// tests remain deterministic) and `stopPid` invalidates it before/after the kill.
+const WINDOWS_PROBE_CACHE_MS = 5000
+const WINDOWS_PROBE_CACHE_MAX = 200
+const windowsProbeCache = new Map()
+
+/** Forget a cached probe (a stop is authoritative; never answer from before it). */
+export function clearProbeCache(pid) {
+  const value = Number(pid)
+  if (Number.isInteger(value) && value > 0) windowsProbeCache.delete(`win32:${value}`)
+}
+
+
+/**
+ * Run a command once and report everything the caller may need: exit code, both
+ * streams and the spawn error. Swallowing the exit code made `taskkill` failures
+ * look like successes (review D-P1-7).
+ * @returns {{code: number|null, stdout: string, stderr: string, error: Error|null}}
+ */
+export function runCommand(command, args, timeout = 8000) {
+  try {
+    const out = spawnSync(command, args, { encoding: 'utf8', timeout, windowsHide: true })
+    return {
+      code: Number.isInteger(out.status) ? out.status : null,
+      stdout: String(out.stdout ?? ''),
+      stderr: String(out.stderr ?? ''),
+      error: out.error ?? null,
+    }
+  } catch (error) {
+    return { code: null, stdout: '', stderr: '', error }
+  }
+}
+
+/**
+ * The PowerShell argument list used to read a pid's command line. Kept separate so a
+ * test can assert the WQL quoting without spawning Windows.
+ *
+ * The pid is the only interpolated value and is validated as a positive integer by
+ * `probePid`, so it cannot inject anything. The WQL predicate is single-quoted: the
+ * old form embedded double quotes inside `-Command`, which only survived because of
+ * one specific argument-quoting rule on Windows (review D-P2).
+ */
+export function windowsProbeArgs(pid) {
+  const value = Number(pid)
+  const script = [
+    `$p = Get-CimInstance Win32_Process -Filter 'ProcessId=${value}'`,
+    `if ($null -eq $p) { '${WINDOWS_PROBE_ABSENT}' } else { '${WINDOWS_PROBE_OK}:' + $p.CommandLine }`,
+  ].join('; ')
+  return ['-NoProfile', '-NonInteractive', '-Command', script]
+}
+
+function parseWindowsProbe(result) {
+  // Spawn failure/timeout: we cannot tell whether the pid exists.
+  if (result?.error !== null && result?.error !== undefined) return { state: 'unknown', commandLine: '' }
+  const text = String(result?.stdout ?? '').trim()
+  const marker = `${WINDOWS_PROBE_OK}:`
+  // The command line is echoed verbatim after the OK marker, so the absent marker
+  // must be matched as the WHOLE output: `includes` used to call a live process dead
+  // when its own command line contained the marker string (review D-P2-2).
+  if (text === WINDOWS_PROBE_ABSENT) return { state: 'dead', commandLine: '' }
+  const at = text.indexOf(marker)
+  if (at !== -1) return { state: 'alive', commandLine: text.slice(at + marker.length).trim() }
+  // Empty output with a non-zero exit code is a permission/availability failure,
+  // NOT proof that the process is gone. Keep it unknown.
+  return { state: 'unknown', commandLine: '' }
+}
+
+/** Default POSIX liveness probe: EPERM means the pid exists but is not ours. */
+export function signalState(pid) {
+  try {
+    process.kill(pid, 0)
+    return 'alive'
+  } catch (error) {
+    if (error?.code === 'ESRCH') return 'dead'
+    if (error?.code === 'EPERM') return 'alive'
+    return 'unknown'
+  }
+}
+
+/**
+ * Identify a pid: `state` is `alive`, `dead` or `unknown`, plus its command line when
+ * it can be read. Everything else (pidfiles, markers, stop) is built on this.
+ * @param {number} pid - process id.
+ * @param {{platform?: NodeJS.Platform, exec?: Function, signal?: Function,
+ *          commandLine?: Function}} [options] - injectable for tests.
+ * @returns {{state: 'alive'|'dead'|'unknown', commandLine: string}}
+ */
+export function probePid(pid, { platform = DEFAULT_PLATFORM, exec = runCommand, signal = signalState, commandLine = null } = {}) {
+  const value = Number(pid)
+  if (!Number.isInteger(value) || value <= 0) return { state: 'dead', commandLine: '' }
+  if (platform === 'win32') {
+    // Cached only for the real probe: tests inject `exec` and must see every call.
+    const cacheable = exec === runCommand
+    const cacheKey = `win32:${value}`
+    if (cacheable) {
+      const hit = windowsProbeCache.get(cacheKey)
+      if (hit !== undefined && Date.now() - hit.at <= WINDOWS_PROBE_CACHE_MS) {
+        return { state: hit.state, commandLine: hit.commandLine }
+      }
+    }
+    const probe = parseWindowsProbe(exec('powershell.exe', windowsProbeArgs(value), 8000))
+    if (cacheable) {
+      if (windowsProbeCache.size >= WINDOWS_PROBE_CACHE_MAX) windowsProbeCache.clear()
+      windowsProbeCache.set(cacheKey, { at: Date.now(), state: probe.state, commandLine: probe.commandLine })
+    }
+    return probe
+  }
+  const state = signal(value)
+  if (state === 'dead') return { state: 'dead', commandLine: '' }
+  if (state !== 'alive') return { state: 'unknown', commandLine: '' }
+  let line = ''
+  if (typeof commandLine === 'function') {
+    line = String(commandLine(value) ?? '').trim()
+  } else {
+    try { line = readFileSync(`/proc/${value}/cmdline`, 'utf8').replace(/\0/g, ' ').trim() } catch { line = '' }
+  }
+  return { state: 'alive', commandLine: line }
+}
+
+/**
+ * The full command line of a live process, or '' when it cannot be read.
+ * Windows: one CIM query per call (~0.5 s); Linux/WSL: /proc.
+ * @param {number} pid - process id.
+ * @returns {string} NUL/space-joined command line.
+ */
+export function processCommandLine(pid, options = {}) {
+  return probePid(pid, options).commandLine
+}
+
+/** Is the pid alive? `false` also covers "could not tell" — use probePid for a
+ *  three-valued answer. */
+export function pidAlive(pid, options = {}) {
+  return probePid(pid, options).state === 'alive'
+}
+
+/**
+ * Which of OUR processes a pid belongs to, without ever confusing "unreadable" with
+ * "not ours":
+ *   - `ours`    - alive and its command line contains one of the markers
+ *   - `foreign` - alive, command line readable, marker absent (pid was reused or the
+ *                 pidfile is stale; safe to unlink the pidfile)
+ *   - `dead`    - definitely gone
+ *   - `unknown` - could not probe / could not read the command line: keep the pidfile
+ * @returns {{state: 'ours'|'foreign'|'dead'|'unknown', commandLine: string}}
+ */
+export function pidIdentity(pid, markers, options = {}) {
+  const list = (Array.isArray(markers) ? markers : [markers]).filter((marker) => typeof marker === 'string' && marker !== '')
+  const probe = probePid(pid, options)
+  if (probe.state === 'dead') return { state: 'dead', commandLine: '' }
+  if (probe.state === 'unknown') return { state: 'unknown', commandLine: probe.commandLine }
+  if (probe.commandLine === '') return { state: 'unknown', commandLine: '' }
+  return {
+    state: list.some((marker) => probe.commandLine.includes(marker)) ? 'ours' : 'foreign',
+    commandLine: probe.commandLine,
+  }
+}
+
+/** Default POSIX kill used by `stopPid`; injectable so the signal path is testable. */
+function defaultKill(pid, sig) {
+  try {
+    process.kill(pid, sig)
+    return { ok: true }
+  } catch (error) {
+    // Already gone is success for a stop request.
+    if (error?.code === 'ESRCH') return { ok: true }
+    return { ok: false, error: String(error?.message ?? error) }
+  }
+}
+
+/**
+ * Stop a process, preferring a clean signal. Windows has no SIGTERM: use
+ * `taskkill /T /F` so the whole tree (java + helpers) goes away and the pidfile
+ * cannot be left pointing at an orphan.
+ *
+ * The result is REPORTED, not assumed: callers must only unlink the pidfile (and
+ * tell the user "stopped") when `ok === true` (review D-P1-7).
+ * @param {number} pid - process id.
+ * @param {{force?: boolean, graceMs?: number, platform?: NodeJS.Platform,
+ *          exec?: Function, signal?: Function, probe?: Function,
+ *          kill?: (pid: number, sig: string) => {ok: boolean, error?: string},
+ *          group?: boolean}} [options]
+ * @returns {Promise<{ok: boolean, code: number|null, error?: string}>}
+ */
+export async function stopPid(pid, {
+  force = false,
+  graceMs = 30000,
+  platform = DEFAULT_PLATFORM,
+  exec = runCommand,
+  signal = signalState,
+  probe = probePid,
+  kill = defaultKill,
+  group = false,
+} = {}) {
+  const value = Number(pid)
+  if (!Number.isInteger(value) || value <= 0) return { ok: false, code: null, error: 'invalid pid' }
+  if (platform === 'win32') {
+    // A stop invalidates every cached answer: the pre-kill state must not leak into
+    // the post-kill verification below.
+    clearProbeCache(value)
+    const result = exec('taskkill', ['/PID', String(value), '/T', '/F'], 30000)
+    clearProbeCache(value)
+    if (result?.code === 0) return { ok: true, code: 0 }
+    // taskkill also fails when the process exited between probe and kill: that is
+    // success for our purposes, so verify instead of trusting the message.
+    const after = probe(value, { platform, exec, signal })
+    if (after.state === 'dead') return { ok: true, code: result?.code ?? null }
+    return {
+      ok: false,
+      code: result?.code ?? null,
+      error: String(result?.stderr ?? '').trim() || `taskkill exited with ${String(result?.code ?? 'no status')}`,
+    }
+  }
+  // A detached child (YMS) is its own group leader: signalling -pid also stops the
+  // helpers it spawned. Windows does the same via `taskkill /T`.
+  const target = group ? -value : value
+  if (force) {
+    const killed = kill(target, 'SIGKILL')
+    if (killed.ok !== true) return { ok: false, code: null, error: killed.error }
+    // SIGKILL is not instantly observable: verify instead of claiming success.
+    for (let i = 0; i < 10; i += 1) {
+      // eslint-disable-next-line no-await-in-loop
+      if (probe(value, { platform, exec, signal }).state === 'dead') return { ok: true, code: null }
+      // eslint-disable-next-line no-await-in-loop
+      await new Promise((resolve) => setTimeout(resolve, 150))
+    }
+    return { ok: false, code: null, error: 'SIGKILL 后进程仍存活' }
+  }
+  const term = kill(target, 'SIGTERM')
+  if (term.ok !== true) return { ok: false, code: null, error: term.error }
+  const deadline = Date.now() + Math.max(0, Number(graceMs) || 0)
+  while (Date.now() < deadline) {
+    // eslint-disable-next-line no-await-in-loop
+    if (probe(value, { platform, exec, signal }).state === 'dead') return { ok: true, code: null }
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, 300))
+  }
+  const killed = kill(target, 'SIGKILL')
+  if (killed.ok !== true) return { ok: false, code: null, error: killed.error }
+  for (let i = 0; i < 10; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    if (probe(value, { platform, exec, signal }).state === 'dead') return { ok: true, code: null }
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, 150))
+  }
+  return { ok: false, code: null, error: 'SIGKILL 后进程仍存活' }
+}

package/lib/risd-peer.js

@@ -0,0 +1,353 @@
+// Talk to the dsh-ris-ide daemon (`risd`) over its HTTP API.
+//
+// This is the preferred tier: when risd owns the engine, its rule table and the
+// system-level intercept, yds must not start or stop anything — it only (a) takes a
+// lease so the daemon does not tear the tunnel down while a launch is in flight,
+// (b) writes its `source: 'yds'` rules through the daemon's CAS, and (c) releases
+// the lease on `yds stop` (the engine stays up: it is machine-wide and an IDE may
+// still be using it).
+//
+// The daemon's state file (`risd.json`) carries a short-lived token; `GET /v1/health`
+// is unauthenticated and cheap, so discovery is always "read state + probe health".
+import { mergeYdsRules, withdrawnBetween, ydsRowsOf } from './rules.js'
+import {
+  closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/** API version this peer understands. Mirrors the daemon's `RISD_API_VERSION`. */
+export const RISD_API_VERSION = 1
+/** Header carrying the API version; a mismatch is refused (409) rather than guessed. */
+const API_VERSION_HEADER = 'x-risd-api-version'
+const REQUEST_TIMEOUT_MS = 2000
+const PROBE_TIMEOUT_MS = 700
+
+/** `YDS_RISD=none` is the documented escape hatch (tests, broken install). */
+export function risdDisabled() {
+  return process.env.YDS_RISD === 'none'
+}
+
+/** Where the shared plugin home lives (the daemon writes `risd.json` there). */
+export function risdHome() {
+  const explicit = process.env.DSH_RIS_IDE_PROXY_HOME || process.env.YDS_RISD_HOME
+  return typeof explicit === 'string' && explicit !== '' ? explicit : join(homedir(), '.dsh-ris-ide')
+}
+
+export function risdStatePath(home = risdHome()) {
+  return join(home, 'risd.json')
+}
+
+/** Read the daemon state file; unreadable/partial files mean "not running". */
+export function readRisdState(home = risdHome()) {
+  const path = risdStatePath(home)
+  if (existsSync(path) !== true) return null
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    if (parsed === null || typeof parsed !== 'object') return null
+    if (!Number.isInteger(parsed.port) || parsed.port <= 0) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+/** One daemon request. Never throws; a transport failure is `{ ok:false, error }`. */
+export async function risdRequest(state, path, { method = 'GET', body, timeoutMs = REQUEST_TIMEOUT_MS } = {}) {
+  const headers = { [API_VERSION_HEADER]: String(RISD_API_VERSION) }
+  if (typeof state?.token === 'string' && state.token !== '') headers.authorization = `Bearer ${state.token}`
+  if (body !== undefined) headers['content-type'] = 'application/json'
+  let response
+  try {
+    response = await fetch(`http://127.0.0.1:${state.port}${path}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+  } catch (error) {
+    return { ok: false, status: 0, body: null, error: String(error?.message ?? error) }
+  }
+  let payload = null
+  try { payload = await response.json() } catch { payload = null }
+  return { ok: response.ok === true && (payload === null || payload.ok !== false), status: response.status, body: payload, error: payload !== null && typeof payload.message === 'string' ? payload.message : '' }
+}
+
+/**
+ * Is a usable daemon running?
+ * Unauthenticated health is the liveness signal; a mismatched API version is
+ * reported explicitly so an old daemon is not silently half-used.
+ */
+export async function probeRisd({ home = risdHome() } = {}) {
+  if (risdDisabled()) return { usable: false, reason: 'disabled', state: null }
+  const state = readRisdState(home)
+  if (state === null) return { usable: false, reason: 'absent', state: null }
+  const health = await risdRequest(state, '/v1/health', { timeoutMs: PROBE_TIMEOUT_MS })
+  if (health.ok !== true) return { usable: false, reason: 'unreachable', state, error: health.error }
+  const apiVersion = Number(health.body?.apiVersion)
+  if (apiVersion !== RISD_API_VERSION) {
+    return { usable: false, reason: 'api-mismatch', state, daemonVersion: apiVersion, version: health.body?.version }
+  }
+  return { usable: true, reason: '', state, health: health.body }
+}
+
+/** Take a lease so the daemon keeps the engine while this launch is in flight. */
+export async function acquireLease({ cwd, state = null, ownerPid = process.pid } = {}) {
+  const resolved = state ?? (await probeRisd()).state
+  if (resolved === null) return { ok: false, error: 'risd 未运行' }
+  const result = await risdRequest(resolved, '/v1/leases', {
+    method: 'POST',
+    body: { ownerPid, sessionId: 'yds', cwd: typeof cwd === 'string' ? cwd : undefined },
+  })
+  const id = typeof result.body?.lease?.id === 'string' ? result.body.lease.id : ''
+  return { ok: result.ok === true && id !== '', id, state: resolved, status: result.status, error: result.error || (id === '' ? 'risd 未返回租约 id' : '') }
+}
+
+/** Release one lease (null-safe: nothing to do when none was taken). */
+export async function releaseLease(id, { state = null } = {}) {
+  if (typeof id !== 'string' || id === '') return { ok: true, released: false }
+  const resolved = state ?? (await probeRisd()).state
+  if (resolved === null) return { ok: true, released: false }
+  const result = await risdRequest(resolved, `/v1/leases/${encodeURIComponent(id)}`, { method: 'DELETE' })
+  return { ok: result.ok === true, released: result.ok === true, status: result.status, error: result.error }
+}
+
+// A lease must outlive the `yds` process that took it (the YMS runtime keeps using
+// the tunnel after the CLI exits), so it is recorded on disk keyed by workspace and
+// owned by the long-lived pid (the YMS process, or the foreground CLI).
+
+function leasesPath(home = risdHome()) {
+  return join(home, '..', '.dsh-ris-yds', 'risd-leases.json')
+}
+
+function readLeases(home = risdHome()) {
+  const path = leasesPath(home)
+  if (existsSync(path) !== true) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+const LEASE_LOCK_TIMEOUT_MS = 2000
+const LEASE_LOCK_STALE_MS = 5000
+const LEASE_LOCK_RETRY_MS = 20
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+/**
+ * Run `fn` while holding a lock beside the lease file.
+ *
+ * The lease record is a tiny read-modify-write file, and two `yds start/stop` runs in
+ * different workspaces could otherwise drop each other's entry (review D-P2-6). The
+ * lock is `O_EXCL`, so a crashed writer cannot deadlock us: a lock older than
+ * LEASE_LOCK_STALE_MS is treated as abandoned. On timeout we still run `fn` unlocked —
+ * losing the lease record is worse than an unlocked write.
+ */
+function withLeaseLock(path, fn) {
+  const lockPath = `${path}.lock`
+  mkdirSync(dirname(path), { recursive: true })
+  const deadline = Date.now() + LEASE_LOCK_TIMEOUT_MS
+  let held = false
+  while (held !== true) {
+    try {
+      const fd = openSync(lockPath, 'wx')
+      try {
+        writeFileSync(fd, String(process.pid), 'utf8')
+      } finally {
+        closeSync(fd)
+      }
+      held = true
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      try {
+        if (Date.now() - statSync(lockPath).mtimeMs > LEASE_LOCK_STALE_MS) {
+          unlinkSync(lockPath)
+          continue
+        }
+      } catch {
+        continue // raced with the owner releasing it: retry immediately
+      }
+      if (Date.now() > deadline) return fn()
+      sleepSync(LEASE_LOCK_RETRY_MS)
+    }
+  }
+  try {
+    return fn()
+  } finally {
+    try { unlinkSync(lockPath) } catch { /* ignore */ }
+  }
+}
+
+/** Write the lease map atomically so a crash never leaves half a JSON object. */
+function writeLeases(path, all) {
+  const tmp = `${path}.${process.pid}.tmp`
+  writeFileSync(tmp, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 })
+  renameSync(tmp, path)
+}
+
+/** Remember a lease id so a later `yds stop` (another process) can release it. */
+export function rememberLease(cwd, entry, { home = risdHome() } = {}) {
+  const path = leasesPath(home)
+  try {
+    return withLeaseLock(path, () => {
+      const all = readLeases(home)
+      all[cwd] = Object.assign({}, entry, { at: new Date().toISOString() })
+      writeLeases(path, all)
+      return true
+    })
+  } catch {
+    return false
+  }
+}
+
+/** The lease recorded for this workspace, or null. */
+export function readLease(cwd, { home = risdHome() } = {}) {
+  const entry = readLeases(home)[cwd]
+  return entry !== null && typeof entry === 'object' ? entry : null
+}
+
+/** Drop the record (after releasing, or when the daemon says it is gone). */
+export function forgetLease(cwd, { home = risdHome() } = {}) {
+  const path = leasesPath(home)
+  try {
+    withLeaseLock(path, () => {
+      const all = readLeases(home)
+      if (all[cwd] === undefined) return
+      delete all[cwd]
+      writeLeases(path, all)
+    })
+  } catch { /* best effort */ }
+}
+
+function pidIsAlive(pid) {
+  if (Number.isInteger(pid) !== true || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error?.code === 'EPERM'
+  }
+}
+
+/**
+ * Drop a recorded lease whose owner process is gone (YMS killed with -9).
+ *
+ * The daemon only reaps by pid, so a dead owner keeps the engine alive until the
+ * 3 s sweep — clearing our own record first means `yds stop` will not try to release
+ * a lease the daemon already forgot (review D-P2-6).
+ */
+export function dropDeadLease(cwd, { home = risdHome(), isAlive = pidIsAlive } = {}) {
+  const entry = readLease(cwd, { home })
+  if (entry === null) return false
+  if (isAlive(Number(entry.ownerPid)) === true) return false
+  forgetLease(cwd, { home })
+  return true
+}
+
+/** The daemon's own view of the rule table (carries the CAS revision). */
+export async function getView(cwd, { state = null } = {}) {
+  const resolved = state ?? (await probeRisd()).state
+  if (resolved === null) return { ok: false, error: 'risd 未运行' }
+  const result = await risdRequest(resolved, `/v1/proxy?cwd=${encodeURIComponent(cwd)}`)
+  return { ok: result.ok === true, view: result.body, status: result.status, error: result.error }
+}
+
+/**
+ * Replace the `source: 'yds'` rows of the global rule table through the daemon.
+ *
+ * The table is one machine-wide list and the panel saves it wholesale, so the
+ * payload below is the COMPLETE table: every non-yds row read from proxy.json is
+ * passed through unchanged and the yds rows are exactly `rules` (an empty array
+ * therefore removes them all). The file is read directly for the other sources'
+ * rows: the daemon's view omits them on purpose (the plugin decorates the table per
+ * session), and a blind write would drop user/auto rules. A revision conflict is
+ * retried once with the fresh revision — another dsh window may have saved in between.
+ */
+export async function putRules(cwd, rules, { gitHost = '', home = risdHome(), attempts = 2, log } = {}) {
+  const state = readRisdState(home)
+  if (state === null) return { ok: false, error: 'risd 未运行' }
+  let lastError = ''
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const view = await getView(cwd, { state })
+    if (view.ok !== true) return { ok: false, status: view.status, error: view.error || '读取 risd 视图失败' }
+    // An empty revision is the daemon's deliberate "force" path. yds must never take
+    // it silently: if the view carries no revision we cannot tell whether somebody
+    // else wrote in between, so fail instead of clobbering their change (D-P2-8).
+    const baseRevision = String(view.view?.revision ?? '').trim()
+    if (baseRevision === '') {
+      return {
+        ok: false,
+        status: 0,
+        error: 'revision-missing：risd 未返回规则表 revision（旧版/异常 daemon），已拒绝无 CAS 的强写，请升级 dsh-ris-ide 后重试',
+      }
+    }
+    const stored = readStoredConfig(home)
+    // Whole-table save: non-yds rows are preserved, the yds rows become exactly the
+    // set this run generated (global table, no cross-workspace bookkeeping).
+    const before = ydsRowsOf(stored.rules, { log })
+    const table = mergeYdsRules(stored.rules, rules, { log })
+    // Only the fields the daemon actually consumes are sent. `shadows` used to be
+    // included, but POST /v1/proxy reads socks/listenPort/rules only, so a value here
+    // could never take effect and looked like a successful mapping update
+    // (review D-P2-8). The daemon keeps the stored shadow list itself.
+    const merged = {
+      socks: stored.socks ?? { host: '', port: 0 },
+      listenPort: stored.listenPort,
+      rules: table,
+    }
+    const result = await risdRequest(state, '/v1/proxy', {
+      method: 'POST',
+      body: {
+        cwd,
+        config: merged,
+        revision: baseRevision,
+        gitHost,
+      },
+      timeoutMs: 8000,
+    })
+    if (result.ok === true) {
+      return {
+        ok: true,
+        revision: result.body?.revision,
+        reloadNote: result.body?.reloadNote ?? '',
+        withdrawn: withdrawnBetween(before, table),
+        status: result.status,
+      }
+    }
+    lastError = result.error || `risd 保存失败（${result.status}）`
+    if (result.status !== 409) return { ok: false, status: result.status, error: lastError }
+  }
+  return { ok: false, status: 409, error: lastError }
+}
+
+function readStoredConfig(home) {
+  const path = join(home, 'proxy.json')
+  if (existsSync(path) !== true) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/** Ensure the daemon owns a running engine for this workspace. */
+export async function startEngine(cwd, { state = null } = {}) {
+  const resolved = state ?? (await probeRisd()).state
+  if (resolved === null) return { ok: false, error: 'risd 未运行' }
+  const result = await risdRequest(resolved, '/v1/action', { method: 'POST', body: { action: 'start', cwd }, timeoutMs: 30000 })
+  return { ok: result.ok === true, status: result.status, result: result.body?.result, error: result.error }
+}
+
+/** Read the daemon engine's status (pid, listen ports, log path). */
+export async function engineStatus(cwd, { state = null } = {}) {
+  const resolved = state ?? (await probeRisd()).state
+  if (resolved === null) return { ok: false, error: 'risd 未运行' }
+  const response = await risdRequest(resolved, `/v1/engine?cwd=${encodeURIComponent(cwd)}`)
+  return { ok: response.ok === true, status: response.status, engine: response.body?.engine ?? null, error: response.error }
+}