docs(quick-260610-i4x): plan/summary/verification + STATE row (node-cron→setInterval, Verified)

.planning/STATE.md

@@ -148,6 +148,7 @@ Recent decisions affecting current work:
 | 260610-cr8 | Adopt drizzle generate+migrate workflow, retire db:push on MariaDB — removed db:push script + repointed deployment.md to migrate with anti-push warning; dry-verified no destructive diff | 2026-06-10 | 1a95d81 | Verified | [260610-cr8-adopt-drizzle-generate-migrate-workflow-](./quick/260610-cr8-adopt-drizzle-generate-migrate-workflow-/) |
 | 260610-czd | Fix docs/deployment.md local-dev command — added "Running locally (host-side, no Docker)" subsection with correct env-sourced two-terminal run command (Phase 2 UAT gap) | 2026-06-10 | 39e2ee0 |  | [260610-czd-fix-docs-deployment-md-local-dev-command](./quick/260610-czd-fix-docs-deployment-md-local-dev-command/) |
 | 260610-hbu | Phase 5 reminder scheduler resilience (UAT Test 1 gap) — catch-up scan `(now, now+16min]` + per-uid exactly-once dedup so a missed/late cron tick no longer drops a reminder; lead-accurate body; also fixes pre-existing cross-tick double-fire. 10/10 reminder tests pass | 2026-06-10 | 19d92c6 | Verified | [260610-hbu-make-phase-5-reminder-scheduler-resilien](./quick/260610-hbu-make-phase-5-reminder-scheduler-resilien/) |
+| 260610-i4x | Replace node-cron with setInterval in all 3 broker workers (poller/outbox/reminder) — node-cron 4.2.1 skipped EVERY scheduled execution in the long-running API process ("missed execution" each tick), so reminders/poll/outbox never fired on schedule. setInterval fires reliably (verified). 91 broker tests pass | 2026-06-10 | d9efbc1 | Verified | [260610-i4x-replace-node-cron-with-setinterval-in-ba](./quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/) |
 
 ## Deferred Items
 

.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-PLAN.md

@@ -0,0 +1,164 @@
+---
+phase: quick-260610-i4x
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - apps/api/src/broker/poller.ts
+  - apps/api/src/broker/outboxWorker.ts
+  - apps/api/src/broker/reminderScheduler.ts
+autonomous: true
+requirements:
+  - QUICK-i4x
+must_haves:
+  truths:
+    - "The three background workers schedule their callbacks with setInterval, not node-cron schedule()"
+    - "No worker file imports node-cron"
+    - "runPoll / runOutboxDrain / runReminderCheck callback bodies are unchanged (still .catch-wrapped)"
+    - "Interval timings are preserved: poller 5 min, outbox 15 s, reminder 1 min"
+    - "apps/api typechecks clean and the broker unit tests still pass"
+  artifacts:
+    - path: "apps/api/src/broker/poller.ts"
+      provides: "startBrokerPoller scheduling runPoll via setInterval(5min)"
+      contains: "setInterval"
+    - path: "apps/api/src/broker/outboxWorker.ts"
+      provides: "startOutboxWorker scheduling runOutboxDrain via setInterval(15s)"
+      contains: "setInterval"
+    - path: "apps/api/src/broker/reminderScheduler.ts"
+      provides: "startReminderScheduler scheduling runReminderCheck via setInterval(1min)"
+      contains: "setInterval"
+  key_links:
+    - from: "apps/api/src/broker/poller.ts"
+      to: "runPoll"
+      via: "setInterval(cb, 5 * 60 * 1000)"
+      pattern: "setInterval\\("
+    - from: "apps/api/src/broker/outboxWorker.ts"
+      to: "runOutboxDrain"
+      via: "setInterval(cb, 15 * 1000)"
+      pattern: "setInterval\\("
+    - from: "apps/api/src/broker/reminderScheduler.ts"
+      to: "runReminderCheck"
+      via: "setInterval(cb, 60 * 1000)"
+      pattern: "setInterval\\("
+---
+
+<objective>
+Replace the node-cron `schedule()` scheduling mechanism with `setInterval` in the three
+background worker `start*` functions so scheduled tasks actually fire in the long-running
+API process.
+
+Purpose: node-cron 4.2.1 silently skips scheduled executions in the long-lived server
+process — the orchestrator proved this live against the running prod container (continuous
+`[NODE-CRON][WARN] missed execution` at every tick while CPU sat at 0.15%; a plain
+`setInterval(…,1000)` in the SAME container fired 8/8 ticks, and a FRESH node-cron process
+fired 8/8 — only the long-lived process misbehaves). Net effect: the CalDAV poller, the
+outbox drain, and the reminder scan never fire on schedule. They only ran when triggered
+manually during debugging.
+
+Output: Three worker files where `startBrokerPoller`, `startOutboxWorker`, and
+`startReminderScheduler` schedule their existing callbacks with `setInterval` at the same
+intervals, with the now-unused `node-cron` import removed and stale doc comments updated.
+</objective>
+
+<execution_context>
+@$HOME/.claude/gsd-core/workflows/execute-plan.md
+</execution_context>
+
+<context>
+@./CLAUDE.md
+
+# The three worker files — only the start* functions and their doc comments change.
+# Do NOT modify runPoll / runOutboxDrain / runReminderCheck logic.
+@apps/api/src/broker/poller.ts
+@apps/api/src/broker/outboxWorker.ts
+@apps/api/src/broker/reminderScheduler.ts
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Swap node-cron schedule() for setInterval in the three worker start* functions</name>
+  <files>apps/api/src/broker/poller.ts, apps/api/src/broker/outboxWorker.ts, apps/api/src/broker/reminderScheduler.ts</files>
+  <action>
+In each of the three files, replace the node-cron scheduling call inside the start* function
+with a setInterval call, keeping the callback body EXACTLY as written (it already wraps the
+run function in `.catch(...)`). Then remove the now-unused `import { schedule } from 'node-cron'`
+line from each file. Do NOT touch runPoll / runOutboxDrain / runReminderCheck, the constants,
+helpers, or any other code. Do NOT touch index.ts, package.json, or the lockfile — the start*
+function names and signatures are unchanged so index.ts keeps working as-is.
+
+Exact mapping (interval in ms = the cron cadence; setInterval fires after the first interval,
+same first-run timing as the old cron — do NOT add an immediate kick, that is out of scope):
+
+- poller.ts `startBrokerPoller`: change `schedule('*/5 * * * *', () => { ... })` to
+  `setInterval(() => { ... }, 5 * 60 * 1000)` — keep the same arrow-function callback body
+  (the `runPoll().catch(...)` block).
+
+- outboxWorker.ts `startOutboxWorker`: change `schedule('*/15 * * * * *', () => { ... })` to
+  `setInterval(() => { ... }, 15 * 1000)` — keep the same `runOutboxDrain().catch(...)` body.
+
+- reminderScheduler.ts `startReminderScheduler`: change `schedule('* * * * *', () => { ... })`
+  to `setInterval(() => { ... }, 60 * 1000)` — keep the same `runReminderCheck().catch(...)` body.
+
+Do NOT call `.unref()` on the returned Timer — we WANT the interval to keep the event loop
+alive (same effect as cron kept the process alive). Storing the returned Timer handle in a
+module-level variable is acceptable if cleaner, but not required — fire-and-forget matches the
+current pattern (the workers run for the process lifetime).
+
+Update the now-stale doc comments that reference node-cron so they describe setInterval, keeping
+the WHY. Specifically:
+  - poller.ts: the file-header line "runs every 5 minutes via node-cron", the
+    "startBrokerPoller wraps it in node-cron's 5-minute schedule." line, the
+    "Source: https://github.com/node-cron/node-cron ..." source line, and the
+    "Starts the 5-minute background polling schedule." block.
+  - outboxWorker.ts: "startOutboxWorker wraps it in a 15-second node-cron schedule." and the
+    "Source: https://github.com/node-cron/node-cron (v4 stable)" line, plus the
+    "Starts the 15-second background outbox drain schedule." block.
+  - reminderScheduler.ts: the file-header "Fires every minute via node-cron." line and the
+    "Start the 1-minute reminder scan schedule." block comment ("keeps the cron out of the test
+    process" → setInterval phrasing).
+Each updated comment must briefly state the WHY (node-cron 4.2.1 skipped scheduled executions
+in the long-running server process, so scheduling uses setInterval instead). Keep edits brief —
+do not rewrite the surrounding decision/threat-mitigation prose. Leave the `node-cron` dependency
+in package.json (now unused, harmless); it is removable later but removing it now risks lockfile
+drift and is out of scope for this tight change.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && ! grep -rn "node-cron" apps/api/src/broker/poller.ts apps/api/src/broker/outboxWorker.ts apps/api/src/broker/reminderScheduler.ts | grep -v '^\s*[0-9]*:.*//' ; grep -c "setInterval" apps/api/src/broker/poller.ts apps/api/src/broker/outboxWorker.ts apps/api/src/broker/reminderScheduler.ts</automated>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api typecheck</automated>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api exec vitest run tests/broker/</automated>
+  </verify>
+  <done>
+All three files import setInterval-based scheduling with no remaining `import { schedule } from 'node-cron'`;
+each start* function calls setInterval at the correct interval (poller 300000 ms, outbox 15000 ms,
+reminder 60000 ms) with its original callback body intact; `pnpm --filter @familysync/api typecheck`
+exits 0; and `pnpm --filter @familysync/api exec vitest run tests/broker/` reports all broker tests
+green (runPoll / runOutboxDrain / runReminderCheck behavior unchanged).
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+- No `import { schedule } from 'node-cron'` remains in any of the three worker files.
+- `grep setInterval` matches in all three files (one per start* function).
+- runPoll / runOutboxDrain / runReminderCheck logic is byte-for-byte unchanged (only doc
+  comments and the scheduling call were touched).
+- `pnpm --filter @familysync/api typecheck` exits 0.
+- `pnpm --filter @familysync/api exec vitest run tests/broker/` passes (crypto, expand, outboxWorker,
+  poller, reminderScheduler, sync, vevent, write). Do NOT run the full suite — it has ~68 pre-existing
+  DB-integration failures unrelated to this change (MariaDB host port not exposed in prod-compose).
+- index.ts, package.json, and the lockfile are untouched.
+</verification>
+
+<success_criteria>
+The three background workers schedule their callbacks via setInterval at the original intervals
+(5 min / 15 s / 1 min), node-cron is no longer imported in src/broker, the apps/api typecheck is
+clean, and the broker unit tests still pass — so in the long-running API process the poller, outbox
+drain, and reminder scan will now actually fire on schedule.
+</success_criteria>
+
+<output>
+Create `.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-SUMMARY.md` when done.
+</output>

.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-SUMMARY.md

@@ -0,0 +1,80 @@
+---
+phase: quick-260610-i4x
+plan: "01"
+subsystem: broker
+tags: [scheduler, setInterval, node-cron, fix]
+dependency_graph:
+  requires: []
+  provides: [reliable-broker-scheduling]
+  affects: [broker/poller, broker/outboxWorker, broker/reminderScheduler]
+tech_stack:
+  added: []
+  patterns: [setInterval-based-scheduling]
+key_files:
+  created: []
+  modified:
+    - apps/api/src/broker/poller.ts
+    - apps/api/src/broker/outboxWorker.ts
+    - apps/api/src/broker/reminderScheduler.ts
+decisions:
+  - "Use setInterval for broker worker scheduling: node-cron 4.2.1 silently skipped executions in the long-running API process; setInterval is reliable in the same process"
+metrics:
+  completed: "2026-06-10"
+---
+
+# Quick Task 260610-i4x: Replace node-cron with setInterval in Broker Workers Summary
+
+**One-liner:** Replaced `node-cron` `schedule()` calls with `setInterval` (300 s / 15 s / 60 s) in all three broker worker `start*` functions so scheduled tasks actually fire in the long-running API process.
+
+## Tasks Completed
+
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| 1 | Swap node-cron schedule() for setInterval in the three worker start* functions | d9efbc1 | poller.ts, outboxWorker.ts, reminderScheduler.ts |
+
+## Changes Made
+
+### apps/api/src/broker/poller.ts
+- Removed `import { schedule } from 'node-cron'`
+- `startBrokerPoller`: `schedule('*/5 * * * *', cb)` → `setInterval(cb, 5 * 60 * 1000)`
+- Updated file-header and JSDoc comments to reference setInterval and document the WHY
+
+### apps/api/src/broker/outboxWorker.ts
+- Removed `import { schedule } from 'node-cron'`
+- `startOutboxWorker`: `schedule('*/15 * * * * *', cb)` → `setInterval(cb, 15 * 1000)`
+- Updated header comment and scheduler JSDoc
+
+### apps/api/src/broker/reminderScheduler.ts
+- Removed `import { schedule } from 'node-cron'`
+- `startReminderScheduler`: `schedule('* * * * *', cb)` → `setInterval(cb, 60 * 1000)`
+- Updated file-header "Fires every minute" line and scheduler JSDoc
+
+Callback bodies (the `.catch`-wrapped `runPoll` / `runOutboxDrain` / `runReminderCheck` calls) are byte-for-byte unchanged. No `.unref()` added — intervals intentionally keep the event loop alive.
+
+## Verification Results
+
+- `! grep -rn "import.*node-cron" apps/api/src/broker/`: exits 1 (no matches) — all imports removed
+- `pnpm --filter @familysync/api typecheck`: **exit 0** — clean
+- `pnpm --filter @familysync/api exec vitest run tests/broker/`: **8 test files passed, 91 tests passed**
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None.
+
+## Threat Flags
+
+None — no new network surface, auth paths, file access, or schema changes introduced.
+
+## Self-Check: PASSED
+
+- [x] `apps/api/src/broker/poller.ts` modified — confirmed
+- [x] `apps/api/src/broker/outboxWorker.ts` modified — confirmed
+- [x] `apps/api/src/broker/reminderScheduler.ts` modified — confirmed
+- [x] Commit d9efbc1 exists on branch gsd/v1.0-milestone
+- [x] No `import { schedule } from 'node-cron'` in any of the three files
+- [x] typecheck: exit 0
+- [x] broker tests: 8 files / 91 tests — all green

.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-VERIFICATION.md

@@ -0,0 +1,73 @@
+---
+phase: quick-260610-i4x
+verified: 2026-06-10T17:08:30Z
+status: passed
+score: 5/5 must-haves verified
+---
+
+# Quick Task 260610-i4x: Verification Report
+
+**Task Goal:** Replace node-cron with setInterval in the three background workers (poller, outboxWorker, reminderScheduler) so scheduled tasks fire in the long-running process.
+**Verified:** 2026-06-10T17:08:30Z
+**Status:** passed
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | The three background workers schedule their callbacks with setInterval, not node-cron schedule() | VERIFIED | Each start* function contains `setInterval(()=>{…}, N)` at lines poller.ts:96, outboxWorker.ts:758, reminderScheduler.ts:210. Zero `schedule(` calls remain in any of the three files. |
+| 2 | No worker file imports node-cron | VERIFIED | All remaining `node-cron` text is inside JSDoc block comments (WHY context). `grep -n "import.*node-cron"` returns no matches. Commit d9efbc1 stat confirms only 3 files changed. |
+| 3 | runPoll / runOutboxDrain / runReminderCheck callback bodies are unchanged (still .catch-wrapped) | VERIFIED | poller.ts:97 `runPoll().catch(...)`, outboxWorker.ts:759 `runOutboxDrain().catch(...)`, reminderScheduler.ts:211 `runReminderCheck().catch(...)` — identical catch wrappers present. |
+| 4 | Interval timings are preserved: poller 5 min, outbox 15 s, reminder 1 min | VERIFIED | poller.ts:100 `5 * 60 * 1000` (300000 ms), outboxWorker.ts:762 `15 * 1000` (15000 ms), reminderScheduler.ts:214 `60 * 1000` (60000 ms). |
+| 5 | apps/api typechecks clean and the broker unit tests still pass | VERIFIED | `pnpm --filter @familysync/api typecheck` exited 0 (no output). `pnpm --filter @familysync/api exec vitest run tests/broker/` reported 8 test files passed, 91 tests passed. |
+
+**Score:** 5/5 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `apps/api/src/broker/poller.ts` | startBrokerPoller scheduling runPoll via setInterval(5min) | VERIFIED | setInterval at line 96, `5 * 60 * 1000` at line 100, `runPoll().catch(...)` callback |
+| `apps/api/src/broker/outboxWorker.ts` | startOutboxWorker scheduling runOutboxDrain via setInterval(15s) | VERIFIED | setInterval at line 758, `15 * 1000` at line 762, `runOutboxDrain().catch(...)` callback |
+| `apps/api/src/broker/reminderScheduler.ts` | startReminderScheduler scheduling runReminderCheck via setInterval(1min) | VERIFIED | setInterval at line 210, `60 * 1000` at line 214, `runReminderCheck().catch(...)` callback |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `apps/api/src/broker/poller.ts` | runPoll | `setInterval(cb, 5 * 60 * 1000)` | VERIFIED | Line 96-100 in startBrokerPoller |
+| `apps/api/src/broker/outboxWorker.ts` | runOutboxDrain | `setInterval(cb, 15 * 1000)` | VERIFIED | Line 758-762 in startOutboxWorker |
+| `apps/api/src/broker/reminderScheduler.ts` | runReminderCheck | `setInterval(cb, 60 * 1000)` | VERIFIED | Line 210-214 in startReminderScheduler |
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+|----------|---------|--------|--------|
+| TypeScript compiles clean | `pnpm --filter @familysync/api typecheck` | exit 0, no output | PASS |
+| Broker unit tests pass | `pnpm --filter @familysync/api exec vitest run tests/broker/` | 8 files / 91 tests passed | PASS |
+
+### Scope Containment
+
+| Check | Result |
+|-------|--------|
+| Commit d9efbc1 touches only 3 files | VERIFIED — git show stat: outboxWorker.ts, poller.ts, reminderScheduler.ts only |
+| index.ts not modified | VERIFIED — not in commit stat |
+| package.json not modified | VERIFIED — not in commit stat |
+| pnpm-lock.yaml not modified | VERIFIED — not in commit stat |
+| No `.unref()` added | VERIFIED — grep returns no matches in any of the three files |
+
+### Anti-Patterns Found
+
+None. All node-cron mentions are in block comments providing WHY context, not imports or calls.
+
+### Human Verification Required
+
+None.
+
+---
+
+_Verified: 2026-06-10T17:08:30Z_
+_Verifier: Claude (gsd-verifier)_