agentworkshop 0.7.5 → 0.7.6

package/cli/commands/stop.mjs

@@ -1,108 +1,108 @@
-// ============================================================
-// 指令:stop —— 终止当前配置根下运行中的 aw 实例(读单实例锁 → 终止进程树)。
-// 用法:aw stop [--home]   (--home 强制以 home 配置根为目标;默认随 cwd 解析)
-// ============================================================
-import { existsSync, readFileSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
-import { spawnSync } from 'node:child_process'
-import { color } from '../core/logger.mjs'
-
-export const meta = {
-  name: 'stop',
-  aliases: [],
-  group: '服务',
-  summary: '终止运行中的 aw 服务实例(读单实例锁)',
-  usage: 'aw stop [--home]',
-  needsProject: false,
-}
-
-function pidAlive(pid) {
-  try {
-    process.kill(pid, 0)
-    return true
-  }
-  catch (err) {
-    return err?.code === 'EPERM'
-  }
-}
-
-/** 终止进程树:Windows taskkill /T /F;POSIX 先 SIGTERM 宽限 5s 再 SIGKILL */
-function killTree(pid) {
-  if (process.platform === 'win32') {
-    const r = spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { encoding: 'utf8' })
-    if (r.status !== 0) throw new Error((r.stderr || r.stdout || 'taskkill 失败').trim().split(/\r?\n/)[0])
-    return
-  }
-  try {
-    process.kill(pid, 'SIGTERM')
-  }
-  catch { /* 已死 */ }
-  const deadline = Date.now() + 5000
-  while (Date.now() < deadline && pidAlive(pid)) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200)
-  }
-  if (pidAlive(pid)) {
-    try {
-      process.kill(pid, 'SIGKILL')
-    }
-    catch { /* 已死 */ }
-  }
-}
-
-export async function run(argv, ctx) {
-  // argv 为 parseArgs 结果({ flags, positionals, unknown });兼容裸数组调用
-  const flags = argv?.flags ?? {}
-  const positionals = Array.isArray(argv?.positionals) ? argv.positionals : (Array.isArray(argv) ? argv : [])
-  const forceHome = flags.home === true || positionals.includes('--home')
-
-  const configRoot = forceHome
-    ? ctx.home
-    : (ctx.mode === 'repo' ? join(ctx.root, '.AgentWorkShop') : ctx.home)
-  const lockPath = join(configRoot, '.runtime', 'aw.lock')
-
-  if (!existsSync(lockPath)) {
-    console.log(`${color.blue('ℹ')} 未发现运行中的实例(无锁文件:${lockPath})`)
-    return 0
-  }
-  let holder
-  try {
-    holder = JSON.parse(readFileSync(lockPath, 'utf8'))
-  }
-  catch {
-    rmSync(lockPath, { force: true })
-    console.log(`${color.blue('ℹ')} 锁文件损坏,已清除:${lockPath}`)
-    return 0
-  }
-
-  const pid = Number(holder?.pid)
-  if (!Number.isInteger(pid) || pid <= 0) {
-    rmSync(lockPath, { force: true })
-    console.log(`${color.blue('ℹ')} 锁内 PID 无效,已清除锁文件`)
-    return 0
-  }
-  if (!pidAlive(pid)) {
-    rmSync(lockPath, { force: true })
-    console.log(`${color.blue('ℹ')} 持锁进程已不存在(pid=${pid},残留锁),已清除锁文件`)
-    return 0
-  }
-
-  console.log(`› 终止实例 pid=${pid}(mode=${holder.mode ?? '?'}${holder.port ? `,端口=${holder.port}` : ''},启动于 ${holder.startedAt ?? '?'})`)
-  try {
-    killTree(pid)
-  }
-  catch (err) {
-    console.error(`${color.red('✖')} 终止失败:${err.message}`)
-    console.error(`  可手动执行:taskkill /PID ${pid} /T /F(Windows)`)
-    return 1
-  }
-  // 锁文件由退出钩子自清;残留则手动兜底
-  for (let i = 0; i < 20 && existsSync(lockPath); i++) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200)
-  }
-  try {
-    if (existsSync(lockPath)) rmSync(lockPath, { force: true })
-  }
-  catch { /* ignore */ }
-  console.log(`${color.green('✔')} 实例已停止(pid=${pid})`)
-  return 0
-}
+// ============================================================
+// 指令:stop —— 终止当前配置根下运行中的 aw 实例(读单实例锁 → 终止进程树)。
+// 用法:aw stop [--home]   (--home 强制以 home 配置根为目标;默认随 cwd 解析)
+// ============================================================
+import { existsSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { color } from '../core/logger.mjs'
+
+export const meta = {
+  name: 'stop',
+  aliases: [],
+  group: '服务',
+  summary: '终止运行中的 aw 服务实例(读单实例锁)',
+  usage: 'aw stop [--home]',
+  needsProject: false,
+}
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  }
+  catch (err) {
+    return err?.code === 'EPERM'
+  }
+}
+
+/** 终止进程树:Windows taskkill /T /F;POSIX 先 SIGTERM 宽限 5s 再 SIGKILL */
+function killTree(pid) {
+  if (process.platform === 'win32') {
+    const r = spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { encoding: 'utf8' })
+    if (r.status !== 0) throw new Error((r.stderr || r.stdout || 'taskkill 失败').trim().split(/\r?\n/)[0])
+    return
+  }
+  try {
+    process.kill(pid, 'SIGTERM')
+  }
+  catch { /* 已死 */ }
+  const deadline = Date.now() + 5000
+  while (Date.now() < deadline && pidAlive(pid)) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200)
+  }
+  if (pidAlive(pid)) {
+    try {
+      process.kill(pid, 'SIGKILL')
+    }
+    catch { /* 已死 */ }
+  }
+}
+
+export async function run(argv, ctx) {
+  // argv 为 parseArgs 结果({ flags, positionals, unknown });兼容裸数组调用
+  const flags = argv?.flags ?? {}
+  const positionals = Array.isArray(argv?.positionals) ? argv.positionals : (Array.isArray(argv) ? argv : [])
+  const forceHome = flags.home === true || positionals.includes('--home')
+
+  const configRoot = forceHome
+    ? ctx.home
+    : (ctx.mode === 'repo' ? join(ctx.root, '.AgentWorkShop') : ctx.home)
+  const lockPath = join(configRoot, '.runtime', 'aw.lock')
+
+  if (!existsSync(lockPath)) {
+    console.log(`${color.blue('ℹ')} 未发现运行中的实例(无锁文件:${lockPath})`)
+    return 0
+  }
+  let holder
+  try {
+    holder = JSON.parse(readFileSync(lockPath, 'utf8'))
+  }
+  catch {
+    rmSync(lockPath, { force: true })
+    console.log(`${color.blue('ℹ')} 锁文件损坏,已清除:${lockPath}`)
+    return 0
+  }
+
+  const pid = Number(holder?.pid)
+  if (!Number.isInteger(pid) || pid <= 0) {
+    rmSync(lockPath, { force: true })
+    console.log(`${color.blue('ℹ')} 锁内 PID 无效,已清除锁文件`)
+    return 0
+  }
+  if (!pidAlive(pid)) {
+    rmSync(lockPath, { force: true })
+    console.log(`${color.blue('ℹ')} 持锁进程已不存在(pid=${pid},残留锁),已清除锁文件`)
+    return 0
+  }
+
+  console.log(`› 终止实例 pid=${pid}(mode=${holder.mode ?? '?'}${holder.port ? `,端口=${holder.port}` : ''},启动于 ${holder.startedAt ?? '?'})`)
+  try {
+    killTree(pid)
+  }
+  catch (err) {
+    console.error(`${color.red('✖')} 终止失败:${err.message}`)
+    console.error(`  可手动执行:taskkill /PID ${pid} /T /F(Windows)`)
+    return 1
+  }
+  // 锁文件由退出钩子自清;残留则手动兜底
+  for (let i = 0; i < 20 && existsSync(lockPath); i++) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200)
+  }
+  try {
+    if (existsSync(lockPath)) rmSync(lockPath, { force: true })
+  }
+  catch { /* ignore */ }
+  console.log(`${color.green('✔')} 实例已停止(pid=${pid})`)
+  return 0
+}

package/cli/infra.mjs

@@ -1,109 +1,108 @@
-// ============================================================
-// AgentWorkShop CLI — 数采基础设施前置检查(Docker 编排)
-// ------------------------------------------------------------
-// aw start 启动服务前的引导层:
-//   1. 探测 MQTT / TimescaleDB 端口连通(按有效配置的 host/port)
-//   2. 已连通 → 依赖就绪,直接通过
-//   3. 未连通且本机 Docker 可用且策略允许 → docker compose up -d 拉起并等待端口
-//   4. 无 Docker → 打印回退引导:安装 Docker,或在 config.yml 按需配置外部依赖地址
-// 真正的容器编排与降级重连在服务进程内(server/plugins/daq.ts → ensureDaqInfrastructure);
-// 本模块只做启动前置探测与引导,失败不阻断服务启动(平台降级可用)。
-// ============================================================
-import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { connect } from 'node:net'
-import { join } from 'node:path'
-import { color } from './core/logger.mjs'
-
-/** 本机 Docker 可用性(docker -v) */
-export function detectDocker() {
-  const r = spawnSync('docker', ['-v'], { encoding: 'utf8', shell: process.platform === 'win32' })
-  if (r.status === 0) return { ok: true, version: (r.stdout ?? '').trim().replace(/^Docker version\s*/i, '') }
-  return { ok: false, version: null }
-}
-
-/** TCP 端口连通探测(毫秒级超时;resolve('online'|'offline')) */
-export function probeTcp(port, host = '127.0.0.1', timeoutMs = 1200) {
-  return new Promise((resolveState) => {
-    const sock = connect({ port: Number(port), host })
-    const done = (state) => {
-      sock.destroy()
-      resolveState(state)
-    }
-    sock.setTimeout(timeoutMs)
-    sock.on('connect', () => done('online'))
-    sock.on('timeout', () => done('offline'))
-    sock.on('error', () => done('offline'))
-  })
-}
-
-/** 在 compose 目录执行 docker compose up -d(阻塞至命令结束) */
-export function composeUp(composeDir) {
-  const r = spawnSync('docker', ['compose', 'up', '-d'], {
-    cwd: composeDir,
-    stdio: 'inherit',
-    shell: process.platform === 'win32',
-  })
-  return r.status === 0
-}
-
-/**
- * 数采基础设施前置检查。
- * @param {{ daq: any, configRoot: string }} opts ctx.config 片段与配置根(daQ compose 种子所在)
- * @returns {{ ok: boolean, mqtt: object, timescale: object, docker: object }}
- */
-export async function daqPreflight({ daq, configRoot }) {
-  const mqtt = {
-    host: String(daq?.['daq.mqtt.host'] ?? '127.0.0.1'),
-    port: Number(daq?.['daq.mqtt.port'] ?? 1883),
-    online: null,
-  }
-  const timescale = {
-    host: String(daq?.['daq.timescale.host'] ?? '127.0.0.1'),
-    port: Number(daq?.['daq.timescale.port'] ?? 5432),
-    online: null,
-  }
-  const policy = String(daq?.['daq.startInfrastructure'] ?? 'auto')
-
-  const docker = detectDocker()
-  mqtt.online = (await probeTcp(mqtt.port, mqtt.host)) === 'online'
-  timescale.online = (await probeTcp(timescale.port, timescale.host)) === 'online'
-  const allOnline = mqtt.online && timescale.online
-  const composeDir = existsSync(join(configRoot, 'docker-compose.yml')) ? configRoot : null
-
-  const result = { ok: allOnline, mqtt, timescale, docker, policy, composeDir }
-
-  if (allOnline) return result
-
-  // 未全连通:
-  //  · Docker 可用 + 策略允许(auto/always)+ 本地有 compose 定义 → 拉起并等待端口上线
-  if (docker.ok && policy !== 'never' && composeDir) {
-    console.log(`${color.cyan('›')} 数采依赖未就绪(MQTT ${mqtt.online ? '✓' : '✗'} / Timescale ${timescale.online ? '✓' : '✗'})——docker compose up -d 拉起 ...`)
-    const up = composeUp(composeDir)
-    // 等待端口上线(最长 30s;Timescale 首启初始化较慢)
-    for (let i = 0; i < 15; i++) {
-      await new Promise(r => setTimeout(r, 2000))
-      mqtt.online = (await probeTcp(mqtt.port, mqtt.host)) === 'online'
-      timescale.online = (await probeTcp(timescale.port, timescale.host)) === 'online'
-      if (mqtt.online && timescale.online) break
-    }
-    result.ok = mqtt.online && timescale.online
-    result.pulled = up
-    return result
-  }
-
-  return result
-}
-
-/** 打印回退引导(无 Docker 且依赖不可达时) */
-export function printInfraGuidance({ mqtt, timescale, docker }) {
-  console.log('')
-  console.log(color.yellow('⚠ 数采基础设施不可达(MQTT/TimescaleDB)——服务将继续启动,数采功能降级并每 30s 自动重连。'))
-  console.log(color.dim('  解决方式(二选一):'))
-  console.log(`  ${color.cyan('1.')} 安装 Docker Desktop 后重启本命令,依赖容器将自动拉起`)
-  console.log(`  ${color.cyan('2.')} 在 config.yml 的 daq 段按需配置外部依赖:`)
-  console.log(color.dim(`       daq.mqtt.host/port       (当前 ${mqtt.host}:${mqtt.port} ✗)`))
-  console.log(color.dim(`       daq.timescale.host/port  (当前 ${timescale.host}:${timescale.port} ✗)`))
-  if (!docker.ok) console.log(color.dim('       (本机未检测到 Docker)'))
-  console.log('')
-}
+// ============================================================
+// AgentWorkShop CLI — 数采基础设施前置检查(Docker 编排)
+// ------------------------------------------------------------
+// aw start 启动服务前的引导层:
+//   1. 探测 MQTT / TimescaleDB 端口连通(按有效配置的 host/port)
+//   2. 已连通 → 依赖就绪,直接通过
+//   3. 未连通且本机 Docker 可用且策略允许 → docker compose up -d 拉起并等待端口
+//   4. 无 Docker → 打印回退引导:安装 Docker,或在 config.yml 按需配置外部依赖地址
+// 真正的容器编排与降级重连在服务进程内(server/plugins/daq.ts → ensureDaqInfrastructure);
+// 本模块只做启动前置探测与引导,失败不阻断服务启动(平台降级可用)。
+// ============================================================
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { connect } from 'node:net'
+import { join } from 'node:path'
+import { color } from './core/logger.mjs'
+
+/** 本机 Docker 可用性(docker -v) */
+export function detectDocker() {
+  const r = spawnSync('docker', ['-v'], { encoding: 'utf8' })
+  if (r.status === 0) return { ok: true, version: (r.stdout ?? '').trim().replace(/^Docker version\s*/i, '') }
+  return { ok: false, version: null }
+}
+
+/** TCP 端口连通探测(毫秒级超时;resolve('online'|'offline')) */
+export function probeTcp(port, host = '127.0.0.1', timeoutMs = 1200) {
+  return new Promise((resolveState) => {
+    const sock = connect({ port: Number(port), host })
+    const done = (state) => {
+      sock.destroy()
+      resolveState(state)
+    }
+    sock.setTimeout(timeoutMs)
+    sock.on('connect', () => done('online'))
+    sock.on('timeout', () => done('offline'))
+    sock.on('error', () => done('offline'))
+  })
+}
+
+/** 在 compose 目录执行 docker compose up -d(阻塞至命令结束) */
+export function composeUp(composeDir) {
+  const r = spawnSync('docker', ['compose', 'up', '-d'], {
+    cwd: composeDir,
+    stdio: 'inherit',
+  })
+  return r.status === 0
+}
+
+/**
+ * 数采基础设施前置检查。
+ * @param {{ daq: any, configRoot: string }} opts ctx.config 片段与配置根(daQ compose 种子所在)
+ * @returns {{ ok: boolean, mqtt: object, timescale: object, docker: object }}
+ */
+export async function daqPreflight({ daq, configRoot }) {
+  const mqtt = {
+    host: String(daq?.['daq.mqtt.host'] ?? '127.0.0.1'),
+    port: Number(daq?.['daq.mqtt.port'] ?? 1883),
+    online: null,
+  }
+  const timescale = {
+    host: String(daq?.['daq.timescale.host'] ?? '127.0.0.1'),
+    port: Number(daq?.['daq.timescale.port'] ?? 5432),
+    online: null,
+  }
+  const policy = String(daq?.['daq.startInfrastructure'] ?? 'auto')
+
+  const docker = detectDocker()
+  mqtt.online = (await probeTcp(mqtt.port, mqtt.host)) === 'online'
+  timescale.online = (await probeTcp(timescale.port, timescale.host)) === 'online'
+  const allOnline = mqtt.online && timescale.online
+  const composeDir = existsSync(join(configRoot, 'docker-compose.yml')) ? configRoot : null
+
+  const result = { ok: allOnline, mqtt, timescale, docker, policy, composeDir }
+
+  if (allOnline) return result
+
+  // 未全连通:
+  //  · Docker 可用 + 策略允许(auto/always)+ 本地有 compose 定义 → 拉起并等待端口上线
+  if (docker.ok && policy !== 'never' && composeDir) {
+    console.log(`${color.cyan('›')} 数采依赖未就绪(MQTT ${mqtt.online ? '✓' : '✗'} / Timescale ${timescale.online ? '✓' : '✗'})——docker compose up -d 拉起 ...`)
+    const up = composeUp(composeDir)
+    // 等待端口上线(最长 30s;Timescale 首启初始化较慢)
+    for (let i = 0; i < 15; i++) {
+      await new Promise(r => setTimeout(r, 2000))
+      mqtt.online = (await probeTcp(mqtt.port, mqtt.host)) === 'online'
+      timescale.online = (await probeTcp(timescale.port, timescale.host)) === 'online'
+      if (mqtt.online && timescale.online) break
+    }
+    result.ok = mqtt.online && timescale.online
+    result.pulled = up
+    return result
+  }
+
+  return result
+}
+
+/** 打印回退引导(无 Docker 且依赖不可达时) */
+export function printInfraGuidance({ mqtt, timescale, docker }) {
+  console.log('')
+  console.log(color.yellow('⚠ 数采基础设施不可达(MQTT/TimescaleDB)——服务将继续启动,数采功能降级并每 30s 自动重连。'))
+  console.log(color.dim('  解决方式(二选一):'))
+  console.log(`  ${color.cyan('1.')} 安装 Docker Desktop 后重启本命令,依赖容器将自动拉起`)
+  console.log(`  ${color.cyan('2.')} 在 config.yml 的 daq 段按需配置外部依赖:`)
+  console.log(color.dim(`       daq.mqtt.host/port       (当前 ${mqtt.host}:${mqtt.port} ✗)`))
+  console.log(color.dim(`       daq.timescale.host/port  (当前 ${timescale.host}:${timescale.port} ✗)`))
+  if (!docker.ok) console.log(color.dim('       (本机未检测到 Docker)'))
+  console.log('')
+}

package/config.yml

@@ -10,7 +10,7 @@
 app:
   name: AgentWorkShop
   title: AgentWorkShop
-  version: 0.7.5
+  version: 0.7.6
   description: 基于 Nuxt 4 的配置驱动运行范式
 
 # 运行模式（dev/prod 实际由启动命令决定，此处仅作运行时展示）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentworkshop",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "type": "module",
   "description": "AgentWorkShop 软件开发系统 - 基于 Nuxt 4 的配置驱动运行范式",
   "license": "PolyForm-Noncommercial-1.0.0",

package/scripts/start.mjs

@@ -53,21 +53,44 @@ const prodPort = eff.effective['server.prod.port'] ?? 3000
 const portSource = eff.sources['server.prod.port']
 
 // ---- 单实例互斥(hardening ST-1):同配置根双开直接退出码 2,防 SQLite 锁崩溃 ----
-const { acquireLock } = await import('../shared/config/single-instance.mjs')
-const lock = acquireLock(rm.configRoot, { mode: `prod:${rm.mode}`, port: argPort ? Number(argPort) : prodPort })
+// ---- 单实例互斥 + 自动顶替:同配置根已有实例 → 自动停止后重启新实例(防 SQLite 锁崩溃) ----
+const { acquireLock, checkPort, terminatePid } = await import('../shared/config/single-instance.mjs')
+let requestedPort = argPort ? Number(argPort) : prodPort
+let lock = acquireLock(rm.configRoot, { mode: `prod:${rm.mode}`, port: requestedPort })
 if (!lock.ok) {
   const h = lock.holder
-  console.error(`✖ 已有实例在运行(pid=${h.pid}${h.port ? `,端口=${h.port}` : ''},启动于 ${h.startedAt ?? '未知'},模式=${h.mode ?? '未知'})`)
-  console.error(`  › 配置根: ${rm.configRoot}`)
-  console.error(`  › 如确认是残留锁文件,可删除 ${lock.lockPath} 后重试`)
-  process.exit(2)
+  console.log(`› 发现已运行实例(pid=${h.pid}${h.port ? `,端口=${h.port}` : ''},启动于 ${h.startedAt ?? '未知'})— 自动停止后重启 ...`)
+  const stopped = await terminatePid(h.pid).catch(() => false)
+  if (!stopped) {
+    console.error(`✖ 旧实例(pid=${h.pid})自动停止失败,请手动执行 aw stop 或 taskkill /PID ${h.pid} /T /F`)
+    process.exit(2)
+  }
+  lock = acquireLock(rm.configRoot, { mode: `prod:${rm.mode}`, port: requestedPort })
+  if (!lock.ok) {
+    console.error(`✖ 旧实例已停止但锁仍被占用(可能并发启动):pid=${lock.holder?.pid ?? '?'}`)
+    process.exit(2)
+  }
+}
+
+// ---- 端口顺延:配置端口被任意进程占用(含其他配置根的实例)→ 逐个 +1(最多 10 次) ----
+let port = requestedPort
+let bumped = 0
+while (bumped < 10 && await checkPort(host, port)) {
+  console.log(`› 端口 ${port} 被占用,顺延至 ${port + 1} ...`)
+  port += 1
+  bumped += 1
+}
+if (bumped >= 10) {
+  console.error(`✖ ${host} 上 ${requestedPort}-${port} 全部被占用,无法启动`)
+  process.exit(1)
 }
+if (bumped > 0) console.log(`✔ 使用顺延端口 ${port}(配置端口 ${requestedPort} 被占用)`)
 
 process.env.HOST = process.env.HOST || process.env.NITRO_HOST || String(host)
-process.env.PORT = process.env.PORT || process.env.NITRO_PORT || String(prodPort)
+process.env.PORT = process.env.PORT || process.env.NITRO_PORT || String(port)
 process.env.NITRO_HOST = process.env.HOST
 process.env.NITRO_PORT = process.env.PORT
 
-console.log(`[config] 生产服务启动 -> http://${process.env.HOST}:${process.env.PORT}  (模式: ${rm.mode}, port source: ${portSource})`)
+console.log(`[config] 生产服务启动 -> http://${process.env.HOST}:${process.env.PORT}  (模式: ${rm.mode}, port source: ${portSource}${bumped > 0 ? ' + 顺延' : ''})`)
 
 await import('../.output/server/index.mjs')

package/shared/config/single-instance.mjs

@@ -1,86 +1,129 @@
-// ============================================================
-// 单实例互斥(hardening ST-1)—— 零依赖,CLI / 启动脚本通用。
-// 锁文件 <configRoot>/.runtime/aw.lock 原子创建(wx):
-//   { pid, startedAt, mode, port }
-// 已存在且 PID 存活 → 视为已有实例(返回冲突信息,调用方以退出码 2 退出);
-// PID 已死(崩溃/强杀残留) → 自动接管重写。进程退出时 releaseLock 兜底清理。
-// ============================================================
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-
-function pidAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false
-  try {
-    // signal 0 探活:进程存在但不发信号;ESRCH=不存在,EPERM=存在(他人进程)
-    process.kill(pid, 0)
-    return true
-  }
-  catch (err) {
-    return err?.code === 'EPERM'
-  }
-}
-
-/**
- * 尝试获取单实例锁。
- * @returns {{ ok: true, lockPath: string, release: () => void }
- *   | { ok: false, lockPath: string, holder: { pid: number, startedAt: string, mode: string, port: number | null } }}
- */
-export function acquireLock(configRoot, { mode = 'prod', port = null } = {}) {
-  const runtimeDir = join(configRoot, '.runtime')
-  const lockPath = join(runtimeDir, 'aw.lock')
-  mkdirSync(runtimeDir, { recursive: true })
-  if (existsSync(lockPath)) {
-    let holder = null
-    try {
-      holder = JSON.parse(readFileSync(lockPath, 'utf8'))
-    }
-    catch { /* 损坏锁文件按残留处理 */ }
-    if (holder && pidAlive(holder.pid)) {
-      return { ok: false, lockPath, holder: { ...holder, port: holder.port ?? null } }
-    }
-    try { rmSync(lockPath) } catch { /* 抢不掉则下方 wx 再失败 */ }
-  }
-  const me = { pid: process.pid, startedAt: new Date().toISOString(), mode, port }
-  try {
-    writeFileSync(lockPath, JSON.stringify(me, null, 2), { flag: 'wx' })
-  }
-  catch (err) {
-    // 与并发启动者竞态:按冲突处理
-    let holder = null
-    try { holder = JSON.parse(readFileSync(lockPath, 'utf8')) } catch { /* ignore */ }
-    if (holder && pidAlive(holder.pid)) {
-      return { ok: false, lockPath, holder: { ...holder, port: holder.port ?? null } }
-    }
-    throw err
-  }
-  let released = false
-  const release = () => {
-    if (released) return
-    released = true
-    try {
-      const cur = JSON.parse(readFileSync(lockPath, 'utf8'))
-      if (cur?.pid !== process.pid) return // 锁已被他人接管,不误删
-      rmSync(lockPath)
-    }
-    catch { /* 已不存在/损坏,忽略 */ }
-  }
-  process.once('exit', release)
-  process.once('SIGINT', () => { release(); process.exit(130) })
-  process.once('SIGTERM', () => { release(); process.exit(143) })
-  return { ok: true, lockPath, release }
-}
-
-/** 端口占用探测:返回占用进程 PID(未占用返回 null)。TCP try-listen 后立刻释放。 */
-export async function checkPort(host, port) {
-  const net = await import('node:net')
-  return new Promise((resolveProbe) => {
-    const srv = net.createServer()
-    srv.once('error', (err) => {
-      resolveProbe(err?.code === 'EADDRINUSE' ? port : null)
-      srv.close()
-    })
-    srv.listen(port, host, () => {
-      srv.close(() => resolveProbe(null))
-    })
-  })
-}
+// ============================================================
+// 单实例互斥(hardening ST-1)—— 零依赖,CLI / 启动脚本通用。
+// 锁文件 <configRoot>/.runtime/aw.lock 原子创建(wx):
+//   { pid, startedAt, mode, port }
+// 已存在且 PID 存活 → 视为已有实例(返回冲突信息,调用方以退出码 2 退出);
+// PID 已死(崩溃/强杀残留) → 自动接管重写。进程退出时 releaseLock 兜底清理。
+// ============================================================
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    // signal 0 探活:进程存在但不发信号;ESRCH=不存在,EPERM=存在(他人进程)
+    process.kill(pid, 0)
+    return true
+  }
+  catch (err) {
+    return err?.code === 'EPERM'
+  }
+}
+
+const waitSync = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+
+/**
+ * 终止进程树并等待其死亡(供 `aw stop` 与 start 的"顶掉旧实例"共用)。
+ * Windows:taskkill /T /F;POSIX:SIGTERM 宽限 5s → SIGKILL。
+ * @returns {Promise<boolean>} 是否已确认死亡
+ */
+export async function terminatePid(pid) {
+  if (!pidAlive(pid)) return true
+  if (process.platform === 'win32') {
+    const { spawnSync } = await import('node:child_process')
+    const r = spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { encoding: 'utf8' })
+    if (r.status !== 0) return !pidAlive(pid)
+  }
+  else {
+    try {
+      process.kill(pid, 'SIGTERM')
+    }
+    catch { /* 已死 */ }
+    const deadline = Date.now() + 5000
+    while (Date.now() < deadline && pidAlive(pid)) waitSync(200)
+    if (pidAlive(pid)) {
+      try {
+        process.kill(pid, 'SIGKILL')
+      }
+      catch { /* 已死 */ }
+    }
+  }
+  const deadline = Date.now() + 5000
+  while (Date.now() < deadline && pidAlive(pid)) waitSync(200)
+  return !pidAlive(pid)
+}
+
+/**
+ * 尝试获取单实例锁。
+ * @returns {{ ok: true, lockPath: string, release: () => void }
+ *   | { ok: false, lockPath: string, holder: { pid: number, startedAt: string, mode: string, port: number | null } }}
+ */
+export function acquireLock(configRoot, { mode = 'prod', port = null } = {}) {
+  const runtimeDir = join(configRoot, '.runtime')
+  const lockPath = join(runtimeDir, 'aw.lock')
+  mkdirSync(runtimeDir, { recursive: true })
+  if (existsSync(lockPath)) {
+    let holder = null
+    try {
+      holder = JSON.parse(readFileSync(lockPath, 'utf8'))
+    }
+    catch { /* 损坏锁文件按残留处理 */ }
+    if (holder && pidAlive(holder.pid)) {
+      return { ok: false, lockPath, holder: { ...holder, port: holder.port ?? null } }
+    }
+    try {
+      rmSync(lockPath)
+    }
+    catch { /* 抢不掉则下方 wx 再失败 */ }
+  }
+  const me = { pid: process.pid, startedAt: new Date().toISOString(), mode, port }
+  try {
+    writeFileSync(lockPath, JSON.stringify(me, null, 2), { flag: 'wx' })
+  }
+  catch (err) {
+    // 与并发启动者竞态:按冲突处理
+    let holder = null
+    try {
+      holder = JSON.parse(readFileSync(lockPath, 'utf8'))
+    }
+    catch { /* ignore */ }
+    if (holder && pidAlive(holder.pid)) {
+      return { ok: false, lockPath, holder: { ...holder, port: holder.port ?? null } }
+    }
+    throw err
+  }
+  let released = false
+  const release = () => {
+    if (released) return
+    released = true
+    try {
+      const cur = JSON.parse(readFileSync(lockPath, 'utf8'))
+      if (cur?.pid !== process.pid) return // 锁已被他人接管,不误删
+      rmSync(lockPath)
+    }
+    catch { /* 已不存在/损坏,忽略 */ }
+  }
+  const releaseAndExit = (code) => {
+    release()
+    process.exit(code)
+  }
+  process.once('exit', release)
+  process.once('SIGINT', () => releaseAndExit(130))
+  process.once('SIGTERM', () => releaseAndExit(143))
+  return { ok: true, lockPath, release }
+}
+
+/** 端口占用探测:返回占用进程 PID(未占用返回 null)。TCP try-listen 后立刻释放。 */
+export async function checkPort(host, port) {
+  const net = await import('node:net')
+  return new Promise((resolveProbe) => {
+    const srv = net.createServer()
+    srv.once('error', (err) => {
+      resolveProbe(err?.code === 'EADDRINUSE' ? port : null)
+      srv.close()
+    })
+    srv.listen(port, host, () => {
+      srv.close(() => resolveProbe(null))
+    })
+  })
+}

package/tui/lib/config.mjs

@@ -1,58 +1,62 @@
-// ============================================================
-// TUI 认证/连接配置 —— 落配置根 .AgentWorkShop/tui-auth.json(0600)。
-// 解析口径与服务端一致:cwd 向上找 config.yml → <repo>/.AgentWorkShop,
-// 找不到(全局安装任意 cwd)→ ~/.AgentWorkShop。
-// ============================================================
-import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join, resolve, dirname } from 'node:path'
-
-/** 向上查找文件(repo 模式判定) */
-function findUp(startDir, filename) {
-  let dir = resolve(startDir)
-  for (;;) {
-    const candidate = join(dir, filename)
-    if (existsSync(candidate)) return candidate
-    const parent = dirname(dir)
-    if (parent === dir) return null
-    dir = parent
-  }
-}
-
-/** 配置根(repo 内 cwd → <repo>/.AgentWorkShop;否则 ~/.AgentWorkShop) */
-export function configRoot(cwd = process.cwd()) {
-  const marker = findUp(cwd, 'config.yml')
-  if (marker) return join(dirname(marker), '.AgentWorkShop')
-  return join(homedir(), '.AgentWorkShop')
-}
-
-const authPath = cwd => join(configRoot(cwd), 'tui-auth.json')
-
-/** 读取已存凭据({ baseUrl, token, email? } 或 null) */
-export function loadAuth(cwd = process.cwd()) {
-  try {
-    const raw = JSON.parse(readFileSync(authPath(cwd), 'utf8'))
-    if (raw && typeof raw.token === 'string' && typeof raw.baseUrl === 'string') return raw
-  }
-  catch { /* 无凭据/损坏 → 重新登录 */ }
-  return null
-}
-
-/** 持久化凭据(0600;路径加入 .gitignore) */
-export function saveAuth(auth, cwd = process.cwd()) {
-  const file = authPath(cwd)
-  mkdirSync(dirname(file), { recursive: true })
-  writeFileSync(file, `${JSON.stringify(auth, null, 2)}\n`, 'utf8')
-  try {
-    chmodSync(file, 0o600)
-  }
-  catch { /* Windows FAT 卷 chmod 无效,忽略 */ }
-}
-
-/** 清除凭据(登出) */
-export function clearAuth(cwd = process.cwd()) {
-  try {
-    existsSync(authPath(cwd)) && (writeFileSync(authPath(cwd), '{}\n', 'utf8'), true)
-  }
-  catch { /* 尽力而为 */ }
-}
+// ============================================================
+// TUI 认证/连接配置 —— 落配置根 .AgentWorkShop/tui-auth.json(0600)。
+// 解析口径与服务端一致:cwd 向上找 config.yml → <repo>/.AgentWorkShop,
+// 找不到(全局安装任意 cwd)→ ~/.AgentWorkShop。
+// ============================================================
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve, dirname } from 'node:path'
+
+/** 向上查找文件(repo 模式判定) */
+function findUp(startDir, filename) {
+  let dir = resolve(startDir)
+  for (;;) {
+    const candidate = join(dir, filename)
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** 配置根(与服务端同策略):仅当用户自建了 <检出根>/.AgentWorkShop 时优先使用;
+ *  否则一律回落 ~/.AgentWorkShop(绝不在 pwd 下自动创建)。 */
+export function configRoot(cwd = process.cwd()) {
+  const marker = findUp(cwd, 'config.yml')
+  if (marker) {
+    const candidate = join(dirname(marker), '.AgentWorkShop')
+    if (existsSync(candidate)) return candidate
+  }
+  return join(homedir(), '.AgentWorkShop')
+}
+
+const authPath = cwd => join(configRoot(cwd), 'tui-auth.json')
+
+/** 读取已存凭据({ baseUrl, token, email? } 或 null) */
+export function loadAuth(cwd = process.cwd()) {
+  try {
+    const raw = JSON.parse(readFileSync(authPath(cwd), 'utf8'))
+    if (raw && typeof raw.token === 'string' && typeof raw.baseUrl === 'string') return raw
+  }
+  catch { /* 无凭据/损坏 → 重新登录 */ }
+  return null
+}
+
+/** 持久化凭据(0600;路径加入 .gitignore) */
+export function saveAuth(auth, cwd = process.cwd()) {
+  const file = authPath(cwd)
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(auth, null, 2)}\n`, 'utf8')
+  try {
+    chmodSync(file, 0o600)
+  }
+  catch { /* Windows FAT 卷 chmod 无效,忽略 */ }
+}
+
+/** 清除凭据(登出) */
+export function clearAuth(cwd = process.cwd()) {
+  try {
+    existsSync(authPath(cwd)) && (writeFileSync(authPath(cwd), '{}\n', 'utf8'), true)
+  }
+  catch { /* 尽力而为 */ }
+}