@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-subagents-stage-artifact-model.mjs

@@ -0,0 +1,538 @@
+import {
+  stage37BudgetSpec,
+  stage37PlannedWritePaths,
+  stage37PolicySpec,
+  stage37ResultFalseFields,
+  stage37ResultReviewFollowup,
+  stage37RunFalseFields,
+  stage37RunTrueFields,
+  stage37Safety,
+  stage37PolicyBudgetSafetyFailures,
+  stage38FallbackChain,
+  stage38ResultFalseFields,
+  stage38ResultFollowup,
+  stage38ResultSafetyTrueFields,
+  stage38ResultWritePaths,
+  stage38ReviewFollowup,
+  stage38ReviewSafetyTrueFields,
+  stage38ReviewWritePaths,
+  stage38Safety,
+  stage38SafetyFalseFields,
+} from './runtime-subagents-artifact-specs.mjs';
+
+export const runtimeSubagentsStageArtifactBoundary = true;
+
+export function createRuntimeSubagentsStageArtifactModel(deps) {
+  const {
+    fs,
+    path,
+    jsonSchemaVersion,
+    stateDirectoryName,
+    schedulerRunsDirectoryName,
+    subagentRunLeasesDirectoryName,
+    subagentRunResultsDirectoryName,
+    subagentResultsDirectoryName,
+    subagentReviewsDirectoryName,
+    ensureRoot,
+    workflowPath,
+    fileDigest,
+    digestObject,
+    readJsonArtifact,
+    listStateFiles,
+    schedulerRunsDirectory,
+    subagentRunLeasesDirectory,
+    subagentRunResultsDirectory,
+    subagentResultsDirectory,
+    subagentReviewsDirectory,
+    subagentDispatchFilePath,
+    subagentRunLeaseFilePath,
+    subagentRunResultFilePath,
+    subagentResultFilePath,
+    subagentReviewFilePath,
+    validateSubagentDispatchArtifact,
+  } = deps;
+
+  function subagentSchedulerRunSnapshotPath(root, timestamp) {
+    return path.join(schedulerRunsDirectory(root), `${timestamp}.subagent-scheduler-run.json`);
+  }
+
+  function subagentRunLeaseSnapshotPath(root, timestamp) {
+    return path.join(subagentRunLeasesDirectory(root), `${timestamp}.subagent-lease.json`);
+  }
+
+  function subagentRunResultSnapshotPath(root, timestamp) {
+    return path.join(subagentRunResultsDirectory(root), `${timestamp}.subagent-run-result.json`);
+  }
+
+  function listSubagentSchedulerRunFiles(root) {
+    return listStateFiles(root, schedulerRunsDirectory, '.subagent-scheduler-run.json');
+  }
+
+  function listSubagentRunLeaseFiles(root) {
+    return listStateFiles(root, subagentRunLeasesDirectory, '.subagent-lease.json');
+  }
+
+  function listSubagentRunResultFiles(root) {
+    return listStateFiles(root, subagentRunResultsDirectory, '.subagent-run-result.json');
+  }
+
+  function subagentSingleShotRunArtifacts(dispatch, { dispatchPath, dispatchDigest, timestamp, runFile, leaseFile, resultFile, policyDigest, plannedWrites, persist }) {
+    const runCore = {
+      version: 1,
+      stage: 'Stage 37',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      run_id: digestObject({ dispatch_file: path.basename(dispatchPath), dispatch_digest: dispatchDigest, timestamp }).slice(0, 16),
+      run_status: 'completed-local-result-recorded',
+      dispatch_file: path.basename(dispatchPath),
+      dispatch_digest: dispatchDigest,
+      task_id: dispatch.task_id || '',
+      scheduler_plan_id: dispatch.scheduler_plan_id || '',
+      scheduler_plan_digest: dispatch.scheduler_plan_digest || '',
+      task_brief_digest: dispatch.task_brief_digest || '',
+      workflow_digest: dispatch.workflow_digest || '',
+      approval_policy_digest: dispatch.approval_policy_digest || '',
+      policy_digest: policyDigest,
+      lease_file: leaseFile,
+      result_file: resultFile,
+      scheduler_selected: true,
+      lease_acquired: true,
+      budget_consumed: true,
+      approval_required: true,
+      foreground_only: true,
+      single_shot: true,
+      no_watcher: true,
+      no_daemon_loop: true,
+      session_created: false,
+      platform_api: false,
+      actual_subagent_session: false,
+      business_source_write: false,
+      git: false,
+      worktree: false,
+      allowed_followup: ['result-review-gate-only'],
+      planned_writes: plannedWrites,
+    };
+    const run = { ...runCore, run_digest: digestObject(runCore) };
+    const runDigest = digestObject(run);
+    const leaseCore = {
+      version: 1,
+      stage: 'Stage 37',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      lease_status: 'acquired-and-released',
+      active: false,
+      run_file: runFile,
+      run_digest: runDigest,
+      dispatch_file: path.basename(dispatchPath),
+      dispatch_digest: dispatchDigest,
+      task_id: dispatch.task_id || '',
+      acquired: true,
+      released: true,
+      foreground_only: true,
+      single_shot: true,
+      stale_recovery_required: false,
+    };
+    const lease = { ...leaseCore, lease_digest: digestObject(leaseCore) };
+    const resultCore = {
+      version: 1,
+      stage: 'Stage 37',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      result_status: 'local-result-recorded',
+      run_file: runFile,
+      run_digest: runDigest,
+      lease_file: leaseFile,
+      lease_digest: digestObject(lease),
+      dispatch_file: path.basename(dispatchPath),
+      dispatch_digest: dispatchDigest,
+      task_id: dispatch.task_id || '',
+      session_created: false,
+      platform_api: false,
+      model_invocation: false,
+      external_delivery: false,
+      actual_subagent_session: false,
+      business_source_write: false,
+      git: false,
+      worktree: false,
+      review_required: true,
+      review_completed: false,
+      allowed_followup: stage37ResultReviewFollowup,
+      summary: 'Stage 37 recorded a bounded local scheduler run boundary. No external subagent session was created and no business source was modified.',
+      evidence: ['approved dispatch verified', 'lease acquired and released locally', 'result sidecar recorded for Stage 38 review gate'],
+    };
+    return { run, lease, result: { ...resultCore, result_digest: digestObject(resultCore) } };
+  }
+
+  function subagentSingleShotRunEnvelope(root, dispatchFile, { persist = false } = {}) {
+    ensureRoot(root);
+    if (!dispatchFile) throw new Error('subagents --run requires --from-dispatch <subagent-dispatch-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 dispatch = dispatchArtifact.subagent_dispatch || {};
+    const dispatchDigest = fileDigest(dispatchPath);
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const runFile = path.basename(subagentSchedulerRunSnapshotPath(root, timestamp));
+    const leaseFile = path.basename(subagentRunLeaseSnapshotPath(root, timestamp));
+    const resultFile = path.basename(subagentRunResultSnapshotPath(root, timestamp));
+    const policy = stage37PolicySpec();
+    const policyDigest = digestObject(policy);
+    const budget = stage37BudgetSpec();
+    const plannedWrites = persist ? stage37PlannedWritePaths(
+      stateDirectoryName,
+      schedulerRunsDirectoryName,
+      subagentRunLeasesDirectoryName,
+      subagentRunResultsDirectoryName,
+    ) : [];
+    const { run, lease, result } = subagentSingleShotRunArtifacts(dispatch, {
+      dispatchPath,
+      dispatchDigest,
+      timestamp,
+      runFile,
+      leaseFile,
+      resultFile,
+      policyDigest,
+      plannedWrites,
+      persist,
+    });
+    return {
+      mode: 'subagent-single-shot-run',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      subagent_scheduler_run: run,
+      subagent_run_lease: lease,
+      subagent_run_result: result,
+      dispatch: { file: path.basename(dispatchPath), digest: dispatchDigest, verification: dispatchVerification },
+      policy: { ...policy, policy_digest: policyDigest },
+      budget,
+      files: { scheduler_run: runFile, lease: leaseFile, result: resultFile },
+      safety: stage37Safety({ writes: persist }),
+      quality: [],
+      action: persist
+        ? 'single-shot subagent scheduler run artifacts were written locally. No external session, platform API, model invocation, git, worktree, or business source write occurred.'
+        : 'single-shot subagent scheduler run was previewed. No files were written and no external session was created.',
+    };
+  }
+
+  function validateSubagentSingleShotRunArtifact(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-single-shot-run') failures.push('mode must be subagent-single-shot-run');
+    if (artifact.ok !== true) failures.push('subagent single-shot run ok must be true');
+    const run = artifact.subagent_scheduler_run || {};
+    const lease = artifact.subagent_run_lease || {};
+    const result = artifact.subagent_run_result || {};
+    const files = artifact.files || {};
+    if (!files.scheduler_run || !String(files.scheduler_run).endsWith('.subagent-scheduler-run.json')) failures.push('files.scheduler_run must be a subagent scheduler run artifact');
+    if (!files.lease || !String(files.lease).endsWith('.subagent-lease.json')) failures.push('files.lease must be a subagent lease artifact');
+    if (!files.result || !String(files.result).endsWith('.subagent-run-result.json')) failures.push('files.result must be a subagent run result artifact');
+    if (fileName) {
+      if (fileName.endsWith('.subagent-scheduler-run.json') && files.scheduler_run !== fileName) failures.push('Stage 37 scheduler run file identity mismatch');
+      else if (fileName.endsWith('.subagent-lease.json') && files.lease !== fileName) failures.push('Stage 37 lease file identity mismatch');
+      else if (fileName.endsWith('.subagent-run-result.json') && files.result !== fileName) failures.push('Stage 37 result file identity mismatch');
+      else if (!fileName.endsWith('.subagent-scheduler-run.json') && !fileName.endsWith('.subagent-lease.json') && !fileName.endsWith('.subagent-run-result.json')) failures.push('Stage 37 artifact file extension is unsupported');
+    }
+    if (lease.run_file !== files.scheduler_run) failures.push('subagent_run_lease.run_file must match files.scheduler_run');
+    if (result.run_file !== files.scheduler_run) failures.push('subagent_run_result.run_file must match files.scheduler_run');
+    if (run.lease_file !== files.lease) failures.push('subagent_scheduler_run.lease_file must match files.lease');
+    if (result.lease_file !== files.lease) failures.push('subagent_run_result.lease_file must match files.lease');
+    if (run.result_file !== files.result) failures.push('subagent_scheduler_run.result_file must match files.result');
+    if (run.version !== 1) failures.push('subagent_scheduler_run.version must be 1');
+    if (run.stage !== 'Stage 37') failures.push('subagent_scheduler_run.stage must be Stage 37');
+    if (run.writes !== true) failures.push('subagent_scheduler_run.writes must be true');
+    if (run.run_status !== 'completed-local-result-recorded') failures.push('subagent_scheduler_run.run_status must be completed-local-result-recorded');
+    if (!run.dispatch_file || !String(run.dispatch_file).endsWith('.subagent-dispatch.json')) failures.push('subagent_scheduler_run.dispatch_file must be a subagent dispatch artifact');
+    if (!run.lease_file || !String(run.lease_file).endsWith('.subagent-lease.json')) failures.push('subagent_scheduler_run.lease_file must be a subagent lease artifact');
+    if (!run.result_file || !String(run.result_file).endsWith('.subagent-run-result.json')) failures.push('subagent_scheduler_run.result_file must be a subagent run result artifact');
+    if (!Array.isArray(run.allowed_followup) || digestObject(run.allowed_followup) !== digestObject(stage37ResultReviewFollowup)) failures.push('subagent_scheduler_run.allowed_followup must equal result-review-gate-only');
+    if (!Array.isArray(run.planned_writes) || digestObject(run.planned_writes) !== digestObject(stage37PlannedWritePaths(
+      stateDirectoryName,
+      schedulerRunsDirectoryName,
+      subagentRunLeasesDirectoryName,
+      subagentRunResultsDirectoryName,
+    ))) failures.push('subagent_scheduler_run.planned_writes must match Stage 37 write whitelist');
+    for (const key of stage37RunTrueFields) if (run[key] !== true) failures.push(`subagent_scheduler_run.${key} must be true`);
+    for (const key of stage37RunFalseFields) if (run[key] !== false) failures.push(`subagent_scheduler_run.${key} must be false`);
+    const runDigestPayload = { ...run };
+    delete runDigestPayload.run_digest;
+    if (run.run_digest !== digestObject(runDigestPayload)) failures.push('subagent_scheduler_run digest mismatch');
+    const runDigest = digestObject(run);
+    if (lease.version !== 1) failures.push('subagent_run_lease.version must be 1');
+    if (lease.stage !== 'Stage 37') failures.push('subagent_run_lease.stage must be Stage 37');
+    if (lease.writes !== true) failures.push('subagent_run_lease.writes must be true');
+    if (lease.lease_status !== 'acquired-and-released') failures.push('subagent_run_lease.lease_status must be acquired-and-released');
+    if (lease.active !== false) failures.push('subagent_run_lease.active must be false');
+    if (lease.acquired !== true || lease.released !== true) failures.push('subagent_run_lease must be acquired and released');
+    if (lease.foreground_only !== true || lease.single_shot !== true) failures.push('subagent_run_lease must be foreground single-shot');
+    if (lease.stale_recovery_required !== false) failures.push('subagent_run_lease.stale_recovery_required must be false');
+    if (lease.run_digest !== runDigest) failures.push('subagent_run_lease.run_digest mismatch');
+    const leaseDigestPayload = { ...lease };
+    delete leaseDigestPayload.lease_digest;
+    if (lease.lease_digest !== digestObject(leaseDigestPayload)) failures.push('subagent_run_lease digest mismatch');
+    const leaseDigest = digestObject(lease);
+    if (result.version !== 1) failures.push('subagent_run_result.version must be 1');
+    if (result.stage !== 'Stage 37') failures.push('subagent_run_result.stage must be Stage 37');
+    if (result.writes !== true) failures.push('subagent_run_result.writes must be true');
+    if (result.result_status !== 'local-result-recorded') failures.push('subagent_run_result.result_status must be local-result-recorded');
+    if (result.run_digest !== runDigest) failures.push('subagent_run_result.run_digest mismatch');
+    if (result.lease_digest !== leaseDigest) failures.push('subagent_run_result.lease_digest mismatch');
+    if (result.review_required !== true || result.review_completed !== false) failures.push('subagent_run_result must require an incomplete review gate');
+    if (!Array.isArray(result.allowed_followup) || digestObject(result.allowed_followup) !== digestObject(stage37ResultReviewFollowup)) failures.push('subagent_run_result.allowed_followup must equal result-review-gate-only');
+    for (const key of stage37ResultFalseFields) if (result[key] !== false) failures.push(`subagent_run_result.${key} must be false`);
+    const resultDigestPayload = { ...result };
+    delete resultDigestPayload.result_digest;
+    if (result.result_digest !== digestObject(resultDigestPayload)) failures.push('subagent_run_result digest mismatch');
+    if (root && run.dispatch_file) {
+      try {
+        const dispatchPath = subagentDispatchFilePath(root, run.dispatch_file);
+        if (fileDigest(dispatchPath) !== run.dispatch_digest) failures.push('subagent_scheduler_run dispatch digest mismatch');
+        if (lease.dispatch_digest !== run.dispatch_digest || result.dispatch_digest !== run.dispatch_digest) failures.push('Stage 37 dispatch digest binding mismatch');
+        const dispatchArtifact = readJsonArtifact(dispatchPath, 'Subagent dispatch');
+        const verification = validateSubagentDispatchArtifact(root, dispatchArtifact);
+        failures.push(...verification.failures.map((failure) => `subagent dispatch: ${failure}`));
+        if ((dispatchArtifact.subagent_dispatch?.task_id || '') !== run.task_id) failures.push('subagent_scheduler_run task_id mismatch');
+        if ((dispatchArtifact.subagent_dispatch?.scheduler_plan_digest || '') !== run.scheduler_plan_digest) failures.push('subagent_scheduler_run scheduler plan digest mismatch');
+        if ((dispatchArtifact.subagent_dispatch?.task_brief_digest || '') !== run.task_brief_digest) failures.push('subagent_scheduler_run task brief digest mismatch');
+        if ((dispatchArtifact.subagent_dispatch?.workflow_digest || '') !== run.workflow_digest) failures.push('subagent_scheduler_run workflow digest mismatch');
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+    failures.push(...stage37PolicyBudgetSafetyFailures({ artifact, run, digestObject }));
+    return { ok: failures.length === 0, failures };
+  }
+
+  function subagentResultSnapshotPath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(subagentResultsDirectory(root), `${timestamp}.subagent-result.json`);
+  }
+
+  function subagentReviewSnapshotPath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(subagentReviewsDirectory(root), `${timestamp}.subagent-review.json`);
+  }
+
+  function listSubagentResultFiles(root) {
+    return listStateFiles(root, subagentResultsDirectory, '.subagent-result.json');
+  }
+
+  function listSubagentReviewFiles(root) {
+    return listStateFiles(root, subagentReviewsDirectory, '.subagent-review.json');
+  }
+
+  function subagentResultIngestionEnvelope(root, resultFile, { persist = false, artifactFile = '' } = {}) {
+    ensureRoot(root);
+    const resultPath = subagentRunResultFilePath(root, resultFile);
+    const runArtifact = readJsonArtifact(resultPath, 'Subagent run result');
+    const runVerification = validateSubagentSingleShotRunArtifact(root, runArtifact, path.basename(resultPath));
+    if (!runVerification.ok) throw new Error(`subagent single-shot run verification failed: ${runVerification.failures.join('; ')}`);
+    const sourceResult = runArtifact.subagent_run_result || {};
+    const scopeChecks = [
+      { id: 'brief_scope', status: 'passed', evidence: ['source result is Stage 37 local sidecar only'], blocked_reason: '' },
+      { id: 'forbidden_files', status: 'passed', evidence: ['business_source_write=false', 'git=false', 'worktree=false'], blocked_reason: '' },
+      { id: 'verification_evidence', status: sourceResult.evidence?.length > 0 ? 'passed' : 'blocked', evidence: sourceResult.evidence || [], blocked_reason: sourceResult.evidence?.length > 0 ? '' : 'Stage 37 result evidence is missing' },
+      { id: 'task_review_gate', status: sourceResult.review_required === true && sourceResult.review_completed === false ? 'passed' : 'blocked', evidence: ['review_required=true', 'review_completed=false'], blocked_reason: sourceResult.review_required === true && sourceResult.review_completed === false ? '' : 'Stage 37 review gate flags drifted' },
+    ];
+    const blockedReasons = scopeChecks.filter((check) => check.status !== 'passed').map((check) => `${check.id}: ${check.blocked_reason}`);
+    const resultArtifactFile = artifactFile || path.basename(subagentResultSnapshotPath(root));
+    const core = {
+      version: 1,
+      stage: 'Stage 38',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      source_result_file: path.basename(resultPath),
+      source_result_digest: fileDigest(resultPath),
+      source_run_file: sourceResult.run_file || '',
+      source_lease_file: sourceResult.lease_file || '',
+      task_id: sourceResult.task_id || '',
+      ingest_status: blockedReasons.length === 0 ? 'ingested-review-required' : 'blocked',
+      scope_checks: scopeChecks,
+      blocked_reasons: blockedReasons,
+      forbidden_files_modified: false,
+      source_merge: false,
+      business_source_write: false,
+      verification_evidence_present: sourceResult.evidence?.length > 0,
+      review_required: true,
+      review_completed: false,
+      allowed_followup: stage38ResultFollowup,
+      fallback: stage38FallbackChain,
+      planned_writes: persist ? stage38ResultWritePaths(stateDirectoryName, subagentResultsDirectoryName) : [],
+    };
+    return {
+      mode: 'subagent-result-ingestion',
+      ok: blockedReasons.length === 0,
+      state_present: fs.existsSync(workflowPath(root)),
+      subagent_result: { ...core, result_digest: digestObject(core) },
+      source_result: { file: path.basename(resultPath), digest: fileDigest(resultPath), verification: runVerification },
+      files: { subagent_result: resultArtifactFile },
+      safety: { ...stage38Safety({ writes: persist }), subagent_result_artifact: Boolean(persist) },
+      quality: blockedReasons,
+      action: persist
+        ? 'subagent result ingestion artifact was written locally. No source merge, platform API, git, worktree, or business source write occurred.'
+        : 'subagent result ingestion was previewed read-only. No files were written and no result was merged.',
+    };
+  }
+
+  function validateSubagentResultArtifact(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-result-ingestion') failures.push('mode must be subagent-result-ingestion');
+    const result = artifact.subagent_result || {};
+    const files = artifact.files || {};
+    if (!files.subagent_result || !String(files.subagent_result).endsWith('.subagent-result.json')) failures.push('files.subagent_result must be a subagent result artifact');
+    if (fileName) {
+      if (fileName.endsWith('.subagent-result.json') && files.subagent_result !== fileName) failures.push('Stage 38 subagent result file identity mismatch');
+      else if (!fileName.endsWith('.subagent-result.json')) failures.push('Stage 38 subagent result artifact file extension is unsupported');
+    }
+    if (result.version !== 1) failures.push('subagent_result.version must be 1');
+    if (result.stage !== 'Stage 38') failures.push('subagent_result.stage must be Stage 38');
+    if (result.writes !== true) failures.push('subagent_result.writes must be true');
+    if (!['ingested-review-required', 'blocked'].includes(result.ingest_status)) failures.push('subagent_result.ingest_status is invalid');
+    if (!Array.isArray(result.allowed_followup) || digestObject(result.allowed_followup) !== digestObject(stage38ResultFollowup)) failures.push('subagent_result.allowed_followup must equal subagent-review-gate-only');
+    if (!Array.isArray(result.fallback) || digestObject(result.fallback) !== digestObject(stage38FallbackChain)) failures.push('subagent_result.fallback must match Stage 38 fallback chain');
+    for (const key of stage38ResultFalseFields) if (result[key] !== false) failures.push(`subagent_result.${key} must be false`);
+    if (result.review_required !== true) failures.push('subagent_result.review_required must be true');
+    if (!Array.isArray(result.scope_checks)) failures.push('subagent_result.scope_checks must be an array');
+    if (!Array.isArray(result.blocked_reasons)) failures.push('subagent_result.blocked_reasons must be an array');
+    const expectedWrites = stage38ResultWritePaths(stateDirectoryName, subagentResultsDirectoryName);
+    if (!Array.isArray(result.planned_writes) || digestObject(result.planned_writes) !== digestObject(expectedWrites)) failures.push('subagent_result.planned_writes must only contain subagent result artifact');
+    const digestPayload = { ...result };
+    delete digestPayload.result_digest;
+    if (result.result_digest !== digestObject(digestPayload)) failures.push('subagent_result digest mismatch');
+    if (root && result.source_result_file) {
+      try {
+        const sourcePath = subagentRunResultFilePath(root, result.source_result_file);
+        if (fileDigest(sourcePath) !== result.source_result_digest) failures.push('subagent_result source result digest mismatch');
+        const source = readJsonArtifact(sourcePath, 'Subagent run result');
+        const verification = validateSubagentSingleShotRunArtifact(root, source, path.basename(sourcePath));
+        failures.push(...verification.failures.map((failure) => `source result: ${failure}`));
+        if ((source.subagent_run_result?.task_id || '') !== result.task_id) failures.push('subagent_result task_id mismatch');
+        if ((source.subagent_run_result?.run_file || '') !== result.source_run_file) failures.push('subagent_result source_run_file mismatch');
+        if ((source.subagent_run_result?.lease_file || '') !== result.source_lease_file) failures.push('subagent_result source_lease_file mismatch');
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+    const safety = artifact.safety || {};
+    if (safety.stage !== 'Stage 38') failures.push('safety.stage must be Stage 38');
+    for (const key of stage38ResultSafetyTrueFields) if (safety[key] !== true) failures.push(`safety.${key} must be true`);
+    for (const key of stage38SafetyFalseFields) if (safety[key] !== false) failures.push(`safety.${key} must be false`);
+    return { ok: failures.length === 0, failures };
+  }
+
+  function subagentReviewGateEnvelope(root, resultFile, { persist = false, artifactFile = '' } = {}) {
+    ensureRoot(root);
+    const resultPath = subagentResultFilePath(root, resultFile);
+    const resultArtifact = readJsonArtifact(resultPath, 'Subagent result');
+    const resultVerification = validateSubagentResultArtifact(root, resultArtifact, path.basename(resultPath));
+    if (!resultVerification.ok) throw new Error(`subagent result verification failed: ${resultVerification.failures.join('; ')}`);
+    const result = resultArtifact.subagent_result || {};
+    const passed = result.ingest_status === 'ingested-review-required' && result.review_required === true && result.review_completed === false && result.forbidden_files_modified === false && result.business_source_write === false;
+    const checks = [
+      { id: 'ingestion_verified', passed: resultVerification.ok, evidence: [path.basename(resultPath)] },
+      { id: 'scope_not_exceeded', passed: result.forbidden_files_modified === false && result.source_merge === false, evidence: ['forbidden_files_modified=false', 'source_merge=false'] },
+      { id: 'verification_evidence_present', passed: result.verification_evidence_present === true, evidence: result.scope_checks?.find((check) => check.id === 'verification_evidence')?.evidence || [] },
+      { id: 'manual_review_still_required', passed: result.review_required === true && result.review_completed === false, evidence: ['review_required=true', 'review_completed=false'] },
+    ];
+    const blockedReasons = checks.filter((check) => !check.passed).map((check) => `${check.id}: failed`);
+    const reviewArtifactFile = artifactFile || path.basename(subagentReviewSnapshotPath(root));
+    const core = {
+      version: 1,
+      stage: 'Stage 38',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      result_file: path.basename(resultPath),
+      result_digest: fileDigest(resultPath),
+      task_id: result.task_id || '',
+      review_status: passed && blockedReasons.length === 0 ? 'review-gate-passed-manual-review-required' : 'blocked',
+      checks,
+      blocked_reasons: blockedReasons,
+      source_merge: false,
+      business_source_write: false,
+      review_required: true,
+      review_completed: false,
+      allowed_followup: stage38ReviewFollowup,
+      fallback: stage38FallbackChain,
+      planned_writes: persist ? stage38ReviewWritePaths(stateDirectoryName, subagentReviewsDirectoryName) : [],
+    };
+    return {
+      mode: 'subagent-review-gate',
+      ok: blockedReasons.length === 0,
+      state_present: fs.existsSync(workflowPath(root)),
+      subagent_review: { ...core, review_digest: digestObject(core) },
+      subagent_result: { file: path.basename(resultPath), digest: fileDigest(resultPath), verification: resultVerification },
+      files: { subagent_review: reviewArtifactFile },
+      safety: { ...stage38Safety({ writes: persist }), subagent_review_artifact: Boolean(persist) },
+      quality: blockedReasons,
+      action: persist
+        ? 'subagent review gate artifact was written locally. No result merge, platform API, git, worktree, or business source write occurred.'
+        : 'subagent review gate was previewed read-only. No files were written and no result was merged.',
+    };
+  }
+
+  function validateSubagentReviewArtifact(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-review-gate') failures.push('mode must be subagent-review-gate');
+    const review = artifact.subagent_review || {};
+    const files = artifact.files || {};
+    if (!files.subagent_review || !String(files.subagent_review).endsWith('.subagent-review.json')) failures.push('files.subagent_review must be a subagent review artifact');
+    if (fileName) {
+      if (fileName.endsWith('.subagent-review.json') && files.subagent_review !== fileName) failures.push('Stage 38 subagent review file identity mismatch');
+      else if (!fileName.endsWith('.subagent-review.json')) failures.push('Stage 38 subagent review artifact file extension is unsupported');
+    }
+    if (review.version !== 1) failures.push('subagent_review.version must be 1');
+    if (review.stage !== 'Stage 38') failures.push('subagent_review.stage must be Stage 38');
+    if (review.writes !== true) failures.push('subagent_review.writes must be true');
+    if (review.review_status !== 'review-gate-passed-manual-review-required') failures.push('subagent_review.review_status must be review-gate-passed-manual-review-required');
+    if (!Array.isArray(review.allowed_followup) || digestObject(review.allowed_followup) !== digestObject(stage38ReviewFollowup)) failures.push('subagent_review.allowed_followup must equal manual-review-or-fallback-only');
+    if (!Array.isArray(review.fallback) || digestObject(review.fallback) !== digestObject(stage38FallbackChain)) failures.push('subagent_review.fallback must match Stage 38 fallback chain');
+    if (review.source_merge !== false || review.business_source_write !== false || review.review_completed !== false) failures.push('subagent_review must not merge source or mark review completed');
+    if (review.review_required !== true) failures.push('subagent_review.review_required must be true');
+    const expectedWrites = stage38ReviewWritePaths(stateDirectoryName, subagentReviewsDirectoryName);
+    if (!Array.isArray(review.planned_writes) || digestObject(review.planned_writes) !== digestObject(expectedWrites)) failures.push('subagent_review.planned_writes must only contain subagent review artifact');
+    const digestPayload = { ...review };
+    delete digestPayload.review_digest;
+    if (review.review_digest !== digestObject(digestPayload)) failures.push('subagent_review digest mismatch');
+    if (root && review.result_file) {
+      try {
+        const resultPath = subagentResultFilePath(root, review.result_file);
+        if (fileDigest(resultPath) !== review.result_digest) failures.push('subagent_review result digest mismatch');
+        const resultArtifact = readJsonArtifact(resultPath, 'Subagent result');
+        const verification = validateSubagentResultArtifact(root, resultArtifact, path.basename(resultPath));
+        failures.push(...verification.failures.map((failure) => `subagent result: ${failure}`));
+        if ((resultArtifact.subagent_result?.task_id || '') !== review.task_id) failures.push('subagent_review task_id mismatch');
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+    const safety = artifact.safety || {};
+    if (safety.stage !== 'Stage 38') failures.push('safety.stage must be Stage 38');
+    for (const key of stage38ReviewSafetyTrueFields) if (safety[key] !== true) failures.push(`safety.${key} must be true`);
+    for (const key of stage38SafetyFalseFields) if (safety[key] !== false) failures.push(`safety.${key} must be false`);
+    return { ok: failures.length === 0, failures };
+  }
+
+  return {
+    subagentSchedulerRunSnapshotPath,
+    subagentRunLeaseSnapshotPath,
+    subagentRunResultSnapshotPath,
+    listSubagentSchedulerRunFiles,
+    listSubagentRunLeaseFiles,
+    listSubagentRunResultFiles,
+    subagentSingleShotRunEnvelope,
+    validateSubagentSingleShotRunArtifact,
+    subagentResultSnapshotPath,
+    subagentReviewSnapshotPath,
+    listSubagentResultFiles,
+    listSubagentReviewFiles,
+    subagentResultIngestionEnvelope,
+    validateSubagentResultArtifact,
+    subagentReviewGateEnvelope,
+    validateSubagentReviewArtifact,
+  };
+}

package/tools/vibe-runtime/runtime-subagents-tail-routing-model.mjs

@@ -0,0 +1,48 @@
+export function createRuntimeSubagentsTailRouting(deps) {
+  const {
+    path,
+    writeJsonEnvelope,
+    subagentEligibilityBridgeEnvelope,
+    subagentEligibilityEnvelope,
+    writeSubagentEligibility,
+    printSubagentEligibility,
+    subagentAuditEnvelope,
+    printSubagentEligibilityAudit,
+    runPlatformSessionSubagentsMode,
+    runSubagentArtifactMode,
+  } = deps;
+
+  function runSubagentEligibilityMode(options) {
+    if (!options.subagentsEligibility) return false;
+    const envelope = options.subagentsFromOrchestrator
+      ? subagentEligibilityBridgeEnvelope(options.root, options.orchestratorFile, options.task, { persist: options.confirm })
+      : subagentEligibilityEnvelope(options.root, options.task, { persist: options.confirm });
+    if (options.confirm) {
+      const file = writeSubagentEligibility(options.root, envelope);
+      if (options.json) writeJsonEnvelope('subagents', { ...envelope, subagent_eligibility_file: path.basename(file) });
+      else printSubagentEligibility(envelope, file);
+      return true;
+    }
+    if (options.json) writeJsonEnvelope('subagents', envelope);
+    else printSubagentEligibility(envelope);
+    return true;
+  }
+
+  function runSubagentAuditMode(options) {
+    if (options.confirm) throw new Error('subagents audit does not support --confirm');
+    const mode = options.subagentsList ? 'list' : options.subagentsVerify ? 'verify' : 'show';
+    const envelope = subagentAuditEnvelope(options.root, mode, options.subagentsFile);
+    if (options.json) writeJsonEnvelope('subagents', envelope);
+    else printSubagentEligibilityAudit(envelope);
+    return true;
+  }
+
+  function runSubagents(options) {
+    if (runPlatformSessionSubagentsMode(options)) return;
+    if (runSubagentArtifactMode(options)) return;
+    if (runSubagentEligibilityMode(options)) return;
+    runSubagentAuditMode(options);
+  }
+
+  return { runSubagents };
+}