Skip to content

fix(portability): code every export/import refusal, and stop rendering 5xx boilerplate - #6066

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/portability-error-codes
Sep 23, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/portability-error-codes

Conversation

@leonlaiyc

@leonlaiyc leonlaiyc commented Aug 26, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

AGENTS.md states the rule directly: "Backend-owned strings have no catalog
path yet, so a new non-2xx JSON body MUST carry a machine-readable code
field."
error-code-baseline.json — the worklist that ratchets the existing
debt down — listed dashboard/handlers/portability.py with missing_code: 9.

The file already had the answer in it. Its 413 answers:

{"error": "archive too large (max 2048 MB)", "code": "import_archive_too_large"}

The other nine refusals across export, import and preview carried prose only.

Why it matters

Two different failures are indistinguishable to a client today. A 400 from
/api/portability/import is either a rejected mode or a rejected archive; a 500
from any of the three endpoints is opaque by design. And PortabilityTab
renders data.error || <localized fallback>, so the English produced in Python
wins over a catalog string that says the same thing in the reader's language —
in a dashboard translated into 12.

What changed (motivation → approach → change)

Backend. The nine refusals gain codes in the vocabulary already used here
and elsewhere in the tree: auth_required (the wire name from
handlers_cloud.py, on all three endpoints), file_field_required,
invalid_import_mode, import_archive_invalid, and one <operation>_failed
per handler — export_failed, import_failed, preview_failed. Every prose
string is unchanged.

The two kinds of 4xx are deliberately kept apart, and this is the decision
the rest of the PR follows from:

  • import_archive_invalid carries the archive validator's own finding —
    "manifest.json is missing". That prose is the value of the message.
  • The 5xx bodies carry boilerplate — "Export failed" — which is opaque on
    purpose, so the cause stays private.

Frontend. refusalText() inverts the preference for exactly one case: a
refusal that is both coded and 5xx. There the localized fallback wins,
because the server's string says strictly less than the fallback already says.
A coded 4xx keeps its detail. An uncoded refusal at any status keeps its
message — it may be from a proxy or an edge rather than these handlers, and
there the prose can be all there is.

That is one predicate on (code, status), not a hand-maintained list of codes
the frontend has to keep in sync with the backend.

The export path is deliberately not moved. Its fallback is
resp.statusText, not a catalog string, so there is nothing localized to
prefer. Giving it one means authoring new user-facing copy in 12 languages,
which is a different change from this contract.

The user-visible effect is two error messages in the Portability tab: where a
failed import or preview read Import failed / Preview failed in English, it
now reads the tab's own localized string.

Both banners also change shape, and that is a real visual delta rather than a
string swap.
Each moves off its ad-hoc <div className="text-danger"> onto the
shared ErrorNotice component (variant="inline"), so the icon becomes
AlertTriangle size={14} where it was AlertCircle size={12}, the icon-to-text
gap goes gap-1 -> gap-1.5, and the element gains role="alert" and a
data-testid. The success and progress lines are deliberately left on the old
<div> -- they are not errors and must not be dressed as one. No panel, layout
or theme token changed. The screenshots below show both banners in both trees, so
the icon and spacing change is visible rather than asserted.

Baseline

missing_code 1117 -> 1108 -- exactly the nine -- and the
dashboard/handlers/portability.py entry is gone. _compliant moves
2182 -> 2239, which is +57, not +9, and the asymmetry is worth stating:
missing_code is the number the gate ratchets and it moves by exactly nine,
while _compliant is a whole-tree count, so regenerating it also absorbs
compliant responses that landed on main after the committed baseline was last
refreshed.

(Read against this PR's own base, cc0c8214e. An earlier revision of this
section claimed missing_code 1262 -> 1253 and _compliant 1410 -> 1419 "exactly
+9". All four numbers were wrong -- they matched neither the committed file nor
its base -- and the _compliant delta was never ±9.)

Rebased onto current main cc0c8214e. The
baseline was regenerated from the live tree with the repo's own
python test/test_error_code_contract.py --update, never hand-merged: the
totals in this file are relative to this PR's base, so adding or reconciling
numbers across branches would be meaningless. Diffing the regenerated file
against main's shows exactly one changed entry --
dashboard/handlers/portability.py, removed -- and no other file added,
removed, or changed. missing_code, the number the gate enforces, moves by
exactly nine.

Tests

test/test_api_portability.py is new — the existing test_portability.py
covers the zip logic, and nothing exercised these handlers over HTTP. It drives
them through an aiohttp TestServer with real multipart uploads, so the auth
and file-part paths are the ones a client actually hits.

Test Locks in
test_every_endpoint_denies_anonymously_with_auth_required 401 → auth_required on all three endpoints
test_export_failure_is_coded_and_stays_opaque export_failed, prose still generic, private path still absent
test_an_unrecognized_import_mode_is_coded invalid_import_mode, four rejected modes
test_an_upload_without_the_file_part_is_coded file_field_required on both upload endpoints
test_a_rejected_archive_keeps_the_validator_detail import_archive_invalid alongside the validator's message — the case the frontend rule turns on
test_import_failure_is_coded / test_preview_failure_is_coded import_failed / preview_failed, cause still not leaked
test_every_refusal_carries_a_code per-file ratchet: no path may regress to prose-only

Red before: with only the handler change stashed, all 14 cases fail.
Green after: 14 pass.

website/src/pages/overview/PortabilityTab.test.tsx covers refusalText
directly — 4 cases, including the two negative controls that define the rule's
edges: a coded 4xx keeps its detail, and an uncoded 5xx keeps its message.

Other gates: test_portability.py and test_error_code_contract.py pass
alongside the new module (68 passed / 3 skipped). tsc -b and eslint clean;
flake8, isort, mypy clean; scripts/check_black_formatting.py passes on
the 5 changed files.

Coverage

The rebased head also tripped the Coverage Gate, in the good direction: this PR's new test/test_api_portability.py takes dashboard/handlers/portability.py from 17.0% to 82.4%, above the 80% per-file floor, so the gate asked for its .github/coverage-baselines/backend.txt entry to be removed or the baseline stops shrinking. Pruned with the repo's own updater against that run's coverage artifact rather than a local run, whose rates differ and would prune the wrong entries. The refresh only deletes, so the diff is exactly one line.

Manual verification

N/A — unit coverage sufficient: the backend tests exercise the real handlers
over HTTP including multipart, and the one user-visible surface is a string
chosen by refusalText, which is asserted directly at every branch.

Screenshots / video

Two surfaces change, and both change string and shape: the preview banner
(a refused archive preview) and the import banner (a refused import). Each is
shown before and after, in both locales -- eight images, uploaded as GitHub
attachments rather than committed, so the branch carries no binaries and the
links survive a force-push, a branch deletion and the merge.

The Japanese preview pair is the one that shows why this matters -- before, a
fully translated panel with a bare English sentence in it.

Preview refused -- 500 + code: preview_failed

Locale Before (main) After (this PR)
Japanese English prose: Preview failed
before, preview, ja
Localized: 無効なアーカイブ
after, preview, ja
English Preview failed
before, preview, en
Invalid archive
after, preview, en

Import refused -- 500 + code: import_failed

Locale Before (main) After (this PR)
Japanese English prose: Import failed
before, import, ja
Localized: インポートに失敗しました
after, import, ja
English Import failed
before, import, en
Import failed -- unchanged text
after, import, en

The English import pair is stated plainly rather than dressed up: the catalog
string for import_failed and the server's boilerplate are the same two words, so
that one pair shows no text delta at all. What it does show is the shape change --
AlertTriangle at 14px where AlertCircle sat at 12px, and the wider gap. It is
included because leaving it out would imply every locale gains a new string.

How these were captured, stated plainly: the real PortabilityTab, the real
src/index.css and theme tokens, and the real i18n catalog, with the real
file-input onChange driven to run the real preview path and, for the import
scenes, the real import path after a successful preview. The locale is switched
through initI18n, not by faking strings. Only the network response is stubbed,
to exactly what dashboard/handlers/portability.py answers on its 5xx paths --
{"ok": false, "error": "Preview failed", "code": "preview_failed"} at 500 for
the preview scenes, {"ok": false, "error": "Import failed", "code": "import_failed"} at 500 for the import scenes (which first take a real 200
preview, since the Import button only enables once a preview succeeded) --
because a specific server response is precisely what this change is about. Each
scene asserts the banner's text and its icon class before a file is written, so
none of these eight can show a surface that did not reach the state its filename
claims.

What is actually in the diff, since an earlier revision of this section said
"only the four PNGs are in the diff" and that was wrong twice over. No image is in
the diff at all now -- the eight above are attachments. Six files:

File Why
src/kiro_crew/dashboard/handlers/portability.py the nine refusals gain codes
website/src/pages/overview/PortabilityTab.tsx refusalText() and the two banners
test/test_api_portability.py new -- the 14 backend cases
website/src/pages/overview/PortabilityTab.test.tsx the 4 refusalText cases
error-code-baseline.json the ratchet, regenerated
.github/coverage-baselines/backend.txt one line pruned (see Coverage)

An earlier revision of this branch committed the eight PNGs under
temp-screenshots/portability-error-codes/. They are removed: the repo's own
evidence rule is that screenshots are uploaded with the description, not
committed, and the attachment URLs above are what the review lanes read.

The harness that drives the captures
(website/capture/portability-error-banners.{html,tsx} and
website/scripts/capture-portability-error-banners.mjs) is temporary and is
not committed.

Related Issues

No issue — this is the dashboard/handlers/portability.py line item from
error-code-baseline.json's own worklist ("drive missing_code to zero, one PR
per file or per directory, moving each frontend consumer in the same PR").

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — N/A, no doc surface changes
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Pattern harvest

Rule candidate: review-prompt — the backend half of this class is already ratcheted by error-code-baseline.json, so the part worth harvesting is the frontend rule: a client should prefer its own localized string over server prose exactly when the refusal is both coded and 5xx (where the server's text is deliberate boilerplate and says strictly less), expressed as one predicate on (code, status) rather than as a hand-maintained list of codes that has to stay in sync with the backend.

Section appended by a maintainer to satisfy the PR Hygiene gate, which began requiring a Pattern harvest section on fix: PRs after this PR was opened. No other part of this description, and nothing on the branch, was touched.

@leonlaiyc
leonlaiyc requested review from a team and patrigao August 26, 2026 14:13
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Aug 26, 2026
@leonlaiyc
leonlaiyc force-pushed the fix/portability-error-codes branch from 6d70bef to 74f17c4 Compare August 27, 2026 01:33
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Aug 27, 2026
@leonlaiyc
leonlaiyc force-pushed the fix/portability-error-codes branch from 9475834 to 639768b Compare August 27, 2026 04:19
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Aug 27, 2026
@leonlaiyc
leonlaiyc force-pushed the fix/portability-error-codes branch from 639768b to ac67704 Compare August 27, 2026 07:27
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Aug 27, 2026
@bolichen97
bolichen97 enabled auto-merge August 30, 2026 00:00
@bolichen97 bolichen97 added needs-pr-triage PR scanner: awaiting automated triage and removed needs-pr-triage PR scanner: awaiting automated triage labels Aug 30, 2026
@bolichen97
bolichen97 disabled auto-merge September 3, 2026 21:31
@bolichen97
bolichen97 enabled auto-merge (squash) September 3, 2026 21:31
@bolichen97

Copy link
Copy Markdown
Contributor

Open PR relationship audit

This is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion.

Relationship findings

  • This PR is OVERLAPPING with PR #7273. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #6066: REBASE. Different layers of the same refusal; 6066's contract is prose-agnostic, so 7273's new messages need no follow-up in 6066. Files: src/kiro_crew/dashboard/handlers/portability.py. The two independent directions used different labels; the matrix conservatively retains OVERLAPPING for coordination.
  • This PR is OVERLAPPING with PR #7308. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #6066: REBASE. Purely mechanical collision on a generated file; whichever lands second regenerates the baseline with python test/test_error_code_contract.py --update. Files: error-code-baseline.json.
  • This PR is OVERLAPPING with PR #8315. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #6066: REBASE. Complementary changes to one handler with disjoint hunks; whichever lands second needs no rework beyond ordinary context adjacency. Files: src/kiro_crew/dashboard/handlers/portability.py.

No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit.

@bolichen97

Copy link
Copy Markdown
Contributor

Rebased onto main 6fa5519c by a maintainer as part of the 2026-09-08 open-PR audit. No behaviour change; the nine coded refusals and refusalText() are exactly as you wrote them.

Conflicts resolved (both generated baselines, took main's version and re-applied only this PR's own edit):

  • error-code-baseline.json: regenerated with test/test_error_code_contract.py --update; net effect is missing_code 1137 to 1128 and the dashboard/handlers/portability.py entry dropped. _compliant kept at main's number plus 9 rather than the full fresh count, to avoid sweeping in unrelated drift.
  • .github/coverage-baselines/backend.txt: main had already removed the agents/cron/prompts lines; only the portability.py 17.0 exemption line is removed here.

Gates run locally on changed files: black, isort, flake8, pytest test/test_api_portability.py test/test_error_code_contract.py (20 passed), tsc --noEmit, and PortabilityTab.test.tsx (4 passed).

Please review the resolution. A maintainer push makes the maintainer the last pusher, so a second approver is needed under the repo's last-push rule. Reply if anything looks wrong.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 8, 2026
@iamwhatever
iamwhatever force-pushed the fix/portability-error-codes branch from a270079 to e11217b Compare September 21, 2026 21:28
@iamwhatever

Copy link
Copy Markdown
Contributor

Rebased onto main (0140fdd57) by a maintainer and force-pushed to e11217b36. Shape after the rebase: 6 files, +329/-17.

Conflicts resolved

src/kiro_crew/dashboard/handlers/portability.py (two hunks, export and import). main has since routed both handlers through the shared owner gate:

denied = await require_owner_dashboard_request(request, "portability.export")
if denied is not None:
    return denied

Both sides were kept: this PR's coded auth_required refusal answers the unauthenticated caller, and main's owner gate then runs for an authenticated non-owner. Preview is untouched by that gate on main, so it keeps the auth-only shape.

error-code-baseline.json (generated). Took main's side wholesale and regenerated with python3 test/test_error_code_contract.py --update rather than hand-merging counters.

One follow-on fix the rebase required

The owner gate reads request.app["state"].owner_id and requires the dashboard-subject marker request["app"] == "". The fixture app in test/test_api_portability.py supplied neither, so nine tests hit a KeyError: 'state' and got a 500 instead of the refusal under test. _make_app now installs a minimal state object with owner_id = "owner" (matching the X-Test-User: owner header the tests already send) and the middleware sets the dashboard marker. That is the whole delta versus the pre-rebase branch (+10 lines).

Baseline numbers

missing_code dashboard/handlers/portability.py
main 1118 9
this head 1109 entry removed (0)

Down 9, never up. Control: regenerating on a pristine origin/main worktree also yields 1118, so the delta is this PR's nine sites and nothing else.

Dropped from the branch

The four temp-screenshots/portability-error-codes/*.png files. temp-screenshots/ is in .gitignore and this repo does not carry committed binaries; they had been force-added. The coverage-baseline prune from that same commit is kept.

Tests and gates run

Gate Result
test/test_error_code_contract.py (incl. test_baseline_is_not_stale) pass
test/test_api_portability.py 14 pass
test/test_portability.py pass (123 pass / 5 skip combined with the two above)
PortabilityTab.test.tsx (vitest) 4 pass
scripts/check_black_formatting.py pass, nothing in scope unformatted outside the baseline
isort --check-only, flake8, mypy on the touched paths pass
eslint --max-warnings 0, tsc --noEmit, check-i18n-strings.mjs pass
check_comment_history.py, check_changelog_history.py (base origin/main) pass

Per-file coverage of portability.py measured at 91% with the sibling portability suites in the same run, clear of the 80% floor, which is what lets the coverage-baseline entry go.

The earlier PR Hygiene red for a missing ## Pattern harvest section is stale; the body carries it and fresh runs on this head supersede it.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 21, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew — drive-to-green pass on head 2b84111c4 (was e11217b36). One disposition per red lane.

GPT 5.6 Review 🔴 BLOCKING F1 — errors-use-error-notice: fixed

Agreed, and the adjudication's reading is the correct one. website/AUTOSDE.yaml declares the rule blocking, and its touch-it-migrate-it clause is explicit: "a diff that edits one (its message, styling, or condition) migrates it". This PR edits the message of both error paths (setPreviewError(refusalText(...)) and msg: refusalText(...)), so the two hand-written <div className="text-danger"> sites at the old lines 196-208 are no longer grandfathered.

Both now render through ErrorNotice with variant="inline", which keeps the existing compact 12px row layout — the block variant would have dropped a bordered banner into a column of inline status rows.

Scope of the migration:

  • previewError → <ErrorNotice variant="inline" … testId="portability-preview-error" />
  • importStatus → only the type === 'error' branch moves (testId="portability-import-error"). The ok and loading/idle lines stay in the plain container: the rule says client-side status about something that has not failed "must not be dressed as one".
  • The export row (line ~136) is untouched by this PR's diff and stays grandfathered — no change there.

Hand-off decision (the rule blocks on a missing decision, not on its direction): askAgent stays OFF on both, each with the required {/* No hand-off: … */} comment naming the draft it protects. The archive under import is held in the file input and in preview, neither saved anywhere durable. The hand-off navigates to the chat and unmounts this tab, and a File cannot be restored programmatically, so the user would have to re-pick the archive — the exact data loss the opt-in default exists to prevent. Same form as src/pages/ProjectsPage.tsx and src/pages/ArtifactDeployPage.tsx.

No message text, no condition, and no backend behaviour changed. Gates on the new head: tsc --noEmit ✅, eslint --max-warnings 0 on the file ✅, PortabilityTab.test.tsx 4/4 ✅, scripts/check_focus_cue.py ✅.

Coverage Combine / Coverage Gate 🔴 — not this PR; cleared by a re-run

Coverage Combine did all of its work successfully: all 8 shard artifacts plus the IPv6 and kernel-lock-owner data downloaded with matching digests, coverage combine / xml / report ran, TOTAL 91%. The job then failed on the very last step, uploading coverage-backend:

Finalizing artifact upload
##[error]Failed to FinalizeArtifact: Received non-retryable error: Failed request: (403) Forbidden: Error from intermediary with HTTP status code 403 "Forbidden"

That is GitHub's artifact service refusing the finalize call — no shard failed to produce data. Coverage Gate is purely downstream (::error::coverage-combine=failure -- failing closed. is its only output), so it inherited the red.

Re-ran the failed jobs with no code change. Both are green on the same commit e11217b36: Coverage Combine ✅ 00:28Z, Coverage Gate ✅ 00:31Z. No test file was touched.

UX Review 🔴 BLOCK — evidence gap, needs a human; I cannot close it

The BLOCK is "Cannot evaluate: missing screenshots of the changed error-banner text". That is correct and it is not fixable from code: the four raw/9475834…/temp-screenshots/… links point at a commit that is not in this repository, and the 2026-09-21 rebase deliberately dropped those PNGs from the branch (temp-screenshots/ is gitignored and this repo carries no committed binaries).

So the lane needs before/after stills (en + ja) of the import/preview error banner attached as assets of this revision — gh pr edit 6066 --attach … or a drag-and-drop into the description. That requires a human with a browser session; I am not adding a <!-- no-visual-delta --> waiver, because the change genuinely is visual (and is now more so: the banner's icon changes from AlertCircle to ErrorNotice's AlertTriangle and the row gains role="alert").

Watch — a preview_failed 500 renders "Invalid archive": still open, unchanged, needs-a-decision. The analysis is right and it is unaffected by the ErrorNotice migration (the message value is computed the same way; only the container changed). The three candidate resolutions were put to the maintainer on 2026-08-30 and none has been ruled on: (a) a new neutral preview_failed catalog key — semantically right, but new user-facing copy the author explicitly declined, and it fans out to 15 locale files; (b) drop the inversion on the preview call only — restores correct fault attribution with no new copy, but undoes the substitution this PR showcases; (c) keep as-is. I have deliberately not pushed any of them: (a) and (b) contradict the author's recorded intent in opposite directions, and this is a contributor's PR. One ruling closes both this Watch and the Design lane's.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 22, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew — drive-to-green pass on head 494f7b85e9 (was 03b6bf3515). Two changes, no code change.

1. Screenshot evidence moved from committed PNGs to real GitHub attachments.
The eight before/after captures are now https://github.com/user-attachments/assets/…
URLs in the description, uploaded with gh pr edit --attach. Each was verified to
resolve: the signed redirect returns 200, the served bytes are image/png, and every
sha256 matches the local capture. The previous raw/<sha>/… links are gone — they are
not admitted by .github/scripts/pr-attachment-evidence.sh, which allowlists
user-attachments assets only, and they would not have survived a force-push.

Because the eight PNGs were now redundant, the commit that carried them
(03b6bf3515, "restore the refusal-banner screenshots the rebase dropped") was
dropped. That commit contained nothing but the eight images, so removing them
emptied it. The branch is now a single commit whose tree is byte-identical to the
previously reviewed one: +346/-29, 6 files, 1 commit, no file deleted relative to
the merge base cc0c8214e, and no symbol lost in either touched .py. The
description's file table was corrected from fourteen files to six.

2. Every red on the previous head was the GitHub App installation rate limit, not a
finding.
GPT 5.6 Review, Opus 4.8 Review, Internal Content Scan and
Security Scope Review all reported "could not run", and Screenshot Evidence
failed with its own diagnostic — "Could not read this PR's description from the API
after 3 attempts … This is a read failure, not missing evidence"
— after three
403 API rate limit exceeded for installation responses. On this head all five ran
and passed, and Publish readiness signal is green.

Backend Tests (Windows) (1) failed once on
test/test_decisions_tool_risk_end_to_end.py — two assertions of the form
record is None after _settle(), an async-settle race on a shard that took 17
minutes. That file is byte-identical at the merge base, at main's tip and on this
head, and nothing in these six files can reach it; the other seven Windows shards and
all Linux shards passed. Re-run rather than patched.

Still open, and deliberately not pushed: the preview-fallback ruling.
UX Review and Design Review both returned 🟡 CONCERNS on this head with the same
item they raised on 5e0b85dfd — a coded 5xx on the preview path renders
invalid_archive ("Invalid archive"), attributing a server failure to the user's file.
The options are unchanged from the disposition already on this PR: (a) a new
localized preview_failed key, which is the new user-facing copy across the locale
files that the author explicitly declined for the export path; (b) drop the
inversion on the preview call only, which restores correct attribution but removes the
substitution these screenshots showcase; (c) keep as-is. This is a maintainer
ruling about a contributor's stated intent, so nothing was pushed for it. Both lanes
state CONCERNS is advisory and does not block merge.

…g 5xx boilerplate

`error-code-baseline.json` listed `dashboard/handlers/portability.py` with
`missing_code: 9` — nine refusals whose only identity was an English sentence.
The file already had the pattern: its 413 answers
`{"error": "archive too large (max 2048 MB)", "code": "import_archive_too_large"}`.
The other nine now follow it — `auth_required` (the wire name from
`handlers_cloud.py`), `file_field_required`, `invalid_import_mode`,
`import_archive_invalid`, and one `<operation>_failed` per handler.

The two kinds of 4xx here are deliberately kept apart. `import_archive_invalid`
carries the archive validator's own finding ("manifest.json is missing"), which
is the whole value of that message; the 5xx bodies carry opaque boilerplate
("Export failed") that exists precisely so the cause stays private.

`PortabilityTab` renders `data.error || <localized fallback>`, so it preferred
that English boilerplate over a catalog string that says the same thing in the
reader's language. `refusalText()` inverts it for exactly one case — a refusal
that is BOTH coded and 5xx — leaving 4xx detail and uncoded refusals of any
status untouched. The export path is not moved: its fallback is
`resp.statusText`, so there is no localized string to prefer, and writing one
is new user-facing copy rather than this contract.

The two error render sites move to `ErrorNotice`. Editing those refusal
messages takes them out of `errors-use-error-notice`'s grandfather clause
(`website/AUTOSDE.yaml`, declared blocking): a diff that edits a hand-written
`text-danger` site's message migrates it. Both now use `variant="inline"`, so
the compact 12px row keeps its layout. Only the FAILURE branch of
`importStatus` moves — the success and progress lines are status, not errors,
and the rule says those must not be dressed as one. `askAgent` stays OFF on
both, each carrying the `No hand-off` comment the rule requires: the archive
under import lives in the file input and in `preview`, neither saved anywhere
durable, and the hand-off unmounts this tab where a `File` cannot be restored
programmatically.

The coverage baseline's `portability.py 17.0` exemption is pruned — the new
HTTP-level tests put the file well clear of the 80% per-file floor, so it no
longer needs one.

Drive-to-green (rebase onto current main): original work by Leon (leonlaiyc);
resolved the error-code-baseline.json conflict by taking main's counters and
regenerating with `python test/test_error_code_contract.py --update`
(the portability entry deleted, `missing_code` down by exactly nine). All
source changes kept verbatim. Squashed to one commit for the `PR Hygiene`
one-or-two-commit rule; the tree is byte-identical to the three-commit form.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Kiro Crew <noreply@kirodotdev.github.io>
@iamwhatever

Copy link
Copy Markdown
Contributor

Rebased onto main to resolve error-code-baseline.json; no code change. The baseline was regenerated with python test/test_error_code_contract.py --update after taking main's side: missing_code 1115 -> 1106 (-9, this PR's own sites in dashboard/handlers/portability.py), tracked files 50 -> 49.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after verified readiness: passed, PR Readiness success on this head, mergeable, no open change requests. [operator: bolichen97 batch review 2026-09-23]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants