@parity/product-lab 0.0.1-placeholder → 0.1.1

package/adapters/host/truapi-cli/src/host-lock.d.ts

@@ -0,0 +1,59 @@
+export declare const DEFAULT_LOCK_FILE: string;
+export interface OrderedPatch {
+    name: string;
+    path: string;
+    sha256: string;
+    base: string;
+    repository: string;
+}
+/**
+ * Resolve requested patch names through the manifest (digests checked), in the
+ * manifest's order with every `appliesAfter` satisfied first. `base` picks each
+ * patch's variant written for that commit (the manifest's `rebased` entries);
+ * without it, the top-level variants (the lock's base). A patch with no variant
+ * for `base` is refused (`NoPatchForBaseError`).
+ */
+export declare function orderedPatches(names: readonly string[], base?: string): OrderedPatch[];
+/**
+ * The patch-set hash: sha256 over the base commit and each patch's name and
+ * digest, in application order (first 12 hex digits). One hash is one binary
+ * per target: framework CI tags `truapi-host-<version>+lab.<hash>`, a local
+ * build labels `truapi-host-<version>+local.<hash>`.
+ */
+export declare function patchsetHash(base: string, patches: readonly Pick<OrderedPatch, "name" | "sha256">[]): string;
+export interface HostLock {
+    schemaVersion: 1;
+    official: {
+        version: string;
+        release: string;
+        archives: Record<string, string>;
+        /**
+         * The behaviours this release carries that the lab's patches add (the manifest's `adds` names, for example
+         * `localNetwork`): what the official host declares instead of patch names (official-behaviours.ts). Absent or empty:
+         * none, as for every release up to 0.25.0. Listed by hand when the lock moves to a release that carries them.
+         */
+        provides?: string[];
+    };
+    patched: {
+        repository: string;
+        base: string;
+        baseVersion: string;
+        /** Behaviours qualified on the unpatched base (not lab patches). */
+        provides?: string[];
+        /** A base bump must explicitly requalify inherited behaviours. */
+        providesBase?: string;
+        patches: string[];
+        patchset: string;
+        archives: Record<string, string>;
+    };
+}
+export declare function readHostLock(file?: string): HostLock;
+/** Required patches after removing behaviours qualified on this exact base. Historical declarations remain usable. */
+export declare function patchesNeededOnBase(names: readonly string[], base: string, lock: {
+    readonly patched: {
+        readonly base?: string;
+        readonly provides?: readonly string[];
+    };
+}, facts?: Readonly<Record<string, {
+    readonly adds: readonly string[];
+}>>): string[];

package/adapters/host/truapi-cli/src/host-lock.js

@@ -0,0 +1,81 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { hostPatches } from "./patches.js";
+import { HOST_PATCH_CATALOGUE } from "./patch-catalogue.js";
+import { resolveHostPatch, patchVariant } from "./patch-manifest.js";
+export const DEFAULT_LOCK_FILE = fileURLToPath(new URL("../host.lock.json", import.meta.url));
+export function orderedPatches(names, base) {
+    const manifest = hostPatches();
+    const requested = new Set(names);
+    if (requested.size !== names.length)
+        throw new Error("A patch is requested twice");
+    for (const name of requested)
+        if (!manifest[name])
+            throw new Error(`Unknown truapi-host patch: ${name}. Known: ${Object.keys(manifest).join(", ")}`);
+    const order = [];
+    const visit = (name, trail) => {
+        if (order.includes(name))
+            return;
+        if (trail.includes(name))
+            throw new Error(`Patch order cycle: ${[...trail, name].join(" -> ")}`);
+        for (const before of patchVariant(name, manifest[name], base).appliesAfter ?? manifest[name].appliesAfter ?? [])
+            if (requested.has(before))
+                visit(before, [...trail, name]);
+        order.push(name);
+    };
+    for (const name of Object.keys(manifest))
+        if (requested.has(name))
+            visit(name, []);
+    const patches = order.map((name) => resolveHostPatch(name, base));
+    const bases = new Set(patches.map((patch) => patch.base));
+    if (bases.size > 1)
+        throw new Error(`Requested patches were written against different bases: ${[...bases].join(", ")}`);
+    return patches;
+}
+export function patchsetHash(base, patches) {
+    if (!/^[a-f0-9]{40}$/.test(base))
+        throw new Error("The patch base must be a full commit hash");
+    const canonical = JSON.stringify({ base, patches: patches.map(({ name, sha256 }) => ({ name, sha256 })) });
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 12);
+}
+export function readHostLock(file = DEFAULT_LOCK_FILE) {
+    const lock = JSON.parse(readFileSync(file, "utf8"));
+    const sha = /^[a-f0-9]{64}$/;
+    if (lock.schemaVersion !== 1)
+        throw new Error(`${file}: unsupported host lock version`);
+    if (!/^\d+\.\d+\.\d+$/.test(lock.official?.version ?? ""))
+        throw new Error(`${file}: official.version must be x.y.z`);
+    for (const [target, digest] of Object.entries(lock.official.archives ?? {}))
+        if (!sha.test(digest))
+            throw new Error(`${file}: official digest for ${target} is not a sha256`);
+    for (const [source, provides] of [["official", lock.official.provides], ["patched", lock.patched?.provides]]) {
+        if (provides !== undefined) {
+            if (!Array.isArray(provides) || provides.some((name) => typeof name !== "string"))
+                throw new Error(`${file}: ${source}.provides must be a list of behaviour names`);
+            if (new Set(provides).size !== provides.length)
+                throw new Error(`${file}: ${source}.provides names a behaviour twice`);
+            const known = new Set(Object.values(HOST_PATCH_CATALOGUE).flatMap((entry) => entry.adds));
+            const unknown = provides.filter((name) => !known.has(name));
+            if (unknown.length)
+                throw new Error(`${file}: ${source}.provides names ${unknown.join(", ")}, which no truapi-host patch adds (known: ${[...known].join(", ")})`);
+        }
+    }
+    if (lock.patched?.provides?.length && lock.patched.providesBase !== lock.patched.base)
+        throw new Error(`${file}: patched.providesBase must match patched.base; requalify inherited behaviours before changing the base`);
+    if (!/^[a-f0-9]{40}$/.test(lock.patched?.base ?? ""))
+        throw new Error(`${file}: patched.base must be a full commit`);
+    if (!/^[a-f0-9]{12}$/.test(lock.patched.patchset ?? ""))
+        throw new Error(`${file}: patched.patchset must be 12 hex digits`);
+    return lock;
+}
+export function patchesNeededOnBase(names, base, lock, facts = HOST_PATCH_CATALOGUE) {
+    if (new Set(names).size !== names.length)
+        throw new Error("A patch is requested twice");
+    if (base !== lock.patched.base)
+        return [...names];
+    const provided = lock.patched.provides ?? [];
+    return names.filter((name) => !facts[name]?.adds.length || !facts[name].adds.every((behaviour) => provided.includes(behaviour)));
+}

package/adapters/host/truapi-cli/src/host-options.d.ts

@@ -0,0 +1,65 @@
+import type { HostOptionDeclaration } from "@parity/product-lab/ports/host";
+import { z } from "zod";
+import type { HostSelection } from "./acquire.js";
+/** The adapter kind (`HostAdapterFactory.kind`). */
+export declare const TRUAPI_CLI_KIND = "truapi-cli";
+/** Patches a truAPI CLI build can carry (patches/truapi-host/manifest.json). */
+export declare const TRUAPI_CLI_PATCHES: readonly ["local-network", "navigation-events", "request-decisions", "chain-reconnect", "signature-evidence"];
+export type TruapiCliPatch = (typeof TRUAPI_CLI_PATCHES)[number];
+/** The data options of a truAPI CLI host (what a lab can declare); the browser, environment and system ports are its dependencies. */
+export declare const truapiCliHostOptionsSchema: z.ZodObject<{
+    hostBin: z.ZodOptional<z.ZodString>;
+    host: z.ZodOptional<z.ZodCustom<HostSelection, HostSelection>>;
+    patches: z.ZodArray<z.ZodEnum<{
+        "local-network": "local-network";
+        "navigation-events": "navigation-events";
+        "request-decisions": "request-decisions";
+        "chain-reconnect": "chain-reconnect";
+        "signature-evidence": "signature-evidence";
+    }>>;
+    stateRoot: z.ZodString;
+    ports: z.ZodOptional<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+    }, z.core.$strict>>;
+    actorStateRoot: z.ZodOptional<z.ZodString>;
+    readyTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    decisionTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    pendingTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    productConfigs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    productConfigOptIn: z.ZodOptional<z.ZodObject<{
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    logLevel: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        warn: "warn";
+        info: "info";
+        debug: "debug";
+        trace: "trace";
+    }>>;
+    rustLog: z.ZodOptional<z.ZodString>;
+    denyByDefault: z.ZodOptional<z.ZodBoolean>;
+    networkExceptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        origin: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    conditionLinks: z.ZodOptional<z.ZodEnum<{
+        always: "always";
+        "when-asked": "when-asked";
+    }>>;
+    networkLocked: z.ZodOptional<z.ZodBoolean>;
+    oneWalletForAllApps: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/**
+ * Backlog 185: the switches this adapter offers on its hosts (`HostAdapterFactory.hostOptions`), which the lab window,
+ * the terminal and scenarios render by these words. Their values are this schema's keys of the same names.
+ */
+export declare const TRUAPI_CLI_HOST_OPTIONS: readonly HostOptionDeclaration[];
+/** The default folder of `oneWalletForAllApps` under a host's `stateRoot`. */
+export declare const ACTOR_STATE_FOLDER = "actor-state";
+/**
+ * The options as the host runs them: `networkLocked` and `oneWalletForAllApps`, when set, decide `denyByDefault` and
+ * `actorStateRoot` (the latter `<stateRoot>/actor-state` unless the options name one).
+ */
+export declare function effectiveTruapiCliOptions<Options extends TruapiCliHostConfig>(options: Options): Options;
+export type TruapiCliHostConfig = z.input<typeof truapiCliHostOptionsSchema>;

package/adapters/host/truapi-cli/src/host-options.js

@@ -0,0 +1,61 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { isAbsolute, join } from "node:path";
+import { z } from "zod";
+export const TRUAPI_CLI_KIND = "truapi-cli";
+export const TRUAPI_CLI_PATCHES = ["local-network", "navigation-events", "request-decisions", "chain-reconnect", "signature-evidence"];
+export const truapiCliHostOptionsSchema = z
+    .strictObject({
+    hostBin: z.string().refine((path) => isAbsolute(path), "hostBin must be an absolute path").optional(),
+    host: z.custom((value) => !!value && typeof value === "object", "expected a host selection").optional(),
+    patches: z
+        .array(z.enum(TRUAPI_CLI_PATCHES)),
+    stateRoot: z.string().min(1),
+    ports: z
+        .strictObject({ from: z.number(), to: z.number() })
+        .refine(({ from, to }) => Number.isInteger(from) && Number.isInteger(to) && from >= 1024 && to <= 65535 && from <= to, "Port range must be integers within 1024-65535")
+        .optional(),
+    actorStateRoot: z.string().refine((path) => isAbsolute(path), "actorStateRoot must be an absolute path").optional(),
+    readyTimeoutMs: z.number().int().positive().optional(),
+    decisionTimeoutMs: z.number().int().positive().optional(),
+    pendingTimeoutMs: z.number().int().positive().optional(),
+    productConfigs: z.array(z.string().refine((path) => isAbsolute(path), "product configs must be absolute paths")).optional(),
+    productConfigOptIn: z.strictObject({ reason: z.string().trim().min(1) }).optional(),
+    logLevel: z.enum(["error", "warn", "info", "debug", "trace"]).optional(),
+    rustLog: z.string().trim().min(1).optional(),
+    denyByDefault: z.boolean().optional(),
+    networkExceptions: z
+        .array(z.strictObject({ origin: z.string(), reason: z.string().trim().min(1) }))
+        .optional(),
+    conditionLinks: z.enum(["when-asked", "always"]).optional(),
+    networkLocked: z.boolean().optional(),
+    oneWalletForAllApps: z.boolean().optional(),
+});
+export const TRUAPI_CLI_HOST_OPTIONS = [
+    {
+        name: "networkLocked",
+        label: "network locked",
+        why: "The wallet may reach only the lab's own chains, and the app only through it: proves the app calls nothing it should not",
+        type: "boolean",
+        default: false,
+        perIdentity: true,
+    },
+    {
+        name: "oneWalletForAllApps",
+        label: "one wallet for all apps of a person",
+        why: "Every app of the same person uses one wallet, as apps on one phone share one; its apps then open one after the other",
+        type: "boolean",
+        default: false,
+        perIdentity: true,
+    },
+];
+export const ACTOR_STATE_FOLDER = "actor-state";
+export function effectiveTruapiCliOptions(options) {
+    const { networkLocked, oneWalletForAllApps, ...rest } = options;
+    const { actorStateRoot, ...shared } = rest;
+    return {
+        ...(oneWalletForAllApps === false ? shared : rest),
+        ...(networkLocked !== undefined ? { denyByDefault: networkLocked } : {}),
+        ...(oneWalletForAllApps ? { actorStateRoot: actorStateRoot ?? join(options.stateRoot, ACTOR_STATE_FOLDER) } : {}),
+    };
+}

package/adapters/host/truapi-cli/src/host-process.d.ts

@@ -0,0 +1,79 @@
+import type { ConditionedLinks, EnvironmentVariables, GatedRoutes, LockManager, OwnedProcesses } from "@parity/product-lab/ports/system";
+import { type HostCapabilities, type HostNetworkRoutes, type ProvisionedIdentity } from "@parity/product-lab/domain";
+import type { HostActor, HostApp, SessionApprovals } from "@parity/product-lab/ports/host";
+import type { AcquiredTruapiHost, TruapiResolvedHost } from "./acquire.js";
+import type { TruapiCliNetworkConfig } from "./network-config.js";
+import { type SeededProductConfig } from "./product-config.js";
+import type { CliHostSession, SharedActorState, TruapiCliHostOptions } from "./host-types.js";
+/** The run's variable that gives every truAPI CLI host a `RUST_LOG` (opt-in; the `rustLog` option wins). Backlog 175. */
+export declare const HOST_RUST_LOG_VARIABLE = "PRODUCT_LAB_HOST_RUST_LOG";
+/** The `RUST_LOG` a host process gets: the `rustLog` option, else the run's variable, else none (the default). */
+export declare function hostRustLog(options: {
+    rustLog?: string;
+    system: {
+        environment?: Pick<EnvironmentVariables, "get">;
+    };
+}): string | undefined;
+export declare function sharedState(actor: string, dataDir: string): SharedActorState;
+/** The CLI's wallet root for a provisioned identity (BIP-39 words for its entropy). */
+export declare function signerMnemonic(identity: ProvisionedIdentity): string;
+/** A session directory is owned by one live process at a time; a lock left by a dead one is taken over. */
+export declare function claim(locks: LockManager, dir: string, shared?: {
+    actor: string;
+    app: string;
+}): () => void;
+export declare function isolatedEnv(): NodeJS.ProcessEnv;
+export declare function blankInherited(): NodeJS.ProcessEnv;
+/** What the provider shares with its host processes and sessions (createTruapiCliHost). The getters read the
+ * provider's state when they are called: `prepare()`, `resolve()` and `dispose()` set it later. */
+export interface HostRuntime {
+    readonly options: TruapiCliHostOptions;
+    /** How the host reaches the environment (the options' `routes`). */
+    readonly lab: HostNetworkRoutes;
+    /** The CLI's local-network config for `lab` (truapiCliNetworkConfig); undefined in public mode. */
+    readonly routes: TruapiCliNetworkConfig | undefined;
+    /** Backlog 92: the gates in front of the routing's nodes, once prepare() opened them (deny-by-default only). */
+    gated(): GatedRoutes | undefined;
+    /** Public mode (backlog A4): every route is public, so the host runs on its own endpoints for `lab.network`. */
+    readonly publicNetwork: boolean;
+    /** Backlog 31: each session's own links to the routing's endpoints, when the host declares conditions. */
+    readonly conditionedLinks: ConditionedLinks | undefined;
+    readonly capabilities: HostCapabilities;
+    readonly denyByDefaultNetwork: boolean;
+    readonly readyTimeoutMs: number;
+    readonly pendingTimeoutMs: number;
+    readonly patches: string[];
+    /** The provider's running sessions. */
+    readonly sessions: Set<CliHostSession>;
+    /** A host port from the `ports` range. */
+    allocate(): Promise<number>;
+    supervisor(): OwnedProcesses | undefined;
+    acquired(): AcquiredTruapiHost | undefined;
+    resolved(): TruapiResolvedHost | undefined;
+    productConfigs(): SeededProductConfig[];
+    /** The next host process number (ids are `<actor>-<app>-<identity>-<n>`). */
+    nextId(): number;
+}
+export interface Running {
+    /** Backlog 192: where the process's standard output and error go (the supervisor's log of this process). */
+    log: string;
+    id: string;
+    pid: number;
+    port: number;
+    dataDir: string;
+    runDir: string;
+    /** This process's confirmations (`per-request` sessions). One per process: ids restart with it. */
+    decisionsDir: string;
+    /** The process's `--base-path` (the identity's host state): the session's account read runs on it too. */
+    hostState: string;
+    /** The process's routing and its file (`HOST_CLI_LOCAL_NETWORK_CONFIG`); absent in public mode. */
+    routes?: TruapiCliNetworkConfig;
+    routingFile?: string;
+    fingerprint: string;
+    release(): void;
+    stop(): Promise<void>;
+    startMs: number;
+}
+export declare function startHostProcess(runtime: HostRuntime, actor: HostActor, app: HostApp, identity: ProvisionedIdentity, approvals: SessionApprovals, runDir: string, 
+/** The session's own routing (its conditioned links, backlog 31); default the provider's. */
+routes?: TruapiCliNetworkConfig | undefined): Promise<Running>;

package/adapters/host/truapi-cli/src/host-process.js

@@ -0,0 +1,160 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { entropyToMnemonic } from "@polkadot-labs/hdkd-helpers";
+import { assertBip39Entropy } from "@parity/product-lab/domain";
+import { identityFingerprint } from "./identity-fingerprint.js";
+import { hostSandboxSpec } from "./sandbox-spec.js";
+import { NAVIGATIONS_LOG_ENV } from "./navigation.js";
+import { productConfigArgs } from "./product-config.js";
+import { DECISIONS_DIR_ENV, DECISIONS_TIMEOUT_ENV } from "./host-requests.js";
+import { SIGNATURES_LOG_ENV } from "./signing-evidence.js";
+import { hostTempDir } from "./host-temp-dir.js";
+const ISOLATED = /^(HOST_|TRUAPI_|VITE_|PPN_|PRODUCT_LAB_|RUST_LOG$)/;
+export const HOST_RUST_LOG_VARIABLE = "PRODUCT_LAB_HOST_RUST_LOG";
+export function hostRustLog(options) {
+    return options.rustLog ?? (options.system.environment?.get(HOST_RUST_LOG_VARIABLE)?.trim() || undefined);
+}
+export function sharedState(actor, dataDir) {
+    return { actor, dataDir, rule: "sequential" };
+}
+export function signerMnemonic(identity) {
+    assertBip39Entropy(identity.entropy);
+    return entropyToMnemonic(identity.entropy);
+}
+export function claim(locks, dir, shared) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const attempt = locks.tryAcquire({ path: join(dir, "session.lock"), onStale: "reclaim", ownerless: "stale" });
+    if (!attempt.acquired)
+        throw new Error(shared
+            ? `${shared.actor}'s host data directory ${dir} is shared by all of the actor's apps (actorStateRoot) and a session of the actor is running; stop it before opening ${shared.app} (sessions of one actor run one after the other)`
+            : `Host data directory ${dir} is in use by a running session; concurrent processes must not share one (core-storage.json is last-writer-wins)`);
+    return () => {
+        attempt.lock.release();
+    };
+}
+export function isolatedEnv() {
+    return Object.fromEntries(Object.entries(process.env).filter(([key]) => !ISOLATED.test(key)));
+}
+export function blankInherited() {
+    return Object.fromEntries(Object.keys(process.env).filter((key) => ISOLATED.test(key)).map((key) => [key, undefined]));
+}
+export async function startHostProcess(runtime, actor, app, identity, approvals, runDir, 
+routes = runtime.routes) {
+    if (!runtime.supervisor())
+        throw new Error("call prepare() before createSession()");
+    const started = performance.now();
+    const fingerprint = identityFingerprint(identity);
+    const dataDir = runtime.options.actorStateRoot
+        ? join(runtime.options.actorStateRoot, actor.id, "identities", fingerprint)
+        : join(runtime.options.stateRoot, "actors", actor.id, "apps", app.id, "identities", fingerprint);
+    const release = claim(runtime.options.system.locks, dataDir, runtime.options.actorStateRoot ? { actor: actor.id, app: app.id } : undefined);
+    let temp;
+    try {
+        const port = await runtime.allocate();
+        const hostState = join(dataDir, "host-state");
+        mkdirSync(hostState, { recursive: true, mode: 0o700 });
+        mkdirSync(runDir, { recursive: true, mode: 0o700 });
+        temp = hostTempDir(runDir, process.env.TMPDIR);
+        const routing = routes ? join(runDir, "host-network.json") : undefined;
+        if (routing)
+            writeFileSync(routing, JSON.stringify(routes, null, 2) + "\n", { mode: 0o600 });
+        const id = `${actor.id}-${app.id}-${fingerprint}-${runtime.nextId()}`.replace(/[^a-zA-Z0-9_-]/g, "-");
+        const decisionsDir = join(runDir, "decisions", id);
+        const rustLog = hostRustLog(runtime.options);
+        if (approvals === "per-request")
+            mkdirSync(decisionsDir, { recursive: true, mode: 0o700 });
+        const plan = {
+            command: runtime.acquired().binary,
+            args: [
+                "signing-host",
+                "--serve",
+                "--frame-listen",
+                `127.0.0.1:${port}`,
+                "--network",
+                runtime.lab.network,
+                "--base-path",
+                hostState,
+                "--product-id",
+                app.productId,
+                ...(approvals === "approve-all" ? ["--auto-accept"] : []),
+                ...productConfigArgs(runtime.productConfigs()),
+                ...(runtime.options.logLevel ? ["--log-level", runtime.options.logLevel] : []),
+            ],
+            cwd: runDir,
+            env: {
+                ...blankInherited(),
+                HOST_CLI_SIGNER_MNEMONIC: signerMnemonic(identity),
+                ...(routing ? { HOST_CLI_LOCAL_NETWORK_CONFIG: routing } : {}),
+                [NAVIGATIONS_LOG_ENV]: join(runDir, "navigations.jsonl"),
+                TRUAPI_APPROVALS_LOG: join(runDir, "approvals.log"),
+                [SIGNATURES_LOG_ENV]: join(runDir, "signatures.jsonl"),
+                TRUAPI_HOST_NO_UPDATE: "1",
+                ...(rustLog ? { RUST_LOG: rustLog } : {}),
+                ...temp.env,
+                ...(approvals === "per-request"
+                    ? { [DECISIONS_DIR_ENV]: decisionsDir, [DECISIONS_TIMEOUT_ENV]: String(runtime.options.decisionTimeoutMs ?? 120_000) }
+                    : {}),
+            },
+        };
+        const finalPlan = runtime.denyByDefaultNetwork && routes ? runtime.options.system.sandbox.denyNetworkExceptLoopback(plan, hostSandboxSpec(routes, port, runDir)) : plan;
+        const owned = await runtime.supervisor().start(id, finalPlan);
+        writeFileSync(join(runDir, "session.json"), JSON.stringify({
+            actor: actor.id,
+            app: app.id,
+            product: app.productId,
+            identity: fingerprint,
+            approvals,
+            port,
+            pid: owned.pid,
+            args: plan.args,
+            routing: runtime.publicNetwork ? `public: the host's own endpoints for ${runtime.lab.network}` : "local-network",
+            ...(runtime.options.actorStateRoot ? { sharedState: sharedState(actor.id, dataDir) } : {}),
+            ...(temp.reason ? { tmpdir: temp.reason } : {}),
+            startedAt: new Date().toISOString(),
+        }, null, 2) + "\n", { mode: 0o600 });
+        const log = runtime.supervisor().logFile(id);
+        let exited;
+        void owned.exited.then((code) => {
+            exited = code;
+        });
+        const deadline = Date.now() + runtime.readyTimeoutMs;
+        for (;;) {
+            const text = existsSync(log) ? readFileSync(log, "utf8") : "";
+            if (text.includes("Signing host ready"))
+                break;
+            if (exited !== undefined)
+                throw new Error(`truapi-host exited (${exited}) before it was ready; see ${log}`);
+            if (Date.now() > deadline) {
+                await owned.stop().catch(() => undefined);
+                throw new Error(`truapi-host was not ready within ${runtime.readyTimeoutMs} ms; see ${log}`);
+            }
+            await delay(100);
+        }
+        const bridge = await fetch(`http://127.0.0.1:${port}/bootstrap.js`, { signal: AbortSignal.timeout(Math.max(1_000, deadline - Date.now())) }).catch(async (error) => {
+            await owned.stop().catch(() => undefined);
+            throw new Error(`truapi-host did not serve its bridge script: ${error instanceof Error ? error.message : String(error)}; see ${log}`, { cause: error });
+        });
+        if (!bridge.ok) {
+            await owned.stop().catch(() => undefined);
+            throw new Error(`truapi-host did not serve its bridge script (${bridge.status})`);
+        }
+        const ownTemp = temp;
+        const stop = async () => {
+            try {
+                await owned.stop();
+            }
+            finally {
+                ownTemp.remove();
+            }
+        };
+        return { id, log, pid: owned.pid, port, dataDir, runDir, decisionsDir, hostState, ...(routes && routing ? { routes, routingFile: routing } : {}), fingerprint, release, stop, startMs: Math.round(performance.now() - started) };
+    }
+    catch (error) {
+        release();
+        temp?.remove();
+        throw error;
+    }
+}

package/adapters/host/truapi-cli/src/host-records.d.ts

@@ -0,0 +1,73 @@
+import type { ResolvedHost } from "@parity/product-lab/ports/host";
+/** Where each archive comes from. `unpinned` is a caller-supplied binary. */
+export type HostOrigin = "official" | "framework-ci" | "local-build" | "unpinned";
+export type AttestationPolicy = "required" | "when-available" | "skip";
+export interface AttestationRecord {
+    status: "verified" | "unavailable" | "skipped" | "none";
+    /** Why it was not verified. */
+    reason?: string;
+    signerWorkflow?: string;
+    /** Commit the attested build ran from. */
+    sourceCommit?: string;
+    sourceRef?: string;
+    runUrl?: string;
+}
+export interface AcquiredRecord {
+    schemaVersion: 1;
+    label: string;
+    origin: Exclude<HostOrigin, "unpinned">;
+    version: string;
+    target: string;
+    archive: {
+        name: string;
+        sha256: string;
+        url?: string;
+    };
+    binary: {
+        path: string;
+        sha256: string;
+    };
+    versionOutput: string;
+    /** `lock`: the digest the archive had to match; `lockSource`: where it came from (host.lock.json, or a resolved version). */
+    checksums: {
+        published?: string;
+        lock?: string;
+        lockSource?: string;
+    };
+    attestation: AttestationRecord;
+    patches: string[];
+    patchset?: string;
+    base?: string;
+    acquiredAt: string;
+    /** Local builds: how the archive was produced (see build.ts). */
+    build?: Record<string, unknown>;
+}
+export interface AcquiredTruapiHost {
+    /** Absolute path of the executable. */
+    binary: string;
+    /** `truapi-host-<version>` or `truapi-host-<version>+<lab|local>.<hash>`. */
+    label: string;
+    origin: HostOrigin;
+    version: string;
+    target: string;
+    archiveSha256: string | null;
+    binarySha256: string;
+    patches: string[];
+    patchset: string | null;
+    attestation: AttestationRecord;
+    /** Cache directory of this host, or the binary's directory for `unpinned`. */
+    dir: string;
+    /** True when no download happened. */
+    cached: boolean;
+    /** Where it came from: the release URL, the build record, or the path. */
+    source: string;
+}
+/** The lock-file entry for a resolved host, with this provider's extra evidence. */
+export interface TruapiResolvedHost extends ResolvedHost {
+    origin: HostOrigin;
+    label: string;
+    archiveSha256: string | null;
+    attestation: AttestationRecord;
+    target: string;
+}
+export declare function resolvedHost(host: AcquiredTruapiHost, versionOutput: string): TruapiResolvedHost;

package/adapters/host/truapi-cli/src/host-records.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function resolvedHost(host, versionOutput) {
+    return {
+        id: "truapi-cli",
+        version: versionOutput,
+        artifact: host.source,
+        sha256: host.binarySha256,
+        patches: host.patches,
+        origin: host.origin,
+        label: host.label,
+        archiveSha256: host.archiveSha256,
+        attestation: host.attestation,
+        target: host.target,
+    };
+}

package/adapters/host/truapi-cli/src/host-requests.d.ts

@@ -0,0 +1,24 @@
+import type { PendingApproval } from "@parity/product-lab/ports/host";
+/** Directory the `request-decisions` host publishes confirmations in. */
+export declare const DECISIONS_DIR_ENV = "TRUAPI_DECISIONS_DIR";
+/** How long that host waits for one decision (ms) before denying it. */
+export declare const DECISIONS_TIMEOUT_ENV = "TRUAPI_DECISIONS_TIMEOUT_MS";
+/** Write a file the host polls for so that it appears whole: the host reads an answer the moment the file exists, and an empty one is a refusal. */
+export declare function writeAtomically(path: string, text: string): void;
+/** The confirmations the host is waiting on, oldest first. */
+export declare function pendingDecisions(dir: string): PendingApproval[];
+/** The answer a terminal would type for this request. Permissions are allowed once, so the next request asks again. */
+export declare function decisionAnswer(request: PendingApproval, approve: boolean): string;
+export interface DecideOptions {
+    /** How long to wait for a request to appear, and then for the host to take the decision. */
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+/**
+ * Decide the oldest pending confirmation, waiting for one, and return it once
+ * the host has taken the decision (`<id>.decided.json`), so a caller's next
+ * step sees the host's state after it. An aborted signal is checked before
+ * anything is read or written and after every wait: an aborted call writes no
+ * `.decision` file and never resolves.
+ */
+export declare function decideNext(dir: string, approve: boolean, { timeoutMs, signal }: DecideOptions): Promise<PendingApproval>;