cli-validator 7.0.33 → 7.0.35

package/validator-local-cli.mjs

@@ -0,0 +1,49 @@
+import { stdin, stdout } from 'node:process'
+import { runApprovedValidatorPlan } from './validator-local-runner.mjs'
+import { RUNNER_LIMITS, RUNNER_PLAN_SCHEMA, RUNNER_APPROVAL_SCHEMA, RUNNER_SIGNER_SCHEMA } from './validator-runner-plan.mjs'
+
+const CAPABILITIES = Object.freeze({
+  schemaVersion: 'validator.local-runner/1.0',
+  operations: ['capabilities', 'run-approved-plan'],
+  operationSchemas: {
+    capabilities: { type: 'object', additionalProperties: false, properties: {} },
+    'run-approved-plan': {
+      type: 'object', additionalProperties: false,
+      required: ['repositoryRoot', 'planPath', 'approvalPath', 'signerConfigPath'],
+      properties: {
+        repositoryRoot: { type: 'string', minLength: 1 }, planPath: { type: 'string', minLength: 1 },
+        approvalPath: { type: 'string', minLength: 1 }, signerConfigPath: { type: ['string', 'null'] },
+      },
+    },
+  },
+  planSchema: RUNNER_PLAN_SCHEMA, approvalSchema: RUNNER_APPROVAL_SCHEMA, signerSchema: RUNNER_SIGNER_SCHEMA,
+  limits: RUNNER_LIMITS,
+  boundary: 'POSIX subprocess runner; external preapproval required. Signed receipts require separately configured trust and isolation.',
+})
+
+async function readInput() {
+  const chunks = []
+  let bytes = 0
+  for await (const chunk of stdin) {
+    bytes += Buffer.byteLength(chunk)
+    if (bytes > RUNNER_LIMITS.maxControlBytes) throw new Error('Validator runner input exceeds its limit')
+    chunks.push(Buffer.from(chunk))
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+export async function runValidatorLocalCli(args) {
+  try {
+    if (args.length !== 1 || !CAPABILITIES.operations.includes(args[0])) {
+      throw new Error('Usage: cli-validator local capabilities | local run-approved-plan < runner-input.json')
+    }
+    const output = args[0] === 'capabilities' ? CAPABILITIES : await runApprovedValidatorPlan(await readInput())
+    stdout.write(JSON.stringify(output) + '\n')
+    if (output.status === 'failed') process.exitCode = 1
+  } catch (error) {
+    const failure = { status: 'failed', error: error instanceof Error ? error.message : String(error) }
+    if (error instanceof Error && error.execution) failure.execution = error.execution
+    stdout.write(JSON.stringify(failure) + '\n')
+    process.exitCode = 1
+  }
+}

package/validator-local-runner.mjs

@@ -0,0 +1,170 @@
+import { spawn } from 'node:child_process'
+import { createHash, randomUUID, sign } from 'node:crypto'
+import { performance } from 'node:perf_hooks'
+import {
+  bytesSha256, loadApprovedExecutionPlan, loadApprovedSigner, validationSubjectForPlan, verifyPlanFiles,
+} from './validator-runner-plan.mjs'
+import { validatorReceiptPayload, validatorReceiptSubject } from './validator-runtime.mjs'
+
+const TERMINATION_GRACE_MS = 250
+const REAP_DEADLINE_MS = 1_000
+const EXECUTION_SCHEMA = 'validator.runner-execution/1.0'
+const EVIDENCE_SCHEMA = 'cli.tax.test-evidence/1.0'
+const RECEIPT_SCHEMA = 'validator.execution-receipt/1.0'
+
+function signalProcessGroup(child, signal) {
+  if (!Number.isInteger(child.pid)) throw new Error('Runner child has no process identifier')
+  try {
+    process.kill(-child.pid, signal)
+    return { signal, status: 'delivered' }
+  } catch (error) {
+    if (!(error instanceof Error) || !('code' in error) || error.code !== 'ESRCH') throw error
+    return { signal, status: 'already-exited' }
+  }
+}
+
+function executeBoundedCommand(authority) {
+  const { policy } = authority.plan
+  return new Promise((resolve, reject) => {
+    const started = performance.now()
+    const child = spawn(policy.executable, policy.args, {
+      cwd: authority.root, env: { ...policy.environment },
+      shell: false, detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const termination = []
+    const stdout = []
+    const stderr = []
+    const stdoutHash = createHash('sha256')
+    const stderrHash = createHash('sha256')
+    let capturedBytes = 0
+    let droppedBytes = 0
+    let timedOut = false
+    let outputLimitExceeded = false
+    let terminating = false
+    let escalation = null
+    let failure = null
+    const terminate = () => {
+      if (terminating) return
+      terminating = true
+      try {
+        termination.push(signalProcessGroup(child, 'SIGTERM'))
+        escalation = setTimeout(() => {
+          try { termination.push(signalProcessGroup(child, 'SIGKILL')) } catch (error) { failure = error }
+        }, TERMINATION_GRACE_MS)
+      } catch (error) {
+        failure = error
+      }
+    }
+    const timer = setTimeout(() => { timedOut = true; terminate() }, policy.timeoutMs)
+    const hardLimit = setTimeout(() => {
+      clearTimeout(timer)
+      if (escalation !== null) clearTimeout(escalation)
+      try { if (Number.isInteger(child.pid)) termination.push(signalProcessGroup(child, 'SIGKILL')) } catch (error) { failure = error }
+      child.stdout.destroy()
+      child.stderr.destroy()
+      child.unref()
+      reject(new Error('Validator process could not be reaped within its hard deadline', { cause: failure }))
+    }, policy.timeoutMs + TERMINATION_GRACE_MS + REAP_DEADLINE_MS)
+    const consume = (target, hash, chunk) => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      hash.update(bytes)
+      const remaining = policy.maxOutputBytes - capturedBytes
+      const retained = Math.min(bytes.length, remaining)
+      if (retained > 0) target.push(Buffer.from(bytes.subarray(0, retained)))
+      capturedBytes += retained
+      droppedBytes += bytes.length - retained
+      if (droppedBytes > 0) { outputLimitExceeded = true; terminate() }
+    }
+    child.stdout.on('data', (chunk) => consume(stdout, stdoutHash, chunk))
+    child.stderr.on('data', (chunk) => consume(stderr, stderrHash, chunk))
+    child.once('error', (error) => { failure = error })
+    child.once('close', (exitCode, signal) => {
+      clearTimeout(timer)
+      clearTimeout(hardLimit)
+      if (escalation !== null) clearTimeout(escalation)
+      try { if (Number.isInteger(child.pid)) termination.push(signalProcessGroup(child, 'SIGKILL')) } catch (error) { failure = error }
+      if (failure !== null) return reject(new Error('Validator subprocess lifecycle failed', { cause: failure }))
+      resolve({
+        exitCode, signal, timedOut, outputLimitExceeded,
+        durationMs: Math.max(0, Math.round(performance.now() - started)),
+        stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8'),
+        stdoutSha256: stdoutHash.digest('hex'), stderrSha256: stderrHash.digest('hex'),
+        capturedBytes, droppedBytes, termination,
+      })
+    })
+  })
+}
+
+function executionSummary(result) {
+  if (result.timedOut) return 'Approved validation command exceeded its deadline'
+  if (result.outputLimitExceeded) return 'Approved validation command exceeded its output limit'
+  if (result.signal !== null) return `Approved validation command ended on signal ${result.signal}`
+  return `Approved validation command exited with code ${result.exitCode}`
+}
+
+export function validatorExecutionLogsDigest(result) {
+  return bytesSha256(JSON.stringify({
+    stdout: result.stdout, stderr: result.stderr, stdoutSha256: result.stdoutSha256, stderrSha256: result.stderrSha256,
+    capturedBytes: result.capturedBytes, droppedBytes: result.droppedBytes,
+  }))
+}
+
+function receiptSummary(result) {
+  return JSON.stringify({
+    message: executionSummary(result), logsSha256: validatorExecutionLogsDigest(result),
+    stdoutSha256: result.stdoutSha256, stderrSha256: result.stderrSha256,
+    capturedBytes: result.capturedBytes, droppedBytes: result.droppedBytes,
+  })
+}
+
+function localEvidence(subject, result, summary) {
+  if (!Number.isInteger(result.exitCode)) return null
+  return {
+    schemaVersion: EVIDENCE_SCHEMA, evidenceId: `${subject.validationRunId}:process`,
+    kind: 'test', runner: 'local', command: subject.policy.command,
+    exitCode: result.exitCode, durationMs: result.durationMs, summary,
+    artifactSha256: subject.artifactSha256, subject, subjectDigest: validatorReceiptSubject(subject),
+  }
+}
+
+function signedEvidence(subject, result, summary, signer, passed) {
+  const issuedAt = new Date()
+  const unsigned = {
+    schemaVersion: RECEIPT_SCHEMA, keyId: signer.keyId, nonce: `receipt-${randomUUID()}`,
+    subjectDigest: validatorReceiptSubject(subject), issuedAt: issuedAt.toISOString(),
+    expiresAt: new Date(issuedAt.getTime() + signer.receiptTtlMs).toISOString(),
+    result: { runner: 'trusted-runner', passed, exitCode: result.exitCode,
+      durationMs: result.durationMs, summary },
+  }
+  const receipt = { ...unsigned,
+    signature: sign(null, Buffer.from(validatorReceiptPayload(unsigned)), signer.key).toString('base64url') }
+  return { ...localEvidence(subject, result, summary), runner: 'trusted-runner', receipt }
+}
+
+export async function runApprovedValidatorPlan(input) {
+  const authority = await loadApprovedExecutionPlan(input)
+  const subject = validationSubjectForPlan(authority.plan, authority.planSha256, new Date().toISOString())
+  const result = await executeBoundedCommand(authority)
+  try {
+    await verifyPlanFiles(authority)
+  } catch (error) {
+    const failure = new Error('Validator integrity changed during execution', { cause: error })
+    failure.execution = { schemaVersion: EXECUTION_SCHEMA, status: 'failed', subject, process: result, evidence: [] }
+    throw failure
+  }
+  const passed = result.exitCode === authority.plan.policy.requiredExitCode
+    && result.signal === null && !result.timedOut && !result.outputLimitExceeded
+  const summary = receiptSummary(result)
+  const signer = Number.isInteger(result.exitCode) ? await loadApprovedSigner(authority) : null
+  const evidence = signer === null ? localEvidence(subject, result, summary)
+    : signedEvidence(subject, result, summary, signer, passed)
+  return {
+    schemaVersion: EXECUTION_SCHEMA, status: passed ? 'succeeded' : 'failed',
+    planSha256: authority.planSha256,
+    approvalSha256: authority.approval.sha256, approvedBy: authority.approval.approval.approvedBy,
+    subject, process: result, evidence: evidence === null ? [] : [evidence],
+    receipt: evidence !== null && signer !== null ? evidence.receipt : null,
+    signingBoundary: signer === null ? 'local-evidence-only'
+      : 'configured-signature-only; independent-uid-or-container-isolation-required-for-production-trust',
+  }
+}

package/validator-runner-plan.mjs

@@ -0,0 +1,306 @@
+import { constants } from 'node:fs'
+import { lstat, open, realpath } from 'node:fs/promises'
+import { createHash, createPrivateKey, createPublicKey } from 'node:crypto'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+import {
+  run as validateProtocol, validatorArtifactSubject,
+} from './validator-runtime.mjs'
+
+export const RUNNER_PLAN_SCHEMA = 'validator.execution-plan/1.0'
+export const RUNNER_APPROVAL_SCHEMA = 'validator.runner-approval/1.0'
+export const RUNNER_SIGNER_SCHEMA = 'validator.runner-signer/1.0'
+export const RUNNER_LIMITS = Object.freeze({
+  maxFiles: 512, maxFileBytes: 16 * 1024 * 1024, maxManifestBytes: 64 * 1024 * 1024,
+  maxControlBytes: 1024 * 1024, maxExecutableBytes: 256 * 1024 * 1024, maxTimeoutMs: 300_000, maxOutputBytes: 1024 * 1024,
+  maxApprovalLifetimeMs: 24 * 60 * 60 * 1000, maxReceiptLifetimeMs: 600_000,
+})
+const SHA = /^[0-9a-f]{64}$/
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const ENVIRONMENT_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+export function bytesSha256(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+function exactObject(value, fields, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join('|') !== [...fields].sort().join('|')) {
+    throw new Error(`${label} has invalid fields`)
+  }
+  return value
+}
+
+function positiveInteger(value, maximum, label) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maximum) {
+    throw new Error(`${label} must be a positive bounded integer`)
+  }
+}
+
+function relativeFile(value) {
+  if (typeof value !== 'string' || !value || value !== value.normalize('NFC')
+    || isAbsolute(value) || /^[A-Za-z]:/.test(value) || value.includes('\\')
+    || /[\u0000-\u001f\u007f]/.test(value)
+    || value.split('/').some((part) => !part || part === '.' || part === '..')) {
+    throw new Error('Manifest paths must be normalized relative files')
+  }
+  return value
+}
+
+function inside(root, target) {
+  const path = relative(root, target)
+  return path === '' || (!isAbsolute(path) && path !== '..' && !path.startsWith(`..${sep}`))
+}
+
+export async function readRegularFile(path, maximum, privateFile) {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const before = await handle.stat()
+    if (!before.isFile() || before.size > maximum) throw new Error('File is not regular or exceeds its limit')
+    if (privateFile && (before.uid !== process.getuid() || (before.mode & 0o777) !== 0o600
+      || before.nlink !== 1)) throw new Error('Runner control files must be owned by the runner and mode 0600')
+    const bytes = await handle.readFile()
+    const after = await handle.stat()
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs
+      || bytes.length !== after.size) throw new Error('File changed while being read')
+    return { bytes, byteLength: bytes.length, sha256: bytesSha256(bytes), device: before.dev, inode: before.ino }
+  } finally {
+    await handle.close()
+  }
+}
+
+async function hashRegularFile(path, maximum) {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const before = await handle.stat()
+    if (!before.isFile() || before.size > maximum) throw new Error('Hash target is not a bounded regular file')
+    const hash = createHash('sha256')
+    const buffer = Buffer.alloc(64 * 1024)
+    let byteLength = 0
+    while (true) {
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, null)
+      if (bytesRead === 0) break
+      byteLength += bytesRead
+      if (byteLength > maximum) throw new Error('Hash target grew beyond its limit')
+      hash.update(buffer.subarray(0, bytesRead))
+    }
+    const after = await handle.stat()
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs
+      || byteLength !== after.size) throw new Error('Hash target changed while being read')
+    return { byteLength, sha256: hash.digest('hex'), device: before.dev, inode: before.ino }
+  } finally {
+    await handle.close()
+  }
+}
+
+async function externalFile(root, path, maximum) {
+  if (typeof path !== 'string' || !isAbsolute(path)) throw new Error('External runner control path must be absolute')
+  const status = await lstat(path)
+  if (status.isSymbolicLink()) throw new Error('External runner control cannot be a symlink')
+  const canonical = await realpath(path)
+  if (inside(root, canonical)) throw new Error('Runner controls and keys must be outside the tested workspace')
+  return { path: canonical, ...(await readRegularFile(canonical, maximum, true)) }
+}
+
+async function projectFile(root, path, contents) {
+  const name = relativeFile(path)
+  let target = root
+  for (const [index, part] of name.split('/').entries()) {
+    target = resolve(target, part)
+    const status = await lstat(target)
+    if (status.isSymbolicLink() || (index < name.split('/').length - 1 && !status.isDirectory())) {
+      throw new Error('Workspace files cannot traverse symlinks or non-directory parents')
+    }
+  }
+  if (!inside(root, await realpath(target))) throw new Error('Workspace file escapes its root')
+  const data = contents ? await readRegularFile(target, RUNNER_LIMITS.maxFileBytes, false)
+    : await hashRegularFile(target, RUNNER_LIMITS.maxFileBytes)
+  return { path: target, ...data }
+}
+
+function validateExecutionPolicy(policy, tests, files) {
+  exactObject(policy, ['executable', 'executableSha256', 'args', 'environment',
+    'timeoutMs', 'maxOutputBytes', 'requiredExitCode'], 'Execution policy')
+  if (typeof policy.executable !== 'string' || !isAbsolute(policy.executable)
+    || !SHA.test(policy.executableSha256)) throw new Error('Executable requires an absolute path and SHA-256')
+  if (!Array.isArray(policy.args) || policy.args.length > 128
+    || policy.args.some((value) => typeof value !== 'string' || value.includes('\0') || value.length > 4096)) {
+    throw new Error('Executable args must be a bounded string array')
+  }
+  if (!policy.environment || typeof policy.environment !== 'object' || Array.isArray(policy.environment)
+    || Object.keys(policy.environment).length > 64
+    || Object.entries(policy.environment).some(([key, value]) => !ENVIRONMENT_KEY.test(key)
+      || typeof value !== 'string' || value.includes('\0') || value.length > 16_384)) {
+    throw new Error('Child environment must be explicit and bounded')
+  }
+  positiveInteger(policy.timeoutMs, RUNNER_LIMITS.maxTimeoutMs, 'timeoutMs')
+  positiveInteger(policy.maxOutputBytes, RUNNER_LIMITS.maxOutputBytes, 'maxOutputBytes')
+  if (policy.requiredExitCode !== 0) throw new Error('Validation requires exit code zero')
+  if (!Array.isArray(tests) || !tests.length || tests.length > RUNNER_LIMITS.maxFiles) {
+    throw new Error('Frozen tests must be non-empty and bounded')
+  }
+  for (const item of tests) {
+    exactObject(item, ['testId', 'path'], 'Frozen test')
+    if (!IDENTIFIER.test(item.testId) || !files.some((file) => file.path === item.path)
+      || !policy.args.includes(relativeFile(item.path))) {
+      throw new Error('Each test must be in the manifest and passed explicitly as a command argument')
+    }
+  }
+}
+
+function validateFrozenPlan(plan) {
+  exactObject(plan, ['schemaVersion', 'frozen', 'planId', 'validationRunId', 'memberId', 'chainId',
+    'artifactSha256', 'files', 'tests', 'policy', 'goldenBaseline', 'contracts'], 'Frozen execution plan')
+  if (plan.schemaVersion !== RUNNER_PLAN_SCHEMA || plan.frozen !== true
+    || !SHA.test(plan.artifactSha256) || !Array.isArray(plan.files)
+    || !plan.files.length || plan.files.length > RUNNER_LIMITS.maxFiles) {
+    throw new Error('Frozen execution plan is invalid')
+  }
+  for (const [index, file] of plan.files.entries()) {
+    exactObject(file, ['path', 'sha256'], 'Manifest entry')
+    relativeFile(file.path)
+    if (!SHA.test(file.sha256) || (index > 0 && plan.files[index - 1].path >= file.path)) {
+      throw new Error('Manifest paths must be unique, sorted and SHA-bound')
+    }
+  }
+  if (validatorArtifactSubject(plan.files) !== plan.artifactSha256) throw new Error('Artifact manifest digest mismatch')
+  validateExecutionPolicy(plan.policy, plan.tests, plan.files)
+  if (plan.contracts?.archguard?.driftStatus === 'red') throw new Error('ArchGuard red blocks execution')
+  return plan
+}
+
+export function validationSubjectForPlan(plan, planSha256, executedAt) {
+  return {
+    schemaVersion: 'validator.validation-subject/1.0',
+    artifactSha256: plan.artifactSha256, memberId: plan.memberId, chainId: plan.chainId,
+    executedAt, files: plan.files, validationRunId: plan.validationRunId, planId: plan.planId,
+    tests: plan.tests,
+    policy: { command: [plan.policy.executable, ...plan.policy.args].map((value) => JSON.stringify(value)).join(' '),
+      requiredExitCode: plan.policy.requiredExitCode, executionPlanSha256: planSha256 },
+    goldenBaseline: plan.goldenBaseline, contracts: plan.contracts,
+  }
+}
+
+async function validateApproval(root, approvalPath, planSha256) {
+  const file = await externalFile(root, approvalPath, RUNNER_LIMITS.maxControlBytes)
+  const approval = exactObject(JSON.parse(file.bytes.toString('utf8')),
+    ['schemaVersion', 'repositoryRoot', 'planSha256', 'approvedBy', 'approvedAt', 'expiresAt'],
+    'Runner approval')
+  const approvedAt = Date.parse(approval.approvedAt)
+  const expiresAt = Date.parse(approval.expiresAt)
+  if (approval.schemaVersion !== RUNNER_APPROVAL_SCHEMA || approval.repositoryRoot !== root
+    || approval.planSha256 !== planSha256 || !IDENTIFIER.test(approval.approvedBy)
+    || !Number.isFinite(approvedAt) || !Number.isFinite(expiresAt)
+    || approvedAt > Date.now() || expiresAt <= Date.now() || expiresAt <= approvedAt
+    || expiresAt - approvedAt > RUNNER_LIMITS.maxApprovalLifetimeMs) {
+    throw new Error('External approval is expired or does not match the frozen plan')
+  }
+  return { ...file, approval }
+}
+
+async function signerAuthority(root, signerConfigPath, policy) {
+  if (signerConfigPath === null) return null
+  const file = await externalFile(root, signerConfigPath, RUNNER_LIMITS.maxControlBytes)
+  const config = exactObject(JSON.parse(file.bytes.toString('utf8')),
+    ['schemaVersion', 'privateKeyPath', 'keyId', 'receiptTtlMs'], 'Runner signer')
+  if (config.schemaVersion !== RUNNER_SIGNER_SCHEMA || !SHA.test(config.keyId)) {
+    throw new Error('External runner signer configuration is invalid')
+  }
+  positiveInteger(config.receiptTtlMs, RUNNER_LIMITS.maxReceiptLifetimeMs, 'receiptTtlMs')
+  const privatePath = await realpath(config.privateKeyPath)
+  if (!isAbsolute(config.privateKeyPath) || inside(root, privatePath)
+    || JSON.stringify([policy.args, policy.environment]).includes(config.privateKeyPath)
+    || JSON.stringify([policy.args, policy.environment]).includes(privatePath)
+    || JSON.stringify([policy.args, policy.environment]).includes(file.path)) {
+    throw new Error('Signer paths cannot be inside the workspace or passed to the child')
+  }
+  const keyStatus = await lstat(config.privateKeyPath)
+  if (keyStatus.isSymbolicLink() || !keyStatus.isFile() || keyStatus.uid !== process.getuid()
+    || (keyStatus.mode & 0o777) !== 0o600 || keyStatus.nlink !== 1) {
+    throw new Error('Runner private key must be a regular owned mode-0600 external file')
+  }
+  return { ...file, config: { ...config, privateKeyPath: privatePath } }
+}
+
+async function verifyBrainControlAuthority(authority) {
+  if (authority.plan.contracts.brain === undefined) return
+  if (process.getuid() !== 0) throw new Error('Brain validation requires an isolated privileged runner')
+  const executable = await lstat(authority.plan.policy.executable)
+  if (executable.uid !== 0 || (executable.mode & 0o022) !== 0) throw new Error('Brain runner executable must be root owned and protected')
+  for (const name of authority.plan.policy.args) {
+    const parts = relativeFile(name).split('/')
+    let target = authority.root
+    for (const [index, part] of ['', ...parts].entries()) {
+      if (part) target = resolve(target, part)
+      const status = await lstat(target)
+      if (status.uid !== 0 || status.isSymbolicLink() || (status.mode & 0o022) !== 0) {
+        throw new Error('Brain runner control paths must be root owned and protected')
+      }
+      if (index === parts.length && (!status.isFile() || status.nlink !== 1 || (status.mode & 0o777) !== 0o600)) {
+        throw new Error('Brain runner controls require root owned mode-0600 regular files')
+      }
+    }
+  }
+}
+
+export async function verifyPlanFiles(authority) {
+  await verifyBrainControlAuthority(authority)
+  let bytes = 0
+  for (const file of authority.plan.files) {
+    const actual = await projectFile(authority.root, file.path, false)
+    bytes += actual.byteLength
+    if (bytes > RUNNER_LIMITS.maxManifestBytes || actual.sha256 !== file.sha256) {
+      throw new Error(`Artifact changed or exceeds its bound: ${file.path}`)
+    }
+  }
+  const executable = await hashRegularFile(authority.plan.policy.executable, RUNNER_LIMITS.maxExecutableBytes)
+  if (executable.sha256 !== authority.plan.policy.executableSha256) throw new Error('Executable SHA-256 mismatch')
+  const plan = await projectFile(authority.root, authority.planPath, true)
+  if (plan.sha256 !== authority.planSha256) throw new Error('Frozen plan changed')
+  const approval = await validateApproval(authority.root, authority.approval.path, authority.planSha256)
+  if (approval.sha256 !== authority.approval.sha256) throw new Error('External approval changed')
+  if (authority.signer !== null) {
+    const signer = await externalFile(authority.root, authority.signer.path, RUNNER_LIMITS.maxControlBytes)
+    if (signer.sha256 !== authority.signer.sha256) throw new Error('External signer configuration changed')
+  }
+}
+
+export async function loadApprovedExecutionPlan(input) {
+  if (process.platform === 'win32' || typeof process.getuid !== 'function') {
+    throw new Error('This bounded subprocess runner requires a POSIX host')
+  }
+  exactObject(input, ['repositoryRoot', 'planPath', 'approvalPath', 'signerConfigPath'], 'Runner input')
+  if (typeof input.repositoryRoot !== 'string' || !isAbsolute(input.repositoryRoot)) {
+    throw new Error('repositoryRoot must be absolute')
+  }
+  const rootStatus = await lstat(input.repositoryRoot)
+  if (!rootStatus.isDirectory() || rootStatus.isSymbolicLink()) throw new Error('Workspace root must be a real directory')
+  const root = await realpath(input.repositoryRoot)
+  const planFile = await projectFile(root, input.planPath, true)
+  if (planFile.bytes.length > RUNNER_LIMITS.maxControlBytes) throw new Error('Frozen plan is too large')
+  const plan = validateFrozenPlan(JSON.parse(planFile.bytes.toString('utf8')))
+  const approval = await validateApproval(root, input.approvalPath, planFile.sha256)
+  const signer = await signerAuthority(root, input.signerConfigPath, plan.policy)
+  const authority = { root, plan, planPath: input.planPath, planSha256: planFile.sha256, approval, signer }
+  await verifyPlanFiles(authority)
+  const subject = validationSubjectForPlan(plan, planFile.sha256, new Date().toISOString())
+  const validation = await validateProtocol({ schemaVersion: 'validator.skill.request/1.0',
+    requestId: 'runner-subject-validation', operation: 'verdict',
+    input: { expectedSubject: subject, evidence: [], findings: [] } })
+  if (validation.status !== 'succeeded') throw new Error('Frozen validation subject fails the Validator protocol')
+  return authority
+}
+
+export async function loadApprovedSigner(authority) {
+  if (authority.signer === null) return null
+  const { config } = authority.signer
+  const file = await externalFile(authority.root, config.privateKeyPath, 16_384)
+  try {
+    const key = createPrivateKey(file.bytes)
+    if (key.asymmetricKeyType !== 'ed25519') throw new Error('Runner signer requires Ed25519')
+    const publicDer = createPublicKey(key).export({ format: 'der', type: 'spki' })
+    if (bytesSha256(publicDer) !== config.keyId) throw new Error('Runner signer public key fingerprint mismatch')
+    return { key, keyId: config.keyId, receiptTtlMs: config.receiptTtlMs }
+  } finally {
+    file.bytes.fill(0)
+  }
+}