feat: AIDLC_DISABLE_USAGE_TRACKING kill switch for Claude usage tracking (2.5.53)

[apackeer]

What

Adds a kill switch for the Claude Code token-usage and cost tracking that shipped in 2.5.40 (#673). Local tracking stays on by default; set AIDLC_DISABLE_USAGE_TRACKING=1 to turn all of it off.

Why

2.5.40 shipped the usage ledger, the statusline ↑in ↓out $cost segment, and the completion-event cost rollups with no way to turn them off short of hand-editing the installed settings.json. Every other behavior-bearing hook already has an AIDLC_DISABLE_* escape hatch (reviewer-scope, review-freeze); this brings the usage producer in line.

Default-on was kept deliberately: cost history cannot be backfilled after the fact, so an install that wants it later should not have silently missed it. The flag is for installs that do not want a cost readout on screen or a usage ledger on disk at all.

Behavior

With AIDLC_DISABLE_USAGE_TRACKING=1:

• The fold hook exits before reading stdin (it fires around every tool call, so the gate is first); the Stop-hook flush and transcript-pointer writes are no-ops through the same seam.
• The statusline renders no cost segment.
• STAGE_COMPLETED / WORKFLOW_COMPLETED add no rollup fields.
• An already-recorded ledger is left on disk untouched: unsetting the flag resumes history rather than restarting it. Delete aidlc/.aidlc-sessions/usage-ledger.json manually if the history should go too.

Unset or any value other than the exact string 1 leaves tracking on, matching the AIDLC_DISABLE_* convention. Metrics emission is unchanged (still separately opt-in via AIDLC_METRICS_ENDPOINT).

Design

One predicate (usageTrackingDisabled() in core/tools/aidlc-usage.ts) gates both ends of the seam: the producer (foldTranscriptIntoLedger, writeCurrentTranscriptPath, plus an early exit in the fold hook itself) and the consumers (stageUsageAuditFields, workflowUsageAuditFields, sessionUsageAggregate). Consumers are gated too so a pre-existing ledger goes quiet everywhere with one flag. Read at call time, never cached.

Versioning

Re-slotted to 2.5.53; based on v2 @ e135e8e.

Testing

• New t271-usage-tracking-kill-switch (4 tests): exact-"1" flag parse, silent producer (no ledger file, no pointers), quiet consumers over a recorded ledger, and ledger survival + history resume across a toggle.
• Runtime check: costSegment renders ↑10 ↓100 $0.00 with the flag unset, "" with it set, ledger file intact.
• smoke+unit+integration: 298 files, 2 reds in the tier run, both live-SDK tests off this branch's surface. t188 human-presence re-ran green alone (74/74). t-journey-workspace is latency-bound (its reverse-engineering drive has a 600s budget that green runs consume ~530-830s of): it re-ran green on this branch, and a paired simultaneous branch-vs-base run passed on both, so the earlier reds were drive-budget flakes, not a branch effect. With the flag unset the only code added to any hot path is one env-var string comparison.
• package.ts --check, gen-coverage-registry --check, typecheck, biome all clean.

[leandrodamascena]

Approved from my review. The kill switch consistently gates ledger writes, transcript pointers, statusline reads, and completion rollups while preserving existing history. Focused tests and repository checks pass.

Non-blocking: update the PR body’s stale 2.5.42 reference to 2.5.53.