cli-aimlock 7.0.36 → 7.0.37

package/README.md

@@ -65,3 +65,9 @@ Source: https://github.com/88208555/aimlock-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-aimlock@latest recover <operation> <requestId>` 可重新查询原调用，不会重做操作或重复计费。链恢复不会跳过人工确认，也不会自动重跑结果不确定的本地命令。代理连接需 Node.js 22.21+ 或 24.5+；不支持的运行时会明确报错。

package/aimlock-chain-calls.mjs

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto'
 import { resolve } from 'node:path'
 import { executeCoordinatorOperation } from 'cli-swarm/coordinator'
 import { loadOfficialSkillContext } from './installer.mjs'
-import { invokeOfficialSkill } from './broker.mjs'
+import { invokeOfficialSkill, recoverOfficialSkill } from './broker.mjs'
 import { fail, sha256 } from './aimlock-local-fs.mjs'
 import { errorRecord } from './aimlock-chain-model.mjs'
 import { saveExecution } from './aimlock-chain-store.mjs'
@@ -52,10 +52,12 @@ export async function callSkill(session, skillId, operation, input) {
     const invocation = await invokeOfficialSkill(context, operation, input, {
       environment: dependencies.environment, credentialAccess: dependencies.credentialAccess,
       request: async (url, options) => {
-        const request = JSON.parse(options.body).input
-        call.requestId = request.requestId
-        call.status = 'dispatched'
-        await saveExecution(session.file, session.state)
+        if (options.method === 'POST') {
+          const request = JSON.parse(options.body).input
+          call.requestId = request.requestId
+          call.status = 'dispatched'
+          await saveExecution(session.file, session.state)
+        }
         return dependencies.request(url, options)
       },
     })
@@ -103,3 +105,20 @@ export async function callCommand(session, input) {
     throw error
   }
 }
+
+export async function recoverSkillCall(session, skillId) {
+  const call = session.record.calls.at(-1)
+  if (!call || call.kind !== 'skill' || !call.requestId || !['uncertain', 'dispatched', 'recorded'].includes(call.status)) {
+    fail('AIMLOCK_CHAIN_RECOVERY_INVALID', 'Only an uncertain skill request can be recovered by receipt query')
+  }
+  call.status = 'uncertain'
+  await saveExecution(session.file, session.state)
+  const invocation = await recoverOfficialSkill(skillContext(session.state, skillId),
+    call.operation, call.requestId, session.dependencies)
+  call.receipt = invocation
+  call.status = 'recorded'
+  call.error = null
+  call.completedAt = new Date().toISOString()
+  await saveExecution(session.file, session.state)
+  return invocation.response.output
+}

package/aimlock-chain-cli.mjs

@@ -1,6 +1,7 @@
 import { stdin, stdout } from 'node:process'
 import { answerExecution, executionStatus, initializeExecution, resumeExecution } from './aimlock-chain-executor.mjs'
 import { errorRecord } from './aimlock-chain-model.mjs'
+import { createBrokerTransport } from './broker-transport.mjs'
 import { fail } from './aimlock-local-fs.mjs'
 
 const PLAN_MAX_BYTES = 1_048_576
@@ -29,7 +30,7 @@ export async function dispatchChain(args) {
   if (!Object.hasOwn(expected, operation) || args.length !== expected[operation]) {
     fail('AIMLOCK_CHAIN_USAGE_INVALID', CHAIN_USAGE)
   }
-  const dependencies = { environment: process.env, request: fetch }
+  const dependencies = { environment: process.env, request: createBrokerTransport({ environment: process.env }) }
   if (operation === 'init') return initializeExecution(repositoryRoot, await readPlan(stdin))
   if (operation === 'status') return executionStatus(repositoryRoot, chainId)
   if (operation === 'resume') return resumeExecution(repositoryRoot, chainId, dependencies)

package/aimlock-chain-executor.mjs

@@ -4,7 +4,7 @@ import { fail } from './aimlock-local-fs.mjs'
 import { bindInput, errorRecord, validatePlan } from './aimlock-chain-model.mjs'
 import { assertNewExecution, executionStatus, initialState, loadExecution, recoverInterrupted,
   saveExecution, withExecutionLock } from './aimlock-chain-store.mjs'
-import { callCommand, callCoordinator, callSkill, resolveContexts, verifyContexts } from './aimlock-chain-calls.mjs'
+import { callCommand, callCoordinator, callSkill, recoverSkillCall, resolveContexts, verifyContexts } from './aimlock-chain-calls.mjs'
 import { answerPending, prepareHuman } from './aimlock-chain-human.mjs'
 import { skillOutcome } from './aimlock-chain-outcomes.mjs'
 
@@ -149,6 +149,20 @@ async function coordinatorStep(session, step, input) {
   }
 }
 
+function finishSkillStep(session, step, output) {
+    if (step.skillId === 'confirm-protocol' && step.operation === 'interaction-request' && output.status === 'succeeded') {
+      session.record.status = 'waiting'
+      session.record.output = output
+      session.record.pending = { kind: 'human', interaction: output.interaction, waitInput: null,
+        presentation: output.chatFallback, response: output,
+        continueWhen: Object.hasOwn(step, 'continueWhen') ? step.continueWhen : null }
+    } else {
+      const outcome = skillOutcome(step, output)
+      finish(session.record, output, outcome.status)
+      session.record.error = outcome.error
+    }
+}
+
 async function executeStep(session, step) {
   if (!await readyForWork(session, step)) return
   const input = bindInput(step, session.state)
@@ -164,17 +178,7 @@ async function executeStep(session, step) {
   } else if (step.kind === 'coordinator') await coordinatorStep(session, step, input)
   else {
     const output = await callSkill(session, step.skillId, step.operation, input)
-    if (step.skillId === 'confirm-protocol' && step.operation === 'interaction-request' && output.status === 'succeeded') {
-      session.record.status = 'waiting'
-      session.record.output = output
-      session.record.pending = { kind: 'human', interaction: output.interaction, waitInput: null,
-        presentation: output.chatFallback, response: output,
-        continueWhen: Object.hasOwn(step, 'continueWhen') ? step.continueWhen : null }
-    } else {
-      const outcome = skillOutcome(step, output)
-      finish(session.record, output, outcome.status)
-      session.record.error = outcome.error
-    }
+    finishSkillStep(session, step, output)
   }
   await saveExecution(session.file, session.state)
 }
@@ -186,6 +190,18 @@ async function advance(root, file, state, dependencies) {
     if (record.status === 'blocked' && step.kind === 'coordinator' && step.operation === 'lock-acquire'
       && record.output?.status === 'queued' && record.input) saveQueuePending(record, record.output, record.input)
     const session = { root, file, state, record, dependencies }
+    if (record.status === 'uncertain' && step.kind === 'skill'
+      && record.calls.at(-1)?.operation === step.operation) {
+      try {
+        finishSkillStep(session, step, await recoverSkillCall(session, step.skillId))
+        await saveExecution(file, state)
+      } catch (error) {
+        await failedStep(session, error)
+        return state
+      }
+      if (record.status === 'succeeded') continue
+      return state
+    }
     if (['failed', 'uncertain'].includes(record.status)) return state
     if (record.status === 'waiting' && record.pending?.kind === 'human') return state
     if (record.status === 'blocked' && record.pending?.kind !== 'coordination-guard') return state

package/aimlock-chain-model.mjs

@@ -179,7 +179,7 @@ export function chainStatus(state) {
 export function errorRecord(error) {
   if (!(error instanceof Error)) return { name: 'ThrownValue', message: String(error) }
   const value = { name: error.name, message: error.message }
-  for (const key of ['code', 'transportCode', 'operation', 'retryable']) {
+  for (const key of ['code', 'transportCode', 'operation', 'requestId', 'stage', 'transport', 'recovery', 'receiptStatus', 'retryable']) {
     if (Object.hasOwn(error, key)) value[key] = error[key]
   }
   if (error.cause instanceof Error) value.cause = errorRecord(error.cause)

package/aimlock-runtime.mjs

@@ -209,7 +209,7 @@ const RESPONSE_SCHEMA = "aimlock.skill.response/1.1";
 const ERROR_SCHEMA = "aimlock.skill.error/1.0";
 const CONTRACT_SCHEMA = "aimlock.scope-contract/1.0";
 const COMPILER_NAME = "aimlock";
-const COMPILER_VERSION = "v7.0.36";
+const COMPILER_VERSION = "v7.0.37";
 const KEEP_ALIVE_SECONDS = 90;
 const KEEP_ALIVE_MESSAGE = "智能目标持续执行中，请勿关闭！";
 const BYPASS_LINE_BUDGET = 500;

package/brain-client.mjs

@@ -4,6 +4,7 @@ import { inspectBrainTarget, brainStateDirectory, saveBrainRequest } from './bra
 export { inspectBrainTarget } from './brain-client-files.mjs'
 import { resolve } from 'node:path'
 import { brainClientAuthorization, transportFailureCode } from './broker.mjs'
+import { createBrokerTransport } from './broker-transport.mjs'
 import { executeCommand } from './aimlock-chain-process.mjs'
 
 export const BRAIN_ENDPOINT = 'https://cli.tax/api/v1/brain'
@@ -45,7 +46,7 @@ export async function invokeBrain(operation, input, dependencies = {}) {
   if (Buffer.byteLength(body) > MAX_INPUT_BYTES) throw new Error('Brain request exceeds the size limit')
   let response
   try {
-    response = await (dependencies.request ?? fetch)(endpoint, {
+    response = await (dependencies.request ?? createBrokerTransport({ environment }))(endpoint, {
       method: 'POST', redirect: 'error', headers: { Authorization: authorization, 'Content-Type': 'application/json' },
       body, signal: AbortSignal.timeout(TIMEOUT_MS),
     })

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

@@ -3,7 +3,7 @@
     "cli-aimlock": "./cli.mjs"
   },
   "dependencies": {
-    "cli-swarm": "7.0.36"
+    "cli-swarm": "7.0.37"
   },
   "description": "Aimlock skill installer for CLI.Tax: lock a user request into an executable aim and route Blueprint, Swarm, and Calctool.",
   "exports": {
@@ -17,6 +17,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",
@@ -49,5 +53,5 @@
     "url": "https://github.com/88208555/aimlock-clitax.git"
   },
   "type": "module",
-  "version": "7.0.36"
+  "version": "7.0.37"
 }

package/skill/SKILL.md

@@ -5,7 +5,7 @@ description: "Aimlock 仅用于大型、深度、跨模块、高风险、需要
 
 # Aimlock Skill
 
-Package version: v7.0.36
+Package version: v7.0.37
 
 Endpoint: https://cli.tax/R3mQ8kWpXn
 
@@ -188,3 +188,9 @@ Aimlock returns the protocol; it does not start a timer.
 4. 运行 `npx cli-aimlock@latest brain check <repositoryRoot> <handoff.json>` 执行批准的检查并回传产物哈希和结果。普通 IDE 回传属于 client-reported，不能据此声称可信验证通过。
 5. 只有已批准的可信 runner 生成与本次计划和报告绑定的签名收据后，才运行 `npx cli-aimlock@latest brain validate <repositoryRoot> <validation.json>`。没有可信收据时保持已回传状态，不伪造验证。
 6. 请求发送后结果不确定时，先用 `brain status <repositoryRoot> <status.json>` 按 requestId 或 planId 查询；禁止自动重发规划或重复计费。
+
+## 网络中断与原回执恢复
+
+仅在 TLS 握手前确定尚未发送 HTTP 请求时，broker 才允许最多 3 次连接尝试，并受总超时约束。请求发出后发生断线或响应中断，只用 GET 查询原 requestId 的服务端回执，禁止重发 POST；未取得有效回执时保留不确定状态，不得假定成功或继续依赖步骤。
+
+`npx cli-aimlock@latest recover <operation> <requestId>` 可重新查询原调用，不会重做操作或重复计费。链恢复不会跳过人工确认，也不会自动重跑结果不确定的本地命令。代理连接需 Node.js 22.21+ 或 24.5+；不支持的运行时会明确报错。

package/skill/skill.json

@@ -6,5 +6,5 @@
   "name": "aimlock",
   "schemaVersion": "aimlock.skill.request/1.1",
   "type": "Skill",
-  "version": "v7.0.36"
+  "version": "v7.0.37"
 }