fix(cli): exit cleanly on non-interactive SSO auth failure (EPMCDME-14148)

[SleepySML]

Summary

EPMCDME-14148 reports that a non-interactive SSO failure hangs on a re-auth prompt. Reproduction showed the hang is already fixed on main by 5b2de4b7 (#471). What is still broken is the quality of the failure: the CLI exits 1 by letting a ConfigurationError escape to Node's default handler — printing a raw stack trace — and the actionable remediation is discarded one frame before it reaches the user.

# before — exit 1, but:
✖ No valid SSO credentials found
ConfigurationError: Authentication expired. Please re-authenticate.
    at promptReauthentication (.../dist/utils/auth.js:65:11)
    at getAuthenticatedClient (.../dist/utils/auth.js:40:36)
Node.js v24.19.0

# after — exit 1
❌ SSO authentication required. Please run "codemie setup" with SSO provider first.

Two independent defects, both required — fixing either alone is insufficient, since handleSdkError already renders ConfigurationError cleanly:

1. getSdkClient() acquired auth outside every action's try, so the throw bypassed handleSdkError. All ~50 sdk actions across 8 files share that one gate, so it is fixed once there rather than at 50 call sites — the same shared-gate approach fix(providers): skip interactive re-auth prompt in non-interactive environments #471 used.
2. promptReauthentication's generic 'Authentication expired' throw shadowed the upstream error naming codemie setup. The original is now preserved.

Changes

• sdk/utils/cli-utils.ts — route auth acquisition through the existing handleSdkError sink.
• utils/auth.ts — preserve the actionable upstream error. promptReauthentication itself is untouched, so its Promise<boolean> contract and the assistants/chat consumer cannot regress — and its existing tests still pass unmodified.
• providers/core/auth-validation.ts — diagnostics to stderr, keeping piped stdout and --json output clean.
• utils/interactive.ts + utils/sdk-client.ts — suppress the ora spinner based on the output stream. ora writes to stderr, so a new isNonInteractiveOutput() (!process.stderr.isTTY) gates it; the existing stdin-based predicate is left alone because prompting genuinely depends on stdin. Gating the spinner on stdin was wrong in both directions — codemie … > run.log 2>&1 kept the spinner and filled the log with escapes, while codemie … < input.json dropped it for a user watching the terminal.
• utils/process-guards.ts (new) + all 12 bin/ entrypoints — last-line-of-defence net for async rejections escaping a command action (program.parse() is sync, so these reach neither the action's try nor the import().catch()). Installed per entrypoint, not from the AgentCLI constructor, so constructing an AgentCLI never mutates global process state.
• docs/AUTHENTICATION.md — shows the message the CLI actually emits, and documents a real boundary: prompt detection reads stdin only, so a pty-allocating runner (docker run -t, some Jenkins/GitLab configs) can still reach the prompt.
• Tests — sdk/** had zero tests across 22 files; adds the first. Plus new sdk-client and process-guards suites, and an end-to-end regression test.

Impact

User-visible behaviour changes worth reviewer attention:

• The auth diagnostic moves stdout → stderr. Verified no consumer parses it from stdout.
• Fatal errors now print one formatted line instead of a stack trace; the full stack goes to the log file.
• The spinner now follows the output stream: suppressed under > log 2>&1, kept when stdin is redirected but the terminal is still attached.

Acceptance criteria — 4 / 4 verified

Re-run end-to-end through bin/codemie.js under the ticket's stated preconditions. Full record in acceptance-verification.md.

AC	Status	Evidence
Non-TTY stdin skips interactive prompt	✅	No prompt, completes in 964 ms. Control: same command with a TTY does prompt (604 ms) — so the guard is demonstrably what skips it
CLI exits non-zero with clear remediation	✅	exit 1; names codemie setup; no stack trace, no ConfigurationError:, no Node banner; stdout clean
--non-interactive / --ci supported or documented	✅	Satisfied through "documented". No flag — EPMCDME-13953 recorded it out of scope. This MR additionally documents the pty-CI boundary the page previously glossed over
Killing during prompt → no readline crash	✅	12/12 runs reached the prompt (4 signal modes × 3 delays); zero ERR_USE_AFTER_CLOSE

Two notes on how that verification was reached, since both bear on how much to trust it:

The environment had to be cleaned first. These probes run from a shell CodeMie itself launched, which exports CODEMIE_PROVIDER=anthropic-subscription and CODEMIE_PROFILE_CONFIG. ConfigLoader gives process.env precedence over both config files, so early runs resolved to the wrong provider — one with no validateAuth and no promptForReauth, which terminated before any prompt could appear. CODEMIE_HOME isolates config files, not the env vars that outrank them. That single fact produced four claims that had to be retracted, all recorded in ac4-investigation.md, including an earlier draft of this PR asserting the prompt was unreachable from codemie sdk ….

AC1's control is the load-bearing part. Without demonstrating that a TTY does produce the prompt, AC1 passes trivially whenever anything else ends the run early — which is exactly how the earlier investigation fooled itself.

The ticket hedges AC4 with "can crash", so that one is a negative result on this build and platform (macOS, Node v24.19.0), not proof the failure is impossible everywhere.

One incidental finding, out of scope, worth its own ticket: Ctrl-C at the prompt exits with code 0. A script checking $? after a user interrupts would conclude the command succeeded.

Verification

Rebased onto d7097a2a and all gates re-run against the rebased tree: license · lint --max-warnings=0 · typecheck · build · unit 3946/3946 (267 files) · commitlint — all pass. All 12 entrypoints start.

Note: d7097a2a removed the test:unit / test:integration package scripts, so the commands above are npx vitest run --project unit|cli.

Spinner behaviour verified empirically in both directions: with stderr redirected the run emits zero cursor-control sequences; under a real pty the spinner still renders.

Two gates are owed to CI, stated plainly rather than rounded up:

• Integration: partial. doctor.test.ts and list.test.ts hang in this environment. Verified pre-existing — doctor hangs identically against origin/main's entrypoint. The four files that do complete — including the new regression suite and the three exercising bin/codemie.js — all pass.
• Secrets: SKIPPED, not passed. It self-skipped with No staged changes to scan (it reads the staged diff; the tree is clean). The pre-commit hook did run gitleaks on every commit. Note it is hook-only — npm run ci does not include it.

Reviewed in two rounds. The first raised 5 blocking findings; the check round found 2 further defects introduced by that first fix-up (guards leaking handlers into test workers; a timeout that stopped CI wedging but left a hang passing every assertion). Both were fixed and independently re-verified — including a counterfactual proving the hang test now fails where it previously passed silently.

Checklist

• Self-reviewed
• Manual testing performed
• Documentation updated
• No breaking changes (or clearly documented) — the stdout→stderr move is documented above

🤖 Generated with Claude Code