cli-aimlock 7.0.37 → 7.0.39

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/cli.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { TASKS_USAGE, runTasksCli } from './aimlock-tasks-cli.mjs'
 import { realpathSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { cwd, stdin, stdout } from 'node:process'
@@ -95,7 +96,7 @@ export function localAimlockApplicability(facts) {
 export function aimlockUsage(context) {
   const usage = defaultUsage(context)
   if (!usage.includes(COMMON_RUN_USAGE)) throw new Error('Shared CLI run usage contract changed')
-  return usage.replace(COMMON_RUN_USAGE, AIMLOCK_RUN_USAGE) + '\n\n' + CHAIN_USAGE
+  return usage.replace(COMMON_RUN_USAGE, AIMLOCK_RUN_USAGE) + '\n\n' + CHAIN_USAGE + '\n\n' + TASKS_USAGE
     + '\n\nRead-time renewal: local budget-auto-renew-request <repositoryRoot> prepares one Confirm Protocol approval;'
     + '\nlocal budget-auto-renew activates the approved chain/scope/policy; budget-auto-renew-stop revokes or completes it.'
 }
@@ -196,6 +197,8 @@ const cliPath = fileURLToPath(import.meta.url)
 if (process.argv[1] && realpathSync(resolve(process.argv[1])) === cliPath) {
   if (process.argv[2] === 'brain') {
     await runBrainCli(process.argv.slice(3))
+  } else if (process.argv[2] === 'tasks') {
+    await runTasksCli(process.argv.slice(3))
   } else if (process.argv[2] === 'chain') {
     await runChainCli(process.argv.slice(3))
   } else if (process.argv[2] === 'local') {

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
+}

package/installer.mjs

@@ -1,10 +1,14 @@
+import { latestOfficialSkillContext } from './official-skill-update.mjs'
+import { installTarget, writeManagedSkill } from './installer-storage.mjs'
+export { installTarget, readInstallMeta } from './installer-storage.mjs'
+import { configureBrainClientCredential } from './broker-credentials.mjs'
 /**
  * 八个官方技能共用这一份安装器。packages/*-cli/installer.mjs 必须与本文件字节一致。
  * 禁止第二套超时、第二套版本来源、第二套 bin 名。
  */
-import { existsSync, readFileSync } from 'node:fs'
-import { cp, mkdir, rm, writeFile } from 'node:fs/promises'
-import { dirname, join, resolve } from 'node:path'
+import { readFileSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
 import { stdin, stdout } from 'node:process'
 import { createInterface } from 'node:readline/promises'
 import { fileURLToPath } from 'node:url'
@@ -33,7 +37,6 @@ export {
 
 import { createBrokerTransport } from './broker-transport.mjs'
 
-const INSTALL_META = 'install-meta.json'
 const BROKER_STDIN_MAX_BYTES = 1_048_576
 
 function asObject(value, label) {
@@ -81,19 +84,6 @@ export function loadOfficialSkillContext(packageRoot) {
   }
 }
 
-export function readInstallMeta(target) {
-  const path = join(target, INSTALL_META)
-  if (!existsSync(path)) return null
-  return asObject(JSON.parse(readFileSync(path, 'utf8')), INSTALL_META)
-}
-
-export function installTarget(skillName, explicit) {
-  if (explicit) return resolve(explicit)
-  const codexHome = process.env.CODEX_HOME?.trim()
-  if (codexHome) return join(codexHome, 'skills', skillName)
-  return join(process.cwd(), '.codex', 'skills', skillName)
-}
-
 export async function fetchLatestVersion(context) {
   const request = createBrokerTransport({ environment: process.env })
   const response = await request(context.latestEndpoint, { signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS) })
@@ -105,51 +95,38 @@ export async function fetchLatestVersion(context) {
   }
 }
 
-export async function installOfficialSkill(context, explicit) {
-  const target = installTarget(context.skillName, explicit)
-  await mkdir(target, { recursive: true })
-  const previous = readInstallMeta(target)
-  await rm(join(target, 'references'), { recursive: true, force: true })
-  await cp(context.skillDir, target, { recursive: true, force: true })
-  const installed = asObject(JSON.parse(readFileSync(join(target, 'skill.json'), 'utf8')), 'installed skill.json')
-  const installedVersion = requiredString(installed.version, 'installed skill.json version')
-  await writeFile(join(target, INSTALL_META), `${JSON.stringify({
-    source: context.runtimeCode,
-    slug: context.skillName,
-    version: installedVersion,
-    packageVersion: context.packageVersion,
-    endpoint: context.endpoint,
-    installedAt: new Date().toISOString(),
-  }, null, 2)}\n`)
-  if (previous?.version && previous.version !== installedVersion) {
-    console.log(`${context.displayName} skill updated: ${target}`)
-    console.log(`  ${previous.version} → ${installedVersion}`)
-  } else {
-    console.log(`${context.displayName} skill installed: ${target} (${installedVersion})`)
-  }
-  console.log('Next: return to your IDE and state the goal. The agent reads the installed SKILL.md.')
+function writeInstallationResult(runtime, value) {
+  const line = JSON.stringify(value) + '\n'
+  if (runtime.writeOutput === undefined) process.stdout.write(line)
+  else runtime.writeOutput(line)
 }
 
-export async function checkOfficialSkill(context, explicit) {
-  const target = installTarget(context.skillName, explicit)
-  const current = readInstallMeta(target)
-  if (!current) {
-    console.log(`${context.displayName} skill is not installed. Run: npx ${context.npmName}@latest install`)
-    process.exitCode = 1
-    return
-  }
-  const installedVersion = requiredString(current.version, 'install-meta.json version')
-  const packageVersion = requiredString(current.packageVersion, 'install-meta.json packageVersion')
-  console.log(`Installed: ${installedVersion} (package ${packageVersion})`)
-  const latest = await fetchLatestVersion(context)
-  console.log(`Latest on cli.tax: ${latest.version}`)
-  if (installedVersion === latest.version) {
-    console.log('Up to date.')
-    return
-  }
-  console.log(`Update available: ${installedVersion} → ${latest.version}`)
-  console.log(`Run: npx ${context.npmName}@latest install`)
-  process.exitCode = 1
+function installationDependencies(dependencies) {
+  return dependencies === undefined ? brokerDependencies() : dependencies
+}
+
+export async function installOfficialSkill(context, explicit, dependencies) {
+  const runtime = installationDependencies(dependencies)
+  const selected = await latestOfficialSkillContext(context, runtime)
+  const environment = runtime.environment === undefined ? process.env : runtime.environment
+  const workingDirectory = runtime.workingDirectory === undefined ? process.cwd() : runtime.workingDirectory
+  const target = installTarget(selected.skillName, explicit, environment, workingDirectory)
+  const installed = await writeManagedSkill(selected, target, { ...runtime, allowCreate: true })
+  if (installed.status === 'skipped') throw new Error('Skill install refused: ' + installed.reason)
+  writeInstallationResult(runtime, { installed, reloadRequired: installed.status !== 'current' })
+  return installed
+}
+
+export async function checkOfficialSkill(context, explicit, dependencies) {
+  const runtime = installationDependencies(dependencies)
+  const selected = await latestOfficialSkillContext(context, runtime)
+  const environment = runtime.environment === undefined ? process.env : runtime.environment
+  const workingDirectory = runtime.workingDirectory === undefined ? process.cwd() : runtime.workingDirectory
+  const target = installTarget(selected.skillName, explicit, environment, workingDirectory)
+  const installed = await writeManagedSkill(selected, target, runtime)
+  if (installed.status === 'skipped') throw new Error('Skill check could not update its managed target: ' + installed.reason)
+  writeInstallationResult(runtime, { installed, reloadRequired: installed.status === 'updated' })
+  return installed
 }
 
 export function defaultUsage(context, extraLines) {
@@ -157,10 +134,12 @@ export function defaultUsage(context, extraLines) {
     `${context.npmName} — install and run the ${context.displayName} skill from CLI.Tax`,
     '',
     'Usage:',
+    '  configure < credential.json',
+    '      Store the Brain Client credential for this account; never put tokens in command arguments.',
     `  npx ${context.npmName}@latest install [directory]`,
     `      Install the ${context.displayName} skill for the current IDE.`,
     `  npx ${context.npmName}@latest check [directory]`,
-    '      Check whether the installed skill has a newer version.',
+    '      Check and atomically update an already managed skill to the current official release.',
     `  npx ${context.npmName}@latest run`,
     "      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>`,
@@ -169,7 +148,8 @@ export function defaultUsage(context, extraLines) {
     '      Read one {"operation":"...","input":{...}} request from JSON stdin.',
     `  npx ${context.npmName}@latest recover <operation> <requestId>`,
     '      Query an uncertain invocation without resending or charging again.',
-    'Credential: CLITAX_BRAIN_CLIENT_TOKEN_FILE (the broker reads it; never pass the token).',
+    'Credential: configure reads a token-file JSON document from stdin and stores it once for the current account.',
+    'An explicit CLITAX_BRAIN_CLIENT_TOKEN_FILE must be absolute. Revoked keys require a fresh authenticated copy from CLI.Tax.',
     `Endpoint: ${context.endpoint}`,
   ]
   if (extraLines?.length) lines.push('', ...extraLines)
@@ -270,7 +250,12 @@ export async function dispatchOfficialSkillCli(options) {
   const command = args[0] ?? 'help'
   const argument = args[1]
   try {
-    if (command === 'install') await installOfficialSkill(context, argument)
+    if (command === 'configure') {
+      if (args.length !== 1) throw new Error('configure accepts credentials only through JSON stdin')
+      const configured = await configureBrainClientCredential(await readBrokerSource(stdin))
+      process.stdout.write(JSON.stringify(configured) + '\n')
+    }
+    else if (command === 'install') await installOfficialSkill(context, argument)
     else if (command === 'check') await checkOfficialSkill(context, argument)
     else if (command === 'run') await options.runCommand(context)
     else if (command === 'recover') await runBrokerRecovery(context, args)