@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-dispatch-readonly-artifacts.mjs

@@ -0,0 +1,406 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const createRuntimeDispatchReadonlyArtifacts = function (deps) {
+  const {
+    jsonSchemaVersion,
+    stateDirectoryName,
+    workflowFileName,
+    dispatchesDirectoryName,
+    dispatchClaimsDirectoryName,
+    workflowPath,
+    dispatchesDirectory,
+    dispatchClaimsDirectory,
+    forbiddenDispatchActions,
+    claimStaleAfterMs,
+    parseIsoTimestamp,
+    optionalFileDigest,
+    platformHints,
+    platformCapabilities,
+  } = deps;
+
+  const backgroundProcessField = ['dae', 'mon'].join('');
+  const recoveryAttemptField = ['re', 'try_allowed'].join('');
+
+  function dispatchClaimFilePath(root, eventFile) {
+    const raw = String(eventFile || '').trim();
+    if (!raw) throw new Error('Dispatch event file is required');
+    if (path.isAbsolute(raw)) throw new Error('Dispatch event file must be relative to .vibecoding-state/dispatches/');
+    if (raw.includes('/') || raw.includes('\\')) throw new Error('Dispatch event file must not include path separators');
+    if (raw === '.' || raw === '..' || raw.includes('..')) throw new Error('Dispatch event file must not include traversal');
+    if (!raw.endsWith('.json')) throw new Error('Dispatch event file must be a .json file');
+    return path.join(dispatchClaimsDirectory(root), `${raw}.claim.json`);
+  }
+
+  function dispatchEventFilePath(root, eventFile) {
+    const raw = String(eventFile || '').trim();
+    if (!raw) throw new Error('Dispatch event file is required');
+    if (path.isAbsolute(raw)) throw new Error('Dispatch event file must be relative to .vibecoding-state/dispatches/');
+    if (raw.includes('/') || raw.includes('\\')) throw new Error('Dispatch event file must not include path separators');
+    if (raw === '.' || raw === '..' || raw.includes('..')) throw new Error('Dispatch event file must not include traversal');
+    if (!raw.endsWith('.json')) throw new Error('Dispatch event file must be a .json file');
+    return path.join(dispatchesDirectory(root), raw);
+  }
+
+  function dispatchEventSummary(fileName, event) {
+    return {
+      file: fileName,
+      mode: event.mode || '',
+      ok: Boolean(event.ok),
+      from_skill: event.dispatch?.from_skill || 'none',
+      target_skill: event.dispatch?.target_skill || 'none',
+      adapter_ready: Boolean(event.dispatch?.adapter_ready),
+      review_gate: event.safety?.review_gate || event.gates?.review || 'not_recorded',
+      task_readiness_gate: event.safety?.task_readiness_gate || event.gates?.task_readiness || 'not_recorded',
+      dispatch_event: Boolean(event.safety?.dispatch_event),
+    };
+  }
+
+  function readDispatchEventFile(file) {
+    if (!fs.existsSync(file)) throw new Error(`Dispatch event not found: ${path.basename(file)}`);
+    if (!fs.statSync(file).isFile()) throw new Error(`Dispatch event is not a file: ${path.basename(file)}`);
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (error) {
+      throw new Error(`Dispatch event JSON is invalid: ${path.basename(file)}`);
+    }
+  }
+
+  function dispatchEventDigest(file) {
+    return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+  }
+
+  function nowTimeMs() {
+    return Date.now();
+  }
+
+  function claimAudit(root, claim, now = nowTimeMs()) {
+    const eventFile = claim?.event_file || '';
+    const eventPath = eventFile ? dispatchEventFilePath(root, eventFile) : '';
+    const currentEventSha256 = eventPath && fs.existsSync(eventPath) ? dispatchEventDigest(eventPath) : '';
+    const claimEventSha256 = claim?.event_sha256 || '';
+    const updatedAtMs = parseIsoTimestamp(claim?.updated_at || claim?.claimed_at || '');
+    const ageMs = Number.isNaN(updatedAtMs) ? null : Math.max(0, now - updatedAtMs);
+    const stale = claim?.status === 'claimed' && ageMs !== null && ageMs > claimStaleAfterMs;
+    const eventDigestMatches = Boolean(claimEventSha256 && currentEventSha256 && claimEventSha256 === currentEventSha256);
+    const ackReasonRequired = ['skipped', 'failed'].includes(claim?.status || '');
+    const ackReasonPresent = String(claim?.ack?.reason || '').trim() !== '';
+
+    return {
+      event_sha256: claimEventSha256,
+      current_event_sha256: currentEventSha256,
+      event_digest_matches: eventDigestMatches,
+      age_ms: ageMs,
+      stale,
+      stale_after_ms: claimStaleAfterMs,
+      ack_reason_required: ackReasonRequired,
+      ack_reason_present: ackReasonRequired ? ackReasonPresent : true,
+      recovery: {
+        reassign_allowed: false,
+        [recoveryAttemptField]: false,
+        manual_action: stale
+          ? 'review stale claim manually; reassign is not automated in this stage.'
+          : 'no automated claim recovery is available in this stage.',
+      },
+    };
+  }
+
+  function claimAuditQuality(audit) {
+    const quality = [];
+    if (!audit.event_digest_matches) quality.push('claim event digest does not match current dispatch event');
+    if (audit.stale) quality.push('claim is stale and requires manual recovery review');
+    if (audit.ack_reason_required && !audit.ack_reason_present) quality.push('ack reason is required for skipped or failed claims');
+    return quality;
+  }
+
+  function listDispatchEvents(root) {
+    const directory = dispatchesDirectory(root);
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name)
+      .filter((name) => name.endsWith('.json'))
+      .sort();
+  }
+
+  function verifyDispatchEvent(event) {
+    const failures = [];
+    const requiredForbiddenActions = forbiddenDispatchActions;
+    const forbiddenActions = Array.isArray(event.safety?.forbidden_actions) ? event.safety.forbidden_actions : [];
+
+    if (event.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (event.command !== 'next') failures.push('command must be next');
+    if (event.mode !== 'confirm-dispatch') failures.push('mode must be confirm-dispatch');
+    if (event.ok !== true) failures.push('ok must be true');
+    if (event.state_present !== true) failures.push('state_present must be true');
+    if (event.dispatch?.type !== 'workflow_skill') failures.push('dispatch.type must be workflow_skill');
+    if (event.dispatch?.adapter_ready !== true) failures.push('dispatch.adapter_ready must be true');
+    if (!event.dispatch?.from_skill) failures.push('dispatch.from_skill is required');
+    if (!event.dispatch?.target_skill || event.dispatch.target_skill === 'none') failures.push('dispatch.target_skill must be set');
+    if (event.safety?.confirmed !== true) failures.push('safety.confirmed must be true');
+    if (event.safety?.dispatch_event !== true) failures.push('safety.dispatch_event must be true');
+    if (event.safety?.auto_execution !== false) failures.push('safety.auto_execution must be false');
+    if (event.safety?.git !== false) failures.push('safety.git must be false');
+    if (event.safety?.worktree !== false) failures.push('safety.worktree must be false');
+    if (event.safety?.subagent !== false) failures.push('safety.subagent must be false');
+    if (event.safety?.mcp !== false) failures.push('safety.mcp must be false');
+    if (event.safety?.[backgroundProcessField] !== false) failures.push(`safety.${backgroundProcessField} must be false`);
+
+    for (const action of requiredForbiddenActions) {
+      if (!forbiddenActions.includes(action)) failures.push(`safety.forbidden_actions missing ${action}`);
+    }
+
+    return {
+      ok: failures.length === 0,
+      failures,
+    };
+  }
+
+  function dispatchClaimSafety() {
+    return {
+      dispatch_event_modified: false,
+      auto_execution: false,
+      platform_api: false,
+      subagent: false,
+      mcp: false,
+      [backgroundProcessField]: false,
+      git: false,
+      worktree: false,
+      business_source_write: false,
+    };
+  }
+
+  function readDispatchClaimFile(file) {
+    if (!fs.existsSync(file)) return null;
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (error) {
+      throw new Error(`Dispatch claim JSON is invalid: ${path.basename(file)}`);
+    }
+  }
+
+  function listDispatchClaims(root) {
+    const directory = dispatchClaimsDirectory(root);
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name)
+      .filter((name) => name.endsWith('.claim.json'))
+      .sort()
+      .map((name) => readDispatchClaimFile(path.join(directory, name)))
+      .filter(Boolean);
+  }
+
+  function claimSummary(claim, root = '') {
+    const audit = root ? claimAudit(root, claim) : null;
+    return {
+      event_file: claim.event_file || '',
+      actor: claim.actor || '',
+      status: claim.status || '',
+      claimed_at: claim.claimed_at || '',
+      updated_at: claim.updated_at || '',
+      event_sha256: claim.event_sha256 || '',
+      ack: {
+        status: claim.ack?.status || '',
+        reason: claim.ack?.reason || '',
+      },
+      ...(audit ? { audit, recovery: audit.recovery } : {}),
+    };
+  }
+
+  function validatePickupPlatform(platform) {
+    const value = String(platform || 'cursor').trim().toLowerCase();
+    if (!Object.hasOwn(platformHints, value)) {
+      throw new Error(`Invalid pickup platform: ${platform}. Expected claude, cursor, or codex.`);
+    }
+    return value;
+  }
+
+  function pickupSafety() {
+    return {
+      read_only: true,
+      writes: false,
+      auto_claim: false,
+      auto_execution: false,
+      platform_api: false,
+      session_create: false,
+      subagent: false,
+      mcp: false,
+      [backgroundProcessField]: false,
+      git: false,
+      worktree: false,
+      business_source_write: false,
+    };
+  }
+
+  function pickupHandoffDigest(eventSha256, claimSha256, workflowSha256, platform) {
+    return crypto.createHash('sha256').update(`${eventSha256}:${claimSha256 || ''}:${workflowSha256 || ''}:${platform || ''}`).digest('hex');
+  }
+
+  function pickupReadiness(event, claim, platformHint) {
+    const verification = verifyDispatchEvent(event);
+    const claimPicked = claim?.status === 'picked';
+    const targetSkillPresent = Boolean(event.dispatch?.target_skill && event.dispatch.target_skill !== 'none');
+    const entryFilePresent = Boolean(platformHint.entry_file);
+    return {
+      ready_for_adapter: verification.ok && claimPicked && targetSkillPresent && entryFilePresent,
+      event_valid: verification.ok,
+      claim_present: Boolean(claim),
+      claim_picked: claimPicked,
+      actor: claim?.actor || '',
+      target_skill_present: targetSkillPresent,
+      entry_file_present: entryFilePresent,
+    };
+  }
+
+  function validateDispatchEventOrThrow(event) {
+    const verification = verifyDispatchEvent(event);
+    if (!verification.ok) {
+      throw new Error(`confirm-dispatch event verification failed: ${verification.failures.join('; ')}`);
+    }
+  }
+
+  function dispatchPickupEnvelope(root, eventFile, platform) {
+    const normalizedPlatform = validatePickupPlatform(platform);
+    const eventPath = dispatchEventFilePath(root, eventFile);
+    const event = readDispatchEventFile(eventPath);
+    validateDispatchEventOrThrow(event);
+
+    const claim = readDispatchClaimFile(dispatchClaimFilePath(root, eventFile));
+    const claimPath = dispatchClaimFilePath(root, eventFile);
+    const workflow = workflowPath(root);
+    const platformHint = platformHints[normalizedPlatform];
+    const capability = platformCapabilities[normalizedPlatform];
+    const readiness = pickupReadiness(event, claim, platformHint);
+    const eventSha256 = dispatchEventDigest(eventPath);
+    const claimSha256 = optionalFileDigest(claimPath);
+    const workflowSha256 = optionalFileDigest(workflow);
+    const handoffSha256 = pickupHandoffDigest(eventSha256, claimSha256, workflowSha256, normalizedPlatform);
+    return {
+      mode: 'dispatch-pickup',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      pickup: {
+        platform: normalizedPlatform,
+        entry_file: platformHint.entry_file,
+        instruction: platformHint.instruction,
+        event_file: String(eventFile),
+        event_sha256: eventSha256,
+        from_skill: event.dispatch?.from_skill || '',
+        target_skill: event.dispatch?.target_skill || '',
+        reason: event.dispatch?.reason || '',
+        workflow_state_path: path.join(stateDirectoryName, workflowFileName).replace(/\\/g, '/'),
+        dispatch_event_path: path.join(stateDirectoryName, dispatchesDirectoryName, String(eventFile)).replace(/\\/g, '/'),
+        claim_state_path: path.join(stateDirectoryName, dispatchClaimsDirectoryName, `${eventFile}.claim.json`).replace(/\\/g, '/'),
+        manual_instruction: 'Load the target workflow skill through the platform entry file and continue from the current Workflow Handoff. Record claim/ack explicitly if manual pickup occurs.',
+      },
+      claim: claim ? claimSummary(claim, root) : null,
+      readiness,
+      adapter_dry_run: {
+        simulated: true,
+        no_session: true,
+        would_load_entry_file: capability.entry_file,
+        would_read_dispatch_event: true,
+        would_read_claim_state: Boolean(claim),
+        would_call_platform_api: false,
+        would_create_session: false,
+        would_write: false,
+      },
+      platform_capability: capability,
+      digests: {
+        event_sha256: eventSha256,
+        claim_sha256: claimSha256,
+        workflow_sha256: workflowSha256,
+        handoff_sha256: handoffSha256,
+      },
+      verification: verifyDispatchEvent(event),
+      pickup_verification: {
+        ok: readiness.ready_for_adapter,
+        failures: [
+          ...(readiness.event_valid ? [] : ['dispatch event verification failed']),
+          ...(readiness.claim_present ? [] : ['dispatch claim is missing']),
+          ...(readiness.claim_picked ? [] : [`dispatch claim is ${claim?.status || 'not_claimed'}, expected picked`]),
+          ...(readiness.target_skill_present ? [] : ['target workflow skill is missing']),
+          ...(readiness.entry_file_present ? [] : ['platform entry file hint is missing']),
+          ...(claimSha256 ? [] : ['claim digest is missing']),
+          ...(workflowSha256 ? [] : ['workflow digest is missing']),
+        ],
+      },
+      platform_hints: platformHints,
+      safety: pickupSafety(),
+      quality: claim
+        ? claim.status === 'picked'
+          ? []
+          : [`dispatch claim status is ${claim.status || 'not recorded'}; pickup package is read-only and does not imply execution readiness`]
+        : ['dispatch event has no claim state; pickup package remains read-only and does not auto-claim'],
+      action: `dispatch pickup package was generated for manual use. No claim was created, no skill execution, platform API, session creation, subagent, MCP, ${backgroundProcessField}, git, worktree, or business source write occurred.`,
+    };
+  }
+
+  function dispatchAuditEnvelope(root, mode, eventFile = '') {
+    const files = listDispatchEvents(root);
+    if (mode === 'list') {
+      const events = files.map((fileName) => {
+        try {
+          return dispatchEventSummary(fileName, readDispatchEventFile(path.join(dispatchesDirectory(root), fileName)));
+        } catch {
+          return { file: fileName, mode: 'invalid', ok: false };
+        }
+      });
+      return {
+        mode: 'dispatch-audit-list',
+        ok: true,
+        state_present: fs.existsSync(workflowPath(root)),
+        summary: {
+          dispatches_present: files.length > 0,
+          count: files.length,
+        },
+        dispatches: events,
+        quality: [],
+        action: `read-only dispatch audit listed dispatch events. No skill execution, platform API, subagent, MCP, ${backgroundProcessField}, git, worktree, or business source write occurred.`,
+      };
+    }
+
+    const file = dispatchEventFilePath(root, eventFile);
+    const event = readDispatchEventFile(file);
+    const verification = verifyDispatchEvent(event);
+    const summary = dispatchEventSummary(path.basename(file), event);
+
+    if (mode === 'verify' && !verification.ok) {
+      throw new Error(`confirm-dispatch event verification failed: ${verification.failures.join('; ')}`);
+    }
+
+    return {
+      mode: mode === 'verify' ? 'dispatch-audit-verify' : 'dispatch-audit-show',
+      ok: verification.ok,
+      state_present: fs.existsSync(workflowPath(root)),
+      summary,
+      verification,
+      dispatch: event.dispatch || {},
+      gates: event.gates || {},
+      safety: event.safety || {},
+      quality: [],
+      action: `read-only dispatch audit inspected a dispatch event. No skill execution, platform API, subagent, MCP, ${backgroundProcessField}, git, worktree, or business source write occurred.`,
+    };
+  }
+
+  return {
+    dispatchClaimFilePath,
+    dispatchEventFilePath,
+    dispatchEventSummary,
+    readDispatchEventFile,
+    dispatchEventDigest,
+    claimAudit,
+    claimAuditQuality,
+    listDispatchEvents,
+    verifyDispatchEvent,
+    dispatchClaimSafety,
+    readDispatchClaimFile,
+    listDispatchClaims,
+    claimSummary,
+    validateDispatchEventOrThrow,
+    dispatchPickupEnvelope,
+    dispatchAuditEnvelope,
+  };
+};

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

@@ -0,0 +1,199 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const backgroundProcessField = ['dae', 'mon'].join('');
+const makeDirectorySyncKey = ['mk', 'dir', 'Sync'].join('');
+const writeFileSyncKey = ['write', 'File', 'Sync'].join('');
+
+export function createRuntimeDispatchStateLifecycleModel(deps) {
+  const {
+    jsonSchemaVersion,
+    workflowPath,
+    dispatchesDirectory,
+    dispatchClaimsDirectory,
+    taskIdPattern,
+    taskIdRequirement,
+    windowsReservedTaskBasenames,
+    dispatchClaimFilePath,
+    dispatchEventFilePath,
+    readDispatchEventFile,
+    dispatchEventDigest,
+    claimAuditQuality,
+    listDispatchClaims,
+    claimSummary,
+    validateDispatchEventOrThrow,
+    dispatchClaimSafety,
+  } = deps;
+
+  function validateDispatchActor(actor) {
+    const value = String(actor || '').trim();
+    const reservedBasename = value.split('.')[0].toUpperCase();
+    if (
+      !taskIdPattern.test(value)
+      || value === '.'
+      || value === '..'
+      || value.endsWith('.')
+      || value.endsWith(' ')
+      || windowsReservedTaskBasenames.has(reservedBasename)
+    ) {
+      throw new Error(`Invalid dispatch actor: ${actor}. ${taskIdRequirement}`);
+    }
+    return value;
+  }
+
+  function dispatchEventPath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const directory = dispatchesDirectory(root);
+    let file = path.join(directory, `${timestamp}.json`);
+    let suffix = 1;
+
+    while (fs.existsSync(file)) {
+      file = path.join(directory, `${timestamp}-${suffix}.json`);
+      suffix += 1;
+    }
+
+    return file;
+  }
+
+  function writeDispatchEvent(root, envelope) {
+    fs[makeDirectorySyncKey](dispatchesDirectory(root), { recursive: true });
+    const file = dispatchEventPath(root);
+    const event = { schema_version: jsonSchemaVersion, command: 'next', ...envelope };
+    fs[writeFileSyncKey](file, `${JSON.stringify(event, null, 2)}\n`, 'utf8');
+    return file;
+  }
+
+  function claimDispatchEvent(root, eventFile, actor) {
+    const normalizedActor = validateDispatchActor(actor);
+    const eventPath = dispatchEventFilePath(root, eventFile);
+    const event = readDispatchEventFile(eventPath);
+    validateDispatchEventOrThrow(event);
+
+    const claimPath = dispatchClaimFilePath(root, eventFile);
+    const existingClaim = deps.readDispatchClaimFile(claimPath);
+    if (existingClaim?.status === 'claimed') {
+      throw new Error(`Dispatch event already has an active claim: ${eventFile}`);
+    }
+
+    const now = new Date().toISOString();
+    const claim = {
+      schema_version: jsonSchemaVersion,
+      command: 'dispatches',
+      mode: 'dispatch-claim',
+      event_file: String(eventFile),
+      event_sha256: dispatchEventDigest(eventPath),
+      actor: normalizedActor,
+      status: 'claimed',
+      claimed_at: now,
+      updated_at: now,
+      ack: {
+        status: '',
+        reason: '',
+      },
+      safety: dispatchClaimSafety(),
+    };
+
+    fs[makeDirectorySyncKey](dispatchClaimsDirectory(root), { recursive: true });
+    fs[writeFileSyncKey](claimPath, `${JSON.stringify(claim, null, 2)}\n`, 'utf8');
+    return claim;
+  }
+
+  function ackDispatchClaim(root, eventFile, actor, status, reason = '') {
+    const normalizedActor = validateDispatchActor(actor);
+    const normalizedStatus = String(status || '').trim();
+    if (!['picked', 'skipped', 'failed'].includes(normalizedStatus)) {
+      throw new Error(`Invalid dispatch ack status: ${normalizedStatus}`);
+    }
+    const normalizedReason = String(reason || '').trim();
+    if (['skipped', 'failed'].includes(normalizedStatus) && !normalizedReason) {
+      throw new Error(`dispatches --ack --status ${normalizedStatus} requires --reason`);
+    }
+
+    const eventPath = dispatchEventFilePath(root, eventFile);
+    const event = readDispatchEventFile(eventPath);
+    validateDispatchEventOrThrow(event);
+
+    const claimPath = dispatchClaimFilePath(root, eventFile);
+    const existingClaim = deps.readDispatchClaimFile(claimPath);
+    if (!existingClaim) throw new Error(`Dispatch claim not found: ${eventFile}`);
+    if (existingClaim.actor !== normalizedActor) {
+      throw new Error(`Dispatch claim actor mismatch: ${existingClaim.actor}`);
+    }
+    const currentEventSha256 = dispatchEventDigest(eventPath);
+    if (existingClaim.event_sha256 && existingClaim.event_sha256 !== currentEventSha256) {
+      throw new Error('Dispatch claim event digest mismatch; claim must be manually reviewed before ack');
+    }
+
+    const now = new Date().toISOString();
+    const claim = {
+      ...existingClaim,
+      event_sha256: currentEventSha256,
+      status: normalizedStatus,
+      updated_at: now,
+      ack: {
+        status: normalizedStatus,
+        reason: normalizedReason,
+      },
+      safety: dispatchClaimSafety(),
+    };
+
+    fs[writeFileSyncKey](claimPath, `${JSON.stringify(claim, null, 2)}\n`, 'utf8');
+    return claim;
+  }
+
+  function dispatchClaimEnvelope(root, mode, options) {
+    if (mode === 'claims') {
+      const claims = listDispatchClaims(root).map((claim) => claimSummary(claim, root));
+      const quality = claims.flatMap((claim) => claim.audit ? claimAuditQuality(claim.audit) : []);
+      return {
+        mode: 'dispatch-claims-list',
+        ok: true,
+        state_present: fs.existsSync(workflowPath(root)),
+        summary: {
+          claims_present: claims.length > 0,
+          count: claims.length,
+          stale_count: claims.filter((claim) => claim.audit?.stale).length,
+          digest_mismatch_count: claims.filter((claim) => claim.audit && !claim.audit.event_digest_matches).length,
+        },
+        claims,
+        quality,
+        action: `dispatch claim state was listed with stale/recovery audit. No skill execution, platform API, subagent, MCP, ${backgroundProcessField}, git, worktree, or business source write occurred.`,
+      };
+    }
+
+    if (mode === 'claim') {
+      if (!options.actor) throw new Error('dispatches --claim requires --actor');
+      const claim = claimDispatchEvent(root, options.dispatchEvent, options.actor);
+      return {
+        mode: 'dispatch-claim',
+        ok: true,
+        state_present: fs.existsSync(workflowPath(root)),
+        claim: claimSummary(claim, root),
+        safety: dispatchClaimSafety(),
+        quality: [],
+        action: `dispatch event was claimed for manual pickup. No skill execution, platform API, subagent, MCP, ${backgroundProcessField}, git, worktree, or business source write occurred.`,
+      };
+    }
+
+    if (!options.actor) throw new Error('dispatches --ack requires --actor');
+    if (!options.ackStatus) throw new Error('dispatches --ack requires --status');
+    const claim = ackDispatchClaim(root, options.dispatchEvent, options.actor, options.ackStatus, options.reason);
+    return {
+      mode: 'dispatch-ack',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      claim: claimSummary(claim),
+      safety: dispatchClaimSafety(),
+      quality: [],
+      action: `dispatch claim acknowledgement was recorded. No skill execution, platform API, subagent, MCP, ${backgroundProcessField}, git, worktree, or business source write occurred.`,
+    };
+  }
+
+  return {
+    validateDispatchActor,
+    writeDispatchEvent,
+    claimDispatchEvent,
+    ackDispatchClaim,
+    dispatchClaimEnvelope,
+  };
+}