@timurproko/a1 0.2.7-dev.806 → 0.2.7-dev.809

package/dist/composition/owned-ui.js

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { unwatchFile, watchFile } from "node:fs";
 import { SuggestionDiagnosticCapture } from "../features/prompt-suggestions/diagnostics.js";
 import { PRODUCT_IDENTITY } from "../product-identity.js";
 import { PromptHistoryService } from "../features/prompt-history/service.js";
@@ -12,8 +12,6 @@ import { createPiSessionPresenters } from "../integrations/pi/session-presenters
 import { ClipboardDiagnosticCapture } from "../app/session-shell/clipboard-diagnostics.js";
 import { createOwnedUiClipboardServices } from "../app/session-shell/clipboard-services.js";
 import { createPiKeybindingsHost } from "../integrations/pi/components/shell-shared-facade.js";
-import { projectResidentTabShortcuts } from "../features/resident-tab/shortcut-projection.js";
-import { readShortcutBindingsFile } from "../features/resident-tab/shortcut-bindings-file.js";
 import { OwnedUiSessionPresenter, OwnedUiTerminalHost, sessionTerminalHostOptions, } from "../app/session-shell/session-shell.js";
 import { OwnedSettingsManager } from "../ui/settings/manager.js";
 import { createPiTerminalBridge } from "../integrations/pi/tui-runtime/presentation-adapter.js";
@@ -21,8 +19,10 @@ import { createOwnedRouteHost } from "./settings-route-host.js";
 import { renderPiShellChangelogLines } from "../integrations/pi/components/shell-presenters-info.js";
 import { nativeHyperlinkStyle } from "../ui/components/spans.js";
 import { ResidentTabRecovery } from "../foundation/resident-tabs/recovery.js";
-import { deriveResidentTabStatus } from "../features/resident-tab/status-deriver.js";
-const SESSION_RUNTIME_REFRESH_MS = 30_000;
+import { bindResidentTabBridge, correlateResidentTabSubmission, currentBackendSessionFile, residentTabKeybindings } from "./resident-tab-bridge.js";
+import { SessionRuntimeRegistry } from "./session-runtime-registry.js";
+import { readPackageVersion, StartupReleaseNote } from "./startup-route.js";
+export { bindResidentTabBridge, correlateResidentTabSubmission } from "./resident-tab-bridge.js";
 export function residentStartupPresentation(resident, fallbackNotice) {
     if (resident)
         return { startup: { quiet: true } };
@@ -34,62 +34,10 @@ export async function composeOwnedUiApplication(options = {}) {
 export async function composeOwnedUi(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const ownedSurfaces = options.ownedSurfaces !== "off";
-    const sessionRuntimeId = ownedSurfaces ? process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId] : undefined;
-    const inspectSessionProcess = options.inspectProcess;
-    let sessionRuntimeIdentity = null;
-    // Invariant: one entry per agent of this runtime; each agent holds its own claim, and the runtime's exit releases all.
-    const activeSessionIdentities = new Map();
-    let sessionRuntimeRefreshTimer = null;
-    let sessionRuntimeRefresh = Promise.resolve();
-    let sessionRuntimeDisposed = false;
-    const runtimeIdentity = async () => {
-        if (sessionRuntimeId === undefined || inspectSessionProcess === undefined)
-            return null;
-        sessionRuntimeIdentity ??= inspectSessionProcess(process.pid).catch(() => null);
-        return await sessionRuntimeIdentity;
-    };
-    const queueSessionRuntimeRefresh = () => {
-        if (sessionRuntimeDisposed || activeSessionIdentities.size === 0 || sessionRuntimeId === undefined || inspectSessionProcess === undefined)
-            return;
-        sessionRuntimeRefresh = sessionRuntimeRefresh.then(async () => {
-            if (sessionRuntimeDisposed)
-                return;
-            const owner = await runtimeIdentity();
-            if (owner === null)
-                return;
-            const { registerSessionRepositoryRuntime } = await import("../foundation/lifecycle/session-repository-context.js");
-            for (const [agentId, identity] of activeSessionIdentities) {
-                if (sessionRuntimeDisposed)
-                    return;
-                await registerSessionRepositoryRuntime(identity, sessionRuntimeId, owner, {
-                    inspectProcess: inspectSessionProcess,
-                    ...(agentId === undefined ? {} : { agentId }),
-                }).catch(() => undefined);
-            }
-        }).catch(() => undefined);
-    };
-    /** The repository context reader for one agent; undefined names the primary agent, the only one composed today. */
-    const repositoryContextReaderFor = (agentId) => async (sessionId, sessionFile, signal) => {
-        const owner = await runtimeIdentity();
-        if (owner === null || sessionRuntimeId === undefined || inspectSessionProcess === undefined)
-            return null;
-        const identity = { sessionId, sessionFile };
-        activeSessionIdentities.set(agentId, identity);
-        const { activateSessionRepositoryContext } = await import("../foundation/lifecycle/session-repository-context.js");
-        const context = await activateSessionRepositoryContext(identity, sessionRuntimeId, owner, {
-            signal,
-            inspectProcess: inspectSessionProcess,
-            ...(agentId === undefined ? {} : { agentId }),
-        });
-        armSessionRuntimeRefresh();
-        return context;
-    };
-    const armSessionRuntimeRefresh = () => {
-        if (sessionRuntimeRefreshTimer !== null)
-            return;
-        sessionRuntimeRefreshTimer = setInterval(queueSessionRuntimeRefresh, SESSION_RUNTIME_REFRESH_MS);
-        sessionRuntimeRefreshTimer.unref();
-    };
+    const sessionRuntimes = new SessionRuntimeRegistry({
+        runtimeId: ownedSurfaces ? process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId] : undefined,
+        inspectProcess: options.inspectProcess,
+    });
     const productPaths = resolveProductPaths();
     const profilePaths = resolveLaunchProfilePaths();
     // Rationale: the manager reads the engine's settings port lazily, after the session exists.
@@ -144,7 +92,7 @@ export async function composeOwnedUi(options = {}) {
     try {
         backend = await host.create({
             cwd,
-            ...(ownedSurfaces ? { repositoryContextReader: repositoryContextReaderFor(undefined) } : {}),
+            ...(ownedSurfaces ? { repositoryContextReader: sessionRuntimes.readerFor(undefined) } : {}),
             ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
             ...(options.sessionSelection === undefined ? {} : { sessionSelection: options.sessionSelection }),
             ...(sessionForkPrompt === undefined ? {} : { sessionForkPrompt }),
@@ -168,39 +116,32 @@ export async function composeOwnedUi(options = {}) {
         tabBridge.accent(settings.value("accentColor"));
     let removeControllerBoundaryInput = () => { };
     let unsubscribeTabBridge = () => { };
-    let releaseNotes = null;
-    let releaseNotesFailure;
-    if (ownedSurfaces) {
-        try {
-            releaseNotes = options.releaseNotes
-                ?? await import("../features/owned-ui/release-notes.js").then(module => module.readPackagedReleaseNotes());
-        }
-        catch (error) {
-            releaseNotesFailure = error;
-        }
-    }
-    const packageVersion = ownedSurfaces
-        ? options.packageVersion ?? await readPackageVersion()
-        : null;
-    const currentReleaseNote = packageVersion === null ? null : releaseNotes?.current(packageVersion) ?? null;
-    const releaseNoteClaim = currentReleaseNote === null || options.profileId === undefined
-        ? null
-        : await import("../features/owned-ui/release-note-state.js").then(module => module.claimReleaseNote({
-            configDir: productPaths.configDir, profileId: options.profileId, version: currentReleaseNote.version,
-        }));
-    const unsubscribeAccent = settings === null || !ownedSurfaces
+    const releaseNote = await StartupReleaseNote.load({
+        ownedSurfaces,
+        configDir: productPaths.configDir,
+        ...(options.releaseNotes === undefined ? {} : { releaseNotes: options.releaseNotes }),
+        ...(options.packageVersion === undefined ? {} : { packageVersion: options.packageVersion }),
+        ...(options.profileId === undefined ? {} : { profileId: options.profileId }),
+    });
+    const unsubscribeAccentChange = settings === null || !ownedSurfaces
         ? () => { }
         : settings.onChange(current => {
             const accent = current.value("accentColor");
             host.setAccentColor(accent);
             tabBridge?.accent(accent);
         });
+    // Rationale: every resident tab is its own process over one shared settings document, so a
+    // change saved in any tab reaches the others only by rereading that document.
+    const unwatchSharedSettings = settings === null || !ownedSurfaces || tabBridge === null
+        ? () => { }
+        : watchSharedSettings(settings);
+    const unsubscribeAccent = () => { unwatchSharedSettings(); unsubscribeAccentChange(); };
     // Rationale: Routes open only after shell construction.
     const references = {
         changelog: async (input) => {
-            if (input?.document === undefined && releaseNotesFailure !== undefined)
-                throw releaseNotesFailure;
-            const markdown = input?.document ?? releaseNotes?.completeMarkdown ?? "No A1 release notes found.";
+            if (input?.document === undefined && releaseNote.failure !== undefined)
+                throw releaseNote.failure;
+            const markdown = input?.document ?? releaseNote.catalog?.completeMarkdown ?? "No A1 release notes found.";
             return { rows: width => renderPiShellChangelogLines(markdown, width).map(row => nativeHyperlinkStyle(row)) };
         },
         hotkeys: async () => {
@@ -210,7 +151,9 @@ export async function composeOwnedUi(options = {}) {
         },
         session: () => import("./session-info-reference.js").then(m => m.loadSessionInfoReference(backend)),
     };
-    const routeHost = settings === null || !ownedSurfaces ? null : createOwnedRouteHost(settings, references);
+    const routeHost = settings === null || !ownedSurfaces ? null : createOwnedRouteHost(settings, references, {
+        settingsPinned: tabBridge?.tabId.startsWith("settings-") === true,
+    });
     const viewportSettings = settings === null || !ownedSurfaces ? null : {
         snapshot: () => viewportSettingsSnapshot(settings),
         onChange: listener => settings.onChange(() => listener(viewportSettingsSnapshot(settings))),
@@ -257,22 +200,11 @@ export async function composeOwnedUi(options = {}) {
     // Invariant: process-wide services are created once here and borrowed by every session shell. The
     // keybinding registry is applied before any presenter is built, so none of them reads Pi's defaults.
     const keybindingsHost = createPiKeybindingsHost({ profile: ownedSurfaces ? "a1" : "pi", agentDir: backend.identity.agentDir });
-    // Invariant: the resident host dispatches and labels the tab shortcuts this child projects
-    // from its effective declarations, so a customization reload republishes the projection.
-    const publishTabShortcuts = () => tabBridge?.shortcuts(projectResidentTabShortcuts({
-        configured: readShortcutBindingsFile(backend.identity.agentDir),
-        reserved: keybindingsHost.manager.getEffectiveConfig(),
-    }).assignments);
-    const keybindings = tabBridge === null ? keybindingsHost : {
-        ...keybindingsHost,
-        reload: () => { keybindingsHost.reload(); publishTabShortcuts(); },
-    };
-    publishTabShortcuts();
+    const keybindings = residentTabKeybindings(tabBridge, backend.identity.agentDir, keybindingsHost);
     const clipboardServices = ownedSurfaces ? createOwnedUiClipboardServices() : null;
     let createdTerminalHost;
     let terminalHost;
     let presenter;
-    let releaseNoteAcknowledgement = null;
     try {
         const presenterOptions = {
             presenters: createPiSessionPresenters(backend),
@@ -280,16 +212,7 @@ export async function composeOwnedUi(options = {}) {
                 backend,
                 cwd: backend.identity.cwd,
                 ...(routeHost === null ? {} : { routeHost }),
-                ...(currentReleaseNote === null || releaseNoteClaim === null ? {} : {
-                    startupRoute: {
-                        route: "changelog",
-                        input: { document: currentReleaseNote.markdown },
-                        onClosed: () => {
-                            releaseNoteAcknowledgement ??= releaseNoteClaim.acknowledge();
-                            return releaseNoteAcknowledgement;
-                        },
-                    },
-                }),
+                ...(releaseNote.startupRoute === undefined ? {} : { startupRoute: releaseNote.startupRoute }),
                 ...(ownedSurfaces ? { sessionLayout: "custom-viewport" } : {}),
                 ...(tabBridge === null || tabRecovery === null ? {} : { residentTab: {
                         requestDetach: () => tabBridge.requestDetach(),
@@ -358,7 +281,7 @@ export async function composeOwnedUi(options = {}) {
     catch (error) {
         await createdTerminalHost?.dispose().catch(() => undefined);
         unsubscribeAccent();
-        await releaseNoteClaim?.release();
+        await releaseNote.releaseClaim();
         clipboardDiagnostics?.dispose();
         suggestionDiagnostics?.dispose();
         clipboardServices?.dispose();
@@ -372,7 +295,7 @@ export async function composeOwnedUi(options = {}) {
         const check = options.checkForNewerRelease
             ?? (await import("../foundation/release/latest-release.js")).checkForNewerRelease;
         const release = await check({
-            runningVersion: packageVersion ?? await readPackageVersion(),
+            runningVersion: releaseNote.packageVersion ?? await readPackageVersion(),
             configDir: productPaths.configDir,
             interactive: process.stdout.isTTY === true,
             ...(settings === null || !ownedSurfaces ? {} : { settingEnabled: settings.value("updateCheck") }),
@@ -401,25 +324,15 @@ export async function composeOwnedUi(options = {}) {
                 await terminalHost.dispose();
                 // Invariant: cleared only once the terminal is restored; a failed dispose leaves it armed.
                 (await exitNotice)?.clear();
-                await releaseNoteAcknowledgement?.catch(() => undefined);
+                await releaseNote.settleAcknowledgement();
             }
             finally {
                 // Invariant: the shared spares outlive every shell and stop only after the last one is disposed.
                 clipboardServices?.dispose();
                 removeControllerBoundaryInput();
                 unsubscribeAccent();
-                sessionRuntimeDisposed = true;
-                if (sessionRuntimeRefreshTimer !== null)
-                    clearInterval(sessionRuntimeRefreshTimer);
-                sessionRuntimeRefreshTimer = null;
-                await sessionRuntimeRefresh;
-                const owner = await runtimeIdentity();
-                if (sessionRuntimeId !== undefined && owner !== null) {
-                    await import("../foundation/lifecycle/session-repository-context.js")
-                        .then(module => module.releaseSessionRepositoryRuntime(sessionRuntimeId, owner))
-                        .catch(() => undefined);
-                }
-                await releaseNoteClaim?.release();
+                await sessionRuntimes.dispose();
+                await releaseNote.releaseClaim();
                 suggestionDiagnostics?.dispose();
                 clipboardDiagnostics?.dispose();
                 unsubscribeTabBridge();
@@ -431,127 +344,20 @@ export async function composeOwnedUi(options = {}) {
     };
     return { application, settings };
 }
-export async function bindResidentTabBridge(tabBridge, backend, recovery = null, options = {}) {
-    await tabBridge.start().catch(() => false);
-    tabBridge.status("starting");
-    const currentSessionFile = () => currentBackendSessionFile(backend);
-    let pendingAutoName = null;
-    const isDefaultName = (name) => name == null || /^agent(?: \d+)?$/i.test(name);
-    const currentSessionName = () => backend.session.view().status.footer?.sessionName ?? null;
-    const announceSession = () => {
-        const name = currentSessionName();
-        const nameSource = name === pendingAutoName ? "auto" : isDefaultName(name) ? "default" : "user";
-        tabBridge.session(currentSessionFile(), name, nameSource);
-    };
-    let working = false;
-    let lastTurnFailed = false;
-    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;
-            const result = await backend.workflows.executeWorkflow({ command: "name", argument: name });
-            if (result.outcome === "completed")
-                tabBridge.session(currentSessionFile(), name, "auto");
-            else if (pendingAutoName === name)
-                pendingAutoName = null;
-        }).catch(() => { pendingAutoName = null; });
-    };
-    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,
-            ...(lastTurnFailed ? { stopReason: "error" } : {}),
-        }), 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)
-                lastTurnFailed = false;
-            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;
-            lastTurnFailed = !event.successful && !event.aborted;
-            tabBridge.prompt(event.aborted);
-            reportStatus();
+const SHARED_SETTINGS_POLL_MS = 250;
+/** Rereads the shared settings document whenever its stat changes; returns the stop. */
+export function watchSharedSettings(settings) {
+    const file = settings.file;
+    const listener = () => {
+        try {
+            settings.refresh();
         }
-        if (event.type === "session-view") {
-            announceSession();
-            reportStatus();
+        catch {
+            // Compatibility: an unreadable peer write resolves on the next stat change.
         }
-    });
-    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));
-}
-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}`;
-}
-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;
+    watchFile(file, { interval: SHARED_SETTINGS_POLL_MS, persistent: false }, listener);
+    return () => unwatchFile(file, listener);
 }
 function quitOutroSettingsSnapshot(settings) {
     return {

package/dist/composition/resident-tab-bridge.d.ts

@@ -0,0 +1,16 @@
+import type { TabBridgeClient } from "../foundation/resident-tabs/bridge-client.js";
+import type { ResidentTabRecovery } from "../foundation/resident-tabs/recovery.js";
+import type { PiKeybindingsHost } from "../integrations/pi/components/shell-shared-facade.js";
+import type { ComposedSessionBackend } from "./session-backend.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 declare function residentTabKeybindings(tabBridge: TabBridgeClient | null, agentDir: string, keybindingsHost: PiKeybindingsHost): PiKeybindingsHost;
+export declare function bindResidentTabBridge(tabBridge: TabBridgeClient, backend: Pick<ComposedSessionBackend, "identity" | "session" | "workflows" | "generateResidentTabName">, recovery?: Pick<ResidentTabRecovery, "settled"> | null, options?: {
+    readonly autoName?: boolean;
+    readonly openRoute?: (route: "settings") => void;
+}): Promise<() => void>;
+export declare function correlateResidentTabSubmission(recovery: Pick<ResidentTabRecovery, "correlated" | "settled">, backend: Pick<ComposedSessionBackend, "identity" | "session">, submissionId: string, entryId: string): Promise<void>;
+export declare function currentBackendSessionFile(backend: Pick<ComposedSessionBackend, "identity">): string | null;

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

@@ -0,0 +1,159 @@
+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(); } };
+}
+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>;
+}