cli-swarm 7.0.19 → 7.0.28

package/README.md

@@ -6,11 +6,20 @@ swarm — 智能体蜂群编排 skill（CLI.Tax 发布）。
 - 项目 JSON 任务派单/认领/回传 + 红绿灯状态 + 进度/错误汇报
 - 固定运维智能体：心跳检测、回收卡死智能体、派新智能体继承任务续跑
 - 固定安全守卫智能体：注入/危险指令检测、异常警报
+- 固定协调智能体：`.coord/` 任务卡、冲突扫描、文件/构建锁、基线握手、依赖等待、超时与死锁处置
 
 ```bash
 npx cli-swarm@latest install
 ```
 
+本地 AutoCoord 首次调用：
+
+```bash
+cli-swarm local capabilities /absolute/repository/path
+```
+
+其余操作从 stdin 接收 capabilities 返回 Schema 对应的 JSON；协调事实只写入 `.coord/`，不依赖对话上下文。
+
 
 也可以直接从 CLI.Tax 对象存储安装（与站点「安装命令」一致）：
 
@@ -20,4 +29,10 @@ npx https://cli.tax/cli-downloads/clitax-zj7fTPVh4p.tgz install
 
 Source: https://github.com/88208555/swarm-clitax.git
 
-反馈：技能详情页「使用评价」支持 好评 / 差评 / 日常聊天。好评与差评计入市场口碑（跑马灯每日清理），日常消息保留 7 天。
+## 受限调用与自动评价
+
+使用 `npx cli-swarm@latest invoke <operation> '<JSON对象>'`，或让 IDE 以 JSON stdin 调用 `npx cli-swarm@latest broker`。broker 本身只需要 Brain Client HTTPS、受限身份文件和显式传入路径，不需要完整磁盘访问。要保证 IDE 看不到 token，必须把 broker 作为独立低权限账户或沙箱服务运行并只暴露受限 IPC；同一系统账户下的 `0600` 不能隔离 IDE 与 broker。
+
+Brain Client 服务端在同一次 runtime 请求的事务中绑定真实响应、生成并持久化权威评分与评语，再返回已提交回执。broker 只验证 `feedbackReceiptId`、`feedbackInvocationId` 和权威摘要，不发起第二次评价写入，也不生成分数或评语。`not-reported`、验证不完整、P0/P1 findings、`blocked` 或 `failed` 都不得生成好评；缺凭证、缺回执、摘要不匹配、响应非法或 HTTP 失败都会显式失败。
+
+本地 CLI 不提供手工评分或评语提交命令，人类不能选择技能分数或填写技能评价。日常聊天不属于评价协议。

package/broker.mjs

@@ -0,0 +1,301 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, open } from 'node:fs/promises'
+import { resolve, win32 } from 'node:path'
+
+export const LOOKUP_TIMEOUT_MS = 8000
+export const CALL_TIMEOUT_MS = 120_000
+const FEEDBACK_API_PATH = '/api/v1/telemetry/skill-usage'
+const TOKEN_FILE_ENV = 'CLITAX_BRAIN_CLIENT_TOKEN_FILE'
+const TOKEN_FILE_VERSION = 'member-brain.client-token-file/1.0'
+const AUTH_SCHEME = 'BrainClient'
+const TOKEN_FILE_MAX_BYTES = 16_384
+const POSIX_TOKEN_FILE_MODE = 0o600
+const WINDOWS_BROKER_DIRECTORY = ['CLI.Tax', 'broker']
+const FEEDBACK_COMMENT_MAX = 500
+const EVALUATION_DURATION_MAX = 86_400_000
+const SCORE_MIN = 0
+const SCORE_MAX = 100
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/
+const INVOCATION_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const DIGEST_PATTERN = /^[0-9a-f]{64}$/
+const PROTOCOL_STATUSES = new Set(['succeeded', 'blocked', 'failed'])
+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]+)$/
+
+function asObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`)
+  }
+  return value
+}
+
+function requiredString(value, label) {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (!text) throw new Error(`${label} is required`)
+  return text
+}
+
+function boundedInteger(value, label) {
+  if (!Number.isFinite(value) || value < 0 || !Number.isSafeInteger(value)) {
+    throw new Error(`${label} must be a non-negative safe integer`)
+  }
+  return value
+}
+
+function insideWindowsDirectory(candidate, directory) {
+  const relative = win32.relative(directory, candidate)
+  return relative === '' || (!relative.startsWith('..\\') && relative !== '..' && !win32.isAbsolute(relative))
+}
+
+export function brainClientTokenPath(environment, platform = process.platform) {
+  const configured = requiredString(environment[TOKEN_FILE_ENV], TOKEN_FILE_ENV)
+  if (platform !== 'win32') return resolve(configured)
+  if (!win32.isAbsolute(configured)) {
+    throw new Error('Windows Brain Client token file path must be absolute')
+  }
+  const localAppData = requiredString(environment.LOCALAPPDATA, 'LOCALAPPDATA')
+  const brokerDirectory = win32.resolve(localAppData, ...WINDOWS_BROKER_DIRECTORY)
+  const candidate = win32.resolve(configured)
+  if (!insideWindowsDirectory(candidate, brokerDirectory)) {
+    throw new Error(`Windows Brain Client token file must be inside ${brokerDirectory}`)
+  }
+  return candidate
+}
+
+function assertTokenFileStatus(status, platform, currentUserId) {
+  if (!status.isFile() || status.size < 1 || status.size > TOKEN_FILE_MAX_BYTES) {
+    throw new Error('Brain Client token file must be a non-empty restricted file')
+  }
+  if (platform === 'win32') return
+  if (!Number.isInteger(currentUserId)) {
+    throw new Error('Brain Client token file ownership cannot be verified')
+  }
+  if (status.uid !== currentUserId || (status.mode & 0o777) !== POSIX_TOKEN_FILE_MODE) {
+    throw new Error('Brain Client token file must be owned by the current user with mode 0600')
+  }
+}
+
+function parseTokenFile(source) {
+  let tokenFile
+  try {
+    tokenFile = asObject(JSON.parse(source), 'Brain Client token file')
+  } catch {
+    throw new Error('Brain Client token file must contain valid JSON')
+  }
+  const expectedKeys = ['authorizationScheme', 'endpoint', 'schemaVersion', 'token']
+  if (Object.keys(tokenFile).sort().join('\n') !== expectedKeys.join('\n')) {
+    throw new Error('Brain Client token file contains unknown or missing fields')
+  }
+  return tokenFile
+}
+
+export async function brainClientAuthorization(context, environment, dependencies = {}) {
+  const platform = dependencies.platform ?? process.platform
+  const tokenFilePath = brainClientTokenPath(environment, platform)
+  const inspectPath = dependencies.lstat ?? lstat
+  const openPath = dependencies.open ?? open
+  const currentUserId = platform === 'win32'
+    ? null
+    : (dependencies.getuid ?? process.getuid)?.()
+  const linkStatus = await inspectPath(tokenFilePath)
+  if (linkStatus.isSymbolicLink()) throw new Error('Brain Client token file cannot be a symlink')
+  const noFollow = platform === 'win32' ? 0 : (constants.O_NOFOLLOW ?? 0)
+  const handle = await openPath(tokenFilePath, constants.O_RDONLY | noFollow)
+  try {
+    const status = await handle.stat()
+    assertTokenFileStatus(status, platform, currentUserId)
+    const tokenFile = parseTokenFile(await handle.readFile('utf8'))
+    const endpoint = new URL(requiredString(tokenFile.endpoint, 'Brain Client endpoint'))
+    if (tokenFile.schemaVersion !== TOKEN_FILE_VERSION
+      || tokenFile.authorizationScheme !== AUTH_SCHEME
+      || endpoint.origin !== new URL(context.endpoint).origin
+      || endpoint.pathname !== FEEDBACK_API_PATH || endpoint.search || endpoint.hash
+      || endpoint.username || endpoint.password
+      || !TOKEN_PATTERN.test(tokenFile.token)) {
+      throw new Error('Brain Client token file authority is invalid')
+    }
+    return `${AUTH_SCHEME} ${tokenFile.token}`
+  } finally {
+    await handle.close()
+  }
+}
+
+function canonicalJson(value) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+    return JSON.stringify(value)
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('automatic evaluation contains a non-finite number')
+    return JSON.stringify(value)
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  const record = asObject(value, 'automatic evaluation')
+  return `{${Object.keys(record).sort().map((key) => (
+    `${JSON.stringify(key)}:${canonicalJson(record[key])}`
+  )).join(',')}}`
+}
+
+function expectedResponseSchema(requestSchema) {
+  const matched = requiredString(requestSchema, 'skill request schemaVersion')
+    .match(REQUEST_SCHEMA_PATTERN)
+  if (!matched) throw new Error('skill request schemaVersion is invalid')
+  return `${matched[1]}.response/${matched[2]}`
+}
+
+function protocolResponse(protocolValue, requestEnvelope) {
+  const protocol = asObject(protocolValue, 'skill protocol response')
+  const responseSchema = expectedResponseSchema(requestEnvelope.schemaVersion)
+  if (protocol.schemaVersion !== responseSchema) {
+    throw new Error('skill protocol response schemaVersion does not match the request')
+  }
+  if (protocol.requestId !== requestEnvelope.requestId) {
+    throw new Error('skill protocol response requestId does not match the request')
+  }
+  const status = requiredString(protocol.status, 'skill protocol status')
+  if (!PROTOCOL_STATUSES.has(status)) {
+    throw new Error('skill protocol status must be succeeded, blocked, or failed')
+  }
+  return { protocol, responseSchema, status }
+}
+
+export function authoritativeEvaluation(value, expected) {
+  const evaluation = asObject(value, 'server automatic evaluation')
+  const expectedKeys = [
+    'digest', 'durationMs', 'findingCount', 'operation', 'p0Count', 'p1Count', 'p2Count',
+    'requestId', 'responseSchemaVersion', 'schemaVersion', 'score', 'status', 'userComment',
+    'validation',
+  ]
+  if (Object.keys(evaluation).sort().join('\n') !== expectedKeys.join('\n')) {
+    throw new Error('server automatic evaluation contains unknown or missing fields')
+  }
+  if (evaluation.schemaVersion !== EVALUATION_SCHEMA
+    || evaluation.operation !== expected.operation
+    || evaluation.requestId !== expected.requestId
+    || evaluation.responseSchemaVersion !== expected.responseSchema
+    || evaluation.status !== expected.status
+    || !VALIDATION_STATES.has(evaluation.validation)
+    || typeof evaluation.userComment !== 'string' || !evaluation.userComment.trim()
+    || Buffer.byteLength(evaluation.userComment, 'utf8') > FEEDBACK_COMMENT_MAX
+    || typeof evaluation.digest !== 'string' || !DIGEST_PATTERN.test(evaluation.digest)) {
+    throw new Error('server automatic evaluation authority is invalid')
+  }
+  for (const field of ['durationMs', 'findingCount', 'p0Count', 'p1Count', 'p2Count', 'score']) {
+    boundedInteger(evaluation[field], `server automatic evaluation ${field}`)
+  }
+  if (evaluation.score < SCORE_MIN || evaluation.score > SCORE_MAX
+    || evaluation.durationMs > EVALUATION_DURATION_MAX
+    || evaluation.findingCount < evaluation.p0Count + evaluation.p1Count + evaluation.p2Count) {
+    throw new Error('server automatic evaluation bounds are invalid')
+  }
+  if ((evaluation.status !== 'succeeded' || evaluation.validation !== 'passed'
+    || evaluation.p0Count > 0 || evaluation.p1Count > 0) && evaluation.score >= 60) {
+    throw new Error('server automatic evaluation cannot report a positive score')
+  }
+  const { digest, ...core } = evaluation
+  const actualDigest = createHash('sha256').update(canonicalJson(core)).digest('hex')
+  if (digest !== actualDigest) throw new Error('server automatic evaluation digest is invalid')
+  return evaluation
+}
+
+async function responsePayload(response, label) {
+  try {
+    return asObject(await response.json(), label)
+  } catch {
+    throw new Error(`${label} is not valid JSON (HTTP ${response.status})`)
+  }
+}
+
+function invocationRequest(context, operation, input) {
+  const normalizedOperation = requiredString(operation, 'skill operation')
+  if (!IDENTIFIER_PATTERN.test(normalizedOperation)) {
+    throw new Error('skill operation is invalid')
+  }
+  expectedResponseSchema(context.schemaVersion)
+  return {
+    schemaVersion: context.schemaVersion,
+    requestId: `${context.runtimeCode}-${randomUUID()}`,
+    operation: normalizedOperation,
+    input: asObject(input, 'skill operation input'),
+  }
+}
+
+export async function invokeOfficialSkill(context, operation, input, dependencies) {
+  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 requestEnvelope = invocationRequest(context, operation, input)
+  let response
+  try {
+    response = await dependencies.request(context.endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: authorization },
+      body: JSON.stringify({ input: requestEnvelope }),
+      signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+    })
+  } catch {
+    throw new Error(`${context.displayName} ${operation} invocation failed`)
+  }
+  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}`)
+  }
+  const invocationId = payload.feedbackInvocationId
+  if (typeof invocationId !== 'string' || !INVOCATION_PATTERN.test(invocationId)) {
+    throw new Error(`${context.displayName} ${operation} response is missing a valid feedbackInvocationId`)
+  }
+  const feedbackReceiptId = payload.feedbackReceiptId
+  const feedbackRequestId = payload.feedbackRequestId
+  if (typeof feedbackReceiptId !== 'string' || !INVOCATION_PATTERN.test(feedbackReceiptId)
+    || feedbackRequestId !== `automatic-${invocationId}`) {
+    throw new Error(`${context.displayName} ${operation} response is missing a committed feedback receipt`)
+  }
+  const protocolAuthority = protocolResponse(payload.output, requestEnvelope)
+  const evaluation = authoritativeEvaluation(payload.feedbackEvaluation, {
+    operation: requestEnvelope.operation,
+    requestId: requestEnvelope.requestId,
+    responseSchema: protocolAuthority.responseSchema,
+    status: protocolAuthority.status,
+  })
+  const feedback = {
+    id: feedbackReceiptId,
+    requestId: feedbackRequestId,
+    duplicated: false,
+  }
+  return { response: payload, invocationId, evaluation, feedback }
+}
+
+export async function callOfficialSkill(context, operation, input, dependencies) {
+  return (await invokeOfficialSkill(context, operation, input, dependencies)).response
+}
+
+export function invokeCommandInput(args) {
+  const operation = requiredString(args[1], 'skill operation')
+  const source = args.slice(2).join(' ').trim()
+  if (!source) return { operation, input: {} }
+  try {
+    return { operation, input: asObject(JSON.parse(source), 'skill operation input') }
+  } catch {
+    throw new Error('skill operation input must be a JSON object')
+  }
+}
+
+export function brokerCommandInput(source) {
+  let parsed
+  try {
+    parsed = asObject(JSON.parse(source), 'broker request')
+  } catch {
+    throw new Error('broker request must be a JSON object')
+  }
+  if (Object.keys(parsed).some((key) => !['operation', 'input'].includes(key))) {
+    throw new Error('broker request contains unknown fields')
+  }
+  return {
+    operation: requiredString(parsed.operation, 'skill operation'),
+    input: asObject(parsed.input, 'skill operation input'),
+  }
+}

package/cli.mjs

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
-import { dirname } from 'node:path'
+import { dirname, resolve } from 'node:path'
+import { stdin } from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { dispatchOfficialSkillCli, runIntakeHandshake } from './installer.mjs'
+import { executeCoordinatorOperation } from './swarm-coordinator.mjs'
+
+const MAX_LOCAL_STDIN_BYTES = 1_048_576
 
 const INTAKE_QUESTIONS = [
   {
@@ -30,14 +34,52 @@ const INTAKE_QUESTIONS = [
   },
 ]
 
-await dispatchOfficialSkillCli({
-  packageRoot: dirname(fileURLToPath(import.meta.url)),
-  runCommand: (context) => runIntakeHandshake(context, {
-    questions: INTAKE_QUESTIONS,
-    outputFile: 'SWARM-REQUIREMENTS.json',
-    afterCapabilities(output) {
-      const instruction = output.nextStep?.instruction
-      if (typeof instruction === 'string' && instruction.trim()) console.log(instruction)
-    },
-  }),
-})
+async function readLocalInput() {
+  const chunks = []
+  let bytes = 0
+  for await (const chunk of stdin) {
+    bytes += chunk.length
+    if (bytes > MAX_LOCAL_STDIN_BYTES) throw new Error('coordinator input exceeds 1 MiB')
+    chunks.push(chunk)
+  }
+  const source = Buffer.concat(chunks).toString('utf8').trim()
+  const input = source ? JSON.parse(source) : {}
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('coordinator input must be a JSON object')
+  }
+  return input
+}
+
+async function runLocalCoordinator(args) {
+  const operation = args[0]?.trim()
+  const repositoryRoot = args[1]?.trim()
+  if (!operation || !repositoryRoot) throw new Error('usage: cli-swarm local <operation> <repositoryRoot>')
+  return executeCoordinatorOperation(operation, repositoryRoot, await readLocalInput())
+}
+
+const cliPath = fileURLToPath(import.meta.url)
+if (process.argv[1] && resolve(process.argv[1]) === cliPath && process.argv[2] === 'local') {
+  try {
+    console.log(JSON.stringify(await runLocalCoordinator(process.argv.slice(3))))
+  } catch (error) {
+    const code = error instanceof Error && typeof error.code === 'string'
+      ? error.code : 'SWARM_COORD_FAILED'
+    console.error(JSON.stringify({ status: 'failed', code,
+      message: error instanceof Error ? error.message : String(error) }))
+    process.exitCode = 1
+  }
+} else {
+  await dispatchOfficialSkillCli({
+    packageRoot: dirname(cliPath),
+    runCommand: (context) => runIntakeHandshake(context, {
+      questions: INTAKE_QUESTIONS,
+      outputFile: 'SWARM-REQUIREMENTS.json',
+      afterCapabilities(output) {
+        const instruction = output.nextStep?.instruction
+        if (typeof instruction === 'string' && instruction.trim()) console.log(instruction)
+      },
+    }),
+  })
+}
+
+export { runLocalCoordinator }

package/installer.mjs

@@ -2,29 +2,33 @@
  * 八个官方技能共用这一份安装器。packages/*-cli/installer.mjs 必须与本文件字节一致。
  * 禁止第二套超时、第二套版本来源、第二套 bin 名。
  */
-import { randomUUID } from 'node:crypto'
-import { constants, existsSync, readFileSync } from 'node:fs'
-import { cp, lstat, mkdir, open, rm, writeFile } from 'node:fs/promises'
+import { existsSync, readFileSync } from 'node:fs'
+import { cp, mkdir, rm, writeFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { stdin, stdout } from 'node:process'
 import { createInterface } from 'node:readline/promises'
 import { fileURLToPath } from 'node:url'
+import {
+  LOOKUP_TIMEOUT_MS,
+  brokerCommandInput,
+  invokeCommandInput,
+  invokeOfficialSkill,
+} from './broker.mjs'
+
+export {
+  CALL_TIMEOUT_MS,
+  LOOKUP_TIMEOUT_MS,
+  authoritativeEvaluation,
+  brainClientAuthorization,
+  brainClientTokenPath,
+  brokerCommandInput,
+  callOfficialSkill,
+  invokeCommandInput,
+  invokeOfficialSkill,
+} from './broker.mjs'
 
-export const LOOKUP_TIMEOUT_MS = 8000
-export const CALL_TIMEOUT_MS = 120_000
 const INSTALL_META = 'install-meta.json'
-const FEEDBACK_API_PATH = '/api/v1/telemetry/skill-usage'
-const BRAIN_CLIENT_TOKEN_FILE_ENV = 'CLITAX_BRAIN_CLIENT_TOKEN_FILE'
-const BRAIN_CLIENT_TOKEN_FILE_VERSION = 'member-brain.client-token-file/1.0'
-const BRAIN_CLIENT_AUTH_SCHEME = 'BrainClient'
-const BRAIN_CLIENT_TOKEN_FILE_MAX_BYTES = 16_384
-const BRAIN_CLIENT_TOKEN_FILE_MODE = 0o600
-const FEEDBACK_COMMENT_MAX = 500
-const FEEDBACK_SCORE_MIN = 0
-const FEEDBACK_SCORE_MAX = 100
-const BRAIN_CLIENT_TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/
-const FEEDBACK_INVOCATION_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
-const FEEDBACK_SCORE_PATTERN = /^(?:0|[1-9]\d{0,2})$/
+const BROKER_STDIN_MAX_BYTES = 1_048_576
 
 function asObject(value, label) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -94,138 +98,6 @@ export async function fetchLatestVersion(context) {
   }
 }
 
-export async function callOfficialSkill(context, operation, input) {
-  const requestId = `${context.npmName}-${Date.now()}`
-  const response = await fetch(context.endpoint, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      input: {
-        schemaVersion: context.schemaVersion,
-        requestId,
-        operation,
-        input,
-      },
-    }),
-    signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
-  })
-  let payload
-  try {
-    payload = await response.json()
-  } catch {
-    throw new Error(`${context.displayName} ${operation} failed: non-JSON response (HTTP ${response.status}). Check ${context.endpoint}.`)
-  }
-  if (!response.ok || payload?.ok !== true) {
-    const message = payload?.error?.message
-    if (typeof message !== 'string' || !message.trim()) {
-      throw new Error(`${context.displayName} ${operation} failed: HTTP ${response.status}`)
-    }
-    throw new Error(`${context.displayName} ${operation} failed: ${message}`)
-  }
-  return payload
-}
-
-export function feedbackCommandInput(args) {
-  const invocationId = requiredString(args[1], 'feedback invocation id')
-  if (!FEEDBACK_INVOCATION_PATTERN.test(invocationId)) {
-    throw new Error('feedback invocation id must be the UUID returned by a real skill response')
-  }
-  const scoreText = requiredString(args[2], 'feedback score')
-  if (!FEEDBACK_SCORE_PATTERN.test(scoreText)) {
-    throw new Error(`feedback score must be an integer between ${FEEDBACK_SCORE_MIN} and ${FEEDBACK_SCORE_MAX}`)
-  }
-  const score = Number(scoreText)
-  if (!Number.isInteger(score) || score < FEEDBACK_SCORE_MIN || score > FEEDBACK_SCORE_MAX) {
-    throw new Error(`feedback score must be between ${FEEDBACK_SCORE_MIN} and ${FEEDBACK_SCORE_MAX}`)
-  }
-  const userComment = args.slice(3).join(' ').trim()
-  if (!userComment) throw new Error('feedback comment is required')
-  if (userComment.length > FEEDBACK_COMMENT_MAX) {
-    throw new Error(`feedback comment must be at most ${FEEDBACK_COMMENT_MAX} characters`)
-  }
-  return { invocationId, score, userComment }
-}
-
-async function brainClientAuthorization(context, environment) {
-  const configuredPath = typeof environment[BRAIN_CLIENT_TOKEN_FILE_ENV] === 'string'
-    ? environment[BRAIN_CLIENT_TOKEN_FILE_ENV].trim() : ''
-  if (!configuredPath) throw new Error(`${BRAIN_CLIENT_TOKEN_FILE_ENV} is required`)
-  if (process.platform === 'win32' || typeof process.getuid !== 'function') {
-    throw new Error('Brain Client token file ownership cannot be verified')
-  }
-  const tokenFilePath = resolve(configuredPath)
-  const linkStatus = await lstat(tokenFilePath)
-  if (linkStatus.isSymbolicLink()) throw new Error('Brain Client token file cannot be a symlink')
-  const handle = await open(tokenFilePath, constants.O_RDONLY | constants.O_NOFOLLOW)
-  try {
-    const status = await handle.stat()
-    if (!status.isFile() || status.uid !== process.getuid()
-      || (status.mode & 0o777) !== BRAIN_CLIENT_TOKEN_FILE_MODE
-      || status.size < 1 || status.size > BRAIN_CLIENT_TOKEN_FILE_MAX_BYTES) {
-      throw new Error('Brain Client token file must be owned by the current user with mode 0600')
-    }
-    const tokenFile = asObject(JSON.parse(await handle.readFile('utf8')), 'Brain Client token file')
-    const expectedKeys = ['authorizationScheme', 'endpoint', 'schemaVersion', 'token']
-    if (Object.keys(tokenFile).sort().join('\n') !== expectedKeys.join('\n')) {
-      throw new Error('Brain Client token file contains unknown or missing fields')
-    }
-    const endpoint = new URL(requiredString(tokenFile.endpoint, 'Brain Client endpoint'))
-    if (tokenFile.schemaVersion !== BRAIN_CLIENT_TOKEN_FILE_VERSION
-      || tokenFile.authorizationScheme !== BRAIN_CLIENT_AUTH_SCHEME
-      || endpoint.origin !== new URL(context.endpoint).origin
-      || endpoint.pathname !== FEEDBACK_API_PATH || endpoint.search || endpoint.hash
-      || endpoint.username || endpoint.password
-      || !BRAIN_CLIENT_TOKEN_PATTERN.test(tokenFile.token)) {
-      throw new Error('Brain Client token file authority is invalid')
-    }
-    return `${BRAIN_CLIENT_AUTH_SCHEME} ${tokenFile.token}`
-  } finally {
-    await handle.close()
-  }
-}
-
-export async function submitOfficialSkillFeedback(context, args, environment, request) {
-  const input = feedbackCommandInput(args)
-  const authorization = await brainClientAuthorization(context, environment)
-  const requestId = `${context.runtimeCode}-${randomUUID()}`
-  let response
-  try {
-    response = await request(new URL(FEEDBACK_API_PATH, context.endpoint), {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: authorization,
-      },
-      body: JSON.stringify({
-        requestId,
-        skillId: context.runtimeCode,
-        invocationId: input.invocationId,
-        score: input.score,
-        userComment: input.userComment,
-      }),
-      signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
-    })
-  } catch {
-    throw new Error('cli.tax feedback request failed')
-  }
-  let payload
-  try {
-    payload = asObject(await response.json(), 'cli.tax feedback response')
-  } catch (error) {
-    if (error instanceof Error && error.message.startsWith('cli.tax feedback response')) throw error
-    throw new Error(`cli.tax feedback failed: non-JSON response (HTTP ${response.status})`)
-  }
-  if (!response.ok || payload.ok !== true) {
-    throw new Error(`cli.tax feedback failed: HTTP ${response.status}`)
-  }
-  if (payload.requestId !== requestId || typeof payload.id !== 'string'
-    || !FEEDBACK_INVOCATION_PATTERN.test(payload.id)
-    || typeof payload.duplicated !== 'boolean') {
-    throw new Error('cli.tax feedback response authority is invalid')
-  }
-  return { id: payload.id, requestId, duplicated: payload.duplicated }
-}
-
 export async function installOfficialSkill(context, explicit) {
   const target = installTarget(context.skillName, explicit)
   await mkdir(target, { recursive: true })
@@ -283,21 +155,52 @@ export function defaultUsage(context, extraLines) {
     `  npx ${context.npmName}@latest check [directory]`,
     '      Check whether the installed skill has a newer version.',
     `  npx ${context.npmName}@latest run`,
-    '      Run the skill handshake: discover capabilities and collect intake answers.',
+    "      Run this skill's applicability or onboarding flow; only a real HTTP invocation can trigger automatic evaluation.",
+    `  npx ${context.npmName}@latest invoke <operation> <JSON-object>`,
+    '      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.',
+    'Credential: CLITAX_BRAIN_CLIENT_TOKEN_FILE (the broker reads it; never pass the token).',
     `Endpoint: ${context.endpoint}`,
   ]
   if (extraLines?.length) lines.push('', ...extraLines)
   return lines.join('\n')
 }
 
+function brokerDependencies() {
+  return { environment: process.env, request: fetch }
+}
+
+async function readBrokerSource(input) {
+  let source = ''
+  for await (const chunk of input) {
+    source += chunk
+    if (Buffer.byteLength(source, 'utf8') > BROKER_STDIN_MAX_BYTES) {
+      throw new Error(`broker request must be at most ${BROKER_STDIN_MAX_BYTES} bytes`)
+    }
+  }
+  if (!source.trim()) throw new Error('broker request is required on stdin')
+  return source
+}
+
+async function runBrokerInvocation(context, commandInput) {
+  const invocation = await invokeOfficialSkill(
+    context, commandInput.operation, commandInput.input, brokerDependencies(),
+  )
+  console.log(JSON.stringify(invocation))
+  return invocation
+}
+
 export async function runIntakeHandshake(context, spec) {
-  const capabilities = await callOfficialSkill(context, 'capabilities', {})
+  const invocation = await invokeOfficialSkill(context, 'capabilities', {}, brokerDependencies())
+  const capabilities = invocation.response
   const output = capabilities.output && typeof capabilities.output === 'object' ? capabilities.output : {}
   const skill = output.skill && typeof output.skill === 'object' ? output.skill : {}
   const version = typeof skill.version === 'string' && skill.version.trim()
     ? skill.version.trim()
     : context.skillVersion
   console.log(`${context.displayName} ${version}`)
+  console.log(`Automatic feedback accepted: ${invocation.feedback.id}`)
   if (typeof spec.afterCapabilities === 'function') spec.afterCapabilities(output)
   const readline = createInterface({ input: stdin, output: stdout })
   const answers = []
@@ -340,9 +243,9 @@ 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 === 'feedback') {
-      const receipt = await submitOfficialSkillFeedback(context, args, process.env, fetch)
-      console.log(`${context.displayName} feedback accepted: ${receipt.id}`)
+    else if (command === 'invoke') await runBrokerInvocation(context, invokeCommandInput(args))
+    else if (command === 'broker') {
+      await runBrokerInvocation(context, brokerCommandInput(await readBrokerSource(stdin)))
     }
     else if (command === 'help' || command === '--help' || command === '-h') {
       console.log(options.usage ? options.usage(context) : defaultUsage(context, options.extraUsageLines))