cli-aimlock 7.0.33 → 7.0.35

package/aimlock-local-runner.mjs

@@ -31,7 +31,7 @@ import { assertChainNotSuspended } from './aimlock-coordination.mjs'
 
 const execFile = promisify(execFileCallback)
 const BUDGET_SCHEMA = 'aimlock.read-budget/1.0'
-const CONFIRMATION_SCHEMA = 'confirm-protocol.answer/1.0'
+const CONFIRMATION_SCHEMA = 'confirm-protocol.skill.response/1.0'
 const MAX_DISCOVERED_FILES = 1_000
 const MAX_SOURCE_BYTES = 1_048_576
 const TOKEN_ESTIMATE_ALGORITHM = 'utf8-bytes-div-4-ceil'
@@ -52,6 +52,20 @@ const schema = (required, properties) => ({ type: 'object', additionalProperties
 const stringSchema = { type: 'string', minLength: 1 }
 const stringArraySchema = { type: 'array', items: stringSchema }
 const objectValueSchema = { type: 'object' }
+const BUDGET_ADDITIONS_SCHEMA = schema(['files', 'tokenEstimate', 'durationMs'], {
+  files: { type: 'integer', minimum: 0 }, tokenEstimate: { type: 'integer', minimum: 0 }, durationMs: { type: 'integer', minimum: 0 },
+})
+const BUDGET_CONFIRMATION_SCHEMA = schema(['schemaVersion', 'requestId', 'status', 'callbackRequest', 'auditEntry', 'nextStep'], {
+  schemaVersion: { const: 'confirm-protocol.skill.response/1.0' }, requestId: stringSchema, status: { const: 'succeeded' },
+  callbackRequest: schema(['operation', 'payload'], { operation: { const: 'budget-extend' },
+    payload: schema(['chainId', 'additions', 'requestId', 'answer'], { chainId: stringSchema,
+      additions: BUDGET_ADDITIONS_SCHEMA, requestId: stringSchema, answer: { const: 'approve' } }) }),
+  auditEntry: schema(['schemaVersion', 'auditId', 'requestId', 'actorId', 'question', 'answer', 'remembered', 'risk', 'answeredAt'], {
+    schemaVersion: { const: 'confirm.audit-entry/1.0' }, auditId: stringSchema, requestId: stringSchema, actorId: stringSchema,
+    question: stringSchema, answer: { const: 'approve' }, remembered: { type: 'boolean' }, risk: { const: 'low' },
+    answeredAt: { type: 'string', format: 'date-time' },
+  }), nextStep: objectValueSchema,
+})
 const LOCAL_OPERATION_SCHEMAS = Object.freeze({
   capabilities: schema([], {}),
   probe: schema(['goal', 'targetHints'], { goal: stringSchema, targetHints: stringArraySchema,
@@ -64,7 +78,7 @@ const LOCAL_OPERATION_SCHEMAS = Object.freeze({
   'budget-read': schema(['chainId', 'path'], { chainId: stringSchema, path: stringSchema }),
   'budget-status': schema(['chainId'], { chainId: stringSchema }),
   'budget-extend': schema(['chainId', 'confirmation', 'additions'], {
-    chainId: stringSchema, confirmation: objectValueSchema, additions: objectValueSchema }),
+    chainId: stringSchema, confirmation: BUDGET_CONFIRMATION_SCHEMA, additions: BUDGET_ADDITIONS_SCHEMA }),
   'gate-issue': schema(['chainId', 'snapshotRoot', 'receipt', 'contract', 'nodes', 'coordinationRequired'], {
     chainId: stringSchema, snapshotRoot: stringSchema, receipt: objectValueSchema,
     contract: objectValueSchema, nodes: { type: 'array', items: objectValueSchema },
@@ -331,23 +345,53 @@ async function readFileWithinBudget(input) {
   })
 }
 
+async function checkCachedReadAccess(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  const chainId = identifier(input.chainId, 'chainId')
+  await assertChainNotSuspended({ repositoryRoot: root, chainId })
+  const budgetPath = managedPath(root, 'runs', chainId, 'read-budget.json')
+  return withFileLock(budgetPath, async () => {
+    const { state } = await readBudget(root, chainId)
+    const path = safeRelativePath(input.path)
+    const budget = budgetView(state)
+    if (budget.remainingDurationMs === 0) fail('AIMLOCK_DECISION_REQUIRED', 'read deadline exhausted')
+    if (budget.remainingTokenEstimate === 0) fail('AIMLOCK_DECISION_REQUIRED', 'read token estimate budget exhausted')
+    if (!state.uniqueFiles.includes(path)) fail('AIMLOCK_CACHE_UNCHARGED', 'cached source was not read by this chain')
+    return { schemaVersion: LOCAL_SCHEMA, path, budget }
+  })
+}
+
 async function readBudgetStatus(input) {
   const root = await repositoryRoot(input.repositoryRoot)
   return budgetView((await readBudget(root, input.chainId)).state)
 }
 
-async function extendReadBudget(input) {
-  const root = await repositoryRoot(input.repositoryRoot)
+function confirmedBudgetExtension(input) {
   const confirmation = input.confirmation
-  if (!confirmation || confirmation.schemaVersion !== CONFIRMATION_SCHEMA
-    || confirmation.confirmed !== true || confirmation.risk !== 'low'
-    || !identifier(confirmation.confirmationId, 'confirmationId')) {
-    fail('AIMLOCK_CONFIRMATION_REQUIRED', 'a low-risk confirmation receipt is required')
+  const audit = confirmation?.auditEntry
+  const callback = confirmation?.callbackRequest
+  const payload = callback?.payload
+  const fields = ['files', 'tokenEstimate', 'durationMs']
+  if (!confirmation || confirmation.schemaVersion !== CONFIRMATION_SCHEMA || confirmation.status !== 'succeeded'
+    || audit?.schemaVersion !== 'confirm.audit-entry/1.0' || audit.risk !== 'low' || audit.answer !== 'approve'
+    || typeof audit.remembered !== 'boolean' || !Number.isFinite(Date.parse(audit.answeredAt))
+    || callback?.operation !== 'budget-extend' || payload?.answer !== 'approve'
+    || payload.chainId !== input.chainId || payload.requestId !== audit.requestId
+    || !payload.additions || fields.some((key) => payload.additions[key] !== input.additions?.[key])) {
+    fail('AIMLOCK_CONFIRMATION_REQUIRED', 'a low-risk Confirm Protocol interaction-answer bound to this chain and exact additions is required')
   }
+  identifier(audit.actorId, 'actorId')
+  identifier(audit.requestId, 'requestId')
+  return identifier(audit.auditId, 'auditId')
+}
+
+async function extendReadBudget(input) {
+  const root = await repositoryRoot(input.repositoryRoot)
+  const confirmationId = confirmedBudgetExtension(input)
   const additions = input.additions
-  if (!additions || !Number.isInteger(additions.files) || additions.files < 0
-    || !Number.isInteger(additions.tokenEstimate) || additions.tokenEstimate < 0
-    || !Number.isInteger(additions.durationMs) || additions.durationMs < 0
+  if (!additions || !Number.isSafeInteger(additions.files) || additions.files < 0
+    || !Number.isSafeInteger(additions.tokenEstimate) || additions.tokenEstimate < 0
+    || !Number.isSafeInteger(additions.durationMs) || additions.durationMs < 0
     || additions.files + additions.tokenEstimate + additions.durationMs === 0) {
     fail('AIMLOCK_EXTENSION_INVALID', 'budget additions must contain a positive integer increase')
   }
@@ -356,6 +400,9 @@ async function extendReadBudget(input) {
   return withFileLock(budgetPath, async () => {
     const authority = await readBudget(root, chainId)
     const state = authority.state
+    if (state.extensions.some((item) => item.confirmationId === confirmationId)) {
+      fail('AIMLOCK_CONFIRMATION_REPLAYED', 'this budget confirmation has already been applied')
+    }
     const updated = {
       ...state,
       maxFiles: state.maxFiles + additions.files,
@@ -363,14 +410,14 @@ async function extendReadBudget(input) {
         ? null : (state.maxTokenEstimate ?? 0) + additions.tokenEstimate,
       maxDurationMs: state.maxDurationMs + additions.durationMs,
       extensions: [...state.extensions, {
-        confirmationId: confirmation.confirmationId,
+        confirmationId,
         additions,
         at: new Date().toISOString(),
       }],
     }
     await atomicJson(authority.path, updated)
     await appendAudit(root, { event: 'read-budget-extended', chainId,
-      confirmationId: confirmation.confirmationId, additions })
+      confirmationId, additions })
     return budgetView(updated)
   })
 }
@@ -395,6 +442,7 @@ export {
   LOCAL_SCHEMA,
   PASS_SCHEMA,
   READ_BUDGETS,
+  checkCachedReadAccess,
   extendReadBudget,
   guardedWriteFile,
   initializeReadBudget,

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

package/brain-client-files.mjs

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, open, realpath, mkdir, writeFile, readFile } from 'node:fs/promises'
+import { relative, resolve, isAbsolute } from 'node:path'
+
+const MAX_FILE_BYTES = 2_000_000
+const MAX_CONTEXT_CHARACTERS = 6_000
+export function validateBrainPath(path) {
+  if (typeof path !== 'string' || !path || path.length > 500 || isAbsolute(path)
+    || /[\\:\u0000-\u001f\u007f]/.test(path) || path.split('/').some((part) => !part || part === '.' || part === '..')
+    || /(?:^|\/)(?:\.env(?:\.[^/]*)?|\.git|\.ssh|node_modules|id_rsa|id_ed25519)(?:\/|$)|\.(?:pem|p12|key)$/i.test(path)) {
+    throw new Error('Brain target must be a safe relative project file')
+  }
+}
+
+async function checkedAncestors(root, path) {
+  const canonicalRoot = await realpath(root)
+  let current = canonicalRoot
+  for (const part of path.split('/').slice(0, -1)) {
+    current = resolve(current, part)
+    let status
+    try { status = await lstat(current) }
+    catch (error) { if (error.code === 'ENOENT') continue; throw error }
+    if (!status.isDirectory() || status.isSymbolicLink()) throw new Error('Brain target has an unsafe parent')
+  }
+  return canonicalRoot
+}
+
+export async function inspectBrainTarget(root, path) {
+  validateBrainPath(path)
+  const canonicalRoot = await checkedAncestors(root, path)
+  const target = resolve(canonicalRoot, path)
+  let status
+  try { status = await lstat(target) }
+  catch (error) { if (error.code === 'ENOENT') return { path, sha256: null, context: '' }; throw error }
+  if (!status.isFile() || status.isSymbolicLink() || status.size > MAX_FILE_BYTES) throw new Error('Brain target is not a bounded regular file')
+  const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const opened = await file.stat()
+    if (opened.dev !== status.dev || opened.ino !== status.ino || !opened.isFile()) throw new Error('Brain target changed during inspection')
+    const bytes = Buffer.alloc(MAX_FILE_BYTES + 1)
+    let length = 0
+    while (length < bytes.length) {
+      const chunk = await file.read(bytes, length, bytes.length - length, length)
+      if (!chunk.bytesRead) break
+      length += chunk.bytesRead
+    }
+    if (length > MAX_FILE_BYTES) throw new Error('Brain target exceeds the file limit')
+    const final = await lstat(target)
+    const inside = relative(canonicalRoot, await realpath(target))
+    if (inside === '..' || inside.startsWith('../') || isAbsolute(inside)
+      || final.dev !== opened.dev || final.ino !== opened.ino || final.mtimeMs !== opened.mtimeMs) {
+      throw new Error('Brain target changed during inspection')
+    }
+    const contents = bytes.subarray(0, length)
+    if (contents.includes(0)) throw new Error('Brain context must be a text file')
+    return { path, sha256: createHash('sha256').update(contents).digest('hex'),
+      context: contents.toString('utf8').slice(0, MAX_CONTEXT_CHARACTERS) }
+  } finally { await file.close() }
+}
+
+export async function brainStateDirectory(root, parts) {
+  const canonicalRoot = await realpath(root)
+  let directory = canonicalRoot
+  for (const part of ['.aimlock', ...parts]) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(part) && part !== '.aimlock') throw new Error('Brain state path is invalid')
+    directory = resolve(directory, part)
+    try { await mkdir(directory, { mode: 0o700 }) }
+    catch (error) { if (error.code !== 'EEXIST') throw error }
+    const status = await lstat(directory)
+    if (!status.isDirectory() || status.isSymbolicLink()) throw new Error('Brain state directory is unsafe')
+  }
+  return directory
+}
+
+export async function saveBrainRequest(root, request, digest) {
+  const directory = await brainStateDirectory(root, ['brain-requests'])
+  const path = resolve(directory, request.requestId + '.json')
+  try { await writeFile(path, JSON.stringify(request), { mode: 0o600, flag: 'wx' }) }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error
+    const status = await lstat(path)
+    if (!status.isFile() || status.isSymbolicLink() || status.size > MAX_FILE_BYTES) throw new Error('Saved Brain request is unsafe')
+    if (digest(JSON.parse(await readFile(path, 'utf8'))) !== digest(request)) {
+      throw new Error('Brain request ID is already bound to different local input')
+    }
+  }
+}

package/brain-client.mjs

@@ -0,0 +1,170 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { readFile, writeFile } from 'node:fs/promises'
+import { inspectBrainTarget, brainStateDirectory, saveBrainRequest } from './brain-client-files.mjs'
+export { inspectBrainTarget } from './brain-client-files.mjs'
+import { resolve } from 'node:path'
+import { brainClientAuthorization, transportFailureCode } from './broker.mjs'
+import { executeCommand } from './aimlock-chain-process.mjs'
+
+export const BRAIN_ENDPOINT = 'https://cli.tax/api/v1/brain'
+const REQUEST_SCHEMA = 'brain.planning-request/1.0'
+const RESPONSE_SCHEMA = 'brain.planning-response/1.0'
+const PLAN_SCHEMA = 'brain.execution-plan/1.0'
+const MAX_INPUT_BYTES = 256_000
+const TIMEOUT_MS = 120_000
+const HASH_PATTERN = /^[0-9a-f]{64}$/
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const OPERATIONS = new Set(['plan', 'status', 'report', 'validate'])
+
+export function canonicalBrainJson(value) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value)
+  if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value)
+  if (Array.isArray(value)) return '[' + value.map(canonicalBrainJson).join(',') + ']'
+  if (!value || typeof value !== 'object') throw new Error('Brain protocol value must be JSON')
+  return '{' + Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+    .map(([key, item]) => JSON.stringify(key) + ':' + canonicalBrainJson(item)).join(',') + '}'
+}
+
+export function brainClientDigest(value) {
+  return createHash('sha256').update(canonicalBrainJson(value)).digest('hex')
+}
+
+function exact(value, keys, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some((key) => !keys.includes(key))
+    || keys.some((key) => !Object.hasOwn(value, key))) throw new Error(label + ' has invalid fields')
+}
+
+export async function invokeBrain(operation, input, dependencies = {}) {
+  if (!OPERATIONS.has(operation)) throw new Error('Unknown Brain operation')
+  const endpoint = dependencies.endpoint ?? BRAIN_ENDPOINT
+  const context = { endpoint, displayName: 'Brain planning' }
+  const environment = dependencies.environment ?? process.env
+  const authorization = await brainClientAuthorization(context, environment, dependencies.credentialAccess)
+  const body = JSON.stringify({ operation, input })
+  if (Buffer.byteLength(body) > MAX_INPUT_BYTES) throw new Error('Brain request exceeds the size limit')
+  let response
+  try {
+    response = await (dependencies.request ?? fetch)(endpoint, {
+      method: 'POST', redirect: 'error', headers: { Authorization: authorization, 'Content-Type': 'application/json' },
+      body, signal: AbortSignal.timeout(TIMEOUT_MS),
+    })
+  } catch (error) {
+    throw new Error('Brain transport failed (' + transportFailureCode(error) + '); query status before submitting another plan')
+  }
+  const payload = await readBrainResponse(response)
+  if (!response.ok) {
+    const code = typeof payload?.code === 'string' ? payload.code : 'BRAIN_HTTP_ERROR'
+    throw new Error('Brain request failed: HTTP ' + response.status + ' (' + code + ')')
+  }
+  if (payload?.schemaVersion !== RESPONSE_SCHEMA || !UUID_PATTERN.test(payload.planId)
+    || !UUID_PATTERN.test(payload.requestId)
+    || !['planning', 'ready', 'reported', 'verified', 'failed', 'expired'].includes(payload.status)) {
+    throw new Error('Brain response envelope is invalid')
+  }
+  if ((operation === 'plan' && payload.requestId !== input.requestId)
+    || (operation !== 'plan' && (input.planId ? payload.planId !== input.planId : payload.requestId !== input.requestId))) throw new Error('Brain response identity does not match')
+  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
+}
+
+export async function prepareBrainRequest(root, specification) {
+  exact(specification, ['requestId', 'goal', 'maxChangedLines', 'targets', 'checks'], 'Brain specification')
+  if (!UUID_PATTERN.test(specification.requestId) || typeof specification.goal !== 'string' || !specification.goal.trim()
+    || !Number.isSafeInteger(specification.maxChangedLines) || specification.maxChangedLines < 1
+    || !Array.isArray(specification.targets) || !specification.targets.length || specification.targets.length > 64
+    || new Set(specification.targets).size !== specification.targets.length) throw new Error('Brain specification is invalid')
+  const targets = []
+  for (const path of specification.targets) targets.push(await inspectBrainTarget(root, path))
+  return { schemaVersion: REQUEST_SCHEMA, ...specification, targets }
+}
+
+export function validateBrainHandoff(request, response) {
+  const plan = response.plan
+  if (response.status !== 'ready' || plan?.schemaVersion !== PLAN_SCHEMA || response.requestId !== request.requestId
+    || response.planId !== plan.planId || brainClientDigest(plan) !== response.planDigest) throw new Error('Brain plan is not ready')
+  const targets = request.targets.map(({ path, sha256 }) => ({ path, sha256 }))
+  if (brainClientDigest(plan.targets) !== brainClientDigest(targets)
+    || brainClientDigest(plan.checks) !== brainClientDigest(request.checks)
+    || brainClientDigest(plan.contract.allowedPaths) !== brainClientDigest(targets.map((target) => target.path))
+    || plan.contract.maxChangedLines !== request.maxChangedLines || plan.contract.allowDeleteFiles !== false) {
+    throw new Error('Brain plan changed the local authorization')
+  }
+  if (!Array.isArray(plan.nodes) || !plan.nodes.length
+    || plan.nodes.some((node) => !targets.some((target) => target.path === node.path))) throw new Error('Brain plan targets are invalid')
+  return plan
+}
+
+export async function collectBrainReport(root, handoff, environment = process.env) {
+  exact(handoff, ['request', 'response'], 'Brain handoff')
+  const plan = validateBrainHandoff(handoff.request, handoff.response)
+  if (typeof environment.PATH !== 'string' || !environment.PATH) throw new Error('Execution PATH is required')
+  const reportId = randomUUID()
+  const directory = await brainStateDirectory(root, ['brain-reports', reportId])
+  const evidence = []
+  for (const check of plan.checks) {
+    exact(check, ['id', 'executable', 'args', 'timeoutMs'], 'Brain check')
+    if (typeof check.id !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(check.id)
+      || typeof check.executable !== 'string' || !check.executable
+      || !Array.isArray(check.args) || check.args.some((arg) => typeof arg !== 'string')
+      || !Number.isSafeInteger(check.timeoutMs) || check.timeoutMs < 1_000 || check.timeoutMs > 3_600_000) {
+      throw new Error('Brain check command is invalid')
+    }
+    const result = await executeCommand(root, {
+      executable: check.executable, args: check.args, timeoutMs: check.timeoutMs,
+      environment: { PATH: environment.PATH }, workingDirectory: '.', evidenceKind: 'test',
+    }, reportId + ':' + check.id, async () => {})
+    const digest = (value) => createHash('sha256').update(value).digest('hex')
+    evidence.push({ checkId: check.id, exitCode: result.status !== 'succeeded' && result.exitCode === 0 ? null : result.exitCode, durationMs: result.durationMs,
+      stdoutSha256: digest(result.stdout), stderrSha256: digest(result.stderr) })
+    await writeFile(resolve(directory, check.id + '.json'), JSON.stringify(result), { mode: 0o600 })
+    if (result.status === 'uncertain') throw new Error('Check process cleanup is unconfirmed; execution stopped')
+  }
+  const files = []
+  for (const node of plan.nodes) {
+    const actual = await inspectBrainTarget(root, node.path)
+    if (actual.sha256 === null) throw new Error('Planned file is missing: ' + node.path)
+    files.push({ path: node.path, sha256: actual.sha256 })
+  }
+  return { planId: plan.planId, planDigest: handoff.response.planDigest, reportId, files, evidence }
+}
+
+export async function runBrainCli(args) {
+  const [operation, root, file] = args
+  if (!['plan', 'check', 'status', 'validate'].includes(operation) || !root || !file || args.length !== 3) {
+    throw new Error('Usage: cli-aimlock brain <plan|check|status|validate> <repositoryRoot> <jsonFile>')
+  }
+  const source = await readFile(resolve(file), 'utf8')
+  if (Buffer.byteLength(source) > MAX_INPUT_BYTES) throw new Error('Brain input file exceeds the size limit')
+  const input = JSON.parse(source)
+  if (operation === 'plan') {
+    const request = await prepareBrainRequest(root, input)
+    await saveBrainRequest(root, request, brainClientDigest)
+    const response = await invokeBrain('plan', request)
+    if (response.status === 'ready') validateBrainHandoff(request, response)
+    process.stdout.write(JSON.stringify({ request, response }) + '\n')
+    return
+  }
+  const payload = operation === 'check' ? await collectBrainReport(root, input) : input
+  const response = await invokeBrain(operation === 'check' ? 'report' : operation, payload)
+  process.stdout.write(JSON.stringify(response) + '\n')
+}
+
+async function readBrainResponse(response) {
+  if (!response.body) throw new Error('Brain response body is missing')
+  const reader = response.body.getReader()
+  const chunks = []
+  let bytes = 0
+  try {
+    for (;;) {
+      const chunk = await reader.read()
+      if (chunk.done) break
+      bytes += chunk.value.byteLength
+      if (bytes > MAX_INPUT_BYTES) { await reader.cancel(); throw new Error('Brain response exceeds the size limit') }
+      chunks.push(Buffer.from(chunk.value))
+    }
+  } finally { reader.releaseLock() }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}

package/cli.mjs

@@ -4,6 +4,8 @@ import { dirname, resolve } from 'node:path'
 import { cwd, stdin, stdout } from 'node:process'
 import { createInterface } from 'node:readline/promises'
 import { fileURLToPath } from 'node:url'
+import { runBrainCli } from './brain-client.mjs'
+import { CHAIN_USAGE, runChainCli } from './aimlock-chain-cli.mjs'
 import { defaultUsage, dispatchOfficialSkillCli, runIntakeHandshake } from './installer.mjs'
 import {
   LOCAL_CAPABILITIES,
@@ -90,7 +92,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)
+  return usage.replace(COMMON_RUN_USAGE, AIMLOCK_RUN_USAGE) + '\n\n' + CHAIN_USAGE
 }
 
 async function collectApplicability(input, output) {
@@ -184,7 +186,11 @@ async function dispatchLocal(args) {
 
 const cliPath = fileURLToPath(import.meta.url)
 if (process.argv[1] && realpathSync(resolve(process.argv[1])) === cliPath) {
-  if (process.argv[2] === 'local') {
+  if (process.argv[2] === 'brain') {
+    await runBrainCli(process.argv.slice(3))
+  } else if (process.argv[2] === 'chain') {
+    await runChainCli(process.argv.slice(3))
+  } else if (process.argv[2] === 'local') {
     try {
       console.log(JSON.stringify(await dispatchLocal(process.argv.slice(3))))
     } catch (error) {

package/package.json

@@ -3,13 +3,15 @@
     "cli-aimlock": "./cli.mjs"
   },
   "dependencies": {
-    "cli-swarm": "7.0.33"
+    "cli-swarm": "7.0.35"
   },
   "description": "Aimlock skill installer for CLI.Tax: lock a user request into an executable aim and route Blueprint, Swarm, and Calctool.",
   "exports": {
     "./coordination": "./aimlock-coordination.mjs",
     "./local-runner": "./aimlock-local-runner.mjs",
-    "./runtime": "./aimlock-runtime.mjs"
+    "./runtime": "./aimlock-runtime.mjs",
+    "./chain-executor": "./aimlock-chain-executor.mjs",
+    "./brain-client": "./brain-client.mjs"
   },
   "files": [
     "cli.mjs",
@@ -18,12 +20,23 @@
     "README.md",
     "skill/SKILL.md",
     "skill/skill.json",
+    "aimlock-chain-model.mjs",
+    "aimlock-chain-store.mjs",
+    "aimlock-chain-process.mjs",
+    "aimlock-chain-calls.mjs",
+    "aimlock-chain-human.mjs",
+    "aimlock-chain-executor.mjs",
+    "aimlock-chain-cli.mjs",
+    "aimlock-chain-outcomes.mjs",
     "aimlock-context-map.mjs",
     "aimlock-coordination.mjs",
     "aimlock-local-fs.mjs",
     "aimlock-local-gate.mjs",
     "aimlock-local-runner.mjs",
-    "aimlock-runtime.mjs"
+    "aimlock-runtime.mjs",
+    "brain-client.mjs",
+    "brain-client-files.mjs",
+    "skill/references/chain-executor.md"
   ],
   "license": "UNLICENSED",
   "name": "cli-aimlock",
@@ -32,5 +45,5 @@
     "url": "https://github.com/88208555/aimlock-clitax.git"
   },
   "type": "module",
-  "version": "7.0.33"
+  "version": "7.0.35"
 }

package/skill/SKILL.md

@@ -5,7 +5,7 @@ description: "Aimlock 仅用于大型、深度、跨模块、高风险、需要
 
 # Aimlock Skill
 
-Package version: v7.0.33
+Package version: v7.0.35
 
 Endpoint: https://cli.tax/R3mQ8kWpXn
 
@@ -161,3 +161,16 @@ Aimlock returns the protocol; it does not start a timer.
 - 本地 CLI 不提供手工评分或评语提交命令，人类不得选择技能分数或填写技能评价；日常聊天不属于评价协议。
 
 调用示例：`npx cli-aimlock@latest invoke <operation> '<JSON对象>'`。IDE 集成可向 `npx cli-aimlock@latest broker` 的 stdin 发送 `{"operation":"capabilities","input":{}}`。
+
+## 宿主持久执行
+
+使用 [chain-executor.md](references/chain-executor.md) 的显式 `chain init/resume/status/answer` 协议驱动本地持久步骤。`run` 的需求采集、远端 `nextStep` 与 `completed` 均不等于已执行。只有真实 broker/协调器/命令结果及绑定证据能推进；未答复人工裁决禁止恢复，发送后结果不确定禁止自动重发。CLI 终端不提供 OS 隔离或独立可信 runner。
+
+## 服务端沙箱规划与 IDE 执行
+
+1. 用户在模型设置中启用自己的模型地址、API Key 和模型名后，规划优先使用该配置；未启用个人模型时使用官方模型并执行有限套餐额度。个人模型失败必须明确报错，禁止自动切换模型或消耗官方额度。
+2. 准备请求 JSON，明确 requestId、目标、允许文件、最大修改行数和批准的检查命令；运行 `npx cli-aimlock@latest brain plan <repositoryRoot> <request.json>`。服务端调用模型规划，再由隔离沙箱编译结构化计划；保留返回的 request/response 交接包。
+3. 审查返回计划的允许范围、基线哈希和检查命令；完成现有 Aimlock 范围、快照和写入门禁后，由 IDE 修改代码。计划本身不授权扩大范围，不替代写入门禁。
+4. 运行 `npx cli-aimlock@latest brain check <repositoryRoot> <handoff.json>` 执行批准的检查并回传产物哈希和结果。普通 IDE 回传属于 client-reported，不能据此声称可信验证通过。
+5. 只有已批准的可信 runner 生成与本次计划和报告绑定的签名收据后，才运行 `npx cli-aimlock@latest brain validate <repositoryRoot> <validation.json>`。没有可信收据时保持已回传状态，不伪造验证。
+6. 请求发送后结果不确定时，先用 `brain status <repositoryRoot> <status.json>` 按 requestId 或 planId 查询；禁止自动重发规划或重复计费。

package/skill/references/chain-executor.md

@@ -0,0 +1,90 @@
+# 持久 CLI 链执行器
+
+服务端技能仍是无状态协议；宿主通过显式计划执行真实步骤，将状态写入仓库的 `.aimlock/executions/<chainId>/state.json`。旧 `run` 仍负责适用性判断与需求采集，生成需求文件不等于执行技能链。
+
+## 命令
+
+```sh
+cli-aimlock chain init /absolute/repository < execution-plan.json
+cli-aimlock chain resume /absolute/repository my-chain
+cli-aimlock chain status /absolute/repository my-chain
+cli-aimlock chain answer /absolute/repository my-chain human-actor
+```
+
+`init` 只验证并保存不可变计划与已安装技能元数据，不触发 HTTP。
+`resume` 按依赖顺序执行尚未完成的步骤；已成功步骤不会重复调用。
+`status` 只读取本地状态。等待时退出码为 2，失败/结果不确定为 1。
+`answer` 必须在真实交互终端使用，读取展示后的选项 ID；拒绝重定向答案。actorId 是本地审计标签，不代表服务端已验证真人身份。
+
+## 显式计划
+
+```json
+{
+  "schemaVersion": "aimlock.execution-plan/1.0",
+  "chainId": "my-chain",
+  "skills": [],
+  "steps": [
+    {
+      "stepId": "test",
+      "kind": "command",
+      "skillId": null,
+      "operation": "exec",
+      "input": {
+        "executable": "/usr/local/bin/node",
+        "args": ["--test"],
+        "workingDirectory": ".",
+        "timeoutMs": 600000,
+        "evidenceKind": "test",
+        "environment": {}
+      },
+      "dependsOn": [],
+      "bindings": []
+    }
+  ]
+}
+```
+
+每步必须提供全部七个字段；Confirm interaction-request 可额外声明 continueWhen。其它额外字段均拒绝。支持三种 kind：
+
+- `skill`：skillId 必须在 skills 中声明 `{skillId, packageRoot}`；packageRoot 指向已安装 npm 技能包。复用受限 broker 的真实 HTTP、requestId 校验、自动评价和提交回执；不读取或输出令牌。初始化后的包元数据变化会阻止恢复。
+- `coordinator`：skillId=null，operation 使用 Swarm 本地接口。`dependency-wait` 会实际登记并驱动 `wait-for-event`/tick，保存唤醒包；不是仅返回 nextStep。`resolve-human` 禁止从计划注入。
+- `command`：skillId=null、operation=exec，按显式 executable/args 执行无 shell 的真实进程；workingDirectory 限于仓库，timeoutMs 为 1..3600000，输出上限 1 MiB，超限/超时/非零退出显式失败。命令输入不得动态绑定；environment 必须显式提供字符串字典，spawn 不继承宿主环境，拒绝令牌、私钥、授权等保留变量。使用非绝对 executable 时应显式声明 PATH。示例路径需改成实际 Node 安装位置。evidenceKind 为 test/build/lint/security/benchmark。
+
+步骤必须按拓扑顺序排列；依赖只能引用前面已声明的步骤。运行时仅从已成功步骤的实际输出取值，忽略服务端 nextStep/completed 字段，不据此调用隐含步骤。
+
+绑定使用 RFC 6901 JSON Pointer：
+```json
+{
+  "stepId": "dispatch",
+  "kind": "skill",
+  "skillId": "swarm",
+  "operation": "dispatch",
+  "input": { "tasks": null },
+  "dependsOn": ["compile"],
+  "bindings": [
+    { "stepId": "compile", "source": "/machineTasks/tasks", "target": "/tasks" }
+  ]
+}
+```
+
+这里 compile 必须是计划中真实调用 Blueprint compile-inline 的步骤，并在 skills 声明两个安装包。source 指向协议 output 本身，不含 broker 外层包装。目标键必须事先在 input 中声明；缺失值、非法指针、循环依赖均报错。Blueprint 的 blueprintSha256 与 criterionId 原样绑定；不要重算或改变前缀。
+
+## 等待、恢复与证据
+
+- 持久记录 pending/running/waiting/blocked/failed/uncertain/succeeded、调用 ID、实际 requestId、输入摘要、结果、反馈回执和错误。网络发送前先保存 requestId。
+- 事件到达才记为依赖满足。死亡、放弃和超时不冒充事件成功；人工选中恢复时保留 `resolved-by-human`、原唤醒原因与 Confirm 审计。
+- 遇到 Swarm 高风险裁决，必须在 skills 声明 confirm-protocol 包。宿主真实调用 interaction-request，保存待答状态。resume 不会代答；answer 读取终端输入、真实调用 interaction-answer，校验问题/答案/回调绑定后才调用 resolve-human。
+- 普通 Confirm 步骤还必须声明结构化继续条件，例如步骤字段 `continueWhen: {"answer":"yes"}`。协议没有通用“同意”的 option ID；不依据 label 推测授权。真人答案未匹配或未声明条件时，下游保持 blocked；choice/input/multi 同样须明确条件。
+- Validator 的协议 succeeded 不代表验收通过：verdict=incomplete/blocked、空或失败执行证据、sandbox-run 等 pending-execution 描述均阻塞链。原协议结果与回执仍保留，不能冒充已执行测试。
+- 普通技能 blocked/failed 保持阻塞/失败，不自动重试。发送后断线、无法校验回执、执行中断等不确定结果禁止自动重发；应先人工核查外部效果，再制定新计划。已登记的事件等待可恢复轮询，不重新声明等待。
+- 本地命令提供 `cli.tax.test-evidence/1.0`：真实 exitCode、durationMs、stdout/stderr 摘要；runner=local、producer=local-cli-process、independentRunnerVerified=false。可把 output.evidence 绑定到 Blueprint acceptance-report 的逐项 results；报告对账不等于独立可信执行。
+- 同链正常 completed 任务不再封锁活跃同伴；全部终态仍封锁。失败/回收任务必须显式注册 supersedesTaskId，保留原任务历史、范围与约束，并先处理人工裁决；任意新任务不构成失败豁免。
+- 人工选中 active 任务后，同链未选中的 human-decision 停放任务可继续保持 blocked；旧 lease 不能写入，因为写入联锁仍要求对应 taskId 为 active。未决裁决继续阻止读取与写入。
+
+## 边界
+
+共享 chainId 的只读预算不是智能体身份隔离。命令步骤是用户已声明的本地进程调用，不是操作系统沙箱，不拦截任意外部进程或其文件读取，也不保证其他命令自动遵守 Aimlock 写入门禁。修改源码的受控调用仍必须走 guarded-write 和有效快照/租约。没有隐式 ContextBase 调用；不要省略其适用的预算链参数。没有独立桌面壳或 OS 弹窗承诺；当前 Confirm 宿主是 CLI 终端。
+
+排队锁恢复：允许排队的请求必须显式给出正整数 `queueTimeoutMs`，与授锁后 `ttlSeconds` 独立；`lock-acquire` 返回 queued 后保存 queueId 并挂起本步骤；`resume` 运行一次协调扫描后只查询 `lock-queue-status`，不会重放申请。只有同一任务、链、资源、路径及当前未过期租约全部匹配的真实 grant 才继续。仍在排队时返回包含 deadlineAt 的等待快照；到期后 tick 落账并返回 need-human/Confirm 请求，原队列阻断。本执行器不会把队列超时的人工恢复解释为已授锁；宿主需处理返回的确认，再提交新的显式申请。终止、过期、失配及旧版缺少 queue→grant 关联的授锁明确阻断，不推测归属。
+
+命令结束与进程回收分开记录：超时或输出超限后最多再等待 1 秒关闭输出管道。仍无法确认回收时返回 `uncertain` 和空执行证据，释放执行锁并禁止自动重放；这不证明脱离进程已停止。已启动子进程后落账失败同样按结果不确定记录。

package/skill/skill.json

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