[earakely-scale]

Stacked on #8877, which is stacked on #8875 and #8874. This branch contains all three. Review only af7253d38, ea252fba1, 4ba2cd964, 7a6ac88ab, 61e026406, 8ad0fabb7, 4c2ec7d28 and 7c49485f7, plus the merges cbaeb4e98, which keeps both this PR's command position and #8874's env assignments in unwrapDesktopCommand, and ae8cfbf95, which keeps both this PR's package-inventory split and #8874's ProgramLookup module. The other merges only bring the earlier PRs in. Once they merge, the diff shrinks to these.

Summary

Lets capture-desktop-application and export-desktop-application handle a closed-source app installed from its vendor's apt repository. The first such app is Typora. Until now the export refused anything not from the Ubuntu 24.04 archive, because the computer installs by package name.

The spec, plan and verification are in docs/specs/desktop-app-environments/vendor-packages/.

Problem and expected behavior

A vendor app such as Typora comes from the vendor's own repository, signed by the vendor's key. Its .deb may also leave out libraries that every desktop happens to have. On agentenv's minimal computer base, Typora installed from its repository would still fail to start without Electron's libraries. Inside a container, Electron also exits unless Chromium's sandbox is off.

After this change, the same capture and export produce a bundle that adds the vendor repository with the key that signs it, installs the app and the libraries it loads, and starts it. All of this was checked in a real agentenv computer (below).

Change and scope

• Capture: vendor repositories.
  • For each apt source of the installed version whose origin is not Ubuntu, the capture records the repository: uri, suite and components, from one-line or deb822 apt sources.
  • It also records the key that signs the repository. That is the signed-by key when there is one. Otherwise it is whichever trusted key gpgv shows verifies the repository's signed index in apt's lists; Typora's own install instructions use trusted.gpg.d.
  • The key is retained with the capture; it is a public key. When no key verifies, the capture records the reason.
• Capture: library packages. From the launched executable, the capture follows DT_NEEDED with RUNPATH/RPATH and the linker cache, using REA's ELF readers. It maps the libraries to their owning packages with dpkg-query -S, and records library_packages, missing_libraries and unpackaged_libraries.
• Export.
  • A verified vendor repository becomes AptSource(apt, suite, components, key="apt-keys/<name>.gpg|.asc"), with the key copied into the bundle.
  • A vendor package's library packages follow it in Packages(apt=[…]). An archive package's declared dependencies are trusted as they are.
  • A vendor source whose key was not verified is left out with a limitation; with none left, the export is refused.
  • When the capture marked the app as Electron, the export adds --no-sandbox to its launch and says so.
  • The generated data/get reports a database that the running app holds locked at once, instead of after SQLite's five-second wait.
• Not included:
  • deb822 sources with the key inline in Signed-By, which add-apt-repository writes on 24.04; they get a reason for now;
  • checking a Signed-By fingerprint against the verifying key;
  • pinning the vendor package's version;
  • leaving Electron's caches out of the seed.

Contract and boundary impact

• Semantic owner and earliest changed stage: capture_desktop_application (new optional package fields), then export_desktop_application.
• Contribution scope fit and linked maintainer decision: same approved desktop-environments work as feat(desktop): capture a Linux desktop application in use #8874.
• CLI and MCP/tool-catalog contract: no new commands or options; MCP catalog unchanged.
• Provider, bridge, target-format, or platform compatibility:
  • The capture runs gpgv, ldconfig -p and dpkg-query -S on the host. When one is missing, the facts it would give are recorded as unavailable.
  • Bundles target agentenv-framework 0.9.1431 AptSource.
• Evidence, artifact, provenance, or reconstruction contract:
  • New optional fields in the capture's package section: apt_repositories (with signing_key {path, sha256, format, fingerprint} or a reason), library_packages, missing_libraries, unpackaged_libraries and library_packages_reason.
  • Older captures still parse.
• Target selection, authority, upstream behavior, and cleanup details: gpgv runs on private copies of each candidate key, in a private runtime root that is removed afterwards.
• Generated metadata: none.

Expected effects:

• Read existing files or captured data.
• Launch or attach to a process.
• Inject instrumentation or run scripts/code.
• Change process memory, registers, files, or configuration.
• Contact network services.
• Recover protected code or work around protections.
• Documentation or usability only; no target interaction.
• Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

• Tests added:
  • parsers for one-line and deb822 sources, using Ubuntu 24.04's real ubuntu.sources and Typora's flat entry;
  • apt list names and ASCII armor;
  • real gpgv and ldconfig -p output, and ELF dependency reading;
  • the inventory with fake hosts: binary and armored keys, missing tools, no verifying key;
  • key retention;
  • the export of a vendor capture (key copied, AptSource, library packages, --no-sandbox) and its refusal without a verified key.
• Typora capture and export (Ubuntu 24.04 arm64 container, Typora 1.14.9 installed per its own instructions):
  • the capture recorded the repository, the key in /etc/apt/trusted.gpg.d/typora.gpg (fingerprint 4AC4…CFAE, verified by gpgv) and 85 library packages;
  • the export wrote envs/typora/apt-keys/typora.gpg and AptSource(apt="https://downloads.typora.io/linux", suite="./").
• Typora in an agentenv computer (agent-env run --keep --no-emulate, local Docker, agentenv-framework 0.9.1431):
  • Install: the build installed typora 1.14.9-1 from the vendor repository with the bundled key and no signature warning. A control run with an empty keyring fails with NO_PUBKEY.
  • Libraries: the base lacked libasound2t64, libnspr4 and libnss3, which the library packages added. ldd then found every library.
  • Start: Typora reached ready on its typora window. It exits at once without --no-sandbox.
  • Data: driven through the computer's input operations, data/get read trip.md as 8 lines, then 10 after the edit. data/reset relaunched Typora and restored all 79 seeded files byte for byte.
• Remaining proof gaps:
  • library packages were mapped on Ubuntu 24.04 arm64 only;
  • other vendor repositories (Sublime Text, VS Code) were not run end to end.

For evidence-bearing changes:

• Observed, derived, and inferred claims remain distinguishable.
• Artifact identity, source provenance, and failed attempts remain preserved.
• Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

• npm run typecheck, lint, lint:typed, format:check, knip, jscpd, docs:check, verify:test-discovery and verify:architecture-guards passed; there are no lint diagnostics in the touched files.
• Desktop tests: 176 passed on macOS and 186 on Linux in the container. CLI boundary: 30 passed.
• The Typora capture, export and agentenv run, as above.

Compatibility, safety, and release

• Breaking changes or migration steps: none; all new capture fields are optional.
• Real Hopper/Ghidra, browser, or OS coverage: Ubuntu 24.04 arm64, Typora 1.14.9, agentenv-framework 0.9.1431.
• Package or release metadata impact: none.
• Security, privacy, process, or containment review:
  • Only public signing keys are retained.
  • The computer trusts a vendor repository only through the key that verified it on the capture host.
  • --no-sandbox turns Chromium's sandbox off inside the computer, which is then the isolation boundary; the README and limitations say so.

Author readiness

Human owner: @earakely-scale

• I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
• I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
• I declare this PR ready for initial maintainer review.

Before merge

• This PR addresses a concrete problem or an agreed enhancement.
• Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
• The PR has one focused outcome and the title follows type(scope): outcome.
• Related issue is linked, or the reason for not linking one is stated above.
• Tests cover changed observable behavior and meaningful failure paths.
• Owning docs, contracts, and generated metadata are updated where needed.
• User-visible CLI/MCP changes include representative output.
• I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🤖 Generated with Claude Code