cli-swarm 7.0.37 → 7.0.39

package/README.md

@@ -42,3 +42,17 @@ Brain Client 服务端在同一次 runtime 请求的事务中绑定真实响应
 仅在 TLS 握手前确定尚未发送 HTTP 请求时，broker 才允许最多 3 次连接尝试，并受总超时约束。请求发出后发生断线或响应中断，只用 GET 查询原 requestId 的服务端回执，禁止重发 POST；未取得有效回执时保留不确定状态，不得假定成功或继续依赖步骤。
 
 `npx cli-swarm@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/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 }
+}

package/broker.mjs

@@ -1,25 +1,17 @@
 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 { brainClientAuthorization } from './broker-credentials.mjs'
+import { prepareOfficialSkillUse, withUpgradeMetadata } from './official-skill-update.mjs'
+export { brainClientAuthorization, brainClientTokenPath } from './broker-credentials.mjs'
+export { LOOKUP_TIMEOUT_MS } from './official-skill-update.mjs'
 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
-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'])
@@ -48,84 +40,6 @@ function boundedInteger(value, label) {
   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)
@@ -205,6 +119,9 @@ export function authoritativeEvaluation(value, expected) {
 
 async function responsePayload(response, context, request) {
   const label = `${context.displayName} ${request.operation} response`
+  if (response.status === 401 || response.status === 403) {
+    throw new OfficialSkillResponseError(request, 'http-response', 'Brain Client authorization was rejected; copy the current authenticated setup from CLI.Tax and run configure again. Revoked credentials cannot renew themselves.')
+  }
   let payload
   try {
     payload = await response.json()
@@ -235,6 +152,9 @@ function invocationRequest(context, operation, input) {
 }
 
 export async function invokeOfficialSkill(context, operation, input, dependencies) {
+  const prepared = await prepareOfficialSkillUse(context, 'broker.mjs', dependencies)
+  if (prepared.module !== null) return withUpgradeMetadata(
+    await prepared.module.invokeOfficialSkill(prepared.context, operation, input, dependencies), prepared.upgrade)
   const environment = asObject(dependencies.environment, 'broker environment')
   if (typeof dependencies.request !== 'function') {
     throw new Error('broker request dependency is required')
@@ -252,14 +172,14 @@ export async function invokeOfficialSkill(context, operation, input, dependencie
     })
   } catch (error) {
     const failure = new OfficialSkillInvocationError(context, requestEnvelope, transportFailureCode(error), 'request', error?.transport)
-    return recoverTransportFailure(context, requestEnvelope, dependencies, authorization, failure)
+    return withUpgradeMetadata(await recoverTransportFailure(context, requestEnvelope, dependencies, authorization, failure), prepared.upgrade)
   }
   let payload
   try {
     payload = await responsePayload(response, context, requestEnvelope)
   } catch (error) {
     if (!(error instanceof OfficialSkillInvocationError)) throw error
-    return recoverTransportFailure(context, requestEnvelope, dependencies, authorization, error)
+    return withUpgradeMetadata(await recoverTransportFailure(context, requestEnvelope, dependencies, authorization, error), prepared.upgrade)
   }
   if (!response.ok || payload.ok !== true) {
     throw new OfficialSkillResponseError(requestEnvelope, 'http-response', `${context.displayName} ${operation} failed: HTTP ${response.status}`)
@@ -267,7 +187,7 @@ export async function invokeOfficialSkill(context, operation, input, dependencie
   try {
     const invocation = validateInvocationResponse(context, operation, payload, requestEnvelope)
     const transport = transportDiagnostics(response.transport)
-    return transport ? { ...invocation, transport } : invocation
+    return withUpgradeMetadata(transport ? { ...invocation, transport } : invocation, prepared.upgrade)
   } catch (error) {
     throw new OfficialSkillResponseError(requestEnvelope, 'response-validation',
       error instanceof Error ? error.message : 'Skill response validation failed')

package/installer-storage.mjs

@@ -0,0 +1,205 @@
+import { execFile } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { cp, lstat, mkdir, readdir, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { promisify } from 'node:util'
+import { assertAccountAncestors, currentAccountHome } from './broker-account-storage.mjs'
+
+const runFile = promisify(execFile)
+const INSTALL_META = 'install-meta.json'
+const MAX_SKILL_FILES = 256
+const GIT_TIMEOUT_MS = 8000
+
+function object(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(label + ' must be an object')
+  return value
+}
+
+export function readInstallMeta(target) {
+  const path = join(target, INSTALL_META)
+  if (!existsSync(path)) return null
+  return object(JSON.parse(readFileSync(path, 'utf8')), INSTALL_META)
+}
+
+export function installTarget(skillName, explicit, environment = process.env, workingDirectory = process.cwd()) {
+  if (explicit !== undefined) {
+    if (typeof explicit !== 'string' || !explicit.trim()) throw new Error('Install directory must be non-empty')
+    return resolve(explicit)
+  }
+  if (environment.CODEX_HOME !== undefined) {
+    if (typeof environment.CODEX_HOME !== 'string' || !isAbsolute(environment.CODEX_HOME)) throw new Error('CODEX_HOME must be absolute')
+    return join(environment.CODEX_HOME, 'skills', skillName)
+  }
+  return join(workingDirectory, '.codex', 'skills', skillName)
+}
+
+function contained(root, path) {
+  const inside = relative(root, path)
+  return inside === '' || (!inside.startsWith('..' + '/') && inside !== '..' && !isAbsolute(inside)
+    && !inside.startsWith('..' + '\\'))
+}
+
+function sameIdentity(meta, context) {
+  return meta.source === context.runtimeCode && meta.slug === context.skillName && meta.endpoint === context.endpoint
+    && typeof meta.version === 'string' && /^v?\d+\.\d+\.\d+$/.test(meta.version)
+    && typeof meta.packageVersion === 'string' && /^\d+\.\d+\.\d+$/.test(meta.packageVersion)
+}
+
+function newerVersion(installed, selected) {
+  const parts = version => {
+    if (typeof version !== 'string' || !/^v?\d+\.\d+\.\d+$/.test(version)) {
+      throw new Error('Managed skill comparison requires a semantic release version')
+    }
+    return version.replace(/^v/, '').split('.').map(value => BigInt(value))
+  }
+  const left = parts(installed), right = parts(selected)
+  const index = left.findIndex((part, position) => part !== right[position])
+  return index !== -1 && left[index] > right[index]
+}
+
+function assertNoManagedDowngrade(previous, context) {
+  if (previous !== null && (newerVersion(previous.version, context.skillVersion)
+    || newerVersion(previous.packageVersion, context.packageVersion))) {
+    throw new Error('The managed skill is newer than the selected release; refusing to downgrade its installation')
+  }
+}
+
+async function targetExists(path) {
+  try { return await lstat(path) } catch (error) { if (error.code === 'ENOENT') return null; throw error }
+}
+
+async function trackedSource(target) {
+  let current = dirname(target)
+  for (;;) {
+    if (await targetExists(join(current, '.git')) !== null) {
+      try {
+        const result = await runFile('git', ['-C', current, 'ls-files', '--', relative(current, target)],
+          { timeout: GIT_TIMEOUT_MS, maxBuffer: 1_048_576 })
+        return result.stdout.trim().length > 0
+      } catch { throw new Error('Cannot verify whether the install target contains repository source files') }
+    }
+    const parent = dirname(current)
+    if (parent === current) return false
+    current = parent
+  }
+}
+
+async function managedTarget(context, target, allowCreate) {
+  const path = resolve(target)
+  await assertAccountAncestors(dirname(path))
+  if (contained(resolve(context.packageRoot), path) || contained(path, resolve(context.packageRoot))) {
+    return { path, status: 'skipped', reason: 'package-source' }
+  }
+  const status = await targetExists(path)
+  if (status === null) return allowCreate ? { path, status: 'new', meta: null }
+    : { path, status: 'skipped', reason: 'not-installed' }
+  if (!status.isDirectory() || status.isSymbolicLink()) throw new Error('Installed skill target must be a regular directory')
+  if (await trackedSource(path)) return { path, status: 'skipped', reason: 'repository-source' }
+  const metaStatus = await targetExists(join(path, INSTALL_META))
+  if (metaStatus === null) return { path, status: 'skipped', reason: 'unmanaged' }
+  if (!metaStatus.isFile() || metaStatus.isSymbolicLink()) throw new Error('Install metadata must be a regular file')
+  if (process.platform !== 'win32' && (status.uid !== process.getuid() || metaStatus.uid !== process.getuid())) throw new Error('Managed skill installation must belong to the current account')
+  const meta = readInstallMeta(path)
+  if (!sameIdentity(meta, context)) return { path, status: 'skipped', reason: 'identity-mismatch' }
+  return { path, status: 'managed', meta }
+}
+
+async function verifySkillSource(directory, context) {
+  let files = 0
+  async function visit(path) {
+    const status = await lstat(path)
+    if (status.isSymbolicLink()) throw new Error('Skill package cannot contain symbolic links')
+    if (status.isDirectory()) {
+      for (const entry of await readdir(path)) await visit(join(path, entry))
+      return
+    }
+    if (!status.isFile() || ++files > MAX_SKILL_FILES) throw new Error('Skill package contains an unsupported or excessive file set')
+  }
+  await assertAccountAncestors(directory)
+  await visit(directory)
+  const skill = object(JSON.parse(readFileSync(join(directory, 'skill.json'), 'utf8')), 'skill.json')
+  if (skill.name !== context.skillName || skill.endpoint !== context.endpoint || skill.version !== context.skillVersion) {
+    throw new Error('Skill package documentation identity does not match the selected version')
+  }
+  const markdown = await lstat(join(directory, 'SKILL.md'))
+  if (!markdown.isFile() || markdown.size === 0) throw new Error('Skill package must contain its actual SKILL.md')
+}
+
+async function restoreInstallation(target, backup, placed, renamePath) {
+  if (placed) await rm(target, { recursive: true })
+  if (backup !== null) await renamePath(backup, target)
+}
+
+async function replaceInstallation(context, target, previous, dependencies) {
+  const renamePath = dependencies.rename === undefined ? rename : dependencies.rename
+  const suffix = randomUUID()
+  const stage = join(dirname(target), '.' + context.skillName + '.stage-' + suffix)
+  const backup = previous === null ? null : join(dirname(target), '.' + context.skillName + '.backup-' + suffix)
+  let moved = false, placed = false
+  await mkdir(stage, { mode: 0o700 })
+  try {
+    await verifySkillSource(context.skillDir, context)
+    for (const entry of await readdir(context.skillDir)) {
+      await cp(join(context.skillDir, entry), join(stage, entry), { recursive: true, force: false, errorOnExist: true })
+    }
+    await writeFile(join(stage, INSTALL_META), JSON.stringify({ source: context.runtimeCode, slug: context.skillName,
+      version: context.skillVersion, packageVersion: context.packageVersion, endpoint: context.endpoint,
+      installedAt: new Date().toISOString() }) + '\n', { flag: 'wx', mode: 0o600 })
+    await verifySkillSource(stage, context)
+    if (backup !== null) { await renamePath(target, backup); moved = true }
+    await renamePath(stage, target)
+    placed = true
+    return { path: target, status: previous === null ? 'installed' : 'updated',
+      previousVersion: previous === null ? null : previous.version, version: context.skillVersion,
+      documentationPath: join(target, 'SKILL.md'), backupPath: backup }
+  } catch (error) {
+    if (moved || placed) await restoreInstallation(target, moved ? backup : null, placed, renamePath)
+    throw error
+  } finally {
+    const remaining = await targetExists(stage)
+    if (remaining !== null) await rm(stage, { recursive: true })
+  }
+}
+
+export async function writeManagedSkill(context, target, options = {}) {
+  const allowCreate = options.allowCreate === true
+  const candidate = await managedTarget(context, target, allowCreate)
+  if (candidate.status === 'skipped') return candidate
+  assertNoManagedDowngrade(candidate.meta, context)
+  if (candidate.meta !== null && candidate.meta.version === context.skillVersion
+    && candidate.meta.packageVersion === context.packageVersion) {
+    await verifySkillSource(candidate.path, context)
+    return { path: candidate.path, status: 'current', version: context.skillVersion,
+      documentationPath: join(candidate.path, 'SKILL.md') }
+  }
+  await mkdir(dirname(candidate.path), { recursive: true })
+  await assertAccountAncestors(dirname(candidate.path))
+  const lock = join(dirname(candidate.path), '.' + context.skillName + '.install-lock')
+  try { await mkdir(lock, { mode: 0o700 }) } catch (error) {
+    if (error.code === 'EEXIST') throw new Error('Skill installation is already locked; inspect its pending update before retrying')
+    throw error
+  }
+  try {
+    const checked = await managedTarget(context, candidate.path, allowCreate)
+    if (checked.status === 'skipped') throw new Error('Skill installation ownership changed before update')
+    assertNoManagedDowngrade(checked.meta, context)
+    return await replaceInstallation(context, checked.path, checked.meta, options)
+  } finally { await rm(lock, { recursive: true }) }
+}
+
+export async function refreshManagedSkillCopies(context, dependencies = {}) {
+  const environment = dependencies.environment === undefined ? process.env : dependencies.environment
+  const home = dependencies.homeDirectory === undefined ? currentAccountHome() : dependencies.homeDirectory
+  const workingDirectory = dependencies.workingDirectory === undefined ? process.cwd() : dependencies.workingDirectory
+  if (!isAbsolute(home) || !isAbsolute(workingDirectory)) throw new Error('Account and project directories must be absolute')
+  const accountCodex = environment.CODEX_HOME === undefined ? join(home, '.codex') : environment.CODEX_HOME
+  if (typeof accountCodex !== 'string' || !isAbsolute(accountCodex) || !contained(home, accountCodex)) {
+    throw new Error('Automatic skill refresh requires CODEX_HOME inside the current account home')
+  }
+  const targets = [...new Set([join(workingDirectory, '.codex', 'skills', context.skillName),
+    join(accountCodex, 'skills', context.skillName)])]
+  const results = []
+  for (const target of targets) results.push(await writeManagedSkill(context, target, dependencies))
+  return results
+}