aura-basetools 0.14.0 → 0.16.0

package/README.md

@@ -1,4 +1,4 @@
-# aura-basetools 0.14.0
+# aura-basetools 0.16.0
 
 Byte-exact file tools for coding agents: read by intent, edit by address, and write whole files without corrupting bytes. One engine shared by a standalone CLI and an MCP server.
 
@@ -21,7 +21,7 @@ The engine is intentionally not a general file manager: it reads and edits UTF-8
 ### Install
 
 ```bash
-npm i -g aura-basetools@0.14.0
+npm i -g aura-basetools@0.16.0
 aura --version
 ```
 
@@ -90,6 +90,8 @@ Compared with the DSH built-in `dsh-tool-fs` tools, the differences are delibera
 - **Read by intent, not whole file.** `map` / `digest` / `lines` / `search` return the structural slice you ask for; the customer comparison measured about 1/24 of the context for the same file.
 - **Edits refuse stale bases.** A region-level gate rejects an edit when the addressed region changed after the read that authorized it, and points at the lines to re-read; `expect` makes the intended text explicit.
 - **Writes are verified, not assumed.** Every write goes through a temp file, flush, rename, and a byte-for-byte read-back; multi-target edits plan first and write nothing if any target fails.
+- **Changes can prove themselves.** `edit` / `write` accept an explicit `verify` command; a non-zero exit or timeout rolls the transaction back and returns the command output plus the rollback state. No auto-discovery of repo scripts.
+- **Changes can span calls.** `tx begin` opens a transaction; `edit` / `write` with `--tx <id>` append to it; `tx commit` checks files were not changed externally (`TX_STALE`) and can run `verify`; `tx rollback` restores all of them.
 - **Addressing is structural.** `target` / `lines` / `old` / `expect` / handles replace "copy the literal text exactly"; failure receipts include ready-to-use retry addresses.
 - **The core is DSH-free.** `aura-basetools` has no runtime dependencies and no DSH imports; the DSH adapter is a separate optional package.
 
@@ -134,7 +136,7 @@ MIT.
 ### 安装
 
 ```bash
-npm i -g aura-basetools@0.14.0
+npm i -g aura-basetools@0.16.0
 aura --version
 ```
 
@@ -203,6 +205,8 @@ npx -y --package aura-basetools aura basetools mcp
 - **按意图读，不读整份。** `map` / `digest` / `lines` / `search` 只返回你要的结构切片；客户版对照实测同一文件上下文约 1/24。
 - **依据过期就拒绝。** 区域级陈旧闸门在“授权读取之后该区域被改过”时拒绝，并指出重读哪几行；`expect` 让目标原文显式化。
 - **写完要验，不靠相信。** 每次写盘走临时文件、flush、rename，再做逐字节回读；多目标先全量规划，任一失败则一个字节都不写。
+- **变更可以自证。** `edit` / `write` 接受显式 `verify` 命令；非零退出或超时会把整个事务回滚，回执带命令输出与回滚状态。不自动发现仓库脚本。
+- **变更可以跨调用。** `tx begin` 开事务；`edit` / `write --tx <id>` 追加；`tx commit` 先检查文件没被外部改过（`TX_STALE`），可带 `verify`；`tx rollback` 恢复全部。
 - **寻址是结构化的。** `target` / `lines` / `old` / `expect` / 句柄替代“把原文一字不差抄对”；失败回执带可直接用的重试地址。
 - **核心不依赖 DSH。** `aura-basetools` 零运行时依赖、无 DSH import；DSH 适配器是独立可选包。
 

package/bin/aura-mcp.mjs

@@ -200,6 +200,10 @@ const TOOLS = [
           type: 'boolean',
           description: '严格新鲜度：要求这一版文件在本会话里被读过（或由本工具写过）；否则 PATCH_UNOBSERVED。create 不受影响；dry_run 同样执行这条判决。',
         },
+        verify: {
+          type: 'string',
+          description: '写后验证命令（显式给出才执行；在 workspace 根下、受超时/输出上限约束）。非零退出 ⇒ 自动回滚并返回 PATCH_VERIFY_FAILED。不自动发现/执行仓库脚本。',
+        },
         create: { type: 'string', description: '文件不存在时用它创建（整份内容）' },
         targets: TARGETS_SCHEMA,
       },
@@ -237,6 +241,10 @@ const TOOLS = [
           enum: ['auto', 'preserve', 'lf', 'crlf'],
           description: '覆写时的换行风格：auto（默认）适配文件已有风格；preserve 按 content 原样写；lf/crlf 强制。新建文件始终按 content 原样写（非 auto 会被拒绝）。',
         },
+        verify: {
+          type: 'string',
+          description: '写后验证命令（显式给出才执行；非零退出 ⇒ 自动回滚并返回 PATCH_VERIFY_FAILED）。',
+        },
       },
       required: ['file_path', 'content'],
     },
@@ -324,6 +332,7 @@ async function editTargetsCall(provider, args) {
     targets,
     dryRun: args.dry_run === true,
     ...(args.require_observation === true ? { requireObservation: true } : {}),
+    ...(typeof args.verify === 'string' ? { verify: args.verify } : {}),
   })
 }
 
@@ -408,6 +417,7 @@ async function callTool(provider, name, args = {}) {
       dryRun: args.dry_run === true,
       create: creating ? args.create : undefined,
       ...(args.require_observation === true ? { requireObservation: true } : {}),
+      ...(typeof args.verify === 'string' ? { verify: args.verify } : {}),
     })
   }
   if (name === 'aura_basetools_write') {
@@ -418,6 +428,7 @@ async function callTool(provider, name, args = {}) {
       noOverwrite: args.no_overwrite === true,
       allowUnobserved: args.allow_unobserved === true,
       ...(typeof args.eol === 'string' ? { eol: args.eol } : {}),
+      ...(typeof args.verify === 'string' ? { verify: args.verify } : {}),
     })
   }
   return { ok: false, error: `unknown tool ${JSON.stringify(name)}`, code: 'UNKNOWN_TOOL' }

package/bin/aura.mjs

@@ -3,9 +3,10 @@
  * aura CLI（薄壳）：参数解析 → `lib/ops.mjs` → 一行 JSON。
  *
  *   aura basetools read  --file F [--mode …] [--around X] [--lines a,b] [--search S] [--since V] [--max-chars N]
- *   aura basetools edit  --file F (--hunks '<json>' | --hunks-file P) [--dry-run] [--create <文本|@文件>]
+ *   aura basetools edit  --file F (--hunks '<json>' | --hunks-file P) [--dry-run] [--verify "命令"] [--create <文本|@文件>]
  *   aura basetools read  --targets '[...]|@spec.json'                    一次读多个目标（与 --file 互斥）
  *   aura basetools edit  --targets '[...]|@spec.json'                    一次改多个文件（与 --file 互斥；任一规划失败 ⇒ 零写入）
+ *   aura basetools tx begin | commit --id <id> [--verify "命令"] | rollback --id <id> | status --id <id>
  *   aura basetools mcp
  *   aura --help | --version
  *
@@ -25,6 +26,10 @@ import {
   // 多目标（fs-contract-v2）的引擎绑定：与单目标同一处（`lib/ops.mjs`），bin 里不另找引擎。
   readManyWith,
   editManyEnvelope,
+  beginTransactionEnvelope,
+  commitTransactionEnvelope,
+  rollbackTransactionEnvelope,
+  statusTransactionEnvelope,
   capabilitiesEnvelope,
   writeEnvelope,
   assertReadTargets,
@@ -86,13 +91,14 @@ const COMMAND_FLAGS = {
     bool: ['pretty'],
   },
   edit: {
-    value: ['cwd', 'file', 'targets', 'hunks', 'hunks-file', 'create', 'target', 'lines', 'start-line', 'end-line', 'line-cue', 'anchor', 'old', 'context', 'handle', 'line', 'position', 'replace', 'expect', 'near', 'eol'],
+    value: ['cwd', 'file', 'targets', 'hunks', 'hunks-file', 'create', 'target', 'lines', 'start-line', 'end-line', 'line-cue', 'anchor', 'old', 'context', 'handle', 'line', 'position', 'replace', 'expect', 'near', 'eol', 'verify', 'tx'],
     bool: ['pretty', 'dry-run', 'plan', 'replace-all', 'require-observation'],
   },
   write: {
-    value: ['cwd', 'file', 'content', 'eol'],
+    value: ['cwd', 'file', 'content', 'eol', 'verify', 'tx'],
     bool: ['pretty', 'dry-run', 'plan', 'no-overwrite', 'allow-unobserved'],
   },
+  tx: { value: ['cwd', 'id', 'verify'], bool: ['pretty', 'json'] },
   doctor: { value: ['cwd'], bool: ['pretty', 'json'] },
   capabilities: { value: ['cwd'], bool: ['pretty'] },
   mcp: { value: ['cwd'], bool: ['pretty'] },
@@ -109,7 +115,9 @@ function validateCommandFlags(command, tokens) {
   if (spec === undefined) return undefined
   const valueFlags = new Set(spec.value)
   const boolFlags = new Set(spec.bool)
-  for (let i = 0; i < tokens.length; i += 1) {
+  // `tx` 的第一个裸位置参数是子命令（begin/commit/rollback/status）；其余命令不允许位置参数。
+  const start = command === 'tx' && tokens[0] !== undefined && !tokens[0].startsWith('--') ? 1 : 0
+  for (let i = start; i < tokens.length; i += 1) {
     const token = tokens[i]
     if (typeof token !== 'string' || !token.startsWith('--')) {
       return `unexpected argument ${JSON.stringify(token)} — this command takes flags only`
@@ -166,9 +174,9 @@ const USAGE = [
   // `--file` 指向**目录**时直接给一张仓库地图（模块/目录/依赖方向），不需要额外旗标。
   '             （--file 传目录 ⇒ 仓库地图：模块清单 + 目录骨架 + 被依赖最多的模块 + 入口点）',
   '  aura basetools read  --targets <json|@文件>                               # 一次读多个目标（≤32 项；与 --file 互斥）',
-  '  aura basetools edit  --targets <json|@文件> [--dry-run|--plan]          # 一次改多个文件（先全量规划，任一失败则零写入）',
+  '  aura basetools edit  --targets <json|@文件> [--dry-run|--plan] [--verify "命令"]  # 一次改多个文件（先全量规划，任一失败则零写入）',
   "  aura basetools edit  --file <路径> --create <内容|@文件>                     # 建文件（不必再给 --hunks）",
-  "  aura basetools edit  --file <路径> (--hunks '<json>' | --hunks-file <路径>) [--dry-run|--plan] [--eol auto|preserve|lf|crlf] [--require-observation]",
+  "  aura basetools edit  --file <路径> (--hunks '<json>' | --hunks-file <路径>) [--dry-run|--plan] [--verify \"命令\"] [--eol auto|preserve|lf|crlf] [--require-observation]",
   '   aura basetools edit  --file <路径> --lines <a,b> --replace <文本> [--expect <文本>] [--near <n>]',
   '   aura basetools edit  --file <路径> --old <原文> --replace <文本> --replace-all        # 改全部非重叠出现',
           "              （只改一处时不必包成 JSON：--target / --lines / --start-line+--end-line / --line-cue / --anchor 任选其一）",
@@ -177,8 +185,12 @@ const USAGE = [
   '   aura basetools edit  --file <路径> --handle <h…> --line <段内行号> --replace <文本>            # 只换区间内第 k 行（1-based，从区间首行数起）',
   '   aura basetools edit  --file <路径> --handle <h…> --position before|after --replace <文本>  # 在区间边界插入，区间本身不动',
   "              （--line / --position 是从属键：只有与 --handle 同时给才成立，单独给不构成一次编辑）",
+  '  aura basetools tx begin               开一个跨调用事务（后续 edit/write 用 --tx <id> 加入）',
+  '  aura basetools tx commit --id <id> [--verify "命令"]  提交；verify 失败/文件被外部改过 ⇒ 拒绝并回滚',
+  '  aura basetools tx rollback --id <id>  回滚整个事务（按 afterVersion 校验）',
+  '  aura basetools tx status --id <id>    只读状态',
   '  aura basetools mcp                    启动 MCP stdio 服务',
-  '  aura basetools write --file <路径> --content <文本|@文件> [--no-overwrite] [--dry-run|--plan] [--allow-unobserved] [--eol auto|preserve|lf|crlf]',
+  '  aura basetools write --file <路径> --content <文本|@文件> [--no-overwrite] [--dry-run|--plan] [--verify "命令"] [--allow-unobserved] [--eol auto|preserve|lf|crlf]',
   '             （覆写默认要求先读过这一版；--allow-unobserved 才允许盲写）',
   '  aura basetools doctor [--json]        自检：Node/版本/MCP 握手/缓存与锁目录可写',
   '  aura basetools capabilities [--pretty] 能力清单：读模式/地址档/语言/限制（JSON）',
@@ -305,7 +317,7 @@ if (command === '--version' || command === '-v') emit({ ok: true, version: VERSI
  * 旧顶层动词只给**迁移提示**，不再作为别名执行——保留别名等于保留未来的撞名。
  * 只提示、不执行：`aura basetools read` 不会偷偷改文件。
  */
-const MOVED_COMMANDS = new Set(['read', 'outline', 'edit', 'write', 'mcp', 'doctor', 'capabilities'])
+const MOVED_COMMANDS = new Set(['read', 'outline', 'edit', 'write', 'tx', 'mcp', 'doctor', 'capabilities'])
 if (!namespaced && MOVED_COMMANDS.has(command)) {
   emit(
     {
@@ -329,6 +341,29 @@ if (command === 'mcp') {
 
 const provider = openProvider(typeof flag('cwd') === 'string' ? flag('cwd') : process.cwd())
 
+if (command === 'tx') {
+  const action = argv[1]
+  const id = typeof flag('id') === 'string' ? flag('id') : undefined
+  if (action === 'begin') {
+    const env = beginTransactionEnvelope(provider)
+    emit(env, env.ok ? 0 : 2)
+  }
+  if (action === 'commit') {
+    const verify = typeof flag('verify') === 'string' ? flag('verify') : undefined
+    const env = await commitTransactionEnvelope(provider, { id, verify })
+    emit(env, env.ok ? 0 : 2)
+  }
+  if (action === 'rollback') {
+    const env = await rollbackTransactionEnvelope(provider, { id })
+    emit(env, env.ok ? 0 : 2)
+  }
+  if (action === 'status') {
+    const env = statusTransactionEnvelope(provider, { id })
+    emit(env, env.ok ? 0 : 2)
+  }
+  emit({ ok: false, error: 'tx 需要 begin | commit | rollback | status（commit/rollback/status 还要 --id）', code: 'USAGE' }, 1)
+}
+
 if (command === 'capabilities') {
   const env = { ok: true, version: VERSION, ...capabilitiesEnvelope() }
   process.stdout.write(`${JSON.stringify(env, null, has('pretty') ? 2 : 0)}\n`)
@@ -352,6 +387,8 @@ if (command === 'write') {
     noOverwrite: has('no-overwrite'),
     allowUnobserved: has('allow-unobserved'),
     ...(typeof eol === 'string' ? { eol } : {}),
+    ...(typeof flag('verify') === 'string' ? { verify: flag('verify') } : {}),
+    ...(typeof flag('tx') === 'string' ? { transaction: flag('tx') } : {}),
   })
   emit(env, env.ok ? 0 : 2)
 }
@@ -473,6 +510,8 @@ if (command === 'edit') {
       targets: spec.targets,
       dryRun: has('dry-run') || has('plan') || spec.dryRun,
       ...(has('require-observation') ? { requireObservation: true } : {}),
+      ...(typeof flag('verify') === 'string' ? { verify: flag('verify') } : {}),
+      ...(typeof flag('tx') === 'string' ? { transaction: flag('tx') } : {}),
     })
     emit(env, env.ok ? 0 : 2)
   }
@@ -585,6 +624,8 @@ if (command === 'edit') {
     dryRun: has('dry-run') || has('plan'),
     create,
     ...(has('require-observation') ? { requireObservation: true } : {}),
+    ...(typeof flag('verify') === 'string' ? { verify: flag('verify') } : {}),
+    ...(typeof flag('tx') === 'string' ? { transaction: flag('tx') } : {}),
   })
   emit(env, env.ok ? 0 : 2)
 }

package/lib/ops.mjs

@@ -10,10 +10,11 @@
  * （`flatHunk` 也从这里出去），于是「引擎在哪」这个问题在整棵树里只有一个答案。
  */
 import fs from 'node:fs'
+import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { createNodeFsProvider, DEFAULT_MAX_TEXT_BYTES } from './fs-provider.mjs'
 import { withWorkspaceLock } from './workspace-lock.mjs'
-import { createTransaction } from './transaction-store.mjs'
+import { createTransaction, getTransactionMeta, openTransaction } from './transaction-store.mjs'
 import { createDiskStore } from './observation-store.mjs'
 
 /**
@@ -91,7 +92,7 @@ export function capabilitiesEnvelope() {
       {
         name: 'aura_basetools_edit',
         addressKinds: [...new Set([...engineArgs.FLAT_ADDRESS_KEYS, 'old', 'context', 'position'])],
-        options: ['replace_all', 'require_observation'],
+        options: ['replace_all', 'require_observation', 'verify'],
         writeSafety: {
           cli: ['workspace-lock', 'stale-region-gate', 'byte-verify'],
           mcp: ['workspace-lock', 'stale-region-gate', 'byte-verify'],
@@ -101,7 +102,7 @@ export function capabilitiesEnvelope() {
       {
         name: 'aura_basetools_write',
         operations: ['create', 'overwrite'],
-        options: ['eol'],
+        options: ['eol', 'verify'],
         writeSafety: {
           cli: ['workspace-lock', 'stale-region-gate', 'observation-gate', 'byte-verify'],
           mcp: ['workspace-lock', 'stale-region-gate', 'observation-gate', 'byte-verify'],
@@ -110,7 +111,7 @@ export function capabilitiesEnvelope() {
         },
       },
     ],
-    commands: ['basetools read', 'basetools edit', 'basetools write', 'basetools mcp', 'basetools doctor', 'basetools capabilities', '--version', '--help'],
+    commands: ['basetools read', 'basetools edit', 'basetools write', 'basetools tx', 'basetools mcp', 'basetools doctor', 'basetools capabilities', '--version', '--help'],
     langs,
     langsCount: langs.length,
     limits: {
@@ -479,6 +480,105 @@ function transactionError(error) {
   }
 }
 
+const VERIFY_OUTPUT_LIMIT = 4000
+const tailText = (value) => {
+  const text = String(value ?? '')
+  return text.length <= VERIFY_OUTPUT_LIMIT ? text : `…${text.slice(-VERIFY_OUTPUT_LIMIT)}`
+}
+
+/**
+ * 写后验证：**只在调用方显式给出命令时**执行。
+ *
+ * 不是自动发现仓库脚本，也不绕过沙箱/权限；命令在 workspace 根下跑，有超时与输出上限。
+ * 失败由外层事务回滚，调用方拿到的是可判定的 `PATCH_VERIFY_FAILED`，不是“写完再说”。
+ */
+function runVerification(command, cwd) {
+  const timeout = Math.min(600000, Math.max(1000, Number(process.env.AURA_VERIFY_TIMEOUT_MS) || 120000))
+  const started = Date.now()
+  const res = spawnSync(command, {
+    cwd,
+    shell: true,
+    encoding: 'utf8',
+    timeout,
+    maxBuffer: 8 * 1024 * 1024,
+    env: process.env,
+    windowsHide: true,
+  })
+  const timedOut = res.error?.code === 'ETIMEDOUT'
+  return {
+    command,
+    cwd,
+    ok: res.status === 0 && res.error === undefined,
+    exitCode: res.status,
+    signal: res.signal ?? null,
+    timedOut,
+    durationMs: Date.now() - started,
+    stdout: tailText(res.stdout),
+    stderr: tailText(res.stderr),
+    ...(res.error === undefined ? {} : { error: String(res.error.message ?? res.error) }),
+  }
+}
+
+async function editInTransaction(provider, request) {
+  const verifyCommand = typeof request.verify === 'string' && request.verify.trim().length > 0 ? request.verify.trim() : null
+  try {
+    return await withWorkspaceLock(provider.root, async () => {
+      const tx = openTransaction(provider.root, request.transaction)
+      const env = await editEnvelopeInner(tx.proxy(provider), request)
+      if (!env.ok) return env
+      let verification
+      if (verifyCommand !== null) {
+        verification = runVerification(verifyCommand, provider.root)
+        if (!verification.ok) {
+          const rollback = await tx.rollback(provider)
+          return {
+            ok: false,
+            code: 'PATCH_VERIFY_FAILED',
+            error: `edit verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+            verification,
+            rollback,
+            transaction: tx.summary(),
+          }
+        }
+      }
+      return { ...env, transaction: tx.summary(), ...(verification === undefined ? {} : { verification }) }
+    })
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
+async function editManyInTransaction(provider, request) {
+  const verifyCommand = typeof request.verify === 'string' && request.verify.trim().length > 0 ? request.verify.trim() : null
+  try {
+    return await withWorkspaceLock(provider.root, async () => {
+      const tx = openTransaction(provider.root, request.transaction)
+      const batch = await editManyEnvelopeInner(tx.proxy(provider), request)
+      if (!batch.ok) return batch
+      let verification
+      if (verifyCommand !== null) {
+        verification = runVerification(verifyCommand, provider.root)
+        if (!verification.ok) {
+          const rollback = await tx.rollback(provider)
+          const finalBatch = writePath.rebuildAfterRollback(batch, rollback)
+          return {
+            ...finalBatch,
+            ok: false,
+            code: 'PATCH_VERIFY_FAILED',
+            error: `edit verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+            verification,
+            rollback,
+            transaction: tx.summary(),
+          }
+        }
+      }
+      return { ...batch, transaction: tx.summary(), ...(verification === undefined ? {} : { verification }) }
+    })
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
 /**
  * 写事务外壳：workspace 锁 + 事务日志 + 失败回滚。
  *
@@ -492,11 +592,35 @@ export async function editEnvelope(provider, request) {
    * 预演不建事务、不写盘，也不需要工作区锁；0.14.0 起事务日志只用于失败回滚。
    */
   if (request.dryRun === true) return editEnvelopeInner(provider, request)
+  if (typeof request.transaction === 'string' && request.transaction.length > 0) return editInTransaction(provider, request)
+  const verifyCommand = typeof request.verify === 'string' && request.verify.trim().length > 0 ? request.verify.trim() : null
   try {
     return await withWorkspaceLock(provider.root, async () => {
       const tx = createTransaction(provider.root, 'aura_basetools_edit')
       const env = await editEnvelopeInner(tx.proxy(provider), request)
       if (env.ok) {
+        if (verifyCommand !== null) {
+          const verification = runVerification(verifyCommand, provider.root)
+          if (!verification.ok) {
+            const rollback = await tx.rollback(provider)
+            return {
+              ok: false,
+              error: `edit verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+              code: 'PATCH_VERIFY_FAILED',
+              verification,
+              rollback,
+            }
+          }
+          try {
+            tx.commit()
+          } catch (error) {
+            const rollback = await tx.rollback(provider)
+            error.transaction = tx.summary()
+            error.rollback = rollback
+            throw error
+          }
+          return { ...env, verification }
+        }
         try {
           tx.commit()
         } catch (error) {
@@ -520,12 +644,38 @@ export async function editManyEnvelope(provider, request) {
   if (provider.root === undefined) return editManyEnvelopeInner(provider, request)
   // 与单目标同一条：预演不建事务、不写盘，不能顶掉真正的最近 committed 事务。
   if (request.dryRun === true) return editManyEnvelopeInner(provider, request)
+  if (typeof request.transaction === 'string' && request.transaction.length > 0) return editManyInTransaction(provider, request)
+  const verifyCommand = typeof request.verify === 'string' && request.verify.trim().length > 0 ? request.verify.trim() : null
   try {
     return await withWorkspaceLock(provider.root, async () => {
       const tx = createTransaction(provider.root, 'aura_basetools_edit')
       try {
         const batch = await editManyEnvelopeInner(tx.proxy(provider), request)
         if (batch.ok) {
+          if (verifyCommand !== null) {
+            const verification = runVerification(verifyCommand, provider.root)
+            if (!verification.ok) {
+              const rollback = await tx.rollback(provider)
+              const finalBatch = writePath.rebuildAfterRollback(batch, rollback)
+              return {
+                ...finalBatch,
+                ok: false,
+                code: 'PATCH_VERIFY_FAILED',
+                error: `edit verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+                verification,
+                rollback,
+              }
+            }
+            try {
+              tx.commit()
+            } catch (error) {
+              const rollback = await tx.rollback(provider)
+              error.transaction = tx.summary()
+              error.rollback = rollback
+              throw error
+            }
+            return { ...batch, verification }
+          }
           try {
             tx.commit()
           } catch (error) {
@@ -554,6 +704,85 @@ export async function editManyEnvelope(provider, request) {
   }
 }
 
+/** 开一个跨调用事务；后续 `edit --tx <id>` 写在同一份日志里。 */
+export function beginTransactionEnvelope(provider) {
+  if (provider.root === undefined) return { ok: false, error: 'transactions need a workspace root', code: 'TX_NO_ROOT' }
+  try {
+    const tx = createTransaction(provider.root, 'aura_basetools_tx')
+    return { ok: true, transaction: tx.summary() }
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
+/** 提交跨调用事务：先做 afterVersion 乐观校验，再跑可选 verify；失败自动 rollback。 */
+export async function commitTransactionEnvelope(provider, { id, verify } = {}) {
+  if (provider.root === undefined) return { ok: false, error: 'transactions need a workspace root', code: 'TX_NO_ROOT' }
+  if (typeof id !== 'string' || id.length === 0) return { ok: false, error: 'commit needs a transaction id', code: 'TX_BAD_ID' }
+  const verifyCommand = typeof verify === 'string' && verify.trim().length > 0 ? verify.trim() : null
+  try {
+    return await withWorkspaceLock(provider.root, async () => {
+      const tx = openTransaction(provider.root, id)
+      const conflicts = tx.assertFresh(provider)
+      if (conflicts.length > 0) {
+        return {
+          ok: false,
+          code: 'TX_STALE',
+          error: `transaction ${id} has ${conflicts.length} file(s) changed since the transaction wrote them`,
+          conflicts,
+          transaction: tx.summary(),
+        }
+      }
+      let verification
+      if (verifyCommand !== null) {
+        verification = runVerification(verifyCommand, provider.root)
+        if (!verification.ok) {
+          const rollback = await tx.rollback(provider)
+          return {
+            ok: false,
+            code: 'PATCH_VERIFY_FAILED',
+            error: `transaction verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+            verification,
+            rollback,
+            transaction: tx.summary(),
+          }
+        }
+      }
+      tx.commit()
+      return { ok: true, transaction: tx.summary(), ...(verification === undefined ? {} : { verification }) }
+    })
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
+/** 回滚跨调用事务：与内部失败回滚同一套 afterVersion 校验。 */
+export async function rollbackTransactionEnvelope(provider, { id } = {}) {
+  if (provider.root === undefined) return { ok: false, error: 'transactions need a workspace root', code: 'TX_NO_ROOT' }
+  if (typeof id !== 'string' || id.length === 0) return { ok: false, error: 'rollback needs a transaction id', code: 'TX_BAD_ID' }
+  try {
+    return await withWorkspaceLock(provider.root, async () => {
+      const tx = openTransaction(provider.root, id)
+      const rollback = await tx.rollback(provider)
+      return { ok: rollback.status === 'rolled_back', rollback, transaction: tx.summary() }
+    })
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
+/** 只读事务状态。 */
+export function statusTransactionEnvelope(provider, { id } = {}) {
+  if (provider.root === undefined) return { ok: false, error: 'transactions need a workspace root', code: 'TX_NO_ROOT' }
+  if (typeof id !== 'string' || id.length === 0) return { ok: false, error: 'status needs a transaction id', code: 'TX_BAD_ID' }
+  try {
+    const meta = getTransactionMeta(provider.root, id)
+    return { ok: true, transaction: { id: meta.id, status: meta.status, files: meta.files.length, written: meta.files.filter((f) => f.written).length, dir: meta.dir } }
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
 /** 整文件写的紧凑回执：不把整份 old/new 文本塞进 applied（那是 edit 的形状，不是 write 的）。 */
 function compactWriteReceipt(env, content) {
   if (env === null || typeof env !== 'object' || env.ok !== true) return env
@@ -567,6 +796,7 @@ function compactWriteReceipt(env, content) {
   const bytes = result.write_verify?.bytes ?? (dryRun && result.operation === 'create' ? Buffer.byteLength(content, 'utf8') : undefined)
   return {
     ok: true,
+    ...(env.verification === undefined ? {} : { verification: env.verification }),
     result: {
       path: result.path,
       operation: result.operation ?? 'write',
@@ -594,7 +824,7 @@ function compactWriteReceipt(env, content) {
  * `preserve` 按 content 原样写（与内置 Write 的“给什么写什么”对齐），`lf` / `crlf` 强制统一。
  * 新建文件永远按 content 原样写；显式传非 `auto` 的 eol 会被拒绝（不做静默忽略）。
  */
-export async function writeEnvelope(provider, { file, content, dryRun = false, noOverwrite = false, allowUnobserved = false, eol = 'auto' } = {}) {
+export async function writeEnvelope(provider, { file, content, dryRun = false, noOverwrite = false, allowUnobserved = false, eol = 'auto', verify, transaction } = {}) {
   if (typeof file !== 'string' || file.length === 0) {
     return { ok: false, error: 'write needs a file path', code: 'WRITE_BAD_ARGS' }
   }
@@ -621,7 +851,7 @@ export async function writeEnvelope(provider, { file, content, dryRun = false, n
       if (dryRun) {
         return { ok: true, result: { path: displayPath, operation: 'create', bytes: Buffer.byteLength(content, 'utf8'), dryRun: true } }
       }
-      return compactWriteReceipt(await editEnvelope(provider, { file, create: content }), content)
+      return compactWriteReceipt(await editEnvelope(provider, { file, create: content, verify, transaction }), content)
     }
     return compactWriteReceipt(
       await editEnvelope(provider, {
@@ -632,6 +862,8 @@ export async function writeEnvelope(provider, { file, content, dryRun = false, n
         requireObservation: allowUnobserved !== true,
         skipStaleGate: allowUnobserved === true,
         toolName: 'aura_basetools_write',
+        verify,
+        transaction,
       }),
       content,
     )

package/lib/transaction-store.mjs

@@ -117,22 +117,13 @@ function fileSummary(entry) {
  * @param root - 工作区根
  * @param tool - 产生它的工具名（仅记录）
  */
-export function createTransaction(root, tool = 'aura_basetools_edit') {
-  const id = transactionId()
-  const dir = path.join(transactionsRoot(root), id)
-  ensureDir(dir)
-  const meta = {
-    id,
-    tool,
-    root: path.resolve(root),
-    createdAt: new Date().toISOString(),
-    status: 'pending',
-    files: [],
-    dir,
-  }
-  saveMeta(meta)
+function makeTransaction(root, meta, dir) {
   const entries = new Map()
-  let closed = false
+  for (let i = 0; i < meta.files.length; i += 1) {
+    const saved = meta.files[i]
+    entries.set(saved.path, { ...saved, metaIndex: i })
+  }
+  let closed = meta.status !== 'pending'
 
   const entryKey = (provider, target) => normalizeTarget(provider, target)
 
@@ -174,7 +165,7 @@ export function createTransaction(root, tool = 'aura_basetools_edit') {
   }
 
   const tx = {
-    id,
+    id: meta.id,
     dir,
     meta,
     entries,
@@ -196,17 +187,29 @@ export function createTransaction(root, tool = 'aura_basetools_edit') {
       }
       return proxy
     },
+    /** 交叉调用提交前的乐观校验：事务写过的文件必须仍停在 afterVersion。 */
+    assertFresh(provider) {
+      const conflicts = []
+      for (const entry of entries.values()) {
+        if (!entry.written) continue
+        let current
+        try { current = provider.stat(entry.path) } catch { current = undefined }
+        if (entry.afterVersion !== null && current?.version !== entry.afterVersion) {
+          conflicts.push({ path: entry.path, expected: entry.afterVersion, actual: current?.version ?? null })
+        }
+      }
+      return conflicts
+    },
     commit() {
       if (closed) return
       meta.status = 'committed'
       meta.committedAt = new Date().toISOString()
-      // 只有 meta 真正落盘后才 closed；否则调用方还能 rollback 已经写出的文件。
       saveMeta(meta)
       closed = true
       prune(root)
     },
     summary() {
-      return { id, dir, status: meta.status, files: meta.files.length }
+      return { id: meta.id, dir, status: meta.status, files: meta.files.length, written: meta.files.filter((f) => f.written).length }
     },
     async rollback(provider, options = {}) {
       if (closed) return { status: meta.status, restored: 0, conflicts: [] }
@@ -243,6 +246,48 @@ export function createTransaction(root, tool = 'aura_basetools_edit') {
   return tx
 }
 
+/**
+ * 创建一个 pending 事务。此时还没有任何文件被记录；第一次 writeText 前才记原始字节。
+ *
+ * @param root - 工作区根
+ * @param tool - 产生它的工具名（仅记录）
+ */
+export function createTransaction(root, tool = 'aura_basetools_edit') {
+  const id = transactionId()
+  const dir = path.join(transactionsRoot(root), id)
+  ensureDir(dir)
+  const meta = {
+    id,
+    tool,
+    root: path.resolve(root),
+    createdAt: new Date().toISOString(),
+    status: 'pending',
+    files: [],
+    dir,
+  }
+  saveMeta(meta)
+  return makeTransaction(root, meta, dir)
+}
+
+/** 打开一个仍处于 pending 的跨调用事务。 */
+export function openTransaction(root, id) {
+  const dir = path.join(transactionsRoot(root), id)
+  const meta = loadMeta(dir)
+  if (meta.status !== 'pending') {
+    throw Object.assign(new Error(`transaction ${id} is ${meta.status}, not open`), { code: 'TX_NOT_OPEN' })
+  }
+  return makeTransaction(root, meta, dir)
+}
+
+/** 读一个事务的元数据（状态/文件数）；不存在时抛 TX_NOT_FOUND。 */
+export function getTransactionMeta(root, id) {
+  try {
+    return loadMeta(path.join(transactionsRoot(root), id))
+  } catch {
+    throw Object.assign(new Error(`transaction not found: ${id}`), { code: 'TX_NOT_FOUND' })
+  }
+}
+
 function readAllMeta(root) {
   const dir = transactionsRoot(root)
   let names

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aura-basetools",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Byte-exact read, edit and write tools for coding agents. Standalone CLI and MCP server; no DSH required. 面向 coding agent 的逐字节读写工具；独立 CLI / MCP，可选 DSH 适配器。",
   "license": "MIT",
   "type": "module",