opencode-session-port 0.0.0-stage → 0.1.1

package/src/tui/wiring/composition.ts

@@ -0,0 +1,354 @@
+/**
+ * SessionPort TUI command composition (Phase 2 experimental Windows wiring).
+ *
+ * `createSessionPortHandlers` composes the completed Phase 2-4 seams into the
+ * two injected command callbacks consumed by `installSessionPortCommands`:
+ *
+ * `/checkpoint [artifact-path]`
+ *   1. resolve the active project from `context.location.directory` through the
+ *      public `location.get` resolver (exact response matching; fail closed);
+ *   2. `runCheckpointFlow` — exhaustive project-scoped collection (fail, never
+ *      truncate, on any collection cap), matching password prompt, P-15 path
+ *      resolution, seal, exclusive encrypted write;
+ *   3. report path/size/session-count facts or a sanitized failure.
+ *
+ * `/restore <artifact-path>`
+ *   1. require the artifact path argument (nothing runs without it);
+ *   2. probe `session.import` capability FIRST — before any artifact read,
+ *      decrypt, or import (O-12);
+ *   3. enumerate existing host projects via `project.list`, let the user select
+ *      with `selectRestoreProject`;
+ *   4. call `location.get` ONLY for the selected candidate and require an exact
+ *      project-ID/directory match (E42 side effect; OQ-16 stays OPEN);
+ *   5. `runRestorePreflightWithPasswordAttempts` — up to three password
+ *      attempts, full authentication, strict parse, destination snapshot, the
+ *      required metadata-only cross-project session-ID occupancy inventory
+ *      (reusing the already-validated selection candidates; no second
+ *      `project.list`, no `location.get`, no message reads), and `planRestore`
+ *      before anything else happens;
+ *   6. `runRestoreExecution` — sequential parent-first imports with the
+ *      explicit target on every call, no retries, no rollback promise;
+ *   7. present the completed non-empty result through the designer-owned
+ *      keyboard-navigable report dialog (aggregate/per-session facts only); an
+ *      empty result keeps the truthful non-success notification, and a
+ *      dialog-display failure falls back to bounded aggregate-only copy.
+ *
+ * Hard boundaries: no shell/Git, no LLM/model call, no historical tool replay,
+ * no direct database access, no `project.update`; passwords stay masked and are
+ * owned/zeroed by the orchestration helpers; only already-sealed ciphertext is
+ * written and only encrypted artifacts are read. Everything is injected through
+ * `SessionPortHandlerDependencies`, so tests use fake clients, fake crypto,
+ * fake artifact I/O, fake dialogs, and a fake report presenter only.
+ *
+ * Platform policy: registration is gated in `install.ts`; this module itself
+ * makes no platform-support claim.
+ */
+
+import type { ByteSource, CheckpointCryptoFactory } from "../../core/contracts/index.ts";
+import { collectCheckpointPayload } from "../../core/sessions/index.ts";
+import type { RemappedIdDeriver } from "../../core/restore/index.ts";
+import type { ResolveCheckpointOutputPathOptions } from "../artifacts/files.ts";
+import { createLocationResolver, LocationResolutionError } from "../adapters/location-resolver.ts";
+import { createProjectDestinationsAdapter } from "../adapters/project-destinations.ts";
+import { createSessionIdInventory } from "../adapters/session-id-inventory.ts";
+import { createSessionReadAdapter } from "../adapters/session-read.ts";
+import { createSessionImportAdapter, probeSessionImportCapability } from "../adapters/session-import.ts";
+import {
+	runCheckpointFlow,
+	runRestoreExecution,
+	runRestorePreflightWithPasswordAttempts,
+	type RestoreExecutionResult,
+} from "../orchestration/index.ts";
+import { requireCallable, isRecordValue } from "../orchestration/shared.ts";
+import { selectRestoreProject, type RestoreProjectDialog } from "../ui/restore-project-selector.ts";
+import type { RestoreReportPresentationModel } from "../ui/restore-report-flow.ts";
+import type { SessionPortCommandHandlers } from "../ui/sessionport-commands.tsx";
+import {
+	EXPERIMENTAL_COLLECTION_POLICY,
+	EXPERIMENTAL_CRYPTO_POLICY,
+	EXPERIMENTAL_MAX_PASSWORD_BYTES,
+} from "./experimental-profile.ts";
+import {
+	mapRestoreExecutionToReportPresentation,
+	reportCheckpointFailure,
+	reportCheckpointOutcome,
+	reportRestoreAuthenticationFailed,
+	reportRestoreCanceled,
+	reportRestoreCapabilityUnavailable,
+	reportRestoreExecution,
+	reportRestoreExecutionFallback,
+	reportRestoreFailure,
+	reportRestoreUsage,
+	type SessionPortNotification,
+} from "./reports.ts";
+
+/* ------------------------------------------------------------------------- */
+/* Injected dependency surface                                               */
+/* ------------------------------------------------------------------------- */
+
+/** One notification sink; the install layer maps it to `context.ui.toast`. */
+export type SessionPortNotifier = (notification: SessionPortNotification) => void;
+
+/**
+ * Masked password provider: one call per prompt, resolves with the UTF-8 bytes
+ * or `undefined` on cancel. The experimental 4-KiB byte limit is always passed.
+ */
+export type SessionPortPasswordProvider = (
+	mode: "checkpoint" | "restore",
+	maxPasswordBytes: number,
+) => Promise<Uint8Array | undefined>;
+
+/** Explicit, fully injected command dependencies. Every effect is supplied by the caller. */
+export interface SessionPortHandlerDependencies {
+	/** Host-provided public client (untrusted); all host methods go through the existing adapters. */
+	readonly client: unknown;
+	/** Live read of the active project directory (`context.location?.directory`). */
+	readonly getActiveDirectory: () => string | undefined;
+	/** Host dialog selection surface for the restore destination. */
+	readonly dialog: RestoreProjectDialog;
+	/** Sanitized notification sink. */
+	readonly notify: SessionPortNotifier;
+	/** Presents the completed restore report (designer-owned dialog in production). */
+	readonly showRestoreReport: (model: RestoreReportPresentationModel) => void;
+	/** Masked password provider (real UI or a fake in tests). */
+	readonly requestPassword: SessionPortPasswordProvider;
+	/** Initialized crypto factory; production uses the experimental Windows profile. */
+	readonly cryptoFactory: CheckpointCryptoFactory;
+	/** Remapped-ID deriver for restore planning. */
+	readonly idDeriver: RemappedIdDeriver;
+	/** P-15 artifact output-path resolver. */
+	readonly resolveCheckpointOutputPath: (options: ResolveCheckpointOutputPathOptions) => Promise<string>;
+	/** Exclusive encrypted-artifact writer (ciphertext only). */
+	readonly writeEncryptedArtifact: (targetPath: string, source: ByteSource) => Promise<number>;
+	/** Lazy encrypted-artifact reader (no IO until iterated). */
+	readonly readEncryptedArtifact: (targetPath: string) => ByteSource;
+}
+
+/* ------------------------------------------------------------------------- */
+/* createSessionPortHandlers                                                 */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Builds the two command callbacks. Dependency shape is validated fail-closed
+ * before any handler runs; host/API and orchestration errors are converted to
+ * sanitized reports inside each handler and are never rethrown to the host.
+ */
+export function createSessionPortHandlers(dependencies: SessionPortHandlerDependencies): SessionPortCommandHandlers {
+	if (!isRecordValue(dependencies)) {
+		throw new TypeError("createSessionPortHandlers requires an explicit dependency object");
+	}
+	requireCallable(dependencies.getActiveDirectory, "getActiveDirectory");
+	requireCallable(dependencies.notify, "notify");
+	requireCallable(dependencies.showRestoreReport, "showRestoreReport");
+	requireCallable(dependencies.requestPassword, "requestPassword");
+	requireCallable(dependencies.resolveCheckpointOutputPath, "resolveCheckpointOutputPath");
+	requireCallable(dependencies.writeEncryptedArtifact, "writeEncryptedArtifact");
+	requireCallable(dependencies.readEncryptedArtifact, "readEncryptedArtifact");
+	if (!isRecordValue(dependencies.cryptoFactory) || typeof dependencies.cryptoFactory.create !== "function") {
+		throw new TypeError("createSessionPortHandlers requires a CheckpointCryptoFactory with a create(policy) function");
+	}
+	if (!isRecordValue(dependencies.idDeriver) || typeof dependencies.idDeriver.derive !== "function") {
+		throw new TypeError("createSessionPortHandlers requires a RemappedIdDeriver with a derive(namespace, identity, id) function");
+	}
+	if (!isRecordValue(dependencies.dialog) || typeof dependencies.dialog.select !== "function") {
+		throw new TypeError("createSessionPortHandlers requires a dialog with a select(options) function");
+	}
+
+	return {
+		async checkpoint(rawInput: string | undefined): Promise<void> {
+			await runCheckpointCommand(dependencies, rawInput);
+		},
+		async restore(rawInput: string | undefined): Promise<void> {
+			await runRestoreCommand(dependencies, rawInput);
+		},
+	};
+}
+
+/* ------------------------------------------------------------------------- */
+/* /checkpoint                                                               */
+/* ------------------------------------------------------------------------- */
+
+async function runCheckpointCommand(
+	dependencies: SessionPortHandlerDependencies,
+	rawInput: string | undefined,
+): Promise<void> {
+	const explicitOutputPath = parseCheckpointOutputArgument(rawInput);
+	try {
+		const activeDirectory = dependencies.getActiveDirectory();
+		if (typeof activeDirectory !== "string" || activeDirectory.trim().length === 0) {
+			throw new LocationResolutionError(
+				"invalid-request",
+				"The active project directory is unavailable; checkpoint requires an active project",
+			);
+		}
+		// One explicit location.get for the active directory (E42 side effect).
+		const resolved = await createLocationResolver(dependencies.client).resolveActiveProject(activeDirectory);
+		const readPort = createSessionReadAdapter(dependencies.client);
+		const outcome = await runCheckpointFlow(readPort, {
+			projectID: resolved.projectID,
+			projectDirectory: resolved.directory,
+			policy: EXPERIMENTAL_COLLECTION_POLICY,
+			cryptoFactory: dependencies.cryptoFactory,
+			cryptoPolicy: EXPERIMENTAL_CRYPTO_POLICY,
+			resolveCheckpointOutputPath: dependencies.resolveCheckpointOutputPath,
+			writeEncryptedArtifact: dependencies.writeEncryptedArtifact,
+			requestPassword: (purpose) => dependencies.requestPassword(purpose, EXPERIMENTAL_MAX_PASSWORD_BYTES),
+			...(explicitOutputPath !== undefined ? { explicitOutputPath } : {}),
+		});
+		dependencies.notify(reportCheckpointOutcome(outcome));
+	} catch (error) {
+		dependencies.notify(reportCheckpointFailure(error));
+	}
+}
+
+/* ------------------------------------------------------------------------- */
+/* /restore                                                                  */
+/* ------------------------------------------------------------------------- */
+
+async function runRestoreCommand(
+	dependencies: SessionPortHandlerDependencies,
+	rawInput: string | undefined,
+): Promise<void> {
+	const artifactPath = parseRestoreArtifactArgument(rawInput);
+	if (artifactPath === undefined) {
+		dependencies.notify(reportRestoreUsage());
+		return;
+	}
+
+	// O-12: capability absence is the first check — before any file read,
+	// decrypt, destination enumeration, or import.
+	const capability = probeSessionImportCapability(dependencies.client);
+	if (!capability.available) {
+		dependencies.notify(reportRestoreCapabilityUnavailable());
+		return;
+	}
+
+	let executionStarted = false;
+	try {
+		// Candidate enumeration and user selection happen before any location.get
+		// or artifact access; a canceled selection changes nothing.
+		const destinations = await createProjectDestinationsAdapter(dependencies.client).listDestinations();
+		const selected = await selectRestoreProject(dependencies.dialog, destinations);
+		if (selected === undefined) {
+			dependencies.notify(reportRestoreCanceled());
+			return;
+		}
+
+		// location.get ONLY for the selected candidate; exact ID/directory match
+		// is required before any artifact read/decrypt/import (E42; OQ-16 OPEN).
+		const resolved = await createLocationResolver(dependencies.client).resolveSelectedProject({
+			projectID: selected.projectID,
+			targetDirectory: selected.targetDirectory,
+		});
+
+		// Destination snapshot uses the same explicit project scope and the
+		// experimental collection bounds; it is read by runRestorePreflight only
+		// after full authentication and strict parsing. The cross-project
+		// session-ID inventory reuses the already-validated selection candidates
+		// (no second project.list) and scans only session metadata (no message
+		// reads, no location.get, no import).
+		const readPort = createSessionReadAdapter(dependencies.client);
+		const sessionIdInventory = createSessionIdInventory({
+			readPort,
+			projects: destinations,
+			selectedProjectID: resolved.projectID,
+			policy: EXPERIMENTAL_COLLECTION_POLICY,
+		});
+		const outcome = await runRestorePreflightWithPasswordAttempts(dependencies.client, {
+			artifactPath,
+			destinationProjectID: resolved.projectID,
+			targetDirectory: resolved.directory,
+			cryptoFactory: dependencies.cryptoFactory,
+			cryptoPolicy: EXPERIMENTAL_CRYPTO_POLICY,
+			readEncryptedArtifact: dependencies.readEncryptedArtifact,
+			requestPassword: (purpose) => dependencies.requestPassword(purpose, EXPERIMENTAL_MAX_PASSWORD_BYTES),
+			readDestination: async (projectID) =>
+				(await collectCheckpointPayload(readPort, { projectID, policy: EXPERIMENTAL_COLLECTION_POLICY })).sessions,
+			readGloballyVisibleSessionIDs: () => sessionIdInventory.readGloballyVisibleSessionIDs(),
+			idDeriver: dependencies.idDeriver,
+		});
+
+		if (outcome.status === "capability-unavailable") {
+			dependencies.notify(reportRestoreCapabilityUnavailable());
+			return;
+		}
+		if (outcome.status === "canceled") {
+			dependencies.notify(reportRestoreCanceled());
+			return;
+		}
+		if (outcome.status === "authentication-failed") {
+			dependencies.notify(reportRestoreAuthenticationFailed());
+			return;
+		}
+
+		// Only a completed preflight reaches execution; every import carries the
+		// explicit target directory through the existing adapter (O-16).
+		const importer = createSessionImportAdapter(dependencies.client);
+		executionStarted = true;
+		const result = await runRestoreExecution({
+			plan: outcome.plan,
+			importer,
+			targetDirectory: outcome.targetDirectory,
+		});
+		reportRestoreOutcome(dependencies, result);
+	} catch (error) {
+		dependencies.notify(reportRestoreFailure(error, executionStarted));
+	}
+}
+
+/* ------------------------------------------------------------------------- */
+/* Restore outcome presentation                                              */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Presents one completed restore execution. A non-empty result is mapped to the
+ * designer's `RestoreReportPresentationModel` and shown in the keyboard-
+ * navigable report dialog (up to the experimental session cap of outcomes, one
+ * navigable entry each) instead of a per-session toast. An empty result keeps
+ * the truthful non-success notification.
+ *
+ * If the report dialog (or the mapping into its model) throws after execution,
+ * the execution is still reported as finished through bounded aggregate-only
+ * copy: a display failure is never reported as an execution failure, and no raw
+ * exception text or per-session content reaches the notification.
+ */
+function reportRestoreOutcome(dependencies: SessionPortHandlerDependencies, result: RestoreExecutionResult): void {
+	if (result.summary.total === 0) {
+		dependencies.notify(reportRestoreExecution(result));
+		return;
+	}
+	try {
+		dependencies.showRestoreReport(mapRestoreExecutionToReportPresentation(result));
+	} catch {
+		dependencies.notify(reportRestoreExecutionFallback(result));
+	}
+}
+
+/* ------------------------------------------------------------------------- */
+/* Raw-argument parsing (no flag syntax; no trimming of path values)         */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * `/checkpoint` accepts one optional raw argument: the explicit artifact output
+ * path. `undefined` or an all-whitespace argument uses the P-15 default
+ * `.sessionport/` location; any other argument is trimmed of surrounding
+ * whitespace and passed to the P-15 resolver verbatim (no flag parsing, no
+ * shell expansion, no quote handling).
+ */
+export function parseCheckpointOutputArgument(rawInput: string | undefined): string | undefined {
+	if (rawInput === undefined) return undefined;
+	const trimmed = rawInput.trim();
+	return trimmed.length === 0 ? undefined : trimmed;
+}
+
+/**
+ * `/restore` requires one raw argument: the artifact path. `undefined` or an
+ * all-whitespace argument yields `undefined` so the caller reports usage
+ * without touching the host; any other argument is trimmed of surrounding
+ * whitespace and used verbatim.
+ */
+export function parseRestoreArtifactArgument(rawInput: string | undefined): string | undefined {
+	if (rawInput === undefined) return undefined;
+	const trimmed = rawInput.trim();
+	return trimmed.length === 0 ? undefined : trimmed;
+}

package/src/tui/wiring/experimental-profile.ts

@@ -0,0 +1,86 @@
+/**
+ * Windows-first experimental runtime defaults (Phase 2 wiring).
+ *
+ * These are the explicitly selected, owner-authorized experimental values
+ * recorded in `docs/v1/decision-log.md` (2026-10-11 entries) for a Windows
+ * experimental build only. They are NOT a production approval, not a format
+ * freeze, and not a general memory budget, compatibility, or support claim.
+ *
+ * - Crypto profile `sessionport-experimental-win-v1`: profile code 1,
+ *   Argon2id13 `crypto_pwhash`, `opslimit=2`, `memlimit=128 MiB`, the current
+ *   implementation's 16-byte random salt, 64-KiB plaintext frames, password cap
+ *   4 KiB, total encrypted artifact cap 66 MiB, decrypted gzip input cap
+ *   64 MiB, decompressed payload cap 256 MiB, expansion ratio 128 defined as
+ *   decompressed payload bytes / decrypted compressed gzip bytes.
+ * - Collection bounds: session page size 50, message page size 200, at most
+ *   1,000 sessions, at most 10,000 messages per session, and at most 50,000
+ *   messages total. Exceeding any bound fails the whole collection; nothing is
+ *   ever truncated.
+ */
+
+import type { CryptoPolicy } from "../../core/contracts/index.ts";
+import type { CryptoPolicyDefinition } from "../../core/crypto/index.ts";
+import type { SessionCollectionPolicy } from "../../core/sessions/index.ts";
+
+/** Explicit allow-listed policy id for the Windows experimental profile. */
+export const EXPERIMENTAL_CRYPTO_POLICY_ID = "sessionport-experimental-win-v1";
+
+/** The explicit policy selector passed to the crypto factory; never read from an artifact. */
+export const EXPERIMENTAL_CRYPTO_POLICY: CryptoPolicy = Object.freeze({
+	id: EXPERIMENTAL_CRYPTO_POLICY_ID,
+});
+
+/** Experimental password byte limit; the password UI is given the same value. */
+export const EXPERIMENTAL_MAX_PASSWORD_BYTES = 4 * 1024;
+
+/**
+ * The complete experimental allow-list definition. Numeric values are the
+ * owner-recorded Windows-experimental defaults; changing any value requires a
+ * new recorded decision and a fresh review (O-01/O-02/O-03 remain PARTIALLY
+ * RESOLVED for the experimental Windows build only).
+ */
+export const EXPERIMENTAL_CRYPTO_POLICY_DEFINITION: CryptoPolicyDefinition = deepFreeze({
+	id: EXPERIMENTAL_CRYPTO_POLICY_ID,
+	profileCode: 1,
+	kdf: {
+		opsLimit: 2,
+		memLimit: 128 * 1024 * 1024,
+	},
+	compression: {
+		level: undefined,
+	},
+	framing: {
+		chunkBytes: 64 * 1024,
+	},
+	limits: {
+		maxPasswordBytes: EXPERIMENTAL_MAX_PASSWORD_BYTES,
+		maxArtifactBytes: 66 * 1024 * 1024,
+		maxCompressedBytes: 64 * 1024 * 1024,
+		maxDecompressedBytes: 256 * 1024 * 1024,
+		maxExpansionRatio: 128,
+	},
+});
+
+/**
+ * The complete experimental collection policy. `maxTotalMessages` is the
+ * required core aggregate cap (zero is a valid fail-closed value in core; the
+ * experimental value is 50,000).
+ */
+export const EXPERIMENTAL_COLLECTION_POLICY: SessionCollectionPolicy = deepFreeze({
+	sessionPageSize: 50,
+	messagePageSize: 200,
+	maxSessions: 1000,
+	maxMessagesPerSession: 10000,
+	maxTotalMessages: 50000,
+});
+
+/** Deep-freezes a plain JSON-shaped configuration object. */
+function deepFreeze<T>(value: T): T {
+	if (value !== null && typeof value === "object") {
+		for (const key of Object.keys(value)) {
+			deepFreeze((value as Record<string, unknown>)[key]);
+		}
+		Object.freeze(value);
+	}
+	return value;
+}

package/src/tui/wiring/index.ts

@@ -0,0 +1,51 @@
+/**
+ * SessionPort TUI wiring (Phase 2 experimental Windows lane).
+ *
+ * Public surface:
+ * - `installSessionPortWiring(context, options?)` — Windows-only install root:
+ *   pinned-sodium initialization, real adapters/artifact I/O/password modal,
+ *   command registration through the existing component-scoped seam, and the
+ *   slot disposer returned unchanged.
+ * - `createSessionPortHandlers(dependencies)` — fully injected composition of
+ *   the `/checkpoint` and `/restore` command callbacks (fake-based testable).
+ * - Experimental runtime defaults (crypto profile + collection bounds +
+ *   password byte limit) and the sanitized report helpers.
+ *
+ * Boundaries: no shell/Git, no LLM/model call, no historical tool replay, no
+ * direct database access, no `project.update`; only already-sealed ciphertext
+ * is written, only encrypted artifacts are read, and every failure report is
+ * generic/sanitized. No production approval, format freeze, or platform-support
+ * claim is made (O-01/O-02/O-03 remain PARTIALLY RESOLVED for the experimental
+ * Windows build only; OQ-16 stays OPEN).
+ */
+
+export {
+	createSessionPortHandlers,
+	parseCheckpointOutputArgument,
+	parseRestoreArtifactArgument,
+} from "./composition.ts";
+export type {
+	SessionPortHandlerDependencies,
+	SessionPortNotifier,
+	SessionPortPasswordProvider,
+} from "./composition.ts";
+export { installSessionPortWiring } from "./install.ts";
+export type { SessionPortInstallOptions } from "./install.ts";
+export {
+	EXPERIMENTAL_COLLECTION_POLICY,
+	EXPERIMENTAL_CRYPTO_POLICY,
+	EXPERIMENTAL_CRYPTO_POLICY_DEFINITION,
+	EXPERIMENTAL_CRYPTO_POLICY_ID,
+	EXPERIMENTAL_MAX_PASSWORD_BYTES,
+} from "./experimental-profile.ts";
+export {
+	reportCheckpointFailure,
+	reportCheckpointOutcome,
+	reportRestoreAuthenticationFailed,
+	reportRestoreCanceled,
+	reportRestoreCapabilityUnavailable,
+	reportRestoreExecution,
+	reportRestoreFailure,
+	reportRestoreUsage,
+} from "./reports.ts";
+export type { SessionPortNotification, SessionPortNotificationVariant } from "./reports.ts";

package/src/tui/wiring/install.ts

@@ -0,0 +1,108 @@
+/// <reference types="node" />
+/**
+ * SessionPort TUI install/composition root (Phase 2 experimental Windows wiring).
+ *
+ * `installSessionPortWiring` is the only host-facing composition entry:
+ *
+ * - **Windows-first experimental only.** On any non-`win32` platform it returns
+ *   `undefined` immediately: no sodium initialization, no host-context access,
+ *   no command registration, and no platform-support claim.
+ * - On Windows it initializes the pinned `libsodium-wrappers-sumo@0.8.4`
+ *   runtime first (`await sodium.ready` plus primitive/constant validation
+ *   through `createCheckpointCryptoFactory`; `createRemappedIdDeriver` also
+ *   awaits/validates it) and fails closed: a rejected initialization aborts
+ *   setup before any command is registered.
+ * - Native commands are registered through the existing component-scoped
+ *   `installSessionPortCommands` (E39: the keymap layer must live inside the
+ *   app-slot component scope). The slot disposer is returned unchanged so the
+ *   host can clean up its contribution as the host contract permits; command
+ *   handlers own their errors and report sanitized copy, so a handler never
+ *   throws raw host data at the host.
+ * - Completed non-empty restore executions are presented through the
+ *   designer-owned `showRestoreReportDialog` (aggregate/per-session facts only);
+ *   empty results and dialog-display failures keep sanitized toast copy.
+ *
+ * This module statically imports the designer-owned UI modules (password modal
+ * and restore report dialog), which import the optional UI peers
+ * (`@opentui/solid`, `solid-js`). The entry (`src/tui.ts`) imports this module
+ * dynamically only after its `process.platform === "win32"` check, so
+ * non-Windows plugin setup never evaluates those modules.
+ *
+ * Test seams (platform/factory/deriver/password provider) exist only for
+ * fake-based tests; production calls use the real defaults. The real password
+ * provider is the designer-owned masked TUI modal, invoked with the
+ * experimental 4-KiB limit.
+ */
+
+import type { Plugin } from "@opencode/plugin/tui";
+import type { CheckpointCryptoFactory } from "../../core/contracts/index.ts";
+import { createCheckpointCryptoFactory } from "../../core/crypto/index.ts";
+import { createRemappedIdDeriver, type RemappedIdDeriver } from "../../core/restore/index.ts";
+import { readEncryptedArtifact, resolveCheckpointOutputPath, writeEncryptedArtifact } from "../artifacts/files.ts";
+import { requestPassword as showPasswordDialog } from "../ui/password-dialog.tsx";
+import { showRestoreReportDialog } from "../ui/restore-report-dialog.tsx";
+import { installSessionPortCommands } from "../ui/sessionport-commands.tsx";
+import { createSessionPortHandlers, type SessionPortPasswordProvider } from "./composition.ts";
+import { EXPERIMENTAL_CRYPTO_POLICY_DEFINITION } from "./experimental-profile.ts";
+
+/** Test-only seams; production omits every field. */
+export interface SessionPortInstallOptions {
+	/** Platform gate override for tests; defaults to `process.platform`. */
+	readonly platform?: string;
+	/** Crypto-factory seam; the default creates the experimental Windows profile and awaits pinned sodium. */
+	readonly createCryptoFactory?: () => Promise<CheckpointCryptoFactory>;
+	/** Remapped-ID deriver seam; the default awaits/validates pinned sodium. */
+	readonly createIdDeriver?: () => Promise<RemappedIdDeriver>;
+	/** Password-provider seam; the default is the designer-owned masked TUI modal. */
+	readonly requestPassword?: SessionPortPasswordProvider;
+}
+
+/**
+ * Installs the SessionPort commands for the experimental Windows lane and
+ * returns the slot disposer, or `undefined` when this platform is not
+ * registered. Fails closed (rejects) when the pinned runtime or the host
+ * command surface is unavailable; nothing is registered in that case.
+ */
+export async function installSessionPortWiring(
+	context: Plugin.Context,
+	options: SessionPortInstallOptions = {},
+): Promise<(() => void) | undefined> {
+	// Windows-first experimental gate: no registration and no host access anywhere else.
+	if ((options.platform ?? process.platform) !== "win32") return undefined;
+
+	// Pinned-runtime initialization (fail closed): the default factory awaits
+	// `sodium.ready` and validates every primitive the provisional format needs;
+	// the deriver repeats the readiness/validation before registration.
+	const cryptoFactory = await (options.createCryptoFactory ?? createExperimentalCryptoFactory)();
+	const idDeriver = await (options.createIdDeriver ?? createRemappedIdDeriver)();
+
+	const handlers = createSessionPortHandlers({
+		client: context.client,
+		getActiveDirectory: () => context.location?.directory,
+		dialog: context.ui.dialog,
+		notify: (notification) => {
+			context.ui.toast.show({
+				title: notification.title,
+				message: notification.message,
+				variant: notification.variant,
+			});
+		},
+		showRestoreReport: (model) => showRestoreReportDialog(context, model),
+		requestPassword:
+			options.requestPassword ?? ((mode, maxPasswordBytes) => showPasswordDialog(context, mode, maxPasswordBytes)),
+		cryptoFactory,
+		idDeriver,
+		resolveCheckpointOutputPath,
+		writeEncryptedArtifact,
+		readEncryptedArtifact,
+	});
+
+	// E39: registration must stay inside the existing app-slot/keymap
+	// component scope; the slot disposer is returned unchanged.
+	return installSessionPortCommands(context, handlers);
+}
+
+/** Default factory: the experimental Windows profile over the pinned runtime. */
+async function createExperimentalCryptoFactory(): Promise<CheckpointCryptoFactory> {
+	return createCheckpointCryptoFactory([EXPERIMENTAL_CRYPTO_POLICY_DEFINITION]);
+}