@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-state-paths.mjs

@@ -0,0 +1,231 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import * as safePaths from './state-safe-paths.mjs';
+
+export * from './runtime-state-risk-paths.mjs';
+export * from './state-safe-paths.mjs';
+
+export const approvalLifecycleFileName = createApprovalLifecycleFileName();
+export const approvalLifecycleFilePath = createApprovalLifecycleFilePath();
+export const safeStateArtifactFilePath = createSafeStateArtifactFilePath();
+export const candidateFilePath = artifactLocator(safePaths.executionCandidatesDirectory, '.candidate.json', 'Candidate');
+export const approvalFilePath = artifactLocator(safePaths.executionApprovalsDirectory, '.approval.json', 'Approval');
+export const autoRunLockFilePath = createAutoRunLockFilePath();
+export const recoveryFilePath = artifactLocator(safePaths.recoveryPackagesDirectory, '.recovery.json', 'Recovery');
+export const recoveryClassificationFilePath = artifactLocator(
+  safePaths.recoveryClassificationsDirectory,
+  '.recovery-classification.json',
+  'Recovery classification',
+);
+export const replyDraftFilePath = artifactLocator(safePaths.replyDraftsDirectory, '.reply-draft.json', 'Reply draft');
+export const replyReviewFilePath = artifactLocator(safePaths.replyReviewsDirectory, '.reply-review.json', 'Reply review');
+export const replyApprovalFilePath = artifactLocator(safePaths.replyApprovalsDirectory, '.reply-approval.json', 'Reply approval');
+export const replyOutboxFilePath = artifactLocator(safePaths.replyOutboxDirectory, '.reply-outbox.json', 'Reply outbox');
+export const replySendRunFilePath = artifactLocator(safePaths.replySendRunsDirectory, '.reply-send-run.json', 'Reply send run');
+export const runtimeTraceFilePath = artifactLocator(safePaths.runtimeTracesDirectory, '.runtime-trace.json', 'Runtime trace');
+export const governanceFilePath = artifactLocator(
+  safePaths.governanceDirectory,
+  '.governance-attestation.json',
+  'Governance attestation',
+);
+export const governancePrReadinessFilePath = artifactLocator(
+  safePaths.governanceDirectory,
+  '.pr-readiness-governance.json',
+  'PR readiness governance',
+);
+export const governancePrReviewIntakeFilePath = artifactLocator(
+  safePaths.governanceDirectory,
+  '.pr-review-intake-governance.json',
+  'PR review intake governance',
+);
+export const governanceAnyFilePath = createGovernanceAnyFilePath();
+export const hookIntentFilePath = artifactLocator(safePaths.hookIntentsDirectory, '.hook-intent.json', 'Hook intent');
+export const subagentEligibilityFilePath = artifactLocator(
+  safePaths.subagentEligibilityDirectory,
+  '.subagent-eligibility.json',
+  'Subagent eligibility',
+);
+export const subagentDispatchFilePath = artifactLocator(
+  safePaths.subagentDispatchesDirectory,
+  '.subagent-dispatch.json',
+  'Subagent dispatch',
+);
+export const subagentAdapterDispatchFilePath = artifactLocator(
+  safePaths.subagentAdapterDispatchesDirectory,
+  '.subagent-adapter-dispatch.json',
+  'Subagent adapter dispatch',
+);
+export const subagentRunResultFilePath = artifactLocator(
+  safePaths.subagentRunResultsDirectory,
+  '.subagent-run-result.json',
+  'Subagent run result',
+);
+export const subagentResultFilePath = artifactLocator(
+  safePaths.subagentResultsDirectory,
+  '.subagent-result.json',
+  'Subagent ingested result',
+);
+export const subagentReviewFilePath = artifactLocator(safePaths.subagentReviewsDirectory, '.subagent-review.json', 'Subagent review');
+export const hookRunFilePath = artifactLocator(safePaths.hookRunsDirectory, '.hook-run.json', 'Hook run');
+export const hookHeartbeatFilePath = artifactLocator(safePaths.hookHeartbeatsDirectory, '.hook-heartbeat.json', 'Hook heartbeat');
+export const platformCapabilityFilePath = artifactLocator(
+  safePaths.platformCapabilitiesDirectory,
+  '.platform-capability.json',
+  'Platform capability',
+);
+export const platformSessionApprovalFilePath = artifactLocator(
+  safePaths.platformSessionApprovalsDirectory,
+  '.platform-session-approval.json',
+  'Platform session approval',
+);
+export const platformSessionFilePath = artifactLocator(safePaths.platformSessionsDirectory, '.platform-session.json', 'Platform session');
+export const platformSessionResultFilePath = artifactLocator(
+  safePaths.platformSessionResultsDirectory,
+  '.platform-session-result.json',
+  'Platform session result',
+);
+export const platformSessionCancellationFilePath = artifactLocator(
+  safePaths.platformSessionCancellationsDirectory,
+  '.platform-session-cancel.json',
+  'Platform session cancellation',
+);
+export const platformSessionIntakeFilePath = artifactLocator(
+  safePaths.platformSessionIntakeDirectory,
+  '.platform-session-intake.json',
+  'Platform session intake',
+);
+export const platformSessionReviewFilePath = artifactLocator(
+  safePaths.platformSessionReviewsDirectory,
+  '.platform-session-review.json',
+  'Platform session review',
+);
+export const sourceChangeCandidateFilePath = artifactLocator(
+  safePaths.sourceChangeCandidatesDirectory,
+  '.source-change-candidate.json',
+  'Source change candidate',
+);
+export const sourceSandboxRunFilePath = artifactLocator(
+  safePaths.sourceSandboxRunsDirectory,
+  '.source-sandbox-run.json',
+  'Source sandbox run',
+);
+export const sourceVerificationFilePath = artifactLocator(
+  safePaths.sourceVerificationsDirectory,
+  '.source-verification.json',
+  'Source verification',
+);
+export const mergeReadinessFilePath = artifactLocator(safePaths.mergeReadinessDirectory, '.merge-readiness.json', 'Merge readiness');
+export const mergeApprovalFilePath = artifactLocator(safePaths.mergeApprovalsDirectory, '.merge-approval.json', 'Merge approval');
+export const mergeApplyFilePath = artifactLocator(safePaths.mergeAppliesDirectory, '.merge-apply.json', 'Merge apply');
+export const plannerRouteFilePath = artifactLocator(safePaths.plannerRoutesDirectory, '.planner-route.json', 'Planner route');
+export const plannerPlanFilePath = artifactLocator(safePaths.plannerPlansDirectory, '.planner-plan.json', 'Planner plan');
+export const plannerBriefsFilePath = artifactLocator(safePaths.plannerBriefsDirectory, '.planner-briefs.json', 'Planner briefs');
+export const routerPlanFilePath = artifactLocator(safePaths.routerPlansDirectory, '.router-plan.json', 'Router plan');
+export const routerApprovalFilePath = artifactLocator(safePaths.routerApprovalsDirectory, '.router-approval.json', 'Router approval');
+export const orchestratorPlanFilePath = artifactLocator(
+  safePaths.orchestratorPlansDirectory,
+  '.orchestrator-plan.json',
+  'Orchestrator plan',
+);
+export const orchestratorDispatchPlanFilePath = artifactLocator(
+  safePaths.orchestratorDispatchPlansDirectory,
+  '.orchestrator-dispatch-plan.json',
+  'Orchestrator dispatch plan',
+);
+export const evalSuiteFilePath = artifactLocator(safePaths.evalSuitesDirectory, '.eval-suite.json', 'Eval suite');
+export const evalRunFilePath = artifactLocator(safePaths.evalRunsDirectory, '.eval-run.json', 'Eval run');
+export const evalReportFilePath = artifactLocator(safePaths.evalReportsDirectory, '.eval-report.json', 'Eval report');
+export const releaseGateFilePath = artifactLocator(safePaths.releaseGatesDirectory, '.release-gate.json', 'Release gate');
+export const releaseNotesFilePath = artifactLocator(safePaths.releaseNotesDirectory, '.release-notes.json', 'Release notes');
+export const feedbackLedgerFilePath = artifactLocator(safePaths.feedbackLedgersDirectory, '.feedback-ledger.json', 'Feedback ledger');
+export const learningObservationFilePath = artifactLocator(
+  safePaths.learningDirectory,
+  '.learning-observation.json',
+  'Learning observation',
+);
+export const learningCandidateInstinctFilePath = artifactLocator(
+  safePaths.learningDirectory,
+  '.candidate-instinct.json',
+  'Candidate instinct',
+);
+export const learningPromotionFilePath = artifactLocator(
+  safePaths.learningDirectory,
+  '.learning-promotion.json',
+  'Learning promotion',
+);
+export const tokenCompactionFilePath = artifactLocator(safePaths.tokenEconomyDirectory, '.token-compaction.json', 'Token compaction');
+export const tokenMetricsFilePath = artifactLocator(safePaths.tokenEconomyDirectory, '.token-metrics.json', 'Token metrics');
+export const plannerRouteSnapshotPath = snapshotLocator(safePaths.plannerRoutesDirectory, '.planner-route.json');
+export const plannerPlanSnapshotPath = snapshotLocator(safePaths.plannerPlansDirectory, '.planner-plan.json');
+export const plannerBriefsSnapshotPath = snapshotLocator(safePaths.plannerBriefsDirectory, '.planner-briefs.json');
+export const routerPlanSnapshotPath = snapshotLocator(safePaths.routerPlansDirectory, '.router-plan.json');
+export const routerApprovalSnapshotPath = snapshotLocator(safePaths.routerApprovalsDirectory, '.router-approval.json');
+export const orchestratorPlanSnapshotPath = snapshotLocator(safePaths.orchestratorPlansDirectory, '.orchestrator-plan.json');
+export const orchestratorDispatchPlanSnapshotPath = snapshotLocator(
+  safePaths.orchestratorDispatchPlansDirectory,
+  '.orchestrator-dispatch-plan.json',
+);
+export const evalSuiteSnapshotPath = snapshotLocator(safePaths.evalSuitesDirectory, '.eval-suite.json');
+export const evalRunSnapshotPath = snapshotLocator(safePaths.evalRunsDirectory, '.eval-run.json');
+export const evalReportSnapshotPath = snapshotLocator(safePaths.evalReportsDirectory, '.eval-report.json');
+export const releaseGateSnapshotPath = snapshotLocator(safePaths.releaseGatesDirectory, '.release-gate.json');
+export const releaseNotesSnapshotPath = snapshotLocator(safePaths.releaseNotesDirectory, '.release-notes.json');
+export const feedbackLedgerSnapshotPath = snapshotLocator(safePaths.feedbackLedgersDirectory, '.feedback-ledger.json');
+
+function createApprovalLifecycleFileName() {
+  return function formatApprovalLifecycleFileName(approvalFile) {
+    const digest = crypto.createHash('sha256').update(String(approvalFile || '')).digest('hex').slice(0, 16);
+    return `${digest}.approval-lifecycle.json`;
+  };
+}
+
+function createApprovalLifecycleFilePath() {
+  return function locateApprovalLifecycleFile(root, approvalFile) {
+    return path.join(safePaths.approvalLifecycleDirectory(root), approvalLifecycleFileName(approvalFile));
+  };
+}
+
+function createSafeStateArtifactFilePath() {
+  return function locateSafeStateArtifact(root, directory, fileName, extension, label) {
+    const raw = String(fileName || '').trim();
+    if (!raw) throw new Error(`${label} file is required`);
+    if (path.isAbsolute(raw)) throw new Error(`${label} file must be relative to its state directory`);
+    if (raw.includes('/') || raw.includes('\\')) throw new Error(`${label} file must not include path separators`);
+    if (raw === '.' || raw === '..' || raw.includes('..')) throw new Error(`${label} file must not include traversal`);
+    if (!raw.endsWith(extension)) throw new Error(`${label} file must be a ${extension} file`);
+    return path.join(directory(root), raw);
+  };
+}
+
+function artifactLocator(directory, extension, label) {
+  return function locateStateArtifact(root, fileName) {
+    return safeStateArtifactFilePath(root, directory, fileName, extension, label);
+  };
+}
+
+function createAutoRunLockFilePath() {
+  return function locateAutoRunLock(root, idempotencyKey) {
+    const digest = crypto.createHash('sha256').update(String(idempotencyKey || '')).digest('hex').slice(0, 32);
+    return path.join(safePaths.autoRunLocksDirectory(root), `${digest}.lock.json`);
+  };
+}
+
+function createGovernanceAnyFilePath() {
+  return function locateGovernanceArtifact(root, governanceFile) {
+    const raw = String(governanceFile || '').trim();
+    if (raw.endsWith('.pr-readiness-governance.json')) return governancePrReadinessFilePath(root, raw);
+    if (raw.endsWith('.pr-review-intake-governance.json')) return governancePrReviewIntakeFilePath(root, raw);
+    return governanceFilePath(root, raw);
+  };
+}
+
+function snapshotLocator(directory, extension) {
+  return function locateSnapshot(root) {
+    return timestampedStateFilePath(root, directory, extension);
+  };
+}
+
+function timestampedStateFilePath(root, directory, extension) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(directory(root), `${timestamp}${extension}`);
+}

package/tools/vibe-runtime/runtime-state-presence-model.mjs

@@ -0,0 +1,6 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function runtimeStatePresent(root) {
+  return fs.existsSync(path.join(path.resolve(root), '.vibecoding-state'));
+}

package/tools/vibe-runtime/runtime-state-risk-paths.mjs

@@ -0,0 +1,70 @@
+import path from 'node:path';
+
+import * as safePaths from './state-safe-paths.mjs';
+import { stateDirectory } from './runtime-state-directory-model.mjs';
+
+export const executionQueueDirectoryName = 'execution-queue';
+export const retryPackagesDirectoryName = 'retry-packages';
+export const retryRunsDirectoryName = 'retry-runs';
+export const schedulerPlansDirectoryName = 'scheduler-plans';
+export const schedulerHookPlansDirectoryName = 'scheduler-hook-plans';
+export const schedulerRunsDirectoryName = 'scheduler-runs';
+export const schedulerLeasesDirectoryName = 'scheduler-leases';
+export const daemonRunsDirectoryName = 'daemon-runs';
+export const daemonLoopsDirectoryName = 'daemon-loops';
+export const daemonHeartbeatsDirectoryName = 'daemon-heartbeats';
+export const daemonStopDirectoryName = 'daemon-stop';
+
+export const executionQueueDirectory = stateDirectoryLocator(executionQueueDirectoryName);
+export const retryPackagesDirectory = stateDirectoryLocator(retryPackagesDirectoryName);
+export const retryRunsDirectory = stateDirectoryLocator(retryRunsDirectoryName);
+export const schedulerPlansDirectory = stateDirectoryLocator(schedulerPlansDirectoryName);
+export const schedulerHookPlansDirectory = stateDirectoryLocator(schedulerHookPlansDirectoryName);
+export const schedulerRunsDirectory = stateDirectoryLocator(schedulerRunsDirectoryName);
+export const schedulerLeasesDirectory = stateDirectoryLocator(schedulerLeasesDirectoryName);
+export const daemonRunsDirectory = stateDirectoryLocator(daemonRunsDirectoryName);
+export const daemonLoopsDirectory = stateDirectoryLocator(daemonLoopsDirectoryName);
+export const daemonHeartbeatsDirectory = stateDirectoryLocator(daemonHeartbeatsDirectoryName);
+export const daemonStopDirectory = stateDirectoryLocator(daemonStopDirectoryName);
+
+export const queueFilePath = artifactLocator(executionQueueDirectory, '.queue.json', 'Queue');
+export const schedulerPlanFilePath = artifactLocator(schedulerPlansDirectory, '.scheduler-plan.json', 'Scheduler plan');
+export const schedulerHookPlanFilePath = artifactLocator(
+  schedulerHookPlansDirectory,
+  '.scheduler-hook-plan.json',
+  'Scheduler hook plan',
+);
+export const retryPackageFilePath = artifactLocator(retryPackagesDirectory, '.retry-package.json', 'Retry package');
+export const daemonLoopFilePath = artifactLocator(daemonLoopsDirectory, '.daemon-loop.json', 'Daemon loop');
+export const subagentRunLeaseFilePath = artifactLocator(
+  safePaths.subagentRunLeasesDirectory,
+  '.subagent-lease.json',
+  'Subagent run lease',
+);
+export const platformSessionLeaseFilePath = artifactLocator(
+  safePaths.platformSessionLeasesDirectory,
+  '.platform-session-lease.json',
+  'Platform session lease',
+);
+
+function stateDirectoryLocator(directoryName) {
+  return function locateStateDirectory(root) {
+    return path.join(stateDirectory(root), directoryName);
+  };
+}
+
+function artifactLocator(directory, extension, label) {
+  return function locateStateArtifact(root, fileName) {
+    return safeStateArtifactFilePath(root, directory, fileName, extension, label);
+  };
+}
+
+function safeStateArtifactFilePath(root, directory, fileName, extension, label) {
+  const raw = String(fileName || '').trim();
+  if (!raw) throw new Error(`${label} file is required`);
+  if (path.isAbsolute(raw)) throw new Error(`${label} file must be relative to its state directory`);
+  if (raw.includes('/') || raw.includes('\\')) throw new Error(`${label} file must not include path separators`);
+  if (raw === '.' || raw === '..' || raw.includes('..')) throw new Error(`${label} file must not include traversal`);
+  if (!raw.endsWith(extension)) throw new Error(`${label} file must be a ${extension} file`);
+  return path.join(directory(root), raw);
+}

package/tools/vibe-runtime/runtime-subagent-adapter-dispatch-command.mjs

@@ -0,0 +1,266 @@
+import path from 'node:path';
+import { readonlyLocalStatePresent } from './runtime-readonly-local-json-output-envelope.mjs';
+import { runtimeSubagentPermissionGate } from './runtime-subagent-permission-gate-model.mjs';
+
+export function createRuntimeSubagentAdapterDispatchCommand(deps) {
+  const {
+    jsonSchemaVersion,
+    stateDirectoryName,
+    subagentAdapterDispatchesDirectoryName,
+    ensureRoot,
+    fileDigest,
+    digestObject,
+    readJsonArtifact,
+    writeStateArtifact,
+    listStateFiles,
+    subagentAdapterDispatchesDirectory,
+    subagentAdapterDispatchFilePath,
+    subagentDispatchFilePath,
+    subagentEligibilityFilePath,
+    platformCapabilityFilePath,
+    validateSubagentDispatchArtifact,
+    validateSubagentEligibilityArtifact,
+    validatePlatformCapabilityArtifact,
+  } = deps;
+
+  function subagentAdapterDispatchSnapshotPath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(subagentAdapterDispatchesDirectory(root), `${timestamp}.subagent-adapter-dispatch.json`);
+  }
+
+  function listSubagentAdapterDispatchFiles(root) {
+    return listStateFiles(root, subagentAdapterDispatchesDirectory, '.subagent-adapter-dispatch.json');
+  }
+
+  function gatePassed(gates, id) {
+    return gates.find((gate) => gate.id === id)?.passed === true;
+  }
+
+  function subagentAdapterDispatchCore(inputs) {
+    const { persist, dispatch, capability, dispatchPath, capabilityPath, gates, fileScopeIsolated, fallbackDefined, permissionGate } = inputs;
+    return {
+      version: 1,
+      stage: 'P8',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      dispatch_status: persist ? 'adapter-dispatch-artifact-ready' : 'adapter-dispatch-preview-only',
+      task_id: dispatch.task_id || '',
+      platform: capability.platform || '',
+      adapter: capability.adapter || '',
+      dispatch_file: path.basename(dispatchPath),
+      dispatch_digest: fileDigest(dispatchPath),
+      dispatch_artifact_digest: dispatch.dispatch_digest || '',
+      eligibility_file: dispatch.eligibility_file || '',
+      eligibility_digest: dispatch.eligibility_digest || '',
+      capability_file: path.basename(capabilityPath),
+      capability_digest: fileDigest(capabilityPath),
+      platform_capability_digest: capability.capability_digest || '',
+      adapter_digest: capability.adapter_digest || '',
+      catalog_digest: capability.catalog_digest || '',
+      task_brief_digest: dispatch.task_brief_digest || '',
+      workflow_digest: dispatch.workflow_digest || '',
+      permission_snapshot: {
+        user_permission_required: true,
+        user_permission_present: permissionGate.checks.find((check) => check.id === 'explicit-user-permission')?.pass === true,
+        source: permissionGate.permission_source,
+      },
+      brief_contract: {
+        task_brief_complete: Boolean(dispatch.task_id && dispatch.task_brief_digest),
+        task_brief_digest: dispatch.task_brief_digest || '',
+      },
+      file_isolation_contract: {
+        file_scope_isolated: fileScopeIsolated,
+        shared_state_conflict_absent: gatePassed(gates, 'shared_state_conflict_absent'),
+        forbidden_file_write: false,
+      },
+      review_contract: {
+        task_review_gate_defined: gatePassed(gates, 'task_review_gate_defined'),
+        final_review_gate_defined: gatePassed(gates, 'final_review_gate_defined'),
+        review_required: true,
+        result_ingestion_required: true,
+      },
+      fallback_contract: {
+        fallback_path_defined: fallbackDefined,
+        fallback: ['manual-owner-takes-over', 'vibe-receiving-code-review', 'vibe-systematic-debugging'],
+      },
+      subagent_permission_gate: permissionGate,
+      adapter_consumable: permissionGate.pass,
+      allowed_followup: ['external-adapter-consume-only', 'subagent-result-ingest-only'],
+      no_session_create: true,
+      no_platform_api: true,
+      no_model_invocation: true,
+      no_subagent_action: true,
+      no_git: true,
+      no_worktree: true,
+      no_business_source_write: true,
+      planned_writes: persist ? [path.join(stateDirectoryName, subagentAdapterDispatchesDirectoryName, '<timestamp>.subagent-adapter-dispatch.json').replace(/\\/g, '/')] : [],
+    };
+  }
+
+  function subagentAdapterDispatchEnvelope(root, dispatchFile, capabilityFile, { persist = false, artifactFile = '' } = {}) {
+    ensureRoot(root);
+    if (!dispatchFile) throw new Error('subagents --adapter-dispatch requires --from-dispatch <subagent-dispatch-file>');
+    if (!capabilityFile) throw new Error('subagents --adapter-dispatch requires --capability <platform-capability-file>');
+    const dispatchPath = subagentDispatchFilePath(root, dispatchFile);
+    const dispatchArtifact = readJsonArtifact(dispatchPath, 'Subagent dispatch');
+    const dispatchVerification = validateSubagentDispatchArtifact(root, dispatchArtifact);
+    if (!dispatchVerification.ok) throw new Error(`subagent dispatch verification failed: ${dispatchVerification.failures.join('; ')}`);
+    const capabilityPath = platformCapabilityFilePath(root, capabilityFile);
+    const capabilityArtifact = readJsonArtifact(capabilityPath, 'Platform capability');
+    const capabilityVerification = validatePlatformCapabilityArtifact(capabilityArtifact, path.basename(capabilityPath));
+    if (!capabilityVerification.ok) throw new Error(`platform capability verification failed: ${capabilityVerification.failures.join('; ')}`);
+    const dispatch = dispatchArtifact.subagent_dispatch || {};
+    const capability = capabilityArtifact.platform_capability || {};
+    const eligibilityPath = subagentEligibilityFilePath(root, dispatch.eligibility_file || '');
+    const eligibilityArtifact = readJsonArtifact(eligibilityPath, 'Subagent eligibility');
+    const eligibilityVerification = validateSubagentEligibilityArtifact(root, eligibilityArtifact);
+    if (!eligibilityVerification.ok) throw new Error(`subagent eligibility verification failed: ${eligibilityVerification.failures.join('; ')}`);
+    const gates = eligibilityArtifact.subagent_eligibility?.gates || [];
+    const fileScopeIsolated = gatePassed(gates, 'file_scope_isolated') && gatePassed(gates, 'shared_state_conflict_absent');
+    const reviewGateDefined = gatePassed(gates, 'task_review_gate_defined') && gatePassed(gates, 'final_review_gate_defined');
+    const fallbackDefined = gatePassed(gates, 'fallback_path_defined');
+    const permissionGate = runtimeSubagentPermissionGate({
+      persist,
+      dispatch: dispatchArtifact,
+      eligibility: eligibilityArtifact,
+      capability: capabilityArtifact,
+    });
+    if (persist && !permissionGate.pass) throw new Error(`subagent permission gate failed: ${permissionGate.blocked_reasons.join('; ')}`);
+    const adapterFile = artifactFile || path.basename(subagentAdapterDispatchSnapshotPath(root));
+    const core = subagentAdapterDispatchCore({
+      persist,
+      dispatch,
+      capability,
+      dispatchPath,
+      capabilityPath,
+      gates,
+      fileScopeIsolated,
+      fallbackDefined,
+      permissionGate,
+    });
+    return {
+      mode: 'subagent-adapter-dispatch',
+      ok: true,
+      state_present: readonlyLocalStatePresent(root),
+      subagent_adapter_dispatch: { ...core, adapter_dispatch_digest: digestObject(core) },
+      subagent_dispatch: { file: path.basename(dispatchPath), digest: fileDigest(dispatchPath), verification: dispatchVerification },
+      subagent_eligibility: { file: path.basename(eligibilityPath), digest: fileDigest(eligibilityPath), verification: eligibilityVerification },
+      platform_capability: { file: path.basename(capabilityPath), digest: fileDigest(capabilityPath), verification: capabilityVerification },
+      files: { subagent_adapter_dispatch: adapterFile },
+      safety: {
+        stage: 'P8',
+        writes: Boolean(persist),
+        subagent_adapter_dispatch_artifact: Boolean(persist),
+        adapter_dispatch_artifact: Boolean(persist),
+        adapter_consumable: Boolean(persist),
+        session_create: false,
+        platform_api: false,
+        model_invocation: false,
+        subagent_dispatch: false,
+        subagent: false,
+        mcp: false,
+        git: false,
+        worktree: false,
+        business_source_write: false,
+        auto_execution: false,
+        hidden_handoff: false,
+      },
+      quality: permissionGate.pass ? [] : permissionGate.blocked_reasons,
+      action: persist
+        ? 'subagent adapter dispatch artifact was written locally for explicit adapter consumption. No session was created and no platform API, model invocation, subagent action, git, worktree, or business source write occurred.'
+        : 'subagent adapter dispatch was previewed read-only. No files were written and no adapter or subagent session was created.',
+    };
+  }
+
+  function validateSubagentAdapterDispatchArtifact(root, artifact, fileName = '') {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'subagents') failures.push('command must be subagents');
+    if (artifact.mode !== 'subagent-adapter-dispatch') failures.push('mode must be subagent-adapter-dispatch');
+    const detail = artifact.subagent_adapter_dispatch || {};
+    const files = artifact.files || {};
+    if (!files.subagent_adapter_dispatch || !String(files.subagent_adapter_dispatch).endsWith('.subagent-adapter-dispatch.json')) failures.push('files.subagent_adapter_dispatch must be a subagent adapter dispatch artifact');
+    if (fileName) {
+      if (!fileName.endsWith('.subagent-adapter-dispatch.json')) failures.push('P8 subagent adapter dispatch artifact file extension is unsupported');
+      else if (files.subagent_adapter_dispatch !== fileName) failures.push('P8 subagent adapter dispatch file identity mismatch');
+    }
+    if (detail.version !== 1) failures.push('subagent_adapter_dispatch.version must be 1');
+    if (detail.stage !== 'P8') failures.push('subagent_adapter_dispatch.stage must be P8');
+    if (detail.writes !== true) failures.push('subagent_adapter_dispatch.writes must be true');
+    if (detail.dispatch_status !== 'adapter-dispatch-artifact-ready') failures.push('subagent_adapter_dispatch.dispatch_status must be adapter-dispatch-artifact-ready');
+    if (!detail.task_id) failures.push('subagent_adapter_dispatch.task_id is required');
+    if (!['claude', 'cursor', 'codex'].includes(detail.platform)) failures.push('subagent_adapter_dispatch.platform must be claude, cursor, or codex');
+    if (detail.adapter !== 'local-contract-only') failures.push('subagent_adapter_dispatch.adapter must be local-contract-only');
+    if (detail.permission_snapshot?.user_permission_present !== true) failures.push('subagent_adapter_dispatch permission snapshot must show explicit user permission');
+    if (detail.brief_contract?.task_brief_complete !== true) failures.push('subagent_adapter_dispatch brief contract must be complete');
+    if (detail.file_isolation_contract?.file_scope_isolated !== true) failures.push('subagent_adapter_dispatch file scope must be isolated');
+    if (detail.review_contract?.review_required !== true || detail.review_contract?.result_ingestion_required !== true) failures.push('subagent_adapter_dispatch review and result ingestion gates are required');
+    if (detail.fallback_contract?.fallback_path_defined !== true) failures.push('subagent_adapter_dispatch fallback path must be defined');
+    if (detail.subagent_permission_gate?.pass !== true) failures.push('subagent_adapter_dispatch permission gate must pass');
+    if (detail.subagent_permission_gate?.gate_kind !== 'subagent-explicit-permission-gate') failures.push('subagent_adapter_dispatch permission gate kind mismatch');
+    if (!Array.isArray(detail.subagent_permission_gate?.checks) || detail.subagent_permission_gate.checks.length < 7) failures.push('subagent_adapter_dispatch permission gate checks are required');
+    if (detail.adapter_consumable !== true) failures.push('subagent_adapter_dispatch.adapter_consumable must be true');
+    if (!Array.isArray(detail.allowed_followup) || digestObject(detail.allowed_followup) !== digestObject(['external-adapter-consume-only', 'subagent-result-ingest-only'])) failures.push('subagent_adapter_dispatch.allowed_followup mismatch');
+    for (const key of ['no_session_create', 'no_platform_api', 'no_model_invocation', 'no_subagent_action', 'no_git', 'no_worktree', 'no_business_source_write']) if (detail[key] !== true) failures.push(`subagent_adapter_dispatch.${key} must be true`);
+    const expectedWrites = [path.join(stateDirectoryName, subagentAdapterDispatchesDirectoryName, '<timestamp>.subagent-adapter-dispatch.json').replace(/\\/g, '/')];
+    if (!Array.isArray(detail.planned_writes) || digestObject(detail.planned_writes) !== digestObject(expectedWrites)) failures.push('subagent_adapter_dispatch.planned_writes must only contain adapter dispatch artifact');
+    const digestPayload = { ...detail };
+    delete digestPayload.adapter_dispatch_digest;
+    if (detail.adapter_dispatch_digest !== digestObject(digestPayload)) failures.push('subagent_adapter_dispatch digest mismatch');
+    if (root && detail.dispatch_file) {
+      try {
+        const dispatchPath = subagentDispatchFilePath(root, detail.dispatch_file);
+        if (fileDigest(dispatchPath) !== detail.dispatch_digest) failures.push('subagent_adapter_dispatch dispatch digest mismatch');
+        const dispatchArtifact = readJsonArtifact(dispatchPath, 'Subagent dispatch');
+        const verification = validateSubagentDispatchArtifact(root, dispatchArtifact);
+        failures.push(...verification.failures.map((failure) => `subagent dispatch: ${failure}`));
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+    if (root && detail.capability_file) {
+      try {
+        const capabilityPath = platformCapabilityFilePath(root, detail.capability_file);
+        if (fileDigest(capabilityPath) !== detail.capability_digest) failures.push('subagent_adapter_dispatch capability digest mismatch');
+        const capabilityArtifact = readJsonArtifact(capabilityPath, 'Platform capability');
+        const verification = validatePlatformCapabilityArtifact(capabilityArtifact, path.basename(capabilityPath));
+        failures.push(...verification.failures.map((failure) => `platform capability: ${failure}`));
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+    const safety = artifact.safety || {};
+    if (safety.stage !== 'P8') failures.push('safety.stage must be P8');
+    for (const key of ['writes', 'subagent_adapter_dispatch_artifact', 'adapter_dispatch_artifact', 'adapter_consumable']) if (safety[key] !== true) failures.push(`safety.${key} must be true`);
+    for (const key of ['session_create', 'platform_api', 'model_invocation', 'subagent_dispatch', 'subagent', 'mcp', 'git', 'worktree', 'business_source_write', 'auto_execution', 'hidden_handoff']) if (safety[key] !== false) failures.push(`safety.${key} must be false`);
+    return { ok: failures.length === 0, failures };
+  }
+
+  function writeSubagentAdapterDispatch(root, envelope) {
+    const fileName = envelope.files?.subagent_adapter_dispatch || path.basename(subagentAdapterDispatchSnapshotPath(root));
+    const file = subagentAdapterDispatchFilePath(root, fileName);
+    const payload = { schema_version: jsonSchemaVersion, command: 'subagents', ...envelope, safety: { ...envelope.safety, subagent_adapter_dispatch_artifact: true, adapter_dispatch_artifact: true } };
+    const verification = validateSubagentAdapterDispatchArtifact(root, payload, path.basename(file));
+    if (!verification.ok) throw new Error(`subagent adapter dispatch verification failed: ${verification.failures.join('; ')}`);
+    return writeStateArtifact(path.dirname(file), path.basename(file), payload);
+  }
+
+  function printSubagentAdapterDispatch(envelope, file = '') {
+    console.log('Vibecoding Runtime Subagent Adapter Dispatch');
+    console.log(`Mode: ${envelope.mode}`);
+    console.log(`Task: ${envelope.subagent_adapter_dispatch.task_id}`);
+    console.log(`Status: ${envelope.subagent_adapter_dispatch.dispatch_status}`);
+    console.log(`Adapter consumable: ${envelope.subagent_adapter_dispatch.adapter_consumable ? 'yes' : 'no'}`);
+    if (file) console.log(`Adapter dispatch: ${path.relative(process.cwd(), file)}`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  return {
+    subagentAdapterDispatchSnapshotPath,
+    listSubagentAdapterDispatchFiles,
+    subagentAdapterDispatchEnvelope,
+    validateSubagentAdapterDispatchArtifact,
+    writeSubagentAdapterDispatch,
+    printSubagentAdapterDispatch,
+  };
+}