@timurproko/a1 0.1.1-dev.7 → 0.1.1-dev.9

package/README.md

@@ -4,19 +4,12 @@ A1 is a terminal-native agent launcher for Windows, Linux, and macOS. Bare `a1`
 
 ## Install
 
-Requirements:
-
-- Node.js 22.19 through 24.x
-- npm 11
-
-Published packages include the integrity-verified process guardian for supported platforms. Building A1 from source additionally requires Rust/Cargo 1.85 or newer.
+Requires Node.js 22.19 through 24.x and npm 11.
 
 ```sh
 npm install --global @timurproko/a1@latest
 ```
 
-The package installs only the `a1` command.
-
 ## Commands
 
 ```sh
@@ -28,79 +21,23 @@ a1 update       # update to npm latest
 a1 update:next  # update to npm next
 ```
 
-Bare `a1` owns its Pi-compatible TUI composition and uses the public Pi engine, components, and terminal APIs. It does not insert a PTY or terminal-byte relay. Default visuals and workflows track the pinned vanilla Pi baseline; A1-specific visual customization and structured tabs remain disabled.
-
-`a1 pi` is the untouched upstream fallback and comparison oracle. Use it to distinguish A1-owned UI problems from upstream Pi, profile, provider, or terminal problems. The `a1 ui` subcommand was removed and is not a compatibility alias; run bare `a1` for the owned UI.
+The `a1 ui` subcommand was removed; run bare `a1` for the owned UI.
 
-`a1 sandbox` is unchanged: it launches vanilla Pi with isolated Pi configuration and resources. “Sandbox” does not mean operating-system, filesystem, process, network, or credential security isolation. See [`docs/features/launch-profiles.md`](docs/features/launch-profiles.md) for first-run directories, independent `/login`, trust behavior, extension placement, and recovery.
-
-Every interactive command creates an independent, non-detachable launch instance. Any number of `a1`, `a1 pi`, and `a1 sandbox` commands may run in separate terminals at the same time. Closing one command closes only its owned UI/Pi process and all agents, extensions, tools, daemons, and descendants created by that invocation; it never requires finding PIDs, deleting control state, or restarting the supervisor. The idle supervisor may remain available for release coordination after all interactive instances close, but it owns no surviving instance runtime.
+Any number of `a1`, `a1 pi`, and `a1 sandbox` commands may run in separate terminals at the same time. Closing one command closes only its own UI/Pi process and everything it spawned.
 
 ## Develop
 
 ```sh
-npm ci
-npm run build
-npm start
-```
-
-`npm start` gives each invocation isolated A1 development state and an isolated development Pi profile. Use `npm start -- --print-environment` to inspect the selected paths without launching the UI.
-
-A1 control state uses `%APPDATA%\\A1` and `%LOCALAPPDATA%\\A1` on Windows, and the `a1` directory under XDG config/data/runtime roots on Unix. Override it only with declared `A1_*` variables such as `A1_CONFIG_DIR`, `A1_DATA_DIR`, `A1_RUNTIME_DIR`, `A1_DATABASE_PATH`, and `A1_ENDPOINT`. Pi profile roots remain `~/.a1/agent`, `~/.pi/agent`, and `~/.a1/sandbox`. This is a no-migration identity hard cut; see [`docs/architecture/toolchain.md`](docs/architecture/toolchain.md#identity-hard-cut-and-cleanup) before removing obsolete control state.
-
-### Worktree lifecycle
-
-The primary worktree stays on `develop` and is integration-only. Each task uses a detached worktree under the repository's ignored `.worktrees/` directory, based on current `origin/develop` unless another base is selected.
-
-```sh
-git fetch origin --prune
-git worktree add --detach .worktrees/<task-id> origin/develop
-cd .worktrees/<task-id>
+npm ci              # install exact locked dependencies
+npm run build       # compile TypeScript and the process guardian into dist
+npm start           # build and launch an isolated development instance
+npm run test:fast   # typecheck + fast suite, no build needed
+npm test            # same as test:fast
+npm run test:full   # complete non-physical suite
 ```
 
-Commit and validate coherent work there. Because `develop` is protected, push the detached commit to one temporary remote branch and merge one pull request for the requested change. After merge, update the primary worktree and remove the task worktree only when its commits are reachable from `develop`:
+## Release
 
 ```sh
-git push origin HEAD:refs/heads/<task-id>
-gh pr create --base develop --head <task-id>
-# After the pull request is merged:
-cd <repository-root>
-git fetch origin --prune
-git merge --ff-only origin/develop
-git worktree remove .worktrees/<task-id>
-git worktree prune
+npm run release:next   # publish current develop tip to npm next via trusted CI workflows
 ```
-
-Manual acceptance does not leave a permanent validation checkout. Once acceptance is recorded, archive the completed OpenSpec change, integrate the archive commit into `develop`, then remove and prune every task or acceptance worktree retained for that change. Never remove a worktree before all of its implementation, acceptance, and archive commits are reachable from `develop`.
-
-Local package archives and ad hoc test builds belong under `.builds/`, never in the repository root. For manual package tests, use:
-
-```sh
-mkdir -p .builds
-npm pack --ignore-scripts --pack-destination .builds
-```
-
-Run the non-desktop gates with:
-
-```sh
-npm run typecheck
-npm run check:architecture
-npm run check:deprecated
-npm test
-npm run test:release
-```
-
-Automated physical-terminal interaction must never run on an active workstation. Future physical certification may run only on dedicated disposable workers or VMs with exclusive test desktops.
-
-## Releases
-
-An exact manually accepted `-dev.N` candidate may publish under npm tag `next` after applicable non-desktop gates pass. Such a preview is explicitly uncertified, cannot move `latest`, and cannot claim stable terminal parity or platform support. Stable claims require deferred physical and cross-platform certification against the exact package.
-
-Trusted preview publication uses `.github/workflows/publish-next.yml` and npm provenance. Local release mechanics are documented in [`docs/architecture/toolchain.md`](docs/architecture/toolchain.md).
-
-## Architecture
-
-- [`docs/architecture/boundaries.md`](docs/architecture/boundaries.md)
-- [`docs/architecture/toolchain.md`](docs/architecture/toolchain.md)
-- [`docs/manual-transparent-checkpoint.md`](docs/manual-transparent-checkpoint.md)
-- [`docs/features/launch-profiles.md`](docs/features/launch-profiles.md)

package/bin/{a1-guardian.js → guardian.js}

@@ -10,7 +10,7 @@ const profileId = process.env.A1_LAUNCH_PROFILE ?? "a1";
 runLaunchGuardian({
   profileId,
   releaseRoot,
-  uiEntry: resolve(releaseRoot, "bin", "a1-ui.js"),
+  uiEntry: resolve(releaseRoot, "bin", "ui.js"),
   environment: process.env,
   cwd: process.cwd(),
 }).then(

package/bin/{a1-ui.js → ui.js}

@@ -3,21 +3,14 @@
 const { runSelectedInteractiveRuntime } = await import("../dist/src/features/launch/index.js");
 
 runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
-  ownedUi: async profileId => {
+  ownedUi: async (profileId, ownedSurfaces) => {
     const [{ runOwnedUi }, { composeOwnedUi }] = await Promise.all([
       import("../dist/src/features/owned-ui/index.js"),
       import("../dist/src/composition/index.js"),
     ]);
-    // A1_OWNED_SURFACES=off presents pinned Pi's interface through A1's own
-    // rendering and input, which is what the parity comparison measures.
-    const ownedSurfaces = process.env.A1_OWNED_SURFACES === "off" ? "off" : "on";
     const { application, settings } = await composeOwnedUi({ cwd: process.cwd(), profileId, ownedSurfaces });
     return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
   },
-  transparent: async profileId => {
-    const { runSelectedTransparentRuntime } = await import("../dist/src/composition/transparent-runtime.js");
-    return await runSelectedTransparentRuntime(profileId);
-  },
 }).then(
   code => { process.exitCode = code; },
   error => {

package/dist/native/darwin-arm64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "unsupported",
-  "builtAt": "2026-08-22T13:11:56.818Z",
+  "builtAt": "2026-08-23T08:07:45.115Z",
   "artifact": {
-    "filename": "a1-process-guardian",
-    "sha256": "bb07d029b67a5eae4fbf3dea64f96cdf03462920949f2ea7e9e7b1bd33dbabc1",
+    "filename": "process-guardian",
+    "sha256": "7524bf568992517f50ed53196c861c5edeba0d7275633bb4735ab45bd5963a28",
     "size": 356368
   },
   "provenance": {

package/dist/native/linux-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-22T13:12:07.615Z",
+  "builtAt": "2026-08-23T08:07:37.399Z",
   "artifact": {
-    "filename": "a1-process-guardian",
-    "sha256": "f66cc7ac6d30ad424bc00992e4c5425259d36f055893d872eda9cf518bdb2ed0",
+    "filename": "process-guardian",
+    "sha256": "29e22fe29de2828982bc67ef418c4adcaab1490281477b7bea592ec6fe621bcd",
     "size": 415696
   },
   "provenance": {

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-22T13:12:29.999Z",
+  "builtAt": "2026-08-23T08:08:17.265Z",
   "artifact": {
-    "filename": "a1-process-guardian.exe",
-    "sha256": "83641a8a264dae32e57020ef1f37823ffe186b5acd28df18eae1afa80d25854c",
+    "filename": "process-guardian.exe",
+    "sha256": "a803cf8cc8bb6143d2adb7378183d4366a6bb880e110786ebeb7e778b64b6c59",
     "size": 172544
   },
   "provenance": {

package/dist/src/composition/index.js

@@ -5,7 +5,7 @@ import { assertPresentationComponent, assertPresentationRuntime, } from "../foun
 import { OwnedUiSessionShell } from "../foundation/pi-owned-ui-integration/index.js";
 import { OwnedUiSettingsSession, OwnedUiSettingsStore } from "../foundation/owned-ui-settings/index.js";
 import { UiAppHost, UiAppRegistry } from "../foundation/ui-apps/index.js";
-import { getAvailablePiThemes, piTheme } from "../foundation/pi-component-adapter/index.js";
+import { applyConfiguredPiTheme, getAvailablePiThemes, piTheme } from "../foundation/pi-component-adapter/index.js";
 import { faint } from "../foundation/ui-components/index.js";
 import { SETTINGS_APP_ID, SETTINGS_ROUTE, SettingsApp } from "../features/owned-ui/index.js";
 import { resolveProductPaths } from "../foundation/lifecycle/index.js";
@@ -29,6 +29,9 @@ export async function composeOwnedUi(options = {}) {
             store: new OwnedUiSettingsStore({ configDir: resolveProductPaths().configDir, profileId: options.profileId }),
             agentProvider: () => adapter.settingsPort(),
         });
+    // Before anything is drawn, so every surface uses the configured theme rather
+    // than the one guessed from the terminal's background.
+    applyConfiguredPiTheme(adapter.configuredTheme());
     const routeHost = settings === null || options.ownedSurfaces === "off" ? null : createOwnedRouteHost(settings);
     const shell = new OwnedUiSessionShell({
         backend: adapter,
@@ -243,6 +246,9 @@ function pinnedTheme() {
     return {
         fg: (token, text) => piTheme().fg(token, text),
         bold: (text) => piTheme().bold(text),
+        // Unpainted, so a list reads against the terminal the reader actually has
+        // rather than against the background the configured theme was built for.
+        plain: (text) => text,
         // Quiet, and quieter again: the terminal's own faint attribute over the
         // dimmest colour the theme has.
         disabled: (text) => faint(piTheme().fg("dim", text)),

package/dist/src/features/launch/initialize-profile.js

@@ -38,7 +38,7 @@ async function ensureSafeDirectoryChain(root) {
         current = parent;
     }
     for (const path of missing.reverse())
-        await mkdir(path, { mode: 0o700 });
+        await createOwnedDirectory(path, "profile path");
 }
 async function ensureOwnedDirectory(path) {
     const metadata = await lstat(path).catch(error => {
@@ -51,7 +51,28 @@ async function ensureOwnedDirectory(path) {
             throw new Error(`profile resource path is not an owned directory: ${path}`);
         return;
     }
-    await mkdir(path, { mode: 0o700 });
+    await createOwnedDirectory(path, "profile resource path");
+}
+/**
+ * Creates a directory, treating "it already exists" as another launch having won
+ * the race rather than as a failure — but still refusing what it finds if that is
+ * not an owned directory.
+ */
+async function createOwnedDirectory(path, subject) {
+    try {
+        await mkdir(path, { mode: 0o700 });
+        return;
+    }
+    catch (error) {
+        if (!isAlreadyThere(error))
+            throw error;
+    }
+    const metadata = await lstat(path);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error(`${subject} is not an owned directory: ${path}`);
+}
+function isAlreadyThere(error) {
+    return typeof error === "object" && error !== null && error.code === "EEXIST";
 }
 function isMissing(error) {
     return error instanceof Error && "code" in error && error.code === "ENOENT";

package/dist/src/features/launch/profiles.d.ts

@@ -7,6 +7,6 @@ export interface LaunchProfileContract {
     readonly productSurface: "agent" | "vanilla-baseline" | "isolated-profile";
     readonly configurationRootPolicy: ConfigurationRootPolicy;
     readonly projectTrust: ProjectTrustPolicy;
-    readonly terminalCapability: "owned-ui" | "transparent";
+    readonly terminalCapability: "owned-ui";
 }
 export declare function launchProfileContract(id: LaunchProfileId): LaunchProfileContract;

package/dist/src/features/launch/profiles.js

@@ -11,14 +11,14 @@ const contracts = Object.freeze({
         productSurface: "vanilla-baseline",
         configurationRootPolicy: "pi-default",
         projectTrust: "pi-default",
-        terminalCapability: "transparent",
+        terminalCapability: "owned-ui",
     }),
     sandbox: Object.freeze({
         id: "sandbox",
         productSurface: "isolated-profile",
         configurationRootPolicy: "sandbox-profile",
         projectTrust: "ignore",
-        terminalCapability: "transparent",
+        terminalCapability: "owned-ui",
     }),
 });
 export function launchProfileContract(id) {

package/dist/src/features/launch/runtime-selection.d.ts

@@ -1,15 +1,19 @@
 import { type LaunchProfileId } from "../../foundation/lifecycle/index.js";
-export type TransparentInteractiveProfileId = Exclude<LaunchProfileId, "a1">;
-export type InteractiveRuntimeSelection = {
+/**
+ * Every interactive command is the same composition. What differs is the
+ * configuration root each one reads and whether A1's own screens are reachable:
+ * bare `a1` is the product, while `a1 pi` and `a1 sandbox` present pinned Pi's
+ * interface and nothing of A1's own, against Pi's own profile and against an
+ * isolated one.
+ */
+export type OwnedUiProfileId = LaunchProfileId;
+export interface InteractiveRuntimeSelection {
     readonly kind: "owned-ui";
-    readonly profileId: Extract<LaunchProfileId, "a1">;
-} | {
-    readonly kind: "transparent";
-    readonly profileId: TransparentInteractiveProfileId;
-};
+    readonly profileId: OwnedUiProfileId;
+    readonly ownedSurfaces: "on" | "off";
+}
 export interface InteractiveRuntimeRunners {
-    readonly ownedUi: (profileId: Extract<LaunchProfileId, "a1">) => Promise<number>;
-    readonly transparent: (profileId: TransparentInteractiveProfileId) => Promise<number>;
+    readonly ownedUi: (profileId: OwnedUiProfileId, ownedSurfaces: "on" | "off") => Promise<number>;
 }
 export declare function selectInteractiveRuntime(profileId: string): InteractiveRuntimeSelection;
 export declare function runSelectedInteractiveRuntime(profileId: string, runners: InteractiveRuntimeRunners): Promise<number>;

package/dist/src/features/launch/runtime-selection.js

@@ -1,13 +1,13 @@
 import { assertLaunchProfileId } from "../../foundation/lifecycle/index.js";
 export function selectInteractiveRuntime(profileId) {
     assertLaunchProfileId(profileId);
-    return profileId === "a1"
-        ? Object.freeze({ kind: "owned-ui", profileId: "a1" })
-        : Object.freeze({ kind: "transparent", profileId });
+    return Object.freeze({
+        kind: "owned-ui",
+        profileId,
+        ownedSurfaces: profileId === "a1" ? "on" : "off",
+    });
 }
 export async function runSelectedInteractiveRuntime(profileId, runners) {
     const selection = selectInteractiveRuntime(profileId);
-    return selection.kind === "owned-ui"
-        ? await runners.ownedUi(selection.profileId)
-        : await runners.transparent(selection.profileId);
+    return await runners.ownedUi(selection.profileId, selection.ownedSurfaces);
 }

package/dist/src/features/owned-ui/settings-app.js

@@ -208,10 +208,12 @@ export class SettingsApp {
             const overRow = menuRowAt(frame, event.row - 1, event.column);
             const overMenu = overRow !== null;
             if (event.kind === "motion") {
-                // While the menu is open it owns the pointer: the row under it lights up,
-                // and nothing behind it hovers.
-                const hadHover = this.#hoverKey !== null;
-                this.#hoverKey = null;
+                // The menu owns the pointer, but the row it came from is still the thing
+                // being changed, so its value keeps reading as the one under the pointer.
+                // Only a dialog that takes the screen puts that out.
+                const hadHover = this.#hoverKey !== menu.anchorKey || this.#hoverRegion !== "value";
+                this.#hoverKey = menu.anchorKey;
+                this.#hoverRegion = "value";
                 if (!overMenu) {
                     const cleared = menu.index !== -1;
                     menu.index = -1;

package/dist/src/foundation/pi-component-adapter/index.d.ts

@@ -3,7 +3,7 @@ export * from "./conformance.js";
 export * from "./shell-components.js";
 export * from "./theme.js";
 export * from "./upstream/theme/theme-controller.js";
-export { getAvailablePiThemes } from "./upstream/theme/theme.js";
+export { applyConfiguredPiTheme, getAvailablePiThemes } from "./upstream/theme/theme.js";
 export * from "./upstream/components/countdown-timer.js";
 export * from "./upstream/components/extension-editor.js";
 export * from "./upstream/components/session-selector.js";

package/dist/src/foundation/pi-component-adapter/index.js

@@ -3,7 +3,7 @@ export * from "./conformance.js";
 export * from "./shell-components.js";
 export * from "./theme.js";
 export * from "./upstream/theme/theme-controller.js";
-export { getAvailablePiThemes } from "./upstream/theme/theme.js";
+export { applyConfiguredPiTheme, getAvailablePiThemes } from "./upstream/theme/theme.js";
 export * from "./upstream/components/countdown-timer.js";
 export * from "./upstream/components/extension-editor.js";
 export * from "./upstream/components/session-selector.js";

package/dist/src/foundation/pi-component-adapter/upstream/theme/theme.d.ts

@@ -51,3 +51,11 @@ export declare function resolvePiThemeSetting(setting: string | undefined, termi
 export declare function detectPiTerminalBackgroundFromEnv(environment?: NodeJS.ProcessEnv): PiTerminalThemeDetection;
 export declare function detectPiTerminalBackgroundTheme(ui: PiTerminalThemeDetector, timeoutMs: number, environment?: NodeJS.ProcessEnv): Promise<PiTerminalThemeDetection>;
 export declare function detectPiTerminalThemeForAuto(ui: PiTerminalThemeDetector, timeoutMs: number, environment?: NodeJS.ProcessEnv): Promise<PiTerminalTheme>;
+/**
+ * Applies the theme the reader configured, as the engine does at startup. The
+ * setting is either a theme's name or the `light/dark` pair meaning "follow the
+ * terminal", and only the pair consults the terminal's own background. An
+ * unreadable or absent setting falls back to that detection, which is what the
+ * engine does with an unset theme.
+ */
+export declare function applyConfiguredPiTheme(setting: string | undefined): PiThemeResult;

package/dist/src/foundation/pi-component-adapter/upstream/theme/theme.js

@@ -312,3 +312,15 @@ function ansi256ToHex(index) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * Applies the theme the reader configured, as the engine does at startup. The
+ * setting is either a theme's name or the `light/dark` pair meaning "follow the
+ * terminal", and only the pair consults the terminal's own background. An
+ * unreadable or absent setting falls back to that detection, which is what the
+ * engine does with an unset theme.
+ */
+export function applyConfiguredPiTheme(setting) {
+    const detected = detectPiTerminalBackgroundFromEnv();
+    const resolved = resolvePiThemeSetting(setting, detected.theme);
+    return applyPiTheme(resolved ?? detected.theme);
+}

package/dist/src/foundation/pi-engine-adapter/adapter.d.ts

@@ -113,6 +113,11 @@ export declare class PiEngineAdapter {
     unbindExtensionUi(): Promise<void>;
     workflowAutocompleteCommands(): readonly PiWorkflowAutocompleteCommand[];
     cycleModelWorkflow(direction: "forward" | "backward"): Promise<PiWorkflowResult>;
+    /**
+     * The theme the engine is configured with, in the engine's own grammar: a
+     * theme's name, or a `light/dark` pair meaning "follow the terminal".
+     */
+    configuredTheme(): string | undefined;
     /** Settings port for the live runtime, or null before the runtime is available. */
     settingsPort(): AgentSettingsPort | null;
     pinnedModelSelectorContext(): {

package/dist/src/foundation/pi-engine-adapter/adapter.js

@@ -380,6 +380,13 @@ export class PiEngineAdapter {
             return workflowResult("model", "failed", error instanceof Error ? error.message : String(error));
         }
     }
+    /**
+     * The theme the engine is configured with, in the engine's own grammar: a
+     * theme's name, or a `light/dark` pair meaning "follow the terminal".
+     */
+    configuredTheme() {
+        return this.#runtime?.services.settingsManager.getThemeSetting();
+    }
     /** Settings port for the live runtime, or null before the runtime is available. */
     settingsPort() {
         const settings = this.#runtime?.services.settingsManager;

package/dist/src/foundation/pi-engine-adapter/settings-integration.d.ts

@@ -17,8 +17,6 @@ export interface PiSettingsProviders {
  * entry per terminal appearance.
  */
 export declare const AUTOMATIC_THEME = "automatic";
-export declare const LIGHT_THEME_KEY = "themeLight";
-export declare const DARK_THEME_KEY = "themeDark";
 interface AutomaticTheme {
     readonly light: string;
     readonly dark: string;

package/dist/src/foundation/pi-engine-adapter/settings-integration.js

@@ -7,8 +7,9 @@ import piSettingsMetadata from "./pi-settings-metadata.json" with { type: "json"
  * entry per terminal appearance.
  */
 export const AUTOMATIC_THEME = "automatic";
-export const LIGHT_THEME_KEY = "themeLight";
-export const DARK_THEME_KEY = "themeDark";
+/** The themes an automatic setting names for each terminal appearance. */
+const LIGHT_APPEARANCE_THEME = "light";
+const DARK_APPEARANCE_THEME = "dark";
 const THEME_KEY = "theme";
 const THINKING_KEY = "thinkingLevel";
 /** A stored theme is automatic when it names one theme per terminal appearance. */
@@ -47,10 +48,6 @@ export function settingsInventoryDrift(presented, mapped) {
     };
 }
 /** What the engine offers for a setting, as the strings it words them with. */
-/** One appearance of an automatic theme, offered as an ordinary setting. */
-function appearance(key, label, description, themes) {
-    return { key, valueType: "enum", writable: true, choices: themes, label, description, resolvedWhenRead: true };
-}
 function offered(key) {
     return PRESENTATION.settings[key]?.values ?? [];
 }
@@ -95,15 +92,9 @@ export class PiSettingsIntegration {
         })
             .map(descriptor => this.#resolved(descriptor))
             .sort((left, right) => rank(left.key) - rank(right.key));
-        const pair = parseAutomaticTheme(this.#storedTheme());
-        if (pair === null)
-            return listed;
-        const themes = this.#themes();
-        return [
-            ...listed,
-            appearance(LIGHT_THEME_KEY, "Light theme", "Theme to use in automatic mode when the terminal is light", themes),
-            appearance(DARK_THEME_KEY, "Dark theme", "Theme to use in automatic mode when the terminal is dark", themes),
-        ];
+        // Following the terminal is one choice on the theme itself, not two further
+        // settings: the pair behind it is the engine's grammar, not a reader's task.
+        return listed;
     }
     /** Overlays the values a setting can only offer once something is running. */
     #resolved(descriptor) {
@@ -129,20 +120,16 @@ export class PiSettingsIntegration {
         return typeof stored === "string" ? stored : "";
     }
     async readSetting(key) {
-        if (key === THEME_KEY || key === LIGHT_THEME_KEY || key === DARK_THEME_KEY) {
+        if (key === THEME_KEY) {
             const pair = parseAutomaticTheme(this.#storedTheme());
-            if (key === THEME_KEY)
-                return pair === null ? this.#operations.get(key)?.read() : AUTOMATIC_THEME;
-            if (pair === null)
-                return undefined;
-            return key === LIGHT_THEME_KEY ? pair.light : pair.dark;
+            return pair === null ? this.#operations.get(key)?.read() : AUTOMATIC_THEME;
         }
         return this.#operations.get(key)?.read();
     }
     async writeSetting(key, value) { this.writeSettingNow(key, value); }
     writeSettingNow(key, value) {
-        if (typeof value === "string" && (key === THEME_KEY || key === LIGHT_THEME_KEY || key === DARK_THEME_KEY)) {
-            this.#writeTheme(key, value);
+        if (typeof value === "string" && key === THEME_KEY) {
+            this.#writeTheme(value);
             return;
         }
         const operation = this.#operations.get(key);
@@ -151,26 +138,26 @@ export class PiSettingsIntegration {
         operation.write(value);
     }
     /**
-     * Composes the stored theme from the part that changed. Turning automatic on
-     * starts from the theme already in use for both appearances, which is where
-     * the engine's own editor starts too.
+     * Writes the theme in the engine's own grammar. Following the terminal is
+     * stored as the pair the engine reads for it, made of the themes named for
+     * each appearance when they are installed; where they are not, the theme
+     * already in use stands for both, so the setting still round-trips.
      */
-    #writeTheme(key, value) {
+    #writeTheme(value) {
         const theme = this.#operations.get(THEME_KEY);
         if (!theme)
-            throw new Error(`setting is unavailable: ${key}`);
-        const current = this.#storedTheme();
-        const pair = parseAutomaticTheme(current);
-        if (key === THEME_KEY) {
-            if (value !== AUTOMATIC_THEME)
-                theme.write(value);
-            else if (pair === null)
-                theme.write(`${current}/${current}`);
+            throw new Error(`setting is unavailable: ${THEME_KEY}`);
+        if (value !== AUTOMATIC_THEME) {
+            theme.write(value);
             return;
         }
-        if (pair === null)
+        if (parseAutomaticTheme(this.#storedTheme()) !== null)
             return;
-        theme.write(key === LIGHT_THEME_KEY ? `${value}/${pair.dark}` : `${pair.light}/${value}`);
+        const installed = this.#themes();
+        const current = this.#storedTheme();
+        const light = installed.includes(LIGHT_APPEARANCE_THEME) ? LIGHT_APPEARANCE_THEME : current;
+        const dark = installed.includes(DARK_APPEARANCE_THEME) ? DARK_APPEARANCE_THEME : current;
+        theme.write(`${light}/${dark}`);
     }
     async flush() { await this.settings.flush(); }
 }

package/dist/src/foundation/release/bootstrap.js

@@ -138,7 +138,7 @@ export async function certifyMaterializedRelease(release, dataDir, verification
     return path;
 }
 export async function startSupervisor(release, environment) {
-    const entry = await resolveReleaseEntryPoint(release, "bin/a1-supervisor.js");
+    const entry = await resolveReleaseEntryPoint(release, "bin/supervisor.js");
     const child = spawn(process.execPath, [entry], {
         detached: true,
         env: releaseEnvironment(environment, release),
@@ -152,7 +152,7 @@ export async function startSupervisor(release, environment) {
     child.unref();
 }
 async function launchUi(release, environment) {
-    const entry = await resolveReleaseEntryPoint(release, "bin/a1-guardian.js");
+    const entry = await resolveReleaseEntryPoint(release, "bin/guardian.js");
     return await new Promise((resolvePromise, rejectPromise) => {
         const child = spawn(process.execPath, [entry], {
             env: releaseEnvironment(environment, release),

package/dist/src/foundation/ui-components/list-view.js

@@ -23,21 +23,21 @@ export function renderGroupHeader(title, width, theme) {
 export function renderListRow(row, state, valueColumn, width, theme) {
     const cursor = state.selected ? "→ " : "  ";
     const leftRaw = `${cursor}  ${row.label}`;
-    const left = `${theme.fg("accent", cursor)}  ${theme.fg(state.selected ? "accent" : "text", row.label)}`;
+    const left = `${theme.fg("accent", cursor)}  ${state.selected ? theme.fg("accent", row.label) : theme.plain(row.label)}`;
     const gap = Math.max(2, valueColumn - displayWidth(leftRaw));
     // Pointing anywhere on the row is pointing at the item; pointing at the value
     // is what brightens it. The selection speaks through the label alone.
     const valueHovered = state.hovered && state.region !== "label";
     const stepper = row.stepper !== undefined && valueHovered;
-    const value = theme.fg(valueHovered ? "text" : "muted", row.value);
+    const value = valueHovered ? theme.plain(row.value) : theme.fg("muted", row.value);
     const minus = stepper
         ? row.stepper?.lower === true
-            ? theme.fg(state.region === "minus" ? "text" : "dim", "- ")
+            ? state.region === "minus" ? theme.plain("- ") : theme.fg("dim", "- ")
             : theme.disabled("- ")
         : "";
     const plus = stepper
         ? row.stepper?.raise === true
-            ? theme.fg(state.region === "plus" ? "text" : "dim", " +")
+            ? state.region === "plus" ? theme.plain(" +") : theme.fg("dim", " +")
             : theme.disabled(" +")
         : "";
     const indent = Math.max(2, stepper ? gap - STEPPER_RESERVE : gap);

package/dist/src/foundation/ui-components/theme.d.ts

@@ -6,6 +6,12 @@ export type UiThemeToken = "accent" | "text" | "muted" | "dim" | "border" | "err
 export interface UiTheme {
     fg(token: UiThemeToken, text: string): string;
     bold(text: string): string;
+    /**
+     * The terminal's own foreground, left unpainted. What a list's own text is:
+     * a theme built for a light background would otherwise write near-black rows
+     * into a dark terminal, which is how the engine leaves its lists too.
+     */
+    plain(text: string): string;
     /** Inverted styling for the active row of a floating surface. */
     highlight(text: string): string;
     /** A control that is present but cannot act: quieter than quiet text. */

package/dist/src/foundation/ui-components/theme.js

@@ -6,6 +6,7 @@
 export const PLAIN_THEME = Object.freeze({
     fg: (_token, text) => text,
     bold: (text) => text,
+    plain: (text) => text,
     highlight: (text) => text,
     disabled: (text) => text,
     panel: (text) => text,