feat(bg): B-0440.1 — standing-by detector skeleton + no-op poll loop (slice 1 of 6)

[AceHack]

Summary

First implementation slice of B-0440 (Standing-by failure-mode detector). Ships ONLY the skeleton — future slices add real detection logic.

What lands

`tools/bg/standing-by-detector.ts` (76 lines):

• `DetectorConfig` type + `DEFAULT_CONFIG` (5min poll / 15min idle threshold)
• `pollOnce()` — no-op result with slice-1 placeholder note
• `runDetector()` — loop scaffolding; `--once` for cron-driven mode
• CLI entry with `--poll-min` / `--idle-min` / `--once` flags

`tools/bg/standing-by-detector.test.ts` (3 tests, all pass):

• Default config thresholds
• `pollOnce` returns ISO-timestamped no-op result
• `runDetector` with `once:true` exits after one iteration

`tools/bg/README.md` — directory purpose + service inventory + run instructions.

Decomposition (per B-0440)

Slice	Status	What
1	THIS PR	Skeleton + no-op poll loop
2	TBD	Commit-history poll via `git log`
3	TBD	PR-activity poll via `gh` CLI
4	TBD	Nudge payload + bus publish (requires B-0400 schema extension for `infinite-backlog-nudge` topic)
5	TBD	Integration with agent subscribers
6	TBD	Cron registration + integration tests

Rule 0 compliance

TypeScript only — no `.sh` files in `tools/bg/`.

Test results

```
bun test v1.3.12
3 pass
0 fail
8 expect() calls
Ran 3 tests across 1 file. [76.00ms]
```

Composes with

• B-0440 (the backlog row this implements; PR docs(backlog): B-0440 + B-0441 + B-0442 — mechanize Standing-by failure mode (3 background services; renumbered from B-0430-0432 due to ID collision with concurrent PRs) #3000 merged earlier today)
• B-0400 (bus protocol — for future slice 4)
• B-0441 / B-0442 (companion services in the mechanization suite)
• PR docs(memory): Aaron architectural challenge — background services must be strong enough that foreground loop is OPTIONAL — mechanize Standing-by failure mode #2998 (architectural challenge that produced these rows)
• PR docs(memory): Aaron substrate-honest discipline triad — stuckness-as-ambiguity + ship-unreviewed-first + decompose-to-dissolve-ambiguity (2026-05-13) #2999 (substrate-honest discipline triad — decomposition discipline)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fa901dffc1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds the first slice of the Standing-by failure-mode detector under tools/bg/ as a Bun-driven background service scaffold, with a no-op polling iteration and basic CLI wiring to support later slices that add real detection and bus integration.

Changes:

• Introduces standing-by-detector.ts with DetectorConfig, pollOnce(), and a polling loop (runDetector()), plus a minimal CLI parser.
• Adds Bun tests covering default config, the no-op poll result shape, and --once execution behavior.
• Documents the tools/bg/ directory purpose, current service inventory, and basic run commands.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
tools/bg/standing-by-detector.ts	New detector skeleton: config types/defaults, no-op polling, loop scaffolding, CLI arg parsing.
tools/bg/standing-by-detector.test.ts	Adds Bun tests for the slice-1 no-op behavior and once-mode loop behavior.
tools/bg/README.md	Documents background-services directory, current/planned services, composition points, and how to run.

Comments suppressed due to low confidence (1)

tools/bg/standing-by-detector.ts:78

• parseArgs() parses --poll-min/--idle-min with Number(...) but never validates the value. If the next token is missing or another flag (e.g. "--poll-min --once"), Number() becomes NaN and the sleep becomes 0ms, creating a tight infinite loop and log spam. Suggest: require an argument, reject non-finite / non-positive values (and ideally non-integers), and surface a usage error/exit code.

    else if (arg === "--poll-min" && i + 1 < argv.length) {
      config.pollIntervalMin = Number(argv[++i]);
    } else if (arg === "--idle-min" && i + 1 < argv.length) {
      config.idleThresholdMin = Number(argv[++i]);
    }