@sentropic/h2a 0.98.5 → 0.98.7-rc.1

package/hooks/deny-manual-h2a-cli.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PreToolUse guard for the packaged H2A plugin.
+ *
+ * The plugin owns its MCP lifecycle. An agent must use the h2a_* / track_*
+ * tools and H2A skills, never invoke the `h2a` executable through Bash.
+ */
+import process from "node:process";
+
+function isManualH2aInvocation(command) {
+  if (typeof command !== "string") return false;
+  // Recognize a command word after normal shell separators and optional common
+  // launch wrappers. This deliberately does not match prose such as
+  // `echo h2a`, paths such as `./h2a`, or an unrelated binary containing h2a.
+  return /(?:^|[;|&\n]\s*)(?:(?:env\s+(?:\w+=(?:"[^"]*"|'[^']*'|\S+)\s+)*)|command\s+|sudo\s+(?:-\w+\s+)*)*h2a(?:\s|$)/m.test(command);
+}
+
+let input = {};
+try {
+  const raw = await new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (data += chunk));
+    process.stdin.on("end", () => resolve(data));
+  });
+  input = raw ? JSON.parse(raw) : {};
+} catch {
+  // A malformed hook payload must never block unrelated work.
+  process.exit(0);
+}
+
+if (isManualH2aInvocation(input?.tool_input?.command)) {
+  process.stderr.write(
+    "Blocked manual `h2a` CLI use. This plugin owns H2A through its single MCP: use h2a_* or track_* tools, or the H2A skill instead.\n",
+  );
+  process.stdout.write(JSON.stringify({ decision: "block", reason: "Use the H2A MCP tools/skill; do not invoke the h2a CLI from Bash." }));
+  process.exit(2);
+}

package/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "description": "Prevents agents from bypassing the H2A plugin MCP with manual h2a CLI commands.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/deny-manual-h2a-cli.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/vibe-post-agent.mjs

@@ -0,0 +1,29 @@
+import { spawnSync } from 'node:child_process';
+import { isAbsolute } from 'node:path';
+// No lifecycle effect until the root parent_session_id field is validated.
+let raw = '';
+const done = message => { if (message) process.stderr.write(message + '\n'); process.exit(0); };
+const timer = setTimeout(() => done('Vibe lifecycle: stdin timeout; no record.'), 4000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('error', () => done('Vibe lifecycle: unreadable stdin; no record.'));
+process.stdin.on('data', chunk => { raw += chunk; if (raw.length > 1_048_576) done('Vibe lifecycle: oversized payload; no record.'); });
+process.stdin.on('end', () => {
+  clearTimeout(timer);
+  try {
+    const payload = JSON.parse(raw);
+    if (typeof payload.parent_session_id === 'string' && payload.parent_session_id.length) return done();
+    if (!Object.hasOwn(payload, 'parent_session_id') || payload.parent_session_id !== null)
+      return done('Vibe lifecycle: missing/invalid parent_session_id; no record.');
+    const flags = {};
+    for (let i = 2; i < process.argv.length; i += 2) flags[process.argv[i]] = process.argv[i + 1];
+    const entrypoint = flags['--entrypoint'], instance = flags['--instance'];
+    if (!entrypoint || !isAbsolute(entrypoint) || !instance || instance === 'auto') return done('Vibe lifecycle: explicit instance and absolute entrypoint required.');
+    const start = Date.now();
+    const tmux = process.env.TMUX_PANE ? spawnSync('tmux', ['display-message', '-p', '#{session_name}'], { encoding: 'utf8', timeout: 500, maxBuffer: 4096 }) : undefined;
+    const args = [entrypoint, 'drumbeat', 'record', '--instance', instance, '--status', flags['--status'] || 'paused',
+      '--command', 'vibe -c', '--resume-command', 'vibe -c', '--tmux-session', tmux?.status === 0 ? tmux.stdout.trim() : '', '--tmux-pane', process.env.TMUX_PANE || ''];
+    if (flags['--root']) args.push('--root', flags['--root']);
+    const result = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: Math.max(1, 4000 - (Date.now() - start)), maxBuffer: 1_048_576 });
+    if (result.status !== 0) process.stderr.write('Vibe lifecycle: drumbeat record failed; inspect the explicit installation.\n');
+  } catch { process.stderr.write('Vibe lifecycle: malformed payload; no record.\n'); }
+});

package/hooks/vibe-pre-tool.mjs

@@ -0,0 +1,40 @@
+// Vibe pre_tool: explicit allow/deny JSON, status 0; the host fails open.
+let raw = '';
+const allow = () => { process.stdout.write('{"decision":"allow"}'); process.exit(0); };
+const timer = setTimeout(allow, 4000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { raw += chunk; if (raw.length > 1_048_576) allow(); });
+process.stdin.on('error', allow);
+process.stdin.on('end', () => {
+  clearTimeout(timer);
+  try {
+    const payload = JSON.parse(raw);
+    const command = payload?.tool_input?.command;
+    if (typeof command !== 'string') return allow();
+    // Quoted arguments stay single words. Separators inside an argument are
+    // data, including the benign Node expression containing "|h2a send".
+    const tokens = [];
+    let word = '', quote = '', escape = false, started = false;
+    const flush = () => { if (started) tokens.push(word); word = ''; started = false; };
+    for (const ch of command) {
+      if (escape) { word += ch; started = true; escape = false; continue; }
+      if (ch === '\\' && quote !== "'") { escape = true; started = true; continue; }
+      if (quote) { if (ch === quote) quote = ''; else word += ch; continue; }
+      if (ch === '"' || ch === "'") { quote = ch; started = true; continue; }
+      if (';|&\n()'.includes(ch)) { flush(); tokens.push(null); }
+      else if (/\s/.test(ch)) flush(); else { word += ch; started = true; }
+    }
+    flush();
+    let executable = true, denied = false;
+    for (const token of tokens) {
+      if (token === null) { executable = true; continue; }
+      if (!executable) continue;
+      if (/^[A-Za-z_][\w]*=/.test(token) || ['env', 'command', 'sudo'].includes(token) || token.startsWith('-')) continue;
+      if (token === 'h2a') { denied = true; break; }
+      executable = false;
+    }
+    if (!denied) return allow();
+    process.stderr.write('Use the H2A MCP tools/skill; manual h2a CLI invocation refused.\n');
+    process.stdout.write(JSON.stringify({ decision: 'deny', reason: 'Use h2a_* or track_* MCP tools and the H2A skill.' }));
+  } catch { allow(); }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/h2a",
-  "version": "0.98.5",
+  "version": "0.98.7-rc.1",
   "description": "h2a — the unified CLI + core for human-to-agent coordination.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,9 @@
     "fixtures",
     "skills",
     "schema",
-    "focus-app"
+    "focus-app",
+    "hooks",
+    "scripts"
   ],
   "publishConfig": {
     "access": "public"
@@ -45,7 +47,7 @@
     "h2a": "dist/bin.js"
   },
   "scripts": {
-    "build": "node ../../scripts/clean-workspace-dist.mjs && tsc -b --force",
+    "build": "node ../../scripts/clean-workspace-dist.mjs && tsc -b --force && node ../../scripts/copy-vendored-engram-live.mjs",
     "prepack": "node ../../scripts/check-focus-app.mjs && chmod +x dist/bin.js"
   },
   "dependencies": {
@@ -55,10 +57,11 @@
     "@sentropic/cluster-mesh": "0.13.3",
     "@sentropic/contracts": "^0.3.0",
     "@sentropic/events": "^0.2.0",
-    "@sentropic/track": "^0.98.5",
-    "hono": "^4.13.7"
+    "@sentropic/track": "0.98.7-rc.1",
+    "hono": "^4.13.7",
+    "toml-eslint-parser": "0.10.1"
   },
   "peerDependencies": {
-    "@sentropic/h2a-runtime": "^0.98.5"
+    "@sentropic/h2a-runtime": "0.98.7-rc.1"
   }
 }

package/scripts/qualification-budget.mjs

@@ -0,0 +1,56 @@
+// An execution is one app-server session (forks included), or the CLI probe.
+// An iteration is one model call, INCLUDING delegated subagent model calls.
+export const VIBE_QUALIFICATION_PLAN = Object.freeze([
+  { id: 'phase1-a', phase: 1, kind: 'session', maxIterations: 3, maxPrice: 0.15, maxSeconds: 90 },
+  { id: 'phase1-b', phase: 1, kind: 'session', maxIterations: 3, maxPrice: 0.15, maxSeconds: 90 },
+  { id: 'cli-probe', phase: 1, kind: 'probe', maxIterations: 3, maxPrice: 0.10, maxSeconds: 90 },
+  { id: 'phase2-origin', phase: 2, kind: 'session', maxIterations: 3, maxPrice: 0.175, maxSeconds: 90 },
+  { id: 'phase2-copy', phase: 2, kind: 'session', maxIterations: 3, maxPrice: 0.175, maxSeconds: 90 }
+]);
+export const PHASE2_RECIPE = Object.freeze({
+  fork: { method: 'session/fork', attach: false, beforeDelegation: true },
+  origin: ['parent requests delegation', 'child model call', 'parent final answer'],
+  copy: ['request benign command', 'request guarded CLI command', 'final answer'],
+  oracle: 'Origin delegates AFTER fork: one record proves both parent-only behavior and the still-active origin. Copy: allow/deny and no record modification.',
+  scope: 'session/fork attaches by default; this recipe explicitly passes attach:false. /branch and ACP forks attach on resume.'
+});
+export class QualificationBudget {
+  constructor(plan = VIBE_QUALIFICATION_PLAN, now = Date.now) {
+    this.plan = plan; this.now = now; this.start = now(); this.executions = new Map();
+    if (plan.length > 5 || plan.reduce((n, e) => n + e.maxIterations, 0) > 15 || plan.reduce((n, e) => n + e.maxPrice, 0) > 0.75000001 || plan.reduce((n, e) => n + e.maxSeconds, 0) > 450)
+      throw new Error('qualification envelope exceeded');
+    for (const e of plan) if (e.maxIterations > 3 || e.maxPrice > 0.25 || e.maxSeconds > 90) throw new Error('per-execution envelope exceeded');
+    for (const phase of [1, 2]) if (plan.filter(e => e.phase === phase && e.kind === 'session').length > 2) throw new Error('too many sessions, forks included');
+  }
+  begin(id) {
+    this.check();
+    if (this.executions.has(id)) throw new Error('automatic retry/restart forbidden');
+    const spec = this.plan.find(e => e.id === id); if (!spec) throw new Error('unbudgeted execution');
+    this.executions.set(id, { ...spec, started: this.now(), iterations: 0, price: 0 }); return spec;
+  }
+  restorePhase1(entries, elapsed) {
+    if (!Array.isArray(entries) || !Number.isFinite(elapsed) || elapsed < 0 || elapsed >= 450_000) throw new Error('invalid prior accounting');
+    const restored = new Map();
+    for (const entry of entries) {
+      const spec = this.plan.find(e => e.phase === 1 && e.id === entry.id);
+      if (!spec || restored.has(entry.id) || !Number.isInteger(entry.iterations) || entry.iterations < 0 || entry.iterations > spec.maxIterations ||
+        !Number.isFinite(entry.price) || entry.price < 0 || entry.price > spec.maxPrice + 1e-9) throw new Error('invalid prior accounting');
+      restored.set(entry.id, { ...spec, iterations: entry.iterations, price: entry.price, started: this.now() - elapsed });
+    }
+    if (restored.size !== this.plan.filter(e => e.phase === 1).length) throw new Error('incomplete prior accounting');
+    this.executions = restored; this.start = this.now() - elapsed;
+  }
+  remaining() { return Math.max(0, 450_000 - (this.now() - this.start)); }
+  account(id, { modelCalls, price }) {
+    if (!Number.isInteger(modelCalls) || modelCalls < 0 || !Number.isFinite(price) || price < 0) throw new Error('native accounting unavailable');
+    const e = this.executions.get(id); if (!e) throw new Error('unknown execution');
+    e.iterations += modelCalls; e.price += price;
+    if (e.iterations > e.maxIterations || e.price > e.maxPrice + 1e-9) throw new Error('native execution budget reached');
+    this.check(id);
+  }
+  check(id) {
+    if (this.now() - this.start >= 450_000) throw new Error('global watchdog reached');
+    const e = this.executions.get(id);
+    if (e && this.now() - e.started >= e.maxSeconds * 1000) throw new Error('execution watchdog reached');
+  }
+}

package/scripts/qualification-cleanup.mjs

@@ -0,0 +1,15 @@
+import { spawnSync } from 'node:child_process';
+import { listDrumbeat } from '../dist/runtime/drumbeat/index.js';
+export function ownedRecordSnapshot(root, instance) {
+  const records = listDrumbeat(root);
+  return { own: records.find(r => r.instance === instance), others: records.filter(r => r.instance !== instance) };
+}
+export function clearQualificationRecords({ root, instances, entrypoint, env, run = spawnSync }) {
+  const before = listDrumbeat(root).filter(r => !instances.includes(r.instance));
+  for (const instance of instances) {
+    const child = run(process.execPath, [entrypoint, 'drumbeat', 'clear', '--instance', instance, '--root', root], { env, encoding: 'utf8', timeout: 5000, maxBuffer: 65536 });
+    if (child.status !== 0) throw new Error('qualification drumbeat cleanup failed');
+  }
+  const after = listDrumbeat(root);
+  if (after.some(r => instances.includes(r.instance)) || JSON.stringify(after) !== JSON.stringify(before)) throw new Error('qualification cleanup verification failed');
+}

package/scripts/qualification-oracles.mjs

@@ -0,0 +1,44 @@
+// Only native structured effects count. An assistant's prose is never evidence.
+export function inspectSkillEntries(entries, requiredResources) {
+  return requiredResources.length > 0 && requiredResources.every(resource => entries.some(e => e.type === 'effect' && e.state?.status === 'completed' &&
+    (e.detail?.input?.path === resource.path || e.detail?.input?.filePath === resource.path) &&
+    (e.state?.output?.content === resource.bytes || e.state?.outputText === resource.bytes)));
+}
+export function inspectGuardEntries(entries, sessionId) {
+  const notices = entries.filter(e => e.sessionId === sessionId && e.type === 'notice').map(e => e.detail);
+  const refused = notices.find(n => n.kind === 'hook_completed' && n.scope === 'pre_tool' && n.hookName === 'sentropic-h2a-deny-manual-cli' && n.status === 'error' && n.toolCallId);
+  const targets = entries.filter(e => e.sessionId === sessionId && e.type === 'effect' && e.detail?.input?.command === 'h2a --version');
+  if (targets.some(e => e.state?.status === 'completed') || !targets.some(e => e.id === refused?.toolCallId && ['failed', 'skipped', 'cancelled'].includes(e.state?.status))) return false;
+  const benign = entries.find(e => e.sessionId === sessionId && e.type === 'effect' && e.detail?.input?.command === 'printf vibe-guard-ok' && e.state?.status === 'completed');
+  const id = benign?.id;
+  const started = notices.some(n => n.kind === 'hook_run_started' && n.scope === 'pre_tool' && n.toolCallId === id);
+  const completed = notices.some(n => n.kind === 'hook_run_completed' && n.scope === 'pre_tool' && n.toolCallId === id);
+  const degraded = notices.some(n => n.scope === 'pre_tool' && n.toolCallId === id && n.status === 'warning');
+  return !!refused && !!benign && started && completed && !degraded;
+}
+export function inspectLifecycleEntries(entries, origin, copy, recordEvidence) {
+  const post = entries.filter(e => e.type === 'notice' && e.detail?.scope === 'post_agent');
+  const nativeParentRun = post.some(e => e.sessionId === origin && e.detail.kind === 'hook_run_started') && post.some(e => e.sessionId === origin && e.detail.kind === 'hook_run_completed');
+  const delegated = entries.some(e => e.sessionId === origin && e.type === 'effect' && e.detail?.kind === 'subagent' && e.state?.status === 'completed');
+  return nativeParentRun && delegated && !!copy && recordEvidence.parentRecordPresent && recordEvidence.lifecycleRecordUnchangedInFork && recordEvidence.recordedAfterParent &&
+    recordEvidence.childRecordUntouched === true && recordEvidence.parentRecordTransitions === 1 && recordEvidence.otherInstancesUntouched === true;
+}
+export function inspectMcpEntries(entries, sessionId, { busRoot, workspace }) {
+  const effects = entries.filter(e => e.sessionId === sessionId && e.type === 'effect' && e.state?.status === 'completed');
+  const decode = e => {
+    let output = e.state.output;
+    if (output?.isError) return undefined;
+    if (output?.content) output = output.content.filter(c => c.type === 'text').map(c => c.text).join('\n');
+    try { return typeof output === 'string' ? JSON.parse(output) : output; } catch { return undefined; }
+  };
+  const identity = effects.filter(e => /h2a_identity_status$/.test(e.detail?.toolName ?? '')).map(decode).find(Boolean);
+  const opened = effects.filter(e => /h2a_session_open$/.test(e.detail?.toolName ?? '')).map(decode).find(o => o?.session?.sessionId);
+  const track = effects.filter(e => /track_/.test(e.detail?.toolName ?? '')).map(decode);
+  const identityContext = identity?.identity ?? identity;
+  const correctBus = ['identity_ready', 'identity_disabled'].includes(identityContext?.state) && identityContext?.root === busRoot;
+  // Track's real status payload is {level, groups}, without a root field.
+  // Bind it to the workspace reported by the same native MCP server. A serve-empty
+  // hint or tool error cannot decode as a successful Track status observation.
+  const correctWorkspace = identityContext?.workspaceRoot === workspace && track.some(result => result?.level && Array.isArray(result.groups));
+  return { MCP: correctBus && !!opened, context: correctBus && correctWorkspace && !!opened, h2aSessionId: opened?.session.sessionId, instance: opened?.session.instance };
+}

package/scripts/qualification-patch.mjs

@@ -0,0 +1,21 @@
+// Apply only the native public-history JSON patch dialect; never execute text.
+export function patchNativeHistory(entry, operations) {
+  let value = structuredClone(entry);
+  for (const operation of operations) {
+    if (!['add', 'replace', 'append', 'remove', 'test'].includes(operation.op)) throw new Error('unsupported native patch');
+    const keys = operation.path.split('/').slice(1).map(k => k.replace(/~1/g, '/').replace(/~0/g, '~'));
+    if (keys.some(k => ['__proto__', 'constructor', 'prototype'].includes(k))) throw new Error('unsafe native patch');
+    if (!keys.length) { if (operation.op !== 'replace') throw new Error('unsupported root patch'); value = operation.value; continue; }
+    const last = keys.pop(), parent = keys.reduce((object, key) => object?.[key], value);
+    if (!parent || typeof parent !== 'object') throw new Error('native patch target missing');
+    if (operation.op === 'remove') { if (Array.isArray(parent)) parent.splice(Number(last), 1); else delete parent[last]; }
+    else if (operation.op === 'test') { if (JSON.stringify(parent[last]) !== JSON.stringify(operation.value)) throw new Error('native patch mismatch'); }
+    else if (operation.op === 'append') {
+      if (typeof parent[last] === 'string') parent[last] += operation.value;
+      else if (Array.isArray(parent[last])) parent[last].push(...operation.value);
+      else throw new Error('unsupported native append');
+    } else parent[last] = structuredClone(operation.value);
+  }
+  if (value.id !== entry.id || value.sessionId !== entry.sessionId) throw new Error('native patch identity changed');
+  return value;
+}

package/scripts/qualification-poll-hosts.mjs

@@ -0,0 +1,19 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+// The spec verifies these discovery/import commands, but no bounded model
+// invocation or hook equivalent for Muse/agy. Never substitute Gemini for agy.
+export function qualifyPollHost({ host, env, cwd, evidence, run = spawnSync }) {
+  const commands = host === 'muse' ? [['muse', 'skills', 'list']] : [['agy', 'plugin', 'import', 'gemini'], ['agy', 'plugin', 'enable', 'h2a']];
+  const checks = [];
+  for (const [command, ...args] of commands) {
+    const result = run(command, args, { env, cwd, encoding: 'utf8', timeout: 15_000, maxBuffer: 1_048_576 });
+    const ok = result.status === 0;
+    checks.push({ command: [command, ...args], ok });
+    evidence.push({ method: 'qualification/native-discovery', command: [command, ...args], ok,
+      sha256: createHash('sha256').update(result.stdout ?? '').digest('hex') });
+    if (!ok) break;
+  }
+  return { skills: 'partial', MCP: 'partial', context: 'partial', guard: 'partial', lifecycle: 'partial',
+    import: host === 'agy' ? checks.length === 2 && checks.every(c => c.ok) ? 'observed-success' : 'failed' : 'N-A', checks,
+    limit: 'Native model/session accounting and usable session traces are not yet qualified. Discovery/import alone never qualifies skills, MCP or the M-B hook equivalents.' };
+}

package/scripts/qualification-probe.mjs

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { createHash } from 'node:crypto';
+import { openQualificationRpc } from './qualification-rpc.mjs';
+import { nativeStats } from './qualification-vibe.mjs';
+import { inspectSkillEntries, inspectMcpEntries } from './qualification-oracles.mjs';
+export async function qualifyVibeProbe({ command = 'vibe', commandArgs = [], appServer = 'vibe-app-server', appServerArgs = [], cwd, env, tools, budget, signal, evidence, cleanup, directory, requiredResources = [], busRoot, components = ['skills', 'MCP', 'context'] }) {
+  if (!tools.length || tools.some(t => /bash|shell|exec|process|terminal|code|eval/i.test(t))) throw new Error('probe requires minimal native read-only tools; execution tools forbidden');
+  const allocation = budget.begin('cli-probe');
+  const needsMcp = components.some(c => c === 'MCP' || c === 'context');
+  const args = [...commandArgs, '-p', 'Read the installed H2A skill resources at ' + requiredResources.map(r => r.path).join(', ') +
+    (needsMcp ? '. Use h2a_identity_status, h2a_session_open and track_status with level=task and baselineCommit=qualification for this workspace.' : '') + ' Do not execute commands.', '--agent', 'auto-approve', '--enabled-tools', ...tools,
+    '--max-turns', String(allocation.maxIterations), '--max-price', String(allocation.maxPrice), '--output', 'streaming'];
+  const child = spawn(command, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+  let raw = '', pending = '', malformed = false, error, rpc;
+  const ids = new Set(), entries = [];
+  const consume = line => {
+    if (!line.trim()) return;
+    try {
+      const entry = JSON.parse(line); entries.push(entry);
+      if (typeof entry.sessionId === 'string' && entry.sessionId) { ids.add(entry.sessionId); if (!cleanup.sessions.includes(entry.sessionId)) cleanup.sessions.push(entry.sessionId); }
+    } catch { malformed = true; }
+  };
+  child.stdout.setEncoding('utf8'); child.stdout.on('data', bytes => {
+    raw += bytes;
+    if (raw.length > 1_048_576) { malformed = true; child.kill('SIGTERM'); return; }
+    pending += bytes; let at;
+    while ((at = pending.indexOf('\n')) >= 0) { consume(pending.slice(0, at)); pending = pending.slice(at + 1); }
+  });
+  child.stderr.on('data', () => {}); child.on('error', e => { error = e; });
+  const abort = () => child.kill('SIGTERM'); signal?.addEventListener('abort', abort, { once: true });
+  const deadline = Math.min(allocation.maxSeconds * 1000, budget.remaining());
+  const watchdog = setTimeout(abort, deadline), force = setTimeout(() => child.kill('SIGKILL'), deadline + 2000);
+  try {
+    const [code] = await once(child, 'close'); consume(pending); pending = '';
+    if (error || code !== 0 || malformed || ids.size !== 1) throw new Error('native CLI probe incomplete or uncorrelated');
+    const [sessionId] = ids;
+    rpc = openQualificationRpc(appServer, appServerArgs, { cwd, env, signal });
+    await rpc.request('initialize', { clientInfo: { name: 'h2a-qualification-probe', version: '1' } }); rpc.notify('initialized');
+    const state = await rpc.request('session/read', { sessionId });
+    const stats = await rpc.request('stats/read', { sessionId }); budget.account('cli-probe', nativeStats(stats.stats));
+    const journal = state.state?.session?.id === sessionId && Array.isArray(state.state?.history) && state.state.history.length > 0;
+    const resources = inspectSkillEntries(entries, requiredResources), mcp = inspectMcpEntries(entries, sessionId, { busRoot, workspace: cwd });
+    const result = { status: journal && (!components.includes('skills') || resources) && (!components.includes('MCP') || mcp.MCP) && (!components.includes('context') || mcp.context) ? 'observed' : 'partial', sessionId, journal, resources, MCP: mcp.MCP, context: mcp.context };
+    evidence.push({ method: 'qualification/cli-probe', ...result, sha256: createHash('sha256').update(raw).digest('hex') }); return result;
+  } finally {
+    clearTimeout(watchdog); clearTimeout(force); signal?.removeEventListener('abort', abort);
+    if (child.pid && child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await once(child, 'close'); }
+    consume(pending);
+    // A failed CLI may create a session before emitting an entry. Never scan
+    // or delete unknown sessions; retain the private cleanup lane.
+    if (!ids.size || malformed) cleanup.incomplete = true;
+    if (ids.size) {
+      try {
+        if (!rpc) { rpc = openQualificationRpc(appServer, appServerArgs, { cwd, env }); await rpc.request('initialize', { clientInfo: { name: 'h2a-qualification-cleanup', version: '1' } }); rpc.notify('initialized'); }
+        for (const sessionId of ids) { await rpc.request('session/delete', { sessionId }); if (!cleanup.deleted.includes(sessionId)) cleanup.deleted.push(sessionId); }
+      } catch { cleanup.incomplete = true; }
+      finally { await rpc?.close(); }
+    }
+  }
+}

package/scripts/qualification-rpc.mjs

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+// Only this child is signalled. Unknown events never establish a qualification.
+export function openQualificationRpc(command, args, { cwd, env, signal, observe = () => {}, serverRequest }) {
+  const child = spawn(command, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
+  let next = 0, buffer = '', failure;
+  const requests = new Map();
+  const fail = error => { failure = error; for (const request of requests.values()) request.reject(error); requests.clear(); };
+  child.on('error', fail); child.on('exit', () => fail(new Error('native app-server exited')));
+  child.stderr.on('data', () => {}); // Never persist stderr: native diagnostics can contain secrets.
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', bytes => {
+    buffer += bytes;
+    if (buffer.length > 1_048_576) { fail(new Error('native frame bound exceeded')); child.kill('SIGTERM'); return; }
+    let index;
+    while ((index = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+      try {
+        const message = JSON.parse(line);
+        if (message.id !== undefined && requests.has(message.id)) {
+          const request = requests.get(message.id); requests.delete(message.id);
+          if (message.error) request.reject(new Error('native RPC refused ' + request.method)); else request.resolve(message.result);
+        } else if (message.id !== undefined) {
+          if (serverRequest) {
+            Promise.resolve(serverRequest(message)).then(result => child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, result }) + '\n'), () => {
+              child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code: -32000, message: 'qualification request refused' } }) + '\n');
+            });
+            continue;
+          }
+          // Unknown approvals are always refused; no blanket tool permission.
+          child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code: -32000, message: 'qualification approval not authorized' } }) + '\n');
+          observe({ method: 'qualification/approval-refused' });
+        } else observe(message);
+      } catch { fail(new Error('invalid native NDJSON frame')); }
+    }
+  });
+  const abort = () => { fail(new Error('qualification interrupted')); child.kill('SIGTERM'); };
+  signal?.addEventListener('abort', abort, { once: true });
+  return {
+    child,
+    notify(method, params = {}) { child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'); },
+    async request(method, params = {}) {
+      if (failure) throw failure;
+      const id = ++next;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { requests.delete(id); reject(new Error('native RPC timeout')); }, 15_000);
+        requests.set(id, { method, resolve: value => { clearTimeout(timer); resolve(value); }, reject: error => { clearTimeout(timer); reject(error); } });
+        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+      });
+    },
+    async close() {
+      signal?.removeEventListener('abort', abort); fail(new Error('qualification closed'));
+      if (!child.pid || child.exitCode !== null || child.signalCode !== null) return;
+      const exited = once(child, 'exit'); child.stdin.end(); child.kill('SIGTERM');
+      const force = setTimeout(() => child.kill('SIGKILL'), 2000);
+      try { await exited; } finally { clearTimeout(force); }
+    }
+  };
+}

package/scripts/qualification-vibe.mjs

@@ -0,0 +1,159 @@
+import fs from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { openQualificationRpc } from './qualification-rpc.mjs';
+import { PHASE2_RECIPE } from './qualification-budget.mjs';
+import { inspectGuardEntries, inspectLifecycleEntries, inspectMcpEntries, inspectSkillEntries } from './qualification-oracles.mjs';
+import { patchNativeHistory } from './qualification-patch.mjs';
+const sha = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export function nativeStats(stats) {
+  if (!Number.isInteger(stats?.steps)) throw new Error('native iteration accounting unavailable');
+  const { sessionPromptTokens: prompt, sessionCompletionTokens: completion, sessionCachedTokens: cached,
+    inputPricePerMillion: input, outputPricePerMillion: output, cachedInputPricePerMillion: cachePrice } = stats;
+  if (![prompt, completion, cached, input, output].every(n => Number.isFinite(n) && n >= 0) || cached > prompt || cachePrice != null && (!Number.isFinite(cachePrice) || cachePrice < 0)) throw new Error('native price accounting unavailable');
+  return { modelCalls: stats.steps, price: ((prompt - cached) * input + cached * (cachePrice ?? input) + completion * output) / 1_000_000 };
+}
+export async function qualifyVibe({ command = 'vibe-app-server', args = [], env, workspaces, busRoot, phase, budget, signal, evidence, cleanup, components, requiredResources = [], clearRecords = () => {}, recordSnapshot = () => undefined }) {
+  const sessions = new Map(), history = new Map(), turns = new Map(), completedTurns = new Map(), calls = [];
+  let rpc;
+  let lifecycleOrigin, recordBaseline, parentHookStarted, childRecordUntouched = false, parentRecordTransitions = 0, parentAfter;
+  const accounted = new Map();
+  const account = (sessionId, stats) => {
+    const execution = sessions.get(sessionId); if (!execution) throw new Error('unmapped native statistics');
+    const current = nativeStats(stats), previous = accounted.get(sessionId) ?? { modelCalls: 0, price: 0 };
+    budget.account(execution.id, { modelCalls: current.modelCalls - previous.modelCalls, price: current.price - previous.price }); accounted.set(sessionId, current);
+  };
+  const onEvent = message => {
+    const p = message.params ?? {};
+    if (p.entry) { const entries = history.get(p.sessionId) ?? new Map(); entries.set(p.entry.id, p.entry); history.set(p.sessionId, entries); }
+    if (p.entryId && p.patch) {
+      const entries = history.get(p.sessionId), entry = entries?.get(p.entryId);
+      if (entry) try { entries.set(p.entryId, patchNativeHistory(entry, p.patch)); } catch { entries.delete(p.entryId); }
+    }
+    if (p.childSession && sessions.has(p.sessionId)) {
+      sessions.set(p.childSession.id, sessions.get(p.sessionId)); cleanup.sessions.push(p.childSession.id);
+      if (p.sessionId === lifecycleOrigin && p.childSession.status?.type === 'idle') childRecordUntouched = JSON.stringify(recordSnapshot()) === JSON.stringify(recordBaseline);
+    }
+    if (message.method === 'stats/updated' && sessions.has(p.sessionId)) try { account(p.sessionId, p.stats); } catch { rpc.child.kill('SIGTERM'); }
+    const detail = p.entry?.detail;
+    if (p.sessionId === lifecycleOrigin && detail?.scope === 'post_agent') {
+      if (detail.kind === 'hook_run_started') {
+        parentHookStarted = Date.now();
+        if (JSON.stringify(recordSnapshot()) !== JSON.stringify(recordBaseline)) childRecordUntouched = false;
+      }
+      if (detail.kind === 'hook_run_completed') {
+        const current = recordSnapshot();
+        if (JSON.stringify(current?.own) !== JSON.stringify(parentAfter?.own)) parentRecordTransitions++;
+        parentAfter = current;
+      }
+    }
+    if (message.method === 'turn/completed') { completedTurns.set(p.turn?.id, p.turn); turns.get(p.turn?.id)?.(p.turn); }
+    evidence.push({ method: message.method, sessionId: p.sessionId, eventId: p.eventId, sha256: sha(message) });
+  };
+  rpc = openQualificationRpc(command, args, { cwd: workspaces[0], env, signal, observe: onEvent,
+    serverRequest: async message => {
+      if (message.method !== 'callback/call') throw new Error('unexpected server request');
+      const cb = message.params.callback, effect = cb.detail?.effect, command = effect?.input?.command;
+      const resourceRead = effect?.kind === 'file_read' && ['read_file', 'file_system.read_file', 'file_read'].includes(effect.toolName) &&
+        requiredResources.some(r => [effect.input?.path, effect.input?.filePath].includes(r.path));
+      const expectedCommand = ['shell', 'process'].includes(effect?.kind) && ['bash', 'file_system.bash', 'process_start', 'process.start'].includes(effect.toolName) &&
+        ['printf vibe-guard-ok', 'h2a --version'].includes(command);
+      const allowed = cb.detail?.kind === 'approval' && (expectedCommand || resourceRead) && sessions.has(cb.sessionId);
+      queueMicrotask(() => rpc.request('callback/respond', { sessionId: cb.sessionId, callbackId: cb.callbackId,
+        output: { type: 'approval', decision: { type: allowed ? 'approve' : 'deny' } } }).catch(() => {}));
+      evidence.push({ method: 'qualification/approval', sessionId: cb.sessionId, allowed, sha256: sha(cb.detail) });
+      return { callbackId: cb.callbackId, accepted: true };
+    } });
+  const start = async (id, cwd) => {
+    const allocation = budget.begin(id), started = Date.now();
+    const agentConfig = { cwd, headless: true, maxTurns: allocation.maxIterations, maxPrice: allocation.maxPrice };
+    const result = await rpc.request('session/start', { agentConfig });
+    const session = result.state?.session;
+    if (!session?.id || session.cwd !== cwd || session.parentSessionId !== null) throw new Error('native session context mismatch');
+    sessions.set(session.id, { id, allocation, started, cwd }); cleanup.sessions.push(session.id);
+    return session.id;
+  };
+  const turn = async (sessionId, text) => {
+    const execution = sessions.get(sessionId);
+    const watchdog = setTimeout(() => rpc.child.kill('SIGTERM'), Math.max(1, Math.min(budget.remaining(), execution.allocation.maxSeconds * 1000 - (Date.now() - budget.executions.get(execution.id).started))));
+    try {
+      const result = await rpc.request('turn/start', { sessionId, message: [{ type: 'text', text }] });
+      const completed = completedTurns.has(result.turn.id) ? Promise.resolve(completedTurns.get(result.turn.id)) : new Promise(resolve => turns.set(result.turn.id, resolve));
+      let onExit;
+      const died = new Promise((_, reject) => { onExit = () => reject(new Error('native turn ended without completion')); rpc.child.once('exit', onExit); });
+      const done = await Promise.race([completed, died]).finally(() => rpc.child.removeListener('exit', onExit)); turns.delete(result.turn.id);
+      if (done.status !== 'completed') throw new Error('native turn incomplete');
+      const stats = await rpc.request('stats/read', { sessionId });
+      account(sessionId, stats.stats);
+      const state = await rpc.request('session/read', { sessionId });
+      // Delegated calls are included; unavailable child accounting is partial.
+      for (const child of state.state?.childSessions ?? []) {
+        cleanup.sessions.push(child.id);
+        const childStats = await rpc.request('stats/read', { sessionId: child.id });
+        sessions.set(child.id, execution); account(child.id, childStats.stats);
+      }
+      return [...(history.get(sessionId)?.values() ?? [])];
+    } finally { clearTimeout(watchdog); }
+  };
+  const result = { skills: 'partial', MCP: 'partial', context: 'partial', guard: 'partial', lifecycle: 'partial', sessions: [], runtimeVersion: undefined };
+  const mcpContexts = [], skillContexts = [];
+  try {
+    const initialized = await rpc.request('initialize', { clientInfo: { name: 'h2a-qualification', version: '1' }, capabilities: { callbackKinds: ['approval'] } });
+    result.runtimeVersion = initialized.serverInfo?.version; rpc.notify('initialized');
+    if (phase === 1) {
+      for (const [i, id] of ['phase1-a', 'phase1-b'].entries()) {
+        const sessionId = await start(id, workspaces[i]); result.sessions.push(sessionId);
+        const skills = await rpc.request('skills/list', { sessionId });
+        const runtime = await rpc.request('runtime/read', { sessionId });
+        result.probeTools = (runtime.runtime?.tools ?? []).map(t => t.name).filter(name => ['read_file', 'file_system.read_file', 'file_read'].includes(name) || /(?:h2a_identity_status|h2a_session_open|track_status)$/.test(name));
+        const names = (skills.skills ?? []).filter(s => s.enabled && s.source === 'local').map(s => s.name);
+        evidence.push({ method: 'qualification/skills', sessionId, names, runtimeHash: sha(runtime.runtime) });
+        if (components.some(c => ['skills', 'MCP', 'context'].includes(c))) {
+          const prompt = 'Use the installed H2A skill. Read the required skill resources at ' + requiredResources.map(r => r.path).join(', ') +
+            (components.some(c => ['MCP', 'context'].includes(c)) ? '. Use MCP tools h2a_identity_status and h2a_session_open to report this session identity, bus root and workspace, then track_status with level=task and baselineCommit=qualification for this workspace.' : '') + ' Do not run shell commands.';
+          const entries = await turn(sessionId, prompt);
+          calls.push(...entries); mcpContexts.push(inspectMcpEntries(entries, sessionId, { busRoot, workspace: workspaces[i] }));
+          skillContexts.push(names.includes('h2a') && names.includes('track-operation') && inspectSkillEntries(entries, requiredResources));
+        }
+      }
+      if (skillContexts.length === 2 && skillContexts.every(Boolean)) result.skills = 'observed';
+      if (mcpContexts.length === 2 && mcpContexts.every(c => c.MCP)) result.MCP = 'observed';
+      if (mcpContexts.length === 2 && mcpContexts.every(c => c.context) && mcpContexts[0].h2aSessionId !== mcpContexts[1].h2aSessionId) result.context = 'observed';
+    } else {
+      const origin = await start('phase2-origin', workspaces[0]); result.sessions.push(origin);
+      lifecycleOrigin = origin; recordBaseline = recordSnapshot();
+      const allocation = budget.begin('phase2-copy');
+      const fork = await rpc.request('session/fork', { sourceSessionId: origin, attach: PHASE2_RECIPE.fork.attach });
+      const copy = fork.state?.session;
+      if (!copy?.id || copy.parentSessionId !== origin) throw new Error('native fork context mismatch');
+      cleanup.sessions.push(copy.id); result.sessions.push(copy.id);
+      const originEntries = await turn(origin, 'Delegate exactly one brief read-only task to one subagent, then answer once. Do not use shell or mutate files.');
+      const parentRecord = recordSnapshot();
+      await rpc.request('session/resume', { sessionId: copy.id, agentConfig: { cwd: workspaces[0], headless: true, maxTurns: allocation.maxIterations, maxPrice: allocation.maxPrice } });
+      sessions.set(copy.id, { id: allocation.id, allocation, started: Date.now(), cwd: workspaces[0] });
+      const copyEntries = await turn(copy.id, 'Run exactly printf vibe-guard-ok, then request h2a --version to exercise the installed guard, then answer once. Do not run other commands.');
+      result.lifecycleRecordUnchangedInFork = JSON.stringify(parentRecord) === JSON.stringify(recordSnapshot());
+      result.parentRecordPresent = !!parentRecord?.own;
+      result.recordedAfterParent = !!parentHookStarted && !!parentRecord?.own?.stoppedAt && Date.parse(parentRecord.own.stoppedAt) >= parentHookStarted;
+      result.childRecordUntouched = childRecordUntouched; result.parentRecordTransitions = parentRecordTransitions;
+      result.otherInstancesUntouched = JSON.stringify(parentRecord?.others) === JSON.stringify(recordBaseline?.others);
+      calls.push(...originEntries, ...copyEntries);
+      if (inspectGuardEntries(copyEntries, copy.id)) result.guard = 'observed';
+      if (inspectLifecycleEntries(calls, origin, copy.id, result)) result.lifecycle = 'observed';
+    }
+    result.observedEntries = calls.map(e => ({ type: e.type, sessionId: e.sessionId, sha256: sha(e), detail: e.type === 'notice' ? { kind: e.detail?.kind, scope: e.detail?.scope, hookName: e.detail?.hookName, status: e.detail?.status, toolCallId: e.detail?.toolCallId } : undefined }));
+    return result;
+  } finally {
+    // Stop producers before deleting only recorded qualification sessions.
+    for (const id of [...new Set(cleanup.sessions)].reverse()) {
+      try { await rpc.request('session/stop', { sessionId: id }); }
+      catch { cleanup.incomplete = true; }
+    }
+    try { await clearRecords(); } catch { cleanup.incomplete = true; }
+    for (const id of [...new Set(cleanup.sessions)].reverse()) {
+      try { await rpc.request('session/delete', { sessionId: id }); cleanup.deleted.push(id); }
+      catch { cleanup.incomplete = true; }
+    }
+    await rpc.close();
+  }
+}