dsh-ris-yds 1.0.0 → 1.1.0

package/lib/rules.js

@@ -0,0 +1,193 @@
+// The proxy rule table is machine-wide AND global: there is exactly one table for the
+// whole box, and the panel saves it wholesale ("全局一张表、保存即整表覆盖"). The daemon's
+// `POST /v1/proxy` mirrors that contract, so yds owns its share outright:
+//
+//   * `yds start` writes the COMPLETE set of yds rows (whatever yds rows were there
+//     before — from any workspace — are replaced),
+//   * `yds stop` removes EVERY `source: 'yds'` row.
+//
+// There is no cross-workspace bookkeeping any more: no `owners` map, no per-workspace
+// subtraction. Two projects that both run `yds start` do not merge their endpoints;
+// the last save simply wins, which is exactly what "没有交叉配置" means.
+//
+// The only identity that must stay distinct is the program: `java.exe` is the Windows
+// image and `java` is the process name a WSL/Linux side matches, so the group key is
+// `side|program` and the two live side by side instead of collapsing into one row.
+export const YDS_RULE_SOURCE = 'yds'
+
+/** Program identity for duplicate detection: basename, lower-case, no script suffix. */
+export function programKeyOf(program) {
+  if (typeof program !== 'string') return ''
+  const text = program.trim()
+  if (text === '') return ''
+  // A wildcard program (`C:\devkit\jdk*\bin\*.exe`) has no basename identity: its
+  // basename is `*.exe`, which would collapse EVERY wildcard program into one row.
+  // Keep the whole pattern as the key instead.
+  if (/[*?]/.test(text)) return `raw:${text.toLowerCase()}`
+  const base = text.split(/[\\/]/).pop() ?? ''
+  return base.toLowerCase().replace(/\.(exe|cmd|bat|sh)$/, '')
+}
+
+/**
+ * Identity of one rule inside the yds share: the side it applies to plus the program.
+ * `windows|java` and `local|java` are different rows on purpose (the Windows engine
+ * matches `java.exe`, the WSL/Linux side matches `java`).
+ * @param {{side?: string, program?: string}} rule
+ * @returns {string}
+ */
+export function ruleGroupKey(rule) {
+  const side = typeof rule?.side === 'string' ? rule.side.trim().toLowerCase() : ''
+  return `${side}|${programKeyOf(rule?.program)}`
+}
+
+function hostList(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item !== '')
+}
+
+function portList(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item !== '')
+}
+
+function uniquePush(target, values) {
+  for (const value of values) {
+    if (!target.includes(value)) target.push(value)
+  }
+}
+
+function hostText(hosts) {
+  return hosts.join(',')
+}
+
+/** A rule allows every port when any caller says `*`: keep the wildcard form. */
+function portText(ports) {
+  return ports.includes('*') ? '*' : ports.join(',')
+}
+
+/**
+ * Validate one fresh row and canonicalize the fields the engine reads. Unknown fields
+ * (id, label, side, ...) are kept as they came; only the list/boolean fields are
+ * normalized so a hand-written value cannot reach the engine half-parsed.
+ * @returns {object|null} null when the row cannot be a rule (logged).
+ */
+function normalizeFreshRow(row, { log } = {}) {
+  if (row === null || typeof row !== 'object' || Array.isArray(row)) {
+    log?.('代理规则：忽略一条不是对象的规则')
+    return null
+  }
+  const program = typeof row.program === 'string' ? row.program.trim() : ''
+  if (program === '') {
+    log?.(`代理规则：忽略一条没有 program 的规则（id=${String(row.id ?? '?')}）`)
+    return null
+  }
+  const hosts = hostList(row.hosts)
+  const ports = portList(row.ports)
+  if (hosts.length === 0 && ports.length === 0) {
+    log?.(`代理规则：忽略一条既没有 host 也没有 port 的规则（id=${String(row.id ?? '?')}）`)
+    return null
+  }
+  return {
+    ...row,
+    program,
+    hosts: hostText(hosts),
+    ports: portText(ports),
+    enabled: row.enabled !== false,
+    shadow: row.shadow === true,
+    direct: row.direct === true,
+    source: YDS_RULE_SOURCE,
+  }
+}
+
+/** Union two fresh rows that name the same side+program (a caller bug, not the norm). */
+function mergeFreshRows(into, extra) {
+  const hosts = hostList(into.hosts)
+  uniquePush(hosts, hostList(extra.hosts))
+  const ports = portList(into.ports)
+  uniquePush(ports, portList(extra.ports))
+  return {
+    ...into,
+    hosts: hostText(hosts),
+    ports: portText(ports),
+    // Lists union; `enabled` is satisfied by either row; the opt-ins only survive if
+    // every copy asked for them (a stray duplicate must not turn interception off).
+    enabled: into.enabled === true || extra.enabled === true,
+    shadow: into.shadow === true && extra.shadow === true,
+    direct: into.direct === true && extra.direct === true,
+  }
+}
+
+/**
+ * Build the table to save: every non-yds row is passed through untouched, then the
+ * fresh yds rows are appended (one row per side+program, ids preserved).
+ *
+ * This is a WHOLE-TABLE function: the return value is the complete rule list, so the
+ * caller can PUT it to the daemon as-is. An empty `freshRules` array therefore removes
+ * every yds row (that is `yds stop`) and leaves the non-yds rows alone.
+ * @param {object[]} existingRules - rows currently stored (any source).
+ * @param {object[]} freshRules - the yds rows to own; empty = remove them all.
+ * @param {{log?: (line: string) => void}} [options]
+ * @returns {object[]} the complete table, non-yds rows first.
+ */
+export function mergeYdsRules(existingRules, freshRules, { log } = {}) {
+  const rows = []
+  for (const row of Array.isArray(existingRules) ? existingRules : []) {
+    if (row === null || typeof row !== 'object' || Array.isArray(row)) continue
+    // The yds share is rebuilt from `freshRules` below, never inherited: a row that
+    // is not regenerated must disappear (an endpoint that moved, or another
+    // workspace's rows, which the global table replaces wholesale).
+    if (row.source === YDS_RULE_SOURCE) continue
+    rows.push(row)
+  }
+  const fresh = new Map()
+  const order = []
+  for (const row of Array.isArray(freshRules) ? freshRules : []) {
+    const normalized = normalizeFreshRow(row, { log })
+    if (normalized === null) continue
+    const key = ruleGroupKey(normalized)
+    const existing = fresh.get(key)
+    if (existing === undefined) {
+      fresh.set(key, normalized)
+      order.push(key)
+      continue
+    }
+    fresh.set(key, mergeFreshRows(existing, normalized))
+  }
+  for (const key of order) rows.push(fresh.get(key))
+  return rows
+}
+
+/** Just the yds rows of a stored table (for counts and withdrawal math). */
+export function ydsRowsOf(existingRules) {
+  return (Array.isArray(existingRules) ? existingRules : [])
+    .filter((row) => row !== null && typeof row === 'object' && row.source === YDS_RULE_SOURCE)
+}
+
+/**
+ * How many yds rows and distinct hosts disappear between two table snapshots, for the
+ * CLI text. Counts yds rows only: the non-yds rows are never ours to report on.
+ * @returns {{rules: number, hosts: number}}
+ */
+export function withdrawnBetween(beforeRules, afterRules) {
+  const hosts = (rows) => {
+    const out = new Set()
+    for (const row of ydsRowsOf(rows)) {
+      for (const host of hostList(row.hosts)) out.add(host)
+    }
+    return out
+  }
+  const before = hosts(beforeRules)
+  const after = hosts(afterRules)
+  let removed = 0
+  for (const host of before) {
+    if (!after.has(host)) removed += 1
+  }
+  return {
+    rules: Math.max(0, ydsRowsOf(beforeRules).length - ydsRowsOf(afterRules).length),
+    hosts: removed,
+  }
+}

package/lib/socks.js

@@ -7,6 +7,7 @@
 
 import { spawn } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { pidAlive, pidIdentity, stopPid } from './proc.js'
 import { join } from 'node:path'
 import net from 'node:net'
 import { fileURLToPath } from 'node:url'
@@ -18,32 +19,48 @@ export function socksPidFile(cfg) {
 /**
  * Verify a pid is really our process (guards against pid reuse after a
  * crash/reboot: a bare pid from a stale pidfile could be an unrelated
- * process — never signal it). Identity = /proc/<pid>/cmdline contains our
- * marker. Returns false when /proc is unavailable (non-Linux): the caller
- * then treats the pid as unverified and refuses to kill it.
+ * process — never signal it). Identity = the pid's command line contains our
+ * marker, from /proc on Linux/WSL or the Win32 process table on Windows.
+ * `unknown` (probe failed) is NOT "not ours": see pidIdentity (review D-P1-6).
  */
 export function pidIsOurs(pid, marker) {
   if (!Number.isInteger(pid) || pid <= 0) return false
-  try {
-    const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8')
-    return cmd.includes(marker)
-  } catch { return false }
+  return pidIdentity(pid, [marker]).state === 'ours'
 }
 
-/** Read + verify the forwarder pidfile; null when absent/stale/foreign. */
-export function forwarderPid(cfg) {
+const FORWARDER_MARKER = 'socks-fwd'
+
+/**
+ * Read + verify the forwarder pidfile.
+ * @returns {{pid: number|null, state: 'absent'|'verified'|'stale'|'unknown', reason: string}}
+ *   Only `verified` yields a pid. `unknown` keeps the pidfile untouched so a
+ *   transient probe failure cannot cause a duplicate forwarder.
+ */
+export function probeForwarder(cfg, options = {}) {
   const pidFile = socksPidFile(cfg)
-  if (!existsSync(pidFile)) return null
+  if (!existsSync(pidFile)) return { pid: null, state: 'absent', reason: 'pidfile 不存在' }
   const pid = Number(readFileSync(pidFile, 'utf8').trim())
-  if (!Number.isInteger(pid) || pid <= 0 || !pidIsOurs(pid, 'socks-fwd')) {
-    try { if (Number.isInteger(pid) && pid > 0 && !pidIsOurs(pid, 'socks-fwd') && !pidIsAlive(pid)) unlinkSync(pidFile) } catch { /* ignore */ }
-    return null
+  if (!Number.isInteger(pid) || pid <= 0) {
+    try { unlinkSync(pidFile) } catch { /* ignore */ }
+    return { pid: null, state: 'stale', reason: 'pidfile 内容无效（已清理）' }
   }
-  return pid
+  const identity = pidIdentity(pid, [FORWARDER_MARKER], options)
+  if (identity.state === 'ours') return { pid, state: 'verified', reason: '' }
+  if (identity.state === 'dead') {
+    try { unlinkSync(pidFile) } catch { /* ignore */ }
+    return { pid: null, state: 'stale', reason: '转发器进程已退出（已清理 pidfile）' }
+  }
+  if (identity.state === 'foreign') {
+    // pid reused by an unrelated process after a crash/reboot: the pidfile is stale.
+    try { unlinkSync(pidFile) } catch { /* ignore */ }
+    return { pid: null, state: 'stale', reason: 'pid 已被其它进程复用（已清理 pidfile）' }
+  }
+  return { pid: null, state: 'unknown', reason: '无法确认 pidfile 进程身份（探测失败），已保留 pidfile 未动' }
 }
 
-function pidIsAlive(pid) {
-  try { process.kill(pid, 0); return true } catch { return false }
+/** Verified forwarder pid, or null (absent/stale/foreign/unknown). */
+export function forwarderPid(cfg, options = {}) {
+  return probeForwarder(cfg, options).pid
 }
 
 export function portOpen(host, port, timeout = 1500) {
@@ -61,10 +78,15 @@ export function portOpen(host, port, timeout = 1500) {
  * the port answers. A port answering without our pid = some other local
  * service (e.g. a local Oracle on 1521) — NOT the tunnel.
  */
-export function isForwarderUp(cfg) {
+export function isForwarderUp(cfg, options = {}) {
   return (async () => {
-    const pid = forwarderPid(cfg)
-    if (pid === null) return false
+    const probe = probeForwarder(cfg, options)
+    // Identity unreadable (`unknown`): fall back to the listeners, because starting a
+    // second forwarder next to a live one is worse than a possible false positive.
+    if (probe.state === 'unknown') {
+      return (await portOpen('127.0.0.1', cfg.dbForwardPort, 400)) || (await portOpen('127.0.0.1', cfg.redisForwardPort, 400))
+    }
+    if (probe.pid === null) return false
     return (await portOpen('127.0.0.1', cfg.dbForwardPort, 400)) || (await portOpen('127.0.0.1', cfg.redisForwardPort, 400))
   })()
 }
@@ -120,7 +142,7 @@ export async function startForwarder(cfg, targets, { logPath } = {}) {
   // the wait loop above can exhaust without the port ever answering (child
   // crashed instantly, e.g. EADDRINUSE) — verify before reporting success.
   const down = await portsUp()
-  const alive = pidIsAlive(child.pid)
+  const alive = pidAlive(child.pid)
   if (down !== null || !alive) {
     try { unlinkSync(socksPidFile(cfg)) } catch { /* ignore */ }
     throw new Error(`socks 转发器启动失败（端口 ${down ?? '?'} 未监听 / 进程存活=${alive}）——详情见 ${out}（端口被占或其他本地服务在 127.0.0.1:${down}？）`)
@@ -129,21 +151,18 @@ export async function startForwarder(cfg, targets, { logPath } = {}) {
 }
 
 /** Stop the detached forwarder if its pidfile pid is ours (never kill a reused foreign pid). */
-export async function stopForwarder(cfg) {
-  const pid = forwarderPid(cfg)
-  if (pid === null) return { stopped: false, reason: 'pidfile 不存在或非本工具进程' }
+export async function stopForwarder(cfg, options = {}) {
+  const probe = probeForwarder(cfg, options)
+  if (probe.pid === null) return { stopped: false, reason: probe.reason }
   const pidFile = socksPidFile(cfg)
-  try { process.kill(pid, 'SIGTERM') } catch { /* already gone */ }
-  for (let i = 0; i < 25; i += 1) {
-    try {
-      process.kill(pid, 0)
-      // eslint-disable-next-line no-await-in-loop
-      await new Promise((r) => setTimeout(r, 200))
-    } catch { break }
+  const killed = await stopPid(probe.pid, { graceMs: 5000, ...options })
+  if (killed.ok !== true) {
+    // Keep the pidfile: the process is still there and `yds status` must keep seeing it
+    // (review D-P1-7).
+    return { stopped: false, pid: probe.pid, reason: `停止失败：${killed.error ?? '未知原因'}（已保留 pidfile）` }
   }
-  try { process.kill(pid, 'SIGKILL') } catch { /* gone */ }
   try { unlinkSync(pidFile) } catch { /* ignore */ }
-  return { stopped: true, pid }
+  return { stopped: true, pid: probe.pid }
 }
 
 /** SOCKS5 no-auth handshake + CONNECT, promise-based (proven implementation). */

package/lib/yms.js

@@ -7,6 +7,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, openSyn
 import { join } from 'node:path'
 import http from 'node:http'
 import { portOpen } from './socks.js'
+import { pidIdentity, stopPid } from './proc.js'
 import { ymsHomeIsBuilt } from './build.js'
 
 export function ymsPidFile(cfg) {
@@ -140,7 +141,12 @@ function rememberPort(cfg) {
 export async function startDetached(cfg, { jvmArgs = [] } = {}) {
   const pidFile = ymsPidFile(cfg)
   const running = await readRunning(cfg)
-  if (running !== null) return { started: false, alreadyRunning: true, pid: running.pid }
+  if (running !== null) {
+    if (running.state === 'unknown') {
+      return { started: false, alreadyRunning: false, unknown: true, pid: running.pid, reason: running.reason }
+    }
+    return { started: false, alreadyRunning: true, pid: running.pid }
+  }
   if (!ymsHomeIsBuilt(cfg)) throw new Error('yms-home 未构建（先执行 yds build）')
   if (cfg.java == null) throw new Error('未找到 JDK——用 .env 的 java.path 或 JAVA_HOME 指定')
   if (cfg.module == null) throw new Error('未识别模块名——检查项目 yonbuilder.json / module.xml')
@@ -180,8 +186,11 @@ export async function startDetached(cfg, { jvmArgs = [] } = {}) {
     }
   }
   if (!up) {
+    // TERM → grace → KILL (Windows: taskkill /T /F) so a half-started java tree cannot
+    // survive the failure and keep the port (review D-P2-5); the pidfile only goes
+    // away once the process is actually gone.
+    try { await stopPid(child.pid, { graceMs: 5000, group: true }) } catch { /* best effort */ }
     try { unlinkSync(pidFile) } catch { /* ignore */ }
-    try { process.kill(child.pid, 'SIGTERM') } catch { /* ignore */ }
     throw new Error(`YMS 端口 ${cfg.ymsPort} 在 120 秒内未就绪——查看 ${log}`)
   }
   return { started: true, pid: child.pid, port: cfg.ymsPort, consoleLog: log }
@@ -216,41 +225,65 @@ export function startForeground(cfg, { jvmArgs = [], onStdout, signal } = {}) {
   return child
 }
 
-/** pid is really our YMS java (cmdline marker), not a reused pid. */
-function pidIsYms(pid) {
-  try {
-    const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8')
-    return cmd.includes('yms.jar') || cmd.includes('YMSLauncher')
-  } catch { return false }
+const YMS_MARKERS = ['yms.jar', 'YMSLauncher']
+
+/**
+ * Identity of a pidfile owner: `ours` / `foreign` / `dead` / `unknown`. The four-way
+ * answer matters: a probe that could not read the command line must never be treated
+ * as "not our process" (that deletes the pidfile and starts a second YMS — review
+ * D-P1-6).
+ * @returns {{state: 'ours'|'foreign'|'dead'|'unknown', commandLine: string}}
+ */
+export function probeYmsPid(pid, options = {}) {
+  return pidIdentity(pid, YMS_MARKERS, options)
 }
 
-/** Read the pidfile; verify the process is alive AND ours; null otherwise (stale pidfile is unlinked). */
-export async function readRunning(cfg) {
+/**
+ * Read the pidfile; verify the process is alive AND ours.
+ * @returns {null | {pid: number, state?: 'unknown', reason?: string}}
+ *   `null` when absent/stale/foreign (the stale pidfile is unlinked). An `unknown`
+ *   entry keeps the pidfile and must be treated as "do not start a second one, do not
+ *   kill it blindly".
+ */
+export async function readRunning(cfg, options = {}) {
   const pidFile = ymsPidFile(cfg)
   if (!existsSync(pidFile)) return null
   const pid = Number(readFileSync(pidFile, 'utf8').trim())
-  if (!Number.isInteger(pid) || pid <= 0) return null
-  try { process.kill(pid, 0) } catch { try { unlinkSync(pidFile) } catch { /* ignore */ } return null }
-  if (!pidIsYms(pid)) {
-    // pid reused by an unrelated process after a crash/reboot — stale marker
+  if (!Number.isInteger(pid) || pid <= 0) {
     try { unlinkSync(pidFile) } catch { /* ignore */ }
     return null
   }
-  return { pid }
+  const identity = probeYmsPid(pid, options)
+  if (identity.state === 'ours') return { pid }
+  if (identity.state === 'dead' || identity.state === 'foreign') {
+    // Gone, or the pid was reused by an unrelated process after a crash/reboot.
+    try { unlinkSync(pidFile) } catch { /* ignore */ }
+    return null
+  }
+  return {
+    pid,
+    state: 'unknown',
+    reason: '无法确认 pidfile 进程身份（命令行为空或探测失败），已保留 pidfile 未动',
+  }
 }
 
-/** Stop the detached YMS: TERM, grace (YMS is slow), KILL. */
-export async function stopYms(cfg, { graceMs = 30000 } = {}) {
-  const running = await readRunning(cfg) // identity-verified: never kills a reused pid
+/** Stop the detached YMS: TERM, grace (YMS is slow), KILL; Windows uses taskkill /T /F. */
+export async function stopYms(cfg, { graceMs = 30000, ...options } = {}) {
+  const running = await readRunning(cfg, options) // identity-verified: never kills a reused pid
   if (running === null) return { stopped: false, reason: '未在运行' }
-  try { process.kill(running.pid, 'SIGTERM') } catch { /* ignore */ }
-  const deadline = Date.now() + graceMs
-  while (Date.now() < deadline) {
-    // eslint-disable-next-line no-await-in-loop
-    await new Promise((r) => setTimeout(r, 500))
-    try { process.kill(running.pid, 0) } catch { break }
+  if (running.state === 'unknown') {
+    return {
+      stopped: false,
+      pid: running.pid,
+      reason: `${running.reason}；为避免误杀，未发送停止信号（请手动确认该 pid）`,
+    }
+  }
+  // Windows has no graceful signal path: taskkill the tree; POSIX TERM→grace→KILL.
+  const killed = await stopPid(running.pid, { graceMs, ...options })
+  if (killed.ok !== true) {
+    // Keep the pidfile so `yds status` still shows the process (review D-P1-7).
+    return { stopped: false, pid: running.pid, reason: `停止失败：${killed.error ?? '未知原因'}（已保留 pidfile）` }
   }
-  try { process.kill(running.pid, 0); process.kill(running.pid, 'SIGKILL') } catch { /* gone */ }
   try { unlinkSync(ymsPidFile(cfg)) } catch { /* ignore */ }
   return { stopped: true, pid: running.pid }
 }
@@ -265,6 +298,7 @@ export async function status(cfg) {
   }
   return {
     process: running,
+    processUnknown: running !== null && running.state === 'unknown',
     port,
     ready: ready !== null ? ready.status : null,
     ymsHomeBuilt: ymsHomeIsBuilt(cfg),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ris-yds",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "YonBIP YDS local runtime for the DSH agent: config resolution (project settings.json + optional .env), YYCToken, confcenter sync, SOCKS forward, yms-home build/start/stop with JDWP, and dsh-ris-ide run-config integration. Cross-OS (linux/darwin/win32, WSL aware). · YonBIP YDS 本地运行时：项目配置解析（settings.json / .env）、YYCToken、confcenter 拉取、SOCKS 转发、yms-home 构建与启停（含 JDWP 调试）、dsh-ris-ide 启动器集成；跨平台（linux/darwin/win32，识别 WSL）。",
   "license": "MIT",
   "repository": {

package/test/cli-stop.test.mjs

@@ -0,0 +1,40 @@
+// `yds stop` must not tear the tunnel down under a YMS it could not stop, and its
+// summary must say how much of the shared rule table actually changed (review
+// D-P1-2 / D-P2-7).
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { stopAbortReason, withdrawnText } from '../lib/cli.js'
+
+test('stop aborts when a live YMS pid could not be stopped', () => {
+  const reason = stopAbortReason({ stopped: false, pid: 4242, reason: '停止失败：Access is denied（已保留 pidfile）' })
+  assert.match(reason, /4242/)
+  assert.match(reason, /已中止/)
+  assert.match(reason, /--force/)
+  assert.match(reason, /Access is denied/, 'the original failure is surfaced')
+})
+
+test('stop continues when nothing is running or the stop succeeded', () => {
+  assert.equal(stopAbortReason({ stopped: false, reason: '未在运行' }), '', 'no pid => nothing to protect')
+  assert.equal(stopAbortReason({ stopped: false, pid: 0 }), '')
+  assert.equal(stopAbortReason({ stopped: true, pid: 4242 }), '')
+})
+
+test('--force overrides the guard', () => {
+  assert.equal(stopAbortReason({ stopped: false, pid: 4242, reason: 'unknown' }, { force: true }), '')
+})
+
+test('the summary reports what was withdrawn instead of a blanket claim', () => {
+  assert.match(withdrawnText({ rules: 2, hosts: 3 }), /2 条规则/)
+  assert.match(withdrawnText({ rules: 2, hosts: 3 }), /3 个 host/)
+  assert.match(withdrawnText({ rules: 2, hosts: 3 }), /全局一张表，不区分 workspace/)
+  assert.doesNotMatch(withdrawnText({ rules: 2, hosts: 3 }), /其它 workspace 的规则保留/)
+})
+
+test('a stop that changed nothing says so', () => {
+  for (const withdrawn of [{ rules: 0, hosts: 0 }, undefined, {}]) {
+    const text = withdrawnText(withdrawn)
+    assert.match(text, /共享规则表里没有 yds 规则（未改动）/)
+    assert.doesNotMatch(text, /已撤掉/)
+  }
+})

package/test/hints.test.mjs

@@ -0,0 +1,13 @@
+// Failures an agent reads must carry the command that fixes them: yds can start the
+// local runtime (and the forwarded tunnel) itself, so the message says so.
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import test from 'node:test'
+
+const cli = readFileSync(new URL('../lib/cli.js', import.meta.url), 'utf8')
+
+test('status and doctor point at `yds start` when the runtime is not running', () => {
+  assert.match(cli, /提示: 运行 yds start 可拉起本地运行时（YMS）/, 'doctor hints the start command')
+  assert.match(cli, /YMS 进程: .*提示: 运行 yds start 可拉起本地运行时（YMS）/, 'status does too')
+  assert.match(cli, /未运行（yds start \/ yds proxy start 会拉起）/, 'the tunnel path keeps its hint')
+})

package/test/ide-config.test.mjs

@@ -141,6 +141,10 @@ test('the discovered backend row is disabled and a hijacked startCommand is remo
   ]
   const result = repairYdsRows(cfg, programs)
   assert.deepEqual(result.renamed.map((item) => item.to), ['c-ass-kk-hans-fe'])
+  // The renamed frontend also takes its own log name: the old "<project>-<name>"
+  // value collided with the backend row and both wrote the same log/pidfile.
+  assert.equal(result.programs[2].logName, 'c-ass-kk-hans-fe')
+  assert.deepEqual(result.renamedLogs, [{ name: 'c-ass-kk-hans-fe', from: undefined, to: 'c-ass-kk-hans-fe' }])
   assert.deepEqual(result.disabled.map((item) => item.name), ['dev-c-ass-kk-hans-bootstrap'])
   assert.deepEqual(result.cleaned.map((item) => item.name), ['c-ass-kk-hans-fe'])
   assert.equal(result.programs[0].disabled, undefined, 'our row stays enabled')