@timurproko/a1 0.2.7-dev.1288 → 0.2.7-dev.1290

package/README.md

@@ -99,6 +99,10 @@ a1 pi
 
 <p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/separator-dark.svg"><img src="docs/assets/readme/separator.svg" alt="" width="280"></picture></p>
 
+## Session colors
+
+Settings → Appearance separates a saved **Default color** (initially blue) from **Current color**, which affects only this session. Both offer blue, green, orange, pink, purple, cyan, and grey. External applications can read and change a targeted session through the [always-JSON local color API](docs/features/session-colors.md).
+
 ## Update
 
 Update on the channel you already use (release stays on release, develop stays on develop):

package/bin/cli.js

@@ -54,6 +54,10 @@ process.exitCode = await dispatchCli(process.argv.slice(2), {
     const { createPiPackagesPort } = await import("../dist/integrations/pi/engine/package-integration.js");
     return await runPackageCommand(request, { createPort: createPiPackagesPort });
   },
+  sessionColor: async arguments_ => {
+    const { runSessionColorCommand } = await import("../dist/cli/session-color.js");
+    return await runSessionColorCommand(arguments_);
+  },
   sessionContext: async request => {
     const { runSessionContextCommand } = await import("../dist/cli/session-context.js");
     return await runSessionContextCommand(request);

package/dist/cli/capabilities.d.ts

@@ -1,6 +1,7 @@
 /** The Pi comparison launch is a prerelease development instrument, not product. */
 export interface CliCapabilities {
     readonly developmentComparison: boolean;
+    readonly sessionColors?: boolean;
     /** Bare `update` stays on this build's channel; absent means stable. */
     readonly runningChannel?: "stable" | "next";
 }

package/dist/cli/capabilities.js

@@ -1,7 +1,7 @@
 import { prerelease } from "semver";
 export function cliCapabilities(version) {
     const development = isPrereleaseVersion(version);
-    return Object.freeze({ developmentComparison: development, runningChannel: development ? "next" : "stable" });
+    return Object.freeze({ developmentComparison: development, sessionColors: true, runningChannel: development ? "next" : "stable" });
 }
 export function isPrereleaseVersion(version) {
     return (prerelease(version)?.length ?? 0) > 0;

package/dist/cli/dispatch.d.ts

@@ -10,6 +10,7 @@ export interface CliHandlers {
     readonly update: (channel: UpdateChannel, target?: string) => Promise<number>;
     readonly packages: (request: PackageCommandRequest) => Promise<number>;
     readonly sessionContext: (request: SessionContextRequest) => Promise<number>;
+    readonly sessionColor?: (arguments_: readonly string[]) => Promise<number>;
     /** Removes A1 from the machine; absent in hosts that cannot uninstall. */
     readonly uninstall?: (request: {
         readonly yes: boolean;
@@ -51,6 +52,9 @@ export type CliCommand = {
 } | {
     readonly kind: "session-context";
     readonly request: SessionContextRequest;
+} | {
+    readonly kind: "session-color";
+    readonly arguments: readonly string[];
 } | {
     readonly kind: "uninstall";
     readonly request: {

package/dist/cli/dispatch.js

@@ -25,6 +25,7 @@ export function cliUsage(capabilities) {
         "worktree detach",
         "worktree complete [--change <id>] [--pr <number>]",
         "worktree list",
+        "session color list | get [--session <id>] | set <color> [--session <id>]",
         "session worktrees",
         "session link-worktree <path>",
         "session unlink-worktree",
@@ -63,6 +64,11 @@ export function cliHelp(capabilities) {
         `  ${command} worktree complete [--change <id>] [--pr <number>]`,
         `  ${command} worktree list`,
         "",
+        "Session colors (always JSON; explicit session id required outside the session shell):",
+        `  ${command} session color list`,
+        `  ${command} session color get --session <id>`,
+        `  ${command} session color set <color> --session <id>`,
+        "",
         "Session context (compatibility aliases):",
         `  ${command} session worktrees`,
         `  ${command} session link-worktree <path>`,
@@ -99,6 +105,12 @@ export async function dispatchCli(arguments_, handlers, output, capabilities) {
         return await handlers.packages(command.request);
     if (command.kind === "session-context")
         return await handlers.sessionContext(command.request);
+    if (command.kind === "session-color") {
+        if (handlers.sessionColor)
+            return await handlers.sessionColor(command.arguments);
+        output.stdout(`${JSON.stringify({ error: { code: "control-unavailable", message: "Session color API is unavailable in this host." } })}\n`);
+        return 1;
+    }
     if (command.kind === "uninstall")
         return handlers.uninstall ? await handlers.uninstall(command.request) : 2;
     return await handlers.update(command.channel, command.target);
@@ -137,6 +149,8 @@ export function parseCliCommand(arguments_, capabilities) {
         return parseUpdate(rest, capabilities.runningChannel ?? "stable");
     if (command === "worktree")
         return parseWorktree(rest);
+    if (command === "session" && rest[0] === "color")
+        return { kind: "session-color", arguments: rest.slice(1) };
     if (command === "session")
         return parseSessionContext(rest);
     if (command?.startsWith("update:"))

package/dist/cli/session-color.d.ts

@@ -0,0 +1,6 @@
+interface ColorCommandOptions {
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly stdout?: (message: string) => void;
+}
+export declare function runSessionColorCommand(arguments_: readonly string[], options?: ColorCommandOptions): Promise<number>;
+export {};

package/dist/cli/session-color.js

@@ -0,0 +1,44 @@
+import { UI_ACCENT_COLORS } from "../contracts/owned-ui/index.js";
+import { requestSessionControl, resolveProductPaths } from "../foundation/lifecycle/index.js";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../product-identity.js";
+const failure = (code, message) => Object.assign(new Error(message), { code });
+export async function runSessionColorCommand(arguments_, options = {}) {
+    const stdout = options.stdout ?? (message => process.stdout.write(message));
+    const environment = options.environment ?? process.env;
+    try {
+        const [action, ...rest] = arguments_;
+        if (action === "help" || action === "--help" || action === "-h") {
+            stdout(`${PRODUCT_TEXT.commandName} session color list | get [--session <id>] | set <color> [--session <id>]\nAlways JSON; get/set target Current color only. Outside an A1 shell, --session is required.\n`);
+            return 0;
+        }
+        if (action === "list" && rest.length === 0) {
+            stdout(`${JSON.stringify({ colors: UI_ACCENT_COLORS })}\n`);
+            return 0;
+        }
+        if (action !== "get" && action !== "set")
+            throw failure("invalid-request", "Use session color list, get, or set <color>.");
+        const color = action === "set" ? rest.shift() : undefined;
+        if (action === "set" && !UI_ACCENT_COLORS.includes(color))
+            throw failure("invalid-color", "Choose blue, green, orange, pink, purple, cyan, or grey.");
+        if (rest.length !== 0 && (rest.length !== 2 || rest[0] !== "--session" || !rest[1]))
+            throw failure("invalid-request", "Expected only --session followed by a complete session id.");
+        const explicit = rest.length === 2;
+        const runtimeId = environment[PRODUCT_IDENTITY.environment.sessionRuntimeId];
+        const sessionId = explicit ? rest[1] : runtimeId && environment.PI_SESSION_FILE ? environment.PI_SESSION_ID : undefined;
+        if (!sessionId)
+            throw failure("session-required", "Supply --session <id> outside an exact A1 shell runtime.");
+        const result = await requestSessionControl({
+            runtimeDir: resolveProductPaths(environment).runtimeDir, sessionId,
+            ...(!explicit && runtimeId ? { runtimeId } : {}),
+            payload: { action, ...(color === undefined ? {} : { color }) },
+        });
+        stdout(`${JSON.stringify(result)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const detail = error;
+        const code = detail.code ?? "control-failed";
+        stdout(`${JSON.stringify({ error: { code, message: detail.message } })}\n`);
+        return ["invalid-request", "invalid-color", "invalid-session", "session-required"].includes(code) ? 2 : 1;
+    }
+}

package/dist/composition/owned-settings.d.ts

@@ -1,12 +1,12 @@
 import type { AgentSettingsPort } from "../contracts/agent-engine/index.js";
-import { OwnedSettingsManager } from "../ui/settings/manager.js";
+import type { OwnedSettingsManager } from "../ui/settings/manager.js";
 interface OwnedSettingsManagerFactoryOptions {
     readonly profileId: string;
     readonly agent?: AgentSettingsPort | null;
     readonly agentProvider?: () => AgentSettingsPort | null;
 }
 /** Builds the profile-global settings manager shared by the Agent and slim utility compositions. */
-export declare function createOwnedSettingsManager(options: OwnedSettingsManagerFactoryOptions): OwnedSettingsManager;
+export declare function createOwnedSettingsManager(options: OwnedSettingsManagerFactoryOptions): Promise<OwnedSettingsManager>;
 /** Rereads the shared settings document whenever its stat changes; returns the stop. */
 export declare function watchSharedSettings(settings: Pick<OwnedSettingsManager, "file" | "refresh">): () => void;
 export {};

package/dist/composition/owned-settings.js

@@ -1,9 +1,9 @@
 import { statSync } from "node:fs";
 import { resolveLaunchProfilePaths } from "../features/launch/profile-paths.js";
 import { PRODUCT_IDENTITY } from "../product-identity.js";
-import { OwnedSettingsManager } from "../ui/settings/manager.js";
 /** Builds the profile-global settings manager shared by the Agent and slim utility compositions. */
-export function createOwnedSettingsManager(options) {
+export async function createOwnedSettingsManager(options) {
+    const { OwnedSettingsManager } = await import("../ui/settings/manager.js");
     const profilePaths = resolveLaunchProfilePaths();
     return new OwnedSettingsManager({
         profileDir: profilePaths.agentProfile,

package/dist/composition/owned-ui.js

@@ -39,7 +39,7 @@ export async function composeOwnedUi(options = {}) {
     let backend;
     const settings = options.profileId === undefined
         ? null
-        : createOwnedSettingsManager({
+        : await createOwnedSettingsManager({
             profileId: options.profileId,
             agentProvider: () => backend.settingsPort(),
         });
@@ -72,18 +72,12 @@ export async function composeOwnedUi(options = {}) {
         ...(options.packageVersion === undefined ? {} : { packageVersion: options.packageVersion }),
         ...(options.profileId === undefined ? {} : { profileId: options.profileId }),
     });
-    const unsubscribeAccentChange = bareSettings === null
-        ? () => { }
-        : bareSettings.onChange(current => {
-            const accent = current.value("accentColor");
-            host.setAccentColor(accent);
-        });
-    // Rationale: separate A1 processes share one settings document; a live scope change saved in
-    // one reaches the others only by rereading that document.
+    const sessionColor = bindSessionColor(backend, bareSettings, color => host.setAccentColor(color), productPaths.runtimeDir);
+    // Rationale: peer refresh shares persisted preferences, never session-local Current color.
     const unwatchSharedSettings = bareSettings === null
         ? () => { }
         : watchSharedSettings(bareSettings);
-    const unsubscribeAccent = () => { unwatchSharedSettings(); unsubscribeAccentChange(); };
+    const unsubscribeAccent = async () => { unwatchSharedSettings(); await sessionColor.dispose(); };
     // Invariant: the Settings search and agent prompt borrow the same resolved Pi keybindings.
     const keybindingsHost = createPiKeybindingsHost({ profile: bare ? "a1" : "pi", agentDir: backend.identity.agentDir });
     // Rationale: Routes open only after shell construction.
@@ -118,7 +112,7 @@ export async function composeOwnedUi(options = {}) {
     const releaseShared = async () => {
         naming.dispose();
         clipboardServices?.dispose();
-        unsubscribeAccent();
+        await unsubscribeAccent();
         await sessionRuntimes.dispose();
         await releaseNote.releaseClaim();
         suggestionDiagnostics?.dispose();
@@ -184,6 +178,7 @@ export async function composeOwnedUi(options = {}) {
                 exitNotice = import("../app/session-shell/exit-notice.js")
                     .then(module => module.armExitNotice(backend, exitNoticePath), () => null);
             presenter.start();
+            sessionColor.start();
             releaseUpdates.start();
         },
         flush: () => backend.session.flushEvents(),
@@ -204,6 +199,31 @@ export async function composeOwnedUi(options = {}) {
     };
     return { application, settings };
 }
+function bindSessionColor(backend, settings, apply, runtimeDir) {
+    if (settings === null)
+        return { start() { }, async dispose() { } };
+    let control = Promise.resolve(null);
+    let started = false, stopped = false;
+    const unsubscribe = settings.onChange(current => apply(current.value("accentColor")));
+    let binding = backend.identity.sessionBindingGeneration;
+    const unbind = backend.session.onEvent(() => {
+        if (binding === backend.identity.sessionBindingGeneration)
+            return;
+        binding = backend.identity.sessionBindingGeneration;
+        settings.startSession();
+    });
+    return {
+        start() {
+            if (started || stopped)
+                return;
+            started = true;
+            control = import("./session-colors.js").then(module => stopped ? null
+                : module.startSessionColorControl(backend, settings, runtimeDir, process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId]))
+                .catch(() => null);
+        },
+        async dispose() { stopped = true; unbind(); unsubscribe(); await (await control)?.dispose(); },
+    };
+}
 function spinnerPresenterOptions(settings) {
     return settings === null ? {} : { spinner: {
             snapshot: () => settings.value("spinnerStyle"),

package/dist/composition/session-colors.d.ts

@@ -0,0 +1,5 @@
+import { type OwnedUiSessionBackend } from "../contracts/owned-ui/index.js";
+import type { OwnedSettingsManager } from "../ui/settings/manager.js";
+export declare function startSessionColorControl(backend: OwnedUiSessionBackend, settings: OwnedSettingsManager, runtimeDir: string, runtimeId?: string): Promise<{
+    dispose: () => Promise<void>;
+}>;

package/dist/composition/session-colors.js

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import { UI_ACCENT_COLORS } from "../contracts/owned-ui/index.js";
+import { serveSessionControl } from "../foundation/lifecycle/session-control.js";
+export async function startSessionColorControl(backend, settings, runtimeDir, runtimeId = randomUUID()) {
+    const identity = () => ({ sessionId: backend.identity.currentHistorySessionId() ?? backend.identity.sessionId, binding: backend.identity.sessionBindingGeneration });
+    const control = await serveSessionControl({ runtimeDir, runtimeId, identity, handle: async (payload) => {
+            if (backend.identity.disposed)
+                throw Object.assign(new Error("The session is stopped."), { code: "session-unavailable" });
+            if (!payload || typeof payload !== "object")
+                throw Object.assign(new Error("Invalid color request."), { code: "invalid-request" });
+            const request = payload;
+            const sessionId = identity().sessionId;
+            if (request.action === "set") {
+                if (!UI_ACCENT_COLORS.includes(request.color))
+                    throw Object.assign(new Error("Unknown color."), { code: "invalid-color" });
+                const result = await settings.change("a1", "accentColor", request.color);
+                if (!result.applied)
+                    throw Object.assign(new Error(result.failure ?? "Color could not be applied."), { code: "control-failed" });
+                return { sessionId, color: result.effectiveValue };
+            }
+            if (request.action !== "get")
+                throw Object.assign(new Error("Unknown color action."), { code: "invalid-request" });
+            return { sessionId, color: settings.value("accentColor") };
+        } });
+    let stopped = false, binding = backend.identity.sessionBindingGeneration, publication = Promise.resolve();
+    const unsubscribe = backend.session.onEvent(() => {
+        if (stopped || binding === backend.identity.sessionBindingGeneration)
+            return;
+        binding = backend.identity.sessionBindingGeneration;
+        publication = publication.then(() => control.publish()).catch(() => { });
+    });
+    return { dispose: async () => { stopped = true; unsubscribe(); await publication; await control.dispose(); } };
+}

package/dist/contracts/owned-ui/index.d.ts

@@ -1,6 +1,6 @@
 export type { OwnedUiSessionNameState, OwnedUiSessionNameCompletion, OwnedUiSessionNamingPort } from "./session-naming.js";
-/** Stable stored choices for bare A1's semantic UI accent. */
-export type UiAccentColor = "purple" | "blue" | "cyan" | "green" | "orange" | "pink";
+export declare const UI_ACCENT_COLORS: readonly ["blue", "green", "orange", "pink", "purple", "cyan", "grey"];
+export type UiAccentColor = typeof UI_ACCENT_COLORS[number];
 export { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, assertOwnedUiExtensionUiPort, } from "./extension-ui.js";
 export type { OwnedUiExtensionAutocompleteItem, OwnedUiExtensionAutocompleteProvider, OwnedUiExtensionAutocompleteProviderFactory, OwnedUiExtensionAutocompleteSuggestions, OwnedUiExtensionComponent, OwnedUiExtensionComponentFactory, OwnedUiExtensionComponentFactoryContext, OwnedUiExtensionCustomFactory, OwnedUiExtensionCustomOptions, OwnedUiExtensionDialogOptions, OwnedUiExtensionEditorComponent, OwnedUiExtensionEditorFactory, OwnedUiExtensionEditorThemePort, OwnedUiExtensionEntryRenderInput, OwnedUiExtensionFooterDataPort, OwnedUiExtensionFooterFactory, OwnedUiExtensionInputListener, OwnedUiExtensionKeybindingsPort, OwnedUiExtensionMessageRenderInput, OwnedUiExtensionNotificationSeverity, OwnedUiExtensionOverlayAnchor, OwnedUiExtensionOverlayHandle, OwnedUiExtensionOverlayMargin, OwnedUiExtensionOverlayOptions, OwnedUiExtensionRenderCallback, OwnedUiExtensionRendererPort, OwnedUiExtensionRuntimePort, OwnedUiExtensionSelectListThemePort, OwnedUiExtensionSizeValue, OwnedUiExtensionTerminalPort, OwnedUiExtensionThemeBackground, OwnedUiExtensionThemeColor, OwnedUiExtensionThemeInfo, OwnedUiExtensionThemePort, OwnedUiExtensionToolRenderContext, OwnedUiExtensionUiCallback, OwnedUiExtensionUiPort, OwnedUiExtensionUiProperty, OwnedUiExtensionWidgetOptions, OwnedUiExtensionWidgetPlacement, OwnedUiExtensionWorkingIndicatorOptions, } from "./extension-ui.js";
 export { OWNED_UI_CONTRACT_VERSION } from "./model.js";

package/dist/contracts/owned-ui/index.js

@@ -1,3 +1,4 @@
+export const UI_ACCENT_COLORS = Object.freeze(["blue", "green", "orange", "pink", "purple", "cyan", "grey"]);
 export { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, assertOwnedUiExtensionUiPort, } from "./extension-ui.js";
 export { OWNED_UI_CONTRACT_VERSION } from "./model.js";
 export { OWNED_UI_HIDDEN_COMMAND_NAMES, OWNED_UI_MODELS_COMMAND_NAME, OWNED_UI_WORKFLOW_COMMAND_NAMES, } from "./session-workflows.js";

package/dist/contracts/presentation/progress-palette.generated.d.ts

@@ -29,7 +29,7 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             };
         };
     };
-    purple: {
+    green: {
         dark: {
             truecolor: {
                 accent: string;
@@ -55,7 +55,7 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             };
         };
     };
-    cyan: {
+    orange: {
         dark: {
             truecolor: {
                 accent: string;
@@ -81,7 +81,7 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             };
         };
     };
-    green: {
+    pink: {
         dark: {
             truecolor: {
                 accent: string;
@@ -107,7 +107,7 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             };
         };
     };
-    orange: {
+    purple: {
         dark: {
             truecolor: {
                 accent: string;
@@ -133,7 +133,33 @@ export declare const SHARED_PROGRESS_PALETTE: Readonly<{
             };
         };
     };
-    pink: {
+    cyan: {
+        dark: {
+            truecolor: {
+                accent: string;
+                border: string;
+                selectedBg: string;
+            };
+            "256color": {
+                accent: string;
+                border: string;
+                selectedBg: string;
+            };
+        };
+        light: {
+            truecolor: {
+                accent: string;
+                border: string;
+                selectedBg: string;
+            };
+            "256color": {
+                accent: string;
+                border: string;
+                selectedBg: string;
+            };
+        };
+    };
+    grey: {
         dark: {
             truecolor: {
                 accent: string;

package/dist/contracts/presentation/progress-palette.generated.js

@@ -2,5 +2,5 @@
  * Generated by scripts/pi/sync-progress-palette.ts from A1's named accent projection
  * over pinned Pi 1.5.2 (MIT), commit b4afdddf44e059c67ccf5097e5317d913521b470. Do not edit directly.
  */
-export const SHARED_PROGRESS_PALETTE = Object.freeze({ "blue": { "dark": { "truecolor": { "accent": "\u001b[38;2;130;160;241m", "border": "\u001b[38;2;116;102;197m", "selectedBg": "\u001b[48;2;52;57;69m" }, "256color": { "accent": "\u001b[38;5;111m", "border": "\u001b[38;5;98m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;63;96;226m", "border": "\u001b[38;2;83;67;154m", "selectedBg": "\u001b[48;2;243;244;246m" }, "256color": { "accent": "\u001b[38;5;62m", "border": "\u001b[38;5;60m", "selectedBg": "\u001b[48;5;255m" } } }, "purple": { "dark": { "truecolor": { "accent": "\u001b[38;2;167;152;215m", "border": "\u001b[38;2;105;115;167m", "selectedBg": "\u001b[48;2;58;56;66m" }, "256color": { "accent": "\u001b[38;5;140m", "border": "\u001b[38;5;61m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;116;89;180m", "border": "\u001b[38;2;68;77;130m", "selectedBg": "\u001b[48;2;243;243;245m" }, "256color": { "accent": "\u001b[38;5;97m", "border": "\u001b[38;5;60m", "selectedBg": "\u001b[48;5;255m" } } }, "cyan": { "dark": { "truecolor": { "accent": "\u001b[38;2;93;179;186m", "border": "\u001b[38;2;74;128;146m", "selectedBg": "\u001b[48;2;48;60;61m" }, "256color": { "accent": "\u001b[38;5;73m", "border": "\u001b[38;5;66m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;40;122;129m", "border": "\u001b[38;2;40;89;106m", "selectedBg": "\u001b[48;2;241;244;244m" }, "256color": { "accent": "\u001b[38;5;30m", "border": "\u001b[38;5;23m", "selectedBg": "\u001b[48;5;255m" } } }, "green": { "dark": { "truecolor": { "accent": "\u001b[38;2;104;183;141m", "border": "\u001b[38;2;75;132;120m", "selectedBg": "\u001b[48;2;50;60;54m" }, "256color": { "accent": "\u001b[38;5;72m", "border": "\u001b[38;5;66m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;51;126;88m", "border": "\u001b[38;2;41;93;82m", "selectedBg": "\u001b[48;2;242;244;243m" }, "256color": { "accent": "\u001b[38;5;65m", "border": "\u001b[38;5;23m", "selectedBg": "\u001b[48;5;255m" } } }, "orange": { "dark": { "truecolor": { "accent": "\u001b[38;2;231;135;83m", "border": "\u001b[38;2;178;89;79m", "selectedBg": "\u001b[48;2;67;54;48m" }, "256color": { "accent": "\u001b[38;5;173m", "border": "\u001b[38;5;131m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;174;80;16m", "border": "\u001b[38;2;133;57;49m", "selectedBg": "\u001b[48;2;245;243;242m" }, "256color": { "accent": "\u001b[38;5;130m", "border": "\u001b[38;5;95m", "selectedBg": "\u001b[48;5;255m" } } }, "pink": { "dark": { "truecolor": { "accent": "\u001b[38;2;223;122;199m", "border": "\u001b[38;2;150;91;171m", "selectedBg": "\u001b[48;2;65;53;62m" }, "256color": { "accent": "\u001b[38;5;176m", "border": "\u001b[38;5;97m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;178;56;153m", "border": "\u001b[38;2;114;61;131m", "selectedBg": "\u001b[48;2;245;243;245m" }, "256color": { "accent": "\u001b[38;5;132m", "border": "\u001b[38;5;60m", "selectedBg": "\u001b[48;5;255m" } } } });
+export const SHARED_PROGRESS_PALETTE = Object.freeze({ "blue": { "dark": { "truecolor": { "accent": "\u001b[38;2;130;160;241m", "border": "\u001b[38;2;116;102;197m", "selectedBg": "\u001b[48;2;52;57;69m" }, "256color": { "accent": "\u001b[38;5;111m", "border": "\u001b[38;5;98m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;63;96;226m", "border": "\u001b[38;2;83;67;154m", "selectedBg": "\u001b[48;2;243;244;246m" }, "256color": { "accent": "\u001b[38;5;62m", "border": "\u001b[38;5;60m", "selectedBg": "\u001b[48;5;255m" } } }, "green": { "dark": { "truecolor": { "accent": "\u001b[38;2;104;183;141m", "border": "\u001b[38;2;75;132;120m", "selectedBg": "\u001b[48;2;50;60;54m" }, "256color": { "accent": "\u001b[38;5;72m", "border": "\u001b[38;5;66m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;51;126;88m", "border": "\u001b[38;2;41;93;82m", "selectedBg": "\u001b[48;2;242;244;243m" }, "256color": { "accent": "\u001b[38;5;65m", "border": "\u001b[38;5;23m", "selectedBg": "\u001b[48;5;255m" } } }, "orange": { "dark": { "truecolor": { "accent": "\u001b[38;2;231;135;83m", "border": "\u001b[38;2;178;89;79m", "selectedBg": "\u001b[48;2;67;54;48m" }, "256color": { "accent": "\u001b[38;5;173m", "border": "\u001b[38;5;131m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;174;80;16m", "border": "\u001b[38;2;133;57;49m", "selectedBg": "\u001b[48;2;245;243;242m" }, "256color": { "accent": "\u001b[38;5;130m", "border": "\u001b[38;5;95m", "selectedBg": "\u001b[48;5;255m" } } }, "pink": { "dark": { "truecolor": { "accent": "\u001b[38;2;223;122;199m", "border": "\u001b[38;2;150;91;171m", "selectedBg": "\u001b[48;2;65;53;62m" }, "256color": { "accent": "\u001b[38;5;176m", "border": "\u001b[38;5;97m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;178;56;153m", "border": "\u001b[38;2;114;61;131m", "selectedBg": "\u001b[48;2;245;243;245m" }, "256color": { "accent": "\u001b[38;5;132m", "border": "\u001b[38;5;60m", "selectedBg": "\u001b[48;5;255m" } } }, "purple": { "dark": { "truecolor": { "accent": "\u001b[38;2;167;152;215m", "border": "\u001b[38;2;105;115;167m", "selectedBg": "\u001b[48;2;58;56;66m" }, "256color": { "accent": "\u001b[38;5;140m", "border": "\u001b[38;5;61m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;116;89;180m", "border": "\u001b[38;2;68;77;130m", "selectedBg": "\u001b[48;2;243;243;245m" }, "256color": { "accent": "\u001b[38;5;97m", "border": "\u001b[38;5;60m", "selectedBg": "\u001b[48;5;255m" } } }, "cyan": { "dark": { "truecolor": { "accent": "\u001b[38;2;93;179;186m", "border": "\u001b[38;2;74;128;146m", "selectedBg": "\u001b[48;2;48;60;61m" }, "256color": { "accent": "\u001b[38;5;73m", "border": "\u001b[38;5;66m", "selectedBg": "\u001b[48;5;59m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;40;122;129m", "border": "\u001b[38;2;40;89;106m", "selectedBg": "\u001b[48;2;241;244;244m" }, "256color": { "accent": "\u001b[38;5;30m", "border": "\u001b[38;5;23m", "selectedBg": "\u001b[48;5;255m" } } }, "grey": { "dark": { "truecolor": { "accent": "\u001b[38;2;163;163;163m", "border": "\u001b[38;2;119;119;119m", "selectedBg": "\u001b[48;2;57;57;57m" }, "256color": { "accent": "\u001b[38;5;247m", "border": "\u001b[38;5;243m", "selectedBg": "\u001b[48;5;237m" } }, "light": { "truecolor": { "accent": "\u001b[38;2;111;111;111m", "border": "\u001b[38;2;84;84;84m", "selectedBg": "\u001b[48;2;244;244;244m" }, "256color": { "accent": "\u001b[38;5;242m", "border": "\u001b[38;5;240m", "selectedBg": "\u001b[48;5;255m" } } } });
 export const SHARED_PROGRESS_ACCENT_ANSI = SHARED_PROGRESS_PALETTE.blue.dark.truecolor.accent;

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

@@ -732,7 +732,7 @@ export class SettingsApp {
         const state = {
             choices: menu.choices.map(choice => displaySettingValue(menu.entry, choice)),
             ...(menu.preview !== null ? { previews: menu.preview.frames(menu.choices, menu.index, theme) }
-                : menu.entry.id === "accentColor" ? {
+                : ["accentColor", "defaultAccentColor"].includes(menu.entry.id) ? {
                     previews: menu.choices.map(choice => theme.accentPreview?.(String(choice), "■") ?? ""),
                 } : {}),
             current: this.#edits.shown(menu.entry) === null ? null : displaySettingValue(menu.entry, this.#edits.shown(menu.entry)),

package/dist/foundation/lifecycle/index.d.ts

@@ -2,6 +2,8 @@ export { assertLaunchProfileId } from "./model.js";
 export type { LaunchProfileId, ProcessIdentity } from "./model.js";
 export { PID_LIVENESS_IDENTITY, inspectLiveProcess } from "./process-liveness.js";
 export { resolveProductPaths } from "./paths.js";
+export { serveSessionControl, requestSessionControl } from "./session-control.js";
+export type { SessionControlHostOptions, SessionControlIdentity, SessionControlRequestOptions } from "./session-control.js";
 export type { ProductPaths } from "./paths.js";
 export { parseSessionSelection, sessionSelectionArguments } from "./session-selection.js";
 export type { SessionSelection } from "./session-selection.js";

package/dist/foundation/lifecycle/index.js

@@ -1,6 +1,7 @@
 export { assertLaunchProfileId } from "./model.js";
 export { PID_LIVENESS_IDENTITY, inspectLiveProcess } from "./process-liveness.js";
 export { resolveProductPaths } from "./paths.js";
+export { serveSessionControl, requestSessionControl } from "./session-control.js";
 export { parseSessionSelection, sessionSelectionArguments } from "./session-selection.js";
 export { PRIMARY_SESSION_AGENT_ID, activateSessionRepositoryContext, clearSessionRepositoryContext, listSessionRepositoryWorktrees, readActiveSessionRepositoryContext, readSessionStartupRoot, readSessionRepositoryContext, registerSessionRepositoryRuntime, releaseInvalidSessionRepositoryContext, releaseSessionRepositoryRuntime, setSessionRepositoryContext, withSessionRepositoryObservation, } from "./session-repository-context.js";
 export { retrySessionCoordination } from "./session-context-retry.js";

package/dist/foundation/lifecycle/session-control.d.ts

@@ -0,0 +1,26 @@
+import type { ProcessIdentity } from "./model.js";
+export interface SessionControlIdentity {
+    readonly sessionId: string;
+    readonly binding: number;
+}
+interface ControlOptions {
+    readonly runtimeDir: string;
+    readonly inspectProcess?: (pid: number) => Promise<ProcessIdentity | null>;
+}
+export interface SessionControlHostOptions extends ControlOptions {
+    readonly runtimeId: string;
+    readonly identity: () => SessionControlIdentity;
+    readonly handle: (payload: unknown) => Promise<unknown>;
+}
+export interface SessionControlRequestOptions extends ControlOptions {
+    readonly sessionId: string;
+    readonly runtimeId?: string;
+    readonly payload: unknown;
+    readonly timeoutMs?: number;
+}
+export declare function serveSessionControl(options: SessionControlHostOptions): Promise<{
+    publish(): Promise<void>;
+    dispose(): Promise<void>;
+}>;
+export declare function requestSessionControl(options: SessionControlRequestOptions): Promise<unknown>;
+export {};

package/dist/foundation/lifecycle/session-control.js

@@ -0,0 +1,222 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readdir, open, realpath, rename, unlink, writeFile, chmod } from "node:fs/promises";
+import { createConnection, createServer } from "node:net";
+import { join, resolve } from "node:path";
+import { inspectLiveProcess } from "./process-liveness.js";
+const LIMIT = 8192;
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/iu;
+const SLUG = /^[a-z0-9-]{1,128}$/iu;
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const hash = (value) => createHash("sha256").update(value).digest("hex").slice(0, 32);
+const address = (directory, id) => process.platform === "win32"
+    ? `\\\\.\\pipe\\session-control-${hash(directory)}-${id}` : join(directory, `${id}.sock`);
+async function privateDirectory(runtimeDir, create) {
+    const selectedRoot = resolve(runtimeDir);
+    if (create)
+        await mkdir(selectedRoot, { recursive: true, mode: 0o700 });
+    const root = await realpath(selectedRoot);
+    const directory = join(root, "session-controls");
+    if (create)
+        await mkdir(directory, { mode: 0o700 }).catch(error => { if (error.code !== "EEXIST")
+            throw error; });
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || resolve(await realpath(directory)) !== directory) {
+        throw fail("control-boundary", "Session control directory is not a private regular directory.");
+    }
+    if (process.platform !== "win32" && (stat.mode & 0o077) !== 0)
+        throw fail("control-boundary", "Session control directory permissions are not private.");
+    return directory;
+}
+async function readRegistration(file) {
+    const stat = await lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > LIMIT || (process.platform !== "win32" && (stat.mode & 0o077) !== 0)) {
+        throw fail("control-boundary", "Invalid session control record.");
+    }
+    const handle = await open(file, "r");
+    let raw;
+    try {
+        const opened = await handle.stat();
+        if (opened.dev !== stat.dev || opened.ino !== stat.ino || !opened.isFile())
+            throw fail("control-boundary", "Session control record changed during lookup.");
+        const buffer = Buffer.alloc(LIMIT + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > LIMIT)
+            throw fail("control-boundary", "Session control record exceeds the size limit.");
+        raw = buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw fail("control-boundary", "Malformed session control record.");
+    }
+    if (!value || typeof value !== "object")
+        throw fail("control-boundary", "Malformed session control record.");
+    if (value.version !== 1 || !UUID.test(value.id) || !UUID.test(value.sessionId) || typeof value.runtimeId !== "string" || !SLUG.test(value.runtimeId)
+        || !UUID.test(value.nonce) || !Number.isSafeInteger(value.binding) || value.binding < 0
+        || !Number.isSafeInteger(value.owner?.pid) || value.owner.pid <= 0 || typeof value.owner.startIdentity !== "string") {
+        throw fail("control-boundary", "Malformed session control record.");
+    }
+    return value;
+}
+function receive(socket, consume) {
+    let data = "", complete = false;
+    socket.setEncoding("utf8");
+    socket.on("data", chunk => {
+        if (complete) {
+            socket.destroy();
+            return;
+        }
+        data += chunk;
+        if (Buffer.byteLength(data) > LIMIT) {
+            socket.destroy();
+            return;
+        }
+        const newline = data.indexOf("\n");
+        if (newline < 0)
+            return;
+        complete = true;
+        if (data.slice(newline + 1).trim() !== "") {
+            socket.destroy();
+            return;
+        }
+        try {
+            consume(JSON.parse(data.slice(0, newline)));
+        }
+        catch {
+            socket.destroy();
+        }
+    });
+}
+export async function serveSessionControl(options) {
+    if (!SLUG.test(options.runtimeId))
+        throw fail("session-unavailable", "Runtime identity is invalid.");
+    const directory = await privateDirectory(options.runtimeDir, true);
+    const inspect = options.inspectProcess ?? inspectLiveProcess;
+    const owner = await inspect(process.pid);
+    if (!owner || owner.pid !== process.pid || !owner.startIdentity)
+        throw fail("session-unavailable", "Runtime identity cannot be verified.");
+    const id = randomUUID(), nonce = randomUUID(), file = join(directory, `${id}.json`);
+    let disposed = false, queue = Promise.resolve(), publication = Promise.resolve();
+    const sockets = new Set();
+    const server = createServer(socket => {
+        sockets.add(socket);
+        socket.setTimeout(5000, () => socket.destroy());
+        socket.on("error", () => { });
+        socket.on("close", () => sockets.delete(socket));
+        receive(socket, input => {
+            queue = queue.then(async () => {
+                try {
+                    const request = input;
+                    const current = options.identity();
+                    if (disposed || socket.destroyed || request.nonce !== nonce || request.runtimeId !== options.runtimeId
+                        || request.sessionId !== current.sessionId || request.binding !== current.binding) {
+                        throw fail("session-unavailable", "The selected session is no longer active.");
+                    }
+                    if (!UUID.test(request.requestId) || !Number.isFinite(request.deadline) || request.deadline <= Date.now() || request.deadline > Date.now() + 5000) {
+                        throw fail("request-expired", "Session request expired before application.");
+                    }
+                    // Concurrency: no await separates the identity/deadline check from calling the live handler.
+                    const result = await options.handle(request.payload);
+                    if (!socket.destroyed)
+                        socket.end(`${JSON.stringify({ requestId: request.requestId, result })}\n`);
+                }
+                catch (error) {
+                    const failure = error;
+                    if (!socket.destroyed)
+                        socket.end(`${JSON.stringify({ error: { code: failure.code ?? "control-failed", message: failure.message } })}\n`);
+                }
+            }).catch(() => { socket.destroy(); });
+        });
+    });
+    await new Promise((done, reject) => { server.once("error", reject); server.listen(address(directory, id), () => { server.off("error", reject); done(); }); });
+    server.on("error", () => { });
+    server.maxConnections = 64;
+    const publish = () => {
+        publication = publication.catch(() => { }).then(async () => {
+            if (disposed)
+                return;
+            const identity = options.identity();
+            if (!UUID.test(identity.sessionId) || !Number.isSafeInteger(identity.binding) || identity.binding < 0)
+                throw fail("session-unavailable", "Session identity is not available.");
+            const temporary = join(directory, `${id}.${randomUUID()}.tmp`);
+            try {
+                await writeFile(temporary, JSON.stringify({ version: 1, id, nonce, runtimeId: options.runtimeId, owner, ...identity }), { mode: 0o600, flag: "wx" });
+                await rename(temporary, file);
+            }
+            finally {
+                await unlink(temporary).catch(() => { });
+            }
+        });
+        return publication;
+    };
+    const dispose = async () => {
+        if (disposed)
+            return;
+        disposed = true;
+        for (const socket of sockets)
+            socket.destroy();
+        await new Promise(done => server.close(() => done()));
+        await queue;
+        await publication.catch(() => { });
+        await unlink(file).catch(() => { });
+    };
+    try {
+        if (process.platform !== "win32")
+            await chmod(address(directory, id), 0o600);
+        await publish();
+    }
+    catch (error) {
+        await dispose();
+        throw error;
+    }
+    return { publish, dispose };
+}
+export async function requestSessionControl(options) {
+    if (!UUID.test(options.sessionId))
+        throw fail("invalid-session", "Supply a complete session UUID.");
+    const budget = Math.min(5000, Math.max(1, options.timeoutMs ?? 3000));
+    const deadline = Date.now() + budget;
+    const directory = await privateDirectory(options.runtimeDir, false).catch(() => { throw fail("session-unavailable", "No live session control is available."); });
+    const names = (await readdir(directory)).filter(name => UUID.test(name.slice(0, -5)) && name.endsWith(".json"));
+    if (names.length > 256)
+        throw fail("control-limit", "Too many session records to resolve safely.");
+    const matches = [];
+    for (const name of names) {
+        const record = await readRegistration(join(directory, name)).catch(error => { if (error.code === "ENOENT")
+            return null; throw error; });
+        if (record === null || `${record.id}.json` !== name || record.sessionId !== options.sessionId || (options.runtimeId !== undefined && record.runtimeId !== options.runtimeId))
+            continue;
+        const owner = await (options.inspectProcess ?? inspectLiveProcess)(record.owner.pid);
+        if (owner?.startIdentity === record.owner.startIdentity)
+            matches.push(record);
+        if (Date.now() >= deadline)
+            throw fail("request-expired", "Session lookup exceeded its deadline.");
+    }
+    if (matches.length !== 1)
+        throw fail(matches.length > 1 ? "ambiguous-session" : "session-unavailable", "Select one running bare session by its complete session id.");
+    const record = matches[0];
+    return await new Promise((done, reject) => {
+        const socket = createConnection(address(directory, record.id));
+        const requestId = randomUUID();
+        const timer = setTimeout(() => { socket.destroy(); reject(fail("request-expired", "Session request timed out; application was not acknowledged.")); }, Math.max(1, deadline - Date.now()));
+        const finish = () => { clearTimeout(timer); socket.destroy(); };
+        socket.on("error", () => { finish(); reject(fail("session-unavailable", "The selected session could not be reached.")); });
+        socket.on("close", () => { clearTimeout(timer); reject(fail("session-unavailable", "The selected session closed before acknowledgement.")); });
+        socket.on("connect", () => socket.write(`${JSON.stringify({ ...record, requestId, deadline, payload: options.payload })}\n`));
+        receive(socket, input => {
+            const response = input;
+            finish();
+            if (response.error)
+                reject(fail(response.error.code, response.error.message));
+            else if (response.requestId !== requestId)
+                reject(fail("control-failed", "Session acknowledgement did not match the request."));
+            else
+                done(response.result);
+        });
+    });
+}

package/dist/foundation/release/early-accent.d.ts

@@ -1,4 +1,5 @@
-type UiAccentColor = "blue" | "purple" | "cyan" | "green" | "orange" | "pink";
+import { SHARED_PROGRESS_PALETTE } from "../../contracts/presentation/index.js";
+type UiAccentColor = keyof typeof SHARED_PROGRESS_PALETTE;
 type EarlyAccentAppearance = "dark" | "light";
 type EarlyAccentMode = "truecolor" | "256color";
 /** Read only global profile data, never project settings or the interactive resource pipeline. */

package/dist/integrations/pi/components/upstream/theme/theme.js

@@ -45,6 +45,7 @@ const ACCENT_PALETTE = Object.freeze({
     green: Object.freeze({ dark: okhslColor(159, 0.59, 0.67), light: okhslColor(159, 0.75, 0.46) }),
     orange: Object.freeze({ dark: okhslColor(48, 0.75, 0.67), light: okhslColor(48, 0.90, 0.47) }),
     pink: Object.freeze({ dark: okhslColor(337, 0.72, 0.67), light: okhslColor(337, 0.75, 0.48) }),
+    grey: Object.freeze({ dark: okhslColor(0, 0, 0.67), light: okhslColor(0, 0, 0.47) }),
 });
 /** Canonical named color used by both the interactive theme and pre-load palette generation. */
 export function namedPiAccent(color, appearance) {
@@ -59,6 +60,7 @@ function wrapHue(hue) {
 /** Derive the complete semantic family from any primary accent, including future custom colors. */
 export function derivePiAccentProjection(accent, appearance) {
     const { h, s, l } = colorToOkhsl(accent);
+    const neutral = s < 0.001;
     const warm = h < 90 || h >= 270;
     const magenta = h >= 270 && h < 325;
     const blue = h >= 210 && h < 270;
@@ -69,10 +71,10 @@ export function derivePiAccentProjection(accent, appearance) {
     const selectedLightness = dark ? l * 0.37 : 1 - (1 - l) * 0.075;
     return Object.freeze({
         accent,
-        border: okhslColor(borderHue, clamp(s * 0.78, 0.30, 0.64), clamp(l - (dark ? 0.17 : 0.11), 0, 1)),
-        secondaryHeading: okhslColor(secondaryHue, clamp(s + 0.20, 0.62, 0.82), clamp(l + (dark ? 0.09 : -0.09), 0, 1)),
-        selectedBg: okhslColor(h, selectedSaturation, selectedLightness),
-        userMessageBg: okhslColor(h, selectedSaturation * 2 / 3, dark ? l * 0.34 : 1 - (1 - l) * 0.055),
+        border: okhslColor(borderHue, neutral ? 0 : clamp(s * 0.78, 0.30, 0.64), clamp(l - (dark ? 0.17 : 0.11), 0, 1)),
+        secondaryHeading: okhslColor(secondaryHue, neutral ? 0 : clamp(s + 0.20, 0.62, 0.82), clamp(l + (dark ? 0.09 : -0.09), 0, 1)),
+        selectedBg: okhslColor(h, neutral ? 0 : selectedSaturation, selectedLightness),
+        userMessageBg: okhslColor(h, neutral ? 0 : selectedSaturation * 2 / 3, dark ? l * 0.34 : 1 - (1 - l) * 0.055),
     });
 }
 let activeBaseTheme;
@@ -118,8 +120,8 @@ export function derivePiCanvasBackground(style, accent) {
         return null;
     if (style === "dark")
         return okhslColor(229, 0.03, 0.12);
-    const { h } = colorToOkhsl(accent);
-    return okhslColor(h, 0.12, 0.12);
+    const { h, s } = colorToOkhsl(accent);
+    return okhslColor(h, s < 0.001 ? 0 : 0.12, 0.12);
 }
 /** Resolves the selected canvas through the active accent and terminal color mode. */
 export function piCanvasBackgroundAnsi(style) {

package/dist/ui/settings/declarations.d.ts

@@ -9,6 +9,8 @@ export interface OwnedUiSettingDeclaration {
     };
     readonly description: string;
     readonly application: OwnedUiSettingApplication;
+    readonly storage?: "session";
+    readonly initialValueFrom?: string;
     readonly defaultValue: OwnedUiSettingValue;
     readonly allowedValues: readonly OwnedUiSettingValue[];
     /**
@@ -34,9 +36,23 @@ export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
         defaultValue: "auto";
         allowedValues: readonly ["auto", "manual"];
     }>;
+    readonly defaultAccentColor: Readonly<{
+        id: "defaultAccentColor";
+        label: "Default color";
+        section: Readonly<{
+            id: "appearance";
+            title: "Appearance";
+        }>;
+        description: "Startup color for future sessions. Changing this does not recolor running sessions.";
+        application: "restart";
+        defaultValue: "blue";
+        allowedValues: readonly ["blue", "green", "orange", "pink", "purple", "cyan", "grey"];
+    }>;
     readonly accentColor: Readonly<{
         id: "accentColor";
-        label: "Accent color";
+        label: "Current color";
+        storage: "session";
+        initialValueFrom: "defaultAccentColor";
         section: Readonly<{
             id: "appearance";
             title: "Appearance";
@@ -44,7 +60,7 @@ export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
         description: "Color used by highlighted interface controls, list markers, and tonal interface surfaces.";
         application: "live";
         defaultValue: "blue";
-        allowedValues: readonly ["blue", "purple", "cyan", "green", "orange", "pink"];
+        allowedValues: readonly ["blue", "green", "orange", "pink", "purple", "cyan", "grey"];
     }>;
     readonly backgroundStyle: Readonly<{
         id: "backgroundStyle";

package/dist/ui/settings/declarations.js

@@ -1,6 +1,5 @@
-const UI_ACCENT_COLOR_CHOICES = Object.freeze([
-    "blue", "purple", "cyan", "green", "orange", "pink",
-]);
+import { UI_ACCENT_COLORS } from "../../contracts/owned-ui/index.js";
+const UI_ACCENT_COLOR_CHOICES = UI_ACCENT_COLORS;
 const MAX_ID_LENGTH = 64;
 const ID_PATTERN = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/;
 const GENERIC_SECTION = Object.freeze({ id: "generic", title: "Generic" });
@@ -17,9 +16,20 @@ export const OWNED_SETTING_DECLARATIONS = Object.freeze({
         defaultValue: "auto",
         allowedValues: Object.freeze(["auto", "manual"]),
     }),
+    defaultAccentColor: Object.freeze({
+        id: "defaultAccentColor",
+        label: "Default color",
+        section: APPEARANCE_SECTION,
+        description: "Startup color for future sessions. Changing this does not recolor running sessions.",
+        application: "restart",
+        defaultValue: "blue",
+        allowedValues: UI_ACCENT_COLOR_CHOICES,
+    }),
     accentColor: Object.freeze({
         id: "accentColor",
-        label: "Accent color",
+        label: "Current color",
+        storage: "session",
+        initialValueFrom: "defaultAccentColor",
         section: APPEARANCE_SECTION,
         description: "Color used by highlighted interface controls, list markers, and tonal interface surfaces.",
         application: "live",

package/dist/ui/settings/early-accent.d.ts

@@ -99,6 +99,22 @@ export declare function preTrustPalette(color: UiAccentColor, appearance: Appear
     accent: string;
     border: string;
     selectedBg: string;
+} | {
+    accent: string;
+    border: string;
+    selectedBg: string;
+} | {
+    accent: string;
+    border: string;
+    selectedBg: string;
+} | {
+    accent: string;
+    border: string;
+    selectedBg: string;
+} | {
+    accent: string;
+    border: string;
+    selectedBg: string;
 };
 export declare function preTrustTerminalAppearance(environment?: NodeJS.ProcessEnv): Appearance;
 export declare function preTrustTerminalColorMode(environment?: NodeJS.ProcessEnv): ColorMode;

package/dist/ui/settings/early-accent.js

@@ -21,9 +21,7 @@ export function readPreTrustAccent(environment = process.env) {
         const namespace = root[PRODUCT_IDENTITY.commandName];
         if (namespace === null || typeof namespace !== "object" || Array.isArray(namespace))
             return "blue";
-        const value = namespace.accentColor;
-        if (value === "default")
-            return "purple";
+        const value = namespace.defaultAccentColor;
         return typeof value === "string" && Object.hasOwn(SHARED_PROGRESS_PALETTE, value) ? value : "blue";
     }
     catch {

package/dist/ui/settings/manager.d.ts

@@ -30,8 +30,9 @@ export interface OwnedUiSettingsChangeOutcome {
 }
 export type OwnedUiSettingsListener = (manager: OwnedSettingsManager) => void;
 /**
- * One profile's A1 settings: resolves the declaration table against the stored document,
- * persists each accepted change atomically without discarding unknown keys, offers the
+ * Owns a profile's durable settings and this session's ephemeral overrides. Durable changes
+ * persist atomically without discarding unknown or legacy session keys; session changes stay local.
+ * Offers the
  * grouped sections a surface presents, and routes every accepted change only to its
  * owning backend, with agent settings reached through the engine settings port.
  */
@@ -42,6 +43,7 @@ export declare class OwnedSettingsManager {
     get resolution(): OwnedUiSettingsResolution;
     /** Reads and resolves the product namespace. Never throws: every failure becomes a notice. */
     read(): OwnedUiSettingsResolution;
+    startSession(): void;
     load(): Promise<void>;
     /**
      * Adopts values another process stored in the shared document. Notifies only when a

package/dist/ui/settings/manager.js

@@ -7,8 +7,9 @@ import { readProfileSettingsNamespace, repairProfileSettingsDocument, updateProf
 const PROFILE_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const MAX_DOCUMENT_BYTES = 256 * 1024;
 /**
- * One profile's A1 settings: resolves the declaration table against the stored document,
- * persists each accepted change atomically without discarding unknown keys, offers the
+ * Owns a profile's durable settings and this session's ephemeral overrides. Durable changes
+ * persist atomically without discarding unknown or legacy session keys; session changes stay local.
+ * Offers the
  * grouped sections a surface presents, and routes every accepted change only to its
  * owning backend, with agent settings reached through the engine settings port.
  */
@@ -26,6 +27,7 @@ export class OwnedSettingsManager {
     #agentSnapshot = null;
     #pending = new Map();
     #restartEffective = new Map();
+    #sessionValues = new Map();
     constructor(options) {
         if (!PROFILE_ID_PATTERN.test(options.profileId)) {
             throw new Error(`owned UI settings profile id is not a bounded slug: ${options.profileId}`);
@@ -42,6 +44,7 @@ export class OwnedSettingsManager {
         this.#hiddenAgentSettingIds = new Set(options.hiddenAgentSettingIds ?? []);
         this.#agentSettingLabelOverrides = { ...(options.agentSettingLabelOverrides ?? {}) };
         this.#resolution = this.read();
+        this.startSession();
         for (const setting of this.#resolution.settings) {
             if (setting.declaration.application === "restart")
                 this.#restartEffective.set(setting.declaration.id, setting.value);
@@ -71,11 +74,31 @@ export class OwnedSettingsManager {
         return this.#resolveNamespace(null, shared.status === "invalid" ? shared.detail : undefined);
     }
     #resolveNamespace(values, unreadableDetail) {
-        return resolveOwnedUiSettings({
+        const resolution = resolveOwnedUiSettings({
             declarations: this.#declarations,
             values,
             ...(unreadableDetail === undefined ? {} : { unreadableDetail }),
         });
+        return { ...resolution, settings: resolution.settings.map(setting => {
+                const value = this.#sessionValues.get(setting.declaration.id);
+                return setting.declaration.storage !== "session" || value === undefined ? setting : { ...setting, value };
+            }) };
+    }
+    startSession() {
+        this.#resolution = this.read();
+        for (const declaration of this.#declarations) {
+            if (declaration.storage !== "session")
+                continue;
+            const source = this.#resolution.settings.find(setting => setting.declaration.id === declaration.initialValueFrom);
+            const value = source !== undefined && declaration.allowedValues.includes(source.value) ? source.value : declaration.defaultValue;
+            this.#sessionValues.set(declaration.id, value);
+            if (source !== undefined && source.declaration.application === "restart") {
+                this.#restartEffective.set(source.declaration.id, source.value);
+                this.#pending.delete(source.declaration.id);
+            }
+        }
+        this.#resolution = this.read();
+        this.#notify();
     }
     async load() {
         this.#resolution = this.read();
@@ -159,6 +182,15 @@ export class OwnedSettingsManager {
         return backend === "a1" ? this.#changeOwned(id, value) : await this.#changeAgentValue(id, value);
     }
     #changeOwned(id, value) {
+        const declaration = this.#declarations.find(candidate => candidate.id === id);
+        if (!declaration?.allowedValues.includes(value))
+            return failed(`value ${JSON.stringify(value)} is not allowed for ${id}`);
+        if (declaration.storage === "session") {
+            this.#sessionValues.set(id, value);
+            this.#resolution = this.read();
+            this.#notify();
+            return changed("applied", "live", value, value);
+        }
         const outcome = this.#write(id, value);
         if (!outcome.stored)
             return failed(outcome.failure ?? `${id} could not be stored`);
@@ -285,7 +317,7 @@ function fromAgentOutcome(result) {
 function compactValues(resolution) {
     const values = { ...resolution.preserved };
     for (const setting of resolution.settings) {
-        if (setting.value !== setting.declaration.defaultValue)
+        if (setting.declaration.storage !== "session" && setting.value !== setting.declaration.defaultValue)
             values[setting.declaration.id] = setting.value;
     }
     return values;

package/dist/ui/settings/resolution.js

@@ -11,7 +11,7 @@ export function resolveOwnedUiSettings(input) {
     const values = input.values ?? {};
     const settings = [];
     for (const declaration of input.declarations) {
-        if (!Object.hasOwn(values, declaration.id)) {
+        if (declaration.storage === "session" || !Object.hasOwn(values, declaration.id)) {
             settings.push({ declaration, value: declaration.defaultValue, source: "default" });
             continue;
         }
@@ -29,7 +29,8 @@ export function resolveOwnedUiSettings(input) {
     }
     const preserved = {};
     for (const [key, value] of Object.entries(values)) {
-        if (findOwnedUiSettingDeclaration(input.declarations, key) === null)
+        const declaration = findOwnedUiSettingDeclaration(input.declarations, key);
+        if (declaration === null || declaration.storage === "session")
             preserved[key] = value;
     }
     return {

package/docs/features/session-colors.md

@@ -0,0 +1,66 @@
+# Session colors and local API
+
+Bare A1 offers two Settings → Appearance controls:
+
+- **Default color** is saved in the active profile as `defaultAccentColor`. It initially resolves to blue. It controls the next session start, not the running interface.
+- **Current color** applies immediately to this active session only. It is not saved to profile settings and does not propagate to other sessions on the same machine, profile, or project.
+
+Both menus offer **blue → green → orange → pink → purple → cyan → grey**, with color previews. There is no automatic/dashed option. Grey keeps the derived semantic family and accent canvas neutral; unrelated success/warning/error colors are unchanged.
+
+A fresh launch, resumed transcript, or successful new/resume/fork/import replacement initializes Current color from the latest saved Default color. Missing or invalid defaults resolve to blue. A failed replacement retains the old session and color. Changing the saved default does not recolor any running session. Cancel and undo respect each setting's storage scope.
+
+The legacy profile `accentColor` key is retained but ignored by interactive color resolution. Current colors never overwrite it. The comparison `a1 pi` profile is unchanged. Standalone installation/update progress keeps its existing saved-profile preference policy.
+
+## Integration commands
+
+External applications such as Herdr can invoke the installed CLI as a subprocess. These commands always return JSON without a `--json` switch:
+
+| Arguments after `a1` | Result |
+| --- | --- |
+| `session color list` | Available color identifiers in display order; no running session needed |
+| `session color get --session <id>` | One live session's Current color |
+| `session color set pink --session <id>` | Set only that session's Current color and acknowledge the applied value |
+
+The selector is a **complete session UUID**, shown by A1's Session Info workflow. It is not a PID, terminal index, abbreviated prefix, transcript path, or machine-wide current session. Get/set require one explicitly targeted live bare-A1 session outside an A1 shell. Within a shell launched by that exact session, omission uses the existing `PI_SESSION_ID`, `PI_SESSION_FILE`, and A1 runtime identity together; it never selects a different session implicitly. Keep the runtime-directory environment consistent when controlling a custom runtime root.
+
+Get/set do not change Default color. Configure the startup preference in Settings. An API write immediately updates the Current color value visible there, along with semantic colors and accent-derived backgrounds.
+
+### Responses
+
+Inventory returns only the color list, not a hard-coded default that could be confused with the configured startup preference:
+
+```json
+{"colors":["blue","green","orange","pink","purple","cyan","grey"]}
+```
+
+Get and successful set use the same shape:
+
+```json
+{"sessionId":"57e38e80-f348-4b28-b791-7cc080886a70","color":"pink"}
+```
+
+Failures return:
+
+```json
+{"error":{"code":"session-unavailable","message":"Select one running bare session by its complete session id."}}
+```
+
+Exactly one newline-terminated JSON object is written to stdout, without progress or human-readable prefixes. Error messages are explanatory text and can evolve; applications should branch on `error.code`. Exit statuses:
+
+- **0:** successful list/get/applied set.
+- **2:** invalid arguments, color, session format, or missing required selector.
+- **1:** unavailable/ambiguous target, timeout, or control failure.
+
+Error codes include `invalid-request`, `invalid-color`, `invalid-session`, `session-required`, `session-unavailable`, `ambiguous-session`, `request-expired`, `control-boundary`, `control-limit`, and `control-failed`. Hosts without a color command adapter return `control-unavailable`. Ordinary `session color help` and global help remain human-readable. CLI capability metadata advertises `sessionColors: true`.
+
+### Herdr integration
+
+Invoke `a1` with an argument array rather than interpolating a shell string. For example, pass `["session", "color", "set", "pink", "--session", sessionId]`, capture stdout, await process completion, and parse its one JSON object. On exit 0, update Herdr's local UI from the returned `sessionId` and `color`. On nonzero exit, display or handle the structured error; do not treat a queued write or process creation as successful application. No subscription/event feed or host-app icon recoloring is provided.
+
+## Lifetime and safety
+
+Control starts alongside the interactive shell and stops with it. It uses an in-process local IPC endpoint: a Windows named pipe or Unix-domain socket, with bounded private discovery records under the runtime directory. It does not introduce a separate resident service, TCP port, or HTTP server. Comparison-profile sessions do not publish endpoints.
+
+Requests have a three-second end-to-end budget, bounded payloads, process-liveness checks, runtime identity, a private endpoint nonce, session binding checks, and correlated acknowledgements. Concurrent requests serialize in the target runtime. Set reports success only after its live settings change path applies the color. Requests still queued after expiry, disconnect, stop, or session replacement cannot recolor a later session. A timeout means application was not acknowledged: a change already applied just before a lost response is not rolled back; get the current value before deciding whether to retry. No delayed request is persisted for future replay.
+
+Private runtime records are not a public file-editing API. Do not write settings files or edit endpoint records to control Current color. Unverifiable, ambiguous, replaced, stopped, malformed, and comparison-profile targets fail closed without choosing another session. An unavailable control directory or failed endpoint startup leaves the interactive session usable, but external control reports unavailable. Worktree attachment authority is unaffected.

package/docs/openspec-archive-automation.md

@@ -42,8 +42,8 @@ Follow the [development worktree protocol](architecture/project-structure.md#dev
 
 ## Version-3 lifecycle
 
-1. **Draft plan:** create one normally named branch/PR such as `feature/...`, `fix/...`, or `chore/...`. Start the body with `## Proposal`, use it for one or two sentences of intent, and follow it with one or more unchecked, outcome-sized task items under `## Implementation`, with no fixed maximum. Each item names a delivered code outcome. Omit generic process tasks; run, verify, validate, evidence, or manual-test items; quoted phase lines; and routine validation command lists, and keep machine linkage under final collapsed `Automation`. Keep it draft and include only planning artifacts until the maintainer approves the plan and explicitly requests implementation.
-2. **Same-PR implementation:** continue after explicit approval in the same worktree, branch, history, draft PR, and phase-free body. Check an Implementation item as soon as its associated code and tests are written and its detailed task bookkeeping is complete; an ordinary progress edit changes only `[ ]` to `[x]` and is not deferred until handoff. Adding, removing, reordering, or rewriting an item is a scope refinement requiring explicit approval and coherent planning updates, with affected scope left unchecked. Reconcile approved refinements before corresponding code edits.
+1. **Draft plan:** create one normally named branch/PR such as `feature/...`, `fix/...`, or `chore/...`. Start the body with `## Proposal`, use it for one or two sentences of intent, and follow it with one or more unchecked, outcome-sized task items under `## Implementation`, with no fixed maximum. Each item names a delivered code outcome, and `tasks.md` holds one task group per item in the same order. Omit generic process tasks; run, verify, validate, evidence, or manual-test items; quoted phase lines; and routine validation command lists, and keep machine linkage under final collapsed `Automation`. Keep it draft and include only planning artifacts until the maintainer approves the plan and explicitly requests implementation.
+2. **Same-PR implementation:** continue after explicit approval in the same worktree, branch, history, draft PR, and phase-free body. Follow the `Implementation progress` rule in `AGENTS.md`: deliver one item at a time, and once its code and tests are written and its task group is ticked, commit, push, and check that item before starting the next. An ordinary progress edit changes only `[ ]` to `[x]` and is never saved for handoff. Adding, removing, reordering, or rewriting an item is a scope refinement requiring explicit approval and coherent planning updates, with affected scope left unchecked. Reconcile approved refinements before corresponding code edits.
 3. **Complete implementation:** finish the code and its tests, substantive tasks, and explicit known-gap disposition. CI runs those tests after readiness; its success is objective evidence, not acceptance, and GitHub check counts are not Implementation task progress. Manual validation is the maintainer's optional choice before integrating and never blocks a checkbox, finalization, or merge.
 4. **Plain acceptance list:** before checking the final item, keep the body phase-free and add final `## Acceptance` with one to ten concise implementation-specific behavior-and-result bullets. Do not use checkboxes, generic review/CI/approval/archive statements, angle-bracket placeholders or HTML, URLs, mentions, or automated-test inventory.
 5. **Automatic readiness and finalization:** reconcile and push current `origin/develop`, run the [delivery body check](#delivery-body-check) on the intended final body, then check the final item. That checkbox update completes the agent-owned implementation job; agents never mark implementation PRs ready themselves. Trusted automation revalidates the exact fully complete version-3 task-list snapshot and all pre-finalization inputs, marks the PR ready, and then conservatively synchronizes all deltas, moves the active change into its dated archive, stages the conditional acceptance manifest, commits that to the same branch with the archive App identity, and writes the emitted paths into the body's implementation fence. It never checks tasks or infers completion. Running the [finalization command](#finalization-command) locally first is optional and yields the same bytes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.2.7-dev.1288",
+  "version": "0.2.7-dev.1290",
   "description": "Standalone single-agent terminal UI on pinned Pi",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -113,7 +113,7 @@
     "@mariozechner/clipboard": "^0.3.9"
   },
   "publication": {
-    "source": "bfbed9a4849fe7ba1b6a879cef7a800a132e18e9",
-    "pullRequest": 915
+    "source": "c39a95552f7be42f1f7c83f7b3fdf8d92203d965",
+    "pullRequest": 917
   }
 }