dsh-standards 1.2.1 → 1.3.0

package/40-checker/src/report.mjs

@@ -31,6 +31,46 @@ function adjustEntryCheck(item, entryClaim) {
   return { ...item, result: 'WARN', reason: 'C-2.1 version declaration missing/invalid; entry treats it as WARN (C-2.2/C-2.3 remain blocking)' }
 }
 
+/** Declaration-class checks: a WARN here is hygiene, not a loadability defect. */
+export const DECLARATION_CHECKS = new Set(['DSC-11', 'DSC-12', 'DSC-13'])
+const DETAIL_RANK = { FAIL: 5, ERROR: 4, WARN: 3, PASS: 2, NA: 1 }
+
+function bucketRow(item, extra = {}) {
+  return {
+    id: item.id,
+    clause: item.clause ?? null,
+    result: item.result,
+    coverage: item.coverage ?? null,
+    reason: item.reason ?? '',
+    ...extra,
+  }
+}
+
+/**
+ * `entryBlocking` is only sound when every prerequisite was actually evaluated.
+ * C-1.x always produce details; C-3.1/3.2/3.5 only produce them when an install
+ * spec or market index was supplied. Missing details must therefore make
+ * `pass` false instead of silently claiming the gate held.
+ */
+export function summarizeBlocking(checks, blocking) {
+  const seen = new Map()
+  for (const item of checks) {
+    for (const detail of item.details ?? []) {
+      if (!blocking.includes(detail.item)) continue
+      const rank = DETAIL_RANK[detail.result] ?? 0
+      if (!seen.has(detail.item) || rank > (DETAIL_RANK[seen.get(detail.item)] ?? 0)) seen.set(detail.item, detail.result)
+    }
+  }
+  const checked = blocking.filter(id => seen.has(id))
+  // C-2.3 (workspace: range) has no detail when C-2.2 was evaluated against a
+  // normal range; evaluating C-2.2 rules the workspace form out, so count it.
+  if (seen.has('C-2.2') && blocking.includes('C-2.3') && !checked.includes('C-2.3')) checked.push('C-2.3')
+  checked.sort((a, b) => blocking.indexOf(a) - blocking.indexOf(b))
+  const failed = blocking.filter(id => seen.get(id) === 'FAIL')
+  const notChecked = blocking.filter(id => !checked.includes(id))
+  return { required: blocking.length, checked, notChecked, failed, pass: failed.length === 0 && notChecked.length === 0 }
+}
+
 function allowedNa(check, scope, profile, kind) {
   if (check.result !== 'NA') return false
   if (check.id === 'DSC-03' && scope !== 'mvp' && profile === 'package') return true
@@ -39,7 +79,7 @@ function allowedNa(check, scope, profile, kind) {
   return false
 }
 
-export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime', advice = true }) {
+export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime', advice = true, declarations = null }) {
   const mandatory = mandatoryFor(scope, profile, staticOnly, entryClaim)
   const adjustedChecks = scope === 'entry' ? checks.map(item => adjustEntryCheck(item, entryClaim)) : checks
   const runtimeIds = new Set(['DSC-04', 'DSC-05', 'DSC-06', 'DSC-07', 'DSC-08', 'DSC-09'])
@@ -59,6 +99,17 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   const warnings = selected.filter(item => item.result === 'WARN')
   const pass = selected.filter(item => item.result === 'PASS')
 
+  // Coverage counts every check the report carries (14 in a full run), not just
+  // the mandatory subset. A report that only counts its mandatory five hides
+  // the runtime checks it never ran; that is the bug this block fixes.
+  const evaluatedAll = effectiveChecks.filter(item => ['PASS', 'WARN', 'FAIL'].includes(item.result))
+  const naAll = effectiveChecks.filter(item => item.result === 'NA')
+  const errorAll = effectiveChecks.filter(item => item.result === 'ERROR')
+  const notRunAll = effectiveChecks.filter(item => item.result !== 'NA' && (item.coverage === 'not-run' || item.coverage === 'partial'))
+  const notRunAllIds = [...new Set([...notRunAll.map(item => item.id), ...errorAll.map(item => item.id), ...missing])]
+  const entryBlockingIds = scope === 'entry' ? (entryClaim === 'static' ? ENTRY_BLOCKING : ENTRY_RUNTIME_BLOCKING) : null
+  const entryBlocking = entryBlockingIds ? summarizeBlocking(effectiveChecks, entryBlockingIds) : null
+
   let status
   let exitCode
   if (failed.length > 0) { status = 'fail'; exitCode = 1 }
@@ -87,6 +138,31 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   if (warnings.length > 0) reasonParts.push(`WARN: ${warnings.map(item => item.id).join(', ')}`)
   if (advisoryWarnings.length > 0) reasonParts.push(`advisory: ${advisoryWarnings.map(item => item.id).join(', ')}`)
 
+  // Findings by reader-relevant bucket. A check appears in exactly one bucket:
+  // FAIL -> blocking, WARN -> hygiene, NA/ERROR/not-run -> notChecked.
+  const blockingBucket = effectiveChecks.filter(item => item.result === 'FAIL').map(item => bucketRow(item))
+  const hygieneBucket = effectiveChecks.filter(item => item.result === 'WARN').map(item => bucketRow(item, {
+    declaration: DECLARATION_CHECKS.has(item.id),
+    advisory: item.advisory === true,
+  }))
+  const notCheckedBucket = effectiveChecks
+    .filter(item => item.result === 'NA' || item.result === 'ERROR')
+    .map(item => bucketRow(item))
+  for (const id of missing) {
+    notCheckedBucket.push({ id, clause: null, result: 'NOT-RUN', coverage: 'not-run', reason: 'mandatory check missing' })
+  }
+  const buckets = { blocking: blockingBucket, hygiene: hygieneBucket, notChecked: notCheckedBucket }
+  const declaredFields = Array.isArray(declarations?.present) ? declarations.present.length : 0
+  const canMarkSuspect = anchor?.suspect === true
+
+  const metrics = {
+    checked: evaluatedAll.length,
+    total: effectiveChecks.length,
+    declaredFields,
+  }
+  const prereq = entryBlocking ? ` (prereq ${entryBlocking.checked.length}/${entryBlocking.required})` : ''
+  const headline = `${scope}/${profile} · runtime ${anchor?.dsh ?? 'unknown'}${anchor?.runtimeSource ? ` ${anchor.runtimeSource}` : ''}${canMarkSuspect ? ' SUSPECT' : ''} · blocking ${buckets.blocking.length}${prereq} · hygiene ${buckets.hygiene.length} · not checked ${buckets.notChecked.length}/${effectiveChecks.length}`
+
   const report = {
     schema: 'dsh-conformance/1',
     standard: { id: 'DS-C', version: '1.0.0' },
@@ -95,21 +171,22 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
     g4,
     checks: effectiveChecks,
     coverage: {
+      total: effectiveChecks.length,
       mandatory: mandatory.length,
-      pass: pass.length,
-      warn: warnings.length,
+      checked: evaluatedAll.length,
+      pass: evaluatedAll.filter(item => item.result === 'PASS').length,
+      warn: evaluatedAll.filter(item => item.result === 'WARN').length,
       advisory: advisoryWarnings.length,
-      fail: failed.length,
-      na: selected.filter(item => item.result === 'NA').length,
-      notRun: notRunIds.length,
-      error: errored.length,
-      entryBlocking: scope === 'entry' ? (() => {
-        const blocking = entryClaim === 'static' ? ENTRY_BLOCKING : ENTRY_RUNTIME_BLOCKING
-        const failedItems = effectiveChecks.flatMap(item => (item.details ?? []).filter(detail => detail.result === 'FAIL' && blocking.includes(detail.item)).map(detail => detail.item))
-        return { required: blocking.length, failed: failedItems, pass: failedItems.length === 0 }
-      })() : null,
+      fail: evaluatedAll.filter(item => item.result === 'FAIL').length,
+      na: naAll.length,
+      notRun: notRunAllIds.length,
+      error: errorAll.length,
+      entryBlocking,
     },
+    buckets,
+    metrics,
     conclusion: {
+      headline,
       level,
       status,
       exitCode,
@@ -132,25 +209,49 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
 
 const ICON = { PASS: 'PASS', WARN: 'WARN', FAIL: 'FAIL', NA: 'NA  ', ERROR: 'ERR ' }
 
+function renderBucket(lines, title, rows, byId) {
+  lines.push(`${title} (${rows.length}):`)
+  if (rows.length === 0) {
+    lines.push('  none')
+    return
+  }
+  for (const row of rows) {
+    const tags = [row.declaration ? 'declaration' : null, row.advisory ? 'advisory' : null].filter(Boolean)
+    const reason = String(row.reason ?? '').replace(/\s+/g, ' ').slice(0, 150)
+    lines.push(`  ${(ICON[row.result] ?? row.result).padEnd(4)} ${String(row.id).padEnd(7)} ${String(row.clause ?? '-').padEnd(6)} ${String(row.coverage ?? '-').padEnd(8)} ${reason}${tags.length > 0 ? ` [${tags.join(',')}]` : ''}`)
+    const item = byId.get(row.id)
+    if (!item || (row.result !== 'FAIL' && row.result !== 'WARN')) continue
+    for (const detail of item.details ?? []) {
+      if (detail.result === 'PASS') continue
+      lines.push(`          - ${detail.item}: ${detail.result} ${String(detail.reason ?? '').replace(/\s+/g, ' ').slice(0, 140)}`)
+    }
+  }
+}
+
 export function formatText(report) {
   const lines = []
-  const { subject, anchor, conclusion, coverage } = report
+  const { subject, anchor = {}, conclusion, coverage } = report
+  const byId = new Map((report.checks ?? []).map(item => [item.id, item]))
   lines.push(`DS-C check — ${subject.name ?? '<unknown>'}@${subject.version ?? '?'} (${subject.kind}${subject.kindInferred ? ', inferred' : ''})`)
-  lines.push(`anchor: repo=${anchor.repo} commit=${anchor.commit.slice(0, 12)} dsh=${anchor.dsh} cordis=${anchor.cordis}`)
+  lines.push(`anchor: repo=${anchor.repo ?? '?'} commit=${String(anchor.commit ?? '').slice(0, 12)} dsh=${anchor.dsh ?? '?'} cordis=${anchor.cordis ?? '?'}${anchor.runtimeSource ? ` source=${anchor.runtimeSource}` : ''}${anchor.suspect ? ' suspect=true' : ''}`)
   lines.push(`scope=${conclusion.scope} profile=${conclusion.profile} status=${conclusion.status} exit=${conclusion.exitCode}${conclusion.subset ? ` subset=${conclusion.subset}` : ''}${conclusion.staticOnly ? ' static-only' : ''}`)
   if (conclusion.level) lines.push(`level: ${conclusion.level}`)
+  if (conclusion.headline) lines.push(`headline: ${conclusion.headline}`)
   lines.push('')
-  lines.push('id      result  clause  layer   reason')
-  for (const item of report.checks) {
-    const reason = (item.reason || '').replace(/\s+/g, ' ').slice(0, 120)
-    lines.push(`${item.id.padEnd(7)} ${ICON[item.result] ?? item.result}  ${item.clause.padEnd(6)} ${item.layer.padEnd(6)} ${reason}`)
-    for (const detail of item.details ?? []) {
-      if (detail.result === 'PASS') continue
-      lines.push(`        - ${detail.item}: ${detail.result} ${String(detail.reason).slice(0, 140)}`)
-    }
-  }
+  renderBucket(lines, 'Blocking (FAIL)', report.buckets?.blocking ?? [], byId)
   lines.push('')
-  lines.push(`coverage: mandatory=${coverage.mandatory} pass=${coverage.pass} warn=${coverage.warn} fail=${coverage.fail} na=${coverage.na} notRun=${coverage.notRun}`)
+  renderBucket(lines, 'Hygiene (WARN)', report.buckets?.hygiene ?? [], byId)
+  lines.push('')
+  renderBucket(lines, 'Not checked (NA / not-run / ERROR)', report.buckets?.notChecked ?? [], byId)
+  lines.push('')
+  const passed = (report.checks ?? []).filter(item => item.result === 'PASS')
+  lines.push(`passed (${passed.length}): ${passed.map(item => item.id).join(', ') || 'none'}`)
+  lines.push(`coverage: total=${coverage.total ?? report.checks.length} checked=${coverage.checked ?? coverage.pass + coverage.warn + coverage.fail} pass=${coverage.pass} warn=${coverage.warn} fail=${coverage.fail} na=${coverage.na} notRun=${coverage.notRun} error=${coverage.error} advisory=${coverage.advisory}`)
+  if (coverage.entryBlocking) {
+    const blocking = coverage.entryBlocking
+    lines.push(`entryBlocking: checked=${blocking.checked?.length ?? '?'}/${blocking.required} failed=[${(blocking.failed ?? []).join(', ')}] notChecked=[${(blocking.notChecked ?? []).join(', ')}] pass=${blocking.pass}`)
+  }
+  lines.push(`metrics: checked=${report.metrics?.checked ?? '?'}/${report.metrics?.total ?? '?'} declaredFields=${report.metrics?.declaredFields ?? 0}/5`)
   if (conclusion.reason) lines.push(`reason: ${conclusion.reason}`)
   if (conclusion.status === 'incomplete') lines.push('NOT A DS-C PASS: at least one mandatory check did not run (see notRun).')
   if (Array.isArray(report.advice) && report.advice.length > 0) {

package/40-checker/src/sandbox-run.mjs

@@ -0,0 +1,403 @@
+/**
+ * Sandbox execution for FLOW evidence collection.
+ *
+ * `flow collect --sandbox` runs the runtime probe (which executes
+ * `dsh plugin add` and boots the tree) behind a containment layer:
+ *
+ *   env      allowlist from `sandbox-env.mjs`; GH_TOKEN / NPM_TOKEN /
+ *            GITHUB_TOKEN are asserted absent, and any secret-shaped name is
+ *            reported rather than silently forwarded;
+ *   home     caller-supplied temporary HOME/DSH_HOME/TMPDIR (never the real
+ *            profile);
+ *   network  `unshare -n` when permitted, falling back to
+ *            `unshare -Urn` (user+network namespace); if neither works the run
+ *            continues degraded and records `unshare-missing`;
+ *   limits   `prlimit --nproc --as` when util-linux prlimit is available; the
+ *            probe reads `/proc/self/limits` so only limits that actually took
+ *            effect are recorded;
+ *   timeout  the child is spawned as its own process-group leader and the
+ *            whole group receives SIGKILL, so `dsh` grandchildren die too
+ *            (Windows: `taskkill /T /F`).
+ *
+ * This is containment, not a security boundary: no seccomp, no cgroup memory/
+ * pids accounting, no OCI image. Evidence is only allowed to call itself
+ * `sandbox` when every item above is effective; any missing item switches the
+ * producer to `sandbox-degraded`, which `level-audit` never reports as runtime.
+ */
+import fs from 'node:fs'
+import { spawn, spawnSync } from 'node:child_process'
+import { isSecretEnvName, sanitizedEnv } from './sandbox-env.mjs'
+
+export const SANDBOX_REPORT_SCHEMA = 'dsh-sandbox-report/1'
+export const SANDBOX_DEGRADED = Object.freeze({
+  unshare: 'unshare-missing',
+  prlimit: 'prlimit-missing',
+  env: 'env-token-present',
+  home: 'home-not-isolated',
+  treeKill: 'process-tree-kill-unavailable',
+  execution: 'sandbox-execution-failed',
+})
+
+/** Names that must never reach a child that may import plugin code. */
+export const CREDENTIAL_ENV_NAMES = Object.freeze(['GH_TOKEN', 'NPM_TOKEN', 'GITHUB_TOKEN'])
+
+/** Inherited or caller-supplied names that look like credentials. */
+export function credentialEnvOffenders(env = process.env, names = CREDENTIAL_ENV_NAMES) {
+  const offenders = new Set()
+  for (const name of names) {
+    if (env && Object.prototype.hasOwnProperty.call(env, name) && env[name] !== undefined && env[name] !== null) {
+      offenders.add(name)
+    }
+  }
+  for (const name of Object.keys(env ?? {})) {
+    if (isSecretEnvName(name)) offenders.add(name)
+  }
+  return [...offenders].sort()
+}
+
+/** Hard gate: refuse to boot a plugin when a credential survived scrubbing. */
+export function assertNoCredentialEnv(env = process.env, names = CREDENTIAL_ENV_NAMES) {
+  const offenders = credentialEnvOffenders(env, names)
+  if (offenders.length > 0) {
+    throw new Error(`sandbox env assertion failed: ${offenders.join(', ')} present in the child environment`)
+  }
+  return { policy: 'allowlist', checked: [...names], absent: true, offenders: [] }
+}
+
+/** Count tasks (processes + threads) owned by this uid, for a safe RLIMIT_NPROC. */
+export function userTaskCount(uid = typeof process.getuid === 'function' ? process.getuid() : null) {
+  if (process.platform !== 'linux' || uid === null) return 0
+  let tasks = 0
+  try {
+    for (const entry of fs.readdirSync('/proc')) {
+      if (!/^\d+$/.test(entry)) continue
+      try {
+        if (fs.statSync(`/proc/${entry}`).uid !== uid) continue
+        const status = fs.readFileSync(`/proc/${entry}/status`, 'utf8')
+        const match = /^Threads:\s+(\d+)$/m.exec(status)
+        tasks += match ? Number(match[1]) : 1
+      } catch { /* process vanished */ }
+    }
+  } catch { return 0 }
+  return tasks
+}
+
+export function defaultNproc() {
+  // RLIMIT_NPROC counts tasks, so a fixed small value (e.g. 64) breaks Node on
+  // a busy desktop. Keep headroom above the current task count.
+  return Math.max(1024, userTaskCount() + 512)
+}
+
+function probeFailure(error) {
+  if (!error) return null
+  return String(error.message ?? error).slice(0, 300)
+}
+
+/**
+ * Try a real network namespace. `unshare -n` needs CAP_SYS_ADMIN; in an
+ * unprivileged container/WSL that fails, so `unshare -Urn` (user namespace +
+ * network namespace) is the fallback. `true` is the probe target so no plugin
+ * code runs while deciding.
+ */
+export function probeNetworkIsolation({ platform = process.platform, unshare = 'unshare', timeoutMs = 5_000 } = {}) {
+  if (platform === 'win32') {
+    return {
+      isolated: false,
+      degraded: SANDBOX_DEGRADED.unshare,
+      reason: 'unshare is not available on win32',
+      attempts: [],
+    }
+  }
+  const attempts = []
+  for (const args of [['-n'], ['-Urn']]) {
+    const command = [unshare, ...args, 'true']
+    const result = spawnSync(unshare, [...args, 'true'], {
+      encoding: 'utf8', stdio: ['ignore', 'ignore', 'pipe'], timeout: timeoutMs, env: sanitizedEnv(),
+    })
+    const exitCode = Number.isInteger(result.status) ? result.status : null
+    const attempt = {
+      command,
+      exitCode,
+      signal: result.signal ?? null,
+      error: probeFailure(result.error),
+      stderr: String(result.stderr ?? '').trim().slice(0, 300) || null,
+    }
+    attempts.push(attempt)
+    if (!result.error && result.status === 0) {
+      return {
+        isolated: true,
+        mechanism: args[0] === '-n' ? 'unshare -n (network namespace)' : 'unshare -Urn (user+network namespace)',
+        bin: unshare,
+        args,
+        probe: attempt,
+        attempts,
+      }
+    }
+  }
+  return {
+    isolated: false,
+    degraded: SANDBOX_DEGRADED.unshare,
+    reason: 'unshare -n and unshare -Urn both failed; no network namespace',
+    attempts,
+  }
+}
+
+function readLimitsProbe() {
+  return [
+    "const t = require('fs').readFileSync('/proc/self/limits', 'utf8')",
+    "const pick = (label) => { const m = new RegExp('^' + label + '\\\\s+(\\\\d+)', 'm').exec(t); return m ? Number(m[1]) : null }",
+    "console.log(JSON.stringify({ nproc: pick('Max processes'), as: pick('Max address space') }))",
+  ].join(';')
+}
+
+/**
+ * Apply and verify `prlimit --nproc --as`. The probe prints the child's own
+ * `/proc/self/limits`, so `applied` lists effects, not intentions.
+ */
+export function probeLimits({
+  platform = process.platform,
+  prlimit = 'prlimit',
+  nproc = null,
+  asBytes = 4 * 1024 ** 3,
+  node = process.execPath,
+  timeoutMs = 15_000,
+} = {}) {
+  if (platform === 'win32') {
+    return { available: false, degraded: SANDBOX_DEGRADED.prlimit, reason: 'prlimit is a util-linux tool; win32 has no equivalent here', applied: [] }
+  }
+  const requestedNproc = Number.isFinite(nproc) && nproc > 0 ? Math.trunc(nproc) : defaultNproc()
+  const requestedAs = Number.isFinite(asBytes) && asBytes > 0 ? Math.trunc(asBytes) : 4 * 1024 ** 3
+  const command = [prlimit, `--nproc=${requestedNproc}`, `--as=${requestedAs}`, '--', node, '-e', readLimitsProbe()]
+  const result = spawnSync(prlimit, command.slice(1), {
+    encoding: 'utf8', timeout: timeoutMs, env: sanitizedEnv(),
+  })
+  const exitCode = Number.isInteger(result.status) ? result.status : null
+  let observed = null
+  try {
+    const line = String(result.stdout ?? '').trim().split(/\r?\n/).filter(Boolean).pop()
+    observed = line ? JSON.parse(line) : null
+  } catch { observed = null }
+  const applied = []
+  if (observed?.nproc === requestedNproc) applied.push('nproc')
+  if (observed?.as === requestedAs) applied.push('as')
+  const available = !result.error && exitCode === 0 && applied.length === 2
+  return {
+    available,
+    ...(available ? {} : { degraded: SANDBOX_DEGRADED.prlimit }),
+    bin: prlimit,
+    nproc: requestedNproc,
+    asBytes: requestedAs,
+    applied,
+    observed,
+    probe: {
+      command,
+      exitCode,
+      signal: result.signal ?? null,
+      error: probeFailure(result.error),
+      stderr: String(result.stderr ?? '').trim().slice(0, 300) || null,
+    },
+    ...(available ? {} : { reason: 'prlimit did not apply and verify nproc+as' }),
+  }
+}
+
+export function processTreeKillCapability(platform = process.platform) {
+  if (platform === 'win32') {
+    const probe = spawnSync('taskkill', ['/?'], { stdio: 'ignore', timeout: 5_000 })
+    const available = !probe.error
+    return {
+      available,
+      mechanism: available ? 'taskkill /T /F' : 'taskkill-missing',
+      ...(available ? {} : { degraded: SANDBOX_DEGRADED.treeKill, reason: 'taskkill is unavailable' }),
+    }
+  }
+  return { available: true, mechanism: 'process-group SIGKILL (detached child, kill(-pgid))' }
+}
+
+/**
+ * Build the containment report for one collection. Degraded reasons are
+ * deduplicated; `mode` is `sandbox` only when the list is empty.
+ */
+export function buildSandboxPlan({
+  platform = process.platform,
+  env = process.env,
+  unshare = 'unshare',
+  prlimit = 'prlimit',
+  nproc = null,
+  asBytes = 4 * 1024 ** 3,
+  homeIsolated = true,
+  force = {},
+} = {}) {
+  const degraded = []
+  const envOffenders = credentialEnvOffenders(env)
+  if (envOffenders.length > 0) degraded.push(SANDBOX_DEGRADED.env)
+  if (!homeIsolated) degraded.push(SANDBOX_DEGRADED.home)
+
+  const network = force.network
+    ? { isolated: false, degraded: SANDBOX_DEGRADED.unshare, reason: 'network isolation disabled by caller', attempts: [] }
+    : probeNetworkIsolation({ platform, unshare })
+  if (!network.isolated) degraded.push(network.degraded ?? SANDBOX_DEGRADED.unshare)
+
+  const limits = force.limits
+    ? { available: false, degraded: SANDBOX_DEGRADED.prlimit, reason: 'rlimits disabled by caller', applied: [] }
+    : probeLimits({ platform, prlimit, nproc, asBytes })
+  if (!limits.available) degraded.push(limits.degraded ?? SANDBOX_DEGRADED.prlimit)
+
+  const processTreeKill = processTreeKillCapability(platform)
+  if (!processTreeKill.available) degraded.push(processTreeKill.degraded ?? SANDBOX_DEGRADED.treeKill)
+
+  const unique = [...new Set(degraded)]
+  return {
+    schema: SANDBOX_REPORT_SCHEMA,
+    mode: unique.length === 0 ? 'sandbox' : 'sandbox-degraded',
+    platform,
+    env: {
+      policy: 'allowlist',
+      checked: [...CREDENTIAL_ENV_NAMES],
+      absent: envOffenders.length === 0,
+      offenders: envOffenders,
+    },
+    home: { isolated: homeIsolated, mode: 'temporary HOME/DSH_HOME/TMPDIR' },
+    network,
+    limits,
+    processTreeKill,
+    degraded: unique,
+    note: 'containment only: no seccomp, no cgroup memory/pids accounting, no OCI image; read access is not restricted',
+  }
+}
+
+/** Wrap `command args...` in the effective prlimit + unshare prefixes. */
+export function sandboxArgv(plan, command, args = []) {
+  let argv = [command, ...args]
+  if (plan?.limits?.available) {
+    argv = [plan.limits.bin, `--nproc=${plan.limits.nproc}`, `--as=${plan.limits.asBytes}`, '--', ...argv]
+  }
+  if (plan?.network?.isolated) {
+    argv = [plan.network.bin, ...plan.network.args, ...argv]
+  }
+  return argv
+}
+
+function groupAlive(pgid, platform) {
+  try {
+    process.kill(platform === 'win32' ? pgid : -pgid, 0)
+    return true
+  } catch (error) {
+    return error?.code === 'EPERM'
+  }
+}
+
+function waitForGroupExit(pgid, platform, timeoutMs) {
+  return new Promise((resolve) => {
+    const deadline = Date.now() + timeoutMs
+    const tick = () => {
+      if (!groupAlive(pgid, platform)) { resolve(true); return }
+      if (Date.now() >= deadline) { resolve(false); return }
+      setTimeout(tick, 50)
+    }
+    tick()
+  })
+}
+
+/** Terminate the child *and its whole process group* (never just the parent). */
+export function killProcessTree(pid, { platform = process.platform, signal = 'SIGKILL' } = {}) {
+  if (!pid) return { mechanism: 'none', signalled: false, pid: null }
+  if (platform === 'win32') {
+    const result = spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', timeout: 10_000 })
+    return { mechanism: 'taskkill /pid <pid> /T /F', signalled: !result.error && result.status === 0, pid, exitCode: result.status ?? null }
+  }
+  let signalled = false
+  try { process.kill(-pid, signal); signalled = true } catch { /* group already gone */ }
+  try { process.kill(pid, signal); signalled = true } catch { /* parent already gone */ }
+  return { mechanism: `process-group ${signal}`, signalled, pid, pgid: pid }
+}
+
+/**
+ * Spawn and supervise one command. On timeout the process group is SIGKILLed
+ * and `treeKill.cleared` is verified before resolving.
+ */
+export function runInProcessTree({
+  command,
+  args = [],
+  cwd = process.cwd(),
+  env = sanitizedEnv(),
+  timeoutMs = 120_000,
+  platform = process.platform,
+  maxBufferBytes = 8 * 1024 * 1024,
+  killGraceMs = 2_000,
+} = {}) {
+  return new Promise((resolve) => {
+    const startedAt = new Date().toISOString()
+    const t0 = Date.now()
+    let child
+    try {
+      child = spawn(command, args, {
+        cwd,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: platform !== 'win32',
+        windowsHide: true,
+      })
+    } catch (error) {
+      resolve({
+        command: [command, ...args], exitCode: null, signal: null, killed: false, timedOut: false,
+        stdout: '', stderr: `spawn error: ${error.message}`, startedAt, endedAt: new Date().toISOString(),
+        durationMs: Date.now() - t0, treeKill: null, spawnError: error.message,
+      })
+      return
+    }
+    let stdout = ''
+    let stderr = ''
+    let stdoutBytes = 0
+    let stderrBytes = 0
+    let timedOut = false
+    let treeKill = null
+    let settled = false
+    let timer = null
+    const append = (chunk, stream) => {
+      const text = String(chunk)
+      if (stream === 'stdout') {
+        if (stdoutBytes < maxBufferBytes) stdout += text.slice(0, maxBufferBytes - stdoutBytes)
+        stdoutBytes += Buffer.byteLength(text)
+      } else {
+        if (stderrBytes < maxBufferBytes) stderr += text.slice(0, maxBufferBytes - stderrBytes)
+        stderrBytes += Buffer.byteLength(text)
+      }
+    }
+    const finalize = async (code, signal) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      if (treeKill) {
+        treeKill.cleared = await waitForGroupExit(child.pid, platform, killGraceMs)
+      }
+      resolve({
+        command: [command, ...args],
+        exitCode: Number.isInteger(code) ? code : timedOut ? 124 : null,
+        signal: signal ?? null,
+        killed: Boolean(treeKill),
+        timedOut,
+        stdout,
+        stderr,
+        startedAt,
+        endedAt: new Date().toISOString(),
+        durationMs: Date.now() - t0,
+        treeKill,
+        stdoutTruncated: stdoutBytes > maxBufferBytes,
+        stderrTruncated: stderrBytes > maxBufferBytes,
+        pid: child.pid ?? null,
+      })
+    }
+    child.stdout?.on('data', (chunk) => append(chunk, 'stdout'))
+    child.stderr?.on('data', (chunk) => append(chunk, 'stderr'))
+    child.on('error', (error) => {
+      stderr += `\n[spawn error] ${error.message}`
+      void finalize(null, null)
+    })
+    child.on('close', (code, signal) => { void finalize(code, signal) })
+    timer = setTimeout(() => {
+      timedOut = true
+      treeKill = killProcessTree(child.pid, { platform })
+    }, timeoutMs)
+    timer.unref?.()
+  })
+}

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 1.3.0 — 2026-11-06
+
+### Added
+
+- `check [dir]` 子命令：默认 cwd、Markdown 报告（一句结论、≤3 条优先修复、分桶全表、advice、免责声明），`--json` 与 `--html`（单文件、内联 CSS、零依赖）。
+- `spec/schemas/advice.schema.json`（`dsh-advice/1`），advice 逐条过 schema。
+- 证据主体绑定：`--flow-evidence --dir` 校验 name/version/treeSha256/tarball 哈希，不一致即 `invalid`。
+- CI 归属：collector 写 `producer.runUrl/repository/commit`，audit 标 `attestation: self-declared|ci`（不升级 claimLevel）。
+- sidecar 生成（`publish/sidecar.json`，`dsh-market-sidecar/1`）、每日过期/撤回 workflow、离线包（~580 KB）。
+- `SUPPORTED.md`（host × node × checker 矩阵 + 证据锚）与 `CHANGELOG-RULES.md`（规则级变更与影响面）。
+
+### Fixed
+
+- coverage 按全部 14 项统计，`na/notRun/error` 不再为 0；未查 C-3.1/3.2/3.5 时 `entryBlocking.pass=false`，并输出 `checked/notChecked`。
+- 默认 runtime 锚改为宿主实际版本（`anchor.runtimeSource=host`），与 `--runtime-version` 不一致时 `anchor.suspect=true`；不再固定 `0.2.2-alpha.2`。
+- 报告分三桶：`blocking`/`hygiene`（DSC-11/12/13 声明类）/`notChecked`，text 分组渲染，JSON 加 `buckets/metrics/headline`。
+
+### Verified
+
+- `npm test` 193/193（含 root `test/`）。
+
+## 1.2.2 — 2026-11-06
+
+- FLOW 沙箱：`flow collect --sandbox` 在 `unshare -Urn` + `prlimit` 下运行，记录 `sandbox{}`；env 白名单硬断言 token 不在子进程；进程组超时击杀；`producer.kind=sandbox` 仅当隔离项全部生效，否则 `sandbox-degraded` 且 audit 永不 runtime。测试 152 → 159。
+- 发布包：`npm test` 改为 `run-tests.mjs`，未随包分发的 test 目录不再导致安装后测试失败。
+
 ## 1.2.1 — 2026-11-06
 
 - **V2 核验修复**：`level-audit` 不再把结构自洽的 self-attested/ci-attested `dsh-flow-evidence/2` 判成 FLOW `runtime`。只有 `claims.claimLevel=sandbox-attested` 或 `producer.kind=sandbox` 才允许 `runtime`；self/ci 的 `passed` 计数保留但 state 记 `not-run`，reason 为 `<claimLevel> evidence; runtime requires sandbox-attested`。`spec/flow-evidence.schema.json` 的 `claims`/`producer.kind` 补充了该判定说明。`advice[]` 新增 `gate`（该 check 的最终结果 PASS/WARN/FAIL），`severity` 跟随 `gate`：ENTRY static claim 把 DSC-02 降为 WARN 时，C-2.1 的 FAIL detail 仍保留在 `reason`，但 advice severity 为 WARN。测试 150 → 152。