cli-aimlock 7.0.19 → 7.0.25

package/README.md

@@ -1,14 +1,54 @@
 # cli-aimlock
 
-Aimlock — 智能目标 skill（CLI.Tax 发布）。
+Aimlock — 面向大型、深度、跨模块、高风险、并行或用户明确要求的工程修改的智能目标门禁（CLI.Tax 发布）。
+
+低难度、预计不超过 500 行、非跨模块、非高风险、不并行且用户未明确要求 Aimlock 的需求不会启动完整链；应直接处理，或最多调用一个匹配专项技能。用户明确要求 Aimlock 时会激活门禁。
+
+`run` 先在本地读取真实文件路径、最近 Git 改动规模、包边界和局部 import 图，推导目标文件、预计行数、跨模块和并行性；调用方自报值不会覆盖探测结果。信息模糊时从小档开始，超出实际预算后只逐级升级并继承已有快照和修改。bypass 不发起任何技能 HTTP 调用、不生成自动评价、不写需求文件。
+
+Aimlock is for substantial or explicitly assigned engineering changes. Small low-difficulty work bypasses only when the user did not explicitly request Aimlock, and is handled directly or with one matched specialist.
+
+`run` derives applicability from real paths, recent Git diffs, package boundaries, and the local import graph. Caller estimates cannot override this probe. Ambiguous work starts in the smaller mode and upgrades one level at a time while preserving existing evidence. Bypass makes no skill HTTP call, emits no automatic evaluation, and writes no requirements file.
+
+Aimlock предназначен для существенных или явно назначенных инженерных изменений. Небольшая простая задача обходит цепочку только если пользователь явно не потребовал Aimlock, и выполняется напрямую либо одним профильным навыком.
+
+`run` выводит факты из реальных путей, истории Git, границ пакетов и локального графа import; самооценка вызывающей стороны не переопределяет проверку. Неясная задача начинает с меньшего режима и повышается по одному уровню с сохранением доказательств. Bypass не выполняет HTTP-вызов, не создаёт автооценку и не записывает файл требований.
+
+激活后，单文件不超过 500 行走 Lock，最多三个文件且总计不超过 500 行走 Probe；目标文件超过三个、总改动超过 500 行、跨模块或必须并行时走 Swarm。Aimlock 不授予磁盘、网络、账号或系统“完全访问”，调用方只能按任务申请可撤销的最小权限。
+
+When active, Aimlock uses Lock for one file through 500 changed lines and Probe for at most three files through 500 lines; more than three target files, more than 500 lines, cross-module work, or required parallelism uses Swarm. Aimlock never grants full access: callers must use revocable, task-scoped least privilege.
+
+После активации Lock применяется к одному файлу до 500 строк, Probe — максимум к трём файлам до 500 строк; более трёх целевых файлов, более 500 строк, межмодульность или необходимая параллельность переводят работу в Swarm. Aimlock не выдаёт полный доступ: разрешения должны быть минимальными, отзывными и ограниченными задачей.
 
 - 把需求锁成可执行目标，阻止思考漂移、执行漂移、范围膨胀
-- Lock / Probe / Swarm 三档：小改不调蜂群；大改才派单
+- Bypass / Lock / Probe / Swarm 分档：小改绕过；深度修改才进入门禁
 - 改前文件快照，禁止创建 git 分支
-- 按目标调用 Blueprint、Swarm、Calctool
+- Lock / Probe / Swarm 分别强制 3 / 10 / 30 个文件与 2 / 8 / 15 分钟读取预算；Probe、Swarm 另有限制 30K / 100K 估算 token
+- Ed25519 写入凭证绑定 chainId、快照摘要、路径集合和最长 300 秒有效期
+- `probe.targetSymbols` 可从新鲜的 ContextBase 项目地图解析真实目标文件；缺失、歧义或陈旧条目直接阻断
+- 服务端按当前需求实时发现专项技能，只返回命中项；非计算需求不出现 Calctool
 
 安装：`npx cli-aimlock@latest install`
 
+## 可信本地执行
+
+IDE 宿主先调用本地探测与预算，再把批量写入统一路由到 `guarded-write`：
+
+```bash
+cli-aimlock local capabilities .
+cli-aimlock local probe .
+cli-aimlock local budget-init .
+cli-aimlock local budget-read .
+cli-aimlock local gate-issue .
+cli-aimlock local guarded-write .
+```
+
+每个命令从 stdin 读取 JSON。读取预算使用进程间原子锁，耗尽后只允许执行、输出方案或明确阻塞；追加预算必须携带 Confirm Protocol 的低风险确认回执。无凭证写入仅豁免 `.aimlock/logs/` 与 `.aimlock/tmp/`。
+
+Swarm 模式下，`chain-plan` 会在 `swarm` 前插入 `coordinator.conflict-scan`。`gate-issue` 必须显式声明 `coordinationRequired`；为 true 时凭证绑定 `.coord/leases/` 中的签名文件锁，`guarded-write` 在同一拦截点同时校验门禁与活动租约。存在活动 `dependency-wait` 的 chain 会被 `budget-read` 拒绝。
+
+物理边界：本包能拒绝所有经过 `guarded-write` 的无证写入，但不能劫持任意 IDE 的系统调用。IDE 集成必须禁止其他批量写入口，并让门禁运行在独立低权限宿主中；否则不得声称实现了全局物理拦截。
+
 
 也可以直接从 CLI.Tax 对象存储安装（与站点「安装命令」一致）：
 
@@ -18,4 +58,10 @@ npx https://cli.tax/cli-downloads/clitax-R3mQ8kWpXn.tgz install
 
 Source: https://github.com/88208555/aimlock-clitax.git
 
-反馈：技能详情页「使用评价」支持 好评 / 差评 / 日常聊天。好评与差评计入市场口碑（跑马灯每日清理），日常消息保留 7 天。
+## 受限调用与自动评价
+
+使用 `npx cli-aimlock@latest invoke <operation> '<JSON对象>'`，或让 IDE 以 JSON stdin 调用 `npx cli-aimlock@latest broker`。broker 本身只需要 Brain Client HTTPS、受限身份文件和显式传入路径，不需要完整磁盘访问。要保证 IDE 看不到 token，必须把 broker 作为独立低权限账户或沙箱服务运行并只暴露受限 IPC；同一系统账户下的 `0600` 不能隔离 IDE 与 broker。
+
+Brain Client 服务端在同一次 runtime 请求的事务中绑定真实响应、生成并持久化权威评分与评语，再返回已提交回执。broker 只验证 `feedbackReceiptId`、`feedbackInvocationId` 和权威摘要，不发起第二次评价写入，也不生成分数或评语。`not-reported`、验证不完整、P0/P1 findings、`blocked` 或 `failed` 都不得生成好评；缺凭证、缺回执、摘要不匹配、响应非法或 HTTP 失败都会显式失败。
+
+本地 CLI 不提供手工评分或评语提交命令，人类不能选择技能分数或填写技能评价。日常聊天不属于评价协议。

package/aimlock-context-map.mjs

@@ -0,0 +1,42 @@
+import { readFile } from 'node:fs/promises'
+import { repositoryRoot, resolvedProjectPath } from './aimlock-local-fs.mjs'
+
+const CONTEXT_MAP_SCHEMA = 'contextbase.project-map/1.0'
+
+function statSignature(status) {
+  return [status.dev, status.ino, status.size, status.mtimeMs, status.ctimeMs].join(':')
+}
+
+async function resolveContextMapTargets(root, targetSymbols) {
+  if (targetSymbols === undefined) return { targets: [], used: false }
+  if (!Array.isArray(targetSymbols) || targetSymbols.length === 0
+    || targetSymbols.some((symbol) => typeof symbol !== 'string' || !symbol.trim())) {
+    throw new Error('targetSymbols must be a non-empty string array')
+  }
+  const canonicalRoot = await repositoryRoot(root)
+  const mapFile = await resolvedProjectPath(canonicalRoot, '.contextbase/project-map.json')
+  const map = JSON.parse(await readFile(mapFile.target, 'utf8'))
+  if (map.schemaVersion !== CONTEXT_MAP_SCHEMA || !Array.isArray(map.entries)) {
+    throw new Error('ContextBase project map is invalid')
+  }
+  const targets = []
+  for (const requested of targetSymbols) {
+    const symbol = requested.trim()
+    const matches = map.entries.filter((entry) => Array.isArray(entry.exports)
+      && entry.exports.some((item) => item?.name === symbol))
+    if (matches.length !== 1) {
+      throw new Error(matches.length ? `${symbol} is ambiguous in the ContextBase map`
+        : `${symbol} is absent from the ContextBase map`)
+    }
+    const entry = matches[0]
+    const file = await resolvedProjectPath(canonicalRoot, entry.path)
+    if (statSignature(file.status) !== entry.signature) {
+      throw new Error(`ContextBase map entry is stale: ${entry.path}`)
+    }
+    targets.push(entry.path)
+  }
+  return { targets: [...new Set(targets)].sort(), used: true,
+    mapPath: mapFile.path }
+}
+
+export { CONTEXT_MAP_SCHEMA, resolveContextMapTargets }

package/aimlock-coordination.mjs

@@ -0,0 +1,97 @@
+import { verify } from 'node:crypto'
+import { lstat, readFile } from 'node:fs/promises'
+import { basename, resolve } from 'node:path'
+import {
+  LEASE_SCHEMA,
+  leasePayload,
+  withCoordinationReadLock,
+} from 'cli-swarm/coordinator-fs'
+import {
+  fail,
+  identifier,
+  repositoryRoot,
+  resolvedProjectPath,
+  safeRelativePath,
+  sha256,
+} from './aimlock-local-fs.mjs'
+
+function targetCovered(target, lockedPath) {
+  return target === lockedPath || target.startsWith(`${lockedPath}/`)
+}
+
+async function regularFile(path, code, message) {
+  const status = await lstat(path)
+  if (!status.isFile() || status.isSymbolicLink()) fail(code, message)
+  return path
+}
+
+async function verifyLeaseAgainstState(state, root, input) {
+  const leasePath = safeRelativePath(input.coordinationLeasePath, 'coordinationLeasePath')
+  if (!leasePath.startsWith('.coord/leases/')) {
+    fail('AIMLOCK_COORDINATION_LEASE_PATH_INVALID', 'coordination lease must be inside .coord/leases')
+  }
+  const leaseFile = await resolvedProjectPath(root, leasePath)
+  await regularFile(leaseFile.target, 'AIMLOCK_COORDINATION_LEASE_INVALID', 'coordination lease must be a regular file')
+  const lease = JSON.parse(await readFile(leaseFile.target, 'utf8'))
+  const publicPath = resolve(root, '.coord', 'authority', 'public.pem')
+  await regularFile(publicPath, 'AIMLOCK_COORDINATION_AUTHORITY_INVALID', 'coordination public key must be a regular file')
+  const publicKey = await readFile(publicPath, 'utf8')
+  const chainId = identifier(input.chainId, 'chainId')
+  const targetPaths = input.targetPaths.map((path) => safeRelativePath(path, 'targetPath'))
+  const signatureValid = typeof lease.signature === 'string'
+    && verify(null, Buffer.from(JSON.stringify(leasePayload(lease))), publicKey,
+      Buffer.from(lease.signature, 'base64url'))
+  const lock = state.locks.find((item) => item.lockId === lease.lockId)
+  const issuedAt = Date.parse(lease.issuedAt)
+  const expiresAt = Date.parse(lease.expiresAt)
+  const valid = lease.schemaVersion === LEASE_SCHEMA
+    && basename(leasePath) === `${lease.leaseId}.json`
+    && lease.authorityKeyId === sha256(publicKey)
+    && lease.chainId === chainId
+    && lease.lockType === 'file'
+    && Array.isArray(lease.paths) && lease.paths.length > 0
+    && targetPaths.every((target) => lease.paths.some((path) => targetCovered(target, path)))
+    && Number.isFinite(issuedAt) && Number.isFinite(expiresAt)
+    && issuedAt <= Date.now() && expiresAt > Date.now()
+    && signatureValid
+    && lock?.status === 'active' && lock.leaseId === lease.leaseId
+    && lock.chainId === lease.chainId && lock.agentId === lease.agentId
+    && lock.expiresAt === lease.expiresAt
+  if (!valid) {
+    fail('AIMLOCK_COORDINATION_LEASE_INVALID', 'coordination lease is forged, expired, released, or outside its lock scope')
+  }
+  return { lease, lock, leaseDigest: sha256(JSON.stringify(lease)), targetPaths }
+}
+
+async function withCoordinationLease(input, action) {
+  if (!Array.isArray(input.targetPaths) || input.targetPaths.length === 0) {
+    fail('AIMLOCK_COORDINATION_TARGETS_REQUIRED', 'targetPaths must be a non-empty array')
+  }
+  return withCoordinationReadLock(input.repositoryRoot, async (state, root) => (
+    action(await verifyLeaseAgainstState(state, root, input))
+  ))
+}
+
+async function verifyCoordinationLease(input) {
+  return withCoordinationLease(input, async (verified) => verified)
+}
+
+async function assertChainNotSuspended(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  const statePath = await resolvedProjectPath(root, '.coord/state.json', { allowMissing: true })
+  if (!statePath.exists) return { suspended: false }
+  const chainId = identifier(input.chainId, 'chainId')
+  return withCoordinationReadLock(root, async (state) => {
+    const wait = state.waits.find((item) => item.chainId === chainId && item.status === 'active')
+    if (wait) {
+      fail('AIMLOCK_COORDINATION_WAITING', `chain ${chainId} is suspended until ${wait.event} or ${wait.deadlineAt}`)
+    }
+    return { suspended: false }
+  })
+}
+
+export {
+  assertChainNotSuspended,
+  verifyCoordinationLease,
+  withCoordinationLease,
+}

package/aimlock-local-fs.mjs

@@ -0,0 +1,172 @@
+import { createHash, randomUUID } from 'node:crypto'
+import {
+  appendFile,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  realpath,
+  rename,
+  unlink,
+  writeFile,
+} from 'node:fs/promises'
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+
+const LOCAL_SCHEMA = 'aimlock.local-runner/1.0'
+const MANAGED_ROOT = '.aimlock'
+const LOCK_POLL_MS = 10
+const LOCK_TIMEOUT_MS = 2_000
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+function fail(code, message) {
+  const error = new Error(message)
+  error.code = code
+  throw error
+}
+
+function identifier(value, field) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value)) {
+    fail('AIMLOCK_IDENTIFIER_INVALID', `${field} must be a safe identifier`)
+  }
+  return value
+}
+
+function safeRelativePath(value, field = 'path') {
+  if (typeof value !== 'string' || !value || value !== value.normalize('NFC')
+    || isAbsolute(value) || /^[A-Za-z]:/.test(value) || value.includes('\\')
+    || /[\u0000-\u001f\u007f]/.test(value)) {
+    fail('AIMLOCK_PATH_UNSAFE', `${field} is unsafe`)
+  }
+  const parts = value.split('/')
+  if (parts.some((part) => !part || part === '.' || part === '..')) {
+    fail('AIMLOCK_PATH_UNSAFE', `${field} is unsafe`)
+  }
+  return parts.join('/')
+}
+
+function assertInside(root, target, field) {
+  const path = relative(root, target)
+  if (path === '' || (!isAbsolute(path) && path !== '..' && !path.startsWith('../'))) return
+  fail('AIMLOCK_PATH_ESCAPE', `${field} escapes the repository`)
+}
+
+async function canonicalMissingTarget(root, target) {
+  const suffix = [basename(target)]
+  let current = dirname(target)
+  for (;;) {
+    try {
+      const parent = await realpath(current)
+      assertInside(root, parent, 'missing path parent')
+      return resolve(parent, ...suffix)
+    } catch (error) {
+      if (!(error instanceof Error && error.code === 'ENOENT') || current === root) throw error
+      suffix.unshift(basename(current))
+      current = dirname(current)
+    }
+  }
+}
+
+async function repositoryRoot(value) {
+  const explicit = resolve(value)
+  const status = await lstat(explicit)
+  if (status.isSymbolicLink() || !status.isDirectory()) {
+    fail('AIMLOCK_ROOT_INVALID', 'repositoryRoot must be a real directory')
+  }
+  return realpath(explicit)
+}
+
+async function resolvedProjectPath(root, value, options = {}) {
+  const path = safeRelativePath(value)
+  const target = resolve(root, ...path.split('/'))
+  assertInside(root, target, 'path')
+  try {
+    const status = await lstat(target)
+    if (status.isSymbolicLink()) fail('AIMLOCK_PATH_SYMLINK', `${path} cannot be a symlink`)
+    const canonical = await realpath(target)
+    assertInside(root, canonical, 'path target')
+    return { path, target: canonical, status, exists: true }
+  } catch (error) {
+    if (!(error instanceof Error && error.code === 'ENOENT' && options.allowMissing)) throw error
+    return { path, target: await canonicalMissingTarget(root, target), status: null, exists: false }
+  }
+}
+
+function managedPath(root, ...parts) {
+  return resolve(root, MANAGED_ROOT, ...parts)
+}
+
+async function ensureManagedDirectory(root, ...parts) {
+  let current = root
+  for (const [index, part] of [MANAGED_ROOT, ...parts].entries()) {
+    if (index > 0) identifier(part, 'managed path segment')
+    current = resolve(current, part)
+    assertInside(root, current, 'managed directory')
+    try {
+      await mkdir(current, { mode: 0o700 })
+    } catch (error) {
+      if (!(error instanceof Error && error.code === 'EEXIST')) throw error
+    }
+    const status = await lstat(current)
+    if (status.isSymbolicLink() || !status.isDirectory()) {
+      fail('AIMLOCK_MANAGED_PATH_INVALID', 'managed directories must be real directories')
+    }
+  }
+  return current
+}
+
+async function appendAudit(root, record) {
+  const directory = await ensureManagedDirectory(root, 'audit')
+  await appendFile(resolve(directory, 'guard.jsonl'), `${JSON.stringify({
+    schemaVersion: LOCAL_SCHEMA,
+    at: new Date().toISOString(),
+    ...record,
+  })}\n`, { mode: 0o600 })
+}
+
+async function withFileLock(path, operation) {
+  const lockPath = `${path}.lock`
+  const deadline = Date.now() + LOCK_TIMEOUT_MS
+  let handle
+  while (!handle) {
+    try {
+      handle = await open(lockPath, 'wx', 0o600)
+    } catch (error) {
+      if (!(error instanceof Error && error.code === 'EEXIST')) throw error
+      if (Date.now() >= deadline) fail('AIMLOCK_LOCK_TIMEOUT', 'authority file is busy')
+      await delay(LOCK_POLL_MS)
+    }
+  }
+  try {
+    return await operation()
+  } finally {
+    await handle.close()
+    await unlink(lockPath)
+  }
+}
+
+async function atomicJson(path, value) {
+  const temporary = `${path}.${randomUUID()}.tmp`
+  await writeFile(temporary, `${JSON.stringify(value)}\n`, { flag: 'wx', mode: 0o600 })
+  await rename(temporary, path)
+}
+
+export {
+  LOCAL_SCHEMA,
+  MANAGED_ROOT,
+  appendAudit,
+  assertInside,
+  atomicJson,
+  ensureManagedDirectory,
+  fail,
+  identifier,
+  managedPath,
+  repositoryRoot,
+  resolvedProjectPath,
+  safeRelativePath,
+  sha256,
+  withFileLock,
+}

package/aimlock-local-gate.mjs

@@ -0,0 +1,275 @@
+import { generateKeyPairSync, randomUUID, sign, verify } from 'node:crypto'
+import { lstat, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { basename, dirname, resolve } from 'node:path'
+import { mutateGate, snapshotVerify } from './aimlock-runtime.mjs'
+import { verifyCoordinationLease, withCoordinationLease } from './aimlock-coordination.mjs'
+import {
+  LOCAL_SCHEMA,
+  MANAGED_ROOT,
+  appendAudit,
+  ensureManagedDirectory,
+  fail,
+  identifier,
+  repositoryRoot,
+  resolvedProjectPath,
+  safeRelativePath,
+  sha256,
+} from './aimlock-local-fs.mjs'
+
+const PASS_SCHEMA = 'aimlock.mutate-pass/1.0'
+const MAX_GATE_TTL_SECONDS = 300
+const MISSING_SHA256 = sha256('aimlock.missing-file/1.0')
+
+function passPayload(pass) {
+  return {
+    schemaVersion: pass.schemaVersion,
+    passId: pass.passId,
+    chainId: pass.chainId,
+    authorityKeyId: pass.authorityKeyId,
+    issuedAt: pass.issuedAt,
+    expiresAt: pass.expiresAt,
+    contractDigest: pass.contractDigest,
+    snapshotReceiptDigest: pass.snapshotReceiptDigest,
+    pathDigest: pass.pathDigest,
+    paths: pass.paths,
+    coordinationRequired: pass.coordinationRequired,
+    coordinationLeasePath: pass.coordinationLeasePath,
+    coordinationLeaseId: pass.coordinationLeaseId,
+    coordinationLockId: pass.coordinationLockId,
+    coordinationLeaseDigest: pass.coordinationLeaseDigest,
+    nonce: pass.nonce,
+  }
+}
+
+async function pathExists(path) {
+  try {
+    await lstat(path)
+    return true
+  } catch (error) {
+    if (error instanceof Error && error.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+async function authorityKeys(root) {
+  const directory = await ensureManagedDirectory(root, 'authority')
+  const privatePath = resolve(directory, 'private.pem')
+  const publicPath = resolve(directory, 'public.pem')
+  const privateExists = await pathExists(privatePath)
+  const publicExists = await pathExists(publicPath)
+  if (privateExists !== publicExists) fail('AIMLOCK_AUTHORITY_INVALID', 'authority key pair is incomplete')
+  if (privateExists) {
+    const [privateStatus, publicStatus] = await Promise.all([lstat(privatePath), lstat(publicPath)])
+    if (privateStatus.isSymbolicLink() || publicStatus.isSymbolicLink()
+      || !privateStatus.isFile() || !publicStatus.isFile()) {
+      fail('AIMLOCK_AUTHORITY_INVALID', 'authority keys must be regular files')
+    }
+  }
+  if (!privateExists) {
+    const pair = generateKeyPairSync('ed25519', {
+      privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+      publicKeyEncoding: { type: 'spki', format: 'pem' },
+    })
+    await writeFile(privatePath, pair.privateKey, { flag: 'wx', mode: 0o600 })
+    await writeFile(publicPath, pair.publicKey, { flag: 'wx', mode: 0o600 })
+  }
+  const privateKey = await readFile(privatePath, 'utf8')
+  const publicKey = await readFile(publicPath, 'utf8')
+  return { privateKey, publicKey, keyId: sha256(publicKey) }
+}
+
+async function fileHash(path) {
+  return sha256(await readFile(path))
+}
+
+async function realSnapshotReceipt(root, input) {
+  if (!input.receipt || !Array.isArray(input.receipt.paths) || !Array.isArray(input.nodes)) {
+    fail('AIMLOCK_SNAPSHOT_AUTHORITY_INVALID', 'receipt paths and nodes are required')
+  }
+  const snapshotRoot = safeRelativePath(input.snapshotRoot, 'snapshotRoot')
+  if (!snapshotRoot.startsWith(`${MANAGED_ROOT}/snapshots/`)) {
+    fail('AIMLOCK_SNAPSHOT_ROOT_INVALID', 'snapshotRoot must be inside .aimlock/snapshots')
+  }
+  const nodes = new Map(input.nodes.map((node) => [node.path, node]))
+  const files = []
+  for (const path of input.receipt.paths) {
+    const source = await resolvedProjectPath(root, path, { allowMissing: true })
+    const newNode = nodes.get(path)?.isNewFile === true
+    const snapshotPath = `${snapshotRoot}/${path}`
+    if (!source.exists && newNode && !(await pathExists(resolve(root, snapshotPath)))) {
+      files.push({ path, sourceHash: MISSING_SHA256, snapshotHash: MISSING_SHA256 })
+      continue
+    }
+    const snapshot = await resolvedProjectPath(root, snapshotPath, { allowMissing: true })
+    if (!source.exists || !snapshot.exists || !source.status.isFile() || !snapshot.status.isFile()) {
+      fail('AIMLOCK_SNAPSHOT_AUTHORITY_INVALID', `${path} does not match its snapshot existence`)
+    }
+    files.push({ path, sourceHash: await fileHash(source.target),
+      snapshotHash: await fileHash(snapshot.target) })
+  }
+  const verified = snapshotVerify({ snapshotId: input.receipt.snapshotId,
+    contract: input.contract, nodes: input.nodes, files })
+  if (verified.findings || verified.receipt?.receiptDigest !== input.receipt.receiptDigest) {
+    fail('AIMLOCK_SNAPSHOT_AUTHORITY_INVALID', 'snapshot files do not match the supplied receipt')
+  }
+  return verified.receipt
+}
+
+async function issueMutationPass(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  const chainId = identifier(input.chainId, 'chainId')
+  const receipt = await realSnapshotReceipt(root, input)
+  const gate = mutateGate({ accepted: true, receipt: input.receipt,
+    contract: input.contract, nodes: input.nodes })
+  if (gate.findings || gate.allowed !== true) fail('AIMLOCK_MUTATE_GATE_BLOCKED', 'mutate-gate did not allow this scope')
+  const ttlSeconds = input.ttlSeconds === undefined ? MAX_GATE_TTL_SECONDS : input.ttlSeconds
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > MAX_GATE_TTL_SECONDS) {
+    fail('AIMLOCK_GATE_TTL_INVALID', `ttlSeconds must be 1..${MAX_GATE_TTL_SECONDS}`)
+  }
+  if (typeof input.coordinationRequired !== 'boolean') {
+    fail('AIMLOCK_COORDINATION_POLICY_REQUIRED', 'coordinationRequired must be an explicit boolean')
+  }
+  if (!input.coordinationRequired && input.coordinationLeasePath !== undefined) {
+    fail('AIMLOCK_COORDINATION_POLICY_INVALID', 'a non-coordinated pass cannot carry a coordination lease')
+  }
+  const coordination = input.coordinationRequired
+    ? await verifyCoordinationLease({ repositoryRoot: root, chainId,
+      coordinationLeasePath: input.coordinationLeasePath, targetPaths: receipt.paths })
+    : null
+  const authority = await authorityKeys(root)
+  const issuedAt = new Date()
+  const pass = {
+    schemaVersion: PASS_SCHEMA,
+    passId: `pass-${randomUUID()}`,
+    chainId,
+    authorityKeyId: authority.keyId,
+    issuedAt: issuedAt.toISOString(),
+    expiresAt: new Date(issuedAt.getTime() + ttlSeconds * 1_000).toISOString(),
+    contractDigest: receipt.contractDigest,
+    snapshotReceiptDigest: receipt.receiptDigest,
+    pathDigest: receipt.pathDigest,
+    paths: [...receipt.paths],
+    coordinationRequired: input.coordinationRequired,
+    coordinationLeasePath: coordination ? input.coordinationLeasePath : null,
+    coordinationLeaseId: coordination?.lease.leaseId ?? null,
+    coordinationLockId: coordination?.lock.lockId ?? null,
+    coordinationLeaseDigest: coordination?.leaseDigest ?? null,
+    nonce: randomUUID(),
+  }
+  const signature = sign(null, Buffer.from(JSON.stringify(passPayload(pass))), authority.privateKey)
+    .toString('base64url')
+  const signedPass = { ...pass, signature }
+  const directory = await ensureManagedDirectory(root, 'gates')
+  const passPath = resolve(directory, `${pass.passId}.json`)
+  await writeFile(passPath, `${JSON.stringify(signedPass)}\n`, { flag: 'wx', mode: 0o600 })
+  await appendAudit(root, { event: 'mutate-pass-issued', chainId, passId: pass.passId,
+    expiresAt: pass.expiresAt, pathDigest: pass.pathDigest })
+  return { schemaVersion: LOCAL_SCHEMA, gatePassPath: `${MANAGED_ROOT}/gates/${pass.passId}.json`,
+    passPath, pass: signedPass }
+}
+
+async function verifyMutationPassFile(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  const gatePath = safeRelativePath(input.gatePassPath, 'gatePassPath')
+  if (!gatePath.startsWith(`${MANAGED_ROOT}/gates/`)) {
+    fail('AIMLOCK_GATE_PATH_INVALID', 'gate pass must be inside .aimlock/gates')
+  }
+  await ensureManagedDirectory(root, 'gates')
+  const gateFile = await resolvedProjectPath(root, gatePath)
+  const pass = JSON.parse(await readFile(gateFile.target, 'utf8'))
+  const chainId = identifier(input.chainId, 'chainId')
+  const targetPath = safeRelativePath(input.targetPath, 'targetPath')
+  const authorityDirectory = await ensureManagedDirectory(root, 'authority')
+  const publicPath = resolve(authorityDirectory, 'public.pem')
+  const publicStatus = await lstat(publicPath)
+  if (publicStatus.isSymbolicLink() || !publicStatus.isFile()) {
+    fail('AIMLOCK_AUTHORITY_INVALID', 'authority public key must be a regular file')
+  }
+  const publicKey = await readFile(publicPath, 'utf8')
+  const issuedAt = Date.parse(pass.issuedAt)
+  const expiresAt = Date.parse(pass.expiresAt)
+  const signatureValid = typeof pass.signature === 'string'
+    && verify(null, Buffer.from(JSON.stringify(passPayload(pass))), publicKey,
+      Buffer.from(pass.signature, 'base64url'))
+  if (pass.schemaVersion !== PASS_SCHEMA || pass.chainId !== chainId
+    || pass.authorityKeyId !== sha256(publicKey) || basename(gatePath) !== `${pass.passId}.json`
+    || !Array.isArray(pass.paths) || !pass.paths.includes(targetPath) || !signatureValid
+    || pass.pathDigest !== sha256(JSON.stringify(pass.paths))
+    || !Number.isFinite(issuedAt) || !Number.isFinite(expiresAt)
+    || issuedAt > Date.now() || expiresAt <= Date.now()) {
+    fail('AIMLOCK_GATE_PASS_INVALID', 'gate pass is forged, expired, or outside its bound scope')
+  }
+  let coordination = null
+  if (pass.coordinationRequired === true) {
+    coordination = await verifyCoordinationLease({ repositoryRoot: root, chainId,
+      coordinationLeasePath: pass.coordinationLeasePath, targetPaths: [targetPath] })
+    if (coordination.lease.leaseId !== pass.coordinationLeaseId
+      || coordination.lock.lockId !== pass.coordinationLockId
+      || coordination.leaseDigest !== pass.coordinationLeaseDigest) {
+      fail('AIMLOCK_COORDINATION_LEASE_INVALID', 'coordination lease does not match the gate pass')
+    }
+  } else if (pass.coordinationRequired !== false || pass.coordinationLeasePath !== null
+    || pass.coordinationLeaseId !== null || pass.coordinationLockId !== null
+    || pass.coordinationLeaseDigest !== null) {
+    fail('AIMLOCK_GATE_PASS_INVALID', 'gate pass has an invalid coordination policy')
+  }
+  return { schemaVersion: LOCAL_SCHEMA, verified: true, pass, targetPath, coordination }
+}
+
+function whitelistedPath(path) {
+  return path.startsWith(`${MANAGED_ROOT}/logs/`) || path.startsWith(`${MANAGED_ROOT}/tmp/`)
+}
+
+async function guardedWriteFile(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  const targetPath = safeRelativePath(input.targetPath, 'targetPath')
+  let passId = null
+  try {
+    if (whitelistedPath(targetPath)) {
+      const bucket = targetPath.split('/')[1]
+      await ensureManagedDirectory(root, bucket)
+    }
+    let verified = null
+    if (!whitelistedPath(targetPath)) {
+      if (!input.gatePassPath) fail('AIMLOCK_GATE_PASS_REQUIRED', 'a gate pass is required')
+      verified = await verifyMutationPassFile({ ...input, targetPath })
+      passId = verified.pass.passId
+    }
+    const performWrite = async () => {
+      const target = await resolvedProjectPath(root, targetPath, { allowMissing: true })
+      await mkdir(dirname(target.target), { recursive: true })
+      const temporary = resolve(dirname(target.target), `.${basename(target.target)}.${randomUUID()}.tmp`)
+      await writeFile(temporary, input.content, {
+        flag: 'wx', mode: target.exists ? target.status.mode & 0o777 : 0o600,
+      })
+      await rename(temporary, target.target)
+    }
+    if (verified?.pass.coordinationRequired === true) {
+      await withCoordinationLease({ repositoryRoot: root, chainId: input.chainId,
+        coordinationLeasePath: verified.pass.coordinationLeasePath, targetPaths: [targetPath] },
+      async (coordination) => {
+        if (coordination.leaseDigest !== verified.pass.coordinationLeaseDigest) {
+          fail('AIMLOCK_COORDINATION_LEASE_INVALID', 'coordination lease changed after pass verification')
+        }
+        await performWrite()
+      })
+    } else {
+      await performWrite()
+    }
+    await appendAudit(root, { event: 'guarded-write-allowed', chainId: input.chainId ?? null,
+      targetPath, passId, whitelisted: whitelistedPath(targetPath) })
+    return { schemaVersion: LOCAL_SCHEMA, written: true, targetPath, passId }
+  } catch (error) {
+    await appendAudit(root, { event: 'guarded-write-denied', chainId: input.chainId ?? null,
+      targetPath, passId, reason: error instanceof Error ? error.message : String(error) })
+    throw error
+  }
+}
+
+export {
+  PASS_SCHEMA,
+  guardedWriteFile,
+  issueMutationPass,
+  passPayload,
+  verifyMutationPassFile,
+}