token-report without --db reads one directory above the ledger: the default is missing the bot/ segment #2778

Implementation: FlyBot (ours) — PR follows within 24h. Do not pick up without a pickup-ok comment on this issue.

Written-by: FlyBot Lead
Claimed-by: FlyBot Lead
Claim-Id: 3cac7fccd5024b2cab40de36341e16a3
Branch: dev/3-token-report-default-db
Base: 7b7f6c4 (read on the live main when PR #2781 opened)
At: 2026-11-10T05:05:27Z

Implementation: FlyBot (ours) — PR follows within 24h. Do not pick up without a pickup-ok comment.
PR is opened within 24h; merge waits behind the current review queue.

Category: defect — a documented default of a shipped tool points one directory above the ledger it is meant to read (core/dev/token-report.mjs, plus docs/subsystems/ds-bot-core.md:104).

Risk tier: T2. core/dev/** is not listed in any rule of .github/agent/risk-rules.json, so unknownPathTier: T2 applies; docs/subsystems/ds-bot-core.md alone would be T0 but the change takes the highest tier. The PR needs the T2 PASS, not merely green checks.

What happens

core/index.js:94 hands every host module the team folder:

const home = config.home ?? join(dshHome, 'bot')

core/src/host/usage.js:327 writes the ledger there, and docs/subsystems/core-host.md:53 says so ($DSH_HOME/bot/usage.sqlite).

core/dev/token-report.mjs:349 reads a different place:

const dbPath = flags.db ?? join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'usage.sqlite')

and its own header (:8) says --db defaults to $DSH_HOME/usage.sqlite (see src/host/usage.js) — the module it does not follow. docs/subsystems/ds-bot-core.md:104 repeats the wrong default. CHANGELOG.md:926 and the two dated reports repeat it as history and are not changed.

Reproduction (measured on f2ef4dfa)

$ ls -l /home/xuke/.dsh/bot/usage.sqlite*      # 12,435,456 bytes, 2026-11-10 02:27 (+ -wal, -shm)
$ ls -l /home/xuke/.dsh/usage.sqlite
ls: cannot access '/home/xuke/.dsh/usage.sqlite': No such file or directory
$ node core/dev/token-report.mjs
token-report: no ledger at /home/xuke/.dsh/usage.sqlite (pass --db <path>)
exit=1

A temp home proves the file itself is fine and only the default is wrong (probe builds the v3 ledger at <tmp>/bot/usage.sqlite): with no --db it exits 1 naming <tmp>/usage.sqlite; with --db <that ledger> it exits 0 and prints the JSON whose db field is the ledger.

Expected

With no --db, the tool reads $DSH_HOME/bot/usage.sqlite (the team folder createRuntime hands the host modules; an install with config.home moves it, and the doc sentence says so). --db still wins. The missing-file sentence no ledger at <path> (pass --db <path>) stays word for word.

Change scope (XS)

• core/dev/token-report.mjs:349 — default gains the bot segment; :8-9 header comment names $DSH_HOME/bot/usage.sqlite and core/index.js:94.
• docs/subsystems/ds-bot-core.md:104 — same sentence corrected; CHANGELOG.md:926 and the dated reports stay as records.
• core/test/token-report.test.js — one new test plus a guard that --db still wins.
• No patch mirroring: core/dev/** and core/test/token-report.test.js are not in patches/ds-bot/topics.json, so no ds-bot-patches generate/check step.

Acceptance (red first)

ready/p666-red-first.test.js, meant to live at core/test/:

1. Ledger built at <tmp>/bot/usage.sqlite exactly as usage.js creates it (v3 schema), DSH_HOME=<tmp>, --json, no --db → exit 0, report.db is that path, one day row. On f2ef4dfa: red (expected 0, actual 1).
2. --db <path> wins even when DSH_HOME points elsewhere → exit 0. Green on base (guard).

After the sketch (adding 'bot' and the comment): 2/2 green, and the existing core/test/token-report.test.js stays 5/5 green. The sketch was reverted; the tree was left clean. Note the base has since moved to 79180c2b (#2769 and #2772 merged); re-run both readings on the current base before opening the PR (main has since reached 7adb4a57, #2753; the readings below are the f2ef4dfa ones and are superseded).

Dedupe (2026-11-10, two steps)

1. Local ledger and notes: token-report|token report → 0 hits.
2. GitHub: repo:ThinkFlowLab/FlyBot token-report → #1144 (closed, records the 2026-10-25 report) and #799 (closed, the tool's origin). No open issue on this face.

Written-by: FlyBot Lead
Bot: FlyBot Product