@aria_asi/cli 0.2.36 → 0.2.37

package/scripts/bundle-sdk.mjs

@@ -31,6 +31,7 @@ const COGNITIVE_SKILLS_SRC = resolve(PKG_ROOT, 'skills', 'aria-cognition');
 const RUNTIME_DISCIPLINE_DST = resolve(RUNTIME_DST, 'discipline');
 const CONNECTOR_HOOKS_SRC = resolve(PKG_ROOT, 'hooks');
 const OPENCODE_PLUGINS_SRC = resolve(PKG_ROOT, 'opencode-plugins');
+const TASK_PROJECT_LEDGER_HELPER_SRC = resolve(OPENCODE_PLUGINS_SRC, 'harness-context', 'task-project-ledger.mjs');
 const CLIENT_ONBOARDING_SRC = resolve(PKG_ROOT, 'CLIENT-ONBOARDING.md');
 const DOCTRINE_TRIGGER_MAP_SRC = resolve(CONNECTOR_HOOKS_SRC, 'doctrine_trigger_map.json');
 const REQUIRED_HOOK_FILES = [
@@ -39,6 +40,7 @@ const REQUIRED_HOOK_FILES = [
   'aria-preturn-memory-gate.mjs',
   'aria-stop-gate.mjs',
   'aria-preprompt-consult.mjs',
+  'aria-first-class-coach.mjs',
   'aria-trigger-autolearn.mjs',
   'aria-userprompt-abandon-detect.mjs',
   'aria-agent-handoff.mjs',
@@ -55,6 +57,10 @@ const REQUIRED_HOOK_HELPERS = [
   'lib/canonical-lenses.mjs',
   'lib/gate-audit.mjs',
   'lib/skill-autoload-gate.mjs',
+  'lib/skill-autoload-gate-impl.mjs',
+  'lib/emergency-gateoff.mjs',
+  'lib/emergency-gateoff-impl.mjs',
+  'lib/first-class-coach.mjs',
 ];
 const REQUIRED_OPENCODE_PLUGINS = [
   'harness-context',
@@ -78,6 +84,7 @@ for (const relativePath of REQUIRED_HOOK_HELPERS) {
 for (const pluginName of REQUIRED_OPENCODE_PLUGINS) {
   requirePathExists(join(OPENCODE_PLUGINS_SRC, pluginName), `required OpenCode plugin ${pluginName}`);
 }
+requirePathExists(TASK_PROJECT_LEDGER_HELPER_SRC, 'task/project ledger helper');
 requirePathExists(CLIENT_ONBOARDING_SRC, 'client onboarding guide');
 
 // Staleness guard — newest src mtime must not exceed newest dist mtime.
@@ -300,6 +307,7 @@ if (existsSync(CONNECTOR_HOOKS_SRC)) {
 if (existsSync(OPENCODE_PLUGINS_SRC)) {
   copyTree(OPENCODE_PLUGINS_SRC, join(DIST_ASSETS_DST, 'opencode-plugins'));
 }
+copyFileSync(TASK_PROJECT_LEDGER_HELPER_SRC, join(RUNTIME_DST, 'task-project-ledger.mjs'));
 
 writeFileSync(
   join(RUNTIME_DST, 'manifest.json'),

package/scripts/check-client-compatibility.mjs

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, '..', '..', '..');
+const packageRoot = resolve(here, '..');
+const home = homedir();
+const failures = [];
+
+function fail(check, message, details = {}) {
+  failures.push({ check, message, details });
+}
+
+function assert(check, condition, message, details = {}) {
+  if (!condition) fail(check, message, details);
+}
+
+function readIfExists(pathname) {
+  return existsSync(pathname) ? readFileSync(pathname, 'utf8') : '';
+}
+
+function runtimeAuthHeaders(extra = {}) {
+  const token = process.env.ARIA_HARNESS_TOKEN ||
+    process.env.ARIA_API_KEY ||
+    process.env.ARIA_MASTER_TOKEN ||
+    readIfExists(join(home, '.aria', 'owner-token')).trim();
+  return {
+    'content-type': 'application/json',
+    ...(token ? { 'x-aria-api-key': token } : {}),
+    ...extra,
+  };
+}
+
+function minimalHarnessPacket(message = 'runtime compatibility regression') {
+  return {
+    packet: {
+      axioms: {
+        truth_over_deception: true,
+        no_harm: true,
+        sacred_trust: true,
+        power_obligates_service: true,
+        reflection_before_action: true,
+      },
+      frames: {
+        first_principle: 'Truth over deception. No harm. Sacred trust. Power obligates service. Reflection before action.',
+        message,
+      },
+      doctrine: {},
+      memory: {},
+    },
+    timestamp: new Date().toISOString(),
+  };
+}
+
+function executable(pathname) {
+  return existsSync(pathname) ? pathname : null;
+}
+
+function spawnCapture(command, args, options = {}) {
+  const timeoutMs = options.timeoutMs || 45000;
+  return new Promise((resolveResult) => {
+    const child = spawn(command, args, {
+      env: options.env || process.env,
+      cwd: options.cwd || home,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('exit', (code, signal) => {
+      clearTimeout(timer);
+      resolveResult({ code, signal, timedOut, stdout, stderr });
+    });
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      resolveResult({ code: null, signal: null, timedOut, stdout, stderr: `${stderr}${error.message}` });
+    });
+  });
+}
+
+function startJsonServer(handler) {
+  const requests = [];
+  const server = createServer((req, res) => {
+    let raw = '';
+    req.on('data', (chunk) => { raw += chunk; });
+    req.on('end', () => {
+      let body = {};
+      try {
+        body = raw ? JSON.parse(raw) : {};
+      } catch {}
+      const record = { method: req.method, url: req.url || '/', headers: req.headers, body };
+      requests.push(record);
+      handler(req, res, record);
+    });
+  });
+  return new Promise((resolveServer) => {
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      resolveServer({
+        server,
+        requests,
+        baseUrl: `http://127.0.0.1:${address.port}`,
+        close: () => new Promise((resolveClose) => server.close(resolveClose)),
+      });
+    });
+  });
+}
+
+function writeSse(res, type, data) {
+  res.write(`event: ${type}\n`);
+  res.write(`data: ${JSON.stringify({ type, ...data })}\n\n`);
+}
+
+function respondCodexStream(res, model) {
+  const responseId = 'resp_aria_compat';
+  const itemId = 'msg_aria_compat';
+  const contentPart = { type: 'output_text', text: 'ok', annotations: [] };
+  const item = { id: itemId, type: 'message', status: 'completed', role: 'assistant', content: [contentPart] };
+  const response = {
+    id: responseId,
+    object: 'response',
+    created_at: Math.floor(Date.now() / 1000),
+    status: 'completed',
+    model,
+    output: [item],
+    usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+  };
+  res.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+  });
+  writeSse(res, 'response.created', { response: { ...response, status: 'in_progress', output: [] } });
+  writeSse(res, 'response.output_item.added', { response_id: responseId, output_index: 0, item: { ...item, status: 'in_progress', content: [] } });
+  writeSse(res, 'response.content_part.added', { response_id: responseId, item_id: itemId, output_index: 0, content_index: 0, part: { type: 'output_text', text: '', annotations: [] } });
+  writeSse(res, 'response.output_text.delta', { response_id: responseId, item_id: itemId, output_index: 0, content_index: 0, delta: 'ok' });
+  writeSse(res, 'response.output_text.done', { response_id: responseId, item_id: itemId, output_index: 0, content_index: 0, text: 'ok' });
+  writeSse(res, 'response.content_part.done', { response_id: responseId, item_id: itemId, output_index: 0, content_index: 0, part: contentPart });
+  writeSse(res, 'response.output_item.done', { response_id: responseId, output_index: 0, item });
+  writeSse(res, 'response.completed', { response });
+  res.write('data: [DONE]\n\n');
+  res.end();
+}
+
+function runVersion(command, args = ['--version']) {
+  return spawnCapture(command, args, { timeoutMs: 10000 });
+}
+
+async function checkWrapperContracts() {
+  const sourceShell = readIfExists(join(packageRoot, 'src', 'connectors', 'shell.ts'));
+  const claudeWrapperPath = join(home, '.aria', 'wrappers', 'claude');
+  const codexWrapperPath = join(home, '.aria', 'wrappers', 'codex');
+  const claudeWrapper = readIfExists(claudeWrapperPath);
+  const codexWrapper = readIfExists(codexWrapperPath);
+  assert('source-wrapper-contract', sourceShell.includes(String.raw`ANTHROPIC_BASE_URL="\${ANTHROPIC_BASE_URL:-$ARIA_RUNTIME_URL}"`), 'Generated wrapper must set Anthropic base at the runtime root.');
+  assert('source-wrapper-contract', sourceShell.includes(String.raw`OPENAI_BASE_URL="\${OPENAI_BASE_URL:-$ARIA_RUNTIME_URL/v1}"`), 'Generated wrapper must keep OpenAI base at the v1 root.');
+  assert('source-wrapper-contract', !/OPENAI_API_KEY=.*ARIA_API_KEY/.test(sourceShell), 'Generated wrapper must not copy Aria control-plane tokens into provider API keys.');
+  assert('active-claude-wrapper-contract', claudeWrapper.includes('ANTHROPIC_BASE_URL="${ANTHROPIC_BASE_URL:-$ARIA_RUNTIME_URL}"'), 'Active Claude wrapper must set Anthropic base at the runtime root.', { claudeWrapperPath });
+  assert('active-claude-wrapper-contract', !/OPENAI_API_KEY=.*ARIA_API_KEY/.test(claudeWrapper), 'Active Claude wrapper must not poison provider API key env.', { claudeWrapperPath });
+  assert('active-codex-wrapper-contract', codexWrapper.includes('ANTHROPIC_BASE_URL="${ANTHROPIC_BASE_URL:-$ARIA_RUNTIME_URL}"'), 'Active Codex wrapper must share the corrected runtime root Anthropic base.', { codexWrapperPath });
+  assert('active-codex-wrapper-contract', codexWrapper.includes('case "${1:-}" in') && codexWrapper.includes('app-server|exec-server|exec|review'), 'Active Codex wrapper must preserve bypasses for native non-interactive subcommands.', { codexWrapperPath });
+}
+
+async function checkClaudeCli() {
+  const claudeBin = process.env.ARIA_COMPAT_CLAUDE_REAL_BIN || executable(join(home, '.local', 'bin', 'claude')) || process.env.ARIA_COMPAT_CLAUDE_BIN || executable(join(home, '.aria', 'wrappers', 'claude'));
+  if (!claudeBin) {
+    fail('claude-black-box', 'Claude binary is not installed.');
+    return;
+  }
+  const version = await runVersion(claudeBin);
+  const fake = await startJsonServer((_req, res, record) => {
+    if (record.method === 'HEAD') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end('');
+      return;
+    }
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({
+      id: 'msg_aria_compat',
+      type: 'message',
+      role: 'assistant',
+      model: record.body?.model || 'claude-sonnet-4-6',
+      content: [{ type: 'text', text: 'ok' }],
+      stop_reason: 'end_turn',
+      usage: { input_tokens: 1, output_tokens: 1 },
+    }));
+  });
+  try {
+    const result = await spawnCapture(claudeBin, [
+      '-p', 'Reply with exactly: ok',
+      '--model', 'sonnet',
+      '--max-turns', '1',
+      '--output-format', 'json',
+    ], {
+      timeoutMs: 60000,
+      env: {
+        ...process.env,
+        ANTHROPIC_BASE_URL: fake.baseUrl,
+        OPENAI_BASE_URL: `${fake.baseUrl}/v1`,
+        ARIA_SELF_UPDATE: 'off',
+      },
+    });
+    const post = fake.requests.find((request) => request.method === 'POST');
+    let output = null;
+    try { output = JSON.parse(result.stdout.trim().split('\n').pop() || '{}'); } catch {}
+    assert('claude-black-box', result.code === 0 && !result.timedOut, 'Claude CLI smoke must exit successfully without timeout.', { code: result.code, signal: result.signal, stderr: result.stderr.slice(0, 400), version: version.stdout.trim() || version.stderr.trim() });
+    assert('claude-black-box', output?.result === 'ok' && output?.is_error !== true, 'Claude CLI smoke must return ok through the fake Anthropic-compatible server.', { stdout: result.stdout.slice(0, 400) });
+    assert('claude-request-contract', Boolean(post), 'Claude CLI must make a provider request during compatibility smoke.');
+    assert('claude-request-contract', post?.url?.startsWith('/v1/messages'), 'Claude CLI must target the Anthropic messages route from a runtime-root base URL.', { url: post?.url });
+    assert('claude-request-contract', /^claude(?:-|$)/i.test(post?.body?.model || ''), 'Claude CLI request must keep Claude model as a client-facing alias.', { model: post?.body?.model });
+    assert('claude-request-contract', Array.isArray(post?.body?.tools) && post.body.tools.length > 0 && Boolean(post.body.tools[0]?.input_schema), 'Claude CLI tool schema must remain Anthropic-style input_schema.', { firstToolKeys: Object.keys(post?.body?.tools?.[0] || {}) });
+  } finally {
+    await fake.close();
+  }
+}
+
+async function checkCodexCli() {
+  const codexBin = process.env.ARIA_COMPAT_CODEX_BIN || executable(join(home, '.aria', 'wrappers', 'codex'));
+  if (!codexBin) {
+    fail('codex-black-box', 'Codex wrapper is not installed.');
+    return;
+  }
+  const version = await runVersion(codexBin);
+  const codexHome = join(tmpdir(), `aria-codex-compat-${process.pid}`);
+  rmSync(codexHome, { recursive: true, force: true });
+  mkdirSync(codexHome, { recursive: true, mode: 0o700 });
+  const fake = await startJsonServer((_req, res, record) => {
+    if (record.body?.stream === true) {
+      respondCodexStream(res, record.body?.model || 'gpt-5.4');
+      return;
+    }
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({
+      id: 'resp_aria_compat',
+      object: 'response',
+      created_at: Math.floor(Date.now() / 1000),
+      status: 'completed',
+      model: record.body?.model || 'gpt-5.4',
+      output: [{ id: 'msg_aria_compat', type: 'message', status: 'completed', role: 'assistant', content: [{ type: 'output_text', text: 'ok', annotations: [] }] }],
+      usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+    }));
+  });
+  try {
+    const args = [
+      'exec',
+      '--skip-git-repo-check',
+      '--ignore-rules',
+      '--ignore-user-config',
+      '--ephemeral',
+      '-c', 'model_provider="openai-custom"',
+      '-c', 'model_providers.openai-custom.name="OpenAI Custom"',
+      '-c', `model_providers.openai-custom.base_url="${fake.baseUrl}/v1"`,
+      '-c', 'model_providers.openai-custom.api_key_env="OPENAI_API_KEY"',
+      '--model', 'gpt-5.4',
+      '--json',
+      'Reply with exactly: ok',
+    ];
+    const result = await spawnCapture(codexBin, args, {
+      timeoutMs: 60000,
+      env: {
+        ...process.env,
+        CODEX_HOME: codexHome,
+        OPENAI_API_KEY: 'dummy-key',
+        ARIA_CODEX_BYPASS_BRIDGE: '1',
+        ARIA_SELF_UPDATE: 'off',
+      },
+    });
+    const post = fake.requests.find((request) => request.method === 'POST');
+    assert('codex-black-box', result.code === 0 && !result.timedOut, 'Codex CLI smoke must exit successfully without timeout.', { code: result.code, signal: result.signal, stderr: result.stderr.slice(0, 400), version: version.stdout.trim() || version.stderr.trim() });
+    assert('codex-black-box', /"type":"item\.completed"/.test(result.stdout) && /"text":"ok"/.test(result.stdout), 'Codex CLI smoke must emit an ok agent message in JSONL output.', { stdout: result.stdout.slice(0, 600) });
+    assert('codex-request-contract', Boolean(post), 'Codex CLI must make a provider request during compatibility smoke.');
+    assert('codex-request-contract', post?.url === '/v1/responses', 'Codex CLI must target the OpenAI Responses route.', { url: post?.url });
+    assert('codex-request-contract', post?.body?.model === 'gpt-5.4', 'Codex CLI request must preserve the configured model name.', { model: post?.body?.model });
+    assert('codex-request-contract', Array.isArray(post?.body?.input) && Array.isArray(post?.body?.tools), 'Codex CLI request must preserve Responses input and tools arrays.', { keys: Object.keys(post?.body || {}) });
+  } finally {
+    await fake.close();
+    rmSync(codexHome, { recursive: true, force: true });
+  }
+}
+
+async function checkRuntimeCompatibility() {
+  if (process.env.ARIA_COMPAT_SKIP_RUNTIME === '1') return;
+  const runtimeUrl = process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319';
+  const fake = await startJsonServer((_req, res, record) => {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({
+      id: 'chatcmpl_aria_compat',
+      object: 'chat.completion',
+      created: Math.floor(Date.now() / 1000),
+      model: record.body?.model || 'grok-4.3',
+      choices: [{ index: 0, message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }],
+      usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+    }));
+  });
+  try {
+    const body = {
+      model: 'claude-sonnet-4-6',
+      max_tokens: 16,
+      providerConfig: {
+        provider: 'xai',
+        model: 'grok-4-3',
+        baseUrl: `${fake.baseUrl}/v1/chat/completions`,
+        apiKey: 'dummy-key',
+      },
+      messages: [{ role: 'user', content: [{ type: 'text', text: 'Reply exactly: ok' }] }],
+    };
+    const response = await fetch(`${runtimeUrl.replace(/\/+$/, '')}/v1/v1/messages?beta=true`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: 'Bearer dummy-provider-key', 'anthropic-version': '2023-06-01' },
+      body: JSON.stringify(body),
+    });
+    const raw = await response.text();
+    let data = {};
+    try { data = JSON.parse(raw); } catch {}
+    assert('runtime-compatibility', response.status === 200, 'Runtime must accept doubled v1 Anthropic-compatible paths for stale clients.', { status: response.status, body: raw.slice(0, 400) });
+    assert('runtime-compatibility', data?.content?.[0]?.text === 'ok', 'Runtime stale-client path must return provider content.', { content: data?.content });
+    assert('runtime-compatibility', !/malformed token/i.test(raw), 'Runtime stale-client path must not route provider bearer tokens into license validation.');
+    assert('runtime-compatibility', fake.requests.some((request) => request.body?.model === 'grok-4.3'), 'Runtime must route Claude client aliases to provider-native upstream model names.', { upstreamRequests: fake.requests.map((request) => ({ url: request.url, model: request.body?.model })) });
+  } catch (error) {
+    fail('runtime-compatibility', `Runtime compatibility smoke failed: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    await fake.close();
+  }
+}
+
+async function checkRuntimeRecoveryContracts() {
+  if (process.env.ARIA_COMPAT_SKIP_RUNTIME === '1') return;
+  const runtimeUrl = (process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319').replace(/\/+$/, '');
+  const packet = minimalHarnessPacket('runtime recovery contract regression');
+  const recoveryContract = [
+    'ARIA CODEX RECOVERY CONTRACT',
+    'surface: codex-stop-output',
+    'status: output held for re-authoring',
+    '',
+    'Observed blockers:',
+    '- completion/readiness claim conflicts with unresolved blocker state',
+    '',
+    'Recovery contract:',
+    '1. Do not retry the same blocked text.',
+    '2. Re-author the answer from the user request, not from this block report.',
+    '3. Include <cognition> and <applied_cognition> when the answer is non-trivial.',
+    '4. Use bounded status language when evidence is missing; do not use completion/readiness claims without proof.',
+    '5. Name a measurable verification predicate, or explicitly state that verification has not run.',
+  ].join('\n');
+
+  try {
+    const controlResponse = await fetch(`${runtimeUrl}/validate-output`, {
+      method: 'POST',
+      headers: runtimeAuthHeaders(),
+      body: JSON.stringify({
+        text: recoveryContract,
+        sessionId: 'aria-compat-recovery-control',
+        packet,
+        fetchPacket: false,
+      }),
+    });
+    const controlRaw = await controlResponse.text();
+    let controlData = {};
+    try { controlData = JSON.parse(controlRaw); } catch {}
+    assert('runtime-recovery-contract', controlResponse.status === 200, 'Runtime must accept recovery-contract validation requests.', { status: controlResponse.status, body: controlRaw.slice(0, 400) });
+    assert('runtime-recovery-contract', controlData?.pass === true, 'Recovery contracts must pass as Aria control output instead of being re-scanned as assistant prose.', { body: controlRaw.slice(0, 600) });
+    assert('runtime-recovery-contract', controlData?.validation?.gateTriggers?.includes('aria-control-output'), 'Recovery contract pass-through must be explicitly labeled as control output.', { validation: controlData?.validation });
+    assert('runtime-recovery-contract', Array.isArray(controlData?.layer3?.failures) && controlData.layer3.failures.length === 0, 'Control output must not produce layer3 failures.', { layer3: controlData?.layer3 });
+
+    const doctrineResponse = await fetch(`${runtimeUrl}/validate-output`, {
+      method: 'POST',
+      headers: runtimeAuthHeaders(),
+      body: JSON.stringify({
+        text: 'Done but blocked by missing proof.',
+        sessionId: 'aria-compat-recovery-sanitized-doctrine',
+        packet,
+        fetchPacket: false,
+        runLayer3: true,
+        requireCognitionBlock: false,
+      }),
+    });
+    const doctrineRaw = await doctrineResponse.text();
+    let doctrineData = {};
+    try { doctrineData = JSON.parse(doctrineRaw); } catch {}
+    assert('runtime-sanitized-doctrine', doctrineResponse.status === 200, 'Runtime must return a structured validation body for doctrine-triggered output.', { status: doctrineResponse.status, body: doctrineRaw.slice(0, 400) });
+    assert('runtime-sanitized-doctrine', doctrineData?.layer3?.pass === false, 'Premature completion with unresolved blockers must still fail layer3.', { layer3: doctrineData?.layer3 });
+    assert('runtime-sanitized-doctrine', !/\(\?:done\|complete|done\\\|complete|completed\\\|ready|verified\\\|fixed/.test(doctrineRaw), 'Doctrine failure detail must not expose raw matcher regex.', { body: doctrineRaw.slice(0, 1000) });
+    assert('runtime-sanitized-doctrine', /premature_task_closeout|feedback_no_premature_task_closeout/.test(doctrineRaw), 'Doctrine failure detail must identify the named trigger.', { body: doctrineRaw.slice(0, 1000) });
+  } catch (error) {
+    fail('runtime-recovery-contract', `Runtime recovery contract smoke failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+async function main() {
+  await checkWrapperContracts();
+  await checkClaudeCli();
+  await checkCodexCli();
+  await checkRuntimeCompatibility();
+  await checkRuntimeRecoveryContracts();
+
+  const result = {
+    ok: failures.length === 0,
+    checkedAt: new Date().toISOString(),
+    packageRoot,
+    checks: ['wrapper-contracts', 'claude-black-box', 'codex-black-box', 'runtime-compatibility', 'runtime-recovery-contract'],
+    failures,
+  };
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.ok ? 0 : 1);
+}
+
+main().catch((error) => {
+  console.error(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }, null, 2));
+  process.exit(1);
+});

package/scripts/check-coach-kernel.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, '..', '..', '..');
+const packageRoot = resolve(here, '..');
+const failures = [];
+
+function fail(check, message, details = {}) {
+  failures.push({ check, message, details });
+}
+
+function readText(pathname) {
+  return existsSync(pathname) ? readFileSync(pathname, 'utf8') : '';
+}
+
+function readJson(pathname) {
+  try {
+    return JSON.parse(readText(pathname));
+  } catch (error) {
+    fail('json', `invalid JSON at ${pathname}: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+function requireTokens(label, text, tokens) {
+  if (!text) {
+    fail(label, `${label} source is missing`);
+    return;
+  }
+  for (const token of tokens) {
+    if (!text.includes(token)) fail(label, `missing token ${token}`);
+  }
+}
+
+const ledgerPath = resolve(repoRoot, 'docs', 'system', 'ARIA_COACH_KERNEL_MICROPHASED_LEDGER.json');
+const coachPath = resolve(packageRoot, 'runtime-src', 'coach-kernel.mjs');
+const servicePath = resolve(packageRoot, 'runtime-src', 'service.mjs');
+const codexBridgePath = resolve(packageRoot, 'runtime-src', 'codex-bridge.mjs');
+const codexConnectorPath = resolve(packageRoot, 'src', 'connectors', 'codex.ts');
+const claudeConnectorPath = resolve(packageRoot, 'src', 'connectors', 'claude-code.ts');
+const claudeCoachHookPath = resolve(packageRoot, 'hooks', 'aria-first-class-coach.mjs');
+const firstClassCoachLibPath = resolve(packageRoot, 'hooks', 'lib', 'first-class-coach.mjs');
+const packageJsonPath = resolve(packageRoot, 'package.json');
+
+const ledger = readJson(ledgerPath);
+const coach = readText(coachPath);
+const service = readText(servicePath);
+const codexBridge = readText(codexBridgePath);
+const codexConnector = readText(codexConnectorPath);
+const claudeConnector = readText(claudeConnectorPath);
+const claudeCoachHook = readText(claudeCoachHookPath);
+const firstClassCoachLib = readText(firstClassCoachLibPath);
+const packageJson = readJson(packageJsonPath);
+
+const requiredPhases = [
+  'pre_turn',
+  'pre_cognition',
+  'post_cognition',
+  'pre_generation',
+  'post_generation',
+  'pre_tool',
+  'post_tool',
+  'pre_output',
+  'post_output',
+  'background_start',
+  'background_checkpoint',
+  'background_complete',
+  'claim_or_release',
+];
+
+if (!ledger) {
+  fail('ledger', 'Coach Kernel ledger is missing or invalid');
+} else {
+  if (ledger.schemaVersion !== 1) fail('ledger.schemaVersion', 'schemaVersion must be 1');
+  if (ledger.ledgerId !== 'aria-coach-kernel-microphased-ledger') fail('ledger.ledgerId', 'unexpected Coach Kernel ledger id');
+  for (const phase of requiredPhases) {
+    if (!Array.isArray(ledger.phaseTaxonomy) || !ledger.phaseTaxonomy.includes(phase)) {
+      fail('ledger.phaseTaxonomy', `missing phase ${phase}`);
+    }
+  }
+  const gates = new Set((ledger.qualityGates || []).map((gate) => gate?.id).filter(Boolean));
+  for (const gate of ['coach_module_gate', 'coach_endpoint_gate', 'provider_phase_gate', 'codex_phase_gate', 'claude_phase_gate', 'repair_block_boundary_gate', 'operator_evidence_gate']) {
+    if (!gates.has(gate)) fail('ledger.qualityGates', `missing quality gate ${gate}`);
+  }
+  if (ledger.readinessClaimAllowed === true && Array.isArray(ledger.openBlockers) && ledger.openBlockers.length > 0) {
+    fail('ledger.readinessClaimAllowed', 'readiness cannot be true while open blockers remain');
+  }
+}
+
+requireTokens('coach-module', coach, [
+  'COACH_EVENT_SCHEMA',
+  'COACH_PHASES',
+  'recordCoachPhase',
+  'normalizeCoachEvent',
+  'evaluateCoachEvent',
+  'repair_once',
+  'hard_block',
+  'warn_operator_only',
+  'coach-events.jsonl',
+  'coach-state.json',
+  'redactPotentialSecrets',
+]);
+
+for (const phase of requiredPhases) {
+  if (!coach.includes(`'${phase}'`)) fail('coach-module.phases', `Coach module missing phase ${phase}`);
+}
+
+requireTokens('runtime-service', service, [
+  './coach-kernel.mjs',
+  'recordRuntimeCoachPhase',
+  'applyCoachRepairDecision',
+  "url.pathname === '/coach/event'",
+  "url.pathname === '/coach/phase'",
+  "url.pathname === '/coach/state'",
+  "phase: 'pre_turn'",
+  "phase: 'pre_generation'",
+  "phase: 'post_generation'",
+  "phase: 'pre_output'",
+  "phase: 'claim_or_release'",
+  'coachKernel',
+]);
+
+const preProviderIndex = service.indexOf("phase: 'pre_generation'");
+const providerCallIndex = service.indexOf('providerMeta = await callProviderByStyle');
+if (preProviderIndex < 0 || providerCallIndex < 0 || preProviderIndex > providerCallIndex) {
+  fail('runtime-service.pre-generation-order', 'Coach pre_generation event must be recorded before upstream provider call');
+}
+
+requireTokens('codex-bridge', codexBridge, [
+  'recordCoachPhaseForTurn',
+  "'/coach/phase'",
+  "'pre_turn'",
+  "'pre_tool'",
+  "'post_generation'",
+  "'pre_output'",
+  "'claim_or_release'",
+]);
+
+requireTokens('codex-connector', codexConnector, [
+  'export async function recordCoachPhase',
+  "runtimePost('/coach/phase'",
+  "recordCoachPhase('pre_turn'",
+  "recordCoachPhase('pre_tool'",
+  "recordCoachPhase('post_tool'",
+  "recordCoachPhase('post_generation'",
+  "recordCoachPhase('pre_output'",
+  "recordCoachPhase('post_output'",
+  "recordCoachPhase('claim_or_release'",
+]);
+
+requireTokens('claude-connector', claudeConnector, [
+  'aria-first-class-coach.mjs',
+  'ARIA_COACH_PLATFORM=claude HOOK_EVENT_NAME=SessionStart',
+  'ARIA_COACH_PLATFORM=claude HOOK_EVENT_NAME=UserPromptSubmit',
+  'ARIA_COACH_PLATFORM=claude HOOK_EVENT_NAME=PreToolUse',
+  'ARIA_COACH_PLATFORM=claude HOOK_EVENT_NAME=PostToolUse',
+  'ARIA_COACH_PLATFORM=claude HOOK_EVENT_NAME=Stop',
+]);
+
+requireTokens('claude-coach-hook', claudeCoachHook, [
+  'recordRuntimeCoachForLifecycle',
+  'runtimeCoachBlocksLocalPhase',
+  'formatRuntimeCoachBlock',
+  "'claim_or_release'",
+  "'post_output'",
+]);
+
+requireTokens('first-class-coach-lib', firstClassCoachLib, [
+  'RUNTIME_COACH_BRIDGE_VERSION',
+  "'/coach/phase'",
+  'recordRuntimeCoachForLifecycle',
+  'runtimeCoachBlocksLocalPhase',
+  'formatRuntimeCoachBlock',
+  "session_start: ['pre_turn']",
+  "pre_prompt_injection: ['pre_turn', 'pre_cognition']",
+  "pre_tool: ['pre_tool']",
+  "post_tool: ['post_tool']",
+  "stop: ['post_generation', 'pre_output']",
+  "'claim_or_release'",
+  "'post_output'",
+]);
+
+const scripts = packageJson?.scripts || {};
+if (!scripts['check:coach-kernel']) {
+  fail('package.scripts.check:coach-kernel', 'package must expose Coach Kernel check');
+}
+if (!String(scripts['check:hooks'] || '').includes('check-coach-kernel.mjs')) {
+  fail('package.scripts.check:hooks', 'check:hooks must include Coach Kernel check');
+}
+
+const result = {
+  ok: failures.length === 0,
+  checkedAt: new Date().toISOString(),
+  ledgerPath,
+  coachPath,
+  servicePath,
+  failures,
+};
+console.log(JSON.stringify(result, null, 2));
+process.exit(result.ok ? 0 : 1);