feat(consumer): seed heartbeat check-in defaults

[artemgetmann]

Review Fast Path

• User path fixed: consumer Telegram DM pairing now gets a usable heartbeat delivery default and a real HEARTBEAT.md check-in template for safe/new workspaces.
• Docs added: docs/consumer/heartbeat.md now documents heartbeat defaults, opt-out behavior, personal-tool boundaries, and follow-up context rules.
• Proof: swift test --package-path apps/macos --filter AgentWorkspaceTests; swift test --package-path apps/macos --filter ConsumerBootstrapTests; git diff --check.
• Shared-state footgun removed: heartbeat delivery defaults to the paired DM only, waits for a DM recipient, disables stale setup-owned Telegram heartbeat routes during the pre-DM setup window, pins explicit directPolicy: allow, updates stale setup-owned Telegram recipients/account ids/direct-policy blocks on re-pair, preserves explicit Telegram group/topic/secondary routes, preserves custom non-Telegram heartbeat routes, preserves blank/comment-only HEARTBEAT.md opt-outs, and avoids writing heartbeat files into unsafe arbitrary workspaces.
• Still hurts: delayed opt-in prompts, abandoned-session source-link generation/routing, Telegram-as-me/WhatsApp-as-me personal scans, and goal-mode autonomous continuation are follow-up work.

Why This Matters

• Missing HEARTBEAT.md gave new consumer workspaces no concrete model behavior to review or tune.
• Pairing Telegram was not enough to give heartbeat a sane DM delivery target.
• Re-pairing Telegram must not leave setup-owned heartbeat messages going to a stale previous DM, stale bot account, or blocked direct-send policy.
• The setup phase before the fresh DM is captured must not keep sending heartbeat messages to an old setup-owned DM route.
• Existing users with custom heartbeat content, explicit Telegram destinations, custom non-Telegram routing, blank/comment-only opt-outs, or unrelated workspace folders should not get overwritten.
• Personal comms are privacy-sensitive and token-expensive, so the template now says selected email rather than assuming every mailbox is worth scanning.

Scope Boundary

Changed:

• Seed a concrete consumer heartbeat template only when HEARTBEAT.md is missing and the workspace is safe to seed.
• Preserve custom HEARTBEAT.md content and blank/comment-only opt-outs.
• Configure consumer heartbeat delivery to the paired Telegram DM after DM pairing, unless the user already has a custom non-Telegram heartbeat target or an explicit Telegram route.
• Disable stale setup-owned Telegram heartbeat delivery while Telegram setup is waiting for the fresh owner DM.
• Pin directPolicy: allow for generated paired-DM heartbeat delivery so doctor does not warn on our own generated config and delivery is not dm-blocked.
• Replace stale recipients when converting a disabled target: none heartbeat to Telegram delivery.
• Replace stale recipients, stale account ids, and blocked direct policies only when re-pairing a setup-owned target: telegram heartbeat.
• Preserve explicit Telegram heartbeat routes such as group/topic destinations or secondary recipients, including during the pre-DM setup window.
• Document that abandoned-task nudges should include a source chat/thread link when available and should not continue original-topic work inside the heartbeat DM.

Not changed:

• No setup prompt/nudge state yet.
• No WhatsApp-as-me or Telegram-as-me inbox scanning yet.
• No abandoned-session/task sweep implementation yet.
• No Telegram topic/source-link generation yet.
• No send-as-user routing back into original Telegram topics yet.
• No goal-mode autonomous task continuation.

Product Follow-Up Plan

Setup prompt copy under review:

Want proactive check-ins? I can scan unfinished Jarvis tasks and connected tools like calendar and selected email, then only DM you when something important or urgent needs your attention.

If accepted, optional personal-message opt-in:

Should I also scan your Telegram and WhatsApp messages if/when connected? I’ll read only for action-needed items and never send as you without approval.

Abandoned task behavior to implement later:

• drop: dismiss this exact surfaced item unless it changes materially.
• snooze: suppress until the requested follow-up time.
• continue: route the user's missing input back to the original work context, not continue the task inside heartbeat DM.
• For Telegram topic tasks, use Telegram-as-me only after approval to post the missing info into the original topic/thread.
• Ask before creating a new topic for long-running work.
• Include a Telegram topic/thread link in the heartbeat nudge when runtime metadata makes one available; otherwise name the source and say the direct link is unavailable.

Verification

• swift test --package-path apps/macos --filter AgentWorkspaceTests
• swift test --package-path apps/macos --filter ConsumerBootstrapTests
• git diff --check
• codex review --base origin/main first found a P2 about overwriting blank/comment-only HEARTBEAT.md opt-outs; fixed by seeding only missing files and adding a regression test.
• codex review --base origin/main then found P2s for unsafe workspace writes and stale recipient preservation; fixed by moving heartbeat seeding behind the safety decision and replacing stale recipients when enabling Telegram from target: none.
• codex review --base origin/main then found a P2 about missing generated directPolicy; fixed by pinning directPolicy: allow for paired-DM heartbeat delivery.
• codex review --base origin/main then found a P1 about stale explicit Telegram heartbeat recipients on re-pair; fixed by updating setup-owned to values.
• codex review --base origin/main then found a P2 about stale explicit heartbeat account ids on re-pair; fixed by updating setup-owned accountId to the consumer default.
• codex review --base origin/main then found a P2 about preserving blocked direct policy while enabling DM delivery; fixed by forcing setup-owned directPolicy: allow.
• codex review --base origin/main then found a P2 about clobbering explicit Telegram routes; fixed by tracking the previous paired DM and only replacing known setup-owned routes.
• codex review --base origin/main then found a P2 about preserving stale setup-owned Telegram heartbeat routing during the pre-DM setup window; fixed by disabling setup-owned heartbeat delivery until the fresh owner DM is captured.
• Commit hook ran after repairing this worktree's node_modules with repo-pinned pnpm 10.23.0.

AI Assistance

• AI-assisted
• Testing degree: targeted

[github-actions]

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

[github-actions]

Closing due to inactivity.
If you believe this PR should be revived, post in #pr-thunderdome-dangerzone on Discord to talk to a maintainer.
That channel is the escape hatch for high-quality PRs that get auto-closed.