@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.402

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/runtime-integration.d.ts

@@ -1,8 +1,20 @@
-import { type AgentSession, type AgentSessionRuntime, type AgentSessionServices, type ScopedModel } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionServices, SettingsManager, type AgentSession, type AgentSessionRuntime, type AgentSessionServices, type ScopedModel } from "@earendil-works/pi-coding-agent";
+import { resolvePiProjectTrustPreflight, type PiProjectTrustPreflightPrompt } from "./project-trust-preflight.js";
+import { type PiSessionForkPrompt, type PiSessionSelection } from "./session-selection.js";
 export interface PiRuntimeIntegrationOptions {
     readonly cwd: string;
     readonly agentDir: string;
     readonly sessionDir?: string;
+    readonly sessionPath?: string;
+    readonly sessionSelection?: PiSessionSelection;
+    readonly sessionForkPrompt?: PiSessionForkPrompt;
+    readonly projectTrustPrompt?: PiProjectTrustPreflightPrompt;
+    readonly preflightDependencies?: PiRuntimePreflightDependencies;
+}
+export interface PiRuntimePreflightDependencies {
+    readonly resolveTrust?: typeof resolvePiProjectTrustPreflight;
+    readonly createSettingsManager?: (cwd: string, agentDir: string, projectTrusted: boolean) => SettingsManager;
+    readonly createServices?: typeof createAgentSessionServices;
 }
 export type PiSessionReplacement = {
     readonly kind: "new";
@@ -26,6 +38,12 @@ interface ConfiguredModelScope {
  * saved default when it is in scope, otherwise the first scoped model.
  */
 export declare function resolveConfiguredModelScope(services: Pick<AgentSessionServices, "settingsManager" | "modelRuntime">): Promise<ConfiguredModelScope>;
+export declare function createPiRuntimeServicesAfterTrust(options: Pick<PiRuntimeIntegrationOptions, "agentDir" | "projectTrustPrompt" | "preflightDependencies"> & {
+    readonly cwd: string;
+}): Promise<{
+    readonly services: AgentSessionServices;
+    readonly trust: Awaited<ReturnType<typeof resolvePiProjectTrustPreflight>>;
+}>;
 export declare function createPiRuntimeIntegration(options: PiRuntimeIntegrationOptions): Promise<AgentSessionRuntime>;
 export declare function bindPiRuntimeSession(runtime: AgentSessionRuntime, rebind: (session: AgentSession) => Promise<void>): () => void;
 export declare function replacePiRuntimeSession(runtime: AgentSessionRuntime, replacement: PiSessionReplacement): Promise<{

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/runtime-integration.js

@@ -1,4 +1,8 @@
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, resolveModelScopeWithDiagnostics, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, resolveModelScopeWithDiagnostics, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { resolvePiProjectTrustPreflight, } from "./project-trust-preflight.js";
+import { openSelectedPiSession, resolveSessionArgumentPath } from "./session-selection.js";
+import { markStartupPhase } from "../../../foundation/startup/index.js";
+import { createWindowsNulCleanupExtension } from "./windows-filesystem-hygiene.js";
 /**
  * Mirrors pinned Pi's CLI startup: resolve the `models` patterns from settings
  * into a scoped model list, keep the resolver's warnings (e.g. "No models match
@@ -29,10 +33,49 @@ export async function resolveConfiguredModelScope(services) {
         diagnostics: diagnostics.map(diagnostic => ({ type: diagnostic.type, message: diagnostic.message })),
     };
 }
+export async function createPiRuntimeServicesAfterTrust(options) {
+    const resolveTrust = options.preflightDependencies?.resolveTrust ?? resolvePiProjectTrustPreflight;
+    const createSettingsManager = options.preflightDependencies?.createSettingsManager
+        ?? ((targetCwd, agentDir, projectTrusted) => SettingsManager.create(targetCwd, agentDir, { projectTrusted }));
+    const createServices = options.preflightDependencies?.createServices ?? createAgentSessionServices;
+    const trust = await resolveTrust({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        ...(options.projectTrustPrompt === undefined ? {} : { prompt: options.projectTrustPrompt }),
+    });
+    const settingsManager = createSettingsManager(options.cwd, options.agentDir, trust.trusted);
+    await markStartupPhase(process.env, "settings-loaded");
+    const cleanupExtension = createWindowsNulCleanupExtension();
+    const services = await createServices({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        settingsManager,
+        ...(cleanupExtension === null ? {} : {
+            resourceLoaderOptions: { extensionFactories: [cleanupExtension] },
+        }),
+    });
+    await markStartupPhase(process.env, "pi-services");
+    await markStartupPhase(process.env, "resource-discovery");
+    return { services, trust };
+}
 export async function createPiRuntimeIntegration(options) {
-    const sessionManager = SessionManager.create(options.cwd, options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR);
+    const directory = options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR;
+    const sessionDir = directory === undefined ? undefined : resolveSessionArgumentPath(directory, options.cwd);
+    const selection = options.sessionSelection ?? (options.sessionPath === undefined ? undefined : { target: resolveSessionArgumentPath(options.sessionPath, options.cwd) });
+    const sessionManager = selection === undefined
+        ? SessionManager.create(options.cwd, sessionDir)
+        : await openSelectedPiSession({
+            cwd: options.cwd, selection,
+            ...(sessionDir === undefined ? {} : { sessionDir }),
+            ...(options.sessionForkPrompt === undefined ? {} : { forkPrompt: options.sessionForkPrompt }),
+        });
     const createRuntime = async ({ cwd, sessionManager: targetSessionManager, sessionStartEvent, }) => {
-        const services = await createAgentSessionServices({ cwd, agentDir: options.agentDir });
+        const { services, trust } = await createPiRuntimeServicesAfterTrust({
+            cwd,
+            agentDir: options.agentDir,
+            ...(options.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: options.projectTrustPrompt }),
+            ...(options.preflightDependencies === undefined ? {} : { preflightDependencies: options.preflightDependencies }),
+        });
         const modelScope = await resolveConfiguredModelScope(services);
         const hasExistingSession = targetSessionManager.buildSessionContext().messages.length > 0;
         const created = await createAgentSessionFromServices({
@@ -43,10 +86,18 @@ export async function createPiRuntimeIntegration(options) {
             ...(modelScope.thinkingLevel && !hasExistingSession ? { thinkingLevel: modelScope.thinkingLevel } : {}),
             ...(modelScope.scopedModels.length > 0 ? { scopedModels: [...modelScope.scopedModels] } : {}),
         });
-        return { ...created, services, diagnostics: [...modelScope.diagnostics] };
+        await markStartupPhase(process.env, "session-created");
+        return {
+            ...created,
+            services,
+            diagnostics: [
+                ...(trust.diagnostic === null ? [] : [{ type: "warning", message: trust.diagnostic }]),
+                ...modelScope.diagnostics,
+            ],
+        };
     };
     return createAgentSessionRuntime(createRuntime, {
-        cwd: options.cwd,
+        cwd: sessionManager.getCwd(),
         agentDir: options.agentDir,
         sessionManager,
     });

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/session-integration.d.ts

@@ -1,5 +1,5 @@
-import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import { type AgentCommandOutcome, type AgentEvent } from "../agent-engine-contracts/index.js";
+import type { AgentSession, AgentSessionEvent, PromptOptions } from "@earendil-works/pi-coding-agent";
+import { type AgentCommandOutcome, type AgentEvent } from "../../../contracts/agent-engine/index.js";
 export interface PiDocumentedSessionCommands {
     readonly isStreaming: AgentSession["isStreaming"];
     readonly isRetrying: AgentSession["isRetrying"];
@@ -18,6 +18,7 @@ export interface PiDocumentedSessionCommands {
 export type PiSessionCommand = {
     readonly type: "prompt" | "steer" | "follow-up";
     readonly text: string;
+    readonly images?: NonNullable<PromptOptions["images"]>;
 } | {
     readonly type: "abort" | "retry" | "compact";
 } | {
@@ -30,6 +31,7 @@ export interface PiSessionCommandResult {
     readonly outcome: AgentCommandOutcome;
     readonly value?: unknown;
 }
+/** Routes neutral session commands to Pi while preserving Pi streaming and retry semantics. */
 export declare class PiSessionCommandIntegration {
     #private;
     private readonly session;

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/session-integration.js

@@ -1,4 +1,5 @@
-import { AGENT_ENGINE_CONTRACT_VERSION, } from "../agent-engine-contracts/index.js";
+import { AGENT_ENGINE_CONTRACT_VERSION, } from "../../../contracts/agent-engine/index.js";
+/** Routes neutral session commands to Pi while preserving Pi streaming and retry semantics. */
 export class PiSessionCommandIntegration {
     session;
     #lastPrompt = null;
@@ -9,15 +10,29 @@ export class PiSessionCommandIntegration {
         switch (command.type) {
             case "prompt":
                 this.#lastPrompt = command.text;
-                await this.session.prompt(command.text, this.session.isStreaming ? { streamingBehavior: "followUp" } : undefined);
+                await this.session.prompt(command.text, command.images === undefined
+                    ? this.session.isStreaming ? { streamingBehavior: "followUp" } : undefined
+                    : {
+                        ...(this.session.isStreaming ? { streamingBehavior: "followUp" } : {}),
+                        images: [...command.images],
+                    });
                 return { outcome: "completed" };
             case "steer":
                 this.#lastPrompt = command.text;
-                await this.session.steer(command.text);
+                // Compatibility: match interactive Pi: prompt() owns template/extension expansion and
+                // turns the accepted steering message into the visible user row while
+                // later messages remain in the pending queue.
+                await this.session.prompt(command.text, {
+                    streamingBehavior: "steer",
+                    ...(command.images === undefined ? {} : { images: [...command.images] }),
+                });
                 return { outcome: "completed" };
             case "follow-up":
                 this.#lastPrompt = command.text;
-                await this.session.followUp(command.text);
+                await this.session.prompt(command.text, {
+                    streamingBehavior: "followUp",
+                    ...(command.images === undefined ? {} : { images: [...command.images] }),
+                });
                 return { outcome: "completed" };
             case "abort":
                 if (this.session.isRetrying)

package/dist/integrations/pi/engine/session-selection.d.ts

@@ -0,0 +1,28 @@
+import { SessionManager, type SessionInfo } from "@earendil-works/pi-coding-agent";
+export interface PiSessionSelection {
+    readonly target: string;
+    readonly sessionDir?: string;
+}
+export type PiSessionForkPrompt = (request: {
+    readonly sourceCwd: string;
+}) => Promise<boolean>;
+/** Expected resume outcomes are concise CLI diagnostics, not engine crashes. */
+export declare class PiSessionSelectionError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+interface SessionSelectionOptions {
+    readonly cwd: string;
+    readonly selection: PiSessionSelection;
+    readonly sessionDir?: string;
+    readonly forkPrompt?: PiSessionForkPrompt;
+    /** Public API seam for deterministic lookup/open race and listing-order evidence. */
+    readonly sessions?: Pick<typeof SessionManager, "list" | "open" | "forkFrom"> & {
+        readonly listAll: (sessionDir?: string) => Promise<SessionInfo[]>;
+    };
+}
+/** Pinned Pi 0.84.2 main.ts policy, using SDK APIs rather than importing the CLI. */
+export declare function openSelectedPiSession(options: SessionSelectionOptions): Promise<SessionManager>;
+/** Resolve before switching effective cwd, including quoted home-relative paths. */
+export declare function resolveSessionArgumentPath(path: string, cwd: string): string;
+export {};

package/dist/integrations/pi/engine/session-selection.js

@@ -0,0 +1,90 @@
+import { accessSync, constants, existsSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+/** Expected resume outcomes are concise CLI diagnostics, not engine crashes. */
+export class PiSessionSelectionError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "PiSessionSelectionError";
+    }
+}
+/** Pinned Pi 0.84.2 main.ts policy, using SDK APIs rather than importing the CLI. */
+export async function openSelectedPiSession(options) {
+    try {
+        const sessions = options.sessions ?? SessionManager;
+        const cwd = resolve(options.cwd);
+        const directory = options.selection.sessionDir ?? options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR;
+        const sessionDir = directory === undefined ? undefined : resolveSessionArgumentPath(directory, cwd);
+        const target = options.selection.target;
+        let path;
+        let global;
+        if (target.includes("/") || target.includes("\\") || target.endsWith(".jsonl")) {
+            path = resolveSessionArgumentPath(target, cwd);
+        }
+        else {
+            const local = matchSession(await sessions.list(cwd, sessionDir), target);
+            const globalMatch = local ? undefined : matchSession(await sessions.listAll(sessionDir), target);
+            // Compatibility: macOS may expose one temporary directory as /var to one process
+            // and /private/var to another. Physical path identity must not turn that alias into
+            // a cross-project fork prompt.
+            global = globalMatch && !sameProjectDirectory(globalMatch.cwd, cwd) ? globalMatch : undefined;
+            const matched = local ?? globalMatch;
+            if (!matched)
+                throw new PiSessionSelectionError(`No session found matching '${target}'`);
+            path = matched.path;
+        }
+        assertResumeFile(path);
+        if (global) {
+            if (!options.forkPrompt || !await options.forkPrompt({ sourceCwd: global.cwd })) {
+                throw new PiSessionSelectionError("Session resume cancelled.", 0);
+            }
+            assertResumeFile(path);
+            assertCwd(cwd);
+            return sessions.forkFrom(path, cwd, sessionDir);
+        }
+        // Invariant: no await between the final guard and SDK open. A disappeared target
+        // can otherwise produce a new in-memory header instead of an existing session.
+        const manager = sessions.open(path, sessionDir);
+        assertResumeFile(path);
+        assertCwd(manager.getCwd());
+        return manager;
+    }
+    catch (error) {
+        if (error instanceof PiSessionSelectionError)
+            throw error;
+        throw new PiSessionSelectionError(`Could not resume session: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function sameProjectDirectory(left, right) {
+    try {
+        const first = realpathSync.native(resolve(left));
+        const second = realpathSync.native(resolve(right));
+        return process.platform === "win32" ? first.toLowerCase() === second.toLowerCase() : first === second;
+    }
+    catch {
+        return resolve(left) === resolve(right);
+    }
+}
+function matchSession(sessions, target) {
+    return sessions.find(session => session.id === target) ?? sessions.find(session => session.id.startsWith(target));
+}
+/** Resolve before switching effective cwd, including quoted home-relative paths. */
+export function resolveSessionArgumentPath(path, cwd) {
+    const expanded = path === "~" ? homedir() : /^~[/\\]/.test(path) ? resolve(homedir(), path.slice(2)) : path;
+    return resolve(cwd, expanded);
+}
+function assertResumeFile(path) {
+    if (!existsSync(path))
+        throw new PiSessionSelectionError(`Session file does not exist: ${path}`);
+    const metadata = statSync(path);
+    if (!metadata.isFile() || metadata.size === 0)
+        throw new PiSessionSelectionError(`Session file is empty or not a regular file: ${path}`);
+    accessSync(path, constants.R_OK);
+}
+function assertCwd(cwd) {
+    if (!existsSync(cwd) || !statSync(cwd).isDirectory())
+        throw new PiSessionSelectionError(`Session working directory does not exist: ${cwd}`);
+}

package/dist/integrations/pi/engine/settings-effects.d.ts

@@ -0,0 +1,66 @@
+import type { AgentJsonValue, AgentSettingApplicationBoundary, AgentSettingChangeOutcome, AgentSettingOwner } from "../../../contracts/agent-engine/index.js";
+export type PiSettingKey = "autoCompact" | "showImages" | "imageWidthCells" | "autoResizeImages" | "blockImages" | "enableSkillCommands" | "steeringMode" | "followUpMode" | "transport" | "httpIdleTimeoutMs" | "thinkingLevel" | "theme" | "hideThinkingBlock" | "mermaidRenderingMode" | "showCacheMissNotices" | "collapseChangelog" | "enableInstallTelemetry" | "quietStartup" | "defaultProjectTrust" | "doubleEscapeAction" | "treeFilterMode" | "showHardwareCursor" | "editorPaddingX" | "outputPad" | "autocompleteMaxVisible" | "clearOnShrink" | "showTerminalProgress" | "tuiMode" | "fullscreenExitOutput" | "fullscreenScrollbar" | "warnings";
+export type PiSettingVisualClass = "none" | "transcript" | "transcript-geometry" | "editor-menu" | "queue-transcript" | "status-error" | "retry-error" | "footer-transcript" | "markdown" | "transcript-notice" | "startup-transcript" | "startup-selector" | "selector" | "terminal-cursor" | "editor-geometry" | "menu-geometry" | "terminal-frame" | "terminal-status" | "restored-parent-output" | "hidden";
+export interface PiSettingVisualEvidence {
+    /** Reviewed visual family; `none` still names the behavior that can emit styled diagnostics. */
+    readonly class: PiSettingVisualClass;
+    /** Pinned component, lifecycle, or provider-visible failure surface used as the visual authority. */
+    readonly pinnedSurface: string;
+    /** Independent pinned/A1 test or physical checkpoint that owns acceptance. */
+    readonly evidence: string;
+}
+export interface PiSettingEffectDefinition {
+    readonly application: AgentSettingApplicationBoundary;
+    readonly owner: AgentSettingOwner;
+    readonly visual: PiSettingVisualEvidence;
+    /** Bare A1 deliberately replaces this Pi behavior, so its settings UI omits the entry. */
+    readonly hiddenInBare?: true;
+}
+/**
+ * Reviewed effect authority for every generated Pi setting. Presentation remains
+ * generated; this table states who must make each accepted value observable.
+ */
+export declare const PI_SETTING_EFFECTS: Readonly<Record<PiSettingKey, PiSettingEffectDefinition>>;
+export interface PiSettingEffectHandler {
+    /** Install one value in the active owner. Handlers must be idempotent and reversible. */
+    apply(value: AgentJsonValue): void | Promise<void>;
+}
+export type PiSettingOwnerHandlers = Partial<Record<PiSettingKey, PiSettingEffectHandler>>;
+export interface PiSettingStorageOperation {
+    readonly key: PiSettingKey;
+    read(): AgentJsonValue;
+    validate(value: AgentJsonValue): void;
+    write(value: AgentJsonValue): void;
+}
+export interface PiSettingsCoordinatorOptions {
+    readonly productMode?: "bare" | "comparison";
+    readonly flush: () => Promise<void>;
+    readonly drainErrors?: () => readonly {
+        readonly error: Error;
+    }[];
+}
+/**
+ * One transactional authority for Pi setting validation, active effects,
+ * persistence, durability, rollback, and owner lifecycle.
+ */
+export declare class PiSettingsCoordinator {
+    #private;
+    constructor(operations: readonly PiSettingStorageOperation[], options: PiSettingsCoordinatorOptions);
+    bindOwner(owner: AgentSettingOwner, handlers: PiSettingOwnerHandlers): () => void;
+    unbindOwner(owner: AgentSettingOwner, keys?: readonly PiSettingKey[]): void;
+    definition(key: PiSettingKey): PiSettingEffectDefinition;
+    storedValue(key: PiSettingKey): AgentJsonValue;
+    effectiveValue(key: PiSettingKey): AgentJsonValue;
+    limitationReason(key: PiSettingKey): string | null;
+    available(key: PiSettingKey): boolean;
+    validate(key: PiSettingKey, value: AgentJsonValue): void;
+    apply(key: PiSettingKey, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
+    flush(): Promise<void>;
+    rollback(key: PiSettingKey, value: AgentJsonValue): Promise<void>;
+}
+export declare function settingsEffectInventoryDrift(presented: readonly string[], reviewed?: readonly string[]): {
+    readonly unmapped: readonly string[];
+    readonly stale: readonly string[];
+    readonly duplicated: readonly string[];
+};
+export declare function settingsVisualInventoryViolations(presented: readonly string[], reviewed?: Readonly<Partial<Record<PiSettingKey, PiSettingEffectDefinition>>>): readonly string[];

package/dist/integrations/pi/engine/settings-effects.js

@@ -0,0 +1,249 @@
+/**
+ * Reviewed effect authority for every generated Pi setting. Presentation remains
+ * generated; this table states who must make each accepted value observable.
+ */
+export const PI_SETTING_EFFECTS = Object.freeze({
+    autoCompact: effect("live", "agent", "transcript", "compaction status, summary, completion, and failure rows", "pinned-transcript-lifecycle-parity"),
+    showImages: effect("live", "shell", "transcript", "pinned inline image and textual fallback components", "pinned-transcript-image-parity"),
+    imageWidthCells: effect("live", "shell", "transcript-geometry", "pinned image component width and clipping", "pinned-transcript-image-parity"),
+    autoResizeImages: effect("live", "agent", "none", "provider image preparation and pinned warning row", "settings-effects-provider-parity"),
+    blockImages: effect("live", "agent", "none", "provider context conversion and pinned blocked-image notice", "settings-effects-provider-parity"),
+    enableSkillCommands: effect("live", "shell", "editor-menu", "pinned command autocomplete list", "pinned-editor-input-parity"),
+    steeringMode: effect("live", "agent", "queue-transcript", "pinned steering queue and submitted prompt rows", "pinned-status-indicator-parity"),
+    followUpMode: effect("live", "agent", "queue-transcript", "pinned follow-up queue and submitted prompt rows", "pinned-status-indicator-parity"),
+    transport: effect("live", "agent", "status-error", "pinned provider request status and failure rows", "settings-effects-provider-parity"),
+    httpIdleTimeoutMs: effect("live", "agent", "retry-error", "pinned timeout, retry, and terminal failure rows", "pinned-transcript-lifecycle-parity"),
+    thinkingLevel: effect("live", "agent", "footer-transcript", "pinned footer indicator, thinking rows, and clamp notice", "pinned-status-indicator-parity"),
+    theme: hiddenEffect("live", "shell", "pinned theme selector and complete themed shell", "pinned-theme-parity"),
+    hideThinkingBlock: effect("live", "shell", "transcript", "pinned thinking block presence and spacing", "pinned-transcript-lifecycle-parity"),
+    mermaidRenderingMode: effect("live", "shell", "markdown", "pinned Mermaid Markdown transformation", "pinned-assistant-content-parity"),
+    showCacheMissNotices: effect("live", "shell", "transcript-notice", "pinned cache-miss transcript notice", "pinned-transcript-lifecycle-parity"),
+    collapseChangelog: effect("next-start", "startup", "startup-transcript", "pinned startup and command changelog components", "pi-startup-composition-parity"),
+    enableInstallTelemetry: effect("next-start", "installation", "none", "install lifecycle and its pinned failure diagnostic", "settings-effects-installation-parity"),
+    quietStartup: hiddenEffect("next-start", "startup", "pinned startup suppression lifecycle", "pi-startup-composition-parity"),
+    defaultProjectTrust: effect("next-start", "startup", "startup-selector", "pinned pre-resource project trust selector", "project-trust-startup-parity"),
+    doubleEscapeAction: effect("live", "shell", "selector", "pinned tree or fork selector", "pinned-selector-parity"),
+    treeFilterMode: effect("live", "shell", "selector", "pinned tree selector filter, rows, and hints", "pinned-selector-parity"),
+    showHardwareCursor: effect("live", "terminal", "terminal-cursor", "pinned editor, overlay, blur, failure, and exit cursor operations", "pi-terminal-operation-parity"),
+    editorPaddingX: effect("live", "shell", "editor-geometry", "pinned editor border, padding, wrapping, and cursor column", "pinned-editor-input-parity"),
+    outputPad: effect("live", "shell", "transcript-geometry", "pinned transcript, tool, status, and error horizontal padding", "pinned-transcript-lifecycle-parity"),
+    autocompleteMaxVisible: effect("live", "shell", "menu-geometry", "pinned autocomplete clipping and editor anchoring", "pinned-editor-input-parity"),
+    clearOnShrink: effect("live", "terminal", "terminal-frame", "pinned resize clearing and resulting terminal frame", "pi-terminal-operation-parity"),
+    showTerminalProgress: effect("live", "terminal", "terminal-status", "pinned OSC progress lifecycle", "pi-terminal-operation-parity"),
+    tuiMode: hiddenEffect("next-session", "shell", "pinned regular/fullscreen selector and terminal lifecycle", "pi-terminal-operation-parity"),
+    fullscreenExitOutput: effect("current-exit", "shutdown", "restored-parent-output", "pinned styled transcript and compact dim resume hint", "pinned-fullscreen-exit-parity"),
+    fullscreenScrollbar: hiddenEffect("live", "shell", "pinned fullscreen scrollbar reservation", "pi-terminal-operation-parity"),
+    warnings: effect("live", "agent", "transcript-notice", "pinned warning rows by warning part", "pinned-transcript-lifecycle-parity"),
+});
+function effect(application, owner, visualClass, pinnedSurface, evidence) {
+    return { application, owner, visual: { class: visualClass, pinnedSurface, evidence } };
+}
+function hiddenEffect(application, owner, pinnedSurface, evidence) {
+    return { application, owner, hiddenInBare: true, visual: { class: "hidden", pinnedSurface, evidence } };
+}
+/**
+ * One transactional authority for Pi setting validation, active effects,
+ * persistence, durability, rollback, and owner lifecycle.
+ */
+export class PiSettingsCoordinator {
+    #operations;
+    #handlers = new Map();
+    #state = new Map();
+    #productMode;
+    #flushStorage;
+    #drainErrors;
+    constructor(operations, options) {
+        this.#operations = new Map(operations.map(operation => [operation.key, operation]));
+        this.#productMode = options.productMode ?? "bare";
+        this.#flushStorage = options.flush;
+        this.#drainErrors = options.drainErrors;
+        for (const operation of operations) {
+            const stored = operation.read();
+            this.#state.set(operation.key, { stored, effective: stored, inconsistentReason: null });
+        }
+    }
+    bindOwner(owner, handlers) {
+        const bound = [];
+        for (const [candidate, handler] of Object.entries(handlers)) {
+            if (handler === undefined)
+                continue;
+            const key = candidate;
+            const definition = PI_SETTING_EFFECTS[key];
+            if (definition === undefined)
+                throw new Error(`unknown Pi setting effect: ${key}`);
+            if (definition.owner !== owner)
+                throw new Error(`${key} belongs to ${definition.owner}, not ${owner}`);
+            if (this.#productMode === "bare" && definition.hiddenInBare === true) {
+                throw new Error(`${key} is hidden in bare A1`);
+            }
+            this.#handlers.set(key, handler);
+            bound.push(key);
+        }
+        return () => this.unbindOwner(owner, bound);
+    }
+    unbindOwner(owner, keys) {
+        const candidates = keys ?? [...this.#handlers.keys()];
+        for (const key of candidates)
+            if (PI_SETTING_EFFECTS[key].owner === owner)
+                this.#handlers.delete(key);
+    }
+    definition(key) {
+        return PI_SETTING_EFFECTS[key];
+    }
+    storedValue(key) {
+        const operation = this.#requireOperation(key);
+        const stored = operation.read();
+        const state = this.#requireState(key);
+        state.stored = stored;
+        return stored;
+    }
+    effectiveValue(key) {
+        return this.#requireState(key).effective;
+    }
+    limitationReason(key) {
+        const definition = PI_SETTING_EFFECTS[key];
+        if (this.#productMode === "bare" && definition.hiddenInBare === true)
+            return "setting is not available in the active product mode";
+        const inconsistent = this.#requireState(key).inconsistentReason;
+        if (inconsistent !== null)
+            return inconsistent;
+        if (!this.#handlers.has(key))
+            return `${definition.owner} effect is not bound for ${definition.application} application`;
+        return null;
+    }
+    available(key) {
+        return this.limitationReason(key) === null;
+    }
+    validate(key, value) {
+        this.#requireOperation(key).validate(value);
+    }
+    async apply(key, value) {
+        const operation = this.#requireOperation(key);
+        operation.validate(value);
+        const definition = PI_SETTING_EFFECTS[key];
+        const previousStored = operation.read();
+        const state = this.#requireState(key);
+        const previousEffective = state.effective;
+        const limitationReason = this.limitationReason(key);
+        if (limitationReason !== null) {
+            return outcome("unavailable", definition.application, previousStored, previousEffective, null, limitationReason);
+        }
+        const handler = this.#handlers.get(key);
+        if (definition.application !== "live") {
+            try {
+                operation.write(value);
+                await this.flush();
+                state.stored = value;
+                return outcome("deferred", definition.application, value, previousEffective, null, null);
+            }
+            catch (error) {
+                const failure = await this.#restorePersistence(operation, previousStored, error);
+                state.stored = operation.read();
+                return outcome("failed", definition.application, state.stored, previousEffective, failure, null);
+            }
+        }
+        try {
+            await handler.apply(value);
+        }
+        catch (error) {
+            return outcome("failed", definition.application, previousStored, previousEffective, describe(error), null);
+        }
+        state.effective = value;
+        try {
+            operation.write(value);
+            await this.flush();
+            state.stored = value;
+            state.inconsistentReason = null;
+            return outcome("applied", definition.application, value, value, null, null);
+        }
+        catch (error) {
+            const persistenceFailure = await this.#restorePersistence(operation, previousStored, error);
+            try {
+                await handler.apply(previousEffective);
+                state.effective = previousEffective;
+                state.stored = operation.read();
+                return outcome("failed", definition.application, state.stored, previousEffective, persistenceFailure, null);
+            }
+            catch (rollbackError) {
+                state.stored = operation.read();
+                state.inconsistentReason = `rollback failed after ${persistenceFailure}: ${describe(rollbackError)}`;
+                return outcome("failed", definition.application, state.stored, state.effective, state.inconsistentReason, state.inconsistentReason);
+            }
+        }
+    }
+    async flush() {
+        await this.#flushStorage();
+        const errors = this.#drainErrors?.() ?? [];
+        if (errors.length > 0)
+            throw new Error(errors.map(value => value.error.message).join("; "));
+    }
+    async rollback(key, value) {
+        const handler = this.#handlers.get(key);
+        if (handler === undefined)
+            throw new Error(`cannot roll back unbound setting: ${key}`);
+        await handler.apply(value);
+        this.#requireState(key).effective = value;
+    }
+    async #restorePersistence(operation, previous, cause) {
+        const original = describe(cause);
+        try {
+            operation.write(previous);
+            await this.flush();
+            return original;
+        }
+        catch (rollbackError) {
+            return `${original}; persistence rollback failed: ${describe(rollbackError)}`;
+        }
+    }
+    #requireOperation(key) {
+        const operation = this.#operations.get(key);
+        if (operation === undefined)
+            throw new Error(`setting is unavailable: ${key}`);
+        return operation;
+    }
+    #requireState(key) {
+        const state = this.#state.get(key);
+        if (state === undefined)
+            throw new Error(`setting state is unavailable: ${key}`);
+        return state;
+    }
+}
+export function settingsEffectInventoryDrift(presented, reviewed = Object.keys(PI_SETTING_EFFECTS)) {
+    const reviewedSet = new Set(reviewed);
+    const presentedSet = new Set(presented);
+    const counts = new Map();
+    for (const key of reviewed)
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    return {
+        unmapped: presented.filter(key => !reviewedSet.has(key)),
+        stale: reviewed.filter(key => !presentedSet.has(key)),
+        duplicated: [...counts].filter(([, count]) => count > 1).map(([key]) => key),
+    };
+}
+export function settingsVisualInventoryViolations(presented, reviewed = PI_SETTING_EFFECTS) {
+    const violations = [];
+    for (const candidate of presented) {
+        const key = candidate;
+        const definition = reviewed[key];
+        if (definition === undefined) {
+            violations.push(`${candidate}: missing visual classification`);
+            continue;
+        }
+        const visual = definition.visual;
+        if (!visual || visual.pinnedSurface.trim().length === 0)
+            violations.push(`${candidate}: missing pinned visual source`);
+        if (!visual || visual.evidence.trim().length === 0)
+            violations.push(`${candidate}: missing independent visual evidence`);
+        if (definition.hiddenInBare === true && visual?.class !== "hidden")
+            violations.push(`${candidate}: hidden setting declares a visible frame`);
+        if (definition.hiddenInBare !== true && visual?.class === "hidden")
+            violations.push(`${candidate}: visible setting declares hidden evidence`);
+    }
+    return violations;
+}
+function outcome(status, application, storedValue, effectiveValue, failure, limitationReason) {
+    return { status, application, storedValue, effectiveValue, failure, limitationReason };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}