fix: add text remediation hints for ACP session errors

[SJeffZhang]

Summary

This is a small first pass for #176.

It keeps the JSON / machine-readable error contract unchanged and adds additive remediation hints only to text-mode error output.

Initial text-mode coverage in this pass:

• AUTH_REQUIRED
• NO_SESSION
• common ACP runtime/session-control failures such as session/load, session/set_mode, session/set_model, and session/set_config_option

Why

acpx already normalizes these failures into stable code, detailCode, origin, and raw acp metadata, but text mode usually stopped at the raw error message. That left users without a clear next step even when the client already had enough information to point them in the right direction.

User Impact

Text-mode CLI failures now include short next-step hints in a few high-value cases, for example:

• add the missing auth credential under auth.<method>
• start a fresh session with acpx <agent> sessions new
• rerun with --verbose to capture ACP method/error details

JSON output and machine-readable error fields stay unchanged.

Root Cause

The existing text formatter and top-level stderr path emitted normalized error messages, but they did not translate the existing normalized metadata into actionable remediation guidance for human readers.

Validation

Targeted local validation:

• corepack pnpm run build:test
• node --test --test-name-pattern 'normalizeOutputError maps ACP resource not found errors to NO_SESSION|normalizeOutputError maps AuthPolicyError to AUTH_REQUIRED detail|normalizeOutputError infers AUTH_REQUIRED detail from ACP payload|sessions new --resume-session fails when agent does not support session/load|sessions new --resume-session surfaces not-found loadSession errors without fallback|set-mode surfaces actionable guidance when agent rejects session/set_mode params|prompt exits with NO_SESSION when no session exists \(no auto-create\)' dist-test/test/error-normalization.test.js dist-test/test/cli.test.js
• local node --input-type=module -e ... assertions for generated remediation hints
• corepack pnpm run typecheck
• corepack pnpm run format:check
• oxlint --type-aware src
• ./node_modules/.bin/tsx scripts/lint-persisted-key-casing.ts
• ./node_modules/.bin/tsx scripts/lint-flow-schema-terms.ts

Manual text-mode end-to-end stderr checks:

• AUTH_REQUIRED
• failed session/load / NO_SESSION
• session/set_mode invalid params

AI Assistance

AI-assisted with Codex. I reviewed the touched code paths and local validation results directly.

[steipete]

Landed via maintainer rewrite and rebase onto main.

• Gate: pnpm run check passed locally after rebase (format, typecheck, lint, build, viewer type/build, coverage: 540 tests)
• Targeted proof: added output regressions showing text mode prints remediation hints, JSON error payloads do not include hints, and missing-session / ACP method failures map to the intended next-step text
• Land commit: b03c475
• Source rewrite commit before rebase: SJeffZhang@ed56726

Thanks @SJeffZhang!