Files
STM32F4-Base/.dsh/plugins/dsh-plugin-subagent-roles/lib/roles.js
T
wandering1 9e538d2809
CI / 静态门禁 (pre-commit) (push) Failing after 43s
CI / 主机侧单测 (MSVC) (push) Failing after 24s
feat(dsh): 门禁账本插件接入 + 角色绑定跨重启还原
二、门禁与唤醒(新插件 dsh-plugin-team-ledger 0.2.0)
宿主 Agent Teams 缺两块能力,补在独立仓
D:/Code/AI/dsh-plugin-team-ledger:

- 状态存放:<工作区>/.dsh/team/gate.jsonl 追加账本,记验收
  清单、实测证据、认领历史,跨重启存活;canonical JSON +
  fsync,坏尾行截断恢复。
- 唤醒模型:门禁推进后按事件计划唤醒下一责任人,借活体
  Lead 作 caller 走宿主 sendMessage;无定时器;30 分钟滑动
  窗口限 4 次防复活风暴。
- 验收独立性由机器强制:执行人/历史认领者不能 accept,
  checklist 逐项 passed=true 缺一不可。
- team_member_revive(Lead 专用):成员模型路由死亡后的
  复活通道——可换 provider/model,再经 subagents.sendMessage
  冷恢复唤醒,绕过宿主 roster 的 phase=active 门禁。

二、角色绑定跨重启还原(roles fork 0.5.2)
persona 与工具白名单只有运行中 agent 的内存态,宿主重启后
冷恢复的成员既无 persona 也无白名单——实测出现 doc-writer
成员带全量工具面(qq_*/ImageGen),属静默权限放大。改为
注入成功时持久化 childId -> {roleId, cwd} 到
~/.dsh/role-inject-bindings.json,并在 agent/created 时重放。
追加 team_member_rebind 补绑定,覆盖 0.5.2 之前已存在的成员。

三、配套
- .dsh/roles 八个角色白名单加入门禁工具;AGENTS.md 委派策略
  补门禁/复活/重绑三套操作口径。
- docs/环境与部署/子Agent角色自动注入实现说明.md 新增
  §5.1,记录绑定机制、存量成员缺口与「成员自省不可全信」的
  台架教训。
2026-11-16 00:42:51 +08:00

613 lines
26 KiB
JavaScript

/**
* Role discovery: two roots, one file form.
*
* <projectRoot>/.dsh/roles/<id>.md project roles (win on id collision)
* ~/.dsh/roles/<id>.md global roles
*
* `<projectRoot>` is the nearest ancestor of the session cwd carrying a
* project-root marker (`.git` by default); without one the cwd itself is the
* project root.
*
* Discovery is SYNCHRONOUS on purpose: the system-prompt section provider that
* renders the role catalog is called synchronously during assembly, so the
* catalog path cannot await filesystem work. Results are cached per absolute
* path and invalidated by `mtimeMs`, so a step re-reads only files that
* changed. Nothing here throws: a malformed file becomes a diagnostic and is
* skipped, because throwing inside prompt assembly would fail every turn.
*/
import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
import { homedir } from 'node:os'
import { basename, extname, join, resolve } from 'node:path'
import { parse as parseYaml } from 'yaml'
/** Role-id grammar; also the file-stem grammar. */
const ROLE_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
/** Project-relative role directory (the only one). */
const PROJECT_ROLE_DIR = ['.dsh', 'roles']
/**
* Prompt variables a role persona may reference by default — exactly the three
* `dsh-agent-loop` registers. A deployment that registers more can extend this
* through the row's `personaVariables`.
*/
export const PERSONA_VARIABLES = ['cwd', 'model', 'provider']
/**
* Accepted `maxToolCallsScope` values. `delegation` restarts the count at each
* delegation (and at each `turn/start` of a continuable child, which is what a
* background wake opens); `session` accumulates for the child's whole life.
*/
export const TOOL_CALL_SCOPES = ['delegation', 'session']
/** Accepted `onToolCallBudget` postures. */
export const TOOL_CALL_BUDGET_MODES = ['interrupt', 'wrap-up', 'off']
/** Frontmatter keys this format accepts; anything else is a typo. */
const ROLE_FRONTMATTER_KEYS = [
'name',
'displayName',
'description',
'whenToUse',
'provider',
'model',
'reasoningEffort',
'tools',
'toolFilter',
'maxToolCalls',
'maxToolCallsScope',
'onToolCallBudget',
'graceToolCalls',
]
/**
* The core's own rules, copied verbatim from `@deepseek-ai/dsh-system-prompt`
* (`VARIABLE_NAME` / `GROUP_AT`): variable names are lowercase and the
* reference must be one complete simple group — no trimming, no whitespace.
*/
const CORE_VARIABLE_NAME = /^[a-z][a-z0-9_]*$/
const CORE_GROUP_AT = /^\{\{([^{}]*)\}\}/
const DEFAULT_MAX_BODY_BYTES = 65536
/**
* Extra bytes a role file may spend on YAML frontmatter, on top of
* `maxBodyBytes`, before the READ itself is refused. The persona limit is
* measured on the body only, so a plain `size > maxBodyBytes` check would reject
* legitimate files; this allowance is far larger than any real frontmatter.
*/
const FRONTMATTER_READ_ALLOWANCE_BYTES = 65536
/** How long a resolved project root is trusted before re-walking the tree. */
const PROJECT_ROOT_TTL_MS = 5000
/**
* Upper bound on every discovery cache. Discovery runs inside prompt assembly
* for the whole life of a host process, and each cache is keyed by an absolute
* path, so without a bound they would grow with every project, cwd, and role file
* the process ever saw. Eviction only costs a re-stat or a re-read.
*/
const MAX_CACHE_ENTRIES = 512
/** Insert into a bounded Map, evicting the oldest entry first. */
function rememberInMap(map, key, value, limit = MAX_CACHE_ENTRIES) {
if (!map.has(key) && map.size >= limit) {
for (const oldest of map.keys()) {
map.delete(oldest)
break
}
}
map.set(key, value)
}
/**
* Resolve the harness home holding the global role directory.
* @param configured - the row's `dshHome`, when set.
* @param env - environment (injectable for tests).
* @returns an absolute path.
*/
function resolveDshHome(configured, env = process.env) {
const fromEnv = env?.DSH_HOME
const raw = configured !== undefined && configured !== null && configured !== ''
? configured
: typeof fromEnv === 'string' && fromEnv.trim().length > 0
? fromEnv
: join(homedir(), '.dsh')
return resolve(raw)
}
/**
* Split one role document into frontmatter text and persona body.
* EOLs are normalized to `\n`; the body is everything after the closing
* delimiter with no leading newline and trailing content preserved.
* @param raw - the file text.
* @returns the frontmatter text (undefined without a block) and the body.
*/
export function splitRoleDocument(raw) {
const text = String(raw).replace(/^\uFEFF/, '').replace(/\r\n/g, '\n')
const lines = text.split('\n')
if (lines[0]?.trimEnd() !== '---') return { frontmatter: undefined, body: text }
let end = -1
for (let index = 1; index < lines.length; index += 1) {
if (lines[index].trimEnd() === '---') {
end = index
break
}
}
if (end < 0) return { frontmatter: undefined, body: text }
return {
frontmatter: lines.slice(1, end).join('\n'),
body: lines.slice(end + 1).join('\n'),
}
}
/**
* Return the first persona `{{variable}}` reference the CORE would reject, or
* undefined when every reference is allowed.
*
* This mirrors `dsh-system-prompt`'s scanner exactly rather than approximating
* it: interpolate() runs AFTER a section provider returns, so a reference this
* check lets through becomes a thrown error on every turn instead of a
* contained plugin failure.
* @param text - the persona body.
* @param allowed - the variable names the deployment registers.
* @returns the offending reference name, or undefined.
*/
export function findUnsupportedPersonaVariable(text, allowed = PERSONA_VARIABLES) {
if (typeof text !== 'string' || text.length === 0) return undefined
let last = 0
for (let open = text.indexOf('{{'); open >= 0; open = text.indexOf('{{', last)) {
const group = CORE_GROUP_AT.exec(text.slice(open))
if (group === null) {
// A lone `{{` without any later `}}` is literal prose for the core…
if (text.indexOf('}}', open + 2) >= 0) return text.slice(open + 2, text.indexOf('}}', open + 2))
// …and scanning continues past it, exactly like the core does.
last = open + 2
continue
}
const name = group[0].slice(2, -2)
if (!CORE_VARIABLE_NAME.test(name)) return name
if (!allowed.includes(name)) return name
last = open + group[0].length
}
return undefined
}
/** Whether catalog text carries a `{{` at all (it is rendered through interpolation). */
function hasVariableSyntax(text) {
return typeof text === 'string' && text.includes('{{')
}
function nonEmptyString(value) {
return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined
}
function normalizeNameList(value, field) {
if (!Array.isArray(value)) return { error: `${field} must be an array of tool names` }
const names = []
for (const entry of value) {
const name = nonEmptyString(entry)
if (name === undefined) return { error: `${field} entries must be non-empty strings` }
if (!names.includes(name)) names.push(name)
}
return { names }
}
/**
* Validate one tool-call budget count: an integer `>= 0`, where `0` means
* unlimited. YAML yields `8.5` or `-1` for a plausible-looking typo, and a
* fractional limit would make "the limit+1-th call" unrepresentable.
* @param value - the parsed frontmatter value.
* @param field - the key name, for the message.
* @returns the count, or an error string.
*/
function normalizeBudgetCount(value, field) {
if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
return { error: `\`${field}\` must be an integer >= 0 (\`0\` means unlimited)` }
}
return { count: value }
}
/**
* Validate one enum-valued frontmatter key against its accepted vocabulary.
* @param value - the parsed frontmatter value.
* @param field - the key name, for the message.
* @param allowed - the accepted values.
* @returns the value, or an error string.
*/
function normalizeEnumValue(value, field, allowed) {
const text = nonEmptyString(value)
if (text === undefined || !allowed.includes(text)) {
return { error: `\`${field}\` must be one of ${allowed.join(', ')}` }
}
return { value: text }
}
/**
* Validate and normalize the `toolFilter` shape (including the `tools`
* allow-list shorthand).
*
* An EXPLICITLY declared `allow` is always preserved, even when empty: the core
* accepts `{ allow: [] }` and reads it as "hide every inherited tool", so
* dropping it (which would leave a bare `deny` and hand the child everything
* else) is a silent fail-open. Only a declaration with nothing effective —
* `{}` or a lone empty `deny` — is refused.
* @param value - parsed frontmatter.
* @returns the normalized filter, or an error string.
*/
export function normalizeRoleToolFilter(value) {
const hasTools = value.tools !== undefined
const hasFilter = value.toolFilter !== undefined
if (hasTools && hasFilter) return { error: 'declare either `tools` or `toolFilter`, not both' }
if (hasTools) {
const list = normalizeNameList(value.tools, 'tools')
if (list.error !== undefined) return { error: list.error }
// `tools: []` is legal and means "no inherited tool at all".
return { filter: { allow: list.names } }
}
if (!hasFilter) return {}
const raw = value.toolFilter
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
return { error: '`toolFilter` must be an object with optional `allow` and/or `deny` arrays' }
}
for (const key of Object.keys(raw)) {
if (key !== 'allow' && key !== 'deny') return { error: `\`toolFilter.${key}\` is not supported (use allow/deny)` }
}
const filter = {}
if (raw.allow !== undefined) {
const list = normalizeNameList(raw.allow, 'toolFilter.allow')
if (list.error !== undefined) return { error: list.error }
filter.allow = list.names
}
if (raw.deny !== undefined) {
const list = normalizeNameList(raw.deny, 'toolFilter.deny')
if (list.error !== undefined) return { error: list.error }
if (list.names.length > 0) filter.deny = list.names
}
if (filter.allow === undefined && filter.deny === undefined) {
return { error: '`toolFilter` has no usable entries; omit the field to grant all tools, or set `allow: []` to grant none' }
}
return { filter }
}
/**
* Parse and validate one role document.
* @param id - the role id (the file stem).
* @param raw - the file text.
* @param options - `maxBodyBytes` guard and the `personaVariables` allow list.
* @returns `{ role }` on success or `{ error }` with a human-readable reason.
*/
export function parseRoleDocument(id, raw, options = {}) {
const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
// Only names the core's own grammar accepts are honoured: an entry the core
// would reject must not be able to turn into a per-turn interpolation throw.
const personaVariables = (Array.isArray(options.personaVariables) && options.personaVariables.length > 0
? options.personaVariables
: PERSONA_VARIABLES
).filter((name) => typeof name === 'string' && CORE_VARIABLE_NAME.test(name))
if (!ROLE_ID_PATTERN.test(id)) {
return { error: `role id "${id}" is not kebab-case (lowercase letters, digits, single hyphens)` }
}
const { frontmatter, body } = splitRoleDocument(raw)
let value = {}
if (frontmatter !== undefined && frontmatter.trim().length > 0) {
let parsed
try {
parsed = parseYaml(frontmatter)
} catch (error) {
return { error: `frontmatter is not valid YAML: ${String(error?.message ?? error)}` }
}
if (parsed === null || parsed === undefined) value = {}
else if (typeof parsed !== 'object' || Array.isArray(parsed)) return { error: 'frontmatter must be a YAML mapping' }
else value = parsed
}
// Reject typos instead of silently ignoring them: a misspelled `tools` key
// would otherwise grant the child every inherited tool.
const unknownKeys = Object.keys(value).filter((key) => !ROLE_FRONTMATTER_KEYS.includes(key))
if (unknownKeys.length > 0) {
return { error: `unknown frontmatter key${unknownKeys.length > 1 ? 's' : ''} ${unknownKeys.map((key) => `\`${key}\``).join(', ')}; supported: ${ROLE_FRONTMATTER_KEYS.join(', ')}` }
}
if (Buffer.byteLength(body, 'utf8') > maxBodyBytes) {
return { error: `persona body is ${Buffer.byteLength(body, 'utf8')} bytes, over the ${maxBodyBytes}-byte limit (raise maxBodyBytes to allow it)` }
}
if (value.name !== undefined) {
const declared = nonEmptyString(value.name)
if (declared === undefined) return { error: '`name` must be a non-empty string when set' }
if (declared !== id) {
return { error: `\`name: ${declared}\` must equal the file id "${id}" or be omitted (the file name is the role id)` }
}
}
const description = nonEmptyString(value.description)
if (description === undefined) return { error: '`description` is required and must be non-empty' }
const displayName = value.displayName === undefined ? undefined : nonEmptyString(value.displayName)
if (value.displayName !== undefined && displayName === undefined) {
return { error: '`displayName` must be a non-empty string when set' }
}
const whenToUse = value.whenToUse === undefined ? undefined : nonEmptyString(value.whenToUse)
if (value.whenToUse !== undefined && whenToUse === undefined) {
return { error: '`whenToUse` must be a non-empty string when set' }
}
// Catalog text reaches the model through the SAME strict interpolation as the
// persona, but it is assembled OUTSIDE this plugin's try/catch — an unknown
// reference there would throw on every turn of every agent that sees the
// catalog. Any `{{` is therefore refused, including the silently-substituted
// registered ones (a description must not leak {{cwd}}).
for (const [field, text] of [['description', description], ['displayName', displayName], ['whenToUse', whenToUse]]) {
if (hasVariableSyntax(text)) {
return { error: `\`${field}\` must not contain \`{{\` (catalog text is interpolated strictly; write plain text)` }
}
}
const route = {}
for (const field of ['provider', 'model', 'reasoningEffort']) {
if (value[field] === undefined) continue
const text = nonEmptyString(value[field])
if (text === undefined) return { error: `\`${field}\` must be a non-empty string when set` }
route[field] = text
}
// A route is a pair: a lone provider/model is merged over the parent's other
// half by the core, silently producing a route nobody declared.
if ((route.provider === undefined) !== (route.model === undefined)) {
return { error: '`provider` and `model` must be set together (or both omitted to inherit the parent route)' }
}
const filterResult = normalizeRoleToolFilter(value)
if (filterResult.error !== undefined) return { error: filterResult.error }
// The tool-call budget. Counts are validated as integers so "the call after
// the limit" is always representable, and the enums are closed so a typo
// (`wrapup`) cannot silently disable the guard a role file asked for.
const budget = {}
for (const field of ['maxToolCalls', 'graceToolCalls']) {
if (value[field] === undefined) continue
const count = normalizeBudgetCount(value[field], field)
if (count.error !== undefined) return { error: count.error }
budget[field] = count.count
}
const budgetEnums = [['maxToolCallsScope', TOOL_CALL_SCOPES], ['onToolCallBudget', TOOL_CALL_BUDGET_MODES]]
for (const [field, allowed] of budgetEnums) {
if (value[field] === undefined) continue
const entry = normalizeEnumValue(value[field], field, allowed)
if (entry.error !== undefined) return { error: entry.error }
budget[field] = entry.value
}
const badVariable = findUnsupportedPersonaVariable(body, personaVariables)
if (badVariable !== undefined) {
return { error: `persona references {{${badVariable}}}; only ${personaVariables.map((name) => `{{${name}}}`).join(', ')} are available (no spaces inside the braces)` }
}
const persona = body.trim().length > 0 ? body : undefined
return {
role: {
id,
displayName: displayName ?? id,
description,
...(whenToUse !== undefined ? { whenToUse } : {}),
...route,
...budget,
...(filterResult.filter !== undefined ? { toolFilter: filterResult.filter } : {}),
...(persona !== undefined ? { persona } : {}),
},
}
}
/**
* Create a cached role loader. One loader per plugin instance; the cache is
* keyed by absolute path and invalidated by `mtimeMs`.
* @param options - resolved discovery config.
* @returns the loader.
*/
export function createRoleLoader(options = {}) {
const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
const personaVariables = Array.isArray(options.personaVariables) ? options.personaVariables : undefined
const cacheEntries = Number.isSafeInteger(options.cacheEntries) && options.cacheEntries > 0
? options.cacheEntries
: MAX_CACHE_ENTRIES
const projectRootTtlMs = typeof options.projectRootTtlMs === 'number' ? options.projectRootTtlMs : PROJECT_ROOT_TTL_MS
const markers = Array.isArray(options.projectRootMarkers) && options.projectRootMarkers.length > 0
? options.projectRootMarkers
: ['.git']
const dshHome = resolveDshHome(options.dshHome)
const fileCache = new Map()
const projectRootCache = new Map()
const dirCache = new Map()
/**
* The diagnostics a per-step read has already surfaced, keyed by role ROOT and
* then by the exact role path.
*
* Two levels, both load-bearing. Inside one root the key is the exact absolute
* path and the value is the set of that path's standing reasons, so healing one
* file clears one small entry instead of walking every reported identity (C).
* Across roots the key is the root, so the global root is shared by every cwd —
* one log line per loader, not one per session — while one project's assembly
* can never forget another project's findings.
*/
const reportedByRoot = new Map()
/**
* Nearest ancestor carrying a project-root marker (or the cwd itself).
*
* The answer is cached with a TTL because the tree can change under a live
* session (`git init` in a project that had no marker) and a permanent cache
* would keep serving the old root for the rest of the process.
*/
function projectRootFor(cwd) {
if (typeof cwd !== 'string' || cwd.length === 0) return undefined
const start = resolve(cwd)
const now = Date.now()
const cached = projectRootCache.get(start)
if (cached !== undefined && now - cached.at < projectRootTtlMs) return cached.root
let current = start
let found = start
for (;;) {
let hit = false
for (const marker of markers) {
if (existsSync(join(current, marker))) {
hit = true
break
}
}
if (hit) {
found = current
break
}
const parent = resolve(current, '..')
if (parent === current) break
current = parent
}
rememberInMap(projectRootCache, start, { root: found, at: now }, cacheEntries)
return found
}
function loadRecord(path, id, source) {
let stats
try {
stats = statSync(path)
} catch (error) {
return { error: `cannot stat role file: ${String(error?.code ?? error)}` }
}
// A symlinked role file is supported, but it must resolve to a REGULAR file.
// `statSync` follows the link, so a link to a FIFO, a socket, or a character
// device lands here as a non-regular file — and `readFileSync` on one blocks
// forever (`/dev/zero`: reads without end) *synchronously, inside prompt
// assembly*, which no signal or timeout can interrupt. Refuse it by type.
if (!stats.isFile()) {
return { error: `role path is not a regular file (${stats.isDirectory() ? 'directory' : 'special file'})` }
}
const cached = fileCache.get(path)
// Size joins mtime so a same-millisecond rewrite is still noticed.
if (cached !== undefined && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) return cached.record
// Bound the READ, not merely the parsed body: the size is already known here,
// and letting `readFileSync` pull in a multi-gigabyte file would allocate it
// all before `maxBodyBytes` is ever consulted.
if (stats.size > maxBodyBytes + FRONTMATTER_READ_ALLOWANCE_BYTES) {
return { error: `role file is ${stats.size} bytes, over the ${maxBodyBytes}-byte persona limit plus ${FRONTMATTER_READ_ALLOWANCE_BYTES} bytes of frontmatter (raise maxBodyBytes or shrink the file)` }
}
let raw
try {
raw = readFileSync(path, 'utf8')
} catch (error) {
return { error: `cannot read role file: ${String(error?.code ?? error)}` }
}
const parsed = parseRoleDocument(id, raw, { maxBodyBytes, personaVariables })
if (parsed.error !== undefined) {
// Failures are deliberately NOT cached: fixing a file must take effect
// even when its mtime did not move.
return { error: parsed.error }
}
const record = { role: { ...parsed.role, path, source } }
rememberInMap(fileCache, path, { mtimeMs: stats.mtimeMs, size: stats.size, record }, cacheEntries)
return record
}
/** List one role directory, cached by the directory's own mtime. */
function listRoleFiles(root) {
let stats
try {
stats = statSync(root.path)
} catch {
return []
}
const cached = dirCache.get(root.path)
if (cached !== undefined && cached.mtimeMs === stats.mtimeMs) return cached.files
let entries
try {
entries = readdirSync(root.path, { withFileTypes: true })
} catch {
return []
}
const files = entries
// A symlinked role file counts: the stats below follow the link.
.filter((entry) => (entry.isFile() || entry.isSymbolicLink()) && extname(entry.name) === '.md')
.map((entry) => entry.name)
.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
rememberInMap(dirCache, root.path, { mtimeMs: stats.mtimeMs, files }, cacheEntries)
return files
}
/**
* Resolve the roots for one session cwd, lowest precedence last.
* @param cwd - the session working directory (may be undefined).
* @returns ordered roots.
*/
function rootsFor(cwd) {
const roots = []
const projectRoot = projectRootFor(cwd)
const globalPath = join(dshHome, 'roles')
if (projectRoot !== undefined) {
const projectPath = join(projectRoot, ...PROJECT_ROLE_DIR)
roots.push({ source: 'project', path: projectPath })
// A repository rooted at the harness home would otherwise be scanned
// twice, reporting every global role as shadowed by itself.
if (resolve(projectPath) === resolve(globalPath)) return roots
}
roots.push({ source: 'global', path: globalPath })
return roots
}
/**
* Load the merged role catalog for one cwd. Never throws.
* @param cwd - the session working directory.
* @param options - `freshDiagnostics` returns only the diagnostics that were NOT
* standing in the previous read of the same root (for per-step logging); the
* default returns every current diagnostic on every read.
* @returns `{ roles, diagnostics, roots }` with project roles winning on id.
*/
function loadSync(cwd, options = {}) {
const roles = []
const byId = new Set()
const diagnostics = []
const roots = rootsFor(cwd)
// The default read is the diagnostic tool's FULL inventory. Only the per-step
// flag turns on the comparison below, so a skipped file is still listed in
// full every time the `subagent_roles` tool asks (E).
const fresh = options.freshDiagnostics === true
for (const root of roots) {
const files = listRoleFiles(root)
let reported
if (fresh) {
reported = reportedByRoot.get(root.path)
if (reported === undefined) {
reported = new Map()
rememberInMap(reportedByRoot, root.path, reported, cacheEntries)
}
}
// Paths this assembly actually looked at. Only a fresh read needs it: it is
// how a file that vanished entirely is told apart from one that healed.
const seen = fresh ? new Set() : undefined
for (const file of files) {
const id = basename(file, '.md')
const path = join(root.path, file)
const reasons = []
const record = loadRecord(path, id, root.source)
if (record.error !== undefined) {
reasons.push(record.error)
} else if (byId.has(id)) {
reasons.push('shadowed by a higher-precedence role of the same id')
} else {
byId.add(id)
roles.push(record.role)
}
if (!fresh) {
for (const reason of reasons) diagnostics.push({ id, path, source: root.source, reason })
continue
}
seen.add(path)
// Compare against THIS path's reasons from the previous fresh read of the
// same root — a per-identity difference, never a monotonic set. A reason
// the previous read did not stand for is new: the first observation, a
// changed cause, or the same cause after the read stopped standing for it
// (the file healed, or the shadow that produced it lifted) and it came
// back. The old "report once, remember forever" set swallowed that last
// case — the shadowed-role recurrence this comparison exists to fix (D).
const previous = reported.get(path)
for (const reason of reasons) {
if (previous?.has(reason) !== true) diagnostics.push({ id, path, source: root.source, reason })
}
// REPLACE, never merge. A cause that stopped being this file's cause must
// not linger in the set, or switching back to it would stay silent (D).
if (reasons.length === 0) reported.delete(path)
else reported.set(path, new Set(reasons))
}
if (!fresh) continue
// A path that stood for a diagnostic last time but was not scanned at all
// now — the file was deleted or renamed away — left the assembly without
// being observed clean. Forget it, so recreating it broken is reported
// again (D). Only THIS root's diagnosed paths are walked, so the cost stays
// proportional to this root's findings, not to everything ever reported.
for (const path of reported.keys()) {
if (!seen.has(path)) reported.delete(path)
}
}
return { roles, diagnostics, roots }
}
return { loadSync, rootsFor, projectRootFor, dshHome }
}