@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.226

package/dist/{src/features → features}/owned-ui/settings-app.js

@@ -1,4 +1,4 @@
-import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, PROMPT_GLYPH, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderStatusLine, renderListRow, renderNote, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, valueColumnFor, valueMenuFrame, promptRule, caretCell, blockRowSpan, displayWidth, faint, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollbarGeometry, selectableIndexes, } from "../../foundation/ui-components/index.js";
+import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, assertNoShortcutConflicts, blockJumpTarget, dialogValueColumn, numericValues, RAIL_COLUMNS, renderDialogPanel, renderEmptyState, renderGroupHeader, renderInputRow, renderListRow, renderNote, renderStatusLine, dialogRowAt, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, valueColumnFor, valueMenuFrame, blockRowSpan, displayWidth, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, isThumbRow, layoutList, moveSelection, rowKey, scrollForSelection, scrollbarGeometry, scrollbarWheelRows, selectableIndexes, } from "../../ui/components/index.js";
 export const SETTINGS_APP_ID = "settings";
 export const SETTINGS_ROUTE = "settings";
 const SCOPE = SETTINGS_APP_ID;
@@ -29,6 +29,7 @@ SETTINGS_SHORTCUTS.declare({ key: "left", scope: DIALOG_SCOPE, description: "Cha
 SETTINGS_SHORTCUTS.declare({ key: "right", scope: DIALOG_SCOPE, description: "Change this part", section: "Parts" }, "part-change");
 SETTINGS_SHORTCUTS.declare({ key: "up", scope: DIALOG_SCOPE, description: "Previous part", section: "Parts" }, "part-previous");
 SETTINGS_SHORTCUTS.declare({ key: "down", scope: DIALOG_SCOPE, description: "Next part", section: "Parts" }, "part-next");
+assertNoShortcutConflicts(SETTINGS_SHORTCUTS.assemble());
 const KEYS = {
     "\u001b[A": "up",
     "\u001b[B": "down",
@@ -56,6 +57,8 @@ export class SettingsApp {
     #session;
     #selectedKey;
     #scroll = 0;
+    // Invariant: keyboard navigation requests visibility once; pointer scrolling then stays free.
+    #selectionNeedsReveal = true;
     #reveal;
     #notice = null;
     #filter = null;
@@ -63,19 +66,15 @@ export class SettingsApp {
     #structured = null;
     #loading = true;
     #interruptArmed = false;
-    /** Values requested but not yet reflected by the source, keyed by entry. */
+    // Invariant: pending values remain visible until the source reflects them.
     #pending = new Map();
     #footerHeight = 1;
-    /** Column the dialog's values start at, so a label stays a label. */
     #dialogValueColumn = 0;
-    /** Screen row the dialog panel starts on, for pointer hits. */
     #panelTop = 0;
     #panelTopForFrame = 0;
-    /** Row key under the pointer, and where each row was drawn last frame. */
     #hoverKey = null;
     #hoverRegion = "label";
     #frameRows = [];
-    /** Where the value menu was drawn last frame, for hit testing. */
     #menuFrame = null;
     constructor(session) {
         this.#session = session;
@@ -90,15 +89,19 @@ export class SettingsApp {
         const theme = host.theme ?? PLAIN_THEME;
         this.#interruptArmed = host.interruptArmed;
         const rows = this.#rows();
+        const selected = indexOfKey(rows, this.#selectedKey);
         const footer = this.#footerLines(rect.width, theme);
         this.#footerHeight = footer.length;
         this.#panelTopForFrame = Math.max(0, rect.height - footer.length);
         this.#panelTop = this.#panelTopForFrame;
         const bodyHeight = Math.max(0, rect.height - footer.length);
-        const selected = indexOfKey(rows, this.#selectedKey);
-        this.#scroll = scrollForSelection(rows, bodyHeight, this.#scroll, selected, this.#reveal);
+        if (this.#selectionNeedsReveal) {
+            this.#scroll = scrollForSelection(rows, bodyHeight, this.#scroll, selected, this.#reveal);
+            this.#selectionNeedsReveal = false;
+        }
         this.#reveal = undefined;
         const layout = layoutList(rows, bodyHeight, this.#scroll);
+        this.#scroll = layout.scroll;
         const contentWidth = Math.max(0, rect.width - RAIL_COLUMNS);
         const valueColumn = this.#valueColumn(rows);
         const geometry = scrollbarGeometry({
@@ -121,14 +124,13 @@ export class SettingsApp {
             for (const index of layout.rowIndexes) {
                 const row = rows[index];
                 if (row !== undefined && row.kind === "element") {
+                    const view = this.#viewRow(row.value);
                     this.#frameRows.push({
-                        key: `${row.value.backend}:${row.value.id}`,
+                        key: view.key,
                         screenRow: body.length,
                         valueColumn,
-                        valueWidth: row.value.structured
-                            ? CONFIGURE.length
-                            : row.value.value === null ? 0 : displayWidth(displayValue(row.value.value)),
-                        stepper: isStepper(row.value),
+                        valueWidth: displayWidth(view.value),
+                        stepper: view.stepper !== undefined,
                     });
                 }
                 body.push(this.#renderRow(row, index === selected, contentWidth, valueColumn, theme));
@@ -148,7 +150,8 @@ export class SettingsApp {
             return this.#menuKey(data);
         if (this.#filter !== null)
             return this.#filterKey(data);
-        const action = SETTINGS_SHORTCUTS.resolve(KEYS[data] ?? data, SCOPE);
+        const key = KEYS[data] ?? data;
+        const action = SETTINGS_SHORTCUTS.resolve(key, SCOPE);
         if (action === null)
             return { consumed: false };
         const rows = this.#rows();
@@ -186,11 +189,14 @@ export class SettingsApp {
             }
             case "first":
             case "last": {
-                // End lands on the very last setting, not on the head of its section.
+                // Invariant: End lands on the very last setting, not on the head of its section.
                 const selectable = selectableIndexes(rows);
                 const target = action === "last" ? selectable.at(-1) : selectable[0];
-                if (target !== undefined)
-                    this.#jump(rows, target);
+                if (target !== undefined) {
+                    this.#select(rows, target);
+                    if (action === "first")
+                        this.#scroll = 0;
+                }
                 return { consumed: true };
             }
             case "previous-value":
@@ -208,7 +214,7 @@ export class SettingsApp {
             const overRow = menuRowAt(frame, event.row - 1, event.column);
             const overMenu = overRow !== null;
             if (event.kind === "motion") {
-                // The menu owns the pointer, but the row it came from is still the thing
+                // Invariant: the menu owns the pointer, but the row it came from is still the thing
                 // being changed, so its value keeps reading as the one under the pointer.
                 // Only a dialog that takes the screen puts that out.
                 const hadHover = this.#hoverKey !== menu.anchorKey || this.#hoverRegion !== "value";
@@ -227,7 +233,7 @@ export class SettingsApp {
             if (event.kind !== "press")
                 return { consumed: true, render: false };
             if (overRow === null) {
-                // A press anywhere else dismisses the menu rather than acting through it.
+                // Invariant: a press anywhere else dismisses the menu rather than acting through it.
                 this.#menu = null;
                 return { consumed: true };
             }
@@ -239,7 +245,7 @@ export class SettingsApp {
         }
         const open = this.#structured;
         if (open !== null) {
-            // The panel owns the pointer while it is open; its flag rows are the targets.
+            // Invariant: the panel owns the pointer while it is open; its flag rows are the targets.
             // The panel's rows begin one line below its rule.
             const panel = { firstRow: this.#panelTop + 1, rows: open.flags.length, valueColumn: this.#dialogValueColumn };
             const row = event.row - 1 - panel.firstRow;
@@ -253,7 +259,7 @@ export class SettingsApp {
             }
             if (event.kind === "press") {
                 open.index = row;
-                // Pointing at the label picks the row; the value is what changes it,
+                // Rationale: pointing at the label picks the row; the value is what changes it,
                 // exactly as in the list behind the dialog.
                 const key = open.flags[row] ?? "";
                 const width = displayWidth((open.record[key] ?? false) ? "true" : "false");
@@ -263,6 +269,15 @@ export class SettingsApp {
             }
             return { consumed: true, render: false };
         }
+        if (event.kind === "wheel-up" || event.kind === "wheel-down") {
+            // Invariant: the whole list pane owns wheel scrolling, including blank space beside
+            // short labels. It must not depend on finding an item under the pointer.
+            if (event.row < 1 || event.row > this.#panelTopForFrame)
+                return { consumed: false };
+            const distance = scrollbarWheelRows(this.#scrollbarSpeed());
+            this.#scroll = Math.max(0, this.#scroll + (event.kind === "wheel-down" ? distance : -distance));
+            return { consumed: true };
+        }
         const row = this.#frameRows.find(candidate => candidate.screenRow === event.row - 1);
         const previousKey = this.#hoverKey;
         const previousRegion = this.#hoverRegion;
@@ -277,7 +292,7 @@ export class SettingsApp {
             const rows = this.#rows();
             const index = rows.findIndex(candidate => rowKey(candidate) === row.key);
             if (index >= 0) {
-                // The pointer acts where it points; the arrow belongs to the keyboard.
+                // Rationale: the pointer acts where it points; the arrow belongs to the keyboard.
                 this.#notice = null;
                 if (this.#hoverRegion === "minus")
                     this.#cycle(rows, index, -1);
@@ -288,10 +303,6 @@ export class SettingsApp {
             }
             return { consumed: true };
         }
-        if (event.kind === "wheel-up" || event.kind === "wheel-down") {
-            this.#scroll = Math.max(0, this.#scroll + (event.kind === "wheel-down" ? 3 : -3));
-            return { consumed: true };
-        }
         const changed = previousKey !== this.#hoverKey || previousRegion !== this.#hoverRegion;
         return { consumed: event.kind !== "motion", render: changed };
     }
@@ -305,7 +316,7 @@ export class SettingsApp {
             return;
         }
         const shown = this.#shownValue(entry);
-        // A number is stepped, not picked from a list: it has its own two controls,
+        // Rationale: a number is stepped, not picked from a list: it has its own two controls,
         // and pointing at it is not a request for anything else.
         if (typeof shown === "number")
             return;
@@ -314,16 +325,12 @@ export class SettingsApp {
             return;
         }
         const current = shown === null ? 0 : Math.max(0, entry.choices.indexOf(shown));
-        // Nothing is highlighted until the pointer or a key picks a row, so opening
-        // the menu does not flash a highlight the reader did not ask for.
-        this.#menu = { entry, current, anchorKey: `${entry.backend}:${entry.id}`, choices: entry.choices, index: -1 };
+        // Compatibility: pinned SelectList opens on the value currently in effect.
+        this.#menu = { entry, current, anchorKey: `${entry.backend}:${entry.id}`, choices: entry.choices, index: current };
     }
-    /**
-     * A structured setting is a set of flags, so it opens as its own list rather
-     * than as a value menu: each row names one flag and toggles it in place.
-     */
+    // Rationale: a structured setting opens as its own flag list rather than a value menu.
     #openStructured(entry) {
-        // The flags come from the declaration, not from the stored value: an unset
+        // Invariant: the flags come from the declaration, not from the stored value: an unset
         // flag still has a row, showing the default the source would apply.
         if (entry.flags.length === 0) {
             this.#notice = `${labelOf(entry)} has nothing to configure`;
@@ -337,7 +344,7 @@ export class SettingsApp {
             const value = stored[flag.key];
             record[flag.key] = typeof value === "boolean" ? value : flag.fallback;
         }
-        // The dialog takes the screen: the row it was opened from stops being the
+        // Invariant: the dialog takes the screen: the row it was opened from stops being the
         // thing under the pointer, so it stops looking like it.
         this.#hoverKey = null;
         this.#hoverRegion = "label";
@@ -385,7 +392,7 @@ export class SettingsApp {
             return { consumed: true };
         }
         if (key === "up" || key === "down") {
-            // The keyboard starts from the value in effect rather than from the top.
+            // Compatibility: the keyboard starts from the value in effect rather than from the top.
             menu.index = menu.index < 0
                 ? menu.current
                 : Math.min(menu.choices.length - 1, Math.max(0, menu.index + (key === "down" ? 1 : -1)));
@@ -403,9 +410,20 @@ export class SettingsApp {
         if (input === null)
             return { consumed: false };
         const key = KEYS[data];
+        if (key === "home" || key === "end") {
+            const rows = this.#rows();
+            const selectable = selectableIndexes(rows);
+            const target = key === "end" ? selectable.at(-1) : selectable[0];
+            if (target !== undefined) {
+                this.#select(rows, target);
+                if (key === "home")
+                    this.#scroll = 0;
+            }
+            return { consumed: true };
+        }
         if (key === "up" || key === "down" || key === "shift+up" || key === "shift+down") {
             const rows = this.#rows();
-            // Nothing found means nothing to move through; the key is still swallowed
+            // Rationale: nothing found means nothing to move through; the key is still swallowed
             // rather than typed into the search.
             if (selectableIndexes(rows).length === 0)
                 return { consumed: true, render: false };
@@ -437,7 +455,7 @@ export class SettingsApp {
         }
         const shown = this.#shownValue(entry);
         if (typeof shown === "number") {
-            // At the end of the range there is nothing to say: the arrow already reads
+            // Rationale: at the end of the range there is nothing to say: the arrow already reads
             // as unavailable, so a message would only repeat it.
             const next = steppedValue(rangeOf(entry), shown, delta);
             if (next !== null)
@@ -458,25 +476,38 @@ export class SettingsApp {
     }
     #apply(entry, value) {
         const key = `${entry.backend}:${entry.id}`;
-        // Shown immediately so the row never lags a keypress, and so the next press
+        // Invariant: shown immediately so the row never lags a keypress, and so the next press
         // steps from here rather than from a value the source has not caught up to.
         this.#pending.set(key, value);
         void this.#session.change(entry.backend, entry.id, value).then(outcome => {
-            if (outcome.failure !== null) {
+            if (outcome.failure !== null || outcome.status === "failed") {
                 this.#pending.delete(key);
-                this.#notice = `Could not save ${labelOf(entry)}: ${outcome.failure}`;
+                this.#notice = `Could not save ${labelOf(entry)}: ${outcome.failure ?? "the effect failed"}`;
                 return;
             }
-            // A later press may have moved on; only the last request clears itself.
+            if (outcome.status === "unavailable" || outcome.limitationReason !== null) {
+                this.#pending.delete(key);
+                this.#notice = outcome.limitationReason ?? `${labelOf(entry)} is unavailable`;
+                return;
+            }
+            // Concurrency: a later press may have moved on; only the last request clears itself.
             if (this.#pending.get(key) === value)
                 this.#pending.delete(key);
-            this.#notice = outcome.pendingRestart ? `${labelOf(entry)} applies on the next start` : null;
+            this.#notice = outcome.status === "deferred" && outcome.application !== null
+                ? `${labelOf(entry)} is stored and applies ${applicationLabel(outcome.application)}`
+                : null;
         });
     }
-    /** What the row shows: the value asked for if one is outstanding, else the source's. */
     #shownValue(entry) {
         return this.#pending.get(`${entry.backend}:${entry.id}`) ?? entry.value;
     }
+    #scrollbarSpeed() {
+        const entry = this.#session.sections()
+            .flatMap(section => section.entries)
+            .find(candidate => candidate.backend === "a1" && candidate.id === "scrollbarSpeed");
+        const value = entry === undefined ? this.#session.value("scrollbarSpeed") : this.#shownValue(entry);
+        return isScrollbarSpeed(value) ? value : "normal";
+    }
     #jump(rows, target) {
         this.#select(rows, target);
         this.#reveal = blockRowSpan(rows, target);
@@ -485,6 +516,7 @@ export class SettingsApp {
         if (index < 0)
             return;
         this.#selectedKey = rowKey(rows[index]);
+        this.#selectionNeedsReveal = true;
         this.#notice = null;
     }
     #rows() {
@@ -494,7 +526,7 @@ export class SettingsApp {
             || labelOf(entry).toLowerCase().includes(needle);
         const rows = [];
         for (const section of this.#session.sections()) {
-            // A section named by the search is what the reader asked for, so it arrives
+            // Rationale: a section named by the search is what the reader asked for, so it arrives
             // whole rather than narrowed to the entries that happen to repeat its name.
             const named = needle.length > 0 && section.title.toLowerCase().includes(needle);
             const entries = named ? section.entries : section.entries.filter(matches);
@@ -510,7 +542,7 @@ export class SettingsApp {
             if (section.readOnlyReason !== null && (needle.length === 0 || named)) {
                 rows.push({ kind: "note", group: section.id, text: section.readOnlyReason });
             }
-            // Presented in the order the source reports, which is the order the
+            // Invariant: presented in the order the source reports, which is the order the
             // pinned engine shows and is neither declaration order nor alphabetical.
             for (const entry of entries) {
                 rows.push({
@@ -543,18 +575,18 @@ export class SettingsApp {
         const hovered = this.#hoverKey === key;
         return renderListRow(this.#viewRow(entry), { selected, hovered, region: this.#hoverRegion }, valueColumn, width, theme);
     }
-    /** What the list view needs to draw a setting: its words, and where it can go. */
     #viewRow(entry) {
         const shown = this.#shownValue(entry);
         const value = entry.structured
             ? CONFIGURE
-            : shown === null ? describeRaw(entry.rawValue) : displayValue(shown);
+            : shown === null
+                ? describeRaw(entry.rawValue)
+                : effectiveDisplay(entry, shown);
         const range = rangeOf(entry);
         return {
             key: `${entry.backend}:${entry.id}`,
             label: labelOf(entry),
             value,
-            ...(entry.origin === "default" ? { suffix: "(default)" } : {}),
             ...(typeof shown === "number" && entry.editable ? { stepper: stepperEnds(range, shown) } : {}),
         };
     }
@@ -578,13 +610,12 @@ export class SettingsApp {
         this.#menuFrame = frame;
         return renderValueMenu(lines, state, frame, theme);
     }
-    /** What the panel needs to present a structured setting's parts. */
     #dialogLines(open, width, theme) {
         const rows = open.flags.map(key => {
             const declared = open.entry.flags.find(flag => flag.key === key);
             return {
                 label: declared?.label ?? humanizeLabel(key),
-                // The engine writes these as the booleans they are rather than as yes/no.
+                // Protocol: the engine writes these as the booleans they are rather than as yes/no.
                 value: (open.record[key] ?? false) ? "true" : "false",
                 ...(declared?.description === undefined ? {} : { description: declared.description }),
             };
@@ -597,8 +628,6 @@ export class SettingsApp {
         const open = this.#structured;
         if (open !== null)
             return this.#dialogLines(open, width, theme);
-        // The hint is the declarations, so a key cannot be described here and bound
-        // to something else.
         const hint = this.#interruptArmed ? "press ctrl+c again to exit A1" : SETTINGS_SHORTCUTS.hint(SCOPE);
         const status = renderStatusLine({ hint, report: this.#notice }, width, theme);
         const input = this.#filter;
@@ -624,6 +653,23 @@ function displayValue(value) {
         return value ? "yes" : "no";
     return String(value);
 }
+function effectiveDisplay(entry, stored) {
+    const effective = entry.effectiveValue;
+    if (effective === stored)
+        return displayValue(stored);
+    const shownEffective = typeof effective === "string" || typeof effective === "number" || typeof effective === "boolean"
+        ? displayValue(effective)
+        : describeRaw(effective);
+    return `${displayValue(stored)} (effective ${shownEffective}; ${applicationLabel(entry.application)})`;
+}
+function applicationLabel(application) {
+    switch (application) {
+        case "live": return "live";
+        case "next-session": return "in the next session";
+        case "next-start": return "on the next start";
+        case "current-exit": return "when the current session exits";
+    }
+}
 function describeRaw(value) {
     if (value === null || value === undefined)
         return "unset";
@@ -631,3 +677,6 @@ function describeRaw(value) {
         return Array.isArray(value) ? `${value.length} items` : "structured value";
     return String(value);
 }
+function isScrollbarSpeed(value) {
+    return value === "normal" || value === "fast" || value === "high";
+}

package/dist/{src/features → features}/workspace/capabilities.d.ts

@@ -1,4 +1,4 @@
-import type { ManagedAgentDescriptor } from "../../foundation/workspace-contracts/index.js";
+import type { ManagedAgentDescriptor } from "../../contracts/workspace/index.js";
 export type WorkspaceCapabilityAction = {
     readonly type: "structured-command";
     readonly command: string;

package/dist/{src/features → features}/workspace/reducer.d.ts

@@ -1,4 +1,4 @@
-import { type ManagedAgentDescriptor } from "../../foundation/workspace-contracts/index.js";
+import { type ManagedAgentDescriptor } from "../../contracts/workspace/index.js";
 export interface WorkspaceAgentFailure {
     readonly code: string;
     readonly message: string;
@@ -23,6 +23,7 @@ export type WorkspaceReducerResult<T = undefined> = {
     readonly code: string;
     readonly diagnostic: string;
 };
+/** Applies validated workspace mutations and advances the revision only when observable state changes. */
 export declare class WorkspaceReducer {
     #private;
     readonly workspaceId: string;

package/dist/{src/features → features}/workspace/reducer.js

@@ -1,5 +1,6 @@
-import { assertManagedAgentDescriptor, } from "../../foundation/workspace-contracts/index.js";
+import { assertManagedAgentDescriptor, } from "../../contracts/workspace/index.js";
 const REMOVABLE_STATES = new Set(["stopped", "failed", "discontinuous"]);
+/** Applies validated workspace mutations and advances the revision only when observable state changes. */
 export class WorkspaceReducer {
     workspaceId;
     #agents = new Map();

package/dist/{src/features → features}/workspace/router.d.ts

@@ -1,5 +1,5 @@
 import { type StructuredCommandRecord } from "../../foundation/structured-agent-runtime/index.js";
-import type { ManagedAgentDescriptor } from "../../foundation/workspace-contracts/index.js";
+import type { ManagedAgentDescriptor } from "../../contracts/workspace/index.js";
 import { WorkspaceReducer, type WorkspaceAgentState, type WorkspaceView } from "./reducer.js";
 export interface RoutedStructuredCommand {
     readonly agentId: string;
@@ -16,6 +16,7 @@ export type WorkspaceRouterResult<T = undefined> = {
     readonly code: string;
     readonly diagnostic: string;
 };
+/** Serializes workspace actions and capability-gates structured commands at the selected-agent boundary. */
 export declare class WorkspaceRouter {
     #private;
     readonly reducer: WorkspaceReducer;

package/dist/{src/features → features}/workspace/router.js

@@ -1,6 +1,7 @@
 import { StructuredCommandTracker, } from "../../foundation/structured-agent-runtime/index.js";
 import { gateWorkspaceAction } from "./capabilities.js";
 import { WorkspaceReducer } from "./reducer.js";
+/** Serializes workspace actions and capability-gates structured commands at the selected-agent boundary. */
 export class WorkspaceRouter {
     reducer;
     #trackers = new Map();

package/dist/{src/features → features}/workspace/store.d.ts

@@ -1,5 +1,6 @@
-import type { AgentRecoveryAuthority, RecoveryReferenceId } from "../../foundation/workspace-contracts/index.js";
+import type { AgentRecoveryAuthority, RecoveryReferenceId } from "../../contracts/workspace/index.js";
 import { WorkspaceReducer, type WorkspaceView } from "./reducer.js";
+/** Persists complete workspace views and recovery references through the control-store boundary. */
 export declare class WorkspaceStore {
     #private;
     constructor(path: string);

package/dist/{src/features → features}/workspace/store.js

@@ -1,5 +1,6 @@
 import { ControlStore, DEFAULT_WORKSPACE_ID, } from "../../foundation/storage/index.js";
 import { WorkspaceReducer } from "./reducer.js";
+/** Persists complete workspace views and recovery references through the control-store boundary. */
 export class WorkspaceStore {
     #store;
     constructor(path) {

package/dist/{src/foundation → foundation}/launch-guardian/main.js

@@ -4,7 +4,8 @@ import { resolve } from "node:path";
 import { assertLaunchProfileId } from "../lifecycle/index.js";
 import { closeVerifiedContainment, LinuxNativeProcessInspector, NativeGuardianContainment, resolveProcessGuardianPath, verifyProcessGuardianArtifact, WindowsNativeProcessInspector, } from "../process-containment/index.js";
 import { SupervisorClient } from "../protocol/index.js";
-import { resolveProductPaths } from "../supervision/index.js";
+import { resolveCohortEndpoint, resolveProductPaths } from "../supervision/index.js";
+import { markStartupPhase } from "../startup/index.js";
 export async function runLaunchGuardian(options) {
     assertLaunchProfileId(options.profileId);
     const environment = { ...(options.environment ?? process.env) };
@@ -17,7 +18,14 @@ export async function runLaunchGuardian(options) {
     if (!guardianIdentity)
         throw diagnosticError("launch guardian cannot verify its own native process identity", "PROCESS_IDENTITY_UNAVAILABLE");
     const client = options.control ?? new SupervisorClient(environment[PRODUCT_IDENTITY.environment.releaseId]);
-    await client.connect(paths.endpoint);
+    // Invariant: an instance belongs to the cohort that launched it and talks to that cohort's endpoint
+    // for its whole life, whatever release becomes the active one meanwhile.
+    const releaseId = environment[PRODUCT_IDENTITY.environment.releaseId];
+    const endpoint = releaseId
+        ? resolveCohortEndpoint(paths, releaseId, environment).endpoint
+        : paths.endpoint;
+    await client.connect(endpoint);
+    await markStartupPhase(environment, "guardian-connected");
     const containment = options.containment ?? new NativeGuardianContainment(instanceId, helperPath, resolve(paths.runtimeDir, "launch-instances", `${instanceId}.ready.json`));
     const stop = stopRequests(client, instanceId);
     let rootIdentity = null;

package/dist/{src/foundation → foundation}/lifecycle/model.d.ts

@@ -1,4 +1,4 @@
-export type LaunchProfileId = "a1" | "pi" | "sandbox";
+export type LaunchProfileId = "a1" | "pi";
 export type GenerationId = string;
 export type DriverProfileId = string;
 export type RequestId = string;

package/dist/{src/foundation → foundation}/lifecycle/model.js

@@ -1,6 +1,6 @@
 import { PRODUCT_TEXT } from "../../product-identity.js";
 export function assertLaunchProfileId(value) {
-    if (value !== "a1" && value !== "pi" && value !== "sandbox")
+    if (value !== "a1" && value !== "pi")
         throw new TypeError(PRODUCT_TEXT.diagnostic(`launch profile is invalid: ${String(value)}`));
 }
 export function assertDimensions(dimensions) {

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

@@ -0,0 +1,28 @@
+export interface ProductPaths {
+    readonly configDir: string;
+    readonly dataDir: string;
+    readonly runtimeDir: string;
+    readonly databasePath: string;
+    /** The endpoint written by releases that predate cohort-scoped identity. */
+    readonly endpoint: string;
+    /** The metadata written by releases that predate cohort-scoped identity. */
+    readonly endpointMetadataPath: string;
+    readonly endpointsDir: string;
+    readonly supervisorLogPath: string;
+}
+/** Where one cohort listens, and where it records that it is listening. */
+export interface CohortEndpointPaths {
+    readonly endpoint: string;
+    readonly endpointMetadataPath: string;
+}
+/**
+ * Endpoint identity for one release cohort. Two cohorts can be live at once — an update
+ * leaves a working session on the release it started on — so the name a supervisor listens
+ * on has to name the release as well as the runtime directory, or the two contend for one
+ * endpoint and replacing one means ending the other.
+ *
+ * An explicit endpoint override keeps its single endpoint: it is how an isolated run pins
+ * the address it is going to talk to.
+ */
+export declare function resolveCohortEndpoint(paths: ProductPaths, releaseId: string, environment?: NodeJS.ProcessEnv, hostPlatform?: NodeJS.Platform): CohortEndpointPaths;
+export declare function resolveProductPaths(environment?: NodeJS.ProcessEnv, hostPlatform?: NodeJS.Platform, fallbackHome?: string): ProductPaths;

package/dist/{src/foundation → foundation}/lifecycle/paths.js

@@ -2,6 +2,26 @@ import { createHash } from "node:crypto";
 import { homedir, platform } from "node:os";
 import { posix, win32 } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/**
+ * Endpoint identity for one release cohort. Two cohorts can be live at once — an update
+ * leaves a working session on the release it started on — so the name a supervisor listens
+ * on has to name the release as well as the runtime directory, or the two contend for one
+ * endpoint and replacing one means ending the other.
+ *
+ * An explicit endpoint override keeps its single endpoint: it is how an isolated run pins
+ * the address it is going to talk to.
+ */
+export function resolveCohortEndpoint(paths, releaseId, environment = process.env, hostPlatform = platform()) {
+    if (environment[PRODUCT_IDENTITY.environment.endpoint]) {
+        return { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath };
+    }
+    const path = hostPlatform === "win32" ? win32 : posix;
+    const token = createHash("sha256").update(releaseId).digest("hex").slice(0, 16);
+    const endpoint = hostPlatform === "win32"
+        ? `${paths.endpoint}-${token}`
+        : path.join(paths.runtimeDir, `${token}-${PRODUCT_IDENTITY.endpoint.unixSocketFilename}`);
+    return { endpoint, endpointMetadataPath: path.join(paths.endpointsDir, `${token}.json`) };
+}
 export function resolveProductPaths(environment = process.env, hostPlatform = platform(), fallbackHome = homedir()) {
     const windows = hostPlatform === "win32";
     const path = windows ? win32 : posix;
@@ -37,6 +57,7 @@ export function resolveProductPaths(environment = process.env, hostPlatform = pl
         databasePath: path.resolve(databaseOverride ?? path.join(dataDir, PRODUCT_IDENTITY.endpoint.databaseFilename)),
         endpoint,
         endpointMetadataPath: path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.metadataFilename),
+        endpointsDir: path.join(runtimeDir, "endpoints"),
         supervisorLogPath: path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.supervisorLogFilename),
     };
 }

package/dist/{src/foundation → foundation}/native-host-protocol/codec.d.ts

@@ -1,8 +1,10 @@
 import { type NativeHostProofMessage } from "./messages.js";
+/** Identifies a bounded native-host framing or message-contract failure. */
 export declare class NativeHostProtocolError extends Error {
     readonly code: "frame-too-large" | "malformed-frame" | "invalid-message";
     constructor(code: "frame-too-large" | "malformed-frame" | "invalid-message", message: string);
 }
+/** Encodes and incrementally decodes size-bounded newline-delimited native-host proof messages. */
 export declare class NativeHostFrameCodec {
     #private;
     encode(message: NativeHostProofMessage): string;

package/dist/{src/foundation → foundation}/native-host-protocol/codec.js

@@ -1,4 +1,5 @@
 import { MAX_NATIVE_HOST_MESSAGE_BYTES, assertNativeHostProofMessage, } from "./messages.js";
+/** Identifies a bounded native-host framing or message-contract failure. */
 export class NativeHostProtocolError extends Error {
     code;
     constructor(code, message) {
@@ -7,6 +8,7 @@ export class NativeHostProtocolError extends Error {
         this.name = "NativeHostProtocolError";
     }
 }
+/** Encodes and incrementally decodes size-bounded newline-delimited native-host proof messages. */
 export class NativeHostFrameCodec {
     #buffer = "";
     encode(message) {

package/dist/{src/foundation → foundation}/native-host-protocol/messages.d.ts

@@ -1,4 +1,4 @@
-import { type CorrelationId, type NativeHostCommand, type NativeHostEvent, type NativeHostHello, type PaneId, type TerminalSessionLaunch } from "../workspace-contracts/index.js";
+import { type CorrelationId, type NativeHostCommand, type NativeHostEvent, type NativeHostHello, type PaneId, type TerminalSessionLaunch } from "../../contracts/workspace/index.js";
 export declare const NATIVE_HOST_PROTOCOL_NAME: string;
 export declare const MAX_NATIVE_HOST_MESSAGE_BYTES: number;
 export type NativeHostProofMessage = {

package/dist/{src/foundation → foundation}/native-host-protocol/messages.js

@@ -1,4 +1,4 @@
-import { NATIVE_HOST_PROTOCOL_VERSION, assertNativeHostCommand, assertTerminalSessionLaunch, } from "../workspace-contracts/index.js";
+import { NATIVE_HOST_PROTOCOL_VERSION, assertNativeHostCommand, assertTerminalSessionLaunch, } from "../../contracts/workspace/index.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 export const NATIVE_HOST_PROTOCOL_NAME = PRODUCT_IDENTITY.protocol.nativeHostSchema;
 export const MAX_NATIVE_HOST_MESSAGE_BYTES = 1024 * 1024;

package/dist/{src/foundation → foundation}/process-containment/linux-process-inspector.d.ts

@@ -1,5 +1,6 @@
 import type { NativeProcessIdentity } from "../lifecycle/index.js";
 import type { NativeProcessInspector } from "./contracts.js";
+/** Verifies Linux process identity from the PID and kernel start-time field in procfs. */
 export declare class LinuxNativeProcessInspector implements NativeProcessInspector {
     observe(pid: number): Promise<NativeProcessIdentity | null>;
     matches(identity: NativeProcessIdentity): Promise<boolean>;

package/dist/{src/foundation → foundation}/process-containment/linux-process-inspector.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+/** Verifies Linux process identity from the PID and kernel start-time field in procfs. */
 export class LinuxNativeProcessInspector {
     async observe(pid) {
         if (!Number.isSafeInteger(pid) || pid <= 0)