feat(monitor): route explicit process exits

[artemgetmann]

Review Fast Path

• User path fixed: explicit goal/monitor waits can arm a background exec and get woken by that process exit instead of waiting for the next cadence tick.
• Proof: targeted monitor/exec/cron regression suites pass; tsgo, format:check, git diff --check, and codex review --base origin/main pass.
• Shared-state footgun removed: fast process exits are stored as bounded pending monitor events and replayed when the matching durable monitor is created; monitor and cron writes share the same monitor-store lock.
• Still hurts: no live runtime restart or live Telegram/WhatsApp/Gmail send proof in this slice; node-host process exits are not wired here.

Summary

• Problem: explicit waits that depend on a local process finishing had no durable monitor wake path, so they could fall back to polling/cadence or miss a fast exit.
• Why it matters: goal mode is the user-facing contract; monitors are the durable continuation state. Process completion is a real trigger for explicit waits and should wake the monitor session with evidence.
• What changed: added opt-in monitorExit for background exec sessions, routes process_exit envelopes through monitor.routeEvent, persists process-exit evidence into lastCheckpoint, and replays bounded pending process exits when a matching monitor is created.
• What did NOT change (scope boundary): no second /goal system, no broad UX rewrite, no node-host process-exit wiring, no live Telegram/WhatsApp/Gmail listener implementation, and no default wake for unarmed background execs.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related feat(jarvis): add goal mode session plumbing #1017
• Related feat(monitor): add hook monitor event ingress #1081
• Related feat(gmail): route monitor event pushes #1084

User-visible / Behavior Changes

• Background exec can now be explicitly armed with monitorExit=true; when that armed process exits, Jarvis emits a process_exit monitor event.
• Foreground execs and unarmed background execs stay silent.
• Matching process-exit monitor wakes receive exit evidence through lastCheckpoint.processExitEvent.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? Yes
• Data access scope changed? No
• Risk + mitigation: monitorExit is opt-in, background-only, and routes only through existing monitor.routeEvent gateway scope. Routing failures are logged and do not change exec completion semantics.

Repro + Verification

Environment

• OS: macOS local isolated worktree
• Runtime/container: no shared/default Jarvis runtime restart
• Model/provider: local test/typecheck only
• Integration/channel (if any): none live
• Relevant config (redacted): temp test stores only

Steps

1. Create or load a durable monitor record with a process_exit trigger for a specific exec session.
2. Run a background exec with monitorExit=true.
3. Send or buffer the matching process_exit monitor event envelope.
4. Verify the monitor route enqueues the cron wake and persists exit evidence.

Expected

• Matching monitor wakes are enqueued.
• Non-matching process exits do not wake monitors.
• Fast process exits before monitor creation are replayed once the matching monitor exists.
• Existing cron/cadence, Gmail/local-listener routing, and origin routing remain intact.

Actual

• Covered by focused tests and integration-style temp-store tests listed below.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • npx -y pnpm@10.23.0 vitest run src/monitor/event-router.test.ts src/gateway/server-methods/monitor.test.ts src/agents/bash-tools.test.ts -> 3 files, 71 tests passed.
  • npx -y pnpm@10.23.0 vitest run src/gateway/server-cron.test.ts src/gateway/server.cron.test.ts -> 2 files, 19 tests passed.
  • npx -y pnpm@10.23.0 vitest run src/monitor/event-router.test.ts src/gateway/server.hooks.test.ts src/gateway/server-methods/monitor.test.ts src/agents/tools/monitor-tool.test.ts src/agents/tools/goal-tools.test.ts src/config/sessions/goals.test.ts src/agents/bash-tools.exec.approval-id.test.ts src/agents/bash-tools.exec-runtime.test.ts src/agents/bash-tools.test.ts src/gateway/server-cron.test.ts src/gateway/server.cron.test.ts -> 11 files, 152 tests passed.
  • npx -y pnpm@10.23.0 tsgo -> passed.
  • npx -y pnpm@10.23.0 format:check -> passed.
  • git diff --check -> passed.
  • codex review --base origin/main -> no introduced correctness issues found.
• Edge cases checked:
  • unarmed background exec emits no process-exit monitor event
  • foreground exec emits no process-exit monitor event
  • approved gateway exec preserves monitorExit
  • non-matching process_exit does not wake
  • fast process_exit before monitor creation is buffered and replayed
  • cron monitor-store writes share the same lock as route/create/update/stop writes
• What you did not verify:
  • no live runtime restart
  • no live Telegram/WhatsApp/Gmail sends
  • no pnpm build / packaged CLI runtime proof
  • no node-host process-exit trigger wiring

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• Older monitor stores without pendingEvents continue to load. The new top-level pendingEvents field is optional and bounded.

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert this PR commit.
• Files/config to restore: src/agents/bash-*, src/gateway/server-methods/monitor.ts, src/gateway/server-cron.ts, src/monitor/*.
• Known bad symptoms reviewers should watch for: armed background exec exits do not enqueue monitor wakes, duplicate process-exit wakes, or monitor-store pendingEvents being lost during concurrent cron writes.

Risks and Mitigations

• Risk: process exits can occur before the monitor record is saved.
  • Mitigation: unmatched process_exit events are stored in a bounded pending-event backlog and replayed during monitor.create.
• Risk: concurrent cron writes can overwrite pending process-exit events.
  • Mitigation: monitor handlers and cron monitor writes share withMonitorStoreWriteLock.
• Risk: external event evidence could be treated as authority.
  • Mitigation: wake message exposes exit details as checkpoint evidence; monitor logic still instructs agents to inspect fresh source state and evaluate stop conditions with evidence.

AI Assistance

• AI-assisted
• Testing degree: targeted