@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/host/truapi-cli/README.md

@@ -0,0 +1,807 @@
+# @product-lab/host-truapi-cli
+
+Host provider for the truAPI CLI host (`truapi-host`, from host-rust-core).
+Imported from the original lab's hosting module.
+
+- `launchPlan(session, options)` / `launch(session, options)` start `truapi-host dev` in front of the app's dev
+  server (or the app alone in `standalone` mode), with per-run host state,
+  strict ports, a run lock and a `launch.json` record. Inherited host/signer
+  variables are stripped. `system: { ports, locks, processes, commands }` (the `PortAllocator`,
+  `LockManager`, `ProcessRunner` and `CommandRunner` ports) is required. `supervision.supervisor`
+  may provide an existing `OwnedProcesses` registry; otherwise the launcher opens
+  one under `<runDir>/processes`, records the host or standalone app as `host`,
+  prints its log path, and closes the registry after stop. Ctrl-C, SIGTERM and
+  abort use the registry's fingerprinted stop policy (SIGTERM, 10 s, then SIGKILL).
+  Callers construct the Node classes (`@product-lab/system-node`).
+- Everything app-specific is a parameter: `productLabel`, the `app` command
+  (`npmWorkspaceDevServer(workspace)` reproduces the npm + Vite launch), and
+  `appEnv(session, context)` for plain variables such as `VITE_*` (`context.routes`
+  carries the network, namespace and chains). `session` is the app's own
+  record, written to `sessionFile` and opaque to the launcher.
+- `checkHost` runs the patched host's `local-network-check` and requires it to
+  confirm the complete local routing contract before launch (`echoesRouting` in
+  `network-config.ts`, shared with the capability probe and `host rebase-check`:
+  format version 1, spelled `schemaVersion` by the lab's patch and
+  `schema_version` since host-rust-core #1454). Host contract, version and
+  launch evidence probes use the bounded command runner.
+- Routing (`network-config.ts`, refactor step 7 part b): `routes` is the
+  domain's `HostNetworkRoutes` (`@product-lab/domain`), for example
+  `RunningEnvironment.routes` or env-engine's `engineRoutes(session)`. It was
+  validated when built (loopback unless an explicit recorded `publicRoutes`
+  opt-in, no credentials or query, 32-byte distinct genesis hashes, the
+  network's namespace). `truapiCliNetworkConfig(routes)` derives the host's
+  routing file (`HOST_CLI_LOCAL_NETWORK_CONFIG`, `TruapiCliNetworkConfig`) and
+  requires People, Asset Hub and Bulletin with their genesis and the
+  `identity-backend` service: an environment without them (a relay-less People
+  node) routes the absent ones to closed loopback ports with `routes.with(…)`.
+  `routesFromTruapiCliNetworkConfig` reads a routing file back. The routing
+  and product namespace come only from `routes`: `HostNetworkSession`,
+  `HostRoutes`, `completeHostRoutes` and `hostRoutes` (moved here from
+  env-engine in part a) are removed.
+- `signerMnemonic` makes the host sign as a supplied wallet (testnet keys
+  only) instead of onboarding an identity. It travels in the environment, and
+  `--session` is omitted because the host rejects it with a mnemonic. The
+  notes example uses both to run on People alone.
+- Product configs (phase2-nav, `product-config.ts`): `productConfigs` (absolute
+  paths) makes the host seed each product's local product config into its
+  manifest cache (`--product-config`, repeated, before the app command), so a
+  product's declared `trustedProducts` grants resolve without the name service;
+  the host prints "Local product grants — declared in config, not published to
+  dotNS". Each file is validated as the domain's `ProductConfig` before
+  anything starts (JSON, a DotNS `productName`, bare-label keys, one config per
+  product) and refused (`ProductConfigRefused`) when a URL in it or any host
+  route is off this machine, unless `productConfigOptIn: { reason }` records
+  why. `launch.json` records each file's sha256, product, grants and the
+  opt-in. It also records the app checkout's commit and whether it has changes
+  (`appCommit`, `appDirty`). They label the evidence only, so an app checkout git cannot
+  read (`appCheckout`; a git link that resolves nowhere) launches anyway, with
+  `appCommitUnknown` naming the checkout and git's reason (backlog 245).
+- A local environment needs `localNetwork`: the `patches/truapi-host/local-network.patch` patch
+  (`localNetworkPatch()`) on a patched host, or an official release that provides it (below), resolved through this adapter's own reader of
+  `patches/truapi-host/manifest.json` (`patch-manifest.ts`: `resolveHostPatch`,
+  digest-checked; env-engine's reader served it before step 7). The patches are product-lab's repository's only
+  (21 October 2026: the package carries no `patches/`): what an installed package needs of the manifest, each patch's
+  `adds` and first upstream pull request, is `HOST_PATCH_CATALOGUE` (`src/patch-catalogue.ts`, equal to the manifest
+  by `tests/patch-catalogue.test.ts`; `patchCatalogue` derives it). `readHostLock` checks `official.provides` and
+  `knownBehaviours`/`describeBehaviour` name behaviours from it. Reading the manifest or a patch file where
+  `patches/truapi-host/` is absent throws `HostPatchesNotInstalled` ("patched hosts are built from the product-lab
+  repository", `HOST_PATCHES_REPOSITORY_ONLY`), so `host build`, `host rebase-check`, a routed patched release and a
+  cached patched host are refused by name in an installed package (`tools/eval/tests/packed-no-patches.test.ts`). Hosts are acquired automatically (below); `hostBin`
+  remains only as an escape hatch and is reported as an unpinned host.
+- Navigation events (`navigation.ts`): a host carrying
+  `patches/truapi-host/navigation-events.patch` appends `{"url","at"}` JSON
+  lines to `TRUAPI_NAVIGATIONS_LOG`, which `launchPlan` sets to
+  `<runDir>/navigations.jsonl`. `watchNavigations` tails it as an
+  `AsyncIterable` of `{ url, product, path, at }`. `resolveNavigation` and
+  `parseProductUrl` live in `@product-lab/domain` (re-exported here).
+- Per-request decisions (`host-requests.ts`, 25 September 2026):
+  a host
+  carrying `patches/truapi-host/request-decisions.patch` publishes each
+  confirmation as `<id>.request.json` in `TRUAPI_DECISIONS_DIR` and waits for
+  `<id>.decision` (the answer a terminal would type). A file channel in the
+  session's run directory (mode 0700): no socket, so it works unchanged under
+  the deny-by-default sandbox.
+- The product-account read (`script-account-read.ts`, 21 October 2026):
+  `scriptAccountRead` runs `signing-host --script` with a product script
+  (`PRODUCT_ACCOUNT_SCRIPT`, `truapi.account.getAccount` at `PL_INDEX`) on a
+  one-shot host with the serving host's binary, base path, signer (stored
+  `--session` or `HOST_CLI_SIGNER_MNEMONIC`), network, routing and sandbox, and
+  returns `{ address, publicKey, productId, derivationIndex }`. No patch: every
+  host with `--script` answers it. It runs beside the live host and changes no
+  file on the binary that serves; a non-zero exit is refused loudly (the known
+  case: the account store is locked while a host onboards a new session, so
+  read after provisioning). The host runs the script with Bun, so `bun` must
+  be on its PATH. It replaced the `product-account-read` patch's
+  `TRUAPI_ACCOUNT_REQUESTS_DIR` channel (host-rust-core #1170).
+- `chain-reconnect.patch` ends interrupted native subscriptions so the existing
+  client can reconnect. The separately installed SDK patch bounds synthetic
+  transport retries; both are needed for the verified original-app recovery.
+  This patch
+  adds no new host conformance flag.
+- One host process serves one product; run one process and one state
+  directory per actor and app.
+
+## `truapiCliHost`: the core HostProvider
+
+Sessions expose passive `networkEvidence()` from their Browser port, retaining every direct endpoint
+and coverage gap. Only the exact host bridge script and frame WebSocket URLs are marked `host-bridge`,
+including URLs from earlier host restarts; other loopback traffic stays listed. A browser without passive
+observation reports incomplete coverage.
+
+The `signature-evidence` patch, included in the current repository patched set, writes actual returned signatures and signer keys to
+`TRUAPI_SIGNATURES_LOG`; complete returned extrinsics also yield their exact BLAKE2b-256 transaction hash.
+Known native `sign payload` and `create transaction` records return SCALE `MultiSignature`: their
+`signature` is normalized to the raw scheme-specific bytes the chain adapter reports, while
+`returnedSignature` preserves the exact returned encoding and `signatureScheme` records the variant.
+Raw message signatures and unknown operations retain their original bytes; no leading byte is removed
+without the known transaction encoding and a valid variant/length.
+`readSigningEvidence(approvalsFile, signaturesFile?, processId?, complete?)` is exported for adopted CLI
+sessions. It never correlates review counts or wording with signatures. Only the exact
+`coverage` / `local-returned-signatures` startup marker establishes initialized coverage; empty or unmarked
+logs retain a gap, while valid actual signature records remain usable. An initialized structured log is
+authoritative for successful local signing; denials remain in the approval transcript. A missing log,
+malformed record or log over 16 MiB creates a coverage gap. Legacy review-only hosts cannot prove a
+signature, even when they approved a request. Both `launchPlan` and HostProvider sessions forward the
+approval and signature transcript paths. WASM and remote-only signing need their own actual-return
+evidence; this native patch records local signer results and complete locally assembled transactions.
+
+`host.ts` holds the provider's lifecycle (`truapiCliHost`, `createTruapiCliHost`: resolve, prepare, the session
+checks, identity import, dispose) and exports its public names; one host process is `host-process.ts`
+(`startHostProcess`, the data-directory lock and the process environment), one session is `cli-session.ts`
+(`openCliSession`: the page, approvals, navigations and the identity swap), and the types are `host-types.ts`.
+
+`truapiCliHost({ patches, browser, routes, stateRoot, ports, system, host?, hostBin?, denyByDefault?, networkExceptions? })`
+implements `HostProvider` (`@product-lab/ports/host`), validating its options once with
+`truapiCliHostOptionsSchema` (`host-options.ts`, refactor step 5) before creating the host. Backlog 185: the factory
+declares the host's options in plain words (`TRUAPI_CLI_HOST_OPTIONS`, `HostAdapterFactory.hostOptions`): `networkLocked`
+("network locked", `denyByDefault`) and `oneWalletForAllApps` ("one wallet for all apps of a person", `actorStateRoot`, by
+default `<stateRoot>/actor-state`, `ACTOR_STATE_FOLDER`), both per identity; when set, each decides over the key it
+stands for (`effectiveTruapiCliOptions`, `tests/host-options.test.ts`). `system`
+holds the `ProcessRunner` (host processes under `<stateRoot>/processes`; `prepare()` first stops a host a killed lab process left running there, which would hold its port, and leaves the hosts of a lab process still running alone: backlog 13a), the `CommandRunner`
+(bounded host probes), the `LockManager` (one lock per data directory, a dead holder's lock taken over), the `PortAllocator` (host ports from
+`ports`) and, only for `denyByDefault`, the `ProcessSandbox` (`@product-lab/ports/system`,
+`system.sandbox`); `truapiCliProvisioner` takes `system: { processes, commands }`.
+
+- Without `hostBin`, `resolve()` takes the cached host for `patches`
+  (`acquireTruapiHost`, below) and records its origin, label, binary and
+  archive digests and attestation in the resolved host and every session's
+  evidence. A missing patched host fails with the exact `host build` command.
+
+- One `truapi-host signing-host --serve --frame-listen 127.0.0.1:<port>`
+  process and one data directory per (actor, app):
+  `actors/<actor>/apps/<app>/identities/<fingerprint>/host-state`, claimed
+  with a lock so two live processes can never share it (the spike showed
+  `core-storage.json` is last-writer-wins). A second concurrent session for
+  the same actor and app is refused; sequential reuse keeps the directory.
+  A session is ready when the host logs `Signing host ready` and then serves its bridge script
+  (`/bootstrap.js`), both within `readyTimeoutMs`; a host that does not is stopped and the start fails
+  with the reason. A session start that fails keeps its own error; a host that then does not stop is
+  added to it (`AggregateError`), never replaces it (`tests/host.test.ts`).
+- Every session of an actor signs as the actor's wallet
+  (`HOST_CLI_SIGNER_MNEMONIC` from the `ProvisionedIdentity` entropy), so its
+  product accounts match across apps. Inherited `HOST_*`, `TRUAPI_*`, `VITE_*`,
+  `PPN_*`, `PRODUCT_LAB_*` and `RUST_LOG` are removed; the update check is off.
+- `productConfigs` and `productConfigOptIn` (options) are read and decided once
+  in `prepare()` (a refused config fails before any session) and passed to
+  every session's `signing-host`; each session's evidence records them.
+- `actorStateRoot` (opt-in, absolute path; phase2-nav): every app of one actor
+  keeps its host data in ONE directory, `<actorStateRoot>/<actor>/identities/<fingerprint>`,
+  as the products of one device share its host storage (the CLI keeps product
+  storage, and so what a cross-product `local_storage_read` sees, per data
+  directory). It is the one sanctioned exception to "never share a host data
+  directory" (adapters/AGENTS.md), for sequential sessions only: the
+  directory's session lock refuses a second session of the actor while one
+  runs, whatever its product and whichever provider opens it (providers of one
+  lab share its `LockManager`). The session evidence and the run's
+  `session.json` record `sharedState: { actor, dataDir, rule: "sequential" }`.
+  Default: one directory per actor and app. `tests/actor-state.test.ts` (its
+  negative control: without the lock check the concurrent session opens and
+  the test fails).
+- Approvals: `approve-all` runs with `--auto-accept`; `deny-all` runs without
+  it, so the terminal-less host denies every confirmation. Decisions come from
+  `TRUAPI_APPROVALS_LOG`. With the `request-decisions` patch
+  (`perRequestApproval`), a session created `per-request` runs without
+  `--auto-accept` and with `TRUAPI_DECISIONS_DIR=<runDir>/decisions/<process id>`
+  (one directory per host process, since ids restart with it) and
+  `TRUAPI_DECISIONS_TIMEOUT_MS` (`decisionTimeoutMs`, default 120 000 ms; an
+  unanswered request is then denied): `approvals.pending()` lists the waiting
+  requests (`{ id, action, kind: "action" | "permission", at }`), and
+  `approve()` / `deny()` decide the oldest one, waiting up to
+  `pendingTimeoutMs` (default 60 000 ms) for one, and return it once the host
+  has taken the decision. A permission is allowed once (`o`), so the next
+  request asks again. Fixed-policy sessions never get the directory, so
+  `deny-all` keeps denying at once.
+- `navigations` tails the session's `TRUAPI_NAVIGATIONS_LOG` (declared only
+  with the `navigation-events` patch); `open(path)` reloads the app page at a
+  path; `importIdentity` restarts the host as the imported wallet in that
+  identity's own directory and reloads the page.
+- The actor's account (backlog item 62): `session.account(index)` answers
+  from the identity the lab started the host with, when the adapter is given a
+  `ProductAccountDerivation` (`deps.accounts`, `TruapiCliFactorySettings.accounts`;
+  the composition root passes `Sr25519ProductAccounts`): `source: "identity"`,
+  no patch and no page. Without a derivation it asks the host (below), and
+  without either it throws `UnsupportedHostOperation` naming what is missing.
+  With a derivation that gives them, `session.resourceAccounts()` lists the
+  accounts this host claims a statement allowance and Bulletin storage for
+  (RFC-0010): the host-bypass audit credits the host's own `AsResources`
+  claims for them to this session's app. The bulletin one carries `signs: true`:
+  the host signs its Bulletin stores (`TransactionStorage.store`) with it
+  itself, and the audit credits a store it signs to this session's app.
+- Product-account read (`productAccountRead`, declared by every truAPI CLI
+  host): `session.account(index, { source: "host" })` asks the host which
+  account it gives the app (`{ address, publicKey, productId,
+  derivationIndex, source: "host" }`) with a `scriptAccountRead` on the
+  session's wallet, made at every call (nothing cached; an identity swap reads
+  the new identity's). The host contract kit asks this way to check the host
+  against the derivation; the capability probe checks it against the account
+  the probe product itself sees.
+- Whether the product connected (`session.connection()`, `src/host-link.ts`):
+  the CLI host emits no such event, so the adapter watches the page's
+  WebSocket to the host's own port (the bridge script opens it; the browser
+  port's `onWebSocket`) and counts frames in both directions. Connected means
+  the app called the host and the host answered; otherwise the detail says
+  what was seen ("the page never loaded the host's bridge script (…): its
+  document has no such script" when the page was not loaded through the
+  lab's proxy, which adds the script since backlog item 64; "the page's
+  document names the host's bridge script (…) and the script did not run"
+  when the app's own Content-Security-Policy or the network refused it; "the
+  page opened a connection to the host, and the app has not called the host
+  (0 messages sent)"). The default session's readiness default rests on it.
+- The signing record (`session.approvals.signing()`, backlog item 63): the
+  signing requests among the host's own approvals transcript
+  (`TRUAPI_APPROVALS_LOG`, upstream), each `{ approved, payload, action }`
+  with `payload` `transaction` (`sign payload`, `create transaction`),
+  `message` (`sign raw data`) or `unknown`. The runtime uses it to settle a
+  failed step without reading the app's page.
+- Public networks (backlog A4, 3 October 2026; `tests/public-network.test.ts`): a routing whose chains and services
+  are all public (with its `publicRoutes` opt-in) runs the host on its own endpoints for `routes.network`: no routing
+  file, no `HOST_CLI_LOCAL_NETWORK_CONFIG` (the `local-network` patch then keeps the host's live behaviour) and no
+  `local-network-check`; `capabilities.localNetwork` is false and the session evidence and `session.json` record
+  `routing: "public"`. A routing that mixes loopback and public endpoints is refused when the host is created
+  (`MixedEndpointsError`, naming both sides), and so is `denyByDefault` on a public network (its sandbox confines the
+  host to this machine).
+- Deny-by-default networking (`denyByDefault`, opt-in; `denyByDefaultNetwork`
+  is declared only when the platform's process sandbox is supported, never
+  falsely: docs/verification/2026-09-25-cli-deny.md). Two layers, both
+  gated by the one option: the native `signing-host` process runs under the
+  platform's `ProcessSandbox` (macOS: `sandbox-exec`, a narrow profile that
+  denies `network-outbound` except loopback and leaves every other operation
+  as it would otherwise be; Linux: an unprivileged user and network namespace
+  of its own, where only its routing's loopback ports and its frame port are
+  forwarded (`hostSandboxSpec`, docs/verification/2026-09-25-linux-sandbox.md),
+  declared only when the machine's probe proves user namespaces usable;
+  Windows: unsupported), and the session's page opens in its own `BrowserContext`
+  routed by the domain's `NetworkPolicy` (the technique
+  `adapters/host/truapi-wasm` already uses), exposing
+  `session.network.blocked()`. That context holds the app only (the native
+  process connects to the chains), so its policy has `hostOnlyRoutes`: the
+  app's own request to a chain or service route is denied and reported, and
+  the app reaches its chains through the host alone (backlog 42, the kit's
+  `hostile-chain-bypass` contract). Routing never sees a dedicated worker's
+  sockets, so since backlog 92 a host given `chainGates` (the composition
+  root's, or a targets module's) routes its native process through origin
+  gates in front of the local nodes, admitting no browser origin (the native
+  process sends none): a worker that opens a node is reset and reported in
+  `session.network.blocked()` too.
+  `prepare()` refuses to start (throws) rather
+  than run an explicit `denyByDefault` opt-in unprotected when the sandbox is
+  unsupported. The native process's own denials are enforced but not
+  exactly reported (macOS redacts the destination of a `network-outbound`
+  denial for this profile; in a Linux namespace a denied connection has no
+  route and nothing records it), so only the browser layer's denials carry an
+  exact URL; `evidence.network.nativeProcessLayer` is the sandbox's own
+  account (`ProcessSandbox.mechanism`). `identityImport` is declared `false` under `denyByDefaultNetwork`
+  (the swap restarts the native host on a new port, which the fixed
+  browser-context policy was not built for; not proven).
+- Per-identity conditions (backlog 31; `capabilities.conditions`, declared for a local routing when the system carries
+  `conditionedLinks`). The native host's connections never go through a page, so each session opens a conditioned link
+  of its own for every endpoint of its routing file (People, Asset Hub, Bulletin, the identity backend;
+  `conditioned-routing.ts`, ports from the host's `ports` range) and the routing file (and the Linux sandbox's forwarded
+  ports) names the links; they close with the session and stay across an identity swap. `session.conditions` applies a
+  network condition to the links and to the session's page (`BrowserTab.conditions`, asked for before the first
+  navigation), and a CPU slowdown to the page only (the native host runs at full speed). `session.localLinks()` is the
+  app's origin and its bridge to the host, read again after a swap moves it: offline, the app keeps its host, and
+  neither reaches the chain. A browser without page conditions gives no `session.conditions` (unsupported). The app's
+  origin is read once without naming a bridge: naming one again makes an app proxy rotate its bridge route. Links open
+  for a session asked for conditions (the scenario's plan asks for the identities its condition sentences name);
+  `conditionLinks: "always"` opens them for every session, so an identity made in the lab window can be conditioned.
+
+Conformance: `product-lab host verify --host truapi-cli --config tools/verify/src/truapi-cli.ts`
+(and `--host truapi-cli-deny` / `--host truapi-cli-deny-leaky`, the deny-by-default target and its
+negative control)
+(the targets moved from this adapter's `src/verify.ts` to `tools/verify` in refactor step 7: they
+compose this host with the relay-less People node, the WASM host, Playwright and the Node system
+adapters, which an adapter never imports)
+with optional `PRODUCT_LAB_HOST_BIN` (absolute; otherwise the cached host; with a resolved `host:truapi-cli` in a lab's
+versions the factory refuses it rather than ignore it,
+`PRODUCT_LAB_CACHE_DIR`), `PRODUCT_LAB_HOST_PATCHES`
+(`local-network[,navigation-events,request-decisions,chain-reconnect]`, default the lock's set), the running lab's People chain (run from a lab: `--environment`, the lab window's Hostile apps), else `PRODUCT_LAB_PEOPLE_WS` or
+`PRODUCT_LAB_BASELINE` (fast baseline), optional `PRODUCT_LAB_PORT_BASE` (default: the first free block from 40000),
+`PRODUCT_LAB_STATE_DIR`, `PRODUCT_LAB_WALLETS` (three comma-separated testnet
+mnemonics; otherwise fresh ones kept in memory). The opt-in live tests
+`tools/verify/tests/truapi-cli-live-sessions.test.ts` and
+`tools/verify/tests/truapi-cli-live-bridge.test.ts` (moved there in refactor
+step 1, because they need the Node system adapters) run with
+`PRODUCT_LAB_CLI_LIVE=1` and the same inputs.
+
+## Acquisition: `acquireTruapiHost` and `product-lab host fetch`
+
+`acquire.ts` resolves and caches hosts.
+It chooses the source
+(`acquireTruapiHost`, `findPatched`, `unpinnedHost`, `obtainHost`) and exports every acquisition name; the
+pieces live beside it: `host-records.ts` (what an acquisition produces), `host-lock.ts` (`host.lock.json` and patch
+sets), `official-release.ts` (the release archive download), `host-cache.ts` (the cache, its lock and the
+verified install) and `host-verification.ts` (checksums, attestation, extraction and the version check):
+
+Archive listing/extraction, binary version checks and GitHub attestation checks use the injected `CommandRunner` port. Each one-shot command has an explicit timeout (15 to 120 seconds), and archive listings retain their previous 16 MiB output cap while attestation JSON retains 32 MiB. `HostToolContext.commands` supplies the runner for `host fetch`; host sessions and the provisioner forward their system runner. A cached host needs no command, while downloading and installing one requires the runner. Aborting a fetch reaches these commands as well as the download.
+
+- **Official releases** (`version: "locked"` or `"x.y.z"`, no patches): the
+  `@parity/truapi@<version>` release archive `truapi-host-<version>-<target>.tar.gz`
+  for `aarch64-apple-darwin`, `x86_64-unknown-linux-musl` or
+  `aarch64-unknown-linux-musl` (anything else fails with the build command).
+  The download must match the published `.sha256`, and for the locked version
+  also the digest in `host.lock.json`; its GitHub build attestation is checked
+  with `gh attestation verify --repo paritytech/host-rust-core --signer-workflow
+  paritytech/host-rust-core/.github/workflows/release-cli.yml`
+  (`attestation: "when-available"` by default: if `gh` is installed and
+  signed in the check must pass, otherwise the record says why it was not
+  checked; `"required"` fails without it; `"skip"`). Archives with absolute
+  paths, `..` or links are refused, and the binary must print
+  `truapi-host <version>`. Up to 0.25.0 official builds lack `local-network`, so they serve
+  the unpatched compatibility row and live networks, not local lab sessions; a release that carries it is declared in
+  the lock's `official.provides` (below).
+- **Patched hosts** (`patches: [...]`, keyed by base commit and patch-set
+  hash): looked up in the cache only, a framework-CI build (`+lab.<hash>`)
+  before a local build (`+local.<hash>`). Never downloaded from anywhere else.
+- **Cache**: `$PRODUCT_LAB_CACHE_DIR`, else `$XDG_CACHE_HOME/product-lab`, else
+  `~/.cache/product-lab`; entries `hosts/truapi-cli/<label>/{archive/,bin/,acquired.json}`,
+  installed atomically under a per-entry lock (a lock that cannot be created for another reason than being held,
+  such as a cache folder that cannot be written, fails at once). The binary is re-hashed on every
+  use; a modified cache entry is refused.
+
+- **A resolved version** (Phase 6, `src/resolved-host.ts`): `resolvedHostVersion(entry, target)` reads the
+  `host:truapi-cli` entry of `lab.lock.json` or of a run's `VersionResolution` (an official
+  `paritytech/host-rust-core` release `@parity/truapi@<x.y.z>` with an `archive:<target>` sha256; a git
+  or other-repository source, a mismatched tag or a missing digest for this platform is refused), and
+  `acquireTruapiHost({ resolved })` (or `obtainHost`, through the host's `host` selection) uses it instead
+  of `host.lock.json`, which is then not read. The download, and a cached entry before it is used, must
+  have exactly that sha256; the check runs before anything from the archive runs (install runs its
+  `--version`). `acquired.json` records the digest and where it came from (`checksums.lockSource`). A
+  resolved version with `patches` or `version` is refused.
+  Since refactor step 8 the run's resolution reaches the factory as `deps.versions` (the host registry
+  passes it to every host it creates): `TruapiCliHostFactory.withResolution` turns a `host:truapi-cli`
+  entry into `host.resolved` and refuses a `hostBin`. A resolved version is an official release: with declared
+  patches the acquisition refuses it (patched hosts are found by patch set), and without them (a product's, whose
+  patches the factory drops) a local environment needs `localNetwork` from it. Only the locked release with the lock's
+  digest for this target provides what `official.provides` lists; any other resolved release provides nothing, so a
+  local session on it is refused by name until the lock names that release and what it provides.
+
+`host.lock.json` is the interim lock until Phase 6 (`lab.lock.json`):
+`official.version`, per-target archive digests and `official.provides` (optional), and `patched` (repository,
+base, crate version, patch names, patch-set hash, and later CI archive
+digests). Update it when bumping the official version or changing a patch;
+`tests/acquire.test.ts` fails when the patch-set hash no longer matches the
+manifest.
+
+### What a release provides: `official.provides` (16 October 2026)
+
+An official host's capabilities come from what its release carries, not from patch names (`src/official-behaviours.ts`).
+`official.provides` lists the behaviours the locked release has taken upstream, by the names the patches' `adds` use
+(`localNetwork`, `navigationEvents`, `perRequestApproval`, `chainReconnect`, …; `readHostLock`
+refuses any other name or a repeat, `productAccountRead` included since its patch was retired on 21 October 2026: every
+host declares it). The official host (no patches, no `hostBin`) declares `navigationEvents`
+and `perRequestApproval` when the release provides them, and a local environment needs `localNetwork`
+from either source: the `local-network` patch on a patched host, or `provides` on the official release
+(`officialProvides`). `provides` belongs to the locked release only: an explicit other version, a resolved version with
+another version or digest, a suite row's route and a binary given by path provide nothing beyond their patches. The
+patched path also inherits `patched.provides` for exactly the locked base. A binary given by path inherits neither
+entry. Absent or empty provides means nothing, as for releases through 0.25.0.
+
+What a release provides is checked, never only claimed: `checkHost` runs the release's `local-network-check` before a
+local session, the conformance kit (`product-lab host verify`) fails a declared capability whose contract fails, and the
+behaviour probes ([capability probes](#capability-probes-audit-g4); `host rebase-check` runs them on a cached official
+archive) show each behaviour as `provides`, `absent` or `blocked`. `product-lab host fetch --list` reports the locked
+release (`locked`: its version, `provides` and whether its archive, with the lock's digest, is cached).
+
+A release that carries host-rust-core #1162 (navigation log) and #1166 (local-network routing) needs only a move of the lock
+to it (done for 0.26.0): its `version`, `release`, the per-target `archives` digests and
+`"provides": ["localNetwork", "navigationEvents"]`, with `product-lab host rebase-check --to
+<version> --probe-ports <range>` showing those two as `provides` first (and `productAccountRead`, the `--script` read).
+#1170 (product account reads) is no longer needed: the lab reads the account with `signing-host --script`. The patches it carries then become retirement
+candidates (`patches/truapi-host/manifest.json`, `retireWhen`).
+
+```sh
+product-lab host fetch                         # the locked official release
+product-lab host fetch --version 0.18.0        # an explicit release
+product-lab host fetch --patches local-network,navigation-events,request-decisions,chain-reconnect --offline   # patched: cache lookup
+product-lab host fetch --list                  # cached hosts with provenance
+```
+
+## Local patched build: `buildPatchedHost` and `product-lab host build`
+
+`product-lab host build [--patches <a,b,…>] [--workdir <new dir>] [--repo <host-rust-core clone>] [--base <commit>]` (default patches: the lock's set, `DEFAULT_BUILD_PATCHES`)
+creates its own checkout, applies the patches (each patch's variant written for `--base` when the manifest has one,
+its `rebased` list; otherwise the lock-base files with a 3-way merge and a warning), runs codegen, `make cli-dist`
+and the CLI crate tests, caches `truapi-host-<version>+local.<hash>` and
+deletes the checkout and target directory. The build log is kept under
+`<cache>/hosts/truapi-cli/build-logs/`.
+The composition root supplies `CommandRunner` for tool checks, git operations, build steps and archive installation. Every command has a timeout: 30 seconds for tool checks, up to 30 minutes for clone/codegen/tests, and 60 minutes for `cli-dist`. The build steps append stdout and stderr directly to the retained log file, so large builds do not hit the captured-output cap. Aborting the build kills a running command's process group; checkout cleanup still runs without the aborted signal. Archive listing and extraction remain bounded at 2 minutes.
+
+Native signing evidence is included in the current three-patch 0.26.0 default:
+
+```sh
+product-lab host build --patches request-decisions,chain-reconnect,signature-evidence
+```
+
+Select that same set in the CLI host configuration (`hosts["truapi-cli"].options` in a lab definition,
+or the options passed to `truapiCliHost`):
+
+```ts
+patches: ["request-decisions", "chain-reconnect", "signature-evidence"]
+```
+
+Ordinary `host build`, the lock and default cached hosts select three 0.26.0 patches, including `signature-evidence`.
+The base carries Bulletin lookup fix #1017, so no backport is needed. Historical four-patch 0.25.0 binaries lack the
+signature startup marker and report missing signing coverage. Selecting `signature-evidence` uses a separate cache key; an explicit binary override still
+requires an actual marker and records its local build provenance. This does not imply an official archive with it.
+
+## Patch rebase check: `product-lab host rebase-check` (audit G3 and G4)
+
+`product-lab host rebase-check --to <latest|x.y.z|@parity/truapi@x.y.z|commit> [--patch-base <commit|x.y.z>] [--repo <clone>] [--patches <a,b>] [--isolated] [--probe-ports <from>-<to>] [--cache <dir>] [--json]`
+(`TruapiCliHostFactory.checkPatches`, `src/rebase-check.ts`) checks whether this adapter's
+`patches/truapi-host/` patches still apply to another host-rust-core commit. It uses git only: no `npm ci`,
+codegen or cargo. `--patch-base` chooses which written set is checked: the variants written for that commit
+(a full commit, or the `baseVersion` a `rebased` item records, for example `0.23.0`); default: the lock's base when
+every selected patch is written for it, otherwise the top-level files (`checkPatchesFrom(manifest, dir, names,
+patchBase)`; a selected patch without a variant for it exits 2).
+
+- **Target.** A release (`latest`, `x.y.z`, `@parity/truapi@x.y.z`) is resolved by the runtime's
+  `UpstreamResolver` (`@product-lab/ports/host`). The composition root backs it with the GitHub version
+  adapter (`composition/src/host-tool-services.ts`), so this adapter never imports that adapter. Only
+  the `@parity/truapi@` family counts. Other packages' tags (`@parity/truapi-provider@…`,
+  `@parity/truapi-host@…`), prereleases and drafts are refused or skipped, and the resolver's answer
+  is checked again. A 40-character commit is used as given.
+- **Read-only input.** `--repo` is only read (`rev-parse`, `cat-file`). The target and the patch base
+  are fetched from it into an owned scratch repository, and upload-pack's `allowAnySHA1InWant` goes on
+  the command line, never into the clone's config. Every apply happens in that scratch repository,
+  which is removed afterwards. Without `--repo`, the source is a bare mirror at
+  `<cache>/upstream/host-rust-core.git`, fetched `--depth=1` by commit (anonymous; the only network step).
+- **Commands.** Every git command goes through the injected `CommandRunner` (`@product-lab/ports/system`;
+  `NodeCommandRunner` from composition). Each command is bounded (120 s; 600 s for a mirror fetch), gets
+  the caller's `AbortSignal`, and runs with no prompt and no global or system git config.
+- **Priming and chain.** First, every patch is applied on its recorded base (`manifest.base`). A
+  patch that fails there is invalid input, and this pass stores the intermediate blobs, so a 3-way
+  apply of a chained patch has its preimages. Then the patches are applied to the target in manifest
+  order (`appliesAfter` first). Each outcome is one of:
+  - `applied`;
+  - `applied-3way`, with `needsRefresh: true` ("needs refresh");
+  - `upstreamed`, when the reverse applies;
+  - `conflicted`, which names the files and failed hunk lines, then restores the tree so independent
+    patches still run;
+  - `skipped`, when an `appliesAfter` dependency did not apply.
+
+  `--isolated` adds each patch's result alone on the target, for information only: the chain result
+  and exit code stand.
+- **Exit code.** 0 when every patch applies or is upstreamed (a 3-way apply is flagged, not failed).
+  1 on any conflict or skip. 2 when nothing was checked: a bad `--to`, another tag family, an unknown
+  ref, a release that cannot be resolved, a digest mismatch, an unknown `appliesAfter`, a cycle, or a
+  patch that fails on its own base.
+- **Retirement rows (G4).** Each patch gets:
+  - `upstreamed`: an exact reverse-apply;
+  - typed `provides` hints (`providesHint`), each `env`, `command`, `symbol` or `prose`, with the string searched for in `search`. The target
+    tree is searched for the first three with `git grep`. Hints are never proof.
+  - for a patch that adds `localNetwork`, the official build's `local-network-check`
+    (`probeOfficialLocalNetwork`). It starts no session and uses the same acceptance as `checkHost`;
+  - `behaviour`: the official build's behavioural probe for the capability the patch adds
+    ([capability probes](#capability-probes-audit-g4), `officialBehaviour`), run on a cached, digest-checked official
+    archive of the target release (`product-lab host fetch --version <x.y.z>` caches one) under the runtime's process
+    sandbox, claiming nothing: `provides` (with verdict `pass`), `absent` or `blocked` (verdict `unsupported`), or
+    `untested` with the reason (a commit target, an uncached archive, no Bun);
+  - `verdict`: a retirement candidate only when the official build shows the behaviour. An exact upstreaming, the
+    hints or the check's echo alone keep the patch (`keep (upstreamed exactly; the official build does not show the
+    behaviour)`, `keep (the official build lacks the behaviour)`, `keep (hints only)`, `keep`).
+
+Tests: `tests/rebase-check.test.ts` (local git fixtures: clean, 3-way, conflict with a skipped dependent
+and an applied independent patch, `--isolated`, upstreamed, priming, invalid input, the input `.git`
+hashed before and after, the mirror, abort, the official probe against stand-in binaries, the behaviour rows and
+their verdicts, and a `rebased` set chosen by `--patch-base`) and `tests/rebase-check-factory.test.ts` (reading `--to`,
+the tag family, exit 2, the resolver's answer checked, `--patch-base`, `--probe-ports`, an uncached official build).
+
+Qualified on a fresh clone of the real upstream (26 September 2026),
+with `--repo`, `--isolated` and `--json`, three
+passes with identical results; the clone's HEAD, refs, status and every `.git` file's hash and times were unchanged:
+
+| `--to` | Commit | Exit | Result |
+| --- | --- | --- | --- |
+| the lock's base | `c7449d3a` | 0 | all five patches apply |
+| `0.19.0`, `@parity/truapi@0.20.0` | `bb436d08`, `9149506d` | 1 | `request-decisions` conflicts (`rust/crates/truapi-host-cli/src/main.rs:26`); the two after it are skipped |
+| `latest` (`@parity/truapi@0.21.0`) and upstream `main` | `b9ee30aa`, `1e735eca` | 1 | `local-network` conflicts (`main.rs:565`); the four after it are skipped |
+
+Requalified on 29 September 2026 with the three written sets (`--patch-base` default, `0.21.0` and `0.23.0`), a clone
+of upstream fetched that day (main `ab647164`), `--isolated`, eight targets:
+
+| `--to` | Commit | Top-level set (base `c7449d3a`) | 0.21.0 set (base `b9ee30aa`, the lock from 29 September to 1 October) | 0.23.0 set (base `37e2d9fe`) |
+| --- | --- | --- | --- | --- |
+| `c7449d3a` | `c7449d3a` | exit 0, all five apply | exit 1, `local-network` conflicts (`main.rs:592`) | exit 1, `local-network` conflicts (`main.rs:20`) |
+| `0.19.0`, `@parity/truapi@0.20.0` | `bb436d08`, `9149506d` | exit 1, `request-decisions` conflicts (`main.rs:26`) | exit 1, `local-network` conflicts (`main.rs:592`) | exit 1, `local-network` conflicts (`main.rs:20`) |
+| `0.21.0` | `b9ee30aa` | exit 1, `local-network` conflicts (`main.rs:565`) | exit 0, all five apply | exit 1, `local-network` 3-way; `chain-reconnect` conflicts (`chain_runtime.rs` is not in `truapi` yet) |
+| `0.22.0` | `0a6b2741` | exit 1, `local-network` conflicts (`main.rs:19`) | exit 1, `local-network` 3-way; `chain-reconnect` conflicts (`chain_runtime.rs` moved) | exit 0, all five apply |
+| `0.23.0`, `latest` | `37e2d9fe` | exit 1, `local-network` conflicts (`main.rs:19`) | as for `0.22.0` | exit 0, all five apply |
+| upstream `main` | `ab647164` | exit 1, `local-network` conflicts (`main.rs:19`) | as for `0.22.0` | exit 0, all five apply |
+
+The 0.21.0 set exists because 0.22.0 changed the product wire format: upstream #17 added `contacts` to the v01
+`ProductAccountTxPayload`, so an app built with `@parity/product-sdk-host` 0.21.0 (the examples') fails
+`createTransaction` with `MalformedFrame` on a 0.22.0 or 0.23.0 host. A build of the 0.21.0 set passed the Notes
+relay-less journey; a build of the 0.23.0 set did not, for that reason only. The lock moved to the 0.21.0 set, and on 1 October 2026 to the 0.23.0 set, when the product SDK moved to 0.24.0, which needs a 0.23.0 host.
+
+With `--probe-ports` and the official archives cached, the rows for 0.23.0 and 0.20.0 carry the official builds'
+behaviour: every patch is kept; the official build lacks `localNetwork`, `navigationEvents`, `perRequestApproval` and
+`productAccountRead` (observed absent) and `chainReconnect` could not be run (blocked: it never connected to the
+loopback endpoint), all `unsupported`. Each run removed its scratch repository, but the empty parent
+`$TMPDIR/product-lab-rebase-check` stays.
+
+## A newer release in a suite row: `routeRelease` (backlog 27)
+
+A nightly matrix row that resolves `host:truapi-cli` from a version source (`latest-release`, a version) runs it the
+way `TruapiCliHostFactory.routeRelease` (`src/route-release.ts`) decides, before the row's run starts:
+
+1. What the lab needs: each capability its `patches` add (`adds` in `patches/truapi-host/manifest.json`); when the
+   lab's patches are part of host.lock.json's set, the whole set (the locked host carries it).
+2. The published archive is downloaded, its sha256 checked against the resolution's `archive:<target>` digest, and
+   probed for those capabilities (`probeHostCapabilities`, claiming nothing).
+3. It does everything: **official**. Otherwise the patches for what it lacks, with the patches they apply after, are
+   checked onto the tag's commit (`checkPatchesOnto`, the cache mirror). They apply: **patched**, built locally
+   (`buildPatchedHost` on that commit, cached by the commit and the patch set; never published) unless a build of
+   exactly that base and patch set is cached, or the request only decides (a dry run). They do not: **unsupported**,
+   naming the patch and its files (`decideHostRoute`, `@product-lab/domain/versions`).
+
+The suite hands the route to the row's run in `PRODUCT_LAB_HOST_ROUTE` (the composition root passes it as the factory's
+`routeFile`): `create()` sets `host.routed` and the actual selected patches. `acquireTruapiHost` takes the official archive
+by its digest (no lab patches claimed) or exactly the routed build from the cache
+(`findRoutedBuild`; missing: the `host build` command). A host binary given by path (`hostBin`,
+`PRODUCT_LAB_HOST_BIN`) is refused with a route. Tests: `tests/route-release.test.ts` (steps faked: the order, a cached
+build, deciding only, no digest, an unreachable release, a conflict, a build with another patch set, the route file,
+the cache lookup).
+
+## Capability probes (audit G4)
+
+`probeHostCapabilities({ binary, claimed, commands, sandbox?, ports?, workParent })` (`src/capability-probes.ts`) checks
+what a truapi-host binary does for each capability the host patches add, from outside, with no browser and no chain:
+
+| Capability (patch) | What the probe does | Observed `provides` when |
+| --- | --- | --- |
+| `localNetwork` (`local-network`) | `local-network-check` with a loopback routing file; then `identity-check` with that routing and a loopback Asset Hub stub (`src/probe-stub.ts`) | the check echoes the complete routing and the stub receives JSON-RPC requests |
+| `navigationEvents` (`navigation-events`) | one `signing-host --serve` session (no `--auto-accept`) and a product run by the host's own `runner.js` with Bun (`src/probe-script.ts`): `system.navigateTo` | the URL appears in `TRUAPI_NAVIGATIONS_LOG` |
+| `perRequestApproval` (`request-decisions`) | the product's two `signing.signRaw` calls; the probe answers permissions once, the first signature `n`, the second `y` | both waited in `TRUAPI_DECISIONS_DIR`, the first failed and the second returned a signature |
+| `productAccountRead` (no patch: the `--script` read, `script-account-read`) | after the product read its own account (`account.getAccount`), the lab's `scriptAccountRead` on the session's wallet, beside the serving host, with the same binary, routing, sandbox and Bun | the read answers the key the product sees; a host without `--script` is `absent` |
+| `chainReconnect` (`chain-reconnect`) | the product's `chain.followHeadSubscribe` through the loopback People stub, which severs the link 1.5 s after `initialized` | the follow ends after the cut, by the stub's and the product's clocks (a host without the patch keeps it open); the follow waits up to 30 s for `initialized`, so a loaded machine's slow start is not `blocked` (backlog 238) |
+
+Sessions start only when the host routes itself to the stubs (`localNetwork` observed) or under the platform's process
+sandbox (loopback only; `HostToolContext.sandbox`); otherwise they are `blocked`, so an official build never reaches a
+public network. The verdict per capability (`probeVerdict`): observed is `pass`; `absent` or `blocked` is `fail` when
+the host claims the capability and `unsupported` when it does not; `untested` stays `untested`. `host rebase-check` runs
+it on the target's official build (claiming nothing); `node --import tsx tools/verify/src/host-probes.ts --binary <abs>
+--claim <patches|all|none> [--ports <from>-<to>]` runs it on any binary (exit 1 when a claim fails). Tests:
+`tests/capability-probes.test.ts` (stand-in host, Bun and runner in `tests/fixtures/probe/`: every behaviour, the
+official case with and without a sandbox, false claims, a host never ready, no runner; the stub; the ports).
+
+## Identity provisioner: `truapiCliProvisioner`
+
+`truapiCliProvisioner({ routes, dataRoot, patches?, host?, usernamePrefix?, system })`
+implements the core `IdentityProvisioner` port (design, section 9). It runs
+`truapi-host signing-host --serve --auto-accept --network <net> --base-path <dir>/host --session <prefix> [--lite-username-prefix <prefix>]`
+with the environment's loopback routing (`routes`, the domain's `HostNetworkRoutes`; checked with `local-network-check`
+first; inherited host variables removed; update check off), waits for
+`Signing host ready` (onboarding took 44-57 s on the local fork), stops the
+process and reads the identity the CLI stored. Each identity gets its own
+`<dataRoot>/identities/<actor>/<time>/` directory with the CLI's account store
+(mnemonic, mode 0600), the routing file, the process log and a non-secret
+`provisioned.json`; `readProvisionedIdentity(dir)` reopens it.
+
+On a public network (4 October 2026): `truapiCliProvisioner({ network: { preset }, dataRoot, usernamePrefix, system })`
+instead of `routes` onboards with the CLI's own preset (`--network paseo-next-v2` or `previewnet`): the network's real
+identity backend and chains, no routing file, no `local-network-check` and no local-network patch needed. Exactly one
+of `routes` and `network` is accepted. `provisioned.json` names the preset instead of the routes and keeps the path of
+the CLI's log (`log`). The composition root's default session uses it for a public target that declares
+`newIdentities` (`composition/src/public-identities.ts`).
+
+`--lite-username-prefix` is passed only to a host whose `signing-host --help` offers it (`signingHostFlags`,
+`src/signing-host-flags.ts`, read once per binary sha256): host-rust-core #1124 removed it after 0.23.0, and there
+`--session <prefix>` alone names the username base. Such a host still reports version 0.23.0, so the flags are read,
+not inferred from the version. `provisioned.json` records the flags used (`sessionArgs`).
+
+Host state across host-rust-core #991 (SQLite core storage, after 0.23.0) is reused as it is: #991 adds an empty
+`core.sqlite3` in the signing profile's directory beside the unchanged file storage and moves no data (its migration
+list is empty at `77474305`). Seen live: a 0.23.0-written identity served by a newer host keeps its product account
+and gains only `core.sqlite3`, and 0.23.0 serves it again unchanged.
+When upstream migrations start moving data
+into that database, a downgrade could lose it: the lab should then record which host last wrote a state directory
+and refuse an older one.
+
+- The result is a `ProvisionedIdentity` (16-byte entropy, `<prefix>.<n>` lite
+  username, identity address) that both hosts import: `truapiCliHost` signs as
+  its entropy and resolves the username from DotNS; the WASM host takes
+  `{ entropy, liteUsername }`. `cli` names the CLI session for direct reuse.
+- **Auto mode cannot adopt chosen entropy**: this provisioner runs `signing-host`,
+  which generates its mnemonic (`Mnemonic::generate(12)`). It keeps
+  `acceptsEntropy: false` and refuses `entropy`, naming the separate opt-in
+  `truapiCliAttestProvisioner` below. Existing callers and defaults are unchanged.
+- Prefixes must be at least 6 lowercase ASCII letters (the identity backend's
+  rule); the default is the actor id's letters, padded with `lab`.
+
+`readTruapiCliIdentity({ basePath, network })` reads the identity the CLI stored (moved here from
+host-truapi-wasm in step 7; the WASM host imports a `ProvisionedIdentity`, not the CLI's store).
+
+Verification targets for provisioned identities:
+`truapi-cli-attached` and `truapi-wasm-attached` in `tools/verify/src/truapi-cli.ts`, with
+`PRODUCT_LAB_ATTACH_ROUTES` (a complete loopback routing file) and one of
+`PRODUCT_LAB_PROVISIONED=<provisioner dir>`, `PRODUCT_LAB_IMPORT_CLI_BASE`, or
+`PRODUCT_LAB_PROVISION=1` with `PRODUCT_LAB_PROVISION_DIR` (provisions a
+throwaway lite person now). Run one contract with `--only identity`.
+
+An example integration's hosted actor connection (which opens that
+product's own pages) stays in the example.
+
+## The host's own log, opt-in (backlog 175)
+
+A host process inherits no `RUST_LOG` (`ISOLATED` in `src/host-process.ts`), so a developer's setting never changes a
+lab run. To see what the host itself did, give it one: the `rustLog` option (a tracing filter, for example
+`info,subxt=debug`, which shows its chain client's block subscriptions), or `PRODUCT_LAB_HOST_RUST_LOG` for every truAPI
+CLI host of a run (`HOST_RUST_LOG_VARIABLE`, read through the system's `environment`; the option wins). The host writes
+it to its process log. Unset (the default), nothing changes. `RUST_LOG` takes precedence over `logLevel` in the host.
+Found with backlog 175, where the host lost the Bulletin block its upload went into and its log could not say why.
+`tests/host.test.ts`: the variable and the
+option (which wins), and the control that an unset variable or an inherited `RUST_LOG` gives the host none; each fails
+with its line removed.
+
+## The host's TMPDIR (backlog 93)
+
+`truapi-host` binds its frame server's Unix socket at `<TMPDIR>/truapi-host-<6>/frames.sock`. A socket path of
+`sun_path`'s size or more (104 bytes on macOS and the BSDs, 108 on Linux) cannot be bound, and the host exits before it
+is ready (`frame server failed to bind … path must be shorter than SUN_LEN`; seen 4 October 2026 with a 117-byte path).
+`src/host-temp-dir.ts`: when the inherited TMPDIR
+is too long (`framesSocketFits`), the provisioning host and each session host get `TMPDIR=/tmp/pl-host-<12 hex of the
+process's directory>` (0700), removed when the process stops; the next start of the same process removes one a crashed
+run left. The provisioner logs the reason; a session records it as `tmpdir` in its `session.json`. A TMPDIR that fits
+changes nothing; the deny-by-default sandbox restricts the network only, so the directory is reachable. The same check
+for a fork's validators is env-engine's `src/engine/node-temp-dir.ts`. `tests/host-temp-dir.test.ts` (both sides of the
+limit), `tests/provision.test.ts` and `tests/host.test.ts` (the processes' environment); each fails with the override
+removed.
+
+## Package
+
+| | |
+| --- | --- |
+| Nx project | `host-truapi-cli` |
+| Tags | `scope:provider`, `type:adapter` |
+| Exports | `.` (`src/index.ts`: launch, patches (`resolveHostPatch`, `readHostPatchManifest`, `HOST_PATCH_DIRECTORY`, `patchVariant`, `patchBases`, `baseForVersion`, `NoPatchForBaseError`), the rebase check (`checkPatchesFrom`, `checkPatchesOnto`, `probeOfficialLocalNetwork`, `providesHint`, `rebaseCheckText`, `retirementBehaviour`, `RebaseCheckInputError`, `TRUAPI_HOST_UPSTREAM` and their types), the capability probes (`probeHostCapabilities`, `probeVerdict`, `PROBED_CAPABILITIES`, `PROBE_PRODUCT`, `probeScript`, `probeLines`, `PROBE_MARKER`, `startChainStub`, `freePorts`, `readFrames` and their types), navigation, acquisition, build, provisioner, `readTruapiCliIdentity`, the routing file (`truapiCliNetworkConfig`, `routesFromTruapiCliNetworkConfig`, `TruapiCliNetworkConfig`, `TruapiCliChainRoute`), `truapiCliHost`, `createTruapiCliHost`, `TruapiCliHostFactory`, the official release's behaviours (`lockedRelease`, `officialProvides`, `knownBehaviours`, `behaviourUpstream`, `describeBehaviour`, `productCliHostDetail`, `productCliHostLocalGap`, `releaseTakesLocalEndpoints`, `LockedRelease`, `OfficialSelection`), `TRUAPI_CLI_KIND`, `TRUAPI_CLI_PATCHES`, `truapiCliHostOptionsSchema`, `resolvedHostVersion`, `TRUAPI_CLI_COMPONENT`, `ResolvedHostVersion`, the release route (`routeTruapiRelease`, `hostNeeds`, `routedPatchset`, `findRoutedBuild`, `readRouteSelection`, `RouteReleaseSteps`, `TruapiRouteSelection`)). The `./verify` subpath was removed in step 7 |
+| Implements | `HostAdapterFactory` (`TruapiCliHostFactory`, refactor step 5; `routeRelease` for a suite row's resolved release, backlog 27; `checkPatches` for `host rebase-check`, using the tool context's `CommandRunner`, `UpstreamResolver` and `ProcessSandbox`) and `HostProvider` (step 7 part b), both `@product-lab/ports/host`; `IdentityProvisioner` (`@product-lab/ports/identity`). Uses the domain's `HostNetworkRoutes` and, under `denyByDefault`, `NetworkPolicy` (`network-guard.ts`) and the ports' `ProcessSandbox` |
+| Depends on | `domain` (host helpers, navigation, identity entropy, `parseAdapterOptions`), `ports`, `zod`, `@polkadot-labs/hdkd-helpers`. No other adapter: the 13 `adapter-imports` and 1 `deep-imports` warnings (env-engine, env-relayless, host-truapi-wasm) were removed in step 7 part a |
+| Used by | `composition/` (constructs it), `examples/notes` and another example, `tools/verify` |
+
+`product-lab host fetch`, `host build` and `host rebase-check` offer this adapter's `fetch`,
+`build` and `checkPatches` (acquisition, local build and the rebase check, above) through the composition root,
+which constructs `TruapiCliHostFactory` (`HOST_TOOL_KINDS` in
+`@product-lab/composition`, refactor step 8). Until step 8 the CLI loaded
+`src/tools.ts` from this package by path; that module is gone.
+
+Tests: `bunx nx run host-truapi-cli:test` (no chain; a stand-in host binary, `tests/fixtures/fake-truapi-host.mjs`, on
+OS-assigned loopback ports from `tests/system-doubles.ts`, so concurrent gates cannot collide; `tests/acquire.test.ts`
+serves its stand-in release from an OS-assigned port with every wait bounded, and
+fails when the patch-set hash no longer matches `host.lock.json`; `tests/deny-by-default.test.ts` checks the `denyByDefault` wiring
+against a fake `ProcessSandbox` and browser context, including the ports it asks a sandbox to forward, and
+`tests/sandbox-spec.test.ts` the ports themselves — the real mechanisms are proven in
+`adapters/system/node/tests/node-process-sandbox.test.ts` (macOS) and `linux-namespace-sandbox.test.ts` (Linux, run in
+a container)). Live:
+`product-lab host verify --host truapi-cli --config tools/verify/src/truapi-cli.ts`, `--host truapi-cli-deny`,
+`--host truapi-cli-deny-leaky` and the opt-in tests above
+(with the four-patch host;
+on Linux).
+
+## Locked setup artifacts
+
+`product-lab host build` chooses a temporary checkout when `--workdir` is omitted and removes it afterwards.
+Its default patches are request-decisions, reduced chain-reconnect and signature-evidence: set `335d3bb47d4c`
+on `@parity/truapi@0.26.0` (`14b1e2a`) since 22 October 2026. Routing and navigation are upstream; the official entry
+is unpatched 0.26.0. The prior base already carried #1017, and the Bulletin backport was retired after the Notes read/restart journey.
+`bun run setup` reuses this exact set from the cache or builds it. Acquisition accepts a cached superset only for
+the same base, target and current manifest digests, recording all patches actually present.
+`PRODUCT_LAB_HOST_BIN` is an optional composition-level override with unpinned provenance.
+
+### Locked patch combinations in the cache
+
+A host declaration can request only the capabilities it needs, such as `local-network`.
+When those patches belong to the current host lock and use its base commit, acquisition
+requires the complete locked combination. An older cached subset does not qualify; the
+error names `bun run setup` and the build command for the current combination. Exact
+cache entries and supersets both need matching base, target and current manifest digests.
+Custom patch sets outside that lock retain their explicit selection. Caller-supplied
+binaries remain explicit unpinned overrides.
+
+In a product (an installed `@parity/product-lab`: the package root's `package.json` is not product-lab's workspace,
+`src/checkout.ts`) the same missing host names nothing to build (7 October 2026): `MissingHostError` and `hostTarget`'s
+unsupported platform say a product runs the official release only (`PRODUCT_RELEASED_ONLY`) and name the truAPI WASM
+test host to run instead (`defaultHost: "truapi-wasm"`). A product runs the locked official release (backlog 212,
+8 October 2026; 16 October 2026): the factory's `create` drops the declared patches and any `hostBin`, and allows the
+host wherever that release provides what the environment needs: a live network nothing more, a local environment
+`localNetwork` (`official.provides`, above). Otherwise it refuses before anything starts, naming the missing behaviour
+and the upstream change that adds it (`productCliHostLocalGap`: "lacks what a local environment needs: localNetwork
+(take the lab's local endpoints: [host-rust-core#1166](https://github.com/paritytech/host-rust-core/pull/1166))"). The
+provisioner follows the same rule. A patched host never runs for a product: `obtainHost` refuses patches or a path
+outside the checkout, and `create` refuses `PRODUCT_LAB_HOST_BIN`, whatever the machine's cache holds
+(`productCliHostRefusal`). `availability` says which release and what it provides (`productCliHostDetail`); while the
+release lacks `localNetwork` it says "on a live network only" and sets `liveNetworkOnly` (`PRODUCT_CLI_HOST_LOCAL`), so
+`product-lab check` lists each local environment whose default host it is as unable to start, with the fix
+(`defaultHost: "truapi-wasm"`, or a live network). The current 0.26.0 lock provides local routing and navigation, so a product can start locally. Tests: `tests/checkout.test.ts`, `tests/acquire.test.ts` (a planted cached patched host the
+checkout runs and a product never does), `tests/public-network.test.ts` ("backlog 212") and
+`tests/official-provides.test.ts` (capabilities from `provides`, a product allowed or refused per environment and
+release, the provisioner, `host fetch --list`). The official release is locked at 0.26.0 (`host.lock.json`); its archives are attested by `paritytech/trinity-user-agents` (host-rust-core's new name), older ones by host-rust-core: `verifyAttestation` tries both, newest first (`ATTESTING_REPOSITORIES`, `tests/attestation-repositories.test.ts`).
+
+The capability probe writes per-request answers through an atomic rename, just as running sessions do. A host
+polling for its answer therefore sees the whole file; a delayed write cannot expose an empty answer as a refusal.
+
+An adopted session reads its product account with `scriptAccountRead` on the launched host's wallet (its binary, `TRUAPI_HOST_BASE_PATH`, stored session, network and `host-network.json`): the host's own product/index answer, an explicit failure when unavailable, no app attributes required. (Until 21 October 2026 the launcher set `TRUAPI_ACCOUNT_REQUESTS_DIR` and `readHostProductAccount` read it, with the product-account-read patch.)
+
+
+Since 30 September 2026, an initialized returned-signature transcript supplies successful local signing records through `approvals.signing()`. Review denials remain recorded; a missing native startup coverage marker remains a gap. Approved review counts alone supply no exact signing proof.
+
+
+## Same-origin bridge diagnosis (item 83)
+
+A lab app proxy now serves the configured native bridge through a session-specific URL under `/.product-lab/bridge/`. `watchHostLink` recognizes that actual same-origin injected URL alongside the legacy direct `/bootstrap.js` URL. A named script without the bridge global reports possible script-src/network refusal. A bridge global without an observed socket reports possible connect-src/network refusal. Neither proves connection: only frames sent to the current native host and frames received from it make the link connected; a nonanswering host remains distinct. The socket still goes to the native port, and app CSP is preserved.
+
+Unit control: `node --import tsx --test adapters/host/truapi-cli/tests/host-link.test.ts`. Actual native account/raw-signature proof is the opt-in `tools/verify/live/bridge-csp.ts` composition helper, recorded separately from stub-browser controls.
+
+## Serving an existing copied CLI wallet (1 October 2026)
+
+`servePersistedTruapiHost` serves one product through `signing-host --serve` from an explicitly owned copy of an existing attested CLI session. Missing, wrongly named or unattested state is refused before launch; it never chooses a new wallet. It checks local routing and executable evidence, owns its process and wallet lock, bounds readiness, strips inherited signer settings, and returns the native bootstrap and public account/navigation/approval/signature paths. Stored attestation is a prerequisite read from the existing store, not a cryptographic integrity claim. Its `readAccount(index)` is a `scriptAccountRead` with the served binary, wallet copy, stored session, network and routing, made when asked, beside the live host. Fixture controls: `tests/serve-persisted.test.ts`, `bunx nx run host-truapi-cli:test`.
+
+The persisted-wallet helper accepts a product in the routed DotNS namespace, or a canonical
+`localhost` / `localhost:<port>` authority (port 1–65535, without leading zeros). This matches a
+product deriving its ID from a local browser origin. The caller still supplies the validated
+routing; a localhost ID does not select or change the network. Other namespaces, IP product IDs,
+lookalikes, credentials, paths and malformed ports are refused before any command or process starts.
+Localhost is a separate product account and storage scope from a DotNS name. This does not add a
+provider capability or qualify cross-product permissions. The existing persisted-wallet tests cover
+these accepted bindings and refused inputs.
+
+
+## Released 0.26.0 and the remaining patches
+
+The lock selects the unpatched 0.26.0 release for products. `official.provides` records local routing and navigation.
+The patched base is also 0.26.0; its three patches are request decisions, reduced chain reconnect and signature evidence.
+`patched.provides` records the qualified upstream capabilities of exactly that base. A different base, a binary override
+or an unqualified route never inherits them. A routed patched host must match both the locked base and patch-set digest;
+a routed official archive must match the locked version, target and archive digest. Historical selections naming local-network or navigation-events
+use the current complete patched set when those requirements are already in the locked base; acquired evidence lists only
+its actual patches. Historical patch files remain available for their recorded older bases.
+
+A variant's `appliesAfter` overrides historical prerequisites, so upstream navigation needs no local patch prerequisite on
+0.26.0. The reduced reconnect variant retains upstream read-side close and adds writer-failure propagation and bounded pump
+shutdown. This remaining change is to file upstream; this job files nothing.
+
+`patched.providesBase` pins the qualification to the exact base: changing `patched.base` without requalifying fails lock
+validation. The remaining reconnect patch also requires `boundedSocketShutdown`, which the exterior follow-cut probe
+does not measure. Suite routing keeps that patch and a retirement row is untested until every required behaviour is probed.
+Suite routing also retains the locked base's routing/navigation as requirements when testing another release. It checks
+patches only for behaviours that release did not provide, using that release's exact historical variants when available.
+The provider uses the route's actual patch list, so an official route claims no requested lab patches and a patched route
+can inherit base behaviours only for the qualified combination.
+
+
+## Caller-chosen wallets through released attest
+
+`truapiCliAttestProvisioner(options)` is a separate, explicit `IdentityProvisioner` for a local environment.
+It declares `registersUsername`, `acceptsEntropy` and `needsIdentityBackend`, requires caller-chosen valid BIP39
+entropy, and runs the acquired official CLI's `attest` command. It uses no host patch by default. A selected binary
+must advertise the mnemonic environment binding in `attest --help` and pass the existing `local-network-check`; an old binary is refused before
+onboarding. This path does not alter `truapiCliProvisioner`, its auto-generated 12-word wallets or its persisted
+CLI sessions.
+
+Options include the local `routes`, private `dataRoot`, independent `accounts: ProductAccountDerivation`,
+`system.commands`, optional `system.sandbox`, `usernamePrefix`, `readyTimeoutMs` (240,000 ms by default), and the
+usual `host` selection. `denyByDefault: true` requires a usable process sandbox and wraps the secret-bearing command
+with only the declared loopback routes. On Linux it needs working user/network namespaces, util-linux and iproute2;
+Ubuntu AppArmor/container policy may refuse them. Such refusal is a prerequisite failure, never a silent unconfined
+fallback. Nothing requires a camera, display or macOS.
+
+The mnemonic appears only in the child's `HOST_CLI_SIGNER_MNEMONIC`, never argv or evidence. Raw command output and
+errors are not logged; failures retain a private wallet for manual inspection of an ambiguous backend write. Failed attempts are not
+automatically retried or reopened as ready. Each
+attempt owns a unique 0700 directory with a 0600 `wallet.json` and route file. The command waits for backend
+registration, dotNS identity and ring inclusion. A successful public result must have the requested username base,
+match independent `uid.<namespace>` index-0 derivation, and have an SS58 address encoding that same public key.
+The caller still verifies finalized chain state for its scenario.
+
+The return type is `CliAttestedIdentity`, with public `AttestProvisionEvidence` and no `cli` auto-session property:
+`attest` creates no auto account store. `readAttestedIdentity(dir, accounts, namespace)` reopens a successful attempt
+and revalidates the private wallet/public binding. Incomplete attempts cannot be reopened as ready. These exports
+are available from `@product-lab/host-truapi-cli` (`@parity/product-lab/host-truapi-cli` in the packed package).
+
+Focused controls: `tests/attest-provision.test.ts` covers chosen entropy, old-command refusal, wrong-wallet/address/
+username results, malformed output, cancellation/error redaction, private-file modes, sandbox admission and corrupt
+saved state. `tests/provision.test.ts` retains auto behavior and its chosen-entropy guard. Run with Node:
+
+```sh
+node --import tsx --test adapters/host/truapi-cli/tests/attest-provision.test.ts adapters/host/truapi-cli/tests/provision.test.ts
+```