@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-hooks-boundary-model.mjs

@@ -0,0 +1,356 @@
+export function createRuntimeHooksBoundaryModel(deps) {
+  const {
+    path,
+    jsonSchemaVersion,
+    stateRootName,
+    workflowFileName,
+    hookRunsDirectoryName,
+    hookHeartbeatsDirectoryName,
+    digestObject,
+    validateCommonArtifactSafety,
+  } = deps;
+
+  const hookIntentSources = Object.freeze(['session_start', 'file_change', 'approval_transition', 'queue_ready']);
+  const hookIntentAllowedFollowup = Object.freeze(['scheduler-plan-only']);
+  const boundedRunAllowedFollowup = Object.freeze(['trace-governance-attestation-only']);
+
+  function hookIntentCatalog() {
+    const sources = hookIntentSources.map((source) => ({
+      source,
+      default_enabled: false,
+      allowed_followup: [...hookIntentAllowedFollowup],
+      writes_by_default: false,
+      scheduler_execution: false,
+      subagent_dispatch: false,
+      platform_api: false,
+    }));
+    const catalog = { stage: 'Stage 33', version: 1, source: 'builtin-data-only', dynamic_code: false, remote_config: false, default_enabled: false, sources };
+    return { ...catalog, catalog_digest: digestObject(catalog) };
+  }
+
+  function hookIntentSafety({ writes = false } = {}) {
+    return {
+      stage: 'Stage 33',
+      writes: Boolean(writes),
+      hook_intent_artifact: Boolean(writes),
+      hook_triggered: false,
+      scheduler_selected: false,
+      scheduler_plan: false,
+      subagent_dispatch: false,
+      session_create: false,
+      external_api: false,
+      external_delivery: false,
+      model_invocation: false,
+      runtime_action: false,
+      auto_execution: false,
+      controlled_auto_execution: false,
+      platform_api: false,
+      skill_execution: false,
+      business_source_write: false,
+      subagent: false,
+      mcp: false,
+      daemon: false,
+      git: false,
+      worktree: false,
+      dispatch_event_modified: false,
+      claim_modified: false,
+    };
+  }
+
+  function hookIntentPayload(root, { workflowPresent = false, workflowDigest = '', rootPath = root } = {}) {
+    const catalog = hookIntentCatalog();
+    const sourceDescriptors = [
+      { type: 'workflow', file: workflowPresent ? workflowFileName : '', digest: workflowDigest, present: workflowPresent },
+    ];
+    const payload = {
+      version: 1,
+      stage: 'Stage 33',
+      created_at: new Date().toISOString(),
+      hook_source: 'session_start',
+      trigger_reason: 'explicit hooks --preview command',
+      allowed_sources: [...hookIntentSources],
+      allowed_followup: [...hookIntentAllowedFollowup],
+      event_digest: digestObject({ root: rootPath, workflow_present: workflowPresent, workflow_digest: workflowDigest, allowed_sources: [...hookIntentSources] }),
+      source_descriptors: sourceDescriptors,
+      source_digest: digestObject(sourceDescriptors),
+      catalog_digest: catalog.catalog_digest,
+      default_enabled: false,
+      hook_enabled: false,
+      scheduler_execution: false,
+      subagent_dispatch: false,
+      platform_api: false,
+      local_only: true,
+      no_execution: true,
+      no_scheduler_run: true,
+      no_subagent_dispatch: true,
+    };
+    return { ...payload, intent_digest: digestObject(payload) };
+  }
+
+  function hookIntentEnvelope(root, { persist = false, statePresent = false, workflowPresent = false, workflowDigest = '', rootPath = root } = {}) {
+    const intent = hookIntentPayload(root, { workflowPresent, workflowDigest, rootPath });
+    return {
+      mode: 'hook-intent',
+      ok: true,
+      state_present: Boolean(statePresent),
+      hook_intent: { ...intent, writes: Boolean(persist) },
+      safety: hookIntentSafety({ writes: persist }),
+      quality: [],
+      action: persist
+        ? 'hook intent artifact was written locally. No scheduler run, subagent dispatch, platform API, hook execution, git, worktree, or business source write occurred.'
+        : 'hook intent was previewed read-only. No files were written and no scheduler run or subagent dispatch occurred.',
+    };
+  }
+
+  function validateHookIntentArtifact(root, artifact) {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'hooks') failures.push('command must be hooks');
+    if (artifact.mode !== 'hook-intent') failures.push('mode must be hook-intent');
+    const intent = artifact.hook_intent || {};
+    if (intent.stage !== 'Stage 33') failures.push('hook_intent.stage must be Stage 33');
+    const digestPayload = { ...intent };
+    delete digestPayload.writes;
+    delete digestPayload.intent_digest;
+    if (intent.intent_digest !== digestObject(digestPayload)) failures.push('hook intent digest mismatch');
+    if (intent.catalog_digest !== hookIntentCatalog().catalog_digest) failures.push('hook intent catalog digest mismatch');
+    if (intent.default_enabled !== false) failures.push('hook intent default_enabled must be false');
+    if (intent.hook_enabled !== false) failures.push('hook intent hook_enabled must be false');
+    if (intent.scheduler_execution !== false) failures.push('hook intent scheduler_execution must be false');
+    if (intent.subagent_dispatch !== false) failures.push('hook intent subagent_dispatch must be false');
+    if (intent.platform_api !== false) failures.push('hook intent platform_api must be false');
+    if (intent.local_only !== true) failures.push('hook intent local_only must be true');
+    if (intent.no_execution !== true) failures.push('hook intent no_execution must be true');
+    if (intent.no_scheduler_run !== true) failures.push('hook intent no_scheduler_run must be true');
+    if (intent.no_subagent_dispatch !== true) failures.push('hook intent no_subagent_dispatch must be true');
+    if (intent.hook_source !== 'session_start') failures.push('hook intent hook_source must be session_start');
+    if (!Array.isArray(intent.allowed_followup) || digestObject(intent.allowed_followup) !== digestObject([...hookIntentAllowedFollowup])) failures.push('hook intent allowed_followup must equal scheduler-plan-only');
+    if (!Array.isArray(intent.allowed_sources) || digestObject(intent.allowed_sources) !== digestObject([...hookIntentSources])) failures.push('hook intent allowed_sources mismatch');
+    if (!Array.isArray(intent.source_descriptors)) failures.push('hook intent source_descriptors must be an array');
+    else {
+      if (intent.source_digest !== digestObject(intent.source_descriptors)) failures.push('hook intent source_digest mismatch');
+    }
+    failures.push(...validateCommonArtifactSafety(artifact.safety, 'Stage 33'));
+    for (const key of ['hook_triggered', 'scheduler_selected', 'scheduler_plan', 'subagent_dispatch', 'session_create', 'external_api', 'external_delivery', 'model_invocation']) {
+      if (artifact.safety?.[key] !== false) failures.push(`safety.${key} must be false`);
+    }
+    return { ok: failures.length === 0, failures };
+  }
+
+  function hookBoundedRunSafety(persist) {
+    return {
+      stage: 'Stage 39',
+      writes: Boolean(persist),
+      hook_run_artifact: Boolean(persist),
+      hook_heartbeat_artifact: Boolean(persist),
+      foreground_loop: true,
+      bounded_loop: true,
+      scheduler_plan: false,
+      scheduler_run: false,
+      session_create: false,
+      subagent_dispatch: false,
+      platform_api: false,
+      external_api: false,
+      external_delivery: false,
+      model_invocation: false,
+      runtime_action: false,
+      auto_execution: false,
+      controlled_auto_execution: false,
+      skill_execution: false,
+      business_source_write: false,
+      subagent: false,
+      mcp: false,
+      daemon: false,
+      watcher: false,
+      git: false,
+      worktree: false,
+      dispatch_event_modified: false,
+      claim_modified: false,
+    };
+  }
+
+  function hookRunEnvelope(root, { persist = false, maxIterations = 1, timestamp, hookRunFile, heartbeatFile, statePresent = false } = {}) {
+    const iterations = Number.isInteger(maxIterations) && maxIterations > 0 ? maxIterations : 1;
+    const policy = {
+      name: 'stage-39-hook-driven-bounded-loop',
+      version: 1,
+      stage: 'Stage 39',
+      default_enabled: false,
+      foreground_only: true,
+      bounded: true,
+      max_iterations: iterations,
+      long_running: false,
+      hidden_worker: false,
+      watcher: false,
+      daemon: false,
+      platform_api: false,
+      session_create: false,
+      subagent_dispatch: false,
+      allowed_followup: [...boundedRunAllowedFollowup],
+    };
+    const policyDigest = digestObject(policy);
+    const core = {
+      version: 1,
+      stage: 'Stage 39',
+      created_at: timestamp,
+      writes: Boolean(persist),
+      run_status: 'completed-bounded-foreground-audit',
+      max_iterations: iterations,
+      iterations_completed: 1,
+      stop_file_required: true,
+      stop_file_observed: false,
+      lease_required: true,
+      lease_acquired: true,
+      heartbeat_file: heartbeatFile,
+      heartbeat_digest: '',
+      allowed_hook_sources: ['session_start'],
+      scheduler_plan_allowed: true,
+      scheduler_run_allowed: false,
+      subagent_dispatch_allowed: false,
+      session_create: false,
+      platform_api: false,
+      model_invocation: false,
+      external_delivery: false,
+      business_source_write: false,
+      git: false,
+      worktree: false,
+      foreground_only: true,
+      bounded: true,
+      long_running: false,
+      hidden_worker: false,
+      watcher: false,
+      daemon: false,
+      policy_digest: policyDigest,
+      allowed_followup: [...boundedRunAllowedFollowup],
+      planned_writes: persist ? [
+        path.join(stateRootName, hookRunsDirectoryName, '<timestamp>.hook-run.json').replace(/\\/g, '/'),
+        path.join(stateRootName, hookHeartbeatsDirectoryName, '<timestamp>.hook-heartbeat.json').replace(/\\/g, '/'),
+      ] : [],
+    };
+    const heartbeatCore = {
+      version: 1,
+      stage: 'Stage 39',
+      created_at: timestamp,
+      writes: Boolean(persist),
+      run_file: hookRunFile,
+      run_status: core.run_status,
+      iteration: 1,
+      max_iterations: iterations,
+      foreground_only: true,
+      bounded: true,
+      long_running: false,
+      watcher: false,
+      daemon: false,
+      platform_api: false,
+      session_create: false,
+      subagent_dispatch: false,
+    };
+    const heartbeat = { ...heartbeatCore, heartbeat_digest: digestObject(heartbeatCore) };
+    const run = { ...core, heartbeat_digest: digestObject(heartbeat), run_digest: digestObject({ ...core, heartbeat_digest: digestObject(heartbeat) }) };
+    return {
+      mode: 'hook-bounded-run',
+      ok: true,
+      state_present: Boolean(statePresent),
+      hook_run: run,
+      hook_heartbeat: heartbeat,
+      policy: { ...policy, policy_digest: policyDigest },
+      files: { hook_run: hookRunFile, heartbeat: heartbeatFile },
+      safety: hookBoundedRunSafety(persist),
+      quality: [],
+      action: persist
+        ? 'bounded hook run artifacts were written locally. No long-running worker, scheduler run, subagent dispatch, platform API, git, worktree, or business source write occurred.'
+        : 'bounded hook run was previewed read-only. No files were written and no hook loop executed.',
+    };
+  }
+
+  function validateHookRunArtifact(_root, artifact, fileName = '') {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'hooks') failures.push('command must be hooks');
+    if (artifact.mode !== 'hook-bounded-run') failures.push('mode must be hook-bounded-run');
+    const run = artifact.hook_run || {};
+    const heartbeat = artifact.hook_heartbeat || {};
+    const files = artifact.files || {};
+    if (!files.hook_run || !String(files.hook_run).endsWith('.hook-run.json')) failures.push('files.hook_run must be a hook run artifact');
+    if (!files.heartbeat || !String(files.heartbeat).endsWith('.hook-heartbeat.json')) failures.push('files.heartbeat must be a hook heartbeat artifact');
+    if (fileName) {
+      if (fileName.endsWith('.hook-run.json') && files.hook_run !== fileName) failures.push('Stage 39 hook run file identity mismatch');
+      else if (fileName.endsWith('.hook-heartbeat.json') && files.heartbeat !== fileName) failures.push('Stage 39 hook heartbeat file identity mismatch');
+      else if (!fileName.endsWith('.hook-run.json') && !fileName.endsWith('.hook-heartbeat.json')) failures.push('Stage 39 artifact file extension is unsupported');
+    }
+    if (heartbeat.run_file !== files.hook_run) failures.push('hook_heartbeat.run_file must match files.hook_run');
+    if (run.heartbeat_file !== files.heartbeat) failures.push('hook_run.heartbeat_file must match files.heartbeat');
+    if (run.version !== 1 || heartbeat.version !== 1) failures.push('hook run and heartbeat version must be 1');
+    if (run.stage !== 'Stage 39' || heartbeat.stage !== 'Stage 39') failures.push('hook run and heartbeat stage must be Stage 39');
+    if (run.writes !== true || heartbeat.writes !== true) failures.push('hook run and heartbeat writes must be true');
+    if (run.run_status !== 'completed-bounded-foreground-audit') failures.push('hook_run.run_status must be completed-bounded-foreground-audit');
+    if (!Number.isInteger(run.max_iterations) || run.max_iterations < 1 || run.max_iterations > 5) failures.push('hook_run.max_iterations must be between 1 and 5');
+    if (heartbeat.max_iterations !== run.max_iterations) failures.push('hook heartbeat max_iterations mismatch');
+    if (heartbeat.run_status !== run.run_status) failures.push('hook heartbeat run_status mismatch');
+    if (!Array.isArray(run.allowed_hook_sources) || digestObject(run.allowed_hook_sources) !== digestObject(['session_start'])) failures.push('hook_run.allowed_hook_sources must equal session_start');
+    if (!Array.isArray(run.allowed_followup) || digestObject(run.allowed_followup) !== digestObject([...boundedRunAllowedFollowup])) failures.push('hook_run.allowed_followup must equal trace-governance-attestation-only');
+    if (!Array.isArray(run.planned_writes) || digestObject(run.planned_writes) !== digestObject([
+      path.join(stateRootName, hookRunsDirectoryName, '<timestamp>.hook-run.json').replace(/\\/g, '/'),
+      path.join(stateRootName, hookHeartbeatsDirectoryName, '<timestamp>.hook-heartbeat.json').replace(/\\/g, '/'),
+    ])) failures.push('hook_run.planned_writes must match Stage 39 write whitelist');
+    for (const key of ['stop_file_required', 'lease_required', 'lease_acquired', 'scheduler_plan_allowed', 'foreground_only', 'bounded']) if (run[key] !== true) failures.push(`hook_run.${key} must be true`);
+    for (const key of ['stop_file_observed', 'scheduler_run_allowed', 'subagent_dispatch_allowed', 'session_create', 'platform_api', 'model_invocation', 'external_delivery', 'business_source_write', 'git', 'worktree', 'long_running', 'hidden_worker', 'watcher', 'daemon']) if (run[key] !== false) failures.push(`hook_run.${key} must be false`);
+    for (const key of ['foreground_only', 'bounded']) if (heartbeat[key] !== true) failures.push(`hook_heartbeat.${key} must be true`);
+    for (const key of ['long_running', 'watcher', 'daemon', 'platform_api', 'session_create', 'subagent_dispatch']) if (heartbeat[key] !== false) failures.push(`hook_heartbeat.${key} must be false`);
+    const heartbeatDigestPayload = { ...heartbeat };
+    delete heartbeatDigestPayload.heartbeat_digest;
+    const heartbeatDigest = digestObject(heartbeatDigestPayload);
+    if (heartbeat.heartbeat_digest !== heartbeatDigest) failures.push('hook_heartbeat digest mismatch');
+    if (run.heartbeat_digest !== digestObject(heartbeat)) failures.push('hook_run heartbeat digest mismatch');
+    const runDigestPayload = { ...run };
+    delete runDigestPayload.run_digest;
+    if (run.run_digest !== digestObject(runDigestPayload)) failures.push('hook_run digest mismatch');
+    const expectedPolicy = {
+      name: 'stage-39-hook-driven-bounded-loop',
+      version: 1,
+      stage: 'Stage 39',
+      default_enabled: false,
+      foreground_only: true,
+      bounded: true,
+      max_iterations: run.max_iterations,
+      long_running: false,
+      hidden_worker: false,
+      watcher: false,
+      daemon: false,
+      platform_api: false,
+      session_create: false,
+      subagent_dispatch: false,
+      allowed_followup: [...boundedRunAllowedFollowup],
+    };
+    const actualPolicy = { ...(artifact.policy || {}) };
+    delete actualPolicy.policy_digest;
+    if (digestObject(actualPolicy) !== digestObject(expectedPolicy)) failures.push('Stage 39 policy fields must match bounded foreground policy');
+    if (artifact.policy?.policy_digest !== digestObject(expectedPolicy)) failures.push('Stage 39 policy digest mismatch');
+    if (run.policy_digest !== digestObject(expectedPolicy)) failures.push('hook_run policy digest mismatch');
+    const safety = artifact.safety || {};
+    if (safety.stage !== 'Stage 39') failures.push('safety.stage must be Stage 39');
+    for (const key of ['writes', 'hook_run_artifact', 'hook_heartbeat_artifact', 'foreground_loop', 'bounded_loop']) if (safety[key] !== true) failures.push(`safety.${key} must be true`);
+    for (const key of ['scheduler_plan', 'scheduler_run', 'session_create', 'subagent_dispatch', 'platform_api', 'external_api', 'external_delivery', 'model_invocation', 'runtime_action', 'auto_execution', 'controlled_auto_execution', 'skill_execution', 'business_source_write', 'subagent', 'mcp', 'daemon', 'watcher', 'git', 'worktree', 'dispatch_event_modified', 'claim_modified']) if (safety[key] !== false) failures.push(`safety.${key} must be false`);
+    return { ok: failures.length === 0, failures };
+  }
+
+  return Object.freeze({
+    hookIntentCatalog,
+    hookIntentEnvelope,
+    validateHookIntentArtifact,
+    hookRunEnvelope,
+    validateHookRunArtifact,
+  });
+}
+
+export function hookAuditListActionText() {
+  return 'read-only hook audit listed local intents, bounded hook runs, and heartbeats. No hook, scheduler, or subagent execution occurred.';
+}
+
+export function hookRunAuditActionText() {
+  return 'read-only hook run audit inspected one bounded hook artifact. No scheduler or subagent execution occurred.';
+}
+
+export function hookIntentAuditActionText() {
+  return 'read-only hook intent audit inspected one intent. No hook, scheduler, or subagent execution occurred.';
+}

package/tools/vibe-runtime/runtime-hooks-command.mjs

@@ -0,0 +1,286 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  createRuntimeHooksBoundaryModel,
+  hookAuditListActionText,
+  hookIntentAuditActionText,
+  hookRunAuditActionText,
+} from './runtime-hooks-boundary-model.mjs';
+
+export function createRuntimeHooksCommand(deps) {
+  const {
+    jsonSchemaVersion,
+    stateDirectoryName,
+    workflowFileName,
+    hookRunsDirectoryName,
+    hookHeartbeatsDirectoryName,
+    ensureRoot,
+    stateDirectory,
+    workflowPath,
+    fileDigest,
+    digestObject,
+    validateCommonArtifactSafety,
+    writeStateArtifact,
+    writeJsonEnvelope,
+    printList,
+    readJsonArtifact,
+    listStateFiles,
+    hookIntentsDirectory,
+    hookRunsDirectory,
+    hookHeartbeatsDirectory,
+    hookIntentFilePath,
+    hookRunFilePath,
+    hookHeartbeatFilePath,
+  } = deps;
+
+  const hooksBoundaryModel = createRuntimeHooksBoundaryModel({
+    fs,
+    path,
+    jsonSchemaVersion,
+    stateRootName: stateDirectoryName,
+    workflowFileName,
+    hookRunsDirectoryName,
+    hookHeartbeatsDirectoryName,
+    stateDirectory,
+    workflowPath,
+    fileDigest,
+    digestObject,
+    validateCommonArtifactSafety,
+  });
+
+  const hookIntentCatalog = hooksBoundaryModel.hookIntentCatalog;
+  function validateHookIntentArtifact(root, artifact) {
+    const verification = hooksBoundaryModel.validateHookIntentArtifact(root, artifact);
+    const failures = verification.failures.slice();
+    const intent = artifact.hook_intent || {};
+    for (const descriptor of intent.source_descriptors || []) {
+      if (descriptor.type === 'workflow' && descriptor.present) {
+        try {
+          const workflow = workflowPath(root);
+          if (path.basename(workflow) !== descriptor.file) failures.push('hook intent workflow file mismatch');
+          if (fileDigest(workflow) !== descriptor.digest) failures.push('hook intent workflow digest mismatch');
+        } catch (error) {
+          failures.push(error.message);
+        }
+      }
+    }
+    return { ok: failures.length === 0, failures };
+  }
+
+  function hookIntentSnapshotPath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(hookIntentsDirectory(root), `${timestamp}.hook-intent.json`);
+  }
+
+  function listHookIntentFiles(root) {
+    return listStateFiles(root, hookIntentsDirectory, '.hook-intent.json');
+  }
+
+  function hookIntentEnvelope(root, { persist = false } = {}) {
+    const workflowFile = workflowPath(root);
+    const workflowPresent = fs.existsSync(workflowFile);
+    return hooksBoundaryModel.hookIntentEnvelope(root, {
+      persist,
+      statePresent: fs.existsSync(stateDirectory(root)),
+      workflowPresent,
+      workflowDigest: workflowPresent ? fileDigest(workflowFile) : '',
+      rootPath: path.resolve(root),
+    });
+  }
+
+  function writeHookIntent(root, envelope) {
+    const file = hookIntentSnapshotPath(root);
+    const payload = { schema_version: jsonSchemaVersion, command: 'hooks', ...envelope, safety: { ...envelope.safety, hook_intent_artifact: true } };
+    const verification = validateHookIntentArtifact(root, payload);
+    if (!verification.ok) throw new Error(`hook intent verification failed: ${verification.failures.join('; ')}`);
+    return writeStateArtifact(path.dirname(file), path.basename(file), payload);
+  }
+
+  function listHookRunFiles(root) {
+    return listStateFiles(root, hookRunsDirectory, '.hook-run.json');
+  }
+
+  function listHookHeartbeatFiles(root) {
+    return listStateFiles(root, hookHeartbeatsDirectory, '.hook-heartbeat.json');
+  }
+
+  function hookRunSnapshotPath(root, timestamp) {
+    return path.join(hookRunsDirectory(root), `${timestamp}.hook-run.json`);
+  }
+
+  function hookHeartbeatSnapshotPath(root, timestamp) {
+    return path.join(hookHeartbeatsDirectory(root), `${timestamp}.hook-heartbeat.json`);
+  }
+
+  function hookRunEnvelope(root, { persist = false, maxIterations = 1 } = {}) {
+    ensureRoot(root);
+    const iterations = Number.isInteger(maxIterations) && maxIterations > 0 ? maxIterations : 1;
+    if (iterations > 5) throw new Error('hooks --hook-run max iterations must be <= 5');
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return hooksBoundaryModel.hookRunEnvelope(root, {
+      persist,
+      maxIterations: iterations,
+      timestamp: new Date().toISOString(),
+      hookRunFile: path.basename(hookRunSnapshotPath(root, timestamp)),
+      heartbeatFile: path.basename(hookHeartbeatSnapshotPath(root, timestamp)),
+      statePresent: fs.existsSync(stateDirectory(root)),
+    });
+  }
+
+  const validateHookRunArtifact = hooksBoundaryModel.validateHookRunArtifact;
+
+  function writeHookRun(root, envelope) {
+    const runFile = hookRunSnapshotPath(root, envelope.files.hook_run.replace('.hook-run.json', ''));
+    const heartbeatFile = hookHeartbeatSnapshotPath(root, envelope.files.heartbeat.replace('.hook-heartbeat.json', ''));
+    const payload = { schema_version: jsonSchemaVersion, command: 'hooks', ...envelope, safety: { ...envelope.safety, hook_run_artifact: true, hook_heartbeat_artifact: true } };
+    const verification = validateHookRunArtifact(root, payload, path.basename(runFile));
+    if (!verification.ok) throw new Error(`hook run verification failed: ${verification.failures.join('; ')}`);
+    writeStateArtifact(path.dirname(runFile), path.basename(runFile), payload);
+    writeStateArtifact(path.dirname(heartbeatFile), path.basename(heartbeatFile), payload);
+    return { runFile, heartbeatFile };
+  }
+
+  function printHookRun(envelope, files = null) {
+    console.log('Vibecoding Runtime Hook Bounded Run');
+    console.log(`Mode: ${envelope.mode}`);
+    console.log(`Iterations: ${envelope.hook_run.iterations_completed}/${envelope.hook_run.max_iterations}`);
+    console.log(`Status: ${envelope.hook_run.run_status}`);
+    if (files) {
+      console.log(`Hook run: ${path.relative(process.cwd(), files.runFile)}`);
+      console.log(`Heartbeat: ${path.relative(process.cwd(), files.heartbeatFile)}`);
+    }
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function hookIntentAuditEnvelope(root, mode, hookIntentFile = '') {
+    if (mode === 'catalog') return { mode: 'hooks-catalog', ok: true, catalog: hookIntentCatalog(), quality: [], action: 'read-only hook intent catalog was shown. No files were written.' };
+    if (mode === 'list') {
+      const intents = listHookIntentFiles(root).map((fileName) => {
+        try {
+          const file = hookIntentFilePath(root, fileName);
+          const artifact = readJsonArtifact(file, 'Hook intent');
+          const verification = validateHookIntentArtifact(root, artifact);
+          return { file: fileName, hook_source: artifact.hook_intent?.hook_source || '', ok: verification.ok, verification_failures: verification.failures, kind: 'hook-intent' };
+        } catch (error) {
+          return { file: fileName, hook_source: '', ok: false, verification_failures: [error.message], kind: 'hook-intent' };
+        }
+      });
+      const runs = listHookRunFiles(root).map((fileName) => {
+        try {
+          const file = hookRunFilePath(root, fileName);
+          const artifact = readJsonArtifact(file, 'Hook run');
+          const verification = validateHookRunArtifact(root, artifact, fileName);
+          return { file: fileName, hook_source: artifact.hook_run?.allowed_hook_sources?.join(',') || '', ok: verification.ok, verification_failures: verification.failures, kind: 'hook-run' };
+        } catch (error) {
+          return { file: fileName, hook_source: '', ok: false, verification_failures: [error.message], kind: 'hook-run' };
+        }
+      });
+      const heartbeats = listHookHeartbeatFiles(root).map((fileName) => {
+        try {
+          const file = hookHeartbeatFilePath(root, fileName);
+          const artifact = readJsonArtifact(file, 'Hook heartbeat');
+          const verification = validateHookRunArtifact(root, artifact, fileName);
+          return { file: fileName, hook_source: artifact.hook_run?.allowed_hook_sources?.join(',') || '', ok: verification.ok, verification_failures: verification.failures, kind: 'hook-heartbeat' };
+        } catch (error) {
+          return { file: fileName, hook_source: '', ok: false, verification_failures: [error.message], kind: 'hook-heartbeat' };
+        }
+      });
+      const all = [...intents, ...runs, ...heartbeats];
+      return { mode: 'hooks-list', ok: true, summary: { count: all.length, intent_count: intents.length, run_count: runs.length, heartbeat_count: heartbeats.length, failed_count: all.filter((item) => !item.ok).length }, hook_intents: all, quality: [], action: hookAuditListActionText() };
+    }
+    if (hookIntentFile.endsWith('.hook-run.json') || hookIntentFile.endsWith('.hook-heartbeat.json')) {
+      const file = hookIntentFile.endsWith('.hook-run.json') ? hookRunFilePath(root, hookIntentFile) : hookHeartbeatFilePath(root, hookIntentFile);
+      const artifact = readJsonArtifact(file, 'Hook run');
+      const verification = validateHookRunArtifact(root, artifact, path.basename(file));
+      if (mode === 'verify' && !verification.ok) throw new Error(`hook run verification failed: ${verification.failures.join('; ')}`);
+      return { mode: mode === 'verify' ? 'hook-run-verify' : 'hook-run-show', ok: verification.ok, summary: { file: path.basename(file), max_iterations: artifact.hook_run?.max_iterations || 0, stop_file_required: artifact.hook_run?.stop_file_required === true }, verification, artifact, quality: verification.failures, action: hookRunAuditActionText() };
+    }
+    const file = hookIntentFilePath(root, hookIntentFile);
+    const artifact = readJsonArtifact(file, 'Hook intent');
+    const verification = validateHookIntentArtifact(root, artifact);
+    if (mode === 'verify' && !verification.ok) throw new Error(`hook intent verification failed: ${verification.failures.join('; ')}`);
+    return { mode: mode === 'verify' ? 'hooks-verify' : 'hooks-show', ok: verification.ok, summary: { file: path.basename(file), hook_source: artifact.hook_intent?.hook_source || '', allowed_followup: artifact.hook_intent?.allowed_followup || [] }, verification, artifact, quality: verification.failures, action: hookIntentAuditActionText() };
+  }
+
+  function printHooks(envelope, file = '') {
+    console.log('Vibecoding Runtime Hook Intent');
+    console.log(`Mode: ${envelope.mode.replace('hooks-', '')}`);
+    if (envelope.mode === 'hooks-catalog') {
+      console.log(`Sources: ${envelope.catalog.sources.length}; Digest: ${envelope.catalog.catalog_digest}`);
+      for (const source of envelope.catalog.sources) console.log(`- ${source.source}: default_enabled=${source.default_enabled}; followup=${source.allowed_followup.join(',')}`);
+    } else if (envelope.hook_intent) {
+      console.log(`Hook source: ${envelope.hook_intent.hook_source}`);
+      console.log(`Allowed followup: ${envelope.hook_intent.allowed_followup.join(', ')}`);
+      if (file) console.log(`Hook intent: ${path.relative(process.cwd(), file)}`);
+    } else if (envelope.mode === 'hooks-list') {
+      console.log(`Hook intents: ${envelope.summary.count}; Failed: ${envelope.summary.failed_count}`);
+      for (const intent of envelope.hook_intents) console.log(`- ${intent.file}: source=${intent.hook_source || 'unknown'}; verification=${intent.ok ? 'passed' : 'failed'}`);
+    } else {
+      console.log(`File: ${envelope.summary.file}`);
+      console.log(`Hook source: ${envelope.summary.hook_source}`);
+      console.log(`Verification: ${envelope.verification.ok ? 'passed' : 'failed'}`);
+      if (envelope.verification.failures.length > 0) printList('Verification failures', envelope.verification.failures);
+    }
+    if (envelope.quality?.length > 0) printList('Blocked reasons', envelope.quality);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function runHooks(options) {
+    if (options.write || options.scan || options.once || options.fromDispatch || options.dispatchEvent || options.actor || options.approval || options.run || options.autoRun) throw new Error('hooks supports intent preview, bounded hook run, and read-only audit only');
+    ensureRoot(options.root);
+    const modes = [options.hooksCatalog, options.hooksPreview, options.hooksRun, options.hooksList, options.hooksShow, options.hooksVerify].filter(Boolean);
+    if (modes.length !== 1) throw new Error('hooks requires exactly one of --catalog, --preview, --hook-run, --list, --show, or --verify');
+    if (options.hooksCatalog) {
+      if (options.confirm || options.dryRun) throw new Error('hooks catalog is read-only');
+      const envelope = hookIntentAuditEnvelope(options.root, 'catalog');
+      if (options.json) writeJsonEnvelope('hooks', envelope);
+      else printHooks(envelope);
+      return;
+    }
+    if (options.hooksPreview) {
+      if (options.confirm && options.dryRun) throw new Error('hooks --preview accepts either preview or --confirm, not both');
+      const envelope = hookIntentEnvelope(options.root, { persist: options.confirm });
+      if (options.confirm) {
+        const file = writeHookIntent(options.root, envelope);
+        if (options.json) writeJsonEnvelope('hooks', { ...envelope, hook_intent_file: path.basename(file) });
+        else printHooks(envelope, file);
+        return;
+      }
+      if (options.json) writeJsonEnvelope('hooks', envelope);
+      else printHooks(envelope);
+      return;
+    }
+    if (options.hooksRun) {
+      if (!options.confirm) throw new Error('hooks --hook-run requires --confirm');
+      if (options.dryRun) throw new Error('hooks --hook-run does not accept --dry-run with --confirm');
+      const envelope = hookRunEnvelope(options.root, { persist: true, maxIterations: options.maxIterations });
+      const files = writeHookRun(options.root, envelope);
+      if (options.json) writeJsonEnvelope('hooks', { ...envelope, hook_run_file: path.basename(files.runFile), hook_heartbeat_file: path.basename(files.heartbeatFile) });
+      else printHookRun(envelope, files);
+      return;
+    }
+    if (options.confirm || options.dryRun) throw new Error('hooks audit is read-only');
+    const mode = options.hooksList ? 'list' : options.hooksVerify ? 'verify' : 'show';
+    const envelope = hookIntentAuditEnvelope(options.root, mode, options.hooksFile);
+    if (options.json) writeJsonEnvelope('hooks', envelope);
+    else printHooks(envelope);
+  }
+
+  return {
+    runHooks,
+    hookIntentCatalog,
+    listHookIntentFiles,
+    listHookRunFiles,
+    listHookHeartbeatFiles,
+    hookIntentEnvelope,
+    validateHookIntentArtifact,
+    writeHookIntent,
+    hookRunEnvelope,
+    validateHookRunArtifact,
+    writeHookRun,
+    hookIntentAuditEnvelope,
+    printHooks,
+    printHookRun,
+  };
+}