Summary

Reshape PR #675's recipes/restart-sweep/ directory into a single self-contained recipes/restart-sweep.md recipe with the (fixed) script inlined as a fenced code block. Apply 8 code-quality fixes, port + extend the test suite to bun:test (12 ported + 14 new = 26 cases + 1 sentinel guard = 27 total).

Why land it as a recipe, not a default behavior: restart-sweep is host-specific to OpenClaw + Telegram + webhook mode. CLAUDE.md is explicit that host-specific operational tooling lives as plugin handlers in the host's own repo, not in gbrain core. So it ships as an opt-in recipe alongside twilio-voice-brain, email-to-brain, etc. — discoverable via gbrain integrations list, only "configured" when the user sets the OpenClaw envs. The recipe body documents the v2 upgrade path: registered Minion handler in the openclaw repo against gbrain/minions (see docs/guides/plugin-handlers.md).

Commits:

• feat(recipes): reshape restart-sweep into single .md recipe + harden script — the meat of the change. New recipes/restart-sweep.md with frontmatter (no expect_exit_code, schema doesn't have it) + agent-facing setup body + inlined ~325-line script with 8 fixes. New test/restart-sweep.test.ts with 27 bun:test cases anchored on a <!-- restart-sweep:script --> sentinel comment. Old recipes/restart-sweep/ directory deleted.
• chore: bump version and changelog (v0.28.3) — VERSION + package.json + CHANGELOG entry written in the GStack release-summary voice.
• docs: sync README + CLAUDE.md for v0.28.3 restart-sweep recipe — README's recipes table gets the new row, CLAUDE.md's test inventory gets the new test annotation, llms-full.txt regenerated via bun run build:llms.

Test Coverage

CODE PATHS                                            STATUS
[+] recipes/restart-sweep.md (inlined script ~325 lines)
  ├── determineAlertMode (3 modes)                    ✓ 3 cases
  ├── filterTelegramSessions (3 paths)                ✓ 3 cases
  ├── detectDroppedMessages
  │   ├── abortedLastRun primary                      ✓ tested
  │   ├── topic extraction                            ✓ tested
  │   ├── malformed key fallback                      ✓ tested
  │   ├── AGGRESSIVE=unset (silent)                   ✓ NEW
  │   └── AGGRESSIVE=1 (fires)                        ✓ NEW
  ├── timing window correctness                        ✓ NEW
  ├── log timestamp regex (Gateway + OpenClaw)        ✓ 2 cases
  ├── loadAlerted (missing/corrupt/prune)             ✓ 3 NEW
  ├── saveAlerted (atomic tmp+rename)                 ✓ NEW
  ├── cooldown layer (not-in-map / suppress / expire) ✓ 3 NEW
  ├── round-trip (2nd invocation skips alerted)       ✓ NEW
  ├── alert formatting (real \n)                      ✓ NEW
  ├── execFile argv shape (no shell)                  ✓ NEW
  ├── GBRAIN_HOME path override                       ✓ NEW
  ├── constructor-time env reads                      ✓ NEW
  └── sentinel-shape guard                            ✓ NEW

COVERAGE: 27/27 paths (100%)  |  bun test test/restart-sweep.test.ts → 27 pass / 0 fail
Tests: 3902 → 3929 (+27 new)

Coverage gate: PASS (100%).

Pre-Landing Review

Already cleared via /plan-eng-review (6 issues, all 6 resolved with recommended option) and /codex consult mode (8 findings, all 8 resolved). The plan file at ~/.claude/plans/figure-out-if-we-eager-coral.md carries the full review trace.

Codex caught 2 silent-correctness bugs the eng review missed:

• C1 (idempotency key collapse): original (sessionKey, restartTimeIso) key changes every run when the bootstrap log is missing, so the same stale session re-alerts forever. Fixed by adding a (sessionKey, lastAlertedAt) cooldown layer with 6h re-alert threshold.
• C2 (import-time env snapshot): original script snapshotted env at module load — tests mutating process.env after import were semantically bogus. Fixed by moving env reads into the MessageSweepDetector constructor.

Eval Results

No prompt-related files changed — evals skipped.

Greptile Review

No Greptile comments on the PR.

Scope Drift

CLEAN. Branch intent: reshape PR #675's recipe shape + apply the 8 code fixes + add proper bun:test coverage. Delivered: same. No files outside recipes/restart-sweep.{md,mjs}, test/restart-sweep.test.ts, or the doc-sync targets.

Plan Completion

• [DONE] Single self-contained recipes/restart-sweep.md (D2)
• [DONE] No expect_exit_code in command health_check (D1)
• [DONE] Atomic tmp+rename write for alerted.json (D3)
• [DONE] Corrupt-JSON recovery in loadAlerted (D4)
• [DONE] 12 ported + 14 new test cases (D5, +1 sentinel guard = 27 total)
• [DONE] AGGRESSIVE-flip recipe-body callout (D6)
• [DONE] Cooldown layer for synthesized restart-time bug (C1)
• [DONE] Constructor-time env reads (C2)
• [DONE] D3-claim wording corrected — atomicity ≠ no-dupes (C3)
• [DONE] Cron environment troubleshooting subsection (C4)
• [DONE] Plugin-handler v2 upgrade-path TODO (C5)
• [DONE] Sentinel-anchored test extractor + ESM-cache-bypass salting (C6)
• [DONE] Recipe-listing-vs-env-presence wording fixed (C7)
• [DONE] Test-runner cite includes both parallel + shard scripts (C8)

12 plan items, 12 done. 0 deferred.

Verification Results

• bun test test/restart-sweep.test.ts → 27 pass / 0 fail
• gbrain integrations show restart-sweep → renders cleanly
• gbrain integrations test recipes/restart-sweep.md → frontmatter validates
• gbrain integrations doctor (with OPENCLAW_OWNER_IDS=test OPENCLAW_TELEGRAM_GROUP=-100) → all 3 health checks pass
• bun run typecheck → clean
• bun run verify → all 7 pre-test gates pass (privacy, jsonb, progress, test-isolation, wasm, admin-build, typecheck)
• bun run test → 3,929 pass / 0 fail across 8 parallel shards + serial pass

TODOS

No TODO items completed in this PR.

Documentation

Updated three files to sync with v0.28.3:

• README.md — added Restart Sweep to the "Getting Data In" recipes table
• CLAUDE.md — added test/restart-sweep.test.ts annotation to the unit-test inventory
• llms-full.txt — regenerated via bun run build:llms

Test plan

• bun test test/restart-sweep.test.ts (27 pass / 0 fail)
• bun run verify (privacy + jsonb + progress + test-isolation + wasm + admin-build + typecheck — all pass)
• bun run test (3,929 pass / 0 fail, no regressions)
• gbrain integrations show restart-sweep renders cleanly
• gbrain integrations test recipes/restart-sweep.md frontmatter validates
• gbrain integrations doctor restart-sweep (with envs set) — all 3 health checks pass
• Real cron-driven dry run on a deployed OpenClaw setup (manual, post-merge)

🤖 Generated with Claude Code