cli-mergeguard 7.0.36 → 7.0.37

package/README.md

@@ -24,3 +24,9 @@ Source: https://github.com/88208555/MergeGuard-clitax.git
 Brain Client 服务端在同一次 runtime 请求的事务中绑定真实响应、生成并持久化权威评分与评语，再返回已提交回执。broker 只验证 `feedbackReceiptId`、`feedbackInvocationId` 和权威摘要，不发起第二次评价写入，也不生成分数或评语。`not-reported`、验证不完整、P0/P1 findings、`blocked` 或 `failed` 都不得生成好评；缺凭证、缺回执、摘要不匹配、响应非法或 HTTP 失败都会显式失败。
 
 本地 CLI 不提供手工评分或评语提交命令，人类不能选择技能分数或填写技能评价。日常聊天不属于评价协议。
+
+## 网络中断与原回执恢复
+
+仅在 TLS 握手前确定尚未发送 HTTP 请求时，broker 才允许最多 3 次连接尝试，并受总超时约束。请求发出后发生断线或响应中断，只用 GET 查询原 requestId 的服务端回执，禁止重发 POST；未取得有效回执时保留不确定状态，不得假定成功或继续依赖步骤。
+
+`npx cli-mergeguard@latest recover <operation> <requestId>` 可重新查询原调用，不会重做操作或重复计费。链恢复不会跳过人工确认，也不会自动重跑结果不确定的本地命令。代理连接需 Node.js 22.21+ 或 24.5+；不支持的运行时会明确报错。

package/broker-failures.mjs

@@ -0,0 +1,68 @@
+const TRANSPORT_ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9_]{1,63}$/
+const NETWORK_TRANSPORT_ERROR = 'NETWORK_TRANSPORT'
+const SKILL_INVOCATION_ERROR = 'SKILL_INVOCATION_FAILED'
+const TRANSPORT_STAGES = new Set(['configuration', 'connecting', 'tls', 'request-sent', 'response-body', 'complete'])
+const MAX_TRANSPORT_ATTEMPTS = 3
+
+export function transportDiagnostics(value) {
+  if (!value || typeof value !== 'object' || !Number.isSafeInteger(value.attempts)
+    || value.attempts < 0 || value.attempts > MAX_TRANSPORT_ATTEMPTS
+    || !TRANSPORT_STAGES.has(value.stage) || typeof value.submitted !== 'boolean') return null
+  return { attempts: value.attempts, stage: value.stage, submitted: value.submitted }
+}
+
+export class OfficialSkillInvocationError extends Error {
+  constructor(context, request, transportCode, stage, transport) {
+    super(`${context.displayName} ${request.operation} invocation failed: network transport ${transportCode}`)
+    this.name = 'OfficialSkillInvocationError'
+    this.code = NETWORK_TRANSPORT_ERROR
+    this.requestId = request.requestId
+    this.operation = request.operation
+    const diagnostic = transportDiagnostics(transport)
+    this.stage = diagnostic ? diagnostic.stage : stage
+    if (diagnostic) this.transport = diagnostic
+    this.retryable = false
+    this.transportCode = transportCode
+  }
+}
+
+export class OfficialSkillResponseError extends Error {
+  constructor(request, stage, message) {
+    super(message)
+    this.name = 'OfficialSkillResponseError'
+    this.code = SKILL_INVOCATION_ERROR
+    this.requestId = request.requestId
+    this.operation = request.operation
+    this.stage = stage
+    this.retryable = false
+  }
+}
+
+export function transportFailureCode(error) {
+  const inspected = new Set()
+  let candidate = error
+  while (candidate && typeof candidate === 'object' && !inspected.has(candidate)) {
+    inspected.add(candidate)
+    const code = typeof candidate.code === 'string' ? candidate.code.trim() : ''
+    if (TRANSPORT_ERROR_CODE_PATTERN.test(code)) return code
+    const name = typeof candidate.name === 'string' ? candidate.name.trim() : ''
+    if (name === 'AbortError' || name === 'TimeoutError') return name
+    candidate = candidate.cause
+  }
+  return 'UNKNOWN_TRANSPORT_ERROR'
+}
+
+export function officialSkillFailureResponse(error) {
+  if (error instanceof OfficialSkillInvocationError || error instanceof OfficialSkillResponseError) {
+    const failure = { code: error.code, message: error.message, requestId: error.requestId,
+      operation: error.operation, stage: error.stage, retryable: error.retryable }
+    if (typeof error.transportCode === 'string') failure.transportCode = error.transportCode
+    if (typeof error.receiptStatus === 'string') failure.receiptStatus = error.receiptStatus
+    if (error.recovery) failure.recovery = error.recovery
+    const diagnostic = transportDiagnostics(error.transport)
+    if (diagnostic) failure.transport = diagnostic
+    return { ok: false, error: failure }
+  }
+  return { ok: false, error: { code: SKILL_INVOCATION_ERROR,
+    message: error instanceof Error ? error.message : 'Skill invocation failed', retryable: false } }
+}

package/broker-recovery.mjs

@@ -0,0 +1,110 @@
+import { OfficialSkillResponseError, transportFailureCode, transportDiagnostics } from './broker-failures.mjs'
+
+export const SKILL_RECEIPT_SCHEMA = 'skill-runtime-receipt/1.0'
+export const SKILL_RECEIPT_HEADER = 'X-Skill-Receipt'
+const RECEIPT_API_PATH = '/api/v1/skill-invocations'
+const QUERY_TIMEOUT_MS = 5_000
+const QUERY_ATTEMPTS = 3
+const QUERY_DELAY_MS = 250
+const TERMINAL_STATUSES = new Set(['completed', 'failed'])
+const RECEIPT_STATUSES = new Set([...TERMINAL_STATUSES, 'pending', 'expired', 'not-found'])
+
+class ReceiptRecoveryError extends OfficialSkillResponseError {
+  constructor(request, status, message, transportCode) {
+    super(request, 'receipt-query', message)
+    this.name = 'ReceiptRecoveryError'
+    this.code = 'SKILL_INVOCATION_UNCERTAIN'
+    this.receiptStatus = status
+    if (transportCode) this.transportCode = transportCode
+  }
+}
+
+function validateReceipt(response, payload, context, request) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+    || payload.schemaVersion !== SKILL_RECEIPT_SCHEMA || payload.runtimeCode !== context.runtimeCode
+    || payload.requestId !== request.requestId || !RECEIPT_STATUSES.has(payload.status)) {
+    throw new ReceiptRecoveryError(request, 'invalid', 'Receipt query returned invalid or mismatched execution identity')
+  }
+  const expectedHttpStatus = payload.status === 'pending' ? 202
+    : payload.status === 'expired' ? 410 : payload.status === 'not-found' ? 404 : 200
+  if (response.status !== expectedHttpStatus || (payload.status !== 'not-found'
+    && !Number.isFinite(Date.parse(payload.expiresAt)))) {
+    throw new ReceiptRecoveryError(request, 'invalid', 'Receipt status or expiration metadata is invalid')
+  }
+  if (TERMINAL_STATUSES.has(payload.status) && (!Number.isInteger(payload.httpStatus)
+    || payload.httpStatus < 100 || payload.httpStatus > 599 || !payload.response
+    || typeof payload.response !== 'object' || Array.isArray(payload.response))) {
+    throw new ReceiptRecoveryError(request, 'invalid', 'Receipt has no valid recorded HTTP result')
+  }
+  if (payload.status === 'failed' && (payload.httpStatus < 400
+    || typeof payload.response.error !== 'string' || typeof payload.response.code !== 'string')) {
+    throw new ReceiptRecoveryError(request, 'invalid', 'Failed receipt has no valid recorded error')
+  }
+  return payload
+}
+
+async function fetchReceipt(context, request, dependencies, authorization) {
+  const endpoint = new URL(context.endpoint)
+  const path = `${RECEIPT_API_PATH}/${encodeURIComponent(context.runtimeCode)}/${encodeURIComponent(request.requestId)}`
+  let response
+  let payload
+  try {
+    response = await dependencies.request(new URL(path, endpoint.origin).href, {
+      method: 'GET', redirect: 'error', headers: { Authorization: authorization },
+      signal: AbortSignal.timeout(QUERY_TIMEOUT_MS),
+    })
+  } catch (error) {
+    throw new ReceiptRecoveryError(request, 'query-failed', 'Receipt query failed; execution outcome remains uncertain',
+      transportFailureCode(error))
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new ReceiptRecoveryError(request, 'unauthorized', `Receipt query authorization failed: HTTP ${response.status}`)
+  }
+  try {
+    payload = await response.json()
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new ReceiptRecoveryError(request, 'invalid', 'Receipt query returned invalid JSON')
+    throw new ReceiptRecoveryError(request, 'query-failed', 'Receipt body was interrupted; execution outcome remains uncertain',
+      transportFailureCode(error))
+  }
+  return { receipt: validateReceipt(response, payload, context, request), transport: transportDiagnostics(response.transport) }
+}
+
+function receiptOutcome(receipt, context, request, validateInvocation, transport) {
+  if (receipt.status === 'failed') {
+    throw new OfficialSkillResponseError(request, 'http-response',
+      `${context.displayName} ${request.operation} failed: HTTP ${receipt.httpStatus} (recorded receipt)`)
+  }
+  if (receipt.httpStatus !== 200 || receipt.response.ok !== true) {
+    throw new ReceiptRecoveryError(request, 'invalid', 'Completed receipt does not contain a successful HTTP response')
+  }
+  try {
+    const invocation = validateInvocation(receipt.response)
+    return { ...invocation, recovery: { status: 'completed', requestId: request.requestId },
+      ...(transport ? { transport } : {}) }
+  } catch (error) {
+    throw new OfficialSkillResponseError(request, 'receipt-validation',
+      error instanceof Error ? error.message : 'Recorded skill response validation failed')
+  }
+}
+
+export async function queryOfficialSkillReceipt(context, request, dependencies, authorization, validateInvocation) {
+  let lastFailure
+  for (let attempt = 0; attempt < QUERY_ATTEMPTS; attempt += 1) {
+    if (attempt > 0) await new Promise((resolve) => setTimeout(resolve, QUERY_DELAY_MS))
+    let fetched
+    try {
+      fetched = await fetchReceipt(context, request, dependencies, authorization)
+    } catch (error) {
+      if (!(error instanceof ReceiptRecoveryError) || error.receiptStatus !== 'query-failed') throw error
+      lastFailure = error
+      continue
+    }
+    const { receipt, transport } = fetched
+    if (TERMINAL_STATUSES.has(receipt.status)) return receiptOutcome(receipt, context, request, validateInvocation, transport)
+    lastFailure = new ReceiptRecoveryError(request, receipt.status,
+      `Invocation outcome is ${receipt.status}; query this requestId again before any new execution`)
+    if (receipt.status !== 'pending') throw lastFailure
+  }
+  throw lastFailure
+}

package/broker-transport-attempt.mjs

@@ -0,0 +1,86 @@
+function responseValue(message, chunks, state) {
+  const headers = new Headers()
+  for (let index = 0; index < message.rawHeaders.length; index += 2) {
+    headers.append(message.rawHeaders[index], message.rawHeaders[index + 1])
+  }
+  const status = message.statusCode
+  if (!Number.isInteger(status) || status < 200 || status > 599) throw new Error('BROKER_RESPONSE_STATUS_INVALID')
+  const body = Buffer.concat(chunks)
+  const emptyBody = status === 204 || status === 205 || status === 304
+  const response = new Response(emptyBody ? null : body, { status, headers })
+  response.transport = Object.freeze({ ...state, stage: 'complete' })
+  return response
+}
+
+/** No write/end/flushHeaders is permitted before the destination TLS socket is authenticated. */
+export function attemptBrokerHttps(input, dependencies) {
+  return new Promise((resolve, reject) => {
+    const { state, signal, failure } = dependencies
+    const agent = dependencies.createAgent({ ...input.agentOptions, keepAlive: false, maxSockets: 1, maxCachedSessions: 0 })
+    let request
+    let settled = false
+    let connectTimer
+    const cleanup = () => {
+      clearTimeout(connectTimer)
+      signal.removeEventListener('abort', abort)
+      agent.destroy()
+    }
+    const finishError = code => {
+      if (settled) return
+      settled = true
+      const error = failure(code)
+      request?.destroy()
+      cleanup()
+      reject(error)
+    }
+    const abort = () => finishError('ABORT_ERR')
+    const receive = response => {
+      state.stage = 'response-body'
+      const chunks = []
+      let bytes = 0
+      response.on('error', error => finishError(error.code))
+      response.on('aborted', () => finishError('BROKER_RESPONSE_TRUNCATED'))
+      response.on('close', () => { if (!response.complete) finishError('BROKER_RESPONSE_TRUNCATED') })
+      response.on('data', chunk => {
+        bytes += chunk.length
+        if (bytes > dependencies.maxResponseBytes) finishError('BROKER_RESPONSE_TOO_LARGE')
+        else chunks.push(chunk)
+      })
+      response.on('end', () => {
+        if (settled) return
+        if (!response.complete) return finishError('BROKER_RESPONSE_TRUNCATED')
+        const coding = response.headers['content-encoding']
+        if (coding !== undefined && coding !== 'identity') return finishError('BROKER_RESPONSE_ENCODING_UNSUPPORTED')
+        let value
+        try { value = responseValue(response, chunks, state) }
+        catch (error) { return finishError(error.message) }
+        settled = true
+        cleanup()
+        resolve(value)
+      })
+    }
+    try {
+      request = dependencies.request(input.target, { method: input.method, headers: input.headers, agent,
+        rejectUnauthorized: true }, receive)
+      request.on('error', error => finishError(error.code))
+      request.once('socket', socket => {
+        state.stage = 'tls'
+        const send = () => {
+          if (settled) return
+          if (signal.aborted) return abort()
+          if (socket.encrypted !== true || socket.authorized !== true) return finishError('BROKER_TLS_UNAUTHORIZED')
+          clearTimeout(connectTimer)
+          state.stage = 'request-sent'
+          state.submitted = true
+          try { request.end(input.body) } catch (error) { finishError(error.code) }
+        }
+        if (socket.encrypted === true && socket.authorized === true) send()
+        else socket.once('secureConnect', send)
+      })
+      connectTimer = setTimeout(() => finishError('ETIMEDOUT'), dependencies.connectTimeoutMs)
+      connectTimer.unref()
+      signal.addEventListener('abort', abort, { once: true })
+      if (signal.aborted) abort()
+    } catch (error) { finishError(error.code) }
+  })
+}

package/broker-transport.mjs

@@ -0,0 +1,107 @@
+import { Agent, request as httpsRequest } from 'node:https'
+import { setTimeout as delay } from 'node:timers/promises'
+import { attemptBrokerHttps } from './broker-transport-attempt.mjs'
+
+export const BROKER_TRANSPORT_TIMEOUT_MS = 120_000
+export const BROKER_TRANSPORT_CONNECT_TIMEOUT_MS = 8_000
+export const BROKER_TRANSPORT_MAX_ATTEMPTS = 3
+export const BROKER_TRANSPORT_MAX_RESPONSE_BYTES = 16 * 1024 * 1024
+const RETRY_DELAY_MS = 150
+const PROXY_KEYS = ['HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy', 'NO_PROXY', 'no_proxy']
+const TRANSIENT_CODES = new Set(['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE', 'EAI_AGAIN', 'ENETUNREACH', 'EHOSTUNREACH'])
+const CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,79}$/
+
+export class BrokerTransportError extends Error {
+  constructor(code, transport) {
+    const safeCode = typeof code === 'string' && CODE_PATTERN.test(code) ? code : 'BROKER_TRANSPORT_FAILED'
+    super(`HTTPS broker transport failed (${safeCode})`)
+    this.name = 'BrokerTransportError'
+    this.code = safeCode
+    this.transport = Object.freeze({ ...transport })
+  }
+}
+
+/** Native Agent proxyEnv: https://nodejs.org/api/https.html#new-agentoptions */
+export function brokerProxyEnvironment(environment, nodeVersion = process.versions.node) {
+  const proxyEnv = {}
+  for (const key of PROXY_KEYS) {
+    if (environment[key] !== undefined) {
+      if (typeof environment[key] !== 'string') throw new Error('BROKER_PROXY_ENV_INVALID')
+      proxyEnv[key] = environment[key]
+    }
+  }
+  const hasProxy = PROXY_KEYS.slice(0, 4).some(key => typeof proxyEnv[key] === 'string' && proxyEnv[key].trim())
+  const version = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(nodeVersion)
+  if (!version) throw new Error('BROKER_NODE_VERSION_INVALID')
+  const major = Number(version[1]), minor = Number(version[2])
+  const supportsProxy = major > 24 || major === 24 && minor >= 5 || major === 22 && minor >= 21
+  if (hasProxy && !supportsProxy) throw new Error('BROKER_PROXY_UNSUPPORTED_NODE')
+  for (const key of PROXY_KEYS.slice(0, 4)) {
+    if (!proxyEnv[key]) continue
+    let proxy
+    try { proxy = new URL(proxyEnv[key]) } catch { throw new Error('BROKER_PROXY_ENV_INVALID') }
+    if (!['http:', 'https:'].includes(proxy.protocol)) throw new Error('BROKER_PROXY_ENV_INVALID')
+  }
+  return supportsProxy ? { proxyEnv } : {}
+}
+
+function requestInput(url, options) {
+  const target = new URL(url)
+  if (target.protocol !== 'https:' || target.username || target.password) throw new Error('BROKER_HTTPS_REQUIRED')
+  const method = options.method === undefined ? 'GET' : options.method
+  if (typeof method !== 'string' || !/^[A-Z]+$/.test(method)) throw new Error('BROKER_METHOD_INVALID')
+  const headers = new Headers(options.headers)
+  headers.set('accept-encoding', 'identity')
+  const source = options.body
+  if (source !== undefined && source !== null && typeof source !== 'string' && !(source instanceof Uint8Array)) {
+    throw new Error('BROKER_BODY_INVALID')
+  }
+  const body = source === undefined || source === null ? undefined : Buffer.from(source)
+  if (body !== undefined) headers.set('content-length', String(body.length))
+  return { target, method, headers: Object.fromEntries(headers), body }
+}
+
+function overallSignal(external) {
+  const controller = new AbortController()
+  const abort = () => controller.abort(external.reason)
+  if (external?.aborted) controller.abort(external.reason)
+  else external?.addEventListener('abort', abort, { once: true })
+  const timer = setTimeout(() => controller.abort(new Error('ETIMEDOUT')), BROKER_TRANSPORT_TIMEOUT_MS)
+  timer.unref()
+  return { signal: controller.signal, cleanup() {
+    clearTimeout(timer)
+    external?.removeEventListener('abort', abort)
+  } }
+}
+
+/** Dependencies support isolated native TLS tests; production callers supply only environment. */
+export function createBrokerTransport({ environment = process.env, request = httpsRequest,
+  createAgent = options => new Agent(options), nodeVersion = process.versions.node } = {}) {
+  return async function brokerRequest(url, options = {}) {
+    const state = { attempts: 0, stage: 'configuration', submitted: false }
+    let configured
+    try { configured = { ...requestInput(url, options), agentOptions: brokerProxyEnvironment(environment, nodeVersion) } }
+    catch (error) { throw new BrokerTransportError(error.message, state) }
+    const overall = overallSignal(options.signal)
+    try {
+      for (let number = 1; number <= BROKER_TRANSPORT_MAX_ATTEMPTS; number += 1) {
+        if (overall.signal.aborted) throw new BrokerTransportError('ABORT_ERR', state)
+        state.attempts = number
+        state.stage = 'connecting'
+        try {
+          return await attemptBrokerHttps(configured, { request, createAgent, signal: overall.signal, state,
+            connectTimeoutMs: BROKER_TRANSPORT_CONNECT_TIMEOUT_MS, maxResponseBytes: BROKER_TRANSPORT_MAX_RESPONSE_BYTES,
+            failure: code => new BrokerTransportError(code, state) })
+        } catch (error) {
+          const failure = error instanceof BrokerTransportError ? error : new BrokerTransportError(error.code, state)
+          const reconnect = !state.submitted && !overall.signal.aborted && TRANSIENT_CODES.has(failure.code)
+            && number < BROKER_TRANSPORT_MAX_ATTEMPTS
+          if (!reconnect) throw failure
+          try { await delay(RETRY_DELAY_MS, undefined, { signal: overall.signal }) }
+          catch { throw new BrokerTransportError('ABORT_ERR', state) }
+        }
+      }
+      throw new BrokerTransportError('BROKER_TRANSPORT_ATTEMPTS_EXHAUSTED', state)
+    } finally { overall.cleanup() }
+  }
+}

package/broker.mjs

@@ -2,6 +2,9 @@ import { createHash, randomUUID } from 'node:crypto'
 import { constants } from 'node:fs'
 import { lstat, open } from 'node:fs/promises'
 import { resolve, win32 } from 'node:path'
+import { OfficialSkillInvocationError, OfficialSkillResponseError, transportFailureCode, transportDiagnostics } from './broker-failures.mjs'
+import { queryOfficialSkillReceipt, SKILL_RECEIPT_HEADER, SKILL_RECEIPT_SCHEMA } from './broker-recovery.mjs'
+export { officialSkillFailureResponse, transportFailureCode } from './broker-failures.mjs'
 
 export const LOOKUP_TIMEOUT_MS = 8000
 export const CALL_TIMEOUT_MS = 120_000
@@ -24,20 +27,6 @@ const VALIDATION_STATES = new Set(['passed', 'failed', 'incomplete'])
 const EVALUATION_SCHEMA = 'skill-automatic-evaluation/1.0'
 const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
 const REQUEST_SCHEMA_PATTERN = /^([A-Za-z0-9.-]+\.skill)\.request\/([0-9]+\.[0-9]+)$/
-const TRANSPORT_ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9_]{1,63}$/
-const NETWORK_TRANSPORT_ERROR = 'NETWORK_TRANSPORT'
-const SKILL_INVOCATION_ERROR = 'SKILL_INVOCATION_FAILED'
-
-class OfficialSkillInvocationError extends Error {
-  constructor(context, operation, transportCode) {
-    super(`${context.displayName} ${operation} invocation failed: network transport ${transportCode}`)
-    this.name = 'OfficialSkillInvocationError'
-    this.code = NETWORK_TRANSPORT_ERROR
-    this.operation = operation
-    this.retryable = false
-    this.transportCode = transportCode
-  }
-}
 
 function asObject(value, label) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -214,12 +203,21 @@ export function authoritativeEvaluation(value, expected) {
   return evaluation
 }
 
-async function responsePayload(response, label) {
+async function responsePayload(response, context, request) {
+  const label = `${context.displayName} ${request.operation} response`
+  let payload
   try {
-    return asObject(await response.json(), label)
-  } catch {
-    throw new Error(`${label} is not valid JSON (HTTP ${response.status})`)
+    payload = await response.json()
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new OfficialSkillResponseError(request, 'response-parse', `${label} is not valid JSON (HTTP ${response.status})`)
+    }
+    throw new OfficialSkillInvocationError(context, request, transportFailureCode(error), 'response-body', error?.transport)
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new OfficialSkillResponseError(request, 'response-validation', `${label} must be an object`)
   }
+  return payload
 }
 
 function invocationRequest(context, operation, input) {
@@ -236,43 +234,6 @@ function invocationRequest(context, operation, input) {
   }
 }
 
-export function transportFailureCode(error) {
-  const inspected = new Set()
-  let candidate = error
-  while (candidate && typeof candidate === 'object' && !inspected.has(candidate)) {
-    inspected.add(candidate)
-    const code = typeof candidate.code === 'string' ? candidate.code.trim() : ''
-    if (TRANSPORT_ERROR_CODE_PATTERN.test(code)) return code
-    const name = typeof candidate.name === 'string' ? candidate.name.trim() : ''
-    if (name === 'AbortError' || name === 'TimeoutError') return name
-    candidate = candidate.cause
-  }
-  return 'UNKNOWN_TRANSPORT_ERROR'
-}
-
-export function officialSkillFailureResponse(error) {
-  if (error instanceof OfficialSkillInvocationError) {
-    return {
-      ok: false,
-      error: {
-        code: error.code,
-        message: error.message,
-        operation: error.operation,
-        retryable: error.retryable,
-        transportCode: error.transportCode,
-      },
-    }
-  }
-  return {
-    ok: false,
-    error: {
-      code: SKILL_INVOCATION_ERROR,
-      message: error instanceof Error ? error.message : 'Skill invocation failed',
-      retryable: false,
-    },
-  }
-}
-
 export async function invokeOfficialSkill(context, operation, input, dependencies) {
   const environment = asObject(dependencies.environment, 'broker environment')
   if (typeof dependencies.request !== 'function') {
@@ -284,17 +245,64 @@ export async function invokeOfficialSkill(context, operation, input, dependencie
   try {
     response = await dependencies.request(context.endpoint, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json', Authorization: authorization },
+      headers: { 'Content-Type': 'application/json', Authorization: authorization,
+        [SKILL_RECEIPT_HEADER]: SKILL_RECEIPT_SCHEMA },
       body: JSON.stringify({ input: requestEnvelope }),
       signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
     })
   } catch (error) {
-    throw new OfficialSkillInvocationError(context, operation, transportFailureCode(error))
+    const failure = new OfficialSkillInvocationError(context, requestEnvelope, transportFailureCode(error), 'request', error?.transport)
+    return recoverTransportFailure(context, requestEnvelope, dependencies, authorization, failure)
+  }
+  let payload
+  try {
+    payload = await responsePayload(response, context, requestEnvelope)
+  } catch (error) {
+    if (!(error instanceof OfficialSkillInvocationError)) throw error
+    return recoverTransportFailure(context, requestEnvelope, dependencies, authorization, error)
   }
-  const payload = await responsePayload(response, `${context.displayName} ${operation} response`)
   if (!response.ok || payload.ok !== true) {
-    throw new Error(`${context.displayName} ${operation} failed: HTTP ${response.status}`)
+    throw new OfficialSkillResponseError(requestEnvelope, 'http-response', `${context.displayName} ${operation} failed: HTTP ${response.status}`)
   }
+  try {
+    const invocation = validateInvocationResponse(context, operation, payload, requestEnvelope)
+    const transport = transportDiagnostics(response.transport)
+    return transport ? { ...invocation, transport } : invocation
+  } catch (error) {
+    throw new OfficialSkillResponseError(requestEnvelope, 'response-validation',
+      error instanceof Error ? error.message : 'Skill response validation failed')
+  }
+}
+
+async function recoverTransportFailure(context, request, dependencies, authorization, failure) {
+  if (failure.transport?.submitted === false) throw failure
+  try {
+    const invocation = await queryOfficialSkillReceipt(context, request, dependencies, authorization,
+      (payload) => validateInvocationResponse(context, request.operation, payload, request))
+    return failure.transport ? { ...invocation, transport: failure.transport } : invocation
+  } catch (error) {
+    if (!(error instanceof OfficialSkillResponseError) || error.code !== 'SKILL_INVOCATION_UNCERTAIN') throw error
+    failure.recovery = { status: error.receiptStatus, message: error.message }
+    throw failure
+  }
+}
+
+export async function recoverOfficialSkill(context, operation, requestId, dependencies) {
+  const normalizedOperation = requiredString(operation, 'skill operation')
+  const normalizedRequestId = requiredString(requestId, 'skill requestId')
+  if (!IDENTIFIER_PATTERN.test(normalizedOperation) || !IDENTIFIER_PATTERN.test(normalizedRequestId)) {
+    throw new Error('skill recovery identity is invalid')
+  }
+  expectedResponseSchema(context.schemaVersion)
+  const environment = asObject(dependencies.environment, 'broker environment')
+  if (typeof dependencies.request !== 'function') throw new Error('broker request dependency is required')
+  const authorization = await brainClientAuthorization(context, environment, dependencies.credentialAccess)
+  const request = { schemaVersion: context.schemaVersion, requestId: normalizedRequestId, operation: normalizedOperation }
+  return queryOfficialSkillReceipt(context, request, dependencies, authorization,
+    (payload) => validateInvocationResponse(context, normalizedOperation, payload, request))
+}
+
+function validateInvocationResponse(context, operation, payload, requestEnvelope) {
   const invocationId = payload.feedbackInvocationId
   if (typeof invocationId !== 'string' || !INVOCATION_PATTERN.test(invocationId)) {
     throw new Error(`${context.displayName} ${operation} response is missing a valid feedbackInvocationId`)

package/installer.mjs

@@ -13,6 +13,7 @@ import {
   brokerCommandInput,
   invokeCommandInput,
   invokeOfficialSkill,
+  recoverOfficialSkill,
   officialSkillFailureResponse,
 } from './broker.mjs'
 
@@ -26,9 +27,12 @@ export {
   callOfficialSkill,
   invokeCommandInput,
   invokeOfficialSkill,
+  recoverOfficialSkill,
   officialSkillFailureResponse,
 } from './broker.mjs'
 
+import { createBrokerTransport } from './broker-transport.mjs'
+
 const INSTALL_META = 'install-meta.json'
 const BROKER_STDIN_MAX_BYTES = 1_048_576
 
@@ -91,7 +95,8 @@ export function installTarget(skillName, explicit) {
 }
 
 export async function fetchLatestVersion(context) {
-  const response = await fetch(context.latestEndpoint, { signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS) })
+  const request = createBrokerTransport({ environment: process.env })
+  const response = await request(context.latestEndpoint, { signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS) })
   if (!response.ok) throw new Error(`cli.tax skill lookup failed: HTTP ${response.status}`)
   const data = asObject(await response.json(), 'cli.tax skill lookup')
   return {
@@ -162,6 +167,8 @@ export function defaultUsage(context, extraLines) {
     '      Invoke through the restricted local broker; a valid real HTTP invocation submits one authority-bound evaluation.',
     `  npx ${context.npmName}@latest broker`,
     '      Read one {"operation":"...","input":{...}} request from JSON stdin.',
+    `  npx ${context.npmName}@latest recover <operation> <requestId>`,
+    '      Query an uncertain invocation without resending or charging again.',
     'Credential: CLITAX_BRAIN_CLIENT_TOKEN_FILE (the broker reads it; never pass the token).',
     `Endpoint: ${context.endpoint}`,
   ]
@@ -170,7 +177,7 @@ export function defaultUsage(context, extraLines) {
 }
 
 function brokerDependencies() {
-  return { environment: process.env, request: fetch }
+  return { environment: process.env, request: createBrokerTransport({ environment: process.env }) }
 }
 
 async function readBrokerSource(input) {
@@ -201,6 +208,19 @@ async function runBrokerInvocation(context, commandInput) {
   }
 }
 
+async function runBrokerRecovery(context, args) {
+  if (args.length !== 3) throw new Error('recover requires operation and original requestId')
+  try {
+    const invocation = await recoverOfficialSkill(context, args[1], args[2], brokerDependencies())
+    console.log(JSON.stringify(invocation))
+  } catch (error) {
+    const response = officialSkillFailureResponse(error)
+    console.log(JSON.stringify({ response }))
+    console.error(response.error.message)
+    process.exitCode = 1
+  }
+}
+
 export async function runIntakeHandshake(context, spec) {
   const invocation = await invokeOfficialSkill(context, 'capabilities', {}, brokerDependencies())
   const capabilities = invocation.response
@@ -253,6 +273,7 @@ export async function dispatchOfficialSkillCli(options) {
     if (command === 'install') await installOfficialSkill(context, argument)
     else if (command === 'check') await checkOfficialSkill(context, argument)
     else if (command === 'run') await options.runCommand(context)
+    else if (command === 'recover') await runBrokerRecovery(context, args)
     else if (command === 'invoke') await runBrokerInvocation(context, invokeCommandInput(args))
     else if (command === 'broker') {
       await runBrokerInvocation(context, brokerCommandInput(await readBrokerSource(stdin)))

package/package.json

@@ -7,6 +7,10 @@
     "cli.mjs",
     "installer.mjs",
     "broker.mjs",
+    "broker-failures.mjs",
+    "broker-recovery.mjs",
+    "broker-transport.mjs",
+    "broker-transport-attempt.mjs",
     "README.md",
     "skill/SKILL.md",
     "skill/skill.json"
@@ -18,5 +22,5 @@
     "url": "https://github.com/88208555/MergeGuard-clitax.git"
   },
   "type": "module",
-  "version": "7.0.36"
+  "version": "7.0.37"
 }

package/skill/SKILL.md

@@ -5,7 +5,7 @@ description: '智能合并守卫：快照分支+预演+验证式合并+规则衰
 
 # MergeGuard
 
-Package version: v7.0.36
+Package version: v7.0.37
 
 当前实现是“规则编译与守门协议”，不是可直接操作 git 的合并器。任何仓库写入、快照、合并或回滚都必须交给真实 local runner；远程纯运行时一律 fail-closed。
 
@@ -112,3 +112,9 @@ MergeGuard 使用 `CLITAX_VALIDATOR_RECEIPT_PUBLIC_KEY` 验证 Ed25519 签名，
 - 本地 CLI 不提供手工评分或评语提交命令，人类不得选择技能分数或填写技能评价；日常聊天不属于评价协议。
 
 调用示例：`npx cli-mergeguard@latest invoke <operation> '<JSON对象>'`。IDE 集成可向 `npx cli-mergeguard@latest broker` 的 stdin 发送 `{"operation":"capabilities","input":{}}`。
+
+## 网络中断与原回执恢复
+
+仅在 TLS 握手前确定尚未发送 HTTP 请求时，broker 才允许最多 3 次连接尝试，并受总超时约束。请求发出后发生断线或响应中断，只用 GET 查询原 requestId 的服务端回执，禁止重发 POST；未取得有效回执时保留不确定状态，不得假定成功或继续依赖步骤。
+
+`npx cli-mergeguard@latest recover <operation> <requestId>` 可重新查询原调用，不会重做操作或重复计费。链恢复不会跳过人工确认，也不会自动重跑结果不确定的本地命令。代理连接需 Node.js 22.21+ 或 24.5+；不支持的运行时会明确报错。

package/skill/skill.json

@@ -5,6 +5,6 @@
   "method": "POST",
   "name": "mergeguard",
   "type": "Skill",
-  "version": "v7.0.36",
+  "version": "v7.0.37",
   "schemaVersion": "mergeguard.skill.request/1.0"
 }