Agent credential bootstrap: what to review

Field	Value
Branch	feat/admin-and-merchant-portals, draft PR #976: feat(admin): portal navigation, financials and monitoring, plus the agent-process work behind them, not merged
Project	README.md
Issue	#955: feat(tooling): agent credential bootstrap, two more per-machine secret files plus PATH-robust gcloud
Servers you need	None. There is nothing to click. Two CLI commands are the whole review
Local origins	Not applicable
Test plan	docs/engineering/testing/runs/agent-credential-bootstrap/README.md, with real captured output

Is there anything to look at?

Two commands, and they are the review.

./lantern doctor

• It now reports on both new credential files: missing, wrong permissions (want 0600), present but missing specific keys, or present and complete, each with the exact fix command.
• It stays severity warning, never a gate. A fresh clone with neither file still exits 0, because a newcomer must never be told they are blocked on credentials.

ls -l ~/.lantern-agent-probe.env ~/.lantern-test-accounts.env

• Both should exist at mode 0600. They were created for real on this machine, all 24 secrets fetched with zero failures.
• Never print their contents. The verification checked presence and length only.

What changed here?

Two more per-machine credential files come from Secret Manager instead of staying manually assembled.

• ~/.lantern-agent-probe.env (Agent Probe admin credentials) and ~/.lantern-test-accounts.env (app and merchant test accounts). Both are read directly by e2e and browser-test tooling rather than through process.env, which is why they need to be files.
• Which keys go where lives in one shared list, tooling/shared/credential-files.cjs, so the bootstrap script and lantern doctor can never drift apart on it.
• Practical consequence for the rest of this branch: the browser checks that were previously blocked on missing local credentials are now runnable. That is what unblocked the live passes on the venues, ad network and merchant projects.

gcloud stopped being a PATH gamble.

• A non-interactive agent shell never sources the Cloud SDK's PATH line in ~/.bashrc: it lives after the interactive-shell guard's early return.
• A session hit exactly this and came within one step of telling you that you needed to re-authenticate when you already were.
• Resolved to an absolute path via tooling/shared/gcloud.mjs. Your shell profile was not edited, which was your stated preference.

The concurrency question was answered by running it, not by reasoning.

• Six concurrent Node processes racing on one synthetic target file, using the exact pid-suffixed-tmp-plus-atomic-rename mechanism the real writer uses: one clean uncorrupted result, zero leftover tmp files.

What is deliberately NOT done?

mergeIntoEnvFile, the pre-existing .env.local writer, still uses a non-pid-suffixed tmp path.

• Two concurrent env:bootstrap runs could in principle interleave on that one write: the same race class this project's own new writer was built to avoid.
• Not touched: pre-existing, untouched-by-incident behaviour outside the three pieces asked for. The fix is a two-line change if picked up later.

Several other scripts still shell out to bare gcloud.

• onboard-grant.mjs, set-admin-role.mjs, authSetup.js, assorted deploy:dev scripts and a handful of .sh setup scripts.
• Only bootstrap-env.mjs and lantern doctor were switched, because those are the two an agent session runs non-interactively. The others are human-run, interactive-shell tools where PATH already resolves.

An ad hoc gcloud typed into an agent shell still needs its full path.

• Extending ~/.bashrc unconditionally would cover it. Editing your shell profile was explicitly out of scope without your word, so it is a recommendation, not done.

What open findings touch this project?

Cross-referenced from ../merchant-and-venue-dashboards/branch-review-0828.md.

One catch spans both statSync and readFileSync. tooling/scripts/lantern.mjs:208

• So an existing but unreadable credential file is reported as missing, with a fix suggestion that cannot fix a permissions problem.
• Open, low priority, not fixed. If lantern doctor tells you a file is missing that you can see on disk, this is why.

bootstrap-env.mjs was NOT reached by the review.

• The reviewer named it explicitly as unreviewed. Treat it as unread rather than as passed.

What issue does each piece close?

Piece	Issue	State
Both credential files, the shared key list, and PATH-robust gcloud	#955: feat(tooling): agent credential bootstrap, two more per-machine secret files plus PATH-robust gcloud	Built, live-verified, pushed
The doctor-green finish-line hook, adjacent and unbuilt	#858: feat(onboarding): finish-line hook, doctor-green prints the day-one path	Open, not overlapping