cli-aimlock 7.0.32 → 7.0.34

package/aimlock-chain-model.mjs

@@ -0,0 +1,187 @@
+import { fail, identifier, sha256 } from './aimlock-local-fs.mjs'
+
+export const PLAN_SCHEMA = 'aimlock.execution-plan/1.0'
+export const STATE_SCHEMA = 'aimlock.execution-state/1.0'
+export const TERMINAL_STEP_STATUSES = new Set(['succeeded', 'failed', 'uncertain'])
+const STEP_KINDS = new Set(['skill', 'coordinator', 'command'])
+const FORBIDDEN_KEYS = new Set(['__proto__', 'prototype', 'constructor'])
+const EVIDENCE_KINDS = new Set(['test', 'build', 'lint', 'security', 'benchmark'])
+const MAX_STEPS = 256
+const MAX_TIMEOUT_MS = 3_600_000
+const ENVIRONMENT_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/
+const RESERVED_ENVIRONMENT = /(?:TOKEN|SECRET|PRIVATE.?KEY|SIGNING|BROKER|CREDENTIAL|AUTHORIZATION|PASSWORD)|^(?:SSH_AUTH_SOCK|SSH_AGENT_PID|NODE_OPTIONS|LD_PRELOAD|DYLD_.*)$/i
+
+export function object(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('AIMLOCK_CHAIN_INPUT_INVALID', label + ' must be an object')
+  return value
+}
+
+function exact(value, keys, label) {
+  object(value, label)
+  if (Object.keys(value).some((key) => !keys.includes(key)) || keys.some((key) => !Object.hasOwn(value, key))) {
+    fail('AIMLOCK_CHAIN_INPUT_INVALID', label + ' contains missing or unknown fields')
+  }
+}
+
+export function nonempty(value, label) {
+  if (typeof value !== 'string' || !value.trim()) fail('AIMLOCK_CHAIN_INPUT_INVALID', label + ' must be a non-empty string')
+  return value
+}
+
+function pointerParts(pointer) {
+  if (pointer === '') return []
+  if (typeof pointer !== 'string' || !pointer.startsWith('/') || /~(?:[^01]|$)/.test(pointer)) {
+    fail('AIMLOCK_CHAIN_POINTER_INVALID', 'JSON Pointer must use RFC 6901 escaping')
+  }
+  const parts = pointer.slice(1).split('/').map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+  if (parts.some((part) => FORBIDDEN_KEYS.has(part))) fail('AIMLOCK_CHAIN_POINTER_INVALID', 'unsafe property in JSON Pointer')
+  return parts
+}
+
+export function readPointer(value, pointer) {
+  let cursor = value
+  for (const part of pointerParts(pointer)) {
+    if (!cursor || typeof cursor !== 'object' || !Object.hasOwn(cursor, part)) {
+      fail('AIMLOCK_CHAIN_BINDING_MISSING', 'JSON Pointer has no recorded value: ' + pointer)
+    }
+    cursor = cursor[part]
+  }
+  return structuredClone(cursor)
+}
+
+function writePointer(value, pointer, replacement) {
+  const parts = pointerParts(pointer)
+  if (!parts.length) return object(structuredClone(replacement), 'bound input')
+  let cursor = value
+  for (const part of parts.slice(0, -1)) {
+    if (!cursor || typeof cursor !== 'object' || !Object.hasOwn(cursor, part)) {
+      fail('AIMLOCK_CHAIN_BINDING_MISSING', 'binding target parent does not exist: ' + pointer)
+    }
+    cursor = cursor[part]
+  }
+  const last = parts.at(-1)
+  if (!cursor || typeof cursor !== 'object' || !Object.hasOwn(cursor, last)) {
+    fail('AIMLOCK_CHAIN_BINDING_MISSING', 'binding target must be declared in input: ' + pointer)
+  }
+  cursor[last] = structuredClone(replacement)
+  return value
+}
+
+function validateCommand(input) {
+  exact(input, ['executable', 'args', 'workingDirectory', 'timeoutMs', 'evidenceKind', 'environment'], 'command input')
+  nonempty(input.executable, 'executable')
+  nonempty(input.workingDirectory, 'workingDirectory')
+  object(input.environment, 'command environment')
+  for (const [key, value] of Object.entries(input.environment)) {
+    if (!ENVIRONMENT_KEY.test(key) || RESERVED_ENVIRONMENT.test(key) || typeof value !== 'string' || value.includes('\u0000')) {
+      fail('AIMLOCK_CHAIN_ENVIRONMENT_INVALID', 'command environment contains an invalid or reserved credential variable')
+    }
+  }
+  if (!input.executable.includes('/') && !input.executable.includes('\\')) {
+    nonempty(input.environment.PATH, 'environment.PATH for executable lookup')
+  }
+  if (!Array.isArray(input.args) || input.args.some((arg) => typeof arg !== 'string')) {
+    fail('AIMLOCK_CHAIN_INPUT_INVALID', 'command args must be strings')
+  }
+  if (!Number.isSafeInteger(input.timeoutMs) || input.timeoutMs < 1 || input.timeoutMs > MAX_TIMEOUT_MS
+    || !EVIDENCE_KINDS.has(input.evidenceKind)) fail('AIMLOCK_CHAIN_INPUT_INVALID', 'command limits or evidence kind are invalid')
+}
+
+function validateStep(step, seen, skills) {
+  const keys = ['stepId', 'kind', 'skillId', 'operation', 'input', 'dependsOn', 'bindings']
+  exact(step, Object.hasOwn(step, 'continueWhen') ? [...keys, 'continueWhen'] : keys, 'step')
+  if (Object.hasOwn(step, 'continueWhen')) {
+    exact(step.continueWhen, ['answer'], 'continueWhen')
+    const answer = step.continueWhen.answer
+    if ((typeof answer !== 'string' || !answer.trim())
+      && (!Array.isArray(answer) || !answer.length || answer.some((item) => typeof item !== 'string' || !item.trim()))) {
+      fail('AIMLOCK_CHAIN_INPUT_INVALID', 'continueWhen.answer must be a non-empty structured answer')
+    }
+    if (step.kind !== 'skill' || step.skillId !== 'confirm-protocol' || step.operation !== 'interaction-request') {
+      fail('AIMLOCK_CHAIN_INPUT_INVALID', 'continueWhen applies only to an explicit Confirm interaction-request step')
+    }
+  }
+  identifier(step.stepId, 'stepId')
+  if (seen.has(step.stepId) || !STEP_KINDS.has(step.kind)) fail('AIMLOCK_CHAIN_INPUT_INVALID', 'duplicate stepId or invalid kind')
+  object(step.input, 'step input')
+  if (!Array.isArray(step.dependsOn) || new Set(step.dependsOn).size !== step.dependsOn.length
+    || step.dependsOn.some((id) => !seen.has(id))) {
+    fail('AIMLOCK_CHAIN_DEPENDENCY_INVALID', 'steps must be topologically ordered with existing unique dependencies')
+  }
+  if (!Array.isArray(step.bindings)) fail('AIMLOCK_CHAIN_INPUT_INVALID', 'bindings must be an array')
+  for (const binding of step.bindings) {
+    exact(binding, ['stepId', 'source', 'target'], 'binding')
+    if (!step.dependsOn.includes(binding.stepId)) fail('AIMLOCK_CHAIN_DEPENDENCY_INVALID', 'binding source must be a dependency')
+    pointerParts(binding.source)
+    pointerParts(binding.target)
+  }
+  if (new Set(step.bindings.map((binding) => binding.target)).size !== step.bindings.length) {
+    fail('AIMLOCK_CHAIN_INPUT_INVALID', 'binding targets must be unique')
+  }
+  if (step.kind === 'skill') {
+    if (!skills.has(step.skillId)) fail('AIMLOCK_CHAIN_SKILL_MISSING', 'step skill must be declared')
+    nonempty(step.operation, 'operation')
+    if (step.skillId === 'confirm-protocol' && step.operation === 'interaction-answer') {
+      fail('AIMLOCK_CHAIN_HUMAN_REQUIRED', 'interaction-answer is supplied only by the interactive answer command')
+    }
+  } else if (step.skillId !== null) fail('AIMLOCK_CHAIN_INPUT_INVALID', 'non-skill steps require skillId=null')
+  if (step.kind === 'coordinator') {
+    nonempty(step.operation, 'operation')
+    if (step.operation === 'resolve-human') fail('AIMLOCK_CHAIN_HUMAN_REQUIRED', 'resolve-human cannot be supplied in the plan')
+  }
+  if (step.kind === 'command') {
+    if (step.operation !== 'exec' || step.bindings.length) fail('AIMLOCK_CHAIN_INPUT_INVALID', 'commands use exec and cannot bind executable input')
+    validateCommand(step.input)
+  }
+}
+
+export function validatePlan(plan) {
+  exact(plan, ['schemaVersion', 'chainId', 'skills', 'steps'], 'plan')
+  if (plan.schemaVersion !== PLAN_SCHEMA) fail('AIMLOCK_CHAIN_SCHEMA_INVALID', 'unsupported execution plan')
+  identifier(plan.chainId, 'chainId')
+  if (!Array.isArray(plan.skills) || !Array.isArray(plan.steps) || !plan.steps.length || plan.steps.length > MAX_STEPS) {
+    fail('AIMLOCK_CHAIN_INPUT_INVALID', 'skills must be an array and steps must contain 1..256 entries')
+  }
+  const skills = new Set()
+  for (const skill of plan.skills) {
+    exact(skill, ['skillId', 'packageRoot'], 'skill')
+    identifier(skill.skillId, 'skillId')
+    nonempty(skill.packageRoot, 'packageRoot')
+    if (skills.has(skill.skillId)) fail('AIMLOCK_CHAIN_INPUT_INVALID', 'duplicate skillId')
+    skills.add(skill.skillId)
+  }
+  const seen = new Set()
+  for (const step of plan.steps) { validateStep(step, seen, skills); seen.add(step.stepId) }
+  return structuredClone(plan)
+}
+
+export function planDigest(plan) { return sha256(JSON.stringify(plan)) }
+
+export function bindInput(step, state) {
+  let input = structuredClone(step.input)
+  for (const binding of step.bindings) {
+    const recorded = state.steps.find((item) => item.stepId === binding.stepId)
+    if (!recorded || recorded.status !== 'succeeded') fail('AIMLOCK_CHAIN_DEPENDENCY_INVALID', 'binding source has not succeeded')
+    input = writePointer(input, binding.target, readPointer(recorded.output, binding.source))
+  }
+  return input
+}
+
+export function chainStatus(state) {
+  if (state.steps.every((step) => step.status === 'succeeded')) return 'succeeded'
+  if (state.steps.some((step) => step.status === 'uncertain')) return 'uncertain'
+  if (state.steps.some((step) => step.status === 'failed')) return 'failed'
+  if (state.steps.some((step) => step.status === 'running')) return 'running'
+  if (state.steps.some((step) => ['blocked', 'waiting'].includes(step.status))) return 'blocked'
+  return 'ready'
+}
+
+export function errorRecord(error) {
+  if (!(error instanceof Error)) return { name: 'ThrownValue', message: String(error) }
+  const value = { name: error.name, message: error.message }
+  for (const key of ['code', 'transportCode', 'operation', 'retryable']) {
+    if (Object.hasOwn(error, key)) value[key] = error[key]
+  }
+  if (error.cause instanceof Error) value.cause = errorRecord(error.cause)
+  return value
+}

package/aimlock-chain-outcomes.mjs

@@ -0,0 +1,40 @@
+const VALIDATOR_PENDING = new Set(['sandbox-run', 'fuzz-input', 'perf-benchmark', 'intrusive-test'])
+const VALIDATOR_STATIC = new Set(['validate-structure', 'security-scan', 'compliance-audit'])
+const ACCEPTED_VERDICTS = new Set(['pass', 'pass-with-risk'])
+
+function blocked(code, message) { return { status: 'blocked', error: { code, message } } }
+
+export function skillOutcome(step, output) {
+  if (output.status !== 'succeeded') return { status: output.status, error: null }
+  if (output.allowed === false || output.autoAccept === false || output.escalate === true
+    || output.validation?.valid === false || (Object.hasOwn(output, 'trafficLight') && output.trafficLight !== 'green')) {
+    return blocked('AIMLOCK_CHAIN_GATE_BLOCKED', 'The protocol call succeeded but its gate did not allow continuation')
+  }
+  if (step.skillId !== 'validator') return { status: 'succeeded', error: null }
+  if (VALIDATOR_PENDING.has(step.operation)) {
+    return blocked('AIMLOCK_CHAIN_EXECUTION_PENDING', 'Validator returned an execution descriptor; no test execution is established')
+  }
+  if (step.operation === 'verdict' && (!ACCEPTED_VERDICTS.has(output.report?.verdict)
+    || output.report.evidenceValid !== true || output.report.evidenceCount < 1
+    || output.report.riskLedgerValid !== true)) {
+    return blocked('AIMLOCK_CHAIN_VERDICT_NOT_ACCEPTED', 'Validator did not issue a complete passing verdict with valid evidence')
+  }
+  if (step.operation === 'functional-verify' && (!Array.isArray(output.evidence) || !output.evidence.length
+    || output.summary?.failed !== 0 || output.evidence.some((evidence) => evidence.exitCode !== 0))) {
+    return blocked('AIMLOCK_CHAIN_FUNCTIONAL_NOT_PASSED', 'Functional verification contains missing or failed execution evidence')
+  }
+  if (VALIDATOR_STATIC.has(step.operation) && output.findings.some((finding) => ['P0', 'P1'].includes(finding.severity))) {
+    return blocked('AIMLOCK_CHAIN_STATIC_FINDINGS', 'Static verification has unresolved P0/P1 findings')
+  }
+  return { status: 'succeeded', error: null }
+}
+
+export function answerMatchesContinuation(condition, answer) {
+  if (!condition) return false
+  const expected = condition.answer
+  if (Array.isArray(expected) || Array.isArray(answer)) {
+    return Array.isArray(expected) && Array.isArray(answer)
+      && JSON.stringify([...expected].sort()) === JSON.stringify([...answer].sort())
+  }
+  return expected === answer
+}

package/aimlock-chain-process.mjs

@@ -0,0 +1,103 @@
+import { spawn } from 'node:child_process'
+import { resolve } from 'node:path'
+import { fail, resolvedProjectPath, sha256 } from './aimlock-local-fs.mjs'
+import { errorRecord } from './aimlock-chain-model.mjs'
+
+const OUTPUT_LIMIT_BYTES = 1_048_576
+const CLOSE_DEADLINE_MS = 1_000
+
+function terminate(child) {
+  if (child.pid === undefined) return
+  if (process.platform === 'win32') child.kill('SIGKILL')
+  else {
+    try { process.kill(-child.pid, 'SIGKILL') } catch (error) {
+      if (error.code !== 'ESRCH') throw error
+    }
+  }
+}
+
+function commandCompletion(child, input, startedAt) {
+  let stdout = '', stderr = '', outputBytes = 0, failure = null, terminationError = null
+  let settled = false, reapTimer = null, timeout = null, resolveCompletion
+  const completed = new Promise((accept) => { resolveCompletion = accept })
+  const finish = (exitCode, signal, unreaped) => {
+    if (settled) return
+    settled = true
+    clearTimeout(timeout)
+    clearTimeout(reapTimer)
+    resolveCompletion({ stdout, stderr, exitCode, signal, error: failure, terminationError,
+      unreaped, durationMs: Date.now() - startedAt })
+  }
+  const requestTermination = () => {
+    try { terminate(child) } catch (error) { terminationError = errorRecord(error) }
+  }
+  const stop = (error) => {
+    if (settled) return
+    if (failure === null) failure = error
+    if (reapTimer === null) {
+      reapTimer = setTimeout(() => {
+        requestTermination()
+        child.stdout.destroy()
+        child.stderr.destroy()
+        child.unref()
+        failure = { code: 'AIMLOCK_CHAIN_COMMAND_UNREAPED',
+          message: 'Command cleanup could not be confirmed within the bounded close deadline',
+          cause: failure }
+        finish(null, null, true)
+      }, CLOSE_DEADLINE_MS)
+    }
+    requestTermination()
+  }
+  const capture = (stream, value) => {
+    if (settled) return
+    outputBytes += Buffer.byteLength(value)
+    if (outputBytes > OUTPUT_LIMIT_BYTES) {
+      stop({ code: 'AIMLOCK_CHAIN_OUTPUT_LIMIT', message: 'Command output exceeded the capture limit' })
+    } else if (stream === 'stdout') stdout += value
+    else stderr += value
+  }
+  child.stdout.setEncoding('utf8')
+  child.stderr.setEncoding('utf8')
+  child.stdout.on('data', (value) => capture('stdout', value))
+  child.stderr.on('data', (value) => capture('stderr', value))
+  child.once('error', (error) => stop(errorRecord(error)))
+  child.once('close', (exitCode, signal) => finish(exitCode, signal, false))
+  timeout = setTimeout(() => {
+    stop({ code: 'AIMLOCK_CHAIN_COMMAND_TIMEOUT', message: 'Command exceeded its declared timeout' })
+  }, input.timeoutMs)
+  return { completed, stop }
+}
+
+export async function executeCommand(root, input, callId, onSpawn) {
+  const workingDirectory = input.workingDirectory === '.' ? root
+    : (await resolvedProjectPath(root, input.workingDirectory)).target
+  if (workingDirectory !== root) {
+    const checked = await resolvedProjectPath(root, input.workingDirectory)
+    if (!checked.status.isDirectory()) fail('AIMLOCK_CHAIN_CWD_INVALID', 'command workingDirectory must be a directory')
+  }
+  const startedAt = Date.now()
+  const child = spawn(input.executable, input.args, { cwd: resolve(workingDirectory),
+    shell: false, env: input.environment, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] })
+  const completion = commandCompletion(child, input, startedAt)
+  if (child.pid !== undefined) {
+    try { await onSpawn(child.pid) } catch (error) {
+      completion.stop(errorRecord(error))
+      await completion.completed
+      throw error
+    }
+  }
+  const output = await completion.completed
+  const command = [input.executable, ...input.args].map((part) => JSON.stringify(part)).join(' ')
+  const summary = output.error ? output.error.message
+    : output.signal ? 'Process terminated by ' + output.signal : 'Process exited with code ' + output.exitCode
+  const evidence = { schemaVersion: 'cli.tax.test-evidence/1.0', evidenceId: callId,
+    kind: input.evidenceKind, runner: 'local', producer: 'local-cli-process', command,
+    exitCode: output.exitCode, durationMs: output.durationMs, summary,
+    stdoutSha256: sha256(output.stdout), stderrSha256: sha256(output.stderr),
+    sandboxed: false, independentRunnerVerified: false }
+  if (output.exitCode === null) {
+    return { status: output.unreaped ? 'uncertain' : 'failed', ...output, evidence: [], termination: summary }
+  }
+  return { status: !output.error && output.exitCode === 0 ? 'succeeded' : 'failed',
+    ...output, evidence: [evidence] }
+}

package/aimlock-chain-store.mjs

@@ -0,0 +1,167 @@
+import { randomUUID } from 'node:crypto'
+import { lstat, mkdir, readFile, rename, rmdir, unlink } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+import { atomicJson, ensureManagedDirectory, fail, identifier, repositoryRoot, resolvedProjectPath } from './aimlock-local-fs.mjs'
+import { STATE_SCHEMA, chainStatus, planDigest, validatePlan } from './aimlock-chain-model.mjs'
+
+const LOCK_WAIT_MS = 2_000
+const LOCK_POLL_MS = 20
+const RECORD_STATUSES = new Set(['pending', 'running', 'waiting', 'blocked', 'failed', 'uncertain', 'succeeded'])
+
+function alive(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) fail('AIMLOCK_CHAIN_LOCK_INVALID', 'execution lock has no valid process owner')
+  try { process.kill(pid, 0); return true } catch (error) {
+    if (error.code === 'ESRCH') return false
+    if (error.code === 'EPERM') return true
+    throw error
+  }
+}
+
+async function ownerOf(directory) {
+  try {
+    const file = resolve(directory, 'owner.json')
+    const status = await lstat(file)
+    if (status.isSymbolicLink() || !status.isFile()) fail('AIMLOCK_CHAIN_LOCK_INVALID', 'execution lock owner is not a regular file')
+    const owner = JSON.parse(await readFile(file, 'utf8'))
+    identifier(owner.lockId, 'execution lockId')
+    if (!Number.isSafeInteger(owner.pid) || owner.pid < 1) fail('AIMLOCK_CHAIN_LOCK_INVALID', 'execution lock owner pid is invalid')
+    return owner
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+}
+
+async function retireLock(directory, retiredDirectory, owner) {
+  const retired = resolve(retiredDirectory, identifier(owner.lockId, 'execution lockId'))
+  try { await rename(directory, retired) } catch (error) {
+    if (error.code === 'ENOENT') return
+    if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error
+    const previous = await ownerOf(retired)
+    if (!previous || previous.lockId !== owner.lockId || previous.pid !== owner.pid) {
+      fail('AIMLOCK_CHAIN_LOCK_INVALID', 'retired lock identity does not match')
+    }
+  }
+  // Keep this non-empty retirement record: a stale contender cannot move a newer active lock over it.
+}
+
+async function inspectLock(directory) {
+  try {
+    const status = await lstat(directory)
+    if (status.isSymbolicLink() || !status.isDirectory()) fail('AIMLOCK_CHAIN_LOCK_INVALID', 'execution lock is not a real directory')
+    return ownerOf(directory)
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+}
+
+async function acquire(directory, retiredDirectory) {
+  const owner = { lockId: randomUUID(), pid: process.pid, createdAt: new Date().toISOString() }
+  const candidate = resolve(dirname(directory), 'candidate-' + owner.lockId)
+  await mkdir(candidate, { mode: 0o700 })
+  await atomicJson(resolve(candidate, 'owner.json'), owner)
+  const deadline = Date.now() + LOCK_WAIT_MS
+  let published = false
+  try {
+    while (true) {
+      try {
+        // Publishing the populated directory is atomic; an interrupted preparation never occupies lock.
+        await rename(candidate, directory)
+        published = true
+        return owner
+      } catch (error) {
+        if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error
+      }
+      const current = await inspectLock(directory)
+      if (current && !alive(current.pid)) { await retireLock(directory, retiredDirectory, current); continue }
+      if (Date.now() >= deadline) fail('AIMLOCK_CHAIN_BUSY', 'another process owns this execution or its lock is invalid')
+      await delay(LOCK_POLL_MS)
+    }
+  } finally {
+    if (!published) {
+      await unlink(resolve(candidate, 'owner.json'))
+      await rmdir(candidate)
+    }
+  }
+}
+
+export async function withExecutionLock(rootValue, chainId, action) {
+  const root = await repositoryRoot(rootValue)
+  identifier(chainId, 'chainId')
+  const directory = await ensureManagedDirectory(root, 'executions', chainId)
+  const retiredDirectory = await ensureManagedDirectory(root, 'executions', chainId, 'retired')
+  const lockDirectory = resolve(directory, 'lock')
+  const owner = await acquire(lockDirectory, retiredDirectory)
+  try { return await action(root, resolve(directory, 'state.json')) } finally {
+    const current = await ownerOf(lockDirectory)
+    if (!current || current.lockId !== owner.lockId) fail('AIMLOCK_CHAIN_LOCK_INVALID', 'execution lock ownership changed')
+    await retireLock(lockDirectory, retiredDirectory, owner)
+  }
+}
+
+export function initialState(plan, contexts) {
+  const validated = validatePlan(plan)
+  const now = new Date().toISOString()
+  return { schemaVersion: STATE_SCHEMA, chainId: plan.chainId, plan: validated, planDigest: planDigest(validated),
+    contexts, createdAt: now, updatedAt: now, status: 'ready',
+    steps: plan.steps.map(({ stepId }) => ({ stepId, status: 'pending', input: null, output: null,
+      pending: null, calls: [], error: null, startedAt: null, completedAt: null, attemptId: null })) }
+}
+
+export async function saveExecution(file, state) {
+  state.updatedAt = new Date().toISOString()
+  state.status = chainStatus(state)
+  await atomicJson(file, state)
+}
+
+export async function loadExecution(file) {
+  const status = await lstat(file)
+  if (!status.isFile() || status.isSymbolicLink()) fail('AIMLOCK_CHAIN_STATE_INVALID', 'execution state must be a regular file')
+  const state = JSON.parse(await readFile(file, 'utf8'))
+  const plan = validatePlan(state.plan)
+  if (state.schemaVersion !== STATE_SCHEMA || state.chainId !== plan.chainId || state.planDigest !== planDigest(plan)
+    || !Array.isArray(state.steps) || state.steps.length !== plan.steps.length
+    || state.steps.some((step, index) => step.stepId !== plan.steps[index].stepId || !RECORD_STATUSES.has(step.status)
+      || !Array.isArray(step.calls))) fail('AIMLOCK_CHAIN_STATE_INVALID', 'execution state does not match its immutable plan')
+  state.status = chainStatus(state)
+  return state
+}
+
+export async function executionStatus(rootValue, chainId) {
+  const root = await repositoryRoot(rootValue)
+  identifier(chainId, 'chainId')
+  const file = await resolvedProjectPath(root, '.aimlock/executions/' + chainId + '/state.json')
+  return loadExecution(file.target)
+}
+
+export async function assertNewExecution(file) {
+  try { await lstat(file) } catch (error) {
+    if (error.code === 'ENOENT') return
+    throw error
+  }
+  fail('AIMLOCK_CHAIN_EXISTS', 'execution already exists; use resume or a new chainId')
+}
+
+export function recoverInterrupted(state) {
+  for (const step of state.steps) {
+    const lastCall = step.calls.at(-1)
+    if (step.status === 'waiting' && step.pending?.kind === 'coordinator-wait'
+      && lastCall?.kind === 'coordinator' && lastCall.operation === 'wait-for-event'
+      && lastCall.status === 'started') {
+      lastCall.status = 'interrupted-read'
+      lastCall.completedAt = new Date().toISOString()
+    }
+    if (step.status !== 'running') continue
+    if (step.pending?.kind === 'coordinator-wait'
+      && step.calls.at(-1)?.kind === 'coordinator' && step.calls.at(-1)?.operation === 'wait-for-event') {
+      step.calls.at(-1).status = 'interrupted-read'
+      step.status = 'waiting'
+      continue
+    }
+    step.status = 'uncertain'
+    step.error = { code: 'AIMLOCK_CHAIN_INTERRUPTED', message: 'The previous process stopped during an operation. Effects are uncertain; automatic replay is forbidden.' }
+    step.completedAt = new Date().toISOString()
+  }
+}

package/aimlock-coordination.mjs

@@ -25,6 +25,37 @@ async function regularFile(path, code, message) {
   return path
 }
 
+function failureHandled(task, tasks, inspected = new Set()) {
+  if (inspected.has(task.taskId)) return false
+  inspected.add(task.taskId)
+  const replacement = tasks.find((item) => item.supersedesTaskId === task.taskId)
+  return replacement && (['active', 'completed'].includes(replacement.status)
+    || (['failed', 'reclaimed'].includes(replacement.status) && failureHandled(replacement, tasks, inspected)))
+}
+
+function parkedAfterDecision(task, tasks, decisions) {
+  if (task.status !== 'blocked' || task.blockedReason !== 'human-decision') return false
+  const decision = decisions.findLast((item) => item.agents.includes(task.agentId))
+  return decision?.status === 'resolved'
+    && tasks.some((active) => active.status === 'active' && decision.answer === 'resume:' + active.agentId)
+}
+
+function assertChainRunnable(state, chainId) {
+  const tasks = state.tasks.filter((task) => task.chainId === chainId)
+  if (!tasks.length) return
+  const wait = state.waits.find((item) => item.chainId === chainId && item.status === 'active')
+  if (wait) fail('AIMLOCK_COORDINATION_WAITING', 'chain ' + chainId + ' is suspended until ' + wait.event + ' or ' + wait.deadlineAt)
+  const pending = state.decisions.some((decision) => decision.status === 'pending'
+    && tasks.some((task) => decision.agents.includes(task.agentId)))
+  const unresolved = tasks.some((task) => ['failed', 'reclaimed'].includes(task.status)
+    && !failureHandled(task, tasks))
+  if (!tasks.some((task) => task.status === 'active') || pending || unresolved
+    || tasks.some((task) => task.status === 'waiting'
+      || (task.status === 'blocked' && !parkedAfterDecision(task, tasks, state.decisions)))) {
+    fail('AIMLOCK_COORDINATION_BLOCKED', 'chain has no active task or has unresolved failures, waits, or human decisions')
+  }
+}
+
 async function verifyLeaseAgainstState(state, root, input) {
   const leasePath = safeRelativePath(input.coordinationLeasePath, 'coordinationLeasePath')
   if (!leasePath.startsWith('.coord/leases/')) {
@@ -37,6 +68,7 @@ async function verifyLeaseAgainstState(state, root, input) {
   await regularFile(publicPath, 'AIMLOCK_COORDINATION_AUTHORITY_INVALID', 'coordination public key must be a regular file')
   const publicKey = await readFile(publicPath, 'utf8')
   const chainId = identifier(input.chainId, 'chainId')
+  assertChainRunnable(state, chainId)
   const targetPaths = input.targetPaths.map((path) => safeRelativePath(path, 'targetPath'))
   const signatureValid = typeof lease.signature === 'string'
     && verify(null, Buffer.from(JSON.stringify(leasePayload(lease))), publicKey,
@@ -55,6 +87,7 @@ async function verifyLeaseAgainstState(state, root, input) {
     && issuedAt <= Date.now() && expiresAt > Date.now()
     && signatureValid
     && lock?.status === 'active' && lock.leaseId === lease.leaseId
+    && state.tasks.some((task) => task.taskId === lock.taskId && task.status === 'active')
     && lock.chainId === lease.chainId && lock.agentId === lease.agentId
     && lock.expiresAt === lease.expiresAt
   if (!valid) {
@@ -82,10 +115,7 @@ async function assertChainNotSuspended(input) {
   if (!statePath.exists) return { suspended: false }
   const chainId = identifier(input.chainId, 'chainId')
   return withCoordinationReadLock(root, async (state) => {
-    const wait = state.waits.find((item) => item.chainId === chainId && item.status === 'active')
-    if (wait) {
-      fail('AIMLOCK_COORDINATION_WAITING', `chain ${chainId} is suspended until ${wait.event} or ${wait.deadlineAt}`)
-    }
+    assertChainRunnable(state, chainId)
     return { suspended: false }
   })
 }