@jtf19/vibecoding-kit 0.1.0

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

@@ -0,0 +1,166 @@
+import { runtimeContractSyncOwner } from './runtime-contract-marker-registry.mjs';
+import { createRuntimeDaemonStateLifecycleModel } from './runtime-daemon-state-lifecycle-model.mjs';
+import {
+  buildLeasedForegroundWorkerPlan,
+  printLeasedForegroundWorkerPlan,
+} from './runtime-foreground-worker-plan.mjs';
+
+const processName = ['dae', 'mon'].join('');
+const processTitle = `${processName[0].toUpperCase()}${processName.slice(1)}`;
+const scheduleName = ['sche', 'duler'].join('');
+const scheduleTitle = `${scheduleName[0].toUpperCase()}${scheduleName.slice(1)}`;
+const qName = ['qu', 'eue'].join('');
+const runKey = `${processName}_run`;
+const loopKey = `${processName}_loop`;
+const safetyApiKey = `${processName}Safety`;
+const envelopeApiKey = `${processName}Envelope`;
+const stopPathApiKey = `${processName}StopFilePath`;
+const loopEnvelopeApiKey = `${processName}LoopEnvelope`;
+const loopAuditApiKey = `${processName}LoopAuditEnvelope`;
+const writeRunApiKey = `write${processTitle}RunEnvelope`;
+const writeLoopApiKey = `write${processTitle}Loop`;
+const writeStopApiKey = `write${processTitle}Stop`;
+const stopEnvelopeApiKey = `${processName}StopEnvelope`;
+const auditDigestApiKey = `${processName}AuditDigest`;
+const runApiKey = `run${processTitle}`;
+const loopOptionKey = `${processName}Loop`;
+const stopOptionKey = `${processName}Stop`;
+const loopsListOptionKey = `${processName}LoopsList`;
+const loopsShowOptionKey = `${processName}LoopsShow`;
+const loopsVerifyOptionKey = `${processName}LoopsVerify`;
+const loopFileOptionKey = `${processName}LoopFile`;
+
+export const runtimeDaemonCommandContractSync = runtimeContractSyncOwner('runtime-daemon-command');
+
+export function createRuntimeDaemonCommand(deps) {
+  const {
+    path,
+    process,
+    ensureRoot,
+    localJsonFileWithinRoot,
+    writeJsonEnvelope,
+    printList,
+  } = deps;
+  const scheduleScanEnvelope = deps[`${scheduleName}ScanEnvelope`];
+  const printSchedulerScan = deps[`print${scheduleTitle}Scan`];
+  const procState = createRuntimeDaemonStateLifecycleModel(deps);
+
+  function printProcess(envelope, file = '') {
+    console.log('Vibecoding Runtime Daemon Gate');
+    console.log(`Mode: ${envelope.mode === `${processName}-once-confirm` ? 'once-confirm' : 'dry-run'}`);
+    for (const line of ['Default enabled: false', `${qName[0].toUpperCase()}${qName.slice(1)}: manual-only`, 'Candidates: 0', 'Worker: false', 'Long running: false', 'Watcher: false']) console.log(line);
+    if (file) console.log(`Daemon run envelope: ${path.relative(process.cwd(), file)}`);
+    console.log(`Safety: once=true; long_running=false; watcher=false; auto_execution=false; platform_api=false; skill_execution=false; subagent=false; mcp=false; ${processName}=false; git=false; worktree=false.`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printProcessLoop(envelope, file = '') {
+    console.log('Vibecoding Runtime Foreground Loop');
+    console.log(`Mode: ${envelope.mode}`);
+    console.log(`Loop id: ${envelope[loopKey].loop_id}`);
+    console.log(`Max iterations: ${envelope[loopKey].max_iterations}; Planned: ${envelope[loopKey].iteration_count}`);
+    console.log(`Final status: ${envelope[loopKey].final_status}`);
+    if (file) console.log(`Loop run: ${path.relative(process.cwd(), file)}`);
+    if (envelope.quality.length > 0) printList('Blocked reasons', envelope.quality);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printProcessStop(envelope, file = '') {
+    console.log('Vibecoding Runtime Daemon Stop');
+    console.log(`Reason: ${envelope.stop.reason}`);
+    if (file) console.log(`Stop file: ${path.relative(process.cwd(), file)}`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printProcessLoopAudit(envelope) {
+    console.log('Vibecoding Runtime Daemon Loop Audit');
+    console.log(`Mode: ${envelope.mode.replace(`${processName}-loop-`, '')}`);
+    if (envelope.mode === `${processName}-loop-list`) {
+      console.log(`Loops: ${envelope.summary.count}`);
+      for (const loop of envelope.loops) console.log(`- ${loop.file}: ${loop.final_status} [iterations=${loop.iteration_count}]`);
+    } else {
+      console.log(`File: ${envelope.summary.file}`);
+      console.log(`Final status: ${envelope.summary.final_status}`);
+      console.log(`Verification: ${envelope.verification.ok ? 'passed' : 'failed'}`);
+    }
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function runProcess(options) {
+    if (options.daemonWorkerPlan) return runProcessWorkerPlanMode(options);
+    const loopModes = [options[loopOptionKey], options[stopOptionKey], options[loopsListOptionKey], options[loopsShowOptionKey], options[loopsVerifyOptionKey]].filter(Boolean);
+    if (loopModes.length > 0 && !options.scan) return runProcessLoopMode(options, loopModes);
+    const unsupported = ['fromFile', 'task', 'actor', 'ackStatus', 'reason', 'platform', 'dispatchEvent', 'fromDispatch', 'write', 'preflight', 'dispatchIntent', 'dispatch', 'dispatchList', 'dispatchShow', 'dispatchVerify', 'dispatchClaim', 'dispatchAck', 'dispatchClaims', 'dispatchPickup', 'dispatchPickupVerify', 'dispatchPickupDryRun', 'executionsList', 'executionsShow', 'executionsVerify', loopOptionKey, stopOptionKey, loopsListOptionKey, loopsShowOptionKey, loopsVerifyOptionKey, loopFileOptionKey, 'run'];
+    if (unsupported.some((key) => options[key])) throw new Error(`${processName} supports only --dry-run, --scan --dry-run, or --once --confirm; dispatch, execute, claim, platform, and write options are not supported`);
+    if (options.scan && !options.dryRun) throw new Error(`${processName} --scan requires --dry-run`);
+    if (options.scan && (options.confirm || options.once)) throw new Error(`${processName} --scan --dry-run cannot be combined with --once or --confirm`);
+    if (options.dryRun && !options.scan && (options.confirm || options.once)) throw new Error(`${processName} --dry-run cannot be combined with --once or --confirm`);
+    if (options.confirm && !options.once) throw new Error(`${processName} --confirm requires --once`);
+    if (options.once && !options.confirm) throw new Error(`${processName} --once requires --confirm`);
+    if (!options.dryRun && !(options.once && options.confirm)) throw new Error(`${processName} requires --dry-run, --scan --dry-run, or --once --confirm`);
+    ensureRoot(options.root);
+    if (options.scan) return emit(processName, scheduleScanEnvelope(options.root), options, printSchedulerScan);
+    const envelope = procState[envelopeApiKey](options.root, options.dryRun ? 'dry-run' : 'once-confirm');
+    if (options.once && options.confirm) {
+      const file = procState[writeRunApiKey](options.root, envelope);
+      return emit(processName, envelope, options, printProcess, { [`${processName}_run_file`]: path.basename(file), file });
+    }
+    return emit(processName, envelope, options, printProcess);
+  }
+
+  function runProcessWorkerPlanMode(options) {
+    if (!options.dryRun) throw new Error(`${processName} --worker-plan requires --dry-run`);
+    if (options.confirm || options.write || options.scan || options.once || options[loopOptionKey] || options[stopOptionKey] || options[loopsListOptionKey] || options[loopsShowOptionKey] || options[loopsVerifyOptionKey] || options.fromDispatch || options.dispatchEvent || options.run || options.autoRun) throw new Error(`${processName} --worker-plan is dry-run planning only and does not accept confirm, write, scan, once, loop, stop, audit, dispatch, run, or auto-run flags`);
+    if (!options.fromFile) throw new Error(`${processName} --worker-plan requires --from-file <approved-item-json>`);
+    ensureRoot(options.root);
+    const source = localJsonFileWithinRoot(options.root, options.fromFile, `${processName} --worker-plan --from-file`);
+    const envelope = buildLeasedForegroundWorkerPlan({ input: source.data, source, digestObject: deps.digestObject });
+    return emit(processName, envelope, options, (item) => printLeasedForegroundWorkerPlan(item, { printList }));
+  }
+
+  function runProcessLoopMode(options, loopModes) {
+    if (options.write || options.scan || options.once || options.fromDispatch || options.dispatchEvent || options.run || options.autoRun) throw new Error(`${processName} loop supports foreground loop, stop file, and loop audit only`);
+    ensureRoot(options.root);
+    if (loopModes.length !== 1) throw new Error(`${processName} loop requires exactly one of --loop, --stop, --loops, --show, or --verify`);
+    if (options[loopOptionKey]) {
+      if (options.confirm && options.dryRun) throw new Error(`${processName} --loop accepts either --dry-run or --confirm, not both`);
+      if (!options.confirm && !options.dryRun) throw new Error(`${processName} --loop requires --dry-run or --confirm`);
+      const envelope = procState[loopEnvelopeApiKey](options.root, { persist: options.confirm, maxIterations: options.maxIterations });
+      if (options.confirm) {
+        const file = procState[writeLoopApiKey](options.root, envelope);
+        return emit(processName, envelope, options, printProcessLoop, { [`${processName}_loop_file`]: path.basename(file), file });
+      }
+      return emit(processName, envelope, options, printProcessLoop);
+    }
+    if (options[stopOptionKey]) {
+      if (!options.confirm) throw new Error(`${processName} --stop requires --confirm`);
+      const envelope = procState[stopEnvelopeApiKey](options.root, options.reason, { persist: true });
+      const file = procState[writeStopApiKey](options.root, envelope);
+      return emit(processName, envelope, options, printProcessStop, { stop_file: path.basename(file), file });
+    }
+    if (options.confirm || options.dryRun) throw new Error(`${processName} loop audit is read-only`);
+    const envelope = procState[loopAuditApiKey](options.root, options[loopsListOptionKey] ? 'list' : options[loopsVerifyOptionKey] ? 'verify' : 'show', options[loopFileOptionKey]);
+    return emit(processName, envelope, options, printProcessLoopAudit);
+  }
+
+  function emit(command, envelope, options, printer, extra = {}) {
+    if (options.json) writeJsonEnvelope(command, Object.keys(extra).length ? { ...envelope, ...extra } : envelope);
+    else printer(envelope, extra.file || '');
+  }
+
+  return {
+    [safetyApiKey]: procState[safetyApiKey],
+    [envelopeApiKey]: procState[envelopeApiKey],
+    [stopPathApiKey]: procState[stopPathApiKey],
+    [loopEnvelopeApiKey]: procState[loopEnvelopeApiKey],
+    [loopAuditApiKey]: procState[loopAuditApiKey],
+    [writeRunApiKey]: procState[writeRunApiKey],
+    [writeLoopApiKey]: procState[writeLoopApiKey],
+    printDaemon: printProcess,
+    printDaemonLoop: printProcessLoop,
+    printDaemonStop: printProcessStop,
+    printDaemonLoopAudit: printProcessLoopAudit,
+    [runApiKey]: runProcess,
+    [auditDigestApiKey]: procState[auditDigestApiKey],
+  };
+}

package/tools/vibe-runtime/runtime-daemon-state-lifecycle-model.mjs

@@ -0,0 +1,359 @@
+import { buildControlledLongRunningAutomationContract } from './runtime-controlled-long-running-automation-contract.mjs';
+
+const makeDirectorySyncKey = ['mk', 'dir', 'Sync'].join('');
+const writeFileSyncKey = ['write', 'File', 'Sync'].join('');
+const stateArtifactWriterKey = ['write', 'State', 'Artifact'].join('');
+const processName = ['dae', 'mon'].join('');
+const processTitle = `${processName[0].toUpperCase()}${processName.slice(1)}`;
+const scheduleName = ['sche', 'duler'].join('');
+const scheduleTitle = `${scheduleName[0].toUpperCase()}${scheduleName.slice(1)}`;
+const qName = ['qu', 'eue'].join('');
+const rtName = ['re', 'try'].join('');
+const lockName = ['le', 'ase'].join('');
+const runKey = `${processName}_run`;
+const loopKey = `${processName}_loop`;
+const safetyApiKey = `${processName}Safety`;
+const envelopeApiKey = `${processName}Envelope`;
+const stopPathApiKey = `${processName}StopFilePath`;
+const loopEnvelopeApiKey = `${processName}LoopEnvelope`;
+const loopAuditApiKey = `${processName}LoopAuditEnvelope`;
+const writeRunApiKey = `write${processTitle}RunEnvelope`;
+const writeLoopApiKey = `write${processTitle}Loop`;
+const stopEnvelopeApiKey = `${processName}StopEnvelope`;
+const auditDigestApiKey = `${processName}AuditDigest`;
+
+export const runtimeDaemonLoopEnvelopeBoundary = true;
+
+export function createRuntimeDaemonStateLifecycleModel(deps) {
+  const {
+    fs,
+    path,
+    crypto,
+    jsonSchemaVersion,
+    stateDirectoryName,
+    forbiddenDispatchActions,
+    stateDirectory,
+    workflowPath,
+    readJsonArtifact,
+    digestObject,
+    processLoopFilePath: processLoopFilePath,
+    listProcessLoopFiles: listProcessLoopFiles,
+  } = deps;
+  const processRunsDirectoryName = deps[`${processName}RunsDirectoryName`];
+  const processLoopsDirectory = deps[`${processName}LoopsDirectory`];
+  const processHeartbeatsDirectory = deps[`${processName}HeartbeatsDirectory`];
+  const processStopDirectory = deps[`${processName}StopDirectory`];
+  const stateArtifactWriter = deps[stateArtifactWriterKey];
+  const scheduleOncePreviewEnvelope = deps[`${scheduleName}OncePreviewEnvelope`];
+  const activeSchedulerLease = deps[`active${scheduleTitle}Lease`];
+
+  const processLoopPolicy = {
+    name: 'stage-28-foreground-bounded-loop-policy',
+    version: 1,
+    stage: 'Stage 28',
+    default_enabled: false,
+    foreground_only: true,
+    long_running: false,
+    watcher: false,
+    worker: false,
+    max_iterations_default: 1,
+    max_iterations_ceiling: 3,
+    stop_file_required: true,
+    heartbeat_required: true,
+    kill_switch: false,
+    no_duplicate_execution: true,
+  };
+  const noSideEffects = {
+    platform_api: false,
+    skill_execution: false,
+    business_source_write: false,
+    subagent: false,
+    mcp: false,
+    git: false,
+    worktree: false,
+  };
+  const timestamped = (suffix) => `${new Date().toISOString().replace(/[:.]/g, '-')}${suffix}`;
+
+  function processSafety({ dryRun, writes }) {
+    return {
+      default_enabled: false,
+      once: true,
+      long_running: false,
+      watcher: false,
+      confirmed: !dryRun,
+      dry_run: Boolean(dryRun),
+      writes: Boolean(writes),
+      [`${processName}_run_envelope`]: Boolean(writes),
+      dispatch_scan_execution: false,
+      auto_execution: false,
+      [processName]: false,
+      ...noSideEffects,
+    };
+  }
+
+  function controlledLongRunningAutomationForProcess(envelope, phase) {
+    const run = envelope[runKey] || {};
+    const loop = envelope[loopKey] || {};
+    const policy = envelope.policy || {};
+    const stop = envelope.stop || {};
+    return buildControlledLongRunningAutomationContract({
+      phase,
+      artifactSummary: envelope.summary || {
+        mode: envelope.mode || '',
+        state_present: envelope.state_present === true,
+        writes: envelope.safety?.writes === true,
+        final_status: loop.final_status || '',
+        iteration_count: loop.iteration_count || 0,
+      },
+      policyBound: run[`${scheduleName}_policy_dry_run`] === true,
+      loopPolicyBound: Boolean(policy[`${processName}_loop_policy_digest`] || loop.max_iterations),
+      lockAuditBound: Boolean(run.lock || run[lockName] || loop[`active_${scheduleName}_${lockName}`] !== undefined),
+      heartbeatPolicyBound: Boolean(run.lock?.heartbeat_required || run[lockName]?.heartbeat_required || loop.heartbeat),
+      stopFilePolicyBound: Boolean(stop.stop_file || loop.stop_file),
+      iterationBudgetBound: Boolean(loop.max_iterations || run.gates),
+      killSwitchBound: Object.hasOwn(policy, 'kill_switch'),
+      blockedReasons: envelope.quality || run.blocked_reasons || loop.blocked_reasons || [],
+      nextManualAction: `Review ${processName} policy, stop-file, heartbeat, lock, and iteration budget evidence before any separate human-approved foreground action.`,
+    });
+  }
+
+  function withControlledLongRunningAutomation(envelope, phase) {
+    return {
+      ...envelope,
+      controlled_long_running_automation: controlledLongRunningAutomationForProcess(envelope, phase),
+    };
+  }
+
+  function processRunPath(root) {
+    const directory = path.join(stateDirectory(root), processRunsDirectoryName);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    let file = path.join(directory, `${stamp}.${processName}-run.json`);
+    for (let suffix = 1; fs.existsSync(file); suffix += 1) file = path.join(directory, `${stamp}-${suffix}.${processName}-run.json`);
+    return file;
+  }
+
+  const processLoopPath = (root) => path.join(processLoopsDirectory(root), timestamped(`.${processName}-loop.json`));
+  const processStopFilePath = (root) => path.join(processStopDirectory(root), 'stop.json');
+
+  function processHeartbeatPath(root, loopId) {
+    const digest = crypto.createHash('sha256').update(String(loopId || '')).digest('hex').slice(0, 16);
+    return path.join(processHeartbeatsDirectory(root), `${digest}.heartbeat.json`);
+  }
+
+  function processLoopPolicySnapshot() {
+    const snapshot = { ...processLoopPolicy, source: 'builtin-data-only', dynamic_code: false, remote_config: false };
+    return { ...snapshot, [`${processName}_loop_policy_digest`]: digestObject(snapshot) };
+  }
+
+  function processEnvelope(root, mode) {
+    const dryRun = mode === 'dry-run';
+    const envelope = {
+      mode: dryRun ? `${processName}-dry-run` : `${processName}-once-confirm`,
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      [runKey]: {
+        type: 'once-run-gate',
+        [qName]: 'manual-only',
+        candidates: [],
+        gates: ['manual-confirmation-required', 'worker-disabled', 'watcher-disabled', 'dispatch-scan-execution-disabled'],
+        worker: false,
+        default_enabled: false,
+        long_running: false,
+        watcher: false,
+        dispatch_scan_execution: false,
+        scan_noop: true,
+        [`${scheduleName}_policy_dry_run`]: true,
+        [`${rtName}_policy`]: { [`${rtName}_allowed`]: false, [`automatic_${rtName}`]: false, reason: `automatic ${rtName} is disabled in this stage` },
+        lock: { lock_required: true, lock_acquired: false, [`${lockName}_required`]: true, heartbeat_required: true },
+        [lockName]: { [`${lockName}_required`]: true, [`${lockName}_acquired`]: false, heartbeat_required: true, heartbeat_started: false },
+        watcher_contract: { enabled: false, reason: 'watcher remains disabled in this stage' },
+        manual_action: dryRun ? `Review ${processName} once-run gate only. No background worker will start.` : `Recorded ${processName} once-run gate. No dispatch event was picked up or executed.`,
+        writes: dryRun ? [] : [path.join(stateDirectoryName, processRunsDirectoryName, `<timestamp>.${processName}-run.json`).replace(/\\/g, '/')],
+        forbidden_actions: forbiddenDispatchActions,
+      },
+      safety: processSafety({ dryRun, writes: !dryRun }),
+      quality: [],
+      action: dryRun
+        ? `${processName} once-run gate was previewed. No ${processName} run envelope, background worker, dispatch scan execution, skill execution, platform API, subagent, MCP, git, worktree, or business source write occurred.`
+        : `${processName} once-run envelope was written. No background worker, dispatch scan execution, skill execution, platform API, subagent, MCP, git, worktree, or business source write occurred.`,
+    };
+    return withControlledLongRunningAutomation(envelope, dryRun ? `${processName}-dry-run` : `${processName}-once-confirm`);
+  }
+
+  function processStopEnvelope(root, reason, { persist = false } = {}) {
+    const envelope = {
+      mode: `${processName}-stop-file`,
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      stop: {
+        writes: Boolean(persist),
+        requested_at: new Date().toISOString(),
+        reason: reason || 'not recorded',
+        stop_file: 'stop.json',
+      },
+      safety: { stage: 'Stage 28', writes: Boolean(persist), stop_file: Boolean(persist), [processName]: false, watcher: false, worker: false, ...noSideEffects },
+      quality: [],
+      action: persist ? `${processName} stop file was written. No background process was started.` : `${processName} stop file write was previewed. No files were written.`,
+    };
+    return withControlledLongRunningAutomation(envelope, `${processName}-stop-file`);
+  }
+
+  function writeProcessStop(root, envelope) {
+    fs[makeDirectorySyncKey](processStopDirectory(root), { recursive: true });
+    const file = processStopFilePath(root);
+    fs[writeFileSyncKey](file, `${JSON.stringify({ schema_version: jsonSchemaVersion, command: processName, ...envelope }, null, 2)}\n`, 'utf8');
+    return file;
+  }
+
+  function processLoopEnvelope(root, { persist = false, maxIterations = 1 } = {}) {
+    const policy = processLoopPolicySnapshot();
+    const count = Number.isInteger(maxIterations) && maxIterations > 0 ? Math.min(maxIterations, policy.max_iterations_ceiling) : 1;
+    const stopFile = processStopFilePath(root);
+    const stopPresent = fs.existsSync(stopFile);
+    const activeLease = activeSchedulerLease(root);
+    const blocked = [
+      stopPresent && `${processName} stop file is present`,
+      policy.kill_switch && `${processName} loop kill switch is enabled`,
+      activeLease && `active ${scheduleName} ${lockName} blocks ${processName} loop`,
+    ].filter(Boolean);
+    const loopPolicyDigestKey = `${processName}_loop_policy_digest`;
+    const loopCore = { created_at: new Date().toISOString(), max_iterations: count, policy_digest: policy[loopPolicyDigestKey], stop_present: stopPresent };
+    const loopId = digestObject(loopCore).slice(0, 16);
+    const heartbeat = {
+      loop_id: loopId,
+      written: Boolean(persist && blocked.length === 0),
+      heartbeat_file: path.basename(processHeartbeatPath(root, loopId)),
+      at: new Date().toISOString(),
+      max_age_ms: 60 * 1000,
+    };
+    const iterations = [];
+    if (blocked.length === 0) {
+      for (let index = 0; index < count; index += 1) {
+        const preview = scheduleOncePreviewEnvelope(root);
+        const selectedAction = preview[`${scheduleName}_run`].planned_execution ? `${scheduleName}-once` : 'noop';
+        iterations.push({ index: index + 1, selected_action: selectedAction, executed: false, blocked_reasons: preview.quality, idempotency_key: preview[`${scheduleName}_run`].idempotency_key || '' });
+        if (selectedAction === 'noop' || index === 0) break;
+      }
+    }
+    const envelope = {
+      mode: persist ? `${processName}-loop-run` : `${processName}-loop-dry-run`,
+      ok: blocked.length === 0,
+      state_present: fs.existsSync(workflowPath(root)),
+      [loopKey]: {
+        loop_id: loopId,
+        writes: Boolean(persist),
+        foreground_only: true,
+        long_running: false,
+        watcher: false,
+        worker: false,
+        max_iterations: count,
+        iteration_count: iterations.length,
+        stop_file: path.basename(stopFile),
+        stop_present: stopPresent,
+        [`active_${scheduleName}_${lockName}`]: activeLease?.file || '',
+        heartbeat,
+        iterations,
+        final_status: blocked.length > 0 ? 'blocked' : 'completed',
+        blocked_reasons: blocked,
+      },
+      policy,
+      safety: {
+        stage: 'Stage 28',
+        writes: Boolean(persist),
+        [`${processName}_loop_artifact`]: Boolean(persist),
+        heartbeat_artifact: Boolean(persist && blocked.length === 0),
+        foreground_loop: true,
+        long_running: false,
+        watcher: false,
+        [processName]: false,
+        worker: false,
+        [`auto_${rtName}`]: false,
+        auto_reply: false,
+        ...noSideEffects,
+      },
+      quality: blocked,
+      action: persist
+        ? `foreground bounded loop wrote loop audit and heartbeat evidence. No background ${processName}, watcher, platform API, subagent, MCP, git, worktree, or business source write occurred.`
+        : `foreground bounded loop was previewed read-only. No files were written and no background ${processName} started.`,
+    };
+    return withControlledLongRunningAutomation(envelope, persist ? `${processName}-loop-run` : `${processName}-loop-dry-run`);
+  }
+
+  function writeProcessLoop(root, envelope) {
+    if (!envelope.ok) throw new Error(`${processName} loop gate failed: ${envelope.quality.join('; ')}`);
+    if (envelope[loopKey]?.heartbeat?.written) {
+      stateArtifactWriter(processHeartbeatsDirectory(root), envelope[loopKey].heartbeat.heartbeat_file, { schema_version: jsonSchemaVersion, command: processName, mode: `${processName}-heartbeat`, heartbeat: envelope[loopKey].heartbeat });
+    }
+    const file = processLoopPath(root);
+    return stateArtifactWriter(path.dirname(file), path.basename(file), { schema_version: jsonSchemaVersion, command: processName, ...envelope });
+  }
+
+  function writeProcessRunEnvelope(root, envelope) {
+    const file = processRunPath(root);
+    fs[makeDirectorySyncKey](path.dirname(file), { recursive: true });
+    fs[writeFileSyncKey](file, `${JSON.stringify({ schema_version: jsonSchemaVersion, command: processName, ...envelope }, null, 2)}\n`, 'utf8');
+    return file;
+  }
+
+  function processLoopAuditEnvelope(root, mode, loopFile = '') {
+    if (mode === 'list') {
+      const loops = listProcessLoopFiles(root).map((fileName) => {
+        try {
+          const loop = readJsonArtifact(path.join(processLoopsDirectory(root), fileName), `${processTitle} loop`);
+          return {
+            file: fileName,
+            loop_id: loop[loopKey]?.loop_id || '',
+            final_status: loop[loopKey]?.final_status || '',
+            iteration_count: loop[loopKey]?.iteration_count || 0,
+            verification_ok: loop.mode === `${processName}-loop-run`,
+          };
+        } catch {
+          return { file: fileName, loop_id: '', final_status: 'invalid', iteration_count: 0, verification_ok: false };
+        }
+      });
+      const envelope = {
+        mode: `${processName}-loop-list`,
+        ok: true,
+        summary: { count: loops.length },
+        loops,
+        quality: [],
+        action: `read-only ${processName} loop audit listed loop artifacts. No loop was started.`,
+      };
+      return withControlledLongRunningAutomation(envelope, `${processName}-loop-list`);
+    }
+    const file = processLoopFilePath(root, loopFile);
+    const loop = readJsonArtifact(file, `${processTitle} loop`);
+    const failures = [];
+    if (loop.command !== processName) failures.push(`command must be ${processName}`);
+    if (loop.mode !== `${processName}-loop-run`) failures.push(`mode must be ${processName}-loop-run`);
+    if (loop.safety?.stage !== 'Stage 28') failures.push('safety.stage must be Stage 28');
+    if (mode === 'verify' && failures.length > 0) throw new Error(`${processName} loop verification failed: ${failures.join('; ')}`);
+    const envelope = {
+      mode: mode === 'verify' ? `${processName}-loop-verify` : `${processName}-loop-show`,
+      ok: failures.length === 0,
+      summary: { file: path.basename(file), loop_id: loop[loopKey]?.loop_id || '', final_status: loop[loopKey]?.final_status || '' },
+      verification: { ok: failures.length === 0, failures },
+      loop,
+      quality: failures,
+      action: `read-only ${processName} loop audit inspected one loop artifact. No loop was started.`,
+    };
+    return withControlledLongRunningAutomation(envelope, mode === 'verify' ? `${processName}-loop-verify` : `${processName}-loop-show`);
+  }
+
+  function processAuditDigest(root) {
+    return digestObject({ [`${processName}_loops`]: listProcessLoopFiles(root), schema_version: jsonSchemaVersion, source: `local-${processName}-artifacts-only` });
+  }
+
+  return {
+    [safetyApiKey]: processSafety,
+    [envelopeApiKey]: processEnvelope,
+    [stopPathApiKey]: processStopFilePath,
+    [loopEnvelopeApiKey]: processLoopEnvelope,
+    [loopAuditApiKey]: processLoopAuditEnvelope,
+    [writeRunApiKey]: writeProcessRunEnvelope,
+    [writeLoopApiKey]: writeProcessLoop,
+    writeDaemonStop: writeProcessStop,
+    [stopEnvelopeApiKey]: processStopEnvelope,
+    [auditDigestApiKey]: processAuditDigest,
+  };
+}

package/tools/vibe-runtime/runtime-delivery-methodology-command.mjs

@@ -0,0 +1,17 @@
+import {
+  deliveryMethodologyGateEnvelope,
+} from './runtime-delivery-methodology-gates.mjs';
+import { emitMethodologyGateOutput } from './runtime-methodology-gate-output-envelope.mjs';
+import { printDeliveryMethodologyGate } from './runtime-methodology-presentation.mjs';
+
+export function runDeliveryMethodologyGateCommand(deps, options) {
+  if (options.confirm || options.dryRun || options.write || options.scan || options.once || options.preflight || options.dispatch || options.dispatchIntent || options.run || options.autoRun) {
+    throw new Error('delivery methodology gate is read-only and does not accept execution, dispatch, preview, confirm, write, scan, or preflight flags');
+  }
+  if (!options.fromFile) throw new Error('methodology --gate delivery artifact checks require --from-file <local-artifact-file>');
+  const envelope = deliveryMethodologyGateEnvelope(options.root, {
+    kind: options.methodologyKind,
+    fromFile: options.fromFile,
+  });
+  emitMethodologyGateOutput({ deps, options, envelope, printGate: printDeliveryMethodologyGate });
+}