dsh-mesh-node 0.0.0-stage → 0.0.1

package/src/core/peer-doctor.js

@@ -0,0 +1,294 @@
+/**
+ * Diagnose one paired peer end to end: can this machine reach it, does a DSH
+ * profile mount it, and do the running DSH instances actually expose its tools?
+ *
+ * Every check corresponds to a failure mode observed in the field:
+ * - missing certificate pin / token -> refused handshake or 401;
+ * - https peer without NODE_EXTRA_CA_CERTS in the DSH process -> silent
+ *   "mcp-client(home): server is disconnected" and zero tools;
+ * - overlay mounted but zero tools -> the in-DSH client failed to start
+ *   (DSH hot-reloads cordis.patch.yml, so a restart is the last resort, not
+ *   the first fix);
+ * - ACL/upgrade drift -> tools exist but calls return E_DENIED on the peer.
+ *
+ * The command is read-only: it never starts, stops, or reconfigures anything.
+ */
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { loadConfig, peersPath } from './config.js'
+import { loadPeers } from './pairing.js'
+import { createHostClient, hostInstances } from './host-agent.js'
+import { connectPeer } from './peer-client.js'
+
+const quiet = { debug() {}, info() {}, warn() {}, error() {} }
+
+/** DSH state directories worth scanning, most specific first. */
+export function dshHomeCandidates(env = process.env) {
+  const homes = []
+  const push = (value) => {
+    if (value && !homes.includes(value)) homes.push(value)
+  }
+  push(env.DSH_HOME)
+  for (const suffix of ['.dsh0', '.dsh1', '.dsh2', '.dsh3', '.dsh']) push(join(homedir(), suffix))
+  return homes
+}
+
+/** Which transport the entry around `lineIndex` declares (search a small window). */
+function transportFor(lines, lineIndex) {
+  for (let index = lineIndex; index >= 0 && index >= lineIndex - 25; index -= 1) {
+    const match = lines[index].match(/transport:\s*['"]?([A-Za-z-]+)/)
+    if (match) return match[1]
+    if (index < lineIndex && /^\s*-\s+insert:/.test(lines[index])) break
+  }
+  return 'unknown'
+}
+
+/** Resolve a path for comparison even when it does not exist yet (junction-aware). */
+function canonicalPath(value) {
+  try {
+    return realpathSync(value)
+  } catch {
+    return resolve(value)
+  }
+}
+
+/**
+ * True when an overlay's patch file lives in exactly this DSH profile directory.
+ * An overlay found through another instance's home (or through a `~/.dsh`
+ * junction pointing at `~/.dsh0`) must never be credited to another instance.
+ */
+export function overlayMatchesProfile(overlay, profileDir) {
+  if (!overlay?.patchPath || !profileDir) return false
+  const overlayDir = canonicalPath(dirname(overlay.patchPath))
+  const wanted = canonicalPath(profileDir)
+  return process.platform === 'win32' ? overlayDir.toLowerCase() === wanted.toLowerCase() : overlayDir === wanted
+}
+
+/**
+ * Find DSH profile overlays that mount this peer (matched by serverName).
+ * Pure filesystem read; returns one row per matching overlay.
+ */
+export function findPeerOverlays(peer, { env = process.env, dshHomes = null } = {}) {
+  const names = new Set([peer?.name, peer?.id, `${peer?.name}-mesh`, `${peer?.id}-mesh`].filter(Boolean))
+  const matches = []
+  const seen = new Set()
+  for (const dshHome of dshHomes ?? dshHomeCandidates(env)) {
+    const profilesDir = join(dshHome, 'profiles')
+    if (!existsSync(profilesDir)) continue
+    let profiles
+    try {
+      profiles = readdirSync(profilesDir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const profile of profiles) {
+      if (!profile.isDirectory()) continue
+      const patchPath = join(profilesDir, profile.name, 'cordis.patch.yml')
+      if (!existsSync(patchPath)) continue
+      let text
+      try {
+        text = readFileSync(patchPath, 'utf8')
+      } catch {
+        continue
+      }
+      if (!text.includes('dsh-mcp-client')) continue
+      const lines = text.split(/\r?\n/)
+      for (let index = 0; index < lines.length; index += 1) {
+        const match = lines[index].match(/^\s*serverName:\s*['"]?([^'"\s]+)['"]?\s*$/)
+        if (!match || !names.has(match[1])) continue
+        const key = `${canonicalPath(patchPath)}::${match[1]}`
+        if (seen.has(key)) continue
+        seen.add(key)
+        matches.push({
+          dshHome,
+          profile: profile.name,
+          patchPath,
+          serverName: match[1],
+          transport: transportFor(lines, index)
+        })
+      }
+    }
+  }
+  return matches
+}
+
+function hintForConnectFailure(code) {
+  if (code === 'E_PEER_PIN_MISMATCH') {
+    return 'the peer certificate changed or the stored pin is wrong: re-pair with `peer add` and the fingerprint printed by `pair --code`'
+  }
+  if (code === 'E_PEER_NO_PIN') {
+    return 'https peer without a fingerprint: `peer import --file <name>.yml --fingerprint <sha256>`'
+  }
+  if (code === 'E_PEER_AUTH') {
+    return 'token rejected: re-pair (`peer add`), or the peer revoked the token (`revoke` on that node)'
+  }
+  if (code === 'E_PEER_TIMEOUT') {
+    return 'no answer in time: check the peer is up (`node src/cli.js cluster status`), the frp tunnel, and that `serve` runs there'
+  }
+  return 'check the peer node: `node src/cli.js cluster status` and the peer’s own mesh serve log'
+}
+
+/**
+ * Run all checks and return {verdict, checks, nextSteps}. `verdict` is `fail`
+ * only when a hard requirement (peer record, pin, handshake) fails; mount and
+ * environment findings are `warn` unless they would make in-session tools
+ * silently absent without any explanation.
+ */
+export async function runPeerDoctor({ home, target = null, timeoutMs = 8000, env = process.env, dshHomes = null } = {}) {
+  const checks = []
+  const add = (id, status, detail, fix) => checks.push({ id, status, detail, ...(fix ? { fix } : {}) })
+  const peers = loadPeers(home)
+  const items = peers.items ?? []
+  add(
+    'peers-file',
+    items.length > 0 ? 'pass' : 'fail',
+    `${peersPath(home)}: ${items.length} peer record(s)`,
+    items.length > 0 ? undefined : 'node src/cli.js peer import --file <name>.yml'
+  )
+
+  const peer = target
+    ? items.find((item) => item.name === target || item.id === target)
+    : items.length === 1
+      ? items[0]
+      : null
+  if (!peer) {
+    add(
+      'peer-selection',
+      'fail',
+      target
+        ? `peer "${target}" is not in ${peersPath(home)}`
+        : `several peers are paired (${items.map((item) => item.name).join(', ')}); pass --to <name>`,
+      'node src/cli.js peer list'
+    )
+    return { verdict: 'fail', checks, nextSteps: ['pick a peer with --to <name>'] }
+  }
+  add('peer-selection', 'pass', `peer "${peer.name}" -> ${peer.url}`)
+
+  const secure = /^https:/i.test(peer.url)
+  if (secure) {
+    add(
+      'certificate-pin',
+      peer.certFingerprint ? 'pass' : 'fail',
+      peer.certFingerprint
+        ? `pinned ${String(peer.certFingerprint).slice(0, 23)}…`
+        : 'https peer has no stored fingerprint; the pinned fetch refuses to connect',
+      peer.certFingerprint
+        ? undefined
+        : 'node src/cli.js peer import --file <name>.yml --fingerprint <sha256 from `pair --code`>'
+    )
+  } else {
+    add('certificate-pin', 'pass', 'plain http peer — no TLS trust needed (not recommended across machines)')
+  }
+
+  const overlays = findPeerOverlays(peer, { env, dshHomes })
+  const httpOverlay = overlays.find((entry) => entry.transport !== 'stdio')
+  const overlayDetail = overlays.map((entry) => `${entry.dshHome}/profiles/${entry.profile} (${entry.transport})`).join('; ')
+  const caEnv = env.NODE_EXTRA_CA_CERTS || ''
+  if (secure && httpOverlay && !caEnv) {
+    add(
+      'dsh-ca-env',
+      'warn',
+      'NODE_EXTRA_CA_CERTS unset in this process and an overlay uses streamable-http: the in-DSH client cannot verify the self-signed peer and stays disconnected',
+      `switch it to the stdio bridge: node src/cli.js peer patch --transport stdio --to ${peer.name}`
+    )
+  } else if (secure) {
+    add(
+      'dsh-ca-env',
+      'pass',
+      caEnv ? `NODE_EXTRA_CA_CERTS=${caEnv}` : 'not needed: the stdio bridge pins the peer certificate itself'
+    )
+  }
+
+  if (overlays.length === 0) {
+    add(
+      'dsh-overlay',
+      'warn',
+      'no DSH profile overlay mounts this peer, so only CLI calls work',
+      `node src/cli.js peer patch --transport stdio --to ${peer.name}`
+    )
+  } else {
+    add('dsh-overlay', 'pass', overlayDetail)
+  }
+
+  // Did the RUNNING instances actually register the peer tools? This is the only
+  // check that distinguishes "overlay is valid" from "overlay is live".
+  try {
+    const config = loadConfig(home)
+    const instances = hostInstances(config)
+    if (instances.length === 0) {
+      add('dsh-live-tools', 'warn', 'no host bridge configured, so loaded tools cannot be verified', 'node src/cli.js host install --profile <DSH profile>')
+    }
+    for (const entry of instances) {
+      const client = createHostClient({ config, home, log: quiet, instance: entry.id })
+      const alive = await client.ping().catch(() => false)
+      if (!alive) {
+        add(`dsh-${entry.id}`, 'warn', 'host bridge not reachable — its loaded tools cannot be verified')
+        continue
+      }
+      const { tools } = await client.tools().catch(() => ({ tools: [] }))
+      const names = (tools ?? []).map((tool) => tool.name)
+      const mounted = names.filter((name) => name.startsWith(`mcp__${peer.name}__`) || name.startsWith(`mcp__${peer.name}-mesh__`))
+      const ownOverlays = entry.profileDir
+        ? overlays.filter((overlay) => overlayMatchesProfile(overlay, entry.profileDir))
+        : overlays
+      if (mounted.length > 0) {
+        add(`dsh-${entry.id}`, 'pass', `${mounted.length} peer tool(s) registered (e.g. ${mounted[0]})`)
+      } else if (ownOverlays.length > 0) {
+        add(
+          `dsh-${entry.id}`,
+          'warn',
+          `overlay is mounted in ${entry.profileDir} but this running instance exposes 0 "${peer.name}" tools (${names.length} total)`,
+          'DSH hot-reloads cordis.patch.yml (HMR) within seconds; if the tools stay missing, check the mcp-client startup error in the DSH log — restart only as a last resort'
+        )
+      } else {
+        add(
+          `dsh-${entry.id}`,
+          'warn',
+          `no overlay in this instance's profile (${entry.profileDir || 'unknown'}), so it can never expose peer tools (${names.length} tools total)`,
+          entry.profileDir
+            ? `add the peer insert block to ${join(entry.profileDir, 'cordis.patch.yml')} (HMR picks it up, no restart)`
+            : undefined
+        )
+      }
+    }
+  } catch (error) {
+    add('dsh-live-tools', 'warn', `could not inspect running instances: ${error?.message || error}`)
+  }
+
+  let connection
+  const started = Date.now()
+  try {
+    connection = await connectPeer(peer, { timeoutMs })
+    const listed = await connection.client.listTools()
+    add('mcp-handshake', 'pass', `initialized and listed ${(listed.tools ?? []).length} tools in ${Date.now() - started} ms`)
+  } catch (error) {
+    const code = typeof error?.code === 'string' ? error.code : null
+    add('mcp-handshake', 'fail', `${code ? `[${code}] ` : ''}${error?.message || error}`, hintForConnectFailure(code))
+  } finally {
+    if (connection) await connection.close()
+  }
+
+  const verdict = checks.some((check) => check.status === 'fail')
+    ? 'fail'
+    : checks.some((check) => check.status === 'warn')
+      ? 'warn'
+      : 'ok'
+  const nextSteps = []
+  const caMissing = secure && !caEnv
+  if (httpOverlay && caMissing) {
+    nextSteps.push(`switch the overlay to the stdio bridge: node src/cli.js peer patch --transport stdio --to ${peer.name}`)
+  }
+  if (overlays.length === 0) {
+    nextSteps.push(`mount the peer in DSH: node src/cli.js peer patch --transport stdio --to ${peer.name}`)
+  }
+  const staleLive = checks.filter(
+    (check) => check.id.startsWith('dsh-') && check.status === 'warn' && /overlay is mounted in/.test(check.detail)
+  )
+  if (staleLive.length > 0) {
+    nextSteps.push(
+      'DSH hot-reloads cordis.patch.yml (HMR): re-run this doctor after ~10 s; restart the instance only if the tools stay missing (read its mcp-client startup error first)'
+    )
+  }
+  return { verdict, peer: { name: peer.name, url: peer.url, secure }, checks, nextSteps }
+}

package/src/core/peer-http.js

@@ -0,0 +1,61 @@
+/**
+ * Minimal HTTP(S) JSON POST used for peer pairing.
+ *
+ * 两个安全选项：
+ * - `caPath`：信任一张自签证书（标准信任链校验）。
+ * - `fingerprint`：TOFU 固定指纹 —— 先不判信任链（自签必然不过），抓 socket 上的
+ *   对端证书算 SHA-256，再和人工核对过的指纹比对；不一致直接 `E_PIN_MISMATCH`。
+ *
+ * 抽成独立文件是为了让 e2e 能直接测（cli.js 有 main 副作用，不适合被 import）。
+ */
+import { fingerprintOfSocket, assertFingerprint } from './tls.js'
+
+export async function postJson(urlString, body, { caPath, fingerprint } = {}) {
+  const isHttps = String(urlString).startsWith('https:')
+  const { request } = await import(isHttps ? 'node:https' : 'node:http')
+  const { readFileSync } = await import('node:fs')
+  const options = { method: 'POST', headers: { 'content-type': 'application/json' } }
+  if (isHttps && caPath) options.ca = readFileSync(caPath)
+  // 固定指纹时先不判信任链（自签必然不过），拿到 socket 证书后自己比对指纹。
+  // 这是 TOFU 的标准做法：信任来自「配对码那条可信信道」里带出来的指纹，而不是 CA。
+  if (isHttps && fingerprint) {
+    options.rejectUnauthorized = false
+    // 关键：不能复用 keep-alive 连接 —— 复用时会话已建立，secureConnect 不会再触发，
+    // 指纹校验就会被跳过。每次固定指纹请求都开新连接。
+    options.agent = false
+  }
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const req = request(urlString, options, (res) => {
+      let text = ''
+      res.setEncoding('utf8')
+      res.on('data', (chunk) => {
+        text += chunk
+      })
+      res.on('end', () => {
+        let parsed
+        try {
+          parsed = JSON.parse(text)
+        } catch {
+          parsed = { raw: text }
+        }
+        resolvePromise({ status: res.statusCode, body: parsed, fingerprint: req.__meshFingerprint })
+      })
+    })
+    if (isHttps && fingerprint) {
+      req.on('socket', (socket) => {
+        socket.once('secureConnect', () => {
+          try {
+            const got = fingerprintOfSocket(socket)
+            assertFingerprint(fingerprint, got)
+            req.__meshFingerprint = got
+          } catch (error) {
+            req.destroy(error)
+          }
+        })
+      })
+    }
+    req.setTimeout(20000, () => req.destroy(new Error('timeout')))
+    req.on('error', rejectPromise)
+    req.end(JSON.stringify(body ?? {}))
+  })
+}

package/src/core/repair.js

@@ -0,0 +1,93 @@
+import { isAbsolute, join, resolve, sep } from 'node:path'
+
+/**
+ * Pure helpers for the repair toolkit (M7 step 3). Keeping the path/validation
+ * logic here means the MCP tool, the CLI and the selftest all agree on what a
+ * legal plugin payload is — writing into a DSH profile is the one operation that
+ * can brick an instance, so it gets validated in exactly one place.
+ */
+
+export const PLUGIN_NAME_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]{0,63}$/i
+
+export function repairError(code, message, extra = {}) {
+  const error = new Error(message)
+  error.code = code
+  Object.assign(error, extra)
+  return error
+}
+
+/** Directory a plugin package occupies inside a profile's node_modules. */
+export function pluginRoot(profileDir, name) {
+  return join(profileDir, 'node_modules', ...String(name).split('/'))
+}
+
+/**
+ * Validate and normalise a plugin file payload.
+ * `path` is always a forward-slash relative path inside the package directory.
+ */
+export function normalizePluginFiles(files, { maxFiles = 20, maxFileBytes = 262144 } = {}) {
+  if (!Array.isArray(files) || files.length === 0) {
+    throw repairError('E_INVALID_ARG', 'files must be a non-empty array of {path, content}')
+  }
+  if (files.length > maxFiles) {
+    throw repairError('E_INVALID_ARG', `too many files: ${files.length} > ${maxFiles}`)
+  }
+  const seen = new Set()
+  return files.map((file, index) => {
+    const raw = typeof file?.path === 'string' ? file.path : ''
+    const rel = raw.replace(/\\/g, '/').replace(/^\.\//, '')
+    if (!rel) throw repairError('E_INVALID_ARG', `files[${index}].path is required`)
+    if (isAbsolute(rel) || /^[a-z]:/i.test(rel)) {
+      throw repairError('E_INVALID_ARG', `files[${index}].path must be relative: ${raw}`)
+    }
+    const parts = rel.split('/').filter((part) => part.length > 0)
+    if (parts.length === 0 || parts.some((part) => part === '.' || part === '..')) {
+      throw repairError('E_INVALID_ARG', `files[${index}].path escapes the package root: ${raw}`)
+    }
+    const content = typeof file?.content === 'string' ? file.content : null
+    if (content === null) throw repairError('E_INVALID_ARG', `files[${index}].content must be a string`)
+    const bytes = Buffer.byteLength(content, 'utf8')
+    if (bytes > maxFileBytes) {
+      throw repairError('E_INVALID_ARG', `files[${index}] is ${bytes} bytes > limit ${maxFileBytes}`)
+    }
+    const key = parts.join('/').toLowerCase()
+    if (seen.has(key)) throw repairError('E_INVALID_ARG', `duplicate file path: ${rel}`)
+    seen.add(key)
+    return { rel: parts.join('/'), abs: parts.join(sep), content, bytes }
+  })
+}
+
+/** True when the profile patch already wires a plugin by name or id. */
+export function patchHasPlugin(patchText, name) {
+  const text = String(patchText || '')
+  if (!text) return false
+  const escaped = String(name).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`(^|[\\s-])(name|id):\\s*['"]?${escaped}['"]?\\s*$`, 'm').test(text)
+}
+
+export function buildPatchBlock(name) {
+  return `- insert:\n    - id: ${name}\n      name: ${name}\n`
+}
+
+/**
+ * Append a `- insert:` block unless the plugin is already wired.
+ * A non-empty, non-`[]` patch is preserved and flagged for backup by the caller.
+ */
+export function applyPatchInsert(patchText, name) {
+  const current = String(patchText ?? '')
+  if (patchHasPlugin(current, name)) return { text: current, changed: false, backup: false }
+  const trimmed = current.trim()
+  const needsBackup = Boolean(trimmed && trimmed !== '[]')
+  const header = needsBackup ? `${current.replace(/\s+$/, '')}\n` : ''
+  return { text: header + buildPatchBlock(name), changed: true, backup: needsBackup }
+}
+
+/** Resolve `candidate` and assert it stays inside `root` (profile confinement). */
+export function assertInside(root, candidate) {
+  const base = resolve(root)
+  const target = resolve(candidate)
+  if (target !== base && !target.startsWith(base + sep)) {
+    throw repairError('E_INVALID_ARG', `path escapes the allowed root: ${target}`)
+  }
+  return target
+}

package/src/core/restart-policy.js

@@ -0,0 +1,21 @@
+// @generated 2026-10-27 repair 重启命令的**运行期**白名单（不只是编辑期校验）
+// [why] 2026-10-27 P2 安全收紧：`repair.restartScripts` 是「配置即白名单」，但配置可以被手改/被别的工具写。
+//       如果只在写配置时校验，手改 config 仍能塞任意命令。所以 service_restart **执行前**也过同一套规则：
+//       只允许调用 mesh 自己的重启脚本 / 看护脚本 / autostart 的 start-dshN.vbs|cmd，且禁止 shell 元字符。
+// 归宿：reusable（dsh-mesh/src/core/）
+export const RESTART_TARGET_RE = /\b(restart-dsh-instance\.mjs|instance-watchdog\.mjs|start-dsh\d*\.(vbs|cmd))\b/
+export const MAX_RESTART_COMMAND_LEN = 600
+/** Shell metacharacters that would let a "restart" command become arbitrary code. */
+const FORBIDDEN_META_RE = /[|&;<>`$(){}]/
+
+export function validateRestartCommand(command) {
+  const text = String(command || '').trim()
+  if (!text) return { ok: false, reason: 'command is empty' }
+  if (text.length > MAX_RESTART_COMMAND_LEN) return { ok: false, reason: `command longer than ${MAX_RESTART_COMMAND_LEN} chars` }
+  const meta = FORBIDDEN_META_RE.exec(text)
+  if (meta) return { ok: false, reason: `command contains shell metacharacter "${meta[0]}" — only plain quoted paths/args are allowed` }
+  if (!RESTART_TARGET_RE.test(text)) {
+    return { ok: false, reason: 'command must reference restart-dsh-instance.mjs / instance-watchdog.mjs / start-dsh<N>.vbs|cmd' }
+  }
+  return { ok: true }
+}

package/src/core/result.js

@@ -0,0 +1,29 @@
+/** Uniform tool result helpers: text content only (M1 keeps no outputSchema, so no structuredContent). */
+export function ok(data) {
+  return { content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }] }
+}
+
+export function fail(code, message, extra = {}) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify({ code, message, retryable: false, ...extra }, null, 2)
+      }
+    ]
+  }
+}
+
+export function denied(message, extra) {
+  return fail('E_DENIED', message, extra)
+}
+export function invalidArg(message, extra) {
+  return fail('E_INVALID_ARG', message, extra)
+}
+export function notFound(message, extra) {
+  return fail('E_NOT_FOUND', message, extra)
+}
+export function internal(message, extra) {
+  return fail('E_INTERNAL', message, { retryable: true, ...extra })
+}

package/src/core/session-profile.js

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/**
+ * Delegation safety profile (2026-10-25).
+ *
+ * A peer must never inject a task into a session that owns a scheduled job:
+ * that mixes two contexts and pollutes the scheduled conversation (real
+ * incident: a `channel_wake` landed inside a company `定时-*` session).
+ *
+ * The profile joins two local sources of truth:
+ *   - `<dshHome>/storages/schedule.json`      schedules  -> sessionId
+ *   - `<fsRoot>/.mesh/tasks/<taskId>/request.json` delegations -> sessionId
+ *
+ * A session is *protected* when it owns at least one schedule record.
+ * Delegations are the sessions this node created for a peer, so they are
+ * identified explicitly instead of being guessed from titles.
+ */
+
+const TITLE_SCHEDULE_HINT = /定时|班次|schedule|nightly/i
+const EMPTY = Object.freeze([])
+
+function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return fallback
+  }
+}
+
+/** `<home>/profiles/web` -> `<home>`; empty/unknown profileDir -> ''. */
+export function dshHomeOf(hostEntry) {
+  const dir = String(hostEntry?.profileDir || '')
+  if (!dir) return ''
+  return dirname(dirname(dir))
+}
+
+/** sessionId -> [{id,title,kind,status,instance}] for one configured instance. */
+export function readScheduleIndex(hostEntry) {
+  const home = dshHomeOf(hostEntry)
+  const file = home ? join(home, 'storages', 'schedule.json') : ''
+  const index = new Map()
+  const raw = file && existsSync(file) ? readJson(file) : null
+  const tasks = raw?.tables?.tasks || {}
+  for (const [id, entry] of Object.entries(tasks)) {
+    const sessionId = entry?.sessionId
+    if (!sessionId) continue
+    const record = entry.record || {}
+    const rows = index.get(sessionId) || []
+    rows.push({
+      id,
+      title: record.title || '',
+      kind: record.kind || '',
+      status: entry.status || '',
+      instance: hostEntry?.id || ''
+    })
+    index.set(sessionId, rows)
+  }
+  return index
+}
+
+/** sessionId -> delegation record from this node's `.mesh/tasks` mailbox. */
+export function readDelegationIndex(root) {
+  const dir = root ? join(root, '.mesh', 'tasks') : ''
+  const index = new Map()
+  if (!dir || !existsSync(dir)) return index
+  let names = []
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return index
+  }
+  for (const name of names) {
+    const request = readJson(join(dir, name, 'request.json'))
+    if (!request?.sessionId) continue
+    index.set(request.sessionId, {
+      taskId: request.taskId || name,
+      conversationId: request.conversationId || '',
+      from: request.from || '',
+      policy: request.sessionPolicy || '',
+      createdAt: request.requestedAt || ''
+    })
+  }
+  return index
+}
+
+/** Join every configured instance's schedules plus this node's delegations. */
+export function buildSessionProfile(config) {
+  const schedules = new Map()
+  for (const entry of config?.hosts || []) {
+    if (entry?.enabled === false) continue
+    for (const [sessionId, rows] of readScheduleIndex(entry)) {
+      const merged = schedules.get(sessionId) || []
+      merged.push(...rows.map((row) => ({ ...row, instance: entry.id })))
+      schedules.set(sessionId, merged)
+    }
+  }
+  return { schedules, delegations: readDelegationIndex(config?.acl?.fsRoots?.[0] || '') }
+}
+
+/** Classify one host_sessions / delegate_candidates / listAgents row. */
+export function classifySession(profile, session) {
+  const sessionId = session?.sessionId || session?.id || ''
+  const schedules = profile?.schedules?.get(sessionId) || EMPTY
+  const delegation = profile?.delegations?.get(sessionId) || null
+  const title = String(session?.title || '')
+  const alive = session?.agentAvailable === true && session?.state !== 'ended'
+  let kind = 'unknown'
+  let reason = 'no schedule record and no delegation record'
+  if (schedules.length > 0) {
+    kind = 'business-scheduled'
+    reason = `owns ${schedules.length} scheduled task(s) — injecting here would pollute the scheduled conversation`
+  } else if (delegation) {
+    kind = 'delegation'
+    reason = `created by delegation ${delegation.taskId}`
+  } else if (TITLE_SCHEDULE_HINT.test(title)) {
+    kind = 'business'
+    reason = 'title looks like a scheduled/business session (no schedule record found — still inject with care)'
+  }
+  return {
+    kind,
+    protected: schedules.length > 0,
+    delegatable: alive && schedules.length === 0,
+    recommended: alive && String(session?.state) === 'idle' && schedules.length === 0,
+    reason,
+    schedules,
+    delegation
+  }
+}
+
+/**
+ * Guard for write-capable tools (host_session_prompt / channel_wake /
+ * host_call / delegate continuation). Returns null when the target is safe.
+ */
+export function sessionBlock(profile, sessionId) {
+  const schedules = profile?.schedules?.get(String(sessionId || '')) || EMPTY
+  if (schedules.length === 0) return null
+  return {
+    kind: 'business-scheduled',
+    reason: `session ${sessionId} owns ${schedules.length} scheduled task(s): ${schedules
+      .map((row) => row.title || row.id)
+      .join(' / ')}`,
+    schedules,
+    hint: 'delegate to a FRESH conversation instead (omit sessionId), or pass force:true if you really mean to inject into this scheduled session'
+  }
+}