@lqc123qwe/car-runtime 1.0.0-rc.1

package/src/load/loader.ts

@@ -0,0 +1,165 @@
+/**
+ * F6 · 插件装配层：manifest 校验 + 免编译加载（缓存击穿热重载）+ Stub 占位 + invalidate
+ *
+ * 口径：
+ *  - 载体：jiti 实装受阻（沙箱 npm），以 Node --experimental-transform-types + 动态 import
+ *    查询串缓存击空承载（POC-2 同口径）；被测不变量与载体无关
+ *  - Stub 占位（Pi 范式，CAR 自研层）：**注册类动作始终可用（收集待注册项）**，
+ *    「依赖宿主绑定的能力查询」在 bindCore 前一调用即抛错——用启动期显式失败换运行期时序正确
+ *  - invalidate：unload/reload 后旧句柄访问显式报错（CAR-INVALIDATED）
+ *  - manifest：name 必填、version 精确 semver（禁区间）；peer 校验挂点预留（O7，M2 启用）
+ */
+import { pathToFileURL } from 'node:url'
+import { readFileSync } from 'node:fs'
+import { checkErasableOnly } from '../ptc/erasable.ts'
+
+/** 简易 semver 区间求解（M2 S5：仅支持 ^x.y.z / x.y.z 两种形态；完整区间求解 M3 扩展） */
+function satisfiesRange(version: string, range: string): boolean {
+  if (range === version) return true
+  const m = /^\^(\d+)\.(\d+)\.(\d+)$/.exec(range)
+  if (!m) return false
+  const [M, mnr, P] = version.split('.').map(Number)
+  // npm caret 语义：左起第一个非零位锁定（^1.2.3→>=1.2.3 <2；^0.2.3→>=0.2.3 <0.3；^0.0.3→==0.0.3）
+  if (M !== Number(m[1])) return false
+  if (M > 0) {
+    if (mnr !== Number(m[2])) return mnr > Number(m[2])
+    return P >= Number(m[3])
+  }
+  if (mnr !== Number(m[2])) return false // ^0.x：minor 锁定
+  return P >= Number(m[3])
+}
+
+/**
+ * F10 · peer 版本约束校验（严格模式默认 + 显式豁免，经中间确认⑥）
+ * 冲突 = 加载期硬报错并输出冲突链；豁免需 manifest.peerPolicyOverride（reason 必填→审计留痕）
+ */
+export interface PeerViolation { peer: string; range: string; installed: string | null; optional: boolean }
+
+export function validatePeers(manifest: Manifest, installed: Map<string, string>): { exempted: boolean; violations: PeerViolation[] } {
+  const violations: PeerViolation[] = []
+  for (const p of manifest.peers ?? []) {
+    const v = installed.get(p.peer)
+    if (v === undefined) {
+      if (!p.optional) violations.push({ peer: p.peer, range: p.range, installed: null, optional: false })
+      continue
+    }
+    if (!satisfiesRange(v, p.range)) violations.push({ peer: p.peer, range: p.range, installed: v, optional: !!p.optional })
+  }
+  const hard = violations.filter(v => !v.optional)
+  if (!hard.length) return { exempted: false, violations }
+  if (manifest.peerPolicyOverride?.relaxed) {
+    // 显式豁免：放宽生效，调用方负责将 manifest.peerPolicy='exempt' 写入审计（留痕）
+    return { exempted: true, violations }
+  }
+  // 严格模式默认：冲突链硬报错（文件/依赖路径/区间/实际版本）
+  const chainStr = hard.map(v => `${v.peer}@${v.range} required but ${v.installed ?? '<missing>'} installed`).join('; ')
+  throw new Error(`CAR-E-PEER: peer dependency conflict for "${manifest.name}" — ${chainStr}（放宽需 manifest.peerPolicyOverride 显式声明 + reason，审计留痕）`)
+}
+
+export interface Manifest {
+  name: string
+  version: string
+  peers?: Array<{ peer: string; range: string; optional?: boolean }>
+  peerPolicyOverride?: { relaxed: true; reason: string }
+}
+
+const SEMVER_EXACT = /^\d+\.\d+\.\d+$/
+const chain = (file: string, detail: string) => `CAR-E-MANIFEST: ${detail} (conflict chain: ${file})`
+
+export function parseManifest(raw: unknown, file = '<manifest>'): Manifest {
+  const m = raw as Manifest
+  if (!m || typeof m !== 'object') throw new Error(chain(file, 'manifest must be an object'))
+  if (!m.name || typeof m.name !== 'string') throw new Error(chain(file, 'field "name" is required and must be a string'))
+  if (!m.version || !SEMVER_EXACT.test(m.version)) {
+    throw new Error(chain(file, `field "version" must be exact semver (x.y.z), got "${m.version}"（版本区间仅用于 peer 校验）`))
+  }
+  if (m.peerPolicyOverride && !m.peerPolicyOverride.reason) {
+    throw new Error(chain(file, 'field "peerPolicyOverride.reason" is required when豁免声明（审计留痕）'))
+  }
+  return m
+}
+
+export interface ToolReg { name: string; run: (args: any) => Promise<unknown> }
+export interface CommandReg { name: string; run: (args: string[]) => Promise<void> }
+export interface PluginApi {
+  registerTool(tool: ToolReg): void
+  registerCommand(cmd: CommandReg): void
+  getRegisteredTools(): ToolReg[]
+}
+
+interface HostBinding {
+  registerTool?(tool: ToolReg): void
+  registerCommand?(cmd: CommandReg): void
+  getRegisteredTools(): ToolReg[]
+}
+
+class ApiImpl {
+  #host: HostBinding | undefined
+  #pendingTools: ToolReg[] = []
+  #pendingCommands: CommandReg[] = []
+  registerTool(tool: ToolReg): void {
+    if (this.#host?.registerTool) { this.#host.registerTool(tool); return }
+    this.#pendingTools.push(tool) // 注册类动作始终可用：Stub 期收集，bind 后冲刷
+  }
+  registerCommand(cmd: CommandReg): void {
+    if (this.#host?.registerCommand) { this.#host.registerCommand(cmd); return }
+    this.#pendingCommands.push(cmd)
+  }
+  getRegisteredTools(): ToolReg[] {
+    // 依赖宿主绑定的能力查询：bindCore 前一调用即抛错（Stub 显式失败）
+    if (!this.#host) throw new Error('CAR-STUB: "getRegisteredTools" called before bindCore（启动期显式失败换运行期时序正确）')
+    return this.#host.getRegisteredTools()
+  }
+  bindHost(host: HostBinding): void {
+    this.#host = host
+    for (const t of this.#pendingTools) host.registerTool?.(t)
+    for (const c of this.#pendingCommands) host.registerCommand?.(c)
+    this.#pendingTools = []
+    this.#pendingCommands = []
+  }
+}
+
+export interface LoadedPlugin {
+  manifest: Manifest
+  api: PluginApi
+  bindCore(host: HostBinding): void
+  invalidate(): void
+  isInvalidated(): boolean
+}
+
+/** 装配插件模块（免编译加载 + Stub 占位 + invalidate 语义） */
+export async function mountPlugin(spec: {
+  file: string
+  manifest: unknown
+  /** reload 版本号：每次 +1 变更 import 查询串击穿 ESM 缓存 */
+  reloadEpoch?: number
+}): Promise<LoadedPlugin> {
+  const manifest = parseManifest(spec.manifest, spec.file)
+  const epoch = spec.reloadEpoch ?? 0
+  // erasable-only 双挂点之二：loader 提交链（挂点一在 run_code 入口——单一事实源 checkErasableOnly）
+  const era = checkErasableOnly(readFileSync(spec.file, 'utf-8'))
+  if (!era.ok) throw new Error(`CAR-E-PTC: ${era.violation} (file: ${spec.file})`)
+  const mod = (await import(pathToFileURL(spec.file).href + (epoch ? `?epoch=${epoch}` : ''))) as {
+    default: (api: PluginApi) => void
+  }
+  if (typeof mod.default !== 'function') {
+    throw new Error(chain(spec.file, 'plugin module must default-export a factory (api) => void'))
+  }
+  let alive = true
+  const apiImpl = new ApiImpl()
+  const api: PluginApi = new Proxy(apiImpl as unknown as PluginApi, {
+    get(target, prop: string) {
+      if (!alive) throw new Error(`CAR-INVALIDATED: "${prop}" on stale plugin context（旧上下文已失效，请重新加载）`)
+      const v = (target as any)[prop]
+      return typeof v === 'function' ? v.bind(target) : v
+    },
+  })
+  mod.default(api)
+  return {
+    manifest,
+    api,
+    bindCore(host: HostBinding) { apiImpl.bindHost(host) },
+    invalidate() { alive = false },
+    isInvalidated() { return !alive },
+  }
+}

package/src/load/registry.ts

@@ -0,0 +1,88 @@
+/**
+ * T-3/T-4 · registry 对接（M3-S13 落位 + M4-S17 T-5 终局对齐增补）
+ *
+ * 口径（M3部署设计增补 §3 + M3安全设计增补 T-4 + 决议⑦ + M4安全增补registry对齐 定稿）：
+ *  - **registries 清单即白名单本身**：白名单外默认拒绝 + 审计落盘（不做静默 fallback）；
+ *  - resolution 四级顺序：①显式源绑定（校验级失败**硬失败不换源**——换源重试已拒内容 = 降级攻击面）
+ *    → ②白名单 priority 升序（网络级失败可按 priority 继续——exclude 通道，类型上仅允许 reason='network'）
+ *    → ③公共 npm 兜底（缺省 false——**候选耗尽**或白名单为空时生效，企业内网安全默认）
+ *    → ④全不可用 = 离线拒绝（显式错误，非静默）；
+ *  - **signed 字段语义（T-5 定稿①）**：签名物承载方式（true=源直供 / false=镜像透传），**永不产生免验/降档/直信**——验签义务恒在 verifier 层（ADR-003）；
+ *  - 本模块纯判定（零网络 I/O），CI 可全量测试。
+ */
+import { createHash } from 'node:crypto'
+
+export interface RegistryEntry { url: string; priority: number; /** 签名物承载方式（T-5 定稿①：不参与信任分级，验签义务恒在 verifier） */ signed: boolean }
+
+export interface RegistryConfig {
+  registries: RegistryEntry[]
+  /** 公共 npm 兜底（缺省必须显式声明——企业内网 false 为试点准入判据，T-5 定稿③） */
+  allowNpmFallback: boolean
+  /** 离线模式：全部拒绝（显式错误） */
+  offline: boolean
+}
+
+export interface PackageSpec { name: string; version: string; /** 显式源绑定（manifest registry 字段）——校验级失败硬失败不换源 */ pinnedRegistry?: string }
+
+export type ResolutionSource = 'registry' | 'npm-fallback' | 'rejected'
+
+export interface Resolution {
+  source: ResolutionSource
+  url?: string
+  /** 判定摘要（审计落盘 payload；含拒绝原因/解析路径） */
+  detail: string
+  /** 解析决策指纹（可落审计哈希链） */
+  decisionId: string
+}
+
+/**
+ * 单源失败排除记录（T-5 定稿②）：reason 类型层仅允许 'network'——
+ * 「校验级失败换源」在本签名上不可表达（校验失败由调用方硬拒，不经本层换源）。
+ */
+export type ExcludedSource = { url: string; reason: 'network' }
+
+export function resolvePackage(spec: PackageSpec, config: RegistryConfig, audit?: (detail: Record<string, unknown>) => void, opts: { exclude?: ExcludedSource[] } = {}): Resolution {
+  const finish = (r: Omit<Resolution, 'decisionId'>): Resolution => {
+    const decisionId = 'RD-' + createHash('sha256').update(JSON.stringify({ spec, r })).digest('hex').slice(0, 16)
+    audit?.({ kind: 'registry-resolution', spec: spec.name, ...r, decisionId })
+    return { ...r, decisionId }
+  }
+  // ④ 离线：全拒（最高优先级——离线声明不可被任何源覆盖）
+  if (config.offline) return finish({ source: 'rejected', detail: 'offline mode: all sources rejected（显式拒绝，非静默）' })
+  const excluded = new Set((opts.exclude ?? []).map(e => e.url))
+  // ① 显式源绑定：校验级失败硬失败不换源（pinned 不在白名单）；
+  //   pinned 命中但被 exclude（网络失败）→ 语义同「按 priority 继续」（T-5 定稿②网络路径）
+  if (spec.pinnedRegistry) {
+    const pinned = config.registries.find(r => r.url === spec.pinnedRegistry)
+    if (!pinned) return finish({ source: 'rejected', detail: `pinned registry "${spec.pinnedRegistry}" not in whitelist——显式绑定不在白名单，硬失败不换源（fail-closed）` })
+    if (!excluded.has(pinned.url)) {
+      return finish({ source: 'registry', url: pinned.url, detail: `pinned to ${pinned.url}（priority=${pinned.priority}）` })
+    }
+    // pinned 网络失败：落审计后按 priority 继续剩余白名单（不含 pinned）
+  }
+  // ② 白名单 priority 升序（排除网络失败源）
+  const sorted = [...config.registries].sort((a, b) => a.priority - b.priority).filter(r => !excluded.has(r.url))
+  if (sorted.length) {
+    const first = sorted[0]
+    return finish({ source: 'registry', url: first.url, detail: `whitelist priority order → ${first.url}（candidates=${sorted.length}${excluded.size ? `, excluded=${excluded.size}` : ''}）` })
+  }
+  // ③ 公共 npm 兜底（**候选耗尽**或白名单为空时生效——T-5 定稿②③修正语义）
+  if (config.allowNpmFallback) {
+    const why = config.registries.length ? 'candidates exhausted（网络级失败耗尽）' : 'whitelist empty'
+    return finish({ source: 'npm-fallback', url: 'https://registry.npmjs.org', detail: `${why} → npm fallback（显式开启；兜底命中包强制过 verifier 不降级）` })
+  }
+  return finish({ source: 'rejected', detail: config.registries.length
+    ? 'candidates exhausted and npm fallback disabled——候选耗尽且兜底关闭（fail-closed）'
+    : 'no whitelist entries and npm fallback disabled——白名单为空且兜底关闭（企业内网安全默认）' })
+}
+
+/** 只读预览（T-5 定稿②新增）：返回按优先级的候选链（不含 pinned 语义，供装载面展示与演练） */
+export function resolveCandidateChain(config: RegistryConfig): { chain: string[]; fallback: boolean } {
+  const chain = [...config.registries].sort((a, b) => a.priority - b.priority).map(r => r.url)
+  return { chain, fallback: config.allowNpmFallback }
+}
+
+/** 白名单校验（插件安装面调用：来源不在清单 = 拒绝并审计） */
+export function isWhitelisted(url: string, config: RegistryConfig): boolean {
+  return !config.offline && config.registries.some(r => r.url === url)
+}

package/src/load/verifier.ts

@@ -0,0 +1,67 @@
+/**
+ * S6 验签器（ADR-003 双轨实装）：minisign 离线轨（node:crypto ed25519）+ Sigstore 接口预留
+ *
+ * fail-closed 分级（D-2 裁决）：
+ *  - 校验失败（有签名但不对）= 硬拒绝，不可配置放行
+ *  - 签名缺失 = warn 模式告警放行（manifestHash 兜底）→ enforce 模式硬拒绝
+ *  - Sigstore 轨不可达 = 回退静态轨；双轨皆败按缺失处理
+ */
+import { verify, createPublicKey } from 'node:crypto'
+
+export interface SignatureBundle {
+  /** minisign 式离线轨：对 manifestHash 的 ed25519 签名（base64） */
+  minisig?: string
+  /** Sigstore keyless 主轨：离线 bundle（S6 接口预留——bundle 校验需生态依赖，M3/沙箱外实装） */
+  sigstoreBundle?: string
+}
+
+export interface VerifyResult { ok: boolean; track: 'minisign' | 'sigstore' | 'none'; error?: string }
+
+export interface VerifierDeps {
+  /** 信任锚公钥（ed25519，base64；内置根 pinning 或 trustRoot 替换点） */
+  trustRootPublicKey: string
+  /** D-2：S6-S9 = warn，S10 起 = enforce */
+  mode: 'warn' | 'enforce'
+  /** Sigstore 主轨探针（骨架期返回 false → 回退静态轨，复现 ADR-003 回退语义） */
+  sigstoreAvailable?: () => boolean
+}
+
+/** 静态轨：ed25519 验证 manifestHash 签名 */
+export function verifyMinisig(manifestHash: string, minisig: string, trustRootPublicKey: string): { ok: boolean; error?: string } {
+  try {
+    const key = createPublicKey({ key: Buffer.from(trustRootPublicKey, 'base64'), format: 'der', type: 'spki' })
+    const ok = verify(null, Buffer.from(manifestHash), key, Buffer.from(minisig, 'base64'))
+    return ok ? { ok: true } : { ok: false, error: 'signature mismatch' }
+  } catch (e) {
+    return { ok: false, error: `verify error: ${String(e)}` }
+  }
+}
+
+/**
+ * 验签入口（装载前调用，A010001 之前的供应链第一道门）：
+ * 返回 { allowed, warning? }——warning 非空时调用方必须告警放行并留痕（enforce 前过渡期）
+ */
+export function enforceSignature(manifestHash: string, sig: SignatureBundle | undefined, deps: VerifierDeps, onCount?: (name: 'car_unsigned_confirmed', labels: { confirmed: 'yes' | 'no' }) => void): { allowed: boolean; warning?: string; error?: string } {
+  // 主轨探针：可用则先走 Sigstore（S6 骨架期默认不可用 → 回退静态轨）
+  if (deps.sigstoreAvailable?.()) {
+    if (sig?.sigstoreBundle) {
+      // bundle 校验需生态依赖（@sigstore/verify），骨架期视为不可达 → 回退静态轨（ADR-003 回退语义）
+    } else if (deps.mode === 'enforce') {
+      return { allowed: false, error: 'CAR-E-SIG: sigstore bundle missing (enforce mode)' }
+    }
+  }
+  // 静态轨
+  if (sig?.minisig) {
+    const r = verifyMinisig(manifestHash, sig.minisig, deps.trustRootPublicKey)
+    if (r.ok) return { allowed: true }
+    // 有签名但校验失败 = 硬拒绝（不可配置放行——ADR-003 fail-closed 第一级）
+    return { allowed: false, error: `CAR-E-SIG: signature verification FAILED: ${r.error}（不可配置放行）` }
+  }
+  // 签名缺失
+  if (deps.mode === 'enforce') {
+    return { allowed: false, error: 'CAR-E-SIG: signature missing (enforce mode)——manifestHash 指纹兜底不替代签名' }
+  }
+  // S17 采集面：unsigned 路径计数（零内容 labels；confirmed=no=未确认 warn / yes=显式确认豁免动作）
+  onCount?.('car_unsigned_confirmed', { confirmed: 'no' })
+  return { allowed: true, warning: 'CAR-W-SIG: unsigned plugin（warn 过渡期放行，manifestHash 指纹兜底；enforce 切换见 D-2 终局条件）' }
+}

package/src/loop/goal.ts

@@ -0,0 +1,53 @@
+/**
+ * F13 · Goal 层（五层停止第五层）：phase 持久化 + activation 进程内
+ *
+ * 口径（dsh goal/goal/src/types.ts:45,75,87-89 源码级已核实 + M2 系统设计增补 T-1）：
+ *  - GoalPhase = active | paused | blocked | complete —— 持久化：经会话日志 goalUpdate 事件
+ *  - GoalActivation = armed | disarmed —— 进程内、never persisted：
+ *    新实例默认 disarmed = 「session-start 重置 disarmed」零分支天然满足（AC-4.5）
+ *  - update_goal(complete) 不立刻掐断 turn：先写持久状态，turn 由既有收口逻辑完成（D5 §9）
+ *  - blocked 产出点：授权门 blockOnDeny / 策略门（stop.ts 集成）
+ */
+import type { SessionLog, SessionEvent } from '../session/log.ts'
+
+export type GoalPhase = 'active' | 'paused' | 'blocked' | 'complete'
+export type GoalActivation = 'armed' | 'disarmed'
+
+export class GoalDriver {
+  #log: SessionLog
+  #phase: GoalPhase = 'active'
+  #activation: GoalActivation = 'disarmed' // 重启/新实例默认 disarmed（不会把历史任务叫醒）
+  #disarmReasons: string[] = []
+
+  constructor(log: SessionLog) { this.#log = log }
+
+  get phase(): GoalPhase { return this.#phase }
+  get activation(): GoalActivation { return this.#activation }
+
+  /** 持久状态变更：写 goalUpdate 事件（重启后由恢复层读取重放） */
+  setPhase(phase: GoalPhase, reason: string): void {
+    this.#phase = phase
+    this.#log.append('runtime', 'goalUpdate', 'GOAL', { phase, reason })
+  }
+
+  /** 进程内激活（不持久化——重启后默认 disarmed） */
+  arm(): void { this.#activation = 'armed' }
+  disarm(reason: string): void {
+    this.#activation = 'disarmed'
+    this.#disarmReasons.push(reason)
+  }
+
+  /** 超限/撞限/错误自动 disarm（D5 §9：Round 超限、max-tokens、Agent error 都会 disarm） */
+  autoDisarmOnTurnEnd(reason: string): void {
+    if (reason !== 'completed') this.disarm(`turn ended with ${reason}`)
+  }
+
+  /** 恢复层：从已落盘日志重放 goalUpdate 重建 phase（activation 不恢复——保持 disarmed） */
+  static replay(events: readonly SessionEvent[]): { phase: GoalPhase; activation: GoalActivation } {
+    let phase: GoalPhase = 'active'
+    for (const e of events) {
+      if (e.kind === 'goalUpdate' && (e.payload as any)?.phase) phase = (e.payload as any).phase
+    }
+    return { phase, activation: 'disarmed' } // activation 永不持久化
+  }
+}

package/src/loop/recover.ts

@@ -0,0 +1,47 @@
+/**
+ * F13 · 恢复层：interrupted 补记（进程消失后恢复层给未闭合 turn 补状态）
+ *
+ * 口径（D4 §18 / D5 §19）：
+ *  - interrupted = 进程消失后恢复层补记，与 aborted（运行期取消可清理）不可混用
+ *  - 未配对 toolCall 补合成错误 toolResult（日志无缺口红线）
+ *  - 副作用审计：补记事件带 recovered=true 标记（副作用是否落地由恢复层显式声明为未知）
+ */
+import type { SessionLog, SessionEvent } from '../session/log.ts'
+
+export interface RecoveryReport {
+  /** 补记 interrupted 的 turn 数 */
+  turnsClosed: number
+  /** 补记合成 toolResult 的未配对调用数 */
+  pairedCalls: number
+}
+
+/** 扫描日志中未闭合的 turn（有 turnStart 语义的用户事件但没有 turnEnd）与未配对 toolCall */
+export function recoverInterrupted(log: SessionLog): RecoveryReport {
+  const report: RecoveryReport = { turnsClosed: 0, pairedCalls: 0 }
+  const callIds = new Set<string>()
+  const resultIds = new Set<string>()
+  const openTurns = new Set<string>()
+  const closedTurns = new Set<string>()
+  for (const e of log.events) {
+    if (e.kind === 'toolCall') callIds.add((e.payload as any).id)
+    if (e.kind === 'toolResult') resultIds.add((e.payload as any).id)
+    if (e.kind === 'user') openTurns.add(e.turnId)
+    if (e.kind === 'turnEnd') { closedTurns.add(e.turnId); openTurns.delete(e.turnId) }
+  }
+  // 未配对 toolCall → 合成错误 toolResult（副作用状态未知：recovered=true 显式声明）
+  for (const e of log.events) {
+    if (e.kind !== 'toolCall') continue
+    const id = (e.payload as any).id
+    if (resultIds.has(id)) continue
+    if (closedTurns.has(e.turnId)) continue // 已闭合 turn 内成对由原逻辑保证
+    log.append('runtime', 'toolResult', e.turnId, { id, error: 'recovered: process interrupted before dispatch result', recovered: true })
+    resultIds.add(id)
+    report.pairedCalls++
+  }
+  // 未闭合 turn → 补记 turnEnd=interrupted（不可与 aborted 混用）
+  for (const turnId of openTurns) {
+    log.append('runtime', 'turnEnd', turnId, null, { reason: 'interrupted', recovered: true })
+    report.turnsClosed++
+  }
+  return report
+}

package/src/loop/stop.ts

@@ -0,0 +1,200 @@
+/**
+ * F5 · 最小 turn 级停止语义（ADR-001 实装）
+ *
+ * 口径（《系统设计》F5 / D4-D5 机制对照 / POC-3 I4）：
+ *  - step 三结果：completed / max-tokens / null（null = 工具结果交回模型，非异常）
+ *  - TurnEndReason 六值：completed / max-tokens / aborted / error / blocked / interrupted
+ *    （aborted=运行期取消可清理；interrupted=进程消失后恢复层补记——不可混用，S1/S2 仅实装前者）
+ *  - ADR-001：max-tokens 解析前收口（截断响应不解析工具调用，禁补全半截 JSON）；
+ *    只读白名单可选补错重试（preset.maxTokens.retryReadOnly）；endReasonTrail 保守判定：
+ *    turn 内任一 step 撞限 → turn/end 保留 max-tokens，不被后续成功 step 冲销
+ *  - 工具收口：concludesTurn=OR（任一 true 即收口）；terminate=AND（整批 finalized 全 true 才中断）
+ *  - 取消：未派发调用补记成对事件（toolCall + 合成错误 toolResult），日志无缺口
+ */
+import type { SessionLog } from '../session/log.ts'
+
+export type StepOutcome = 'completed' | 'max-tokens' | 'null'
+export type TurnEndReason = 'completed' | 'max-tokens' | 'aborted' | 'error' | 'blocked' | 'interrupted'
+export type SideEffect = 'readonly' | 'write'
+
+export interface ToolCall { id: string; tool: string; args: Record<string, unknown> }
+export interface ToolDef {
+  declaredSideEffect: SideEffect
+  concludesTurn?: boolean
+  terminate?: boolean
+  run(args: Record<string, unknown>): Promise<unknown>
+}
+/** 模型单步响应（provider 形态；stopReason 为不可变透传——ADR-001） */
+export interface ModelStep {
+  text?: string
+  stopReason: 'stop' | 'length' | 'toolUse' | 'error'
+  /** 仅 stopReason=toolUse 时有意义；length 时 provider 可能给半截信息（CAR 不解析其 args） */
+  toolCalls?: ToolCall[]
+  /** length 时 provider 给出的「截断工具调用」：只有名字，args 不可信 */
+  truncatedTools?: Array<{ id: string; tool: string }>
+}
+
+export interface TurnPreset {
+  /** ADR-001：只读白名单补错重试开关（默认关） */
+  maxTokensRetryReadOnly?: boolean
+  /** 权限模式（F4 集成点）：confirm 下写操作需审批回调放行 */
+  mode?: 'readonly' | 'confirm' | 'full'
+  /** 确认模式审批回调：返回 true 放行 */
+  authorize?: (call: ToolCall) => Promise<boolean>
+  maxSteps?: number
+  /** F13：OR/AND 收口可配置（默认 any/all = M1 行为等价） */
+  aggregate?: { concludesTurn?: 'any' | 'all'; terminate?: 'any' | 'all' }
+  /** F13：授权拒绝即收口 blocked（默认 false = 模型继续调整） */
+  blockOnDeny?: boolean
+}
+
+export interface TurnResult { reason: TurnEndReason; steps: number; endReasonTrail: Array<{ seq: number; reason: TurnEndReason }> }
+
+export class TurnAborted extends Error {
+  constructor() { super('CAR-ABORTED: turn cancelled by user') }
+}
+
+export async function runTurn(opts: {
+  log: SessionLog
+  turnId: string
+  model: () => Promise<ModelStep>
+  tools: Map<string, ToolDef>
+  preset?: TurnPreset
+  signal?: { aborted: boolean }
+}): Promise<TurnResult> {
+  const { log, turnId, model, tools, preset = {}, signal } = opts
+  const maxSteps = preset.maxSteps ?? 32
+  const trail: Array<{ seq: number; reason: TurnEndReason }> = []
+  let sawMaxTokens = false
+  let steps = 0
+
+  const executeBatch = async (calls: ToolCall[]): Promise<{ concludesTurn: boolean; concludesAll: boolean; terminateVotes: number; terminateAll: boolean; finalized: number; denies: number }> => {
+    let concludesTurn = false
+    let concludesVotes = 0
+    let terminateVotes = 0
+    let finalized = 0
+    let denies = 0
+    for (const call of calls) {
+      if (signal?.aborted) {
+        // 取消：未派发调用补记成对事件（日志无缺口）
+        log.append('runtime', 'toolCall', turnId, call)
+        log.append('runtime', 'toolResult', turnId, { id: call.id, error: 'aborted-before-dispatch' })
+        continue
+      }
+      const def = tools.get(call.tool)
+      log.append('model', 'toolCall', turnId, call)
+      if (!def) {
+        log.append('plugin', 'toolResult', turnId, { id: call.id, error: `unknown tool "${call.tool}"` })
+        continue
+      }
+      // 权限门（F4 集成点）：write 类在 readonly/confirm 模式需放行
+      if (def.declaredSideEffect === 'write' && preset.mode !== 'full') {
+        const granted = preset.mode === 'confirm' ? await (preset.authorize?.(call) ?? Promise.resolve(false)) : false
+        log.append('runtime', 'toolResult', turnId, { id: call.id, error: 'authorization-denied', granted, mode: preset.mode })
+        if (!granted) { denies++; continue }
+      }
+      // 工具错误 = 成对 toolResult 交回模型（US-5/D5 语义：工具错误是结果而非 turn 中断——
+      // 与取消补记成对事件同纪律；turn 级 error 仅保留给模型请求/协议层失败）
+      let result: unknown
+      let toolError: string | undefined
+      try {
+        result = await def.run(call.args)
+      } catch (e) {
+        result = undefined
+        toolError = String(e)
+      }
+      log.append('plugin', 'toolResult', turnId, { id: call.id, result, ...(toolError ? { error: toolError } : {}) })
+      finalized++
+      if (def.concludesTurn) { concludesTurn = true; concludesVotes++ }
+      if (def.terminate) terminateVotes++
+    }
+    return {
+      concludesTurn, concludesAll: finalized > 0 && concludesVotes === finalized,
+      terminateVotes, terminateAll: finalized > 0 && terminateVotes === finalized,
+      finalized, denies,
+    }
+  }
+
+  try {
+    while (steps < maxSteps) {
+      if (signal?.aborted) {
+        const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'aborted' }).seq
+        trail.push({ seq, reason: 'aborted' })
+        return { reason: 'aborted', steps, endReasonTrail: trail }
+      }
+      steps++
+      log.snapshotModelRequest() // agent-loop 集成点：请求时快照（N1）
+      const step = await model()
+
+      if (step.stopReason === 'error') {
+        const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'error' }).seq
+        trail.push({ seq, reason: 'error' })
+        return { reason: 'error', steps, endReasonTrail: trail }
+      }
+
+      // ===== ADR-001：解析前收口 =====
+      if (step.stopReason === 'length') {
+        sawMaxTokens = true
+        const readonlyRetry = preset.maxTokensRetryReadOnly === true
+        const trunc = step.truncatedTools ?? []
+        const retryable = readonlyRetry && trunc.every(t => tools.get(t.tool)?.declaredSideEffect === 'readonly')
+        if (retryable && trunc.length) {
+          // Pi 式补错重试：只读白名单工具收到「参数可能被截断」错误结果，交回模型下轮
+          for (const t of trunc) {
+            log.append('runtime', 'toolCall', turnId, { id: t.id, tool: t.tool, args: {}, truncated: true })
+            log.append('runtime', 'toolResult', turnId, { id: t.id, error: 'arguments may be truncated (max-tokens)' })
+          }
+          continue
+        }
+        // 默认收口：截断响应不解析、不执行任何工具调用
+        const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'max-tokens' }).seq
+        trail.push({ seq, reason: 'max-tokens' })
+        return { reason: 'max-tokens', steps, endReasonTrail: trail }
+      }
+
+      if (step.stopReason === 'toolUse' && step.toolCalls?.length) {
+        const batch = await executeBatch(step.toolCalls)
+        // F13：授权拒绝即收口（blockOnDeny 产出点——blocked 仅新增产出点，枚举不增）
+        if (preset.blockOnDeny && batch.denies > 0) {
+          const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'blocked', denies: batch.denies }).seq
+          trail.push({ seq, reason: 'blocked' })
+          return { reason: 'blocked', steps, endReasonTrail: trail }
+        }
+        const agg = preset.aggregate ?? {}
+        const abortedNow = (agg.terminate ?? 'all') === 'any' ? batch.terminateVotes > 0 : batch.terminateAll
+        if (abortedNow) { // terminate 收口：默认 AND（整批），可配置 any
+          const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'aborted' }).seq
+          trail.push({ seq, reason: 'aborted' })
+          return { reason: 'aborted', steps, endReasonTrail: trail }
+        }
+        const concludedNow = (agg.concludesTurn ?? 'any') === 'any' ? batch.concludesTurn : batch.concludesAll && batch.finalized > 0
+        if (concludedNow) { // concludesTurn 收口：默认 OR，可配置 all
+          const reason: TurnEndReason = sawMaxTokens ? 'max-tokens' : 'completed'
+          const seq = log.append('runtime', 'turnEnd', turnId, null, { reason }).seq
+          trail.push({ seq, reason })
+          return { reason, steps, endReasonTrail: trail }
+        }
+        // null：工具结果交回模型，继续下一 step（非异常）
+        continue
+      }
+
+      // stopReason === 'stop'：模型自然完成
+      const reason: TurnEndReason = sawMaxTokens ? 'max-tokens' : 'completed'
+      const seq = log.append('runtime', 'turnEnd', turnId, null, { reason }).seq
+      trail.push({ seq, reason })
+      return { reason, steps, endReasonTrail: trail }
+    }
+    const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'error', detail: 'max-steps' }).seq
+    trail.push({ seq, reason: 'error' })
+    return { reason: 'error', steps, endReasonTrail: trail }
+  } catch (e) {
+    if (e instanceof TurnAborted) {
+      const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'aborted' }).seq
+      trail.push({ seq, reason: 'aborted' })
+      return { reason: 'aborted', steps, endReasonTrail: trail }
+    }
+    const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'error', detail: String(e) }).seq
+    trail.push({ seq, reason: 'error' })
+    return { reason: 'error', steps, endReasonTrail: trail }
+  }
+}