@timurproko/a1 0.2.7-dev.1276 → 0.2.7-dev.1285

package/README.md

@@ -73,7 +73,11 @@ a1 --session <id>
 
 When a session exits, A1 prints the `a1 --session <id>` command that resumes it; a custom session store is included in the printed command. Closing the terminal ends the agent, as it does for Pi.
 
-Bare A1 automatically names unnamed sessions from the first prompt and regenerates automatic names on the next prompt after a worktree-context change. Manual `/name` renames are preserved. Names appear after footer stats, with a secondary-accent reveal for automatic changes. Agent settings offers **Session name format** with Kebab case (default), Sentence case, and Title Case for future generated names, or **Automatic session name** to disable naming; see [session names](docs/features/session-naming.md) for details.
+If a saved session's folder was moved or deleted, recovery offers **Continue**, **Fork**, or **Cancel**. Continue uses the current folder for this run and asks again on the next resume. Fork keeps the original and creates a new session ID in the current folder, so later resumes no longer ask. This also applies to session import and extension-triggered switching.
+
+Bare A1 automatically names unnamed sessions from the current task and relevant discussion, using up to three descriptive words and 32 characters, and regenerates on the next prompt after a worktree-context change. Manual `/name` renames are preserved. Names appear after footer stats, with a secondary-accent reveal for automatic changes; narrow footers reduce stats before shortening the name. Agent settings offers **Session name format** with Sentence case (default, first choice), Kebab case, and Title Case for future generated names, or **Automatic session name** to disable naming. Valid saved formats are preserved; see [session names](docs/features/session-naming.md) for details.
+
+Inside an A1 agent session, `a1 worktree enter <branch>` creates or resumes a task checkout and attaches it. `a1 worktree attach <path>` attaches an existing checkout; `a1 worktree detach` releases it without deleting work. A1 handles coordination and ordinary recovery internally; successful attachment needs no second inventory check. See [worktree commands](docs/features/worktrees.md).
 
 Show all commands:
 

package/dist/app/session-shell/session-shell-root.d.ts

@@ -1,8 +1,7 @@
 import type { OwnedUiShellComponents, OwnedUiShellHotkeysPresentation, OwnedUiShellClipboardContent, OwnedUiShellComponentPort, OwnedUiShellEditorPort, OwnedUiShellHeaderOptions, OwnedUiShellHeaderPort, OwnedUiShellHistoryEditor, OwnedUiShellImageAssetResolver, OwnedUiShellKeybindingsHost, OwnedUiShellLoadedResourcesPort, OwnedUiShellViewComponentPort } from "../../contracts/owned-ui/index.js";
-import type { TerminalComponentPort, TerminalInputCoordinationScheduler, TerminalInputDiagnosticsEvent, TerminalInputSurfaceKind, TerminalLayoutNode, TerminalPort } from "../../contracts/presentation/index.js";
+import type { TerminalComponentPort, TerminalInputSurfaceKind, TerminalLayoutNode } from "../../contracts/presentation/index.js";
 import type { ShellPresentationPorts, ThemeSource } from "../../contracts/presentation/index.js";
-import type { OwnedUiBackgroundSettingsPort, OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionBackend, OwnedUiSessionPresenters, OwnedUiSessionViewModel, OwnedUiTranscriptRendererPort, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
-import type { UiRouteHost, UiRouteInput } from "../../ui/apps/contracts.js";
+import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionPresenters, OwnedUiSessionViewModel, OwnedUiTranscriptRendererPort, OwnedUiViewportSettings, SuggestionDecision, SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
 import type { TranscriptViewportFrame, TranscriptViewportFrameDescriptor } from "../../ui/components/transcript-viewport.js";
 import { PromptChipStore, type PreparedPrompt } from "./prompt-chips.js";
 import type { PastePreparationClientOptions } from "./paste-preparation-client.js";
@@ -15,70 +14,8 @@ import type { PasteEvent, PasteSource } from "./paste-protocol.js";
 import { DockChrome } from "./dock-chrome.js";
 import { WorkflowOutput } from "./workflow-output.js";
 import { TranscriptDocument } from "./transcript-document.js";
-import type { StreamPresentationScheduler } from "./stream-presentation-coalescer.js";
-type OwnedUiTerminalPort = TerminalPort;
-type OwnedUiStartupOptions = OwnedUiShellHeaderOptions;
-/** The engine session the shell presents and the composition's decisions about it. */
-export interface OwnedUiShellEngineOptions {
-    readonly backend: OwnedUiSessionBackend;
-    readonly cwd: string;
-    /**
-     * Declared A1-owned routes. A route this host claims resolves to its app;
-     * every other route continues to the pinned workflow table unchanged.
-     */
-    readonly routeHost?: UiRouteHost;
-    /** One product-owned route presented after the first usable frame and any startup modal. */
-    readonly startupRoute?: {
-        readonly route: string;
-        readonly input?: UiRouteInput;
-        readonly onClosed?: () => void | Promise<void>;
-    };
-    /** Bare A1 selects the owned bounded viewport; comparison profiles stay pinned. */
-    readonly sessionLayout?: "pinned" | "custom-viewport";
-}
-/** Terminal, startup, viewport, and presentation-cadence seams; production leaves most at their defaults. */
-export interface OwnedUiShellPresentationOptions {
-    readonly terminal?: OwnedUiTerminalPort;
-    readonly startup?: OwnedUiStartupOptions;
-    /** Live profile-local settings, supplied only to the bare-A1 composition. */
-    readonly viewportSettings?: OwnedUiViewportSettingsPort;
-    /** Live fullscreen canvas choice, supplied only to the bare-A1 composition. */
-    readonly backgroundSettings?: OwnedUiBackgroundSettingsPort;
-    /** Deterministic scheduling seam for presentation-cadence tests. */
-    readonly stream?: {
-        readonly intervalMs?: number;
-        readonly scheduler?: StreamPresentationScheduler;
-    };
-    /**
-     * Minimum time the reload box stays visible so a fast reload still reads as one.
-     * Production uses the default hold; tests inject `now`/`sleep` for determinism.
-     */
-    readonly reload?: {
-        readonly minVisibleMs?: number;
-        readonly now?: () => number;
-        readonly sleep?: (ms: number) => Promise<void>;
-    };
-    /**
-     * Quit outro settings and seams, supplied only to the bare-A1 composition.
-     * `interactive` states whether the terminal can show the animation; production
-     * passes stdout's TTY state, tests opt in explicitly.
-     */
-    readonly quitOutro?: OwnedUiQuitOutroSettingsPort & {
-        readonly interactive: boolean;
-        readonly now?: () => number;
-        readonly sleep?: (ms: number) => Promise<void>;
-        readonly seed?: number;
-    };
-    readonly input?: {
-        readonly scheduler?: TerminalInputCoordinationScheduler;
-        readonly onEvent?: (event: TerminalInputDiagnosticsEvent) => void;
-        readonly now?: () => number;
-        /** Evidence-only baseline seam; production leaves coordination enabled. */
-        readonly coordination?: boolean;
-        /** Evidence-only baseline seam; production leaves dock reuse enabled. */
-        readonly viewportReuse?: boolean;
-    };
-}
+import type { OwnedUiShellEngineOptions, OwnedUiShellPresentationOptions } from "./shell-options.js";
+export type { OwnedUiShellEngineOptions, OwnedUiShellPresentationOptions } from "./shell-options.js";
 /** Persistent prompt history: its store, its bound, the editor that recalls it, and the image sidecar. */
 export interface OwnedUiShellHistoryOptions {
     readonly store: import("../../contracts/owned-ui/index.js").PromptHistoryPort;
@@ -286,4 +223,3 @@ export type PinnedLayoutParts = Readonly<Record<PinnedLayoutPart, TerminalCompon
  * so its single `transcript` scroll view is shared by whichever session the parts currently resolve to.
  */
 export declare function pinnedLayoutRoot(parts: PinnedLayoutParts, theme: ThemeSource): TerminalLayoutNode;
-export {};

package/dist/app/session-shell/session-shell.js

@@ -7,7 +7,7 @@ import { LoginInteraction } from "./login-interaction.js";
 import { PromptSubmission } from "./prompt-submission.js";
 import { SessionConcerns } from "./session-concern.js";
 import { composeExitText, SessionStopLatch } from "./session-lifecycle.js";
-import { openWorkflowSelector } from "./workflow-router.js";
+import { openWorkflowSelector, selectSessionCwdRecovery } from "./workflow-router.js";
 import { SessionSelectors } from "./session-selectors.js";
 import { bindSessionSettings, bindShellSettings } from "./settings-bindings.js";
 import { promptSuggestionSurface, suggestionPresentationBlockReason, } from "./suggestion-surface.js";
@@ -606,18 +606,12 @@ export class OwnedUiSessionPresenter {
             this.selectors.showModelSelector((result.detail ?? request.argument.trim()) || undefined);
             return { outcome: "completed", diagnostic: null };
         }
-        if (result.outcome === "requires-confirmation" && request.command === "resume") {
-            const confirmed = await this.#extensionBridge.context.confirm("Session cwd not found", result.message);
-            return this.runWorkflow({ ...request, confirmed: confirmed === true });
+        if (result.outcome === "requires-selection" && result.cwdRecovery !== undefined && (request.command === "resume" || request.command === "import")) {
+            return this.runWorkflow(await selectSessionCwdRecovery(request, result, this.#extensionBridge.context));
         }
         if (result.outcome === "requires-confirmation" && request.command === "import") {
-            const recoveringCwd = result.detail !== undefined;
-            const confirmed = await this.#extensionBridge.context.confirm(recoveringCwd ? "Session cwd not found" : "Import session", result.message);
-            return this.runWorkflow({
-                ...request,
-                confirmed: confirmed === true,
-                ...(confirmed === true && result.detail ? { cwdOverride: result.detail } : {}),
-            });
+            const confirmed = await this.#extensionBridge.context.confirm("Import session", result.message);
+            return this.runWorkflow({ ...request, confirmed: confirmed === true });
         }
         if (result.outcome === "requires-selection" || result.outcome === "requires-confirmation") {
             this.root.workflow.appendResult({ command: request.command, outcome: "failed", message: `Owned controller missing for ${request.command}` });

package/dist/app/session-shell/shell-host.js

@@ -270,8 +270,8 @@ export class OwnedUiTerminalHost {
             requestHyperlinkCleanup: rows => { if (attached())
                 this.#damageTerminal?.requestHyperlinkCleanup(rows); },
             openRoute: (surface, callbacks) => this.#openRoute(presenter, surface, callbacks),
-            // Invariant: an inactive presenter must never hold the active presenter's frames.
-            beginPresentationHold: () => attached() ? runtime.beginPresentationHold() : () => { },
+            // Invariant: only an attached presenter on a running runtime can hold frames.
+            beginPresentationHold: () => attached() && runtime.active ? runtime.beginPresentationHold() : () => { },
             switchMode: mode => runtime.switchMode(mode),
             setTitle: title => { if (attached())
                 runtime.setTitle(title); },

package/dist/app/session-shell/shell-options.d.ts

@@ -0,0 +1,65 @@
+import type { OwnedUiBackgroundSettingsPort, OwnedUiSessionBackend, OwnedUiShellHeaderOptions, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort } from "../../contracts/owned-ui/index.js";
+import type { TerminalInputCoordinationScheduler, TerminalInputDiagnosticsEvent, TerminalPort } from "../../contracts/presentation/index.js";
+import type { StreamPresentationScheduler } from "./stream-presentation-coalescer.js";
+import type { UiRouteHost, UiRouteInput } from "../../ui/apps/index.js";
+/** The engine session the shell presents and the composition's decisions about it. */
+export interface OwnedUiShellEngineOptions {
+    readonly backend: OwnedUiSessionBackend;
+    readonly cwd: string;
+    /**
+     * Declared A1-owned routes. A route this host claims resolves to its app;
+     * every other route continues to the pinned workflow table unchanged.
+     */
+    readonly routeHost?: UiRouteHost;
+    /** One product-owned route presented after the first usable frame and any startup modal. */
+    readonly startupRoute?: {
+        readonly route: string;
+        readonly input?: UiRouteInput;
+        readonly onClosed?: () => void | Promise<void>;
+    };
+    /** Bare A1 selects the owned bounded viewport; comparison profiles stay pinned. */
+    readonly sessionLayout?: "pinned" | "custom-viewport";
+}
+/** Terminal, startup, viewport, and presentation-cadence seams; production leaves most at their defaults. */
+export interface OwnedUiShellPresentationOptions {
+    readonly terminal?: TerminalPort;
+    readonly startup?: OwnedUiShellHeaderOptions;
+    /** Live profile-local settings, supplied only to the bare-A1 composition. */
+    readonly viewportSettings?: OwnedUiViewportSettingsPort;
+    /** Live fullscreen canvas choice, supplied only to the bare-A1 composition. */
+    readonly backgroundSettings?: OwnedUiBackgroundSettingsPort;
+    /** Deterministic scheduling seam for presentation-cadence tests. */
+    readonly stream?: {
+        readonly intervalMs?: number;
+        readonly scheduler?: StreamPresentationScheduler;
+    };
+    /**
+     * Minimum time the reload box stays visible so a fast reload still reads as one.
+     * Production uses the default hold; tests inject `now`/`sleep` for determinism.
+     */
+    readonly reload?: {
+        readonly minVisibleMs?: number;
+        readonly now?: () => number;
+        readonly sleep?: (ms: number) => Promise<void>;
+    };
+    /**
+     * Quit outro settings and seams, supplied only to the bare-A1 composition.
+     * `interactive` states whether the terminal can show the animation; production
+     * passes stdout's TTY state, tests opt in explicitly.
+     */
+    readonly quitOutro?: OwnedUiQuitOutroSettingsPort & {
+        readonly interactive: boolean;
+        readonly now?: () => number;
+        readonly sleep?: (ms: number) => Promise<void>;
+        readonly seed?: number;
+    };
+    readonly input?: {
+        readonly scheduler?: TerminalInputCoordinationScheduler;
+        readonly onEvent?: (event: TerminalInputDiagnosticsEvent) => void;
+        readonly now?: () => number;
+        /** Evidence-only baseline seam; production leaves coordination enabled. */
+        readonly coordination?: boolean;
+        /** Evidence-only baseline seam; production leaves dock reuse enabled. */
+        readonly viewportReuse?: boolean;
+    };
+}

package/dist/app/session-shell/shell-options.js

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

package/dist/app/session-shell/workflow-router.d.ts

@@ -1,4 +1,4 @@
-import type { OwnedUiCommandResult, OwnedUiWorkflowRequest } from "../../contracts/owned-ui/index.js";
+import type { OwnedUiCommandResult, OwnedUiExtensionUiPort, OwnedUiWorkflowRequest, OwnedUiWorkflowResult } from "../../contracts/owned-ui/index.js";
 /** The owned selectors a workflow can open in place of asking the engine to choose. */
 export interface WorkflowSelectors {
     showScopedModelsSelector(): void;
@@ -14,6 +14,8 @@ export interface WorkflowSelectors {
     showLogoutSelector(): Promise<void>;
     showTreeSelector(): Promise<void>;
 }
+/** Maps the pinned recovery labels back to explicit choices, including Escape as cancellation. */
+export declare function selectSessionCwdRecovery(request: OwnedUiWorkflowRequest, result: OwnedUiWorkflowResult, ui: Pick<OwnedUiExtensionUiPort, "select">): Promise<OwnedUiWorkflowRequest>;
 /**
  * Opens the owned selector a workflow request asks for when the user has not chosen yet. Returns
  * the command result when a selector handled the request, settling once an asynchronous selector

package/dist/app/session-shell/workflow-router.js

@@ -1,3 +1,15 @@
+/** Maps the pinned recovery labels back to explicit choices, including Escape as cancellation. */
+export async function selectSessionCwdRecovery(request, result, ui) {
+    const options = result.options ?? [];
+    const selected = await ui.select(result.message, options.map(option => option.label));
+    const choice = options.find(option => option.label === selected)?.id;
+    const cwdRecoveryChoice = choice === "continue" || choice === "fork" ? choice : "cancel";
+    return {
+        ...request,
+        cwdRecoveryChoice,
+        ...(cwdRecoveryChoice === "continue" ? { cwdOverride: result.cwdRecovery.fallbackCwd } : {}),
+    };
+}
 const unchosen = (request) => request.selection === undefined && request.confirmed === undefined;
 const unchosenBare = (request) => unchosen(request) && request.argument.trim().length === 0;
 // Invariant: the routes are checked in this order, matching the order the workflows were introduced.

package/dist/cli/dispatch.js

@@ -20,6 +20,10 @@ export function cliUsage(capabilities) {
         "uninstall [--yes] [--purge]",
         "uninstall <source>",
         "list",
+        "worktree enter <branch> [--base <branch>]",
+        "worktree attach <path>",
+        "worktree detach",
+        "worktree list",
         "session worktrees",
         "session link-worktree <path>",
         "session unlink-worktree",
@@ -51,7 +55,13 @@ export function cliHelp(capabilities) {
         `  ${command} uninstall <source>`,
         `  ${command} list`,
         "",
-        "Session context:",
+        "Worktrees (successful enter/attach is authoritative; detach preserves files):",
+        `  ${command} worktree enter <branch> [--base <branch>]`,
+        `  ${command} worktree attach <path>`,
+        `  ${command} worktree detach`,
+        `  ${command} worktree list`,
+        "",
+        "Session context (compatibility aliases):",
         `  ${command} session worktrees`,
         `  ${command} session link-worktree <path>`,
         `  ${command} session unlink-worktree`,
@@ -123,6 +133,8 @@ export function parseCliCommand(arguments_, capabilities) {
     }
     if (command === "update")
         return parseUpdate(rest, capabilities.runningChannel ?? "stable");
+    if (command === "worktree")
+        return parseWorktree(rest);
     if (command === "session")
         return parseSessionContext(rest);
     if (command?.startsWith("update:"))
@@ -131,6 +143,20 @@ export function parseCliCommand(arguments_, capabilities) {
     // explicit, and a typo must never start an interactive or maintenance path.
     return { kind: "noop" };
 }
+function parseWorktree(rest) {
+    const [action, value, flag, base, extra] = rest;
+    if (action === "enter" && value !== undefined && !value.startsWith("-")
+        && (flag === undefined || (flag === "--base" && base !== undefined && !base.startsWith("-"))) && extra === undefined) {
+        return { kind: "session-context", request: { action: "enter-worktree", branch: value, ...(base === undefined ? {} : { base }) } };
+    }
+    if (action === "attach" && value !== undefined && flag === undefined) {
+        return { kind: "session-context", request: { action: "link-worktree", path: value } };
+    }
+    if ((action === "detach" || action === "list") && value === undefined) {
+        return { kind: "session-context", request: { action: action === "detach" ? "unlink-worktree" : "worktrees" } };
+    }
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic("worktree accepts enter <branch> [--base <branch>], attach <path>, detach, or list.") };
+}
 function parseSessionContext(rest) {
     const [action, value, extra] = rest;
     if (action === "link-worktree") {

package/dist/cli/packages.js

@@ -21,7 +21,7 @@ export async function runPackageCommand(request, environment) {
     const port = environment.createPort({
         profileRoot,
         cwd,
-        onProgress: progress => stdout(style.dim(`${progress.message}\n`)),
+        onProgress: progress => stdout((progress.severity === "warning" ? style.yellow : style.dim)(`${progress.message}\n`)),
         onDiagnostic: diagnostic => {
             stderr(`${style.yellow(diagnostic.message)}\n`);
             if (diagnostic.detail)
@@ -60,11 +60,27 @@ export function renderPackageOutcome(outcome, style = chalk) {
         case "remove":
             return `${style.green(`Removed ${outcome.source}`)}\n`;
         case "update":
-            return `${style.green(outcome.source === null ? "Updated packages" : `Updated ${outcome.source}`)}\n`;
+            return renderPackageUpdate(outcome, style);
         case "list":
             return renderPackageList(outcome, style);
     }
 }
+function renderPackageUpdate(outcome, style) {
+    const summary = outcome.updateSummary;
+    if (summary?.offline)
+        return `${style.yellow("Skipped package updates (offline mode)")}\n`;
+    const changes = summary?.changes ?? [];
+    if (changes.length > 0) {
+        const heading = `Updated ${changes.length} package${changes.length === 1 ? "" : "s"}:`;
+        return `${style.green(heading)}\n${changes.map(change => `  ${change}\n`).join("")}`;
+    }
+    if (summary?.warningCount) {
+        return `${style.yellow(outcome.source
+            ? `${outcome.source} was not updated, see the warnings above`
+            : "No packages were updated, see the warnings above")}\n`;
+    }
+    return `${style.green(outcome.source ? `${outcome.source} is already up to date` : "Packages are already up to date")}\n`;
+}
 function renderPackageList(outcome, style) {
     if (outcome.packages.length === 0)
         return `${style.dim("No packages installed.")}\n`;

package/dist/cli/session-context.js

@@ -16,7 +16,7 @@ export async function runSessionContextCommand(request, options = {}) {
         if (outcome.kind === "unlinked")
             stdout("Session worktree context cleared.\n");
         if (outcome.kind === "linked")
-            stdout(`Session worktree context linked: ${outcome.cwd}\n`);
+            stdout(`Session worktree context linked: ${outcome.cwd} (${outcome.branch})\n`);
         if (outcome.kind === "worktrees") {
             for (const entry of outcome.entries) {
                 // Compatibility: the primary agent is the only agent of a single-session runtime, so it stays unnamed.
@@ -44,7 +44,7 @@ function readIdentity(environment) {
 /** Known coordination failures must not expose internal paths or another session's identity. */
 function recoveryDetail(code) {
     const details = {
-        "worktree-claim-busy": "another mutation is still running; runtime registration retries automatically, so retry this link shortly",
+        "worktree-claim-busy": "coordination did not settle within the operation budget; no ownership was changed; retry this link shortly if the system remains busy",
         "worktree-legacy-recovery-required": "an older-format worktree lock requires safe recovery; stop all older A1 processes, move only session-worktree-claims/mutation.lock to a backup while stopped, then start the updated A1; keep all sessions and worktree claims",
         "worktree-coordination-unavailable": "worktree coordination is unavailable; repair or update this A1 installation, then retry",
         "worktree-coordination-io": "worktree coordination could not access its files; check A1 data-directory permissions and filesystem availability, then retry",
@@ -54,6 +54,10 @@ function recoveryDetail(code) {
         "session-runtime-stopped": "this shell belongs to a stopped runtime; resume in a running A1 session before linking",
         "worktree-active-in-another-session": "another live agent owns this worktree; use a different worktree or wait for its owner to release it",
         "worktree-owner-unverifiable": "worktree ownership cannot be verified; retain the claim and use another worktree rather than forcing recovery",
+        "worktree-primary-checkout": "attach a task worktree, not the primary checkout; use worktree enter to create one",
+        "worktree-git-locked": "Git has locked this worktree; retain it and ask its owner to release the lock",
+        "worktree-foreign-repository": "the selected worktree belongs to a different repository; the previous attachment was preserved",
+        "worktree-context-changed": "the attachment changed during the operation; no ownership was overridden",
     };
     return code === null ? undefined : details[code];
 }

package/dist/composition/owned-ui.js

@@ -17,22 +17,23 @@ import { createPiTerminalBridge } from "../integrations/pi/tui-runtime/presentat
 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 { SessionRuntimeRegistry } from "./session-runtime-registry.js";
 import { bindAutomaticSessionNaming } from "./session-naming.js";
 import { deferStartupReleaseUpdateObservation, readPackageVersion, StartupReleaseNote } from "./startup-route.js";
 import { createOwnedSettingsManager, watchSharedSettings } from "./owned-settings.js";
 /** Production default: without an inspector the registry never registers; loaded lazily. */
 const inspectLiveProcessOnDemand = async (pid) => (await import("../foundation/lifecycle/process-liveness.js")).inspectLiveProcess(pid);
+/** Load coordination only when composing a session, not while evaluating the startup facade. */
+async function createSessionRuntimes(bare, inspectProcess) {
+    const { SessionRuntimeRegistry } = await import("./session-runtime-registry.js");
+    return new SessionRuntimeRegistry({ runtimeId: bare ? process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId] : undefined, inspectProcess });
+}
 export async function composeOwnedUiApplication(options = {}) {
     return (await composeOwnedUi(options)).application;
 }
 export async function composeOwnedUi(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const productMode = options.productMode ?? "bare", bare = productMode === "bare";
-    const sessionRuntimes = new SessionRuntimeRegistry({
-        runtimeId: bare ? process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId] : undefined,
-        inspectProcess: options.inspectProcess ?? inspectLiveProcessOnDemand,
-    });
+    const sessionRuntimes = await createSessionRuntimes(bare, options.inspectProcess ?? inspectLiveProcessOnDemand);
     const productPaths = resolveProductPaths();
     // Rationale: the manager reads the engine's settings port lazily, after the session exists.
     let backend;
@@ -46,12 +47,14 @@ export async function composeOwnedUi(options = {}) {
     const bareSettings = bare ? settings : null;
     // Invariant: process-wide engine state has one owner. The host installs the HTTP dispatcher, applies
     // the theme singletons, and announces startup notices once; every session is created through it.
-    const host = await (options.createEngineHost ?? createPiEngineHost)(engineHostOptions(options, productMode, bareSettings));
+    const host = await (options.createEngineHost ?? createPiEngineHost)(engineHostOptions(options, productMode, bareSettings, productPaths.runtimeDir));
     const sessionForkPrompt = options.sessionForkPrompt;
     try {
         backend = await host.create({
             cwd,
             ...(bare ? { repositoryContextReader: sessionRuntimes.readerFor(undefined) } : {}),
+            ...(bare && process.env[PRODUCT_IDENTITY.environment.sessionRuntimeId] !== undefined
+                ? { worktreeCwdReader: sessionRuntimes.toolReaderFor(undefined) } : {}),
             ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
             ...(options.sessionSelection === undefined ? {} : { sessionSelection: options.sessionSelection }),
             ...(sessionForkPrompt === undefined ? {} : { sessionForkPrompt }),
@@ -127,7 +130,7 @@ export async function composeOwnedUi(options = {}) {
     let presenter;
     try {
         const presenterOptions = {
-            presenters: createPiSessionPresenters(backend),
+            presenters: createPiSessionPresenters(backend, spinnerPresenterOptions(bareSettings)),
             engine: {
                 backend,
                 cwd: backend.identity.cwd,
@@ -201,6 +204,12 @@ export async function composeOwnedUi(options = {}) {
     };
     return { application, settings };
 }
+function spinnerPresenterOptions(settings) {
+    return settings === null ? {} : { spinner: {
+            snapshot: () => settings.value("spinnerStyle"),
+            onChange: (listener) => settings.onChange(() => listener()),
+        } };
+}
 /** The settings-driven ports only bare A1 receives: viewport, background, quit outro, suggestions, image limit, and skills. */
 function bareShellPorts(settings, generator, diagnostics) {
     const viewportSettings = {
@@ -235,10 +244,13 @@ function bareShellPorts(settings, generator, diagnostics) {
         },
     };
 }
-function engineHostOptions(options, productMode, settings) {
+function engineHostOptions(options, productMode, settings, runtimeDir) {
     const bare = productMode === "bare";
     return {
         productMode,
+        deliveryIncident: failure => {
+            void import("../foundation/terminal-cleanup/index.js").then(module => module.writeFatalDiagnostic(`${runtimeDir}/crashes`, "delivery", Object.assign(new Error(), { deliveryFailure: failure }), options.packageVersion)).catch(() => undefined);
+        },
         availableThemes: () => getAvailablePiThemes().map(theme => theme.name),
         ...(bare ? { workflowHost: { reserveExport: async (id, format) => (await import("../foundation/lifecycle/user-exports.js")).reserveUserExport(id, format) } } : {}),
         announceStartupChangelog: !bare,

package/dist/composition/session-naming.js

@@ -6,7 +6,7 @@ export function bindAutomaticSessionNaming(backend, settings, bare) {
     const naming = new SessionNamingController({
         backend, naming: backend.naming,
         enabled: () => settings?.value("sessionAutoName") ?? true,
-        format: () => settings?.value("sessionNameFormat") ?? "kebab",
+        format: () => settings?.value("sessionNameFormat") ?? "sentence",
         withContext: async (consume, signal) => {
             const sessionId = backend.identity.currentHistorySessionId();
             const sessionFile = backend.identity.currentSessionFile();

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

@@ -16,6 +16,8 @@ export declare class SessionRuntimeRegistry {
         branch: string;
         revision: string;
     } | null>;
+    /** Strict tool cwd lookup: transient startup failure never redirects a write to primary. */
+    toolReaderFor(agentId: string | undefined): (sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string>;
     /** Drain publication before releasing claims; never republish after disposal. */
     dispose(): Promise<void>;
 }

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

@@ -2,6 +2,7 @@
 export class SessionRuntimeRegistry {
     #options;
     #identities = new Map();
+    #activated = new Map();
     #abort = new AbortController();
     #owner = null;
     #timer = null;
@@ -15,7 +16,9 @@ export class SessionRuntimeRegistry {
             const { runtimeId, inspectProcess } = this.#options;
             if (this.#disposed || runtimeId === undefined || inspectProcess === undefined)
                 return null;
-            const identity = { sessionId, sessionFile };
+            const previous = this.#identities.get(agentId);
+            const identity = previous?.sessionId === sessionId && previous.sessionFile === sessionFile
+                ? previous : { sessionId, sessionFile };
             this.#identities.set(agentId, identity);
             // Invariant: initial activation or inspection failure must not disable retries.
             this.#arm();
@@ -23,25 +26,62 @@ export class SessionRuntimeRegistry {
                 const owner = await this.#ownerIdentity();
                 if (owner === null || !this.#current(agentId, identity))
                     return null;
-                const { activateSessionRepositoryContext, withSessionRepositoryObservation } = await import("../foundation/lifecycle/session-repository-context.js");
+                const { activateSessionRepositoryContext, readActiveSessionRepositoryContext } = await import("../foundation/lifecycle/session-repository-context.js");
                 if (!this.#current(agentId, identity))
                     return null;
                 const options = {
+                    runtimeId,
                     signal: AbortSignal.any([signal, this.#abort.signal]),
                     inspectProcess,
                     ...(agentId === undefined ? {} : { agentId }),
                 };
-                const selected = await activateSessionRepositoryContext(identity, runtimeId, owner, options);
-                if (selected === null)
-                    return null;
-                return await withSessionRepositoryObservation(identity, context => {
+                if (this.#activated.get(agentId) !== identity) {
+                    await activateSessionRepositoryContext(identity, runtimeId, owner, options);
+                    if (!this.#current(agentId, identity))
+                        return null;
+                    this.#activated.set(agentId, identity);
+                }
+                try {
+                    const context = await readActiveSessionRepositoryContext(identity, options);
+                    if (context === null)
+                        return null;
                     if (context.branch === null)
                         throw new Error("associated branch unavailable");
                     return { cwd: context.cwd, branch: context.branch, revision: context.revision };
-                }, options);
+                }
+                catch (error) {
+                    const code = error instanceof Error && "code" in error ? error.code : null;
+                    if ((code === "session-runtime-unavailable" || code === "worktree-context-changed") && this.#current(agentId, identity)) {
+                        this.#activated.delete(agentId);
+                    }
+                    throw error;
+                }
             });
         };
     }
+    /** Strict tool cwd lookup: transient startup failure never redirects a write to primary. */
+    toolReaderFor(agentId) {
+        const read = this.readerFor(agentId);
+        return async (sessionId, sessionFile, signal) => {
+            const { retrySessionCoordination } = await import("../foundation/lifecycle/session-context-retry.js");
+            return await retrySessionCoordination(async () => {
+                signal.throwIfAborted();
+                if (this.#disposed || this.#options.runtimeId === undefined)
+                    throw new Error("worktree runtime is not active");
+                const context = await read(sessionId, sessionFile, signal);
+                if (this.#disposed)
+                    throw new Error("worktree runtime is not active");
+                const active = this.#activated.get(agentId);
+                if (active?.sessionId !== sessionId || active.sessionFile !== sessionFile) {
+                    throw Object.assign(new Error("worktree runtime registration is still recovering"), { code: "session-runtime-unavailable" });
+                }
+                if (context !== null)
+                    return context.cwd;
+                const { readSessionStartupRoot } = await import("../foundation/lifecycle/session-repository-context.js");
+                return await readSessionStartupRoot({ sessionId, sessionFile });
+            }, 8_000, signal);
+        };
+    }
     /** Drain publication before releasing claims; never republish after disposal. */
     async dispose() {
         this.#disposed = true;
@@ -82,7 +122,7 @@ export class SessionRuntimeRegistry {
     #arm() {
         if (this.#timer !== null)
             return;
-        this.#timer = setInterval(() => this.#queueRefresh(), this.#options.refreshMs ?? 30_000);
+        this.#timer = setInterval(() => this.#queueRefresh(), this.#options.refreshMs ?? 1_000);
         this.#timer.unref();
     }
     #queueRefresh() {
@@ -96,7 +136,7 @@ export class SessionRuntimeRegistry {
                 return;
             const { registerSessionRepositoryRuntime } = await import("../foundation/lifecycle/session-repository-context.js");
             for (const [agentId, identity] of this.#identities) {
-                if (!this.#current(agentId, identity))
+                if (!this.#current(agentId, identity) || this.#activated.get(agentId) === identity)
                     continue;
                 await registerSessionRepositoryRuntime(identity, runtimeId, owner, {
                     inspectProcess,

package/dist/contracts/agent-engine/package-ports.d.ts

@@ -1,17 +1,6 @@
-/**
- * Extension packages are managed outside any session: the command that installs
- * one runs before the runtime exists, against a profile root chosen by the caller
- * rather than by whatever session happens to be open. So this port stands apart
- * from the session-scoped service ports and names only what a package operation
- * needs — a root, a source, and an outcome a caller can render without knowing
- * which engine performed it.
- */
+/** Non-interactive package operations use a caller-chosen profile root before any session exists. */
 export type AgentPackageOperation = "install" | "remove" | "update" | "refresh-models" | "list";
-/**
- * Why an operation ended, kept separate from the prose so callers can branch on
- * it. `not-found` is the one failure an engine can state structurally — the source
- * is not configured in this profile — rather than only in a message.
- */
+/** Status is separate from prose; not-found means the source is unconfigured. */
 export type AgentPackageStatus = "completed" | "not-found" | "failed";
 export interface AgentPackageDescriptor {
     readonly source: string;
@@ -25,10 +14,17 @@ export interface AgentPackageOutcome {
     readonly source: string | null;
     readonly packages: readonly AgentPackageDescriptor[];
     readonly detail: string | null;
+    /** Update facts distinguish a checked result from skipped or warned work. */
+    readonly updateSummary?: {
+        readonly offline: boolean;
+        readonly warningCount: number;
+        readonly changes: readonly string[];
+    };
 }
 export interface AgentPackageProgress {
     readonly operation: AgentPackageOperation;
     readonly message: string;
+    readonly severity?: "warning";
 }
 export interface AgentPackagesPort {
     readonly capabilities: {
@@ -57,4 +53,4 @@ export interface AgentPackagesPortInput {
     readonly onDiagnostic?: (diagnostic: AgentPackageDiagnostic) => void;
 }
 export declare function assertAgentPackagesPort(port: AgentPackagesPort): void;
-export declare function agentPackageOutcome(operation: AgentPackageOperation, status: AgentPackageStatus, detail?: string | null, source?: string | null, packages?: readonly AgentPackageDescriptor[]): AgentPackageOutcome;
+export declare function agentPackageOutcome(operation: AgentPackageOperation, status: AgentPackageStatus, detail?: string | null, source?: string | null, packages?: readonly AgentPackageDescriptor[], updateSummary?: AgentPackageOutcome["updateSummary"]): AgentPackageOutcome;