feat(tracking): decode and persist current device tracking interval from mc=11 events

[brockamer]

During #197's investigation, we discovered the Mini 3 Plus emits messageCode=11 ("Track Interval") events when its active tracking interval changes — and the new interval value is conveyed in status.intervalChange (seconds) on the event payload. Per Garmin IPC Outbound spec §Message Codes Table.

We currently silent-drop mc=11 events via the standard non-Free-Text path (src/app.ts:225 area, non_free_text log line). With LOG_TRACK_PAYLOADS=true shipped in #199/#200 we now persist the full payload to logs, but we don't programmatically know the device's currently-active tracking interval at the moment of handleStopTrack.

Knowing it would let us:

• Tag the refusal SMS for track_too_brief and track_no_pings with a hint: "device interval is 4hr — set it shorter in Garmin Explore" (high-signal operator advice that doesn't fit in 160 chars right now).
• Expose the active interval in published track post frontmatter for diagnostics.
• Correlate session-publish failures across time with device autonomous-interval-flap behavior — feeds into investigate: live-prod findings contradict spec §0 (mc=0 events + Satellite transport) #194's investigation.

Current state

• mc=11 events arrive at /garmin/ipc and are silent-dropped (logged as non_free_text with full payload when LOG_TRACK_PAYLOADS=true, which is now the default).
• The status.intervalChange field (seconds; 0 = unchanged) is in the payload but not extracted programmatically.
• Per Garmin spec, intervalChange ALSO appears on mc=0/10/12 events — we could read it on any event, not just mc=11.

Acceptance criteria

Expand

• A new KV key (e.g. track_interval:<imei>) tracks the device's last-known tracking interval in seconds, updated on any incoming event whose status.intervalChange > 0.
• TTL ~24h (matches existing track_start TTL semantics).
• handleStopTrack reads this key and includes it in the refusal SMS for track_too_brief / track_no_pings branches (within the 160-char budget — likely needs wording iteration).
• Optional: include the value in published track post frontmatter (device_interval_seconds).
• Regression tests for the KV write path and the refusal-SMS variant.
• Real-device verification: change interval mid-session via the device UI, confirm the KV value updates.

Depends on

• (none — chore(observability): enable LOG_TRACK_PAYLOADS by default in all envs #199/chore(observability): enable LOG_TRACK_PAYLOADS by default in all envs (#199) #200 already shipped the diagnostic logging that surfaces these payloads)

Related

• fix(tracking): single-ping Stop Track sessions publish zero-distance "ghost" posts (LLM hallucinates speeds) #197 (discovery of mc=11 / intervalChange semantics)
• chore(observability): enable LOG_TRACK_PAYLOADS by default in all envs #199 / chore(observability): enable LOG_TRACK_PAYLOADS by default in all envs (#199) #200 (LOG_TRACK_PAYLOADS default flip — feeds this)
• investigate: live-prod findings contradict spec §0 (mc=0 events + Satellite transport) #194 (live-prod findings re: mc=0 + Satellite transport — same device-behavior investigation)

Model & execution guidance

Cheap-tier work (USE a Haiku subagent):
  - Confirm the intervalChange field's range across recent production
    logs (now that LOG_TRACK_PAYLOADS=true is the default)
  - Scan Garmin IPC Outbound spec for any edge cases (negative values?
    reset semantics?) we haven't accounted for

Standard-tier work (USE a Sonnet subagent):
  - Add KV write path in the non_free_text inbound handler (one new
    helper in src/core/tracking.ts that updates track_interval:<imei>
    on any event with status.intervalChange > 0)
  - Read the key in handleStopTrack; thread into refusal SMS variants
  - Update tests/tracking.test.ts and tests/app.test.ts coverage
  - Update CLAUDE.md / PRD if device interval behavior becomes
    user-visible (publishable frontmatter, etc.)

Smart-tier moments (USE `advisor()`):
  - 160-char budget for refusal SMS gets tight when you add the
    interval hint — likely needs a phrasing-vs-truncation deliberation
  - Should the refusal SMS recommend specific interval values (e.g.
    "interval is 14400s; try 120s")? Or just nudge to "check device
    interval setting"? UX trade-off worth a second opinion

Subagent dispatches (USE these for the noted task):
  - Sonnet for the KV plumbing + handleStopTrack thread-through (~80
    line diff)
  - Haiku for the log-scan confirmation

Execution sketch:
  1. Spec the KV shape (one int + one timestamp? just the int?)
  2. Add the write path in the inbound handler
  3. Read in handleStopTrack; iterate on SMS wording
  4. Tests
  5. Real-device verification with explicit interval changes

[brockamer]

Session 2026-05-21 — Device-test sequence (post-merge acceptance gate)

State: Implementation merged via PR #205 (commit 0ae4bba, deployed to production 2026-05-18 at 15:28Z). All 420 tests green; KV write path, refusal-SMS read path, and the mc=12-self-latch ordering invariant all asserted in CI. Outstanding: real-device verification against the Mini 3 Plus.

Next action on pickup: run the device-test sequence below. The acceptance gate is observing the (interval: 4h) paren-tag on a refusal SMS from production.

---

Device-test sequence

Total time: ~5 minutes once outside. Stand outside with clear sky view first — the Mini needs Iridium line-of-sight to transmit. Wait for the satellite icon to confirm signal lock.

Step 1 — Pick a distinctive interval value

On the device: Settings → Tracking → Send Interval.

• If your current interval is NOT 4 hours: set it to 4 hours (will appear as (interval: 4h) in the SMS).
• If your current interval IS already 4 hours: set it to 10 minutes instead (will appear as (interval: 10m)).

Pick a value that's clearly different from whatever's already set — that way you know the change registered and didn't just no-op.

Step 2 — Start Track

Press Start Track on the device. The device transmits a mc=10 Start Track event, which carries the new interval value in its status.intervalChange field. The Worker should latch this to KV (track_interval:<imei> in the prod TS_TRACKS namespace, id 4b81a282e191454ca01dc7406bfd4f78).

Step 3 — Wait ~30 seconds

Let the device's Iridium transmission complete. Reply latency can run up to ~75s on the Mini 3 Plus per prior observation, but Start Track itself goes out within a few seconds.

Step 4 — Stop Track

Press Stop Track. The Worker pulls MapShare for the ~30-second window. At a 4-hour interval (or even 10 minutes), there won't be any breadcrumbs in that window, so the Worker will refuse to publish.

Expected SMS reply (within ~30-60s):

Track ended; no breadcrumbs in MapShare for this window. (interval: 4h)

OR

Track too brief — 1 breadcrumb. Try longer or move sooner after Start. (interval: 4h)

Either is a green light — both prove the read path works.

Step 5 — (Optional but recommended) Test the no_active_session branch

Without starting a new session, press Stop Track AGAIN immediately after the SMS in step 4 arrives. The first Stop cleared the session record, so this second one hits a different refusal branch.

Expected SMS reply:

Track ended; no active session was recorded — nothing to publish. (interval: 4h)

Step 6 — Cleanup

Reset Settings → Tracking → Send Interval back to your usual default (2 minutes / 120s, or whatever you normally run).

---

What "done" looks like

• ✅ Green: (interval: 4h) (or (interval: 10m) if used) suffix appears on the refusal SMS → close this issue, mark the acceptance gate satisfied.
• ❌ Yellow: Refusal SMS arrives but without the (interval: …) suffix → KV write didn't fire. Debug: wrangler tail against prod during the test, look for track_interval_recorded log event or its absence. Possible cause: device didn't include intervalChange on the events transmitted; may need to force an mc=11 separately.
• ❌ Red: No SMS at all → either Iridium delivery delay (give it 75s+) or actual Worker error. Check wrangler tail for stop_track_handler_error log lines.

Useful inspection commands during the test

# Watch prod Worker logs live
pnpm wrangler tail --env production --format pretty

# Check the latched interval in prod KV directly (use your IMEI)
pnpm wrangler kv key get --namespace-id 4b81a282e191454ca01dc7406bfd4f78 \
  "track_interval:300052030374220" --remote

Reference

• PR: feat(tracking): latch device tracking interval, surface in refusal SMS (#201) #205 (merged 2026-05-18)
• Production deploy: https://github.com/brockamer/trailscribe/actions/runs/26043170698
• KV namespace (prod TS_TRACKS): 4b81a282e191454ca01dc7406bfd4f78
• Operator IMEI seen in prior prod logs: 300052030374220

[brockamer]

Guidance audit (#1)

• Smart-tier decisions: routed through advisor()? [yes]
  • advisor() before PR was load-bearing — caught the missing mc=12-self-latch ordering test
    and surfaced that the scope extension to no_active_session needed to be called out in the
    PR body, not buried in the diff.
• Were your session's model and dispatch choices well-matched to the work size? [yes]
  • ~80 LOC well-bounded change with clear AC; inline-at-Opus avoided subagent round-trip
    overhead and kept the design conversation in one context. The Sonnet dispatch the
    file-time guidance suggested would have added cost without proportionate gain.
• Looking back, did any cheap-tier or surface-mapping work run inline that would have been
  better dispatched? [no]
  • The cheap-tier items in the guidance (log-scan to confirm intervalChange field range, spec
    edge-case scan) were intentionally skipped as low-value for this scope rather than run
    inline. Surface mapping (Reads on app.ts, tracking.ts, types.ts, tests) was load-bearing
    for the inline design decisions and benefited from being in-context.