error-tracking flow can make a Node app's start script exit when .env is missing, and the report says uploads are wired when CI wiring was skipped #1329

Problem

The error-tracking flow can leave a plain Node app unable to start in production.

For a Node backend, init.md offers two ways to load .env. One is to install dotenv. The other is to add --env-file=.env to the start and dev scripts. configure.md then tells the agent to make the run script load the env file with "the runtime's own flag". Both files present the options as equal, but they fail in different ways.

node --env-file=.env exits with code 9 before any app code runs when .env is missing. .env is gitignored, and the wizard adds it to .gitignore when it writes keys. So the file is usually absent where the app is deployed. A host that injects POSTHOG_API_KEY and POSTHOG_HOST as real environment variables still gets a process that stops at boot with node: .env: not found. dotenv does not fail this way. config() does nothing when the file is missing, and the injected variables still apply.

No task in the run catches this. No task starts the app without .env, and the report tells the user that production "runs with npm start".

The agent picks one of the two options on each run. On the same fixture, one run used dotenv and another used --env-file.

The second problem is smaller and shows up in the same run's report. The report says "Source-map upload is wired into the production build" and "Every production build run through this command uploads its source maps". But the run skipped two tasks: "Wire source-map uploads" (wire-ci), because the repo has no CI, and "Collect upload credentials". So no build uploads yet. npm run build exits 1 until POSTHOG_CLI_API_KEY and POSTHOG_CLI_PROJECT_ID are set. The report's "What you still need to do" section does list the key and the missing CI, so the facts are on the page. The later sentence contradicts them. report.md has only two branches, wired or skipped. It has no branch for a build that is wired while credentials or CI are still missing.

The review of #377, the first version of this flow, raised both points. #377 was closed, and #393 merged the same text.

Evidence

The sweep ran wizard error-tracking in the real TUI on wizard-workbench apps/basic-integration/javascript-node/express-todo. The wizard was at d938a43 (#1307). Wizard main runs the same context-mill flow (src/lib/programs/error-tracking/index.ts:171, agentFlow: 'error-tracking'), and the flow text comes from context-mill releases at run time. So this is not specific to the refactor stack.

Before the run, the fixture had "start": "node index.js", and .gitignore already listed .env.

After the run, the package.json scripts were:

"build": "esbuild index.js --bundle --platform=node --format=cjs --sourcemap=external --sources-content=true --outfile=dist/index.js && posthog-cli --dotenv-file .env sourcemap process --directory ./dist --release-name express-todo",
"start": "node --env-file=.env dist/index.js",
"dev": "node --env-file=.env --watch index.js"

I tested a copy of the result on Node 22.22.0. I removed .env and set the runtime variables directly, the way a host would:

$ NODE_ENV=production POSTHOG_API_KEY=<placeholder> POSTHOG_HOST=https://us.i.posthog.com npm start
> node --env-file=.env dist/index.js
node: .env: not found
(exit 9)

In the same directory, node --env-file-if-exists=.env prints .env not found. Continuing without it. and runs the script.

The Release A run (wizard 200961f, #1303) on the same fixture used require('dotenv').config() with "start": "node dist/index.js". That start command works without .env.

Task statuses in the d938a43 run:

• Install PostHog SDK: completed
• Initialize PostHog: completed
• Collect upload credentials: skipped
• Capture exceptions: completed
• Configure source-map uploads: completed
• Wire source-map uploads: skipped
• Report setup: completed
• Offer end-to-end test: completed

The TUI showed these skips only as "(2 skipped as not required)". That wizard-side count is tracked with the blocked-step outros on #951; this issue covers only the flow text. The run's .env holds no POSTHOG_CLI_* names. On the copy, npm run build bundles, and then posthog-cli stops with "Couldn't find POSTHOG_CLI_API_KEY and POSTHOG_CLI_PROJECT_ID in process env" and exit code 1.

The lines on context-mill main (dc2898b):

• context/agents/error-tracking/init.md:61-65 offers dotenv or "add --env-file=.env to the start and dev scripts, when the project is on Node 20.6+". The only condition is the Node version, not whether .env exists where the app runs.
• context/agents/error-tracking/configure.md:59-61 says: "make the run script provide exactly those — export the env file ahead of the command, pass the runtime's own flag for it".
• context/agents/error-tracking/report.md:41-45 says: "When source-map upload was wired: ... and that every production build now uploads." The only other branch is "When it was skipped".

Findings from the #377 review:

• init.md:65, must fix, "The production start command can require a missing .env file": feat(agents): add the error-tracking orchestrator flow context-mill#377 (comment)
• report.md:39, consider, "The report can claim uploads before follow-ups are complete": feat(agents): add the error-tracking orchestrator flow context-mill#377 (comment)

Suggested fix

1. init.md:61-65: never add a hard --env-file=.env to start. For the production path, prefer dotenv. If the project does not want a new dependency, use --env-file-if-exists=.env, but only when the project pins Node 22.9 or later (engines, .nvmrc, .node-version, or a Dockerfile base image). A hard --env-file=.env is fine on dev, where .env exists.
2. configure.md:59-61: apply the same rule to the run script that this step writes. The loader or flag must work when the file is missing, because production supplies the variables as real environment variables.
3. report.md:41-45: add a third branch. When the build was wired but the credentials handoff or wire-ci reports a skip, say the build is set up to upload. Also say that uploads start, and npm run build succeeds, only once the POSTHOG_CLI_* values are present where the build runs. Say "every production build uploads" only when the credentials were written and wire-ci completed.
4. Add a contract test in scripts/lib/tests/, like error-tracking-upload-source-maps.test.js, that fails if init.md or configure.md tells the agent to put a hard --env-file=.env on start.