Gateway Module — `dispatch/`

1. Purpose

The dispatch module owns the full lifecycle of CyberShinobi agent dispatches: creation, milestone progress, completion, and the three background detectors that reconcile agent liveness against reality. It is the largest gateway module (~2,275 TS lines) and the only module that mounts two Express routers — /api/dispatch (lifecycle CRUD) and /api/timeline (SSE event stream). It also hosts a process-local timeline event bus that fans repository/detector writes out to SSE subscribers, and three independent setInterval-driven services: the stall detector, the filesystem-heartbeat daemon, and the dispatch garbage collector. Dispatch rows are the canonical post-dispatch record; agent output cache entries link to them by dispatch_id.

2. File Inventory

3. Public API Surface

REST Endpoints — /api/dispatch (mount: index.ts:734)

REST Endpoints — /api/timeline (mount: index.ts:735, SSE)

MCP Tools

The dispatch write-path is fronted by MCP tools registered in mcp/index.ts (documented in the mcp module spec). Dispatch-relevant tools: report_dispatch/report_dispatch_raw, report_progress/report_progress_raw, report_complete/report_complete_raw (raw twins canonical per Raw Twin Discipline), plus the read-only list_dispatches. No MCP tool targets /api/timeline.

4. Internal API

Exported from index.ts via createDispatchLayer(db, psychicCacheRepo?, notificationService?) → DispatchLayer { repo, router, timelineRouter, stallDetector, fsHeartbeatDetector, dispatchGc }.

DispatchRepository (types.ts) methods: create, getMaxId, findById, findActive, findByMission, findByAgent, findRecent, updateProgress, complete, markStalled.

eventBus.ts exports the timelineBus singleton with emitTimelineEvent(event) and onTimelineEvent(listener) → unsubscribe. Consumed cross-module by psychic-cache/repository.ts (cache_write events) and activity/repository.ts (activity events).

fs-heartbeat.ts exposes sweepOnce(): SweepResult for verification probes. dispatch-gc.ts exposes sweep() for opportunistic invocation.

5. Background Services

Three setInterval services, started/stopped from index.ts:928-946 alongside the shared DB handle.

Timeline emission discipline (all three + repository): events emitted via setImmediate after the DB write commits, so SSE subscribers can safely re-read the row.

6. Data Contracts

Zod schemas in types.ts:

• ReportDispatchInputSchema: agent_name (min 1), task_description (min 1), mission_namespace?, milestones (string[], min 1), retry_of? (positive int), plan_slug?, channel? (vscode|hermes, default vscode), session_id?.
• ReportProgressInputSchema: dispatch_id (positive int), milestone_name (min 1), notes?.
• ReportCompleteInputSchema: dispatch_id (positive int), result_summary (min 1), confidence (high|medium|low), domain_affinity (boolean), output_content?.

DispatchRecord (readonly interface) carries 22 fields incl. status (dispatched|active|completed|failed|stalled|silent_but_live), milestones[], retry_of, plan_slug, fs_last_activity, jsonl_path, completion_notified_at, hang_notified_at, channel, session_id. TimelineEvent (eventBus.ts): kind (7 kinds), dispatch_id (nullable), agent_name, mission_namespace, created_at, detail?.

7. Dependencies

• Gateway modules consumed: shared/zod-error.js (formatZodError); psychic-cache/types.js (PsychicCacheRepository — optional, for output-missing probe + backfill); notifications/notification-service.js (NotificationService — optional, Telegram). eventBus is consumed BY psychic-cache and activity (reverse dependency).
• External libraries: better-sqlite3, express, zod, Node fs/os/path/events.
• Environment variables: VAULT_ROOT (falls back to the hard-coded Google Drive SageLibrary path); HOME (subagent JSONL root resolution).

8. Test Coverage

9. Known Limitations

• dispatch_gc_closed events are NOT forwarded to SSE subscribers. eventBus.ts declares the kind and dispatch-gc.ts emits it, but the dispatch-scoped shouldForward in timeline-routes.ts only whitelists milestone, dispatch_complete, dispatch_stalled, dispatch_silent_but_live — dispatch_gc_closed and cache_write/activity (for the scoped route) fall through to return false. GC closures are invisible on the dispatch-scoped timeline stream. [DIVERGENCE — MEDIUM] Confirmed by source read at HEAD 5c9a304.
• Timeline SSE and post-AK-415 Bearer gate collide. /api/timeline/stream* are GET under a now-Bearer-required prefix, but expose no ?token= query-param handshake (unlike /api/sessions/events, which does). A browser EventSource cannot set an Authorization header, so these streams are unreachable from an unauthenticated EventSource — the dashboard must proxy with a Bearer token or the stream 401s. [DIVERGENCE — worth gray-fox/genji review]
• FS-heartbeat daemon runs on the gateway (VPS) host; it cannot stat operator-Mac subagent JSONLs for VS Code channel dispatches (D1220 cross-host evidence) — hence the D1222 NULL non-vote fix. silent_but_live is effectively a Hermes-channel-only signal until Path A wiring lands.
• markStalled(ids) on the repository interface is largely vestigial — the stall detector writes stalled directly via its own prepared statement; markStalledFn in the repo emits events but the primary sweep path does not call it.

10. Change History