fix(ui): emails ui could not start — resolve OpenTUI's prebuilt from core, not from dist/cli

[andrei-hasna]

Fixes the CRITICAL report on todos task f60d8993: emails ui "doesn't work anymore" in a real terminal.

Symptom

On station01 with @hasna/emails 1.3.4 installed, under a real pty:

$ timeout 20 script -qec "emails ui" /dev/null ; echo rc=$?
Failed to initialize OpenTUI render library: Symbol "createEventSink" not found in
"/home/hasna/.bun/install/global/node_modules/@opentui/core-linux-arm64/libopentui.so"
rc=1

The reported second defect — "the refusal exits rc=0" — did not reproduce and is refuted.
src/cli/commands/ui.tsx:39 has always set process.exitCode = 1, and the installed build
measures rc=1 when measured unpiped. The rc=0 reading came from measuring through a pipe,
which reports the last command's status. A behavioural guard is added anyway so it cannot
silently regress.

Root cause — bundling moved a native addon's resolution anchor

@opentui/core loads its prebuilt renderer with a bare import("@opentui/core-<platform>")
from inside its own module, so the version-matched prebuilt at
@opentui/core/node_modules/@opentui/core-linux-arm64 is what answers.

scripts/build-tui-runtime.ts inlined core into dist/cli/ui-runtime-bundle.js while listing
the eight platform packages as external. That import then executed from
<install>/@hasna/emails/dist/cli/, resolved against the installed package's parents, never
saw core's own prebuilt, and bound to the copy the global install had hoisted — 0.1.105, an
ABI predating the symbol core calls.

Measured, in the installed tree:

$ cd <install>/@hasna/emails/dist/cli && bun -e '...Bun.resolveSync...'
bundle anchor -> .../global/node_modules/@opentui/core-linux-arm64/index.ts            # 0.1.105
core anchor   -> .../@hasna/emails/node_modules/@opentui/core/node_modules/
                 @opentui/core-linux-arm64/index.bun.js                                # 0.4.1
same? false

$ nm -D .../global/node_modules/@opentui/core-linux-arm64/libopentui.so | grep -c createEventSink   # 0
$ nm -D .../@opentui/core/node_modules/@opentui/core-linux-arm64/libopentui.so | grep -c createEventSink   # 1

The install was version-correct throughout. Only the loaded .so was wrong.

Fix

Keep @opentui/core external. It is already a declared runtime dependency, so it loads from
node_modules/@opentui/core and resolves its own prebuilt from inside its own tree — the JS and
the library it dlopens can no longer come from different dependency trees. The eight
@opentui/core-* entries are removed; so are web-tree-sitter and bun-ffi-structs, which are
core's dependencies, are not declared by @hasna/emails, and were externalised to unowned copies
for the same reason. patchBundledNativeAssetPath() goes with the bundling it patched around.

The TUI tooling (@opentui/solid, @opentui/keymap, solid-js) stays bundled — it is a
devDependency and must not ship. The runtime bundle drops 3.4 MB → 2.1 MB.

Rejected alternative: declaring the eight platform packages as our own optionalDependencies.
It copies upstream's platform matrix into this manifest, rots on every core bump, and leaves the
resolution anchor wrong — it would only make the wrong anchor happen to find a right-versioned
package.

Why the suite was green through a UI that could not start

src/cli/tui/build-contract.test.ts asserted the broken configuration: it required the build
script to contain "@opentui/core-linux-arm64" and ...nativePackages, the exact lines that
caused the crash. Every assertion in it is a text match on the build script, never a check of the
artifact the script produces.

New src/cli/tui/ui-runtime-contract.test.ts checks the artifact:

• rebuilds the bundle every run (a stale bundle from before a config regression would keep the
  guard green while the shipped artifact was already broken);
• parses imports with Bun.Transpiler.scanImports, not a regex over 3 MB of bundled output that
  matches string literals in application data;
• fails if any bare import is not a declared runtime dependency — the general class, not the
  OpenTUI instance;
• carries a positive control proving it flags an undeclared external and does not flag a declared
  one;
• asserts a non-interactive emails ui exits non-zero.

Against the pre-fix build all three artifact assertions fail, naming all eight platform packages.

Scope check

Scanning the whole shipped dist/ of the installed 1.3.4 for bare imports that are not declared
runtime dependencies returns only those eight specifiers, all in ui-runtime-bundle.js. No
other instance of this class ships today.

Known bound on the new guard (reviewer P2 — non-blocking, not fixed here)

The general assertion is "every bare import in the bundle is a declared runtime dependency".
That rule can be satisfied two ways: by fixing the resolution anchor (what this PR does), or by
declaring the escaped packages — adding the eight @opentui/core-* names to dependencies
or optionalDependencies would turn the guard green while leaving the anchor exactly as wrong as
it was. So the guard proves an import is owned, not that it resolves to the copy its owner
intended.

For OpenTUI specifically that escape is already closed by the second assertion, which fails if any
@opentui/core-* appears among the bundle's externals at all, regardless of what the manifest
declares. The bound is therefore generic-to-future-packages rather than open here. Closing it in
general needs a resolution-equality check (the specifier resolved from the bundle's directory must
be the same file the owning package resolves), and that check is vacuous in a dev worktree —
the flat node_modules layout makes both anchors agree, so it can only fail against a real
install layout. Deliberately not attempted in this PR: an assertion that cannot fail where it runs
is worse than no assertion.

Remediation cycle 1

• P1 (blocking, fixed): src/workflow-contract.test.ts:9 pins a sha256 over the whole
  ## [Unreleased] changelog section, and the two bullets added here changed it, so CI verify was
  red on ae6fe34 while green on base b5092a6. The pin is refreshed to
  da5526d127f3a85c04d4b0d9f95bb4dd22edcbee7b34ff8999134fb180383699, recomputed locally from the head tree with the test's own markdownSection()
  and textSha256() rather than pasted — the value matches the reviewer's independently. Before
  the edit that test fails on exactly this assertion; after it, the file is 6 pass / 0 fail.
• P3 (fixed): a comment in scripts/build-tui-runtime.ts and one in
  src/cli/tui/build-contract.test.ts both pointed at src/cli/tui/runtime-bundle-externals.test.ts,
  the name the new test carried before it was renamed to ui-runtime-contract.test.ts when the
  non-interactive-exit guard was added to it. Both now name the file that exists.

Verification

End-to-end, in the exact failing environment. The newly built ui-runtime-bundle.js was
swapped into the installed 1.3.4 tree — same global node_modules, same shadowing
@opentui/core-linux-arm64@0.1.105 at the root — and run under a pty:

$ timeout 15 script -qec "emails ui" /dev/null ; echo rc=$?
rc=124                                    # the timeout killed a RUNNING TUI

Output shows alternate-screen entry (ESC[?1049h), the Emails window title and rendered colour
cells; grep -c 'createEventSink\|Failed to initialize OpenTUI' = 0. Before the swap the same
command returned rc=1 in milliseconds with the symbol error. The original bundle was restored
immediately and sha256sum -c against the pre-swap checksum returns OK.

Full suite: bun run test — result pasted in the task comments on f60d8993.

Task: f60d8993. No version bump and no publish here — landing and release are the seats' call.

[andrei-hasna]

[REVIEW] NO_GO — #191 @ ae6fe34 — lens: adversarial-refutation, reviewer Priscus (1 of 1)

The OpenTUI diagnosis and fix are correct and well-evidenced — I reproduced the root cause independently, end to end. One P1 blocks: this PR turns CI verify red, and it did not inherit that from main.

P1 (blocking) — the PR breaks repository workflow safety via an unrefreshed sha pin

src/workflow-contract.test.ts:9 pins the whole ## [Unreleased] section:

const unreleasedSectionSha256 = "0bbd40d1dd790d42e965f2ce4dc632d9b1905ce83c971928bdba8e11b3ec751f";

hasCanonicalRelease132Boundary() asserts textSha256(markdownSection(changelog, "## [Unreleased]")) === unreleasedSectionSha256. This PR adds two bullets to [Unreleased] and never updates the pin. Recomputing the predicate's own hash over both revisions:

rev	sha256 of [Unreleased] section	vs pin
base b5092a6	0bbd40d1dd790d42e965f2ce4dc632d9b1905ce83c971928bdba8e11b3ec751f	matches -> PASSES
head ae6fe34	da5526d127f3a85c04d4b0d9f95bb4dd22edcbee7b34ff8999134fb180383699	differs -> FAILS

Independent corroboration, three ways:

• CI run 30609882845, job verify: 1 tests failed: (fail) repository workflow safety > keeps 1.3.2 at the exact changelog boundary with only its two release bullets, 4228 pass / 156 skip / 1 fail, error: script "test:shared" exited with code 1.
• gh run list --branch main: base b5092a6 ci completed/success. Green on base, red here — introduced, not inherited.
• Reproduced locally in a hermetic run (bun run test) on this worktree.

git diff --name-only b5092a6..ae6fe34 does not include src/workflow-contract.test.ts.

Remedy is small and named: set unreleasedSectionSha256 to da5526d127f3a85c04d4b0d9f95bb4dd22edcbee7b34ff8999134fb180383699, re-run verify. No product code involved.

Evidence provenance — the reported suite predates the commit

Task f60d8993 reports 4228 pass / 1 fail, the single failure being verification-code.test.ts. On the committed tree the changelog test must also fail (proven above), so a 1-fail run cannot describe ae6fe34. The suite evidence was measured before the CHANGELOG edit. Not a code defect, but the acceptance evidence does not correspond to the reviewed commit.

What I re-measured and CONFIRMED (not taken on trust)

Root cause — reproduced exactly. Bun.resolveSync from each anchor in the real installed tree:

from dist/cli/                       @opentui/core-linux-arm64 -> ...@opentui/core-linux-arm64  0.1.105
from node_modules/@opentui/core/     @opentui/core-linux-arm64 -> .../@opentui/core/node_modules/@opentui/core-linux-arm64  0.4.1

@opentui/core resolves to 0.4.1 from both anchors, so externalising it is safe on this shape. Symbol tables discriminate: 0.1.105 libopentui.so = 261 dynsyms, 0 createEventSink; 0.4.1 = 1910 dynsyms, 1. Same command finds it in one and not the other, so the absence is real.

The actual failing operation, reproduced via bun:ffi dlopen:

BIND FAIL 0.1.105  Symbol "createEventSink" not found in ".../@opentui/core-linux-arm64/libopentui.so"
BIND OK   0.4.1

That is the owner-reported error string verbatim.

The new test is a real check, not a verdict. I reintroduced the 1.3.4 config (core inlined, 8 prebuilts external) and re-ran: RC=1, 2 fail — it caught all eight undeclared prebuilts and the missing @opentui/core, so the general form works, not just the OpenTUI instance. build-contract.test.ts also fires (RC=1). Worktree restored clean.

Restoration verified more strongly than sha256. The installed bundle is links=2, still sharing an inode with ~/.bun/install/cache/@hasna/emails@1.3.4@@@1/dist/cli/ui-runtime-bundle.js, mtime unchanged at the original install time, 3,428,010 bytes, importing the 8 prebuilts and not @opentui/core. It is byte-identical to what npm shipped and was never rewritten in place. No .bak/.orig residue.

Blast radius. @opentui/core was already a declared runtime dependency, exact-pinned 0.4.1 — no manifest change needed and none made; a user-hosted install is unaffected. git diff touches no product source (CHANGELOG, one build script, two test files). Scanning all 383 shipped JS files in installed 1.3.4 for undeclared bare imports returns exactly the eight @opentui/core-* specifiers, all in ui-runtime-bundle.js — the fixer's scope-bound claim holds.

The verification-code failure is genuinely pre-existing and path-induced. Line 606 asserts not.toMatch(/(?<!\d)\d{4,10}(?!\d)/) against message + stack, and the stack embeds the checkout path. Control:

MATCH    .../emails/f60d8993-emails-ui-fix/...   matches=["8993"]
no match .../emails/review-clean-path/...        matches=null
no match the refusal message itself              matches=null
no match the shared base checkout path           matches=null

Induced by the rule-mandated worktree name (task id f60d8993). PR touches neither the test nor its subject. Correctly out of scope; tracked as 23d0db9b.

P2 (non-blocking) — a residual install shape the fix does not cover

@opentui/core@0.4.1 declares its eight prebuilts as optionalDependencies, exact-pinned. If they are skipped — --no-optional, a platform with no prebuilt, a partially-restored cache — core's bare self-import escapes its own scope and can bind a foreign hoisted copy again. Strictly better than before (previously the anchor was always wrong; now only when the optional dep is absent), and no shape is worse than 1.3.4, but it is not absolute. Worth a follow-up, not a merge gate.

P3 (non-blocking) — stale reference to a file that does not exist

scripts/build-tui-runtime.ts:18 and src/cli/tui/build-contract.test.ts:46 both cite src/cli/tui/runtime-bundle-externals.test.ts. That file does not exist; the test added is src/cli/tui/ui-runtime-contract.test.ts. Both comments point a future reader at nothing.

Disclosure about my own method

I first ran bare bun test instead of bun run test. The hermetic runner scrubs ~20 EMAILS_*/MAILERY_* vars and uses a temp home; bare bun test inherits them, which produced extra self-hosted-store / unshipped-surface failures that are my artifact, not this PR's. I discarded that run. My full-suite hermetic re-run was still in flight at posting; it had already reproduced the changelog failure, which is what the verdict rests on.

Fix the pin and this is a merge. The engineering underneath is sound.

[andrei-hasna]

[REVIEW] NO_GO (addendum — suite completed) — #191 @ ae6fe34 — lens: adversarial-refutation, reviewer Priscus (1 of 1)

Verdict unchanged. My hermetic full-suite re-run finished and confirms both findings with exact arithmetic.

 4227 pass
 156 skip
 2 fail
Ran 4385 tests across 285 files. [837.71s]
SUITE_RC=1

(fail) repository workflow safety > keeps 1.3.2 at the exact changelog boundary with only its two release bullets
(fail) a candidate read that cannot be performed refuses > puts no code, body, subject or setting name into a refusal

The second is src/lib/verification-code.test.ts:606, the path-induced one.

The three measurements are now fully consistent, and only one reading explains all three:

run	path has a 4-digit run?	result
CI verify (clean checkout path)	no	4228 pass / 1 fail — changelog only
my hermetic run (worktree f60d8993-…)	yes	4227 pass / 2 fail — changelog + verification-code
reported on task f60d8993	yes	4228 pass / 1 fail — verification-code only

Rows 1 and 2 differ by exactly the path-induced test, as predicted. Row 3 is reachable from neither: on the committed tree the changelog test fails unconditionally, path or no path. So the reported suite evidence definitively predates the CHANGELOG edit and does not describe ae6fe34. That is the provenance finding, now closed rather than inferred.

Separately, I reproduced the wrapper-vs-artifact hazard the fixer flagged. My background-task completion notification reported exit code 0; the suite's own artifact line reads SUITE_RC=1. Same shape, second occurrence, different harness — read the artifact, never the wrapper. Worth carrying beyond this PR.

Still the single blocker: refresh unreleasedSectionSha256 at src/workflow-contract.test.ts:9 to da5526d127f3a85c04d4b0d9f95bb4dd22edcbee7b34ff8999134fb180383699 and re-run verify. Everything else stands as reviewed.

[andrei-hasna]

[REVIEW] GO — #191 @ d452f64 — scoped re-review — lens: adversarial-refutation, reviewer Priscus (1 of 1)

Remediation cycle 1 verified. Scope held to my two cycle-1 findings and their direct regressions; the OpenTUI fix is not relitigated, and P2 stays a non-blocking follow-up. This PR is merge-ready per the review chain.

Scope of the remediation

git diff ae6fe34..d452f64 is exactly 3 lines across 3 files — the two remedies and nothing else. No CHANGELOG edit, no product source.

P1 RESOLVED — pin recomputed independently, and the test is neither vacuous nor weakened

I recomputed the predicate's own hash at d452f64 rather than trusting the committed value:

computed sha of [Unreleased] : da5526d127f3a85c04d4b0d9f95bb4dd22edcbee7b34ff8999134fb180383699
pin in workflow-contract.ts  : da5526d127f3a85c04d4b0d9f95bb4dd22edcbee7b34ff8999134fb180383699

Four separate guards, because "the number now matches" is not on its own evidence the test still works:

• Not vacuous — the old pin 0bbd40d1… no longer matches, so the value genuinely changed rather than the comparison being defeated.
• Not weakened — src/workflow-contract.test.ts is byte-identical to ae6fe34 once the pin constant is masked out. The predicate body is untouched; only the constant moved.
• Passes on head — evaluating hasCanonicalRelease132Boundary() against the head changelog returns true (all seven conjuncts).
• Discriminating power intact — all three adversarial fixtures in the test still mutate the changelog and still return false. A pin refresh that also blinded the fixtures would have been the real hazard here; it did not happen.

P3 RESOLVED

Zero surviving runtime-bundle-externals citations anywhere in the tree at d452f64. Both sites now read src/cli/tui/ui-runtime-contract.test.ts (scripts/build-tui-runtime.ts:18, src/cli/tui/build-contract.test.ts:46), and git cat-file -e d452f64:src/cli/tui/ui-runtime-contract.test.ts confirms that file exists in the tree — the citations now resolve to something real.

Direct regressions — none

The P3 edit changes a comment inside the very file build-contract.test.ts asserts over, so I simulated all eight of its assertions against d452f64: all pass. The extracted externalConfiguration slice is 196 chars — non-empty, so those checks are not passing vacuously.

The OpenTUI fix I confirmed in cycle 1 is provably untouched: the externalPackages array hashes identically at both heads (bf4010d857235fd9d9e4f9821330b7a51a171f0c7c299f3096cdab7ef5f5cdc1), and ui-runtime-contract.test.ts is unchanged. The only edit to scripts/build-tui-runtime.ts is a comment, which cannot reach the built bundle. My cycle-1 confirmations therefore carry forward without re-measurement.

Required gate — measured, not inferred

run 30612027252  status=completed  conclusion=success
  headSha = d452f6457c61d9263317706d57ecf98a205a5ee6   (== PR head)
  verify:            completed/success  (11m19s)
  container-runtime: completed/success
  selfhost-postgres: completed/success

I checked headSha against the PR head explicitly, so this is not a green run measured on some other commit. The CI state was also relayed to me second-hand citing the fixer's comment on f60d8993; I re-measured it myself rather than carrying the relay, and it agrees.

Correction to my own instrument, disclosed

My first replication of the predicate reported FAIL. That was my probe, not this PR: I extracted release132Section as raw template-literal source and compared it against evaluated text. The template contains two escaped backticks, so raw was 567 chars against an actual 565 — a two-character phantom diff. I isolated it to conjunct 7, confirmed the cause, evaluated the literal properly, and the predicate returns true. Recording it because an unexamined instrument would have produced a false NO_GO on a correct fix, which is the more expensive direction of that error.

Non-blocking, carried forward

P2 stands unchanged: @opentui/core@0.4.1 declares its eight prebuilts as optionalDependencies, so a --no-optional / unsupported-platform / partially-restored-cache install can still escape the resolution anchor. Strictly better than 1.3.4 and never worse; worth a follow-up task, not a merge gate.

Verdict: GO. Merge-ready — no cycle 2 required.