@timurproko/a1 0.2.6 → 0.2.7-dev.1221

package/dist/composition/resident-tab-bridge.js

@@ -0,0 +1,180 @@
+import { residentUtilityRoute } from "../foundation/resident-tabs/routes.js";
+import { deriveResidentTabStatus } from "../features/resident-tab/status-deriver.js";
+import { projectResidentTabShortcuts } from "../features/resident-tab/shortcut-projection.js";
+import { readShortcutBindingsFile } from "../features/resident-tab/shortcut-bindings-file.js";
+/**
+ * The keybindings the shells borrow. Inside a resident tab the host dispatches and labels the tab
+ * shortcuts this child projects from its effective declarations, so the projection is published now
+ * and again after every customization reload.
+ */
+export function residentTabKeybindings(tabBridge, agentDir, keybindingsHost) {
+    if (tabBridge === null)
+        return keybindingsHost;
+    const publish = () => tabBridge.shortcuts(projectResidentTabShortcuts({
+        configured: readShortcutBindingsFile(agentDir),
+        reserved: keybindingsHost.manager.getEffectiveConfig(),
+    }).assignments);
+    publish();
+    return { ...keybindingsHost, reload: () => { keybindingsHost.reload(); publish(); } };
+}
+/**
+ * How owned screens are presented in a resident tab: a Settings or Changelog tab's screen is the tab, and the Plus menu entry opens
+ * the tab bar's own Plus Menu dialog while this tab's controlling client can show it.
+ */
+export function residentRouteHostOptions(tabBridge) {
+    return {
+        ...(tabBridge === null ? {} : { tabRoute: residentUtilityRoute(tabBridge.tabId) }),
+        configurePlusMenu: () => {
+            if (tabBridge === null || !tabBridge.available || tabBridge.captureAttachment() === null)
+                return false;
+            void tabBridge.requestAction("configure-plus");
+            return true;
+        },
+    };
+}
+/** Closes a utility tab when its own screen closes. Invariant: a utility tab's screen is the tab. */
+export function closeResidentUtilityRoute(tabBridge, route) {
+    if (residentUtilityRoute(tabBridge.tabId) === route)
+        void tabBridge.requestClose();
+}
+export async function bindResidentTabBridge(tabBridge, backend, recovery = null, options = {}) {
+    await tabBridge.start().catch(() => false);
+    tabBridge.status("starting");
+    const currentSessionFile = () => currentBackendSessionFile(backend);
+    let pendingAutoName = null;
+    // Invariant: while a generated name is being applied, the session name it produces is automatic
+    // even if the session normalizes it; reporting it as `user` would block the strip's title
+    // animation and every later automatic rename.
+    let applyingAutoName = false;
+    const isDefaultName = (name) => name == null || /^agent(?: \d+)?$/i.test(name);
+    const currentSessionName = () => backend.session.view().status.footer?.sessionName ?? null;
+    const announceSession = () => {
+        const name = currentSessionName();
+        // Invariant: the session may announce the applied name after the workflow resolves; the
+        // first non-default name announced for a pending auto-name is that automatic name.
+        if (applyingAutoName && !isDefaultName(name)) {
+            pendingAutoName = name;
+            applyingAutoName = false;
+        }
+        const automatic = name === pendingAutoName;
+        const nameSource = automatic ? "auto" : isDefaultName(name) ? "default" : "user";
+        tabBridge.session(currentSessionFile(), name, nameSource);
+    };
+    let working = false;
+    // Invariant: the last turn's settlement stays reported until the next turn starts.
+    let lastTurn;
+    let autoNameAttempted = false;
+    let autoNameArmed = false;
+    // Invariant: naming launches once per tab during an agent run, as soon as its prompt is projected,
+    // and runs beside the turn instead of waiting for it to settle.
+    const launchAutoName = () => {
+        if (!autoNameArmed || autoNameAttempted || options.autoName !== true || !isDefaultName(currentSessionName()))
+            return;
+        const prompt = backend.session.view().transcript.find(block => block.kind === "user")?.text.trim();
+        if (!prompt)
+            return;
+        autoNameAttempted = true;
+        void import("../features/resident-tab/index.js").then(({ generateAutoName }) => generateAutoName(prompt, request => backend.generateResidentTabName(request.prompt, request.maxTokens, request.signal))).then(async (name) => {
+            // Invariant: a manual rename made while generation was pending owns both the session and the tab.
+            if (!isDefaultName(currentSessionName()))
+                return;
+            pendingAutoName = name;
+            applyingAutoName = true;
+            const result = await backend.workflows.executeWorkflow({ command: "name", argument: name });
+            if (result.outcome !== "completed") {
+                applyingAutoName = false;
+                if (pendingAutoName === name)
+                    pendingAutoName = null;
+                return;
+            }
+            const current = currentSessionName();
+            if (current !== null && !isDefaultName(current)) {
+                // Invariant: The session already holds the applied name; report it as automatic now.
+                pendingAutoName = current;
+                applyingAutoName = false;
+                tabBridge.session(currentSessionFile(), current, "auto");
+            }
+            else {
+                // Invariant: The session announces later; show the generated name meanwhile, still automatic.
+                tabBridge.session(currentSessionFile(), name, "auto");
+            }
+        }).catch(() => { pendingAutoName = null; applyingAutoName = false; });
+    };
+    const reportStatus = (lifecycle) => {
+        const view = backend.session.view();
+        const pendingRequests = view.dialog == null ? 0 : 1;
+        const queuedInput = view.editor?.queuedSubmissions.length ?? 0;
+        tabBridge.status(deriveResidentTabStatus({
+            lifecycle: lifecycle ?? view.lifecycle,
+            pendingRequests,
+            queuedInput,
+            ...(lastTurn === undefined ? {} : { lastTurn }),
+        }), false, pendingRequests, queuedInput);
+    };
+    announceSession();
+    const unsubscribeCommands = typeof tabBridge.onCommand === "function" ? tabBridge.onCommand(command => {
+        // Invariant: visibility stays decoded for generation-1 peers but never pauses rendering; a hidden tab
+        // keeps its resident terminal current while the holder withholds only its client surfaces.
+        if (command.type === "rename") {
+            void backend.workflows.executeWorkflow({ command: "name", argument: command.name }).catch(() => { });
+        }
+        else if (command.type === "route") {
+            if (options.openRoute !== undefined)
+                options.openRoute(command.route);
+            else
+                void backend.workflows.executeWorkflow({ command: command.route, argument: "" }).catch(() => { });
+        }
+        else if (command.type === "stop") {
+            void backend.session.dispose().catch(() => { });
+        }
+    }) : () => { };
+    const unsubscribeEvents = backend.session.onEvent(event => {
+        if (event.type === "session-lifecycle") {
+            const wasWorking = working;
+            working = event.lifecycle === "busy";
+            if (working)
+                lastTurn = undefined;
+            reportStatus(event.lifecycle);
+            if (wasWorking && !working && recovery !== null) {
+                void recovery.settled(currentSessionFile()).catch(() => tabBridge.degraded(true));
+            }
+        }
+        if (event.type === "agent-run-started") {
+            autoNameArmed = true;
+            launchAutoName();
+        }
+        // Rationale: Pi starts the run before it projects the user message, so the prompt may arrive later.
+        if (event.type === "transcript-block" || event.type === "session-view")
+            launchAutoName();
+        if (event.type === "agent-run-settled") {
+            launchAutoName();
+            autoNameArmed = false;
+            lastTurn = event.aborted ? "aborted" : event.successful ? "done" : "error";
+            tabBridge.prompt(event.aborted);
+            reportStatus();
+        }
+        if (event.type === "session-view") {
+            announceSession();
+            reportStatus();
+        }
+    });
+    return () => {
+        unsubscribeCommands();
+        unsubscribeEvents();
+    };
+}
+export async function correlateResidentTabSubmission(recovery, backend, submissionId, entryId) {
+    await recovery.correlated(submissionId, entryId);
+    // Concurrency: a normal prompt command can resolve after the ready transition already fired.
+    // Re-read lifecycle only after correlation is active; a concurrent ready observer and this path
+    // safely race because recovery consumes the active entry once and retirement is idempotent.
+    if (backend.session.view().lifecycle !== "busy")
+        await recovery.settled(currentBackendSessionFile(backend));
+}
+export function currentBackendSessionFile(backend) {
+    const direct = backend.identity.currentSessionFile?.();
+    if (direct !== undefined && direct !== null)
+        return direct;
+    const resume = backend.identity.currentSessionResumeMetadata();
+    return resume === null ? null : `${resume.sessionDir}/${resume.sessionId}`;
+}

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

@@ -0,0 +1,19 @@
+import type { AgentSettingsPort } from "../contracts/agent-engine/index.js";
+import type { OwnedUiPromptSuggestionGeneratorPort, UiAccentColor } from "../contracts/owned-ui/index.js";
+import type { PiEngineSessionRequest } from "../integrations/pi/engine/host.js";
+import type { PiSessionPresenterBackend } from "../integrations/pi/session-presenters/index.js";
+/**
+ * The session backend composition wires: the owned-UI port, the prompt-suggestion generator, and
+ * the agent settings port. `settingsPort` stays outside the owned-UI contract because its type
+ * belongs to the agent-engine contracts, which the owned-UI contract may not import.
+ */
+export interface ComposedSessionBackend extends PiSessionPresenterBackend, OwnedUiPromptSuggestionGeneratorPort {
+    settingsPort(): AgentSettingsPort | null;
+    generateResidentTabName(instruction: string, maxTokens: number, signal: AbortSignal): Promise<string | null>;
+}
+/** The process-level engine host as composition drives it: sessions, the live accent, and disposal. */
+export interface ComposedEngineHost {
+    create(request: PiEngineSessionRequest): Promise<ComposedSessionBackend>;
+    setAccentColor(color: UiAccentColor): void;
+    dispose(): Promise<void>;
+}

package/dist/composition/session-backend.js

@@ -0,0 +1 @@
+export {};

package/dist/composition/session-runtime-registry.d.ts

@@ -0,0 +1,20 @@
+import type { NativeProcessIdentity } from "../foundation/lifecycle/model.js";
+export interface SessionRuntimeRegistryOptions {
+    /** This runtime's id from the environment; absent outside a runtime that claims worktrees. */
+    readonly runtimeId: string | undefined;
+    /** Exact native process inspection; absent SDK seams publish no claims. */
+    readonly inspectProcess: ((pid: number) => Promise<NativeProcessIdentity | null>) | undefined;
+    readonly refreshMs?: number;
+}
+/**
+ * The live worktree claims this runtime's agents hold: each agent's session identity, the heartbeat
+ * that keeps the claims fresh, and their release when the runtime is disposed.
+ */
+export declare class SessionRuntimeRegistry {
+    #private;
+    constructor(options: SessionRuntimeRegistryOptions);
+    /** The repository context reader for one agent; undefined names the primary agent. */
+    readerFor(agentId: string | undefined): (sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<import("../foundation/lifecycle/session-repository-context.js").SessionRepositoryContext | null>;
+    /** Stops the heartbeat, waits for an in-flight refresh, and releases every claim this runtime holds. */
+    dispose(): Promise<void>;
+}

package/dist/composition/session-runtime-registry.js

@@ -0,0 +1,85 @@
+const SESSION_RUNTIME_REFRESH_MS = 30_000;
+/**
+ * The live worktree claims this runtime's agents hold: each agent's session identity, the heartbeat
+ * that keeps the claims fresh, and their release when the runtime is disposed.
+ */
+export class SessionRuntimeRegistry {
+    #options;
+    // Invariant: one entry per agent of this runtime; each agent holds its own claim, and the runtime's exit releases all.
+    #identities = new Map();
+    #owner = null;
+    #timer = null;
+    #refresh = Promise.resolve();
+    #disposed = false;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** The repository context reader for one agent; undefined names the primary agent. */
+    readerFor(agentId) {
+        return async (sessionId, sessionFile, signal) => {
+            const { runtimeId, inspectProcess } = this.#options;
+            const owner = await this.#ownerIdentity();
+            if (owner === null || runtimeId === undefined || inspectProcess === undefined)
+                return null;
+            const identity = { sessionId, sessionFile };
+            this.#identities.set(agentId, identity);
+            const { activateSessionRepositoryContext } = await import("../foundation/lifecycle/session-repository-context.js");
+            const context = await activateSessionRepositoryContext(identity, runtimeId, owner, {
+                signal,
+                inspectProcess,
+                ...(agentId === undefined ? {} : { agentId }),
+            });
+            this.#arm();
+            return context;
+        };
+    }
+    /** Stops the heartbeat, waits for an in-flight refresh, and releases every claim this runtime holds. */
+    async dispose() {
+        this.#disposed = true;
+        if (this.#timer !== null)
+            clearInterval(this.#timer);
+        this.#timer = null;
+        await this.#refresh;
+        const { runtimeId } = this.#options;
+        const owner = await this.#ownerIdentity();
+        if (runtimeId === undefined || owner === null)
+            return;
+        await import("../foundation/lifecycle/session-repository-context.js")
+            .then(module => module.releaseSessionRepositoryRuntime(runtimeId, owner))
+            .catch(() => undefined);
+    }
+    async #ownerIdentity() {
+        const { runtimeId, inspectProcess } = this.#options;
+        if (runtimeId === undefined || inspectProcess === undefined)
+            return null;
+        this.#owner ??= inspectProcess(process.pid).catch(() => null);
+        return await this.#owner;
+    }
+    #arm() {
+        if (this.#timer !== null)
+            return;
+        this.#timer = setInterval(() => this.#queueRefresh(), this.#options.refreshMs ?? SESSION_RUNTIME_REFRESH_MS);
+        this.#timer.unref();
+    }
+    #queueRefresh() {
+        const { runtimeId, inspectProcess } = this.#options;
+        if (this.#disposed || this.#identities.size === 0 || runtimeId === undefined || inspectProcess === undefined)
+            return;
+        this.#refresh = this.#refresh.then(async () => {
+            if (this.#disposed)
+                return;
+            const owner = await this.#ownerIdentity();
+            if (owner === null)
+                return;
+            const { registerSessionRepositoryRuntime } = await import("../foundation/lifecycle/session-repository-context.js");
+            for (const [agentId, identity] of this.#identities) {
+                if (this.#disposed)
+                    return;
+                await registerSessionRepositoryRuntime(identity, runtimeId, owner, {
+                    inspectProcess,
+                    ...(agentId === undefined ? {} : { agentId }),
+                }).catch(() => undefined);
+            }
+        }).catch(() => undefined);
+    }
+}

package/dist/composition/settings-route-host.d.ts

@@ -1,6 +1,7 @@
 import type { ReferenceDocumentProvider } from "../features/owned-ui/reference-screen-app.js";
 import type { OwnedSettingsManager } from "../ui/settings/manager.js";
 import type { UiRouteHost, UiRouteInput } from "../ui/apps/contracts.js";
+import type { PiKeybindingsHost } from "../integrations/pi/components/shell-shared-facade.js";
 /** Styled document rows for one content width. */
 export type OwnedReferenceRows = NonNullable<ReferenceDocumentProvider["rows"]>;
 /** Documents supplied by composition so the route host never reads shell data itself. */
@@ -9,5 +10,19 @@ export interface OwnedReferenceProviders {
     hotkeys(): Promise<ReferenceDocumentProvider>;
     session(): Promise<ReferenceDocumentProvider>;
 }
+/** How the settings route is presented. */
+export interface OwnedRouteHostOptions {
+    /**
+     * The route whose screen is this resident utility tab. That screen is the tab, so it offers no
+     * screen-level close: neither Esc nor one Ctrl+C dismisses it, and it shows no close hint.
+     */
+    readonly tabRoute?: string | null;
+    /** Opens the tab bar's own Plus Menu dialog; false when no tab bar can show it. */
+    readonly configurePlusMenu?: () => boolean;
+    readonly keybindings?: PiKeybindingsHost;
+    readonly agentDir?: string;
+    readonly cwd?: string;
+    readonly copyText?: (text: string) => void;
+}
 /** Declares settings and lazy document routes. */
-export declare function createOwnedRouteHost(settings: OwnedSettingsManager, references?: OwnedReferenceProviders): UiRouteHost;
+export declare function createOwnedRouteHost(settings: OwnedSettingsManager, references?: OwnedReferenceProviders, options?: OwnedRouteHostOptions): UiRouteHost;

package/dist/composition/settings-route-host.js

@@ -3,7 +3,7 @@ import { SETTINGS_APP_ID, SETTINGS_ROUTE } from "../features/owned-ui/settings-r
 import { piTheme, renderPiAccentPreview } from "../integrations/pi/components/upstream/theme/theme.js";
 import { faint } from "../ui/components/text.js";
 /** Declares settings and lazy document routes. */
-export function createOwnedRouteHost(settings, references) {
+export function createOwnedRouteHost(settings, references, options = {}) {
     const routes = new Set([SETTINGS_ROUTE, ...(references === undefined ? [] : [CHANGELOG_ROUTE, HOTKEYS_ROUTE, "session"])]);
     return {
         claims: route => routes.has(route),
@@ -11,13 +11,14 @@ export function createOwnedRouteHost(settings, references) {
             if (!routes.has(route))
                 return null;
             if (route === SETTINGS_ROUTE) {
-                return deferredSurface(SETTINGS_APP_ID, "settings", () => loadSettingsSurface(settings));
+                return deferredSurface(SETTINGS_APP_ID, "settings", () => loadSettingsSurface(settings, options));
             }
             const changelog = route === CHANGELOG_ROUTE;
             const session = route === "session";
             const title = session ? "Session Info" : changelog ? input ? "What's New" : "Changelog" : HOTKEYS_TITLE;
             const document = session ? references.session() : changelog ? references.changelog(input) : references.hotkeys();
-            return deferredSurface(route, title, () => loadReferenceSurface(settings, route, route, title, document));
+            const pinned = options.tabRoute === route;
+            return deferredSurface(route, title, () => loadReferenceSurface(settings, route, title, document, pinned));
         },
     };
 }
@@ -61,11 +62,27 @@ function deferredSurface(id, label, load) {
         onExitRequested: listener => { onExit = listener; },
     };
 }
-async function loadSettingsSurface(settings) {
-    const { SettingsApp } = await import("../features/owned-ui/settings-app.js");
-    return hostApp(SETTINGS_APP_ID, SETTINGS_ROUTE, () => new SettingsApp(settings));
+async function loadSettingsSurface(settings, options) {
+    const [{ SettingsApp }, { createSettingsSearchInputFactory }] = await Promise.all([
+        import("../features/owned-ui/settings-app.js"),
+        import("./settings-search-input.js"),
+    ]);
+    const pinned = options.tabRoute === SETTINGS_ROUTE;
+    const searchInputFactory = createSettingsSearchInputFactory({
+        ...(options.keybindings === undefined ? {} : { keybindings: options.keybindings }),
+        ...(options.agentDir === undefined ? {} : { agentDir: options.agentDir }),
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+    });
+    // Invariant: a pinned Settings tab closes as a tab; neither Esc nor one unclaimed Ctrl+C dismisses its screen.
+    return hostApp(SETTINGS_APP_ID, SETTINGS_ROUTE, () => new SettingsApp(settings, {
+        pinned,
+        searchInputFactory,
+        configurePlusMenu: options.configurePlusMenu ?? null,
+        ...(options.copyText === undefined ? {} : { copyText: options.copyText }),
+    }), !pinned, true);
 }
-async function loadReferenceSurface(settings, id, route, title, document) {
+async function loadReferenceSurface(settings, route, title, document, pinned) {
+    const id = route;
     // Rationale: the app module and the document load together, so a document that fails
     // to render is reported by the placeholder rather than by a screen that never fills.
     const [{ ReferenceScreenApp }, content] = await Promise.all([import("../features/owned-ui/reference-screen-app.js"), document]);
@@ -78,9 +95,10 @@ async function loadReferenceSurface(settings, id, route, title, document) {
             scrollbarStyle: settings.value("scrollbarStyle"),
             scrollbarSpeed: settings.value("scrollbarSpeed"),
         }),
-    }));
+        pinned,
+    }), !pinned);
 }
-async function hostApp(id, route, create) {
+async function hostApp(id, route, create, closeOnInterrupt = true, appInputBeforeInterrupt = false) {
     const [{ UiAppHost }, { UiAppRegistry }] = await Promise.all([
         import("../ui/apps/host.js"),
         import("../ui/apps/registry.js"),
@@ -94,7 +112,8 @@ async function hostApp(id, route, create) {
     let onExit = () => undefined;
     const host = new UiAppHost({
         registry,
-        closeOnInterrupt: true,
+        closeOnInterrupt,
+        appInputBeforeInterrupt,
         theme: pinnedTheme(),
         surface: {
             size: () => size,

package/dist/composition/settings-search-input.d.ts

@@ -0,0 +1,9 @@
+import type { SettingsSearchInputFactory } from "../features/owned-ui/settings-search-input.js";
+import { type PiKeybindingsHost } from "../integrations/pi/components/shell-shared-facade.js";
+export interface SettingsSearchInputFactoryOptions {
+    readonly keybindings?: PiKeybindingsHost;
+    readonly agentDir?: string;
+    readonly cwd?: string;
+}
+/** Builds Settings search from the same configurable owned editor used by the agent prompt. */
+export declare function createSettingsSearchInputFactory(options?: SettingsSearchInputFactoryOptions): SettingsSearchInputFactory;

package/dist/composition/settings-search-input.js

@@ -0,0 +1,58 @@
+import { editorInsertedText } from "../integrations/pi/components/owned-editor-ux.js";
+import { createPiShellEditor } from "../integrations/pi/components/shell-editor-autocomplete.js";
+import { piShellTruncateToWidth, piShellVisibleWidth, } from "../integrations/pi/components/shell-shared-facade.js";
+import { backgroundSgrSpan } from "../ui/components/spans.js";
+import { caretCell } from "../ui/components/line-input.js";
+import { PromptInput } from "../ui/components/prompt-input.js";
+/** Builds Settings search from the same configurable owned editor used by the agent prompt. */
+export function createSettingsSearchInputFactory(options = {}) {
+    return {
+        isTextInput: data => {
+            const text = editorInsertedText(data);
+            return text !== undefined && /[^\p{Cc}]/u.test(text);
+        },
+        create: surface => createSettingsSearchInput(surface, options),
+    };
+}
+function createSettingsSearchInput(surface, options) {
+    let columns = 80;
+    const editor = createPiShellEditor({
+        keybindingProfile: "a1",
+        inputCapabilities: {
+            singleLine: true,
+            paste: false,
+            autocomplete: false,
+            placeholder: "Search settings",
+        },
+        ...(options.keybindings === undefined ? {} : { keybindings: options.keybindings }),
+        ...(options.agentDir === undefined ? {} : { agentDir: options.agentDir }),
+        cwd: options.cwd ?? process.cwd(),
+        getColumns: () => columns,
+        getRows: surface.getRows,
+        requestRender: surface.requestRender,
+        onSubmit: () => { },
+        onCopyText: text => surface.copyText(text),
+        paintEditorSelection: (line, from, to, atomic) => backgroundSgrSpan(line, from, to, atomic ? "\u001b[7m" : "\u001b[27m\u001b[48;2;38;79;120m", atomic ? "\u001b[27m" : "\u001b[49m", piShellVisibleWidth),
+        promptPresentation: {
+            input: new PromptInput({ fg: (token, text) => surface.theme.fg(token, text) }, {
+                measure: piShellVisibleWidth,
+                truncate: piShellTruncateToWidth,
+            }),
+            styleSuggestion: text => surface.theme.fg("dim", text),
+            styleSuggestionCaret: caretCell,
+        },
+    });
+    editor.setFocused?.(true);
+    return {
+        render(width) {
+            columns = width;
+            return editor.render(width);
+        },
+        handleInput: (data) => editor.handleInput?.(data),
+        handlePointer: (event) => editor.handlePointer(event),
+        getText: () => editor.getText(),
+        hasSelection: () => editor.hasSelection(),
+        ownsPointer: () => editor.ownsPointer(),
+        setFocused: (focused) => editor.setFocused?.(focused),
+    };
+}

package/dist/composition/startup-route.d.ts

@@ -0,0 +1,32 @@
+import type { OwnedUiShellEngineOptions } from "../app/session-shell/index.js";
+import type { ReleaseNoteCatalog } from "../features/owned-ui/release-notes.js";
+type StartupRoute = NonNullable<OwnedUiShellEngineOptions["startupRoute"]>;
+export interface StartupReleaseNoteOptions {
+    readonly ownedSurfaces: boolean;
+    /** Deterministic catalog and version seams for composition tests. */
+    readonly releaseNotes?: ReleaseNoteCatalog;
+    readonly packageVersion?: string;
+    /** Without a profile there is nowhere to remember the note as seen, so it is never shown on startup. */
+    readonly profileId?: string;
+    readonly configDir: string;
+}
+export declare function readPackageVersion(): Promise<string>;
+/**
+ * The release notes bare A1 ships and the one note this version shows once per profile on startup:
+ * the packaged catalog (or why it could not be read), the running version, and the claim that
+ * marks the note seen after its route closes.
+ */
+export declare class StartupReleaseNote {
+    #private;
+    readonly catalog: ReleaseNoteCatalog | null;
+    readonly failure: unknown;
+    readonly packageVersion: string | null;
+    static load(options: StartupReleaseNoteOptions): Promise<StartupReleaseNote>;
+    private constructor();
+    /** The changelog route to present after the first frame, or undefined when there is no unseen note to show. */
+    get startupRoute(): StartupRoute | undefined;
+    /** Waits for a pending acknowledgement; a failed one stays unseen and is never reported. */
+    settleAcknowledgement(): Promise<void>;
+    releaseClaim(): Promise<void>;
+}
+export {};

package/dist/composition/startup-route.js

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+export async function readPackageVersion() {
+    const manifest = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
+    const version = manifest?.version;
+    if (typeof version !== "string")
+        throw new Error("A1 package version is unavailable");
+    return version;
+}
+/**
+ * The release notes bare A1 ships and the one note this version shows once per profile on startup:
+ * the packaged catalog (or why it could not be read), the running version, and the claim that
+ * marks the note seen after its route closes.
+ */
+export class StartupReleaseNote {
+    catalog;
+    failure;
+    packageVersion;
+    #current;
+    #claim;
+    #acknowledgement = null;
+    static async load(options) {
+        let catalog = null;
+        let failure;
+        if (options.ownedSurfaces) {
+            try {
+                catalog = options.releaseNotes
+                    ?? await import("../features/owned-ui/release-notes.js").then(module => module.readPackagedReleaseNotes());
+            }
+            catch (error) {
+                failure = error;
+            }
+        }
+        const packageVersion = options.ownedSurfaces ? options.packageVersion ?? await readPackageVersion() : null;
+        const current = packageVersion === null ? null : catalog?.current(packageVersion) ?? null;
+        const profileId = options.profileId;
+        const claim = current === null || profileId === undefined
+            ? null
+            : await import("../features/owned-ui/release-note-state.js").then(module => module.claimReleaseNote({
+                configDir: options.configDir, profileId, version: current.version,
+            }));
+        return new StartupReleaseNote(catalog, failure, packageVersion, current, claim);
+    }
+    constructor(catalog, failure, packageVersion, current, claim) {
+        this.catalog = catalog;
+        this.failure = failure;
+        this.packageVersion = packageVersion;
+        this.#current = current;
+        this.#claim = claim;
+    }
+    /** The changelog route to present after the first frame, or undefined when there is no unseen note to show. */
+    get startupRoute() {
+        const current = this.#current;
+        const claim = this.#claim;
+        if (current === null || claim === null)
+            return undefined;
+        return {
+            route: "changelog",
+            input: { document: current.markdown },
+            onClosed: () => {
+                this.#acknowledgement ??= claim.acknowledge();
+                return this.#acknowledgement;
+            },
+        };
+    }
+    /** Waits for a pending acknowledgement; a failed one stays unseen and is never reported. */
+    async settleAcknowledgement() {
+        await this.#acknowledgement?.catch(() => undefined);
+    }
+    async releaseClaim() {
+        await this.#claim?.release();
+    }
+}

package/dist/composition/utility-tab.d.ts

@@ -0,0 +1,28 @@
+import type { OwnedUiApplicationPort, PresentationTerminalPort } from "../contracts/presentation/index.js";
+import type { TabBridgeClient } from "../foundation/resident-tabs/bridge-client.js";
+import type { ResidentTabRoute } from "../foundation/resident-tabs/routes.js";
+import type { ReleaseNoteCatalog } from "../features/owned-ui/release-notes.js";
+import type { UiRouteHost } from "../ui/apps/contracts.js";
+import type { OwnedSettingsManager } from "../ui/settings/manager.js";
+import { terminateOwnedUiProcess } from "../features/owned-ui/run.js";
+export { terminateOwnedUiProcess };
+export interface UtilityTabOptions {
+    readonly route: ResidentTabRoute;
+    readonly bridge: TabBridgeClient;
+    readonly cwd?: string;
+    readonly profileId?: string;
+    readonly terminal?: PresentationTerminalPort;
+    readonly agentDir?: string;
+    readonly settings?: OwnedSettingsManager;
+    readonly routeHost?: UiRouteHost;
+    readonly releaseNotes?: ReleaseNoteCatalog;
+    readonly onApplication?: (application: OwnedUiApplicationPort) => void;
+}
+export interface UtilityTabComposition {
+    readonly application: OwnedUiApplicationPort;
+    readonly settings: OwnedSettingsManager;
+}
+/** Runs one pinned Settings or Changelog screen without constructing an Agent engine or session. */
+export declare function runUtilityTab(options: UtilityTabOptions): Promise<number>;
+export declare function composeUtilityTab(options: UtilityTabOptions): Promise<UtilityTabComposition>;
+export declare function utilityAgentDir(environment?: NodeJS.ProcessEnv): string;