Package a versioned native terminal host image on Windows

Assemble the packaged Bun carrier, bundled host entrypoint, and a merged
manifest into a content-tagged image inside the real dev3 Windows bundle, so it
ships in the final update archive, and verify that archive end to end: validate
sizes/checksums/runtime/protocol/OS-arch/entrypoint/archive paths, stage the
image additively outside the installation root, drive detached start, reattach,
and stop with no Bun on PATH, then stage a second image beside the live one and
assert the older image is byte-identical and still selectable for rollback.

Merge the artifact manifest into the host-images module so it is type-checked
and covered by vitest, and gate it in CI together with a new job that builds the
real Windows package.

Author: h0x91b

.github/workflows/windows-conpty-package.yml

@@ -11,6 +11,7 @@ on:
       - "scripts/build-windows-terminal-host.ts"
       - "scripts/verify-packaged-windows-conpty.ts"
       - "scripts/verify-windows-conpty-update-archive.ts"
+      - "scripts/native-terminal-host-manifest/**"
       - "src/bun/native-terminal-host/**"
       - "src/shared/native-terminal-runtime.ts"
       - "src/bun/prototypes/detached-pty/**"
@@ -43,6 +44,11 @@ jobs:
       - name: Native shell launch pure tests
         run: bun run test:native-shell-launch
 
+      # Merged host-image manifest: generator, validator, deterministic assembly,
+      # additive staging outside the install root, and rollback selection.
+      - name: Packaged host image + manifest tests
+        run: bun run test:native-host-image
+
       # Real-runtime lifecycle regression for the persistent native-session
       # registry — runs on native Windows + POSIX with the pinned Bun 1.3.14.
       - name: Native-session registry lifecycle E2E
@@ -113,3 +119,36 @@ jobs:
           name: windows-conpty-package
           path: |
             scripts/fixtures/windows-conpty-package/artifacts/
+
+  # The REAL dev3 Windows package, not the isolated tracer fixture: proves the
+  # versioned native host image ships inside the final update archive and that
+  # it stages, launches detached, reattaches, and stops from there with no Bun
+  # on PATH. Separate job so its ~10 minutes do not eat the matrix job's budget.
+  windows-app-archive:
+    runs-on: windows-latest
+    timeout-minutes: 35
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup build Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.14"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      # postBuild assembles + validates the host image inside the bundle;
+      # postPackage re-verifies it from the final `.tar.zst` and drives the
+      # detached lifecycle from the staged copy.
+      - name: Build the real dev3 Windows package and verify the final archive
+        run: bun run package:win-archive
+
+      - name: Upload real Windows archive proof
+        if: always()
+        uses: actions/upload-artifact@v5
+        with:
+          name: windows-app-archive-proof
+          path: |
+            artifacts/windows-conpty-package-proof.json
+            artifacts/*-update.json

change-logs/2026/07/25/chore-windows-packaged-native-host-image.md

@@ -0,0 +1 @@
+The Windows build now assembles a versioned native terminal host image — the packaged Bun runtime carrier, the bundled host entrypoint, and a merged manifest with per-file checksums — into the real dev3 package, so it ships inside the final update archive and is verified from that exact archive. Staging the image is additive and lands outside the replaceable installation directory, so an older image keeps serving a running host while a newer one is staged beside it and rollback can select either. tmux remains the default terminal backend and nothing here starts the native host.

decisions/164-native-terminal-host-manifest-generator.md

@@ -36,11 +36,21 @@ NOT run under `bun run test`/`bun run lint` or in CI (the task also forbids addi
 a CI check). Type-check the module directly with
 `bunx tsc --ignoreConfig --noEmit --strict ... manifest.ts generate.ts`.
 
+## Superseded by 169
+
+Once packaging started consuming the manifest, the module moved into
+`src/bun/native-terminal-registry/host-images/artifact-manifest.ts` (CLI logic in
+`artifact-manifest-cli.ts`, a thin shim left at
+`scripts/native-terminal-host-manifest/generate.ts`). The core contract above is
+unchanged; the runner, the type-check path, and the CI gap are not — see
+`169-packaged-windows-native-host-image.md`. Tests now run under vitest via
+`bun run test:native-host-image` and are gated in CI.
+
 ## Risks
 
-Tests are not wired into CI, so a regression here is caught only by running the
-Bun test command above. Acceptable while the module is production-unused; when a
-packaging step starts consuming it, wire the tests into a checked path then.
+(Historic, resolved by 169.) Tests were not wired into CI, so a regression here
+was caught only by running the Bun test command above. Acceptable while the module
+was production-unused.
 
 ## Alternatives considered
 

decisions/169-packaged-windows-native-host-image.md

@@ -0,0 +1,85 @@
+# 169 — Package the versioned native host image inside the Windows archive
+
+## Context
+
+RUN-006 / WIN-004 (parent seq 1141, tmux removal) needed the packaged-runtime
+proof and the deterministic artifact manifest to become a real, versioned host
+image that ships inside the production Windows update archive — installable on
+demand, outside the replaceable application directory, without enabling the
+native backend. tmux stays the production default and its packaged artifacts are
+untouched.
+
+Two manifests already existed and described the same artifact from different
+angles: `image-manifest.ts` (immutable identity: tag, protocol version,
+entrypoint, runtime floor) and the `scripts/` artifact manifest (deterministic
+per-file size + SHA-256, Bun version, OS/arch). Neither knew where the image sits
+inside an archive, and the artifact manifest lived outside `tsconfig.json`'s
+`include` and outside every vitest root, so it was neither type-checked nor run
+in CI.
+
+## Investigation
+
+Electrobun's hook order settles where the image can be built
+(`node_modules/electrobun/src/cli/index.ts`): `postBuild` runs at line 3435,
+`createTar` at 3761, `postPackage` at 4243. The packaged Bun runtime only exists
+inside the build directory, and only content written under the app bundle before
+`createTar` reaches the archive. So the image must be assembled in `postBuild`,
+into the bundle directory that becomes the archive's top-level entry — which is
+also why `archiveRoot` is recorded relative to that bundle root rather than to
+the tarball root.
+
+## Decision
+
+- **Merged manifest** — `host-images/packaged-image-manifest.ts` embeds the
+  artifact manifest under `artifact` and adds `tag`, `runtimeFloor`,
+  `runtimeCarrier`, and `archiveRoot`. `validatePackagedHostImageManifest`
+  re-verifies sizes, SHA-256s, entrypoint, carrier, runtime floor, tag shape,
+  archive path, and caller expectations (OS/arch/Bun/protocol/tag) as typed
+  `ManifestError` codes. No clock is read, so the manifest is byte-stable.
+- **Content-derived tag** — `<bunVersion>-p<protocolVersion>-<digest12>`. Two
+  builds of the same bytes agree; a changed entrypoint lands beside the old image
+  instead of replacing it.
+- **Assembly at `postBuild`, verification at `postPackage`** — the real
+  `electrobun.config.ts` gained `postPackage`; `scripts/verify-packaged-windows-conpty.ts`
+  assembles + validates on the way in and, in archive mode, discovers the shipped
+  image, stages it, drives detached start / reattach / stop with no Bun on PATH,
+  then stages a second image beside the live one and asserts the old one is
+  byte-identical and still selectable for rollback.
+- **Staging root outside the install directory** —
+  `hostImagesRootDir()` = additive `~/.dev3.0/native-host-images/`
+  (`DEV3_NATIVE_HOST_IMAGES_DIR` override). `stagePackagedImage` copies into a
+  dot-prefixed scratch directory (invisible to every reader), validates, then
+  moves it into place; an existing tag is never overwritten and a corrupt copy is
+  discarded and reported.
+- **Manifest module moved into `src/`** — `scripts/native-terminal-host-manifest/manifest.ts`
+  became `host-images/artifact-manifest.ts`, its CLI logic
+  `artifact-manifest-cli.ts` (the `scripts/` file is now a thin shim). It is now
+  type-checked by `bun run lint`, runs under `bun run test`, and is gated in CI
+  via `bun run test:native-host-image`.
+
+## Risks
+
+- The new `windows-app-archive` CI job builds the real Windows package, which is
+  a heavier and less-exercised path than the tracer fixture; a failure there can
+  be an Electrobun packaging problem rather than a host-image problem. The proof
+  JSON names which stage failed.
+- Assembly needs `ELECTROBUN_APP_VERSION`, so the script only works as an
+  Electrobun hook, not standalone.
+- Windows code signing and uninstall are still **not** covered: Electrobun has no
+  Windows signing path and this change invented no credentials, so the RUN-006
+  signing/uninstall gap remains open. The image is unsigned, exactly like the rest
+  of the Windows package.
+
+## Alternatives considered
+
+- **Assemble into `dist/native/` and rely on a copy rule** — rejected: the
+  packaged Bun runtime does not exist at that point, so dev3 would have to
+  download and pin a second Bun itself.
+- **Assemble on first launch from the installed package** — rejected: then the
+  image is not *in* the archive, so nothing can be verified at build time.
+- **Keep the two manifests separate and validate twice** — rejected: the archive
+  path has to be checked against the same file table it describes, and two
+  independent schemas would drift.
+- **A fourth vitest project rooted at `scripts/`** — rejected: moving the module
+  into `src/` gets type-checking and CI for free (this supersedes the
+  "not wired into CI" risk recorded in decision 164).

electrobun.config.ts

@@ -61,6 +61,10 @@ export default {
 		},
 	},
 	scripts: {
+		// Windows only (both no-op elsewhere): postBuild assembles the versioned
+		// native host image into the bundle so it ships inside the update archive,
+		// postPackage re-verifies that image from the FINAL archive.
 		postBuild: "./scripts/verify-packaged-windows-conpty.ts",
+		postPackage: "./scripts/verify-windows-conpty-update-archive.ts",
 	},
 } satisfies ElectrobunConfig;

package.json

@@ -27,6 +27,8 @@
 		"test:native-shell-launch": "bunx vitest run --config vitest.config.bun.ts src/bun/native-terminal-registry/__tests__/shell-launch.test.ts src/bun/native-terminal-registry/__tests__/shell-probe.test.ts src/bun/native-terminal-registry/__tests__/windows-shell-runner.test.ts src/bun/native-terminal-registry/__tests__/windows-shell-evidence.test.ts src/bun/native-terminal-registry/__tests__/windows-shell-matrix-support.test.ts src/bun/native-terminal-registry/__tests__/host-config.test.ts src/bun/native-terminal-registry/__tests__/protocol.test.ts src/bun/native-terminal-registry/__tests__/registry.test.ts src/bun/native-terminal-registry/__tests__/client.test.ts src/bun/native-terminal-registry/__tests__/isolation.test.ts",
 		"test:native-live-parser-e2e": "bun src/bun/native-terminal-registry/__tests__/live-parser.bun-e2e.ts",
 		"test:native-host-images-e2e": "bun src/bun/native-terminal-registry/host-images/__tests__/lifecycle.bun-e2e.ts",
+		"test:native-host-image": "bunx vitest run --config vitest.config.bun.ts src/bun/native-terminal-registry/host-images/__tests__/artifact-manifest.test.ts src/bun/native-terminal-registry/host-images/__tests__/artifact-manifest-cli.test.ts src/bun/native-terminal-registry/host-images/__tests__/packaged-image-manifest.test.ts src/bun/native-terminal-registry/host-images/__tests__/packaged-image.test.ts",
+		"package:win-archive": "bun scripts/generate-build-info.ts && bun scripts/generate-changelog.ts && vite build && bun run build:cli && electrobun build --env=canary",
 		"test:native-parity-e2e": "bun src/bun/native-terminal-adapter/__tests__/parity-corpus.native-e2e.ts",
 		"test:terminal-state-spike": "bunx vitest run --config vitest.config.bun.ts src/bun/prototypes/terminal-state/__tests__",
 		"benchmark:terminal-state-spike": "bun src/bun/prototypes/terminal-state/benchmark.ts",

scripts/fixtures/windows-conpty-package/electrobun.config.ts

@@ -25,6 +25,7 @@ export default {
 		generatePatch: false,
 	},
 	scripts: {
+		postBuild: "../../verify-packaged-windows-conpty.ts",
 		postPackage: "../../verify-windows-conpty-update-archive.ts",
 	},
 } satisfies ElectrobunConfig;