Repository navigation
feat: stable error catalog with machine-readable error codes - #1148
Merged
Merged
Conversation
Introduces PHW_<GROUP>_<NAME> error codes (src/lib/errors/codes.ts), per-code metadata with retry advice (catalog.ts), classifiers for auth 401s, detectError kinds, skill-install failures, and AgentErrorType, plus the machine-readable phw-error stderr line emitter. Unit tests enforce catalog completeness and code uniqueness.
WizardError carries an optional code; wizardAbort({ code, detail })
stamps OutroData.errorCode/errorDetail, tags analytics with error_code,
and emits the phw-error stderr line when running under LoggingUI/
HeadlessUI. TaskStreamError carries code/detail so the backend sees
the failure class on the terminal error push.
Wires catalog codes at every terminal failure site: non-interactive validation, local-services and outage checks, detect prerequisites (both ciPreRun and onReady paths), skill install, the full agent error taxonomy (linear + orchestrator), auth 401 classification, CI install signup, doctor, skill registry, CLI guards, and interactive fatal catches. Also closes two headless gaps found while mapping exits: an unsupported framework version now aborts non-interactive runs instead of being silently dropped, and unfixable Claude settings conflicts now fail closed instead of continuing into the redirect. Fixes three pre-existing type errors in orchestrator-runner (docsUrl lookup, missing requestRemark task inputs).
fercgomes
requested review from
TueHaulund,
arnohillen,
fasyy612 and
ksvat
and removed request for
a team
August 26, 2026 18:26
🧙 Wizard CIRun the Wizard CI and test your changes against wizard-workbench example apps by replying with a GitHub comment using one of the following commands: Test all apps:
Test all apps in a directory:
Test an individual app:
Show more apps
Results will be posted here when complete. |
32 of 51 tasks
An abort case that matches a known [ABORT] reason now carries its own errorCode, so dynamic precondition failures classify correctly instead of all surfacing as PHW_AGENT_ABORT. Wired: audit / web-analytics-doctor / source-maps no-SDK cases (PHW_DETECT_NO_POSTHOG_SDK), source-maps bare React Native + mcp-analytics unsupported language (PHW_DETECT_UNSUPPORTED_PLATFORM), web-analytics-doctor insufficient permissions (PHW_AUTH_MISSING_SCOPE), self-driving interactive mode (PHW_CLI_INTERACTIVE_REQUIRED). Fixes the headless audit run reporting PHW_AGENT_ABORT for a repo with no PostHog SDK installed.
![veria-ai[bot]](https://avatars.githubusercontent.com/in/1723776?s=60&v=4){kind=small}
PR overviewAll previously flagged issues have been addressed. No open security concerns remain on this pull request. Security reviewNo open security issues remain on this pull request. Fixed/addressed: 1 · PR risk: 0/10 |
looks great
edwinyjlim
reviewed
Aug 26, 2026
Remote channels (task-stream session row, phw-error stderr line) now drop detail fields not on the allowlist (reason, detected, platform), so detect failures no longer ship the absolute install path to team-visible telemetry. Local surfaces (TUI error screen, debug log) keep the full detail. Addresses the local-path-disclosure review comment on PR #1148.
PhwErrorLine.code is now the closed ErrorCode union instead of a bare string, so every emit site is compile-time checked against the catalog. The type import in emit.ts is erased at compile time, keeping the module runtime-dependency-free for the bin.ts Node preflight. bin.ts and ci-install's failCI now pass catalog constants instead of raw strings. Addresses the typing review comment on PR #1148.
emitPhwError -> emitWizardError, formatPhwErrorLine -> formatWizardErrorLine, PhwErrorLine -> WizardErrorLine, matching the repo's Wizard* vocabulary. The PHW namespace stays on the wire contract only (PHW_* codes, phw-error: prefix, PHW_ERROR_PREFIX constant). No behavior change. Addresses the naming review comment on PR #1148.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The wizard runs headless inside cloud-worker sandboxes. When a run dies, the backend and web UI cannot tell why — every failure surfaces as a generic message, because thrown errors are not propagated with any stable classification. Hosts have to parse human-readable text to guess the failure class.
Changes
A stable, append-only error catalog (
PHW_<GROUP>_<NAME>) covering every terminal failure path, propagated through three channels:src/lib/errors/— 40 codes (codes.ts), per-code metadata with retry advice (catalog.ts), classifiers (auth 401 → stored-login/settings/key-type/scope/region/invalid; detectError kinds; skill-install failures; AgentErrorType), and thephw-error:stderr line emitter.wizardAbort({ code, detail })resolves the code (explicit param →WizardError.code), stampsOutroData.errorCode/errorDetail, tags analytics witherror_code, and — for non-interactive hosts — prints one machine-readable line to stderr just before exit:phw-error:line on stderr.TaskStreamErrornow carriescode/detail, so the PostHog backend receives the failure class on the terminalRunPhase.Errorpush.Also closes two headless gaps found while mapping exits:
setUnsupportedVersionstub dropped it; now aborts withPHW_DETECT_UNSUPPORTED_VERSION.PHW_SETTINGS_UNFIXABLE_CONFLICT.Incidentally fixes three pre-existing type errors in
orchestrator-runner.ts(docsUrl lookup, missingrequestRemarktask inputs).Exit codes stay 1/130 — the code rides structured channels, not the exit byte. Full reference:
docs/error-catalog.md(catalog table, stability contract, propagation spec, sandbox integration recipe).Test plan
src/lib/errors/__tests__/codes.test.ts— 6 tests).pnpm build✓, 2020/2021 tests pass. The single failure (skill-cli.test.tsyargs locale message) is pre-existing onmain— verified by stashing the diff and re-running.tsc --noEmit: zero new errors vsmain; net −3.