fix(usage): persist host fingerprints across container recreates

[maria-rcks]

Container recreates change os.hostname(), making the same provider history look like a different usage source. Save the first hostname in <T3 home>/usage-host-id, publish it atomically for concurrent startup, and reuse it across restarts. T3CODE_HOST_ID provides a trimmed explicit override without rewriting the saved identity; unavailable persistence falls back to the current hostname.

The maintainer's triage and suggested fix explicitly recommends persisting the first-seen hostname and/or honoring T3CODE_HOST_ID, with the current hostname as fallback. This PR follows that scoped direction.

Keeping the original hostname preserves deduplication between sibling worktree servers instead of substituting their distinct environment IDs. This adapts the persistence approach from #13984 and the override from #12299. Environment display labels remain a separate issue from source fingerprints.

Verification:

• Blacksmith: 70 tests passed across UsageService, usageScanCache, and usageMerge. Existing-file regressions exercise hostname changes, override precedence/removal/blank values, shared-worktree totals, distinct hosts, concurrent initialization, and unavailable persistence through real filesystem/transcript scans.
• Blacksmith: server typecheck and scoped formatting passed. Scoped lint has zero errors and one pre-existing unused layerTest warning.
• The restart regression fails before persistence when hostnames are injected through the existing OS reference. Actual Docker recreation and the live provider/client path are unverified; shared-runtime evidence and two final exact-head reviews are pending with the parent task.

Closes #11849.

Model: gpt-6.1-sol (xhigh). Harness: Codex in T3 Code.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Advanced
• Run ID: 28c19955-a6f6-43e1-9494-16cae751908a

📥 Commits

Reviewing files that changed from the base of the PR and between 17c0878 and 56e1d0a.

📒 Files selected for processing (3)

• apps/server/src/usage/UsageService.test.ts
• apps/server/src/usage/UsageService.ts
• docs/user/usage.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

The server now resolves a stable host ID for usage fingerprints. It uses T3CODE_HOST_ID first, then a saved ID in T3 home, then the hostname. The documentation and tests describe identity persistence, overrides, concurrent initialization, and fallback behavior.

Changes

Usage Host Identity

Layer / File(s)	Summary
Resolve and use the usage host ID apps/server/src/usage/UsageService.ts	UsageService.make selects a host ID from the trimmed T3CODE_HOST_ID, a saved ID, or the hostname. When no ID is configured or saved, it attempts to persist the hostname and uses a concurrent initializer’s saved value when available. Usage fingerprints use the resolved ID.
Validate and document host identity apps/server/src/usage/UsageService.test.ts, docs/user/usage.md	Tests cover host ID selection, shared-worktree deduplication, concurrent initialization, and persistence failure. Documentation describes the saved identity and T3CODE_HOST_ID override.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Low

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to 56e1d

Usage reporting continues when identity persistence is unavailable. No actionable issue remains from this review; the change is mergeable after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 56e1d

The change is limited to usage attribution and deduplication; no new authorization capability was demonstrated. Atomic publication and explicit fallback constrain failures, but actual container recreation and interruption recovery remain unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — Changing the resolved host label can affect local usage sources published by that service and their contributions when connected environments merge summaries. The inspected flow does not use this label to select credentials, grant privileges, or authorize access.

Security Findings and Attack Paths

• inferred — Influencing this identity requires control of the server process environment, hostname, or persisted identity file. A changed label can alter usage attribution, but no remote request-to-identity mutation or new authorization bypass was established in the inspected change.

Trust Boundaries and Controls

• observed — The persistence destination is a fixed filename under configured T3 home, not a path derived from the override. The override returns before filesystem publication, while publication does not replace an existing identity file.

Resilience and Maintainability Implications

• inferred — Before publication, interruption leaves no published candidate; after successful publication, later initialization can reuse the completed value. Scoped temporary-file ownership supports cleanup, but direct interruption, abrupt-process termination, and storage-durability behavior were not verified. When persistence is unavailable, usage continues without guaranteeing identity stability across restarts.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: persisting usage host identity across container recreates.
Description check	✅ Passed	The description covers the problem, the change, maintainer-approved scope, and focused verification results. It also states the unverified checks and includes the model and harness. Although it does n…
Linked Issues check	✅ Passed	#11849 requires one usage identity across container recreates when T3 home persists. UsageService.make reads and saves the first hostname in config.baseDir/usage-host-id, then reuses that value. I…
Out of Scope Changes check	✅ Passed	The reported changes are limited to UsageService.ts, its tests, and docs/user/usage.md. The implementation stabilizes the host fingerprint for #11849. The tests verify that behavior, and the docum…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Approved at 56e1d0a

Macroscope's review found this PR approvable — This is a contained usage bug fix that stabilizes source identity across container recreates, with explicit override and failure fallback behavior covered by tests. It adds only a small advisory identity file and documentation, without schema, deployment, security, or billing changes.

^{You can add or adjust custom eligibility rules. Learn more.}

[maria-rcks]

Note

Written by gpt-6.1-sol on behalf of Maria

The default identity change follows the maintainer's accepted triage and suggested fix: "Persist the first-seen hostname ... on the T3 volume and reuse it after recreate" and/or honor T3CODE_HOST_ID, keeping the hostname as fallback. The PR body now links that direction directly.

The persisted value starts as the existing hostname, so initial non-container and sibling-worktree fingerprints retain the same host/path/volume key. The changed behavior stabilizes that key when the disposable hostname changes. Existing-file regressions verify unchanged shared-history totals, distinct hosts, restart/override removal, concurrent initialization, and unavailable persistence; all 70 scoped Blacksmith tests and exact-head CI passed at 2a9a7a44d3e4c793f4bafa42414eb86f26a021e9.

Actual Docker recreation and the live provider/client path remain unverified and are disclosed in the body. This evidence does not establish merge readiness; that runtime pass and two independent final reviews remain pending with the parent task.