cli-aimlock 7.0.37 → 7.0.39

package/README.md

@@ -71,3 +71,17 @@ Brain Client 服务端在同一次 runtime 请求的事务中绑定真实响应
 仅在 TLS 握手前确定尚未发送 HTTP 请求时，broker 才允许最多 3 次连接尝试，并受总超时约束。请求发出后发生断线或响应中断，只用 GET 查询原 requestId 的服务端回执，禁止重发 POST；未取得有效回执时保留不确定状态，不得假定成功或继续依赖步骤。
 
 `npx cli-aimlock@latest recover <operation> <requestId>` 可重新查询原调用，不会重做操作或重复计费。链恢复不会跳过人工确认，也不会自动重跑结果不确定的本地命令。代理连接需 Node.js 22.21+ 或 24.5+；不支持的运行时会明确报错。
+
+## 账号共享凭据与自动更新
+
+在已登录的能力市场复制安装入口，将内容粘贴给 IDE。页面只展示原地址，剪贴板会携带当前账号凭据。IDE 将四字段凭据 JSON 经标准输入交给 `npx cli-aimlock@latest configure`；不要放到命令参数、项目文件或日志中。一次配置供同一操作系统账号的所有项目、分支和任务使用，八个技能共享同一文件。
+
+默认位置：macOS 为 `~/Library/Application Support/CLI.Tax/broker/credential.json`，Linux 为 `~/.local/share/CLI.Tax/broker/credential.json`，Windows 为 `%LOCALAPPDATA%\CLI.Tax\broker\credential.json`。显式 `CLITAX_BRAIN_CLIENT_TOKEN_FILE` 仍按绝对路径覆盖默认位置；迁移旧 IDE 配置时移除其过时覆盖，再使用账号共享文件。macOS/Linux 校验当前账号所有权和0600权限；Windows校验仅当前账号与SYSTEM可访问的ACL。
+
+每次新技能调用先查询官方发布版本，精确版本下载并校验身份后自动使用；更新已托管的当前项目与账号技能目录，失败恢复旧目录，禁止覆盖 Git 跟踪源码或未托管内容。升级返回 `upgrade.reloadRequired` 和说明路径时，IDE 应读取更新后的 SKILL.md、核对本任务合同再继续。install/check同样自动更新，不需要每次人工发升级指令。查询不确定调用的原回执不升级、不重发操作。
+
+升级不会清除账号凭据；各调用重新读取共享文件，因此重新同步一次密钥后所有任务使用新值。已撤销或失效的密钥不能为自己取得新权限，必须从已认证网页重新同步一次。两个不同操作系统账号不共享私密文件。
+
+English: configure once using JSON stdin; all tasks under the same OS account reuse the credential. Each new invocation checks and updates the official package and managed documentation. Reload updated instructions when indicated. Revoked keys require a fresh authenticated copy.
+
+Русский: настройте ключ один раз через JSON stdin для всех задач пользователя ОС. Перед новым вызовом пакет и управляемые инструкции обновляются автоматически. Отозванный ключ требует повторной синхронизации с авторизованной страницы.

package/aimlock-chain-calls.mjs

@@ -30,7 +30,7 @@ function skillContext(state, skillId) {
 
 async function startCall(session, kind, operation, input) {
   const call = { callId: 'call-' + randomUUID(), kind, operation, inputDigest: sha256(JSON.stringify(input)),
-    requestId: null, status: 'started', pid: null, receipt: null, error: null,
+    requestId: null, requestSchemaVersion: null, status: 'started', pid: null, receipt: null, error: null,
     startedAt: new Date().toISOString(), completedAt: null }
   session.record.calls.push(call)
   await saveExecution(session.file, session.state)
@@ -51,10 +51,12 @@ export async function callSkill(session, skillId, operation, input) {
     const dependencies = session.dependencies
     const invocation = await invokeOfficialSkill(context, operation, input, {
       environment: dependencies.environment, credentialAccess: dependencies.credentialAccess,
+      workingDirectory: session.root, homeDirectory: dependencies.homeDirectory,
       request: async (url, options) => {
         if (options.method === 'POST') {
           const request = JSON.parse(options.body).input
           call.requestId = request.requestId
+          call.requestSchemaVersion = request.schemaVersion
           call.status = 'dispatched'
           await saveExecution(session.file, session.state)
         }
@@ -113,7 +115,13 @@ export async function recoverSkillCall(session, skillId) {
   }
   call.status = 'uncertain'
   await saveExecution(session.file, session.state)
-  const invocation = await recoverOfficialSkill(skillContext(session.state, skillId),
+  const context = skillContext(session.state, skillId)
+  // Legacy calls used the initialized context; new calls persist the schema actually sent before POST.
+  const schemaVersion = Object.hasOwn(call, 'requestSchemaVersion') ? call.requestSchemaVersion : context.schemaVersion
+  if (typeof schemaVersion !== 'string' || !/^[a-z-]+\.skill\.request\/\d+\.\d+$/.test(schemaVersion)) {
+    fail('AIMLOCK_CHAIN_RECOVERY_INVALID', 'Dispatched request schema is missing or invalid')
+  }
+  const invocation = await recoverOfficialSkill({ ...context, schemaVersion },
     call.operation, call.requestId, session.dependencies)
   call.receipt = invocation
   call.status = 'recorded'

package/aimlock-chain-executor.mjs

@@ -1,3 +1,4 @@
+import { decisionResumesTask, decisionTargetsTask } from 'cli-swarm/coordinator'
 import { randomUUID } from 'node:crypto'
 import { assertChainNotSuspended } from './aimlock-coordination.mjs'
 import { fail } from './aimlock-local-fs.mjs'
@@ -57,14 +58,13 @@ function finish(record, output, status) {
 
 async function stillWaiting(session, output, pending) {
   if (output.status === 'waiting') return true
-  const releasedByHuman = pending.decision?.status === 'resolved'
-    && pending.decision.answer === 'resume:' + pending.input.agentId
+  const releasedByHuman = pending.decision && decisionResumesTask(pending.decision, pending.input)
   if (output.status !== 'blocked' || (output.wakePackage?.reason !== 'event-received' && !releasedByHuman)) return false
   const current = (await callCoordinator(session, 'status', {})).state
   const task = current.tasks.find((item) => item.taskId === pending.input.taskId)
   if (!task || ['completed', 'failed', 'reclaimed'].includes(task.status)) return false
   return current.waits.some((wait) => wait.taskId === task.taskId && wait.status === 'active')
-    || current.decisions.some((decision) => decision.status === 'pending' && decision.agents.includes(task.agentId))
+    || current.decisions.some((decision) => decisionTargetsTask(decision, task) && decision.status === 'pending')
 }
 
 async function driveWait(session) {
@@ -80,8 +80,7 @@ async function driveWait(session) {
     await prepareHuman(session, output.confirmProtocolRequests[0].input.interaction, pending.input)
     return
   }
-  const releasedByHuman = pending.decision?.status === 'resolved'
-    && pending.decision.answer === 'resume:' + pending.input.agentId
+  const releasedByHuman = pending.decision && decisionResumesTask(pending.decision, pending.input)
     && output.status === 'resolved'
   if (releasedByHuman) {
     finish(session.record, { ...output, status: 'resolved-by-human',

package/aimlock-coordination.mjs

@@ -1,3 +1,4 @@
+import { decisionResumesTask, decisionTargetsTask } from 'cli-swarm/coordinator'
 import { verify } from 'node:crypto'
 import { lstat, readFile } from 'node:fs/promises'
 import { basename, resolve } from 'node:path'
@@ -35,9 +36,9 @@ function failureHandled(task, tasks, inspected = new Set()) {
 
 function parkedAfterDecision(task, tasks, decisions) {
   if (task.status !== 'blocked' || task.blockedReason !== 'human-decision') return false
-  const decision = decisions.findLast((item) => item.agents.includes(task.agentId))
+  const decision = decisions.findLast((item) => decisionTargetsTask(item, task))
   return decision?.status === 'resolved'
-    && tasks.some((active) => active.status === 'active' && decision.answer === 'resume:' + active.agentId)
+    && tasks.some((active) => active.status === 'active' && decisionResumesTask(decision, active))
 }
 
 function assertChainRunnable(state, chainId) {
@@ -46,7 +47,7 @@ function assertChainRunnable(state, chainId) {
   const wait = state.waits.find((item) => item.chainId === chainId && item.status === 'active')
   if (wait) fail('AIMLOCK_COORDINATION_WAITING', 'chain ' + chainId + ' is suspended until ' + wait.event + ' or ' + wait.deadlineAt)
   const pending = state.decisions.some((decision) => decision.status === 'pending'
-    && tasks.some((task) => decision.agents.includes(task.agentId)))
+    && tasks.some((task) => decisionTargetsTask(decision, task)))
   const unresolved = tasks.some((task) => ['failed', 'reclaimed'].includes(task.status)
     && !failureHandled(task, tasks))
   if (!tasks.some((task) => task.status === 'active') || pending || unresolved

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.37";
+const COMPILER_VERSION = "v7.0.39";
 const KEEP_ALIVE_SECONDS = 90;
 const KEEP_ALIVE_MESSAGE = "智能目标持续执行中，请勿关闭！";
 const BYPASS_LINE_BUDGET = 500;

package/aimlock-tasks-cli.mjs

@@ -0,0 +1,202 @@
+import { stdin, stdout } from 'node:process'
+import { executeCoordinatorOperation } from 'cli-swarm/coordinator'
+import { errorRecord } from './aimlock-chain-model.mjs'
+import { fail } from './aimlock-local-fs.mjs'
+
+const TASK_INPUT_MAX_BYTES = 1_048_576
+const MAX_TASK_DELIVERY_TIMEOUT_MS = 2_147_483_647
+export const TASK_DELIVERY_TIMEOUT_MS = 30_000
+export const TASK_OPERATIONS = Object.freeze([
+  'task-describe', 'task-checkpoint', 'task-resume', 'message-route', 'message-status',
+  'message-accept', 'message-complete', 'message-delivery-start', 'message-delivery-report',
+  'message-resolve', 'handoff-release', 'handoff-resume',
+])
+export const TASKS_USAGE = [
+  '  cli-aimlock tasks <operation> <repositoryRoot> < task-message.json',
+  '  cli-aimlock tasks capabilities <repositoryRoot>',
+  `      Operations: ${TASK_OPERATIONS.join(', ')}.`,
+  '      Message routing preserves the original plan. A resume package does not execute work.',
+].join('\n')
+
+function taskCapabilities(capabilities) {
+  if (!capabilities || !Array.isArray(capabilities.operations)
+    || !capabilities.operationSchemas || typeof capabilities.operationSchemas !== 'object') {
+    fail('AIMLOCK_TASKS_CAPABILITIES_INVALID', 'coordinator task capabilities are invalid')
+  }
+  for (const operation of TASK_OPERATIONS) {
+    if (!capabilities.operations.includes(operation) || !Object.hasOwn(capabilities.operationSchemas, operation)) {
+      fail('AIMLOCK_TASKS_OPERATION_UNAVAILABLE', `coordinator task operation is unavailable: ${operation}`)
+    }
+  }
+  return { operations: [...TASK_OPERATIONS], operationSchemas: Object.fromEntries(
+    TASK_OPERATIONS.map((operation) => [operation, capabilities.operationSchemas[operation]]),
+  ) }
+}
+
+async function readTaskInput(input) {
+  const chunks = []
+  let byteLength = 0
+  for await (const chunk of input) {
+    if (typeof chunk !== 'string' && !(chunk instanceof Uint8Array)) {
+      fail('AIMLOCK_TASKS_INPUT_INVALID', 'task input must be UTF-8 JSON')
+    }
+    const bytes = Buffer.from(chunk)
+    byteLength += bytes.byteLength
+    if (byteLength > TASK_INPUT_MAX_BYTES) fail('AIMLOCK_TASKS_INPUT_TOO_LARGE', 'task input exceeds 1 MiB')
+    chunks.push(bytes)
+  }
+  if (byteLength === 0) fail('AIMLOCK_TASKS_INPUT_REQUIRED', 'task input is required on stdin')
+  let value
+  try { value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))) }
+  catch { fail('AIMLOCK_TASKS_INPUT_INVALID', 'task input must be valid UTF-8 JSON') }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    fail('AIMLOCK_TASKS_INPUT_INVALID', 'task input must be a JSON object')
+  }
+  return value
+}
+
+export async function dispatchTasks(args, dependencies = {}) {
+  const [operation, repositoryRoot] = args
+  if (args.length !== 2 || (operation !== 'capabilities' && !TASK_OPERATIONS.includes(operation))) {
+    fail('AIMLOCK_TASKS_USAGE_INVALID', TASKS_USAGE)
+  }
+  const execute = dependencies.executeCoordinatorOperation ?? executeCoordinatorOperation
+  const input = dependencies.input ?? stdin
+  if (operation === 'capabilities') return taskCapabilities(await execute(operation, repositoryRoot, {}))
+  return execute(operation, repositoryRoot, await readTaskInput(input))
+}
+
+export async function runTasksCli(args) {
+  try {
+    const result = await dispatchTasks(args)
+    stdout.write(JSON.stringify(result) + '\n')
+    if (result.status === 'blocked' || result.status === 'waiting') process.exitCode = 2
+    else if (result.status === 'failed' || result.status === 'uncertain') process.exitCode = 1
+  } catch (error) {
+    stdout.write(JSON.stringify({ status: 'failed', error: errorRecord(error) }) + '\n')
+    process.exitCode = 1
+  }
+}
+
+function sourceIdentity(input) {
+  const identity = {}
+  for (const field of ['taskId', 'agentId', 'chainId']) {
+    if (typeof input?.[field] !== 'string' || !input[field].trim()) {
+      fail('AIMLOCK_TASKS_IDENTITY_REQUIRED', `task identity requires ${field}`)
+    }
+    identity[field] = input[field]
+  }
+  return identity
+}
+
+function receiptMatches(receipt, delivery) {
+  return receipt && typeof receipt === 'object'
+    && receipt.requestId === delivery.requestId && receipt.targetTaskId === delivery.targetTaskId
+    && typeof receipt.receiptId === 'string' && receipt.receiptId.length > 0
+}
+
+async function deliveryStatus(execute, root, source, delivery) {
+  const status = await execute('message-status', root, { ...source, requestId: delivery.requestId })
+  if (!status || !Object.hasOwn(status, 'receipt')) {
+    fail('AIMLOCK_TASKS_RECEIPT_INVALID', 'coordinator message status has no receipt field')
+  }
+  if (status.receipt !== null && !receiptMatches(status.receipt, delivery)) {
+    fail('AIMLOCK_TASKS_RECEIPT_INVALID', 'coordinator receipt does not match the target delivery')
+  }
+  return status.receipt
+}
+
+async function awaitHostDelivery(adapter, delivery, timeoutMs) {
+  let timer
+  const deadline = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(Object.assign(new Error(
+      `host delivery timed out after ${timeoutMs} ms; the actual delivery was not canceled`,
+    ), { code: 'AIMLOCK_TASKS_DELIVERY_TIMEOUT' })), timeoutMs)
+  })
+  try {
+    return await Promise.race([Promise.resolve().then(() => adapter.deliver(delivery)), deadline])
+  } finally { clearTimeout(timer) }
+}
+
+async function deliverTaskMessage(root, source, delivery, adapter, execute, timeoutMs) {
+  const recorded = await deliveryStatus(execute, root, source, delivery)
+  if (recorded) return { requestId: delivery.requestId, status: 'accepted', receipt: recorded, recovered: true }
+  const claim = await execute('message-delivery-start', root, { ...source, requestId: delivery.requestId })
+  if (!claim || typeof claim.claimed !== 'boolean'
+    || (claim.claimed && (typeof claim.attemptId !== 'string' || !claim.attemptId))) {
+    fail('AIMLOCK_TASKS_DELIVERY_CLAIM_INVALID', 'coordinator delivery claim is invalid')
+  }
+  if (!claim.claimed) {
+    const receipt = await deliveryStatus(execute, root, source, delivery)
+    if (receipt) return { requestId: delivery.requestId, status: 'accepted', receipt, recovered: true }
+    fail('AIMLOCK_TASKS_DELIVERY_UNCERTAIN', 'delivery was already attempted; query its receipt before any further action')
+  }
+  let delivered
+  let deliveryError
+  try { delivered = await awaitHostDelivery(adapter, { ...delivery, attemptId: claim.attemptId }, timeoutMs) }
+  catch (error) { deliveryError = errorRecord(error) }
+  const receipt = await deliveryStatus(execute, root, source, delivery)
+  if (!receipt) {
+    const detail = deliveryError ? `: ${deliveryError.message}` : ''
+    fail('AIMLOCK_TASKS_DELIVERY_UNCERTAIN', `target acceptance has not been recorded${detail}`)
+  }
+  if (!deliveryError && (!receiptMatches(delivered, delivery) || delivered.status !== 'accepted'
+    || delivered.receiptId !== receipt.receiptId)) {
+    fail('AIMLOCK_TASKS_RECEIPT_INVALID', 'adapter receipt does not match the recorded target acceptance')
+  }
+  return { requestId: delivery.requestId, status: 'accepted', receipt, recovered: Boolean(deliveryError),
+    ...(deliveryError ? { deliveryError } : {}) }
+}
+
+async function reportDeliveryFailure(root, source, delivery, error, execute, failures) {
+  const failure = errorRecord(error)
+  failures.push({ requestId: delivery.requestId, stage: 'delivery', error: failure })
+  try {
+    await execute('message-delivery-report', root, { ...source, requestId: delivery.requestId,
+      errorCode: typeof failure.code === 'string' ? failure.code : 'AIMLOCK_TASKS_DELIVERY_FAILED',
+      errorMessage: failure.message })
+  } catch (reportError) {
+    failures.push({ requestId: delivery.requestId, stage: 'delivery-report', error: errorRecord(reportError) })
+  }
+}
+
+/** A host adapter delivers messages; only the coordinator may issue durable acceptance receipts. */
+export async function handleTaskMessage(root, input, adapter, { deliveryTimeoutMs = TASK_DELIVERY_TIMEOUT_MS } = {}) {
+  if (!adapter || typeof adapter.deliver !== 'function' || typeof adapter.continueTask !== 'function') {
+    fail('AIMLOCK_TASKS_ADAPTER_REQUIRED', 'host adapter requires deliver and continueTask functions')
+  }
+  if (!Number.isSafeInteger(deliveryTimeoutMs) || deliveryTimeoutMs <= 0
+    || deliveryTimeoutMs > MAX_TASK_DELIVERY_TIMEOUT_MS) {
+    fail('AIMLOCK_TASKS_TIMEOUT_INVALID', 'deliveryTimeoutMs must be a positive integer within the timer limit')
+  }
+  const source = sourceIdentity(input)
+  const execute = executeCoordinatorOperation
+  const routed = await execute('message-route', root, input)
+  if (!routed || !Array.isArray(routed.deliveries)
+    || Object.keys(source).some((field) => routed.source?.[field] !== source[field])) {
+    fail('AIMLOCK_TASKS_ROUTE_INVALID', 'coordinator message route does not match the source task')
+  }
+  const deliveries = []
+  const failures = []
+  for (const delivery of routed.deliveries) {
+    if (delivery.status !== 'pending-delivery') continue
+    try { deliveries.push(await deliverTaskMessage(root, source, delivery, adapter, execute, deliveryTimeoutMs)) }
+    catch (error) { await reportDeliveryFailure(root, source, delivery, error, execute, failures) }
+  }
+  let continuation = null
+  let continuationDispatched = false
+  try {
+    continuation = await execute('task-resume', root, source)
+    if (!continuation || typeof continuation.canContinue !== 'boolean'
+      || Object.keys(source).some((field) => continuation[field] !== source[field])) {
+      fail('AIMLOCK_TASKS_RESUME_INVALID', 'coordinator resume package does not match the original task')
+    }
+    if (continuation.canContinue) {
+      await adapter.continueTask(continuation)
+      continuationDispatched = true
+    }
+  } catch (error) { failures.push({ requestId: null, stage: 'continuation', error: errorRecord(error) }) }
+  return { status: failures.length ? 'failed' : continuationDispatched ? 'continued' : 'waiting',
+    messageId: routed.messageId, requests: routed.requests, deliveries, continuation,
+    continuationDispatched, failures }
+}

package/brain-client.mjs

@@ -1,3 +1,7 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { loadOfficialSkillContext } from './installer.mjs'
+import { prepareOfficialSkillUse, withUpgradeMetadata } from './official-skill-update.mjs'
 import { createHash, randomUUID } from 'node:crypto'
 import { readFile, writeFile } from 'node:fs/promises'
 import { inspectBrainTarget, brainStateDirectory, saveBrainRequest } from './brain-client-files.mjs'
@@ -38,6 +42,14 @@ function exact(value, keys, label) {
 
 export async function invokeBrain(operation, input, dependencies = {}) {
   if (!OPERATIONS.has(operation)) throw new Error('Unknown Brain operation')
+  let upgrade = null
+  if (operation !== 'status') {
+    const context = loadOfficialSkillContext(dirname(fileURLToPath(import.meta.url)))
+    const prepared = await prepareOfficialSkillUse(context, 'brain-client.mjs', dependencies)
+    if (prepared.module !== null) return withUpgradeMetadata(
+      await prepared.module.invokeBrain(operation, input, dependencies), prepared.upgrade)
+    upgrade = prepared.upgrade
+  }
   const endpoint = dependencies.endpoint ?? BRAIN_ENDPOINT
   const context = { endpoint, displayName: 'Brain planning' }
   const environment = dependencies.environment ?? process.env
@@ -68,7 +80,7 @@ export async function invokeBrain(operation, input, dependencies = {}) {
   if (payload.plan !== null && (payload.plan?.schemaVersion !== PLAN_SCHEMA
     || payload.plan.planId !== payload.planId || !HASH_PATTERN.test(payload.planDigest)
     || brainClientDigest(payload.plan) !== payload.planDigest)) throw new Error('Brain response plan digest is invalid')
-  return payload
+  return upgrade === null ? payload : withUpgradeMetadata(payload, upgrade)
 }
 
 export async function prepareBrainRequest(root, specification) {

package/broker-account-storage.mjs

@@ -0,0 +1,135 @@
+import { execFile } from 'node:child_process'
+import { lstat, mkdir, readFile, rm } from 'node:fs/promises'
+import { dirname, join, parse, resolve, win32 } from 'node:path'
+import { userInfo } from 'node:os'
+import { promisify } from 'node:util'
+import { randomUUID } from 'node:crypto'
+
+const runFile = promisify(execFile)
+const DIRECTORY_MODE = 0o700
+const FILE_MODE = 0o600
+const SYSTEM_SID = 'S-1-5-18'
+const ACL_SID_ALIASES = Object.freeze({ SY: SYSTEM_SID, WD: 'S-1-1-0', BA: 'S-1-5-32-544',
+  BU: 'S-1-5-32-545', AU: 'S-1-5-11', CO: 'S-1-3-0', CG: 'S-1-3-1', AN: 'S-1-5-7' })
+const SID_PATTERN = /^S-1-(?:[0-9]+-)*[0-9]+$/
+const ACL_TIMEOUT_MS = 15_000
+
+export function currentAccountHome() {
+  const home = userInfo().homedir
+  if (typeof home !== 'string' || !parse(home).root) throw new Error('The current account has no absolute home directory')
+  return home
+}
+
+export async function assertAccountAncestors(path, platform = process.platform) {
+  const paths = platform === 'win32' ? win32 : { dirname, resolve, parse }
+  let current = paths.resolve(path)
+  const ancestors = []
+  while (current !== paths.parse(current).root) {
+    ancestors.unshift(current)
+    current = paths.dirname(current)
+  }
+  for (const ancestor of ancestors) {
+    let status
+    try { status = await lstat(ancestor) } catch (error) {
+      if (error.code === 'ENOENT') continue
+      throw error
+    }
+    if (status.isSymbolicLink() || !status.isDirectory()) throw new Error('Account storage cannot traverse symlink or non-directory parents')
+  }
+}
+
+function aclText(bytes) {
+  return bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe
+    ? bytes.subarray(2).toString('utf16le') : bytes.toString('utf8')
+}
+
+export function windowsAclEntries(text) {
+  const descriptor = text.split(/\r?\n/).find(line => line.startsWith('D:'))
+  if (!descriptor) throw new Error('Windows ACL descriptor is missing')
+  const entries = [...descriptor.matchAll(/\(([^()]*)\)/g)].map(match => {
+    const fields = match[1].split(';')
+    if (fields.length !== 6) throw new Error('Windows ACL entry is invalid')
+    return { type: fields[0], flags: fields[1], rights: fields[2], sid: fields[5] }
+  })
+  if (!entries.length) throw new Error('Windows ACL cannot be empty')
+  return { descriptor, entries }
+}
+
+export function assertRestrictedWindowsAcl(text, ownerSid) {
+  const { descriptor, entries } = windowsAclEntries(text)
+  if (!descriptor.startsWith('D:P') || entries.length !== 2) throw new Error('Windows account ACL must be protected and grant only the user and SYSTEM')
+  const expected = new Set([ownerSid, SYSTEM_SID])
+  for (const entry of entries) {
+    const sid = Object.hasOwn(ACL_SID_ALIASES, entry.sid) ? ACL_SID_ALIASES[entry.sid] : entry.sid
+    if (entry.type !== 'A' || !['FA', '0x1f01ff'].includes(entry.rights)
+      || entry.flags.replaceAll('OI', '').replaceAll('CI', '') !== '' || !expected.delete(sid)) {
+      throw new Error('Windows account ACL contains unexpected access')
+    }
+  }
+  if (expected.size) throw new Error('Windows account ACL is missing the user or SYSTEM')
+}
+
+async function windowsOwnerSid(run) {
+  const result = await run('whoami.exe', ['/user', '/fo', 'csv', '/nh'], { windowsHide: true, timeout: ACL_TIMEOUT_MS })
+  const candidates = result.stdout.match(/S-1-(?:[0-9]+-)*[0-9]+/g)
+  if (candidates === null || candidates.length !== 1 || !SID_PATTERN.test(candidates[0])) throw new Error('Current Windows account SID could not be verified')
+  return candidates[0]
+}
+
+async function readWindowsAcl(path, run) {
+  const temporary = join(dirname(path), '.acl-' + randomUUID() + '.txt')
+  try {
+    await run('icacls.exe', [path, '/save', temporary, '/q'], { windowsHide: true, timeout: ACL_TIMEOUT_MS })
+    return aclText(await readFile(temporary))
+  } finally {
+    try { await rm(temporary) } catch (error) { if (error.code !== 'ENOENT') throw error }
+  }
+}
+
+async function protectWindowsPath(path, directory, dependencies) {
+  const run = dependencies.execFile === undefined ? runFile : dependencies.execFile
+  const owner = await windowsOwnerSid(run)
+  const flags = directory ? '(OI)(CI)F' : 'F'
+  await run('icacls.exe', [path, '/inheritance:r', '/grant:r', '*' + owner + ':' + flags,
+    '*' + SYSTEM_SID + ':' + flags], { windowsHide: true, timeout: ACL_TIMEOUT_MS })
+  const { entries } = windowsAclEntries(await readWindowsAcl(path, run))
+  for (const entry of entries) {
+    const sid = Object.hasOwn(ACL_SID_ALIASES, entry.sid) ? ACL_SID_ALIASES[entry.sid] : entry.sid
+    if (entry.type === 'A' && [owner, SYSTEM_SID].includes(sid)) continue
+    if (!SID_PATTERN.test(sid)) throw new Error('Unexpected Windows ACL trustee')
+    await run('icacls.exe', [path, entry.type === 'D' ? '/remove:d' : '/remove:g', '*' + sid],
+      { windowsHide: true, timeout: ACL_TIMEOUT_MS })
+  }
+  assertRestrictedWindowsAcl(await readWindowsAcl(path, run), owner)
+}
+
+export async function protectAccountPath(path, directory, dependencies = {}) {
+  const platform = dependencies.platform === undefined ? process.platform : dependencies.platform
+  await assertAccountAncestors(dirname(path), platform)
+  const status = await lstat(path)
+  if (status.isSymbolicLink() || (directory ? !status.isDirectory() : !status.isFile())) throw new Error('Account storage object has an unsafe type')
+  if (platform === 'win32') return protectWindowsPath(path, directory, dependencies)
+  const mode = directory ? DIRECTORY_MODE : FILE_MODE
+  if (status.uid !== process.getuid() || (status.mode & 0o777) !== mode) throw new Error('Account storage must be owned by the current account with restricted permissions')
+}
+
+export async function ensureAccountDirectory(path, dependencies = {}) {
+  const platform = dependencies.platform === undefined ? process.platform : dependencies.platform
+  await assertAccountAncestors(path, platform)
+  await mkdir(path, { recursive: true, mode: DIRECTORY_MODE })
+  await protectAccountPath(path, true, dependencies)
+}
+
+export async function verifyAccountPath(path, dependencies = {}) {
+  const platform = dependencies.platform === undefined ? process.platform : dependencies.platform
+  await assertAccountAncestors(dirname(path), platform)
+  const status = await lstat(path)
+  if (!status.isFile() || status.isSymbolicLink()) throw new Error('Credential must be a regular account file')
+  if (platform !== 'win32') {
+    if (status.uid !== process.getuid() || (status.mode & 0o777) !== FILE_MODE) throw new Error('Credential must be owned by the account with mode 0600')
+    return
+  }
+  const run = dependencies.execFile === undefined ? runFile : dependencies.execFile
+  const owner = await windowsOwnerSid(run)
+  assertRestrictedWindowsAcl(await readWindowsAcl(path, run), owner)
+}

package/broker-credentials.mjs

@@ -0,0 +1,125 @@
+import { constants } from 'node:fs'
+import { lstat, open, rename, rm } from 'node:fs/promises'
+import { currentAccountHome, ensureAccountDirectory, protectAccountPath, verifyAccountPath } from './broker-account-storage.mjs'
+import { isAbsolute, join, resolve, win32 } from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+const TOKEN_FILE_ENV = 'CLITAX_BRAIN_CLIENT_TOKEN_FILE'
+const TOKEN_FILE_VERSION = 'member-brain.client-token-file/1.0'
+const TOKEN_FILE_MAX_BYTES = 16_384
+const AUTH_SCHEME = 'BrainClient'
+const TOKEN_ENDPOINT = 'https://cli.tax/api/v1/telemetry/skill-usage'
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/
+const TOKEN_MODE = 0o600
+
+export function accountBrokerDirectory(environment, platform = process.platform, home = currentAccountHome()) {
+  if (platform === 'win32') {
+    if (typeof environment.LOCALAPPDATA !== 'string' || !win32.isAbsolute(environment.LOCALAPPDATA)) {
+      throw new Error('LOCALAPPDATA must identify the current account directory')
+    }
+    const relative = win32.relative(home, environment.LOCALAPPDATA)
+    if (relative === '..' || relative.startsWith('..\\') || win32.isAbsolute(relative)) throw new Error('LOCALAPPDATA must belong to the current account home')
+    return win32.join(environment.LOCALAPPDATA, 'CLI.Tax', 'broker')
+  }
+  if (!isAbsolute(home)) throw new Error('Account home directory must be absolute')
+  return platform === 'darwin' ? join(home, 'Library', 'Application Support', 'CLI.Tax', 'broker')
+    : join(home, '.local', 'share', 'CLI.Tax', 'broker')
+}
+
+export function brainClientTokenPath(environment, platform = process.platform, home = currentAccountHome()) {
+  const configured = environment[TOKEN_FILE_ENV]
+  const directory = accountBrokerDirectory(environment, platform, home)
+  if (configured === undefined) return platform === 'win32'
+    ? win32.join(directory, 'credential.json') : join(directory, 'credential.json')
+  if (typeof configured !== 'string' || !configured.trim()) throw new Error(TOKEN_FILE_ENV + ' must be an absolute path')
+  const candidate = configured.trim()
+  if (platform !== 'win32') {
+    if (!isAbsolute(candidate)) throw new Error(TOKEN_FILE_ENV + ' must be absolute and independent of the project directory')
+    return resolve(candidate)
+  }
+  if (!win32.isAbsolute(candidate)) throw new Error('Windows Brain Client token file path must be absolute')
+  const path = win32.resolve(candidate), relative = win32.relative(directory, path)
+  if (relative === '..' || relative.startsWith('..\\') || win32.isAbsolute(relative)) {
+    throw new Error('Windows Brain Client token file must be inside its account broker directory')
+  }
+  return path
+}
+
+export function validateBrainClientCredential(value, endpoint = TOKEN_ENDPOINT) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join(',') !== 'authorizationScheme,endpoint,schemaVersion,token') {
+    throw new Error('Brain Client credential has unknown or missing fields')
+  }
+  if (value.schemaVersion !== TOKEN_FILE_VERSION || value.authorizationScheme !== AUTH_SCHEME
+    || value.endpoint !== TOKEN_ENDPOINT || new URL(endpoint).origin !== new URL(TOKEN_ENDPOINT).origin
+    || typeof value.token !== 'string' || !TOKEN_PATTERN.test(value.token)) {
+    throw new Error('Brain Client token file authority is invalid')
+  }
+  return value
+}
+
+function parseCredential(source) {
+  if (Buffer.byteLength(source) > TOKEN_FILE_MAX_BYTES) throw new Error('Brain Client credential exceeds the size limit')
+  let parsed
+  try { parsed = JSON.parse(source) } catch { throw new Error('Brain Client credential must contain valid JSON') }
+  return validateBrainClientCredential(parsed)
+}
+
+function assertRestrictedFile(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) || status.uid !== currentUserId || (status.mode & 0o777) !== TOKEN_MODE) {
+    throw new Error('Brain Client token file must be owned by the current user with mode 0600')
+  }
+}
+
+export async function brainClientAuthorization(context, environment, dependencies = {}) {
+  const platform = dependencies.platform === undefined ? process.platform : dependencies.platform
+  const path = brainClientTokenPath(environment, platform, dependencies.homeDirectory === undefined ? currentAccountHome() : dependencies.homeDirectory)
+  const inspect = dependencies.lstat === undefined ? lstat : dependencies.lstat
+  const openFile = dependencies.open === undefined ? open : dependencies.open
+  const currentUserId = platform === 'win32' ? null : (dependencies.getuid === undefined ? process.getuid : dependencies.getuid)()
+  let status
+  try { status = await inspect(path) } catch (error) {
+    if (error.code === 'ENOENT') throw new Error('Brain Client credential is not configured; copy the authenticated setup from CLI.Tax and run configure with JSON stdin')
+    throw error
+  }
+  if (status.isSymbolicLink()) throw new Error('Brain Client token file cannot be a symlink')
+  const verifyPath = dependencies.verifyPath === undefined ? verifyAccountPath : dependencies.verifyPath
+  await verifyPath(path, { ...dependencies, platform })
+  const handle = await openFile(path, constants.O_RDONLY | (platform === 'win32' ? 0 : constants.O_NOFOLLOW))
+  try {
+    assertRestrictedFile(await handle.stat(), platform, currentUserId)
+    const value = validateBrainClientCredential(parseCredential(await handle.readFile('utf8')), context.endpoint)
+    return AUTH_SCHEME + ' ' + value.token
+  } finally { await handle.close() }
+}
+
+export async function configureBrainClientCredential(source, environment = process.env, dependencies = {}) {
+  const credential = parseCredential(source)
+  const platform = dependencies.platform === undefined ? process.platform : dependencies.platform
+  const home = dependencies.homeDirectory === undefined ? currentAccountHome() : dependencies.homeDirectory
+  const directory = accountBrokerDirectory(environment, platform, home)
+  await ensureAccountDirectory(directory, { ...dependencies, platform })
+  const path = join(directory, 'credential.json')
+  try { await protectAccountPath(path, false, { ...dependencies, platform }) }
+  catch (error) { if (error.code !== 'ENOENT') throw error }
+  const temporary = join(directory, 'credential-' + randomUUID() + '.json')
+  const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL
+    | (platform === 'win32' ? 0 : constants.O_NOFOLLOW), TOKEN_MODE)
+  try {
+    await handle.writeFile(JSON.stringify(credential) + '\n')
+    await handle.sync()
+  } finally { await handle.close() }
+  try {
+    await protectAccountPath(temporary, false, { ...dependencies, platform })
+    await rename(temporary, path)
+    await protectAccountPath(path, false, { ...dependencies, platform })
+  } catch (error) {
+    try { await rm(temporary) } catch (cleanupError) { if (cleanupError.code !== 'ENOENT') throw cleanupError }
+    throw error
+  }
+  return { configured: true, path, scope: 'current-account', requiresEnvironmentOverrideRemoval: environment[TOKEN_FILE_ENV] !== undefined }
+}