@timurproko/a1 0.1.8-dev.157 → 0.1.8-dev.214

package/dist/features/owned-ui/settings-app.js

@@ -1,4 +1,4 @@
-import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, assertNoShortcutConflicts, 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 "../../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;
@@ -57,7 +57,7 @@ export class SettingsApp {
     #session;
     #selectedKey;
     #scroll = 0;
-    /** Keyboard navigation requests visibility once; pointer scrolling then stays free. */
+    // Invariant: keyboard navigation requests visibility once; pointer scrolling then stays free.
     #selectionNeedsReveal = true;
     #reveal;
     #notice = null;
@@ -66,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;
@@ -93,12 +89,12 @@ 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);
         if (this.#selectionNeedsReveal) {
             this.#scroll = scrollForSelection(rows, bodyHeight, this.#scroll, selected, this.#reveal);
             this.#selectionNeedsReveal = false;
@@ -154,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();
@@ -192,7 +189,7 @@ 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) {
@@ -217,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";
@@ -236,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 };
             }
@@ -248,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;
@@ -262,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");
@@ -273,11 +270,12 @@ export class SettingsApp {
             return { consumed: true, render: false };
         }
         if (event.kind === "wheel-up" || event.kind === "wheel-down") {
-            // The whole list pane owns wheel scrolling, including blank space beside
+            // 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 };
-            this.#scroll = Math.max(0, this.#scroll + (event.kind === "wheel-down" ? 3 : -3));
+            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);
@@ -294,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);
@@ -318,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;
@@ -327,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`;
@@ -350,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";
@@ -398,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)));
@@ -429,7 +423,7 @@ export class SettingsApp {
         }
         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 };
@@ -461,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)
@@ -482,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 ?? "the effect failed"}`;
+                return;
+            }
+            if (outcome.status === "unavailable" || outcome.limitationReason !== null) {
                 this.#pending.delete(key);
-                this.#notice = `Could not save ${labelOf(entry)}: ${outcome.failure}`;
+                this.#notice = outcome.limitationReason ?? `${labelOf(entry)} is unavailable`;
                 return;
             }
-            // A later press may have moved on; only the last request clears itself.
+            // 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);
@@ -519,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);
@@ -535,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({
@@ -568,12 +575,13 @@ 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}`,
@@ -602,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 }),
             };
@@ -621,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;
@@ -648,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";
@@ -655,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/features/workspace/reducer.d.ts

@@ -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/features/workspace/reducer.js

@@ -1,5 +1,6 @@
 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/features/workspace/router.d.ts

@@ -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/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/features/workspace/store.d.ts

@@ -1,5 +1,6 @@
 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/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/foundation/launch-guardian/main.js

@@ -17,7 +17,7 @@ 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]);
-    // An instance belongs to the cohort that launched it and talks to that cohort's 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

package/dist/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/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/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/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)

package/dist/foundation/process-containment/native-guardian-containment.d.ts

@@ -1,5 +1,6 @@
 import type { NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
 import type { ContainedProcessHandle, ContainedSpawnOptions, ProcessContainment } from "./contracts.js";
+/** Delegates one root runtime to the native guardian and exposes its verified containment identity. */
 export declare class NativeGuardianContainment implements ProcessContainment {
     #private;
     readonly instanceId: string;

package/dist/foundation/process-containment/native-guardian-containment.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { mkdir, readFile, rm } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/** Delegates one root runtime to the native guardian and exposes its verified containment identity. */
 export class NativeGuardianContainment {
     instanceId;
     helperPath;

package/dist/foundation/process-containment/windows-process-inspector.d.ts

@@ -8,6 +8,7 @@ export interface InspectorCommandResult {
 export interface InspectorCommandRunner {
     run(executable: string, arguments_: readonly string[]): Promise<InspectorCommandResult>;
 }
+/** Verifies Windows process identity through the bounded process-guardian inspection command. */
 export declare class WindowsNativeProcessInspector implements NativeProcessInspector {
     readonly helperPath: string;
     private readonly runner;

package/dist/foundation/process-containment/windows-process-inspector.js

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+/** Verifies Windows process identity through the bounded process-guardian inspection command. */
 export class WindowsNativeProcessInspector {
     helperPath;
     runner;

package/dist/foundation/protocol/client.d.ts

@@ -5,6 +5,7 @@ interface ClientEvents {
     stopIntent: [LaunchInstanceStopIntent];
     disconnect: [];
 }
+/** Maintains one negotiated supervisor connection and rejects all pending commands on disconnect. */
 export declare class SupervisorClient extends EventEmitter<ClientEvents> {
     #private;
     readonly clientId: `${string}-${string}-${string}-${string}-${string}`;

package/dist/foundation/protocol/client.js

@@ -2,6 +2,7 @@ import { EventEmitter } from "node:events";
 import { connect } from "node:net";
 import { randomUUID } from "node:crypto";
 import { CONTROL_ENVELOPE, CONTROL_ENVELOPE_REVISION, encodeFrame, LineFrameDecoder, localControlHello, negotiateControlFeatures } from "./messages.js";
+/** Maintains one negotiated supervisor connection and rejects all pending commands on disconnect. */
 export class SupervisorClient extends EventEmitter {
     clientId = randomUUID();
     releaseId;

package/dist/foundation/protocol/messages.d.ts

@@ -76,6 +76,7 @@ export interface ControlNegotiation {
 export declare function localControlHello(releaseId?: string): ControlHello;
 export declare function negotiateControlFeatures(client: ControlHello, server?: ControlHello): ControlNegotiation;
 export declare function encodeFrame(message: ClientMessage | ServerMessage | Readonly<Record<string, unknown>>): string;
+/** Incrementally decodes size-bounded newline-delimited control frames from arbitrary chunks. */
 export declare class LineFrameDecoder {
     #private;
     push(chunk: Buffer | string): unknown[];

package/dist/foundation/protocol/messages.js

@@ -58,6 +58,7 @@ export function negotiateControlFeatures(client, server = localControlHello()) {
 export function encodeFrame(message) {
     return `${JSON.stringify(message)}\n`;
 }
+/** Incrementally decodes size-bounded newline-delimited control frames from arbitrary chunks. */
 export class LineFrameDecoder {
     #buffer = "";
     push(chunk) {

package/dist/foundation/release/bootstrap.js

@@ -21,11 +21,11 @@ export async function runBootstrap(options) {
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
     const stateStore = new CohortStateStore(paths.dataDir);
     let state = await stateStore.read();
-    // Records left by cohorts whose processes are gone say nothing about ownership, and there
+    // Invariant: records left by cohorts whose processes are gone say nothing about ownership, and there
     // can now be several of them. Clearing them first keeps the decision below about what is
     // actually running.
     await sweepDeadEndpoints(paths).catch(() => []);
-    // Each cohort keeps its own endpoint, so a launch looks for the endpoint of the release it
+    // Protocol: each cohort keeps its own endpoint, so a launch looks for the endpoint of the release it
     // is about to run rather than for the one endpoint the runtime directory used to have.
     const activeReleaseId = state.references.active;
     let endpointPaths = activeReleaseId === null
@@ -33,7 +33,7 @@ export async function runBootstrap(options) {
         : resolveCohortEndpoint(paths, activeReleaseId, environment);
     let endpoint = await readEndpointMetadata(endpointPaths.endpointMetadataPath);
     if (endpoint === null) {
-        // A release that predates cohort-scoped endpoints published one endpoint for the whole
+        // Compatibility: a release that predates cohort-scoped endpoints published one endpoint for the whole
         // runtime directory. Recognizing it is what lets a session started by that release keep
         // working through the first launch that knows about cohorts.
         const legacy = await readEndpointMetadata(paths.endpointMetadataPath);
@@ -76,7 +76,7 @@ export async function runBootstrap(options) {
     }
     else if (!activeIsLaunchable && candidate.releaseId !== activeId
         && state.releases[candidate.releaseId]?.approval !== "approved") {
-        // The active reference points at a copy that cannot launch, so reusing it
+        // Invariant: the active reference points at a copy that cannot launch, so reusing it
         // is off the table — but an unapproved candidate would lose the selection
         // below to that same broken active (`start-active`). Approving the healed
         // candidate here lets ordinary cohort selection activate it, while a live
@@ -85,7 +85,7 @@ export async function runBootstrap(options) {
         await stateStore.approve(candidate.releaseId, diagnosticsPath);
         state = await stateStore.read();
     }
-    // The candidate's own endpoint decides whether this launch attaches or starts a supervisor.
+    // Protocol: the candidate's own endpoint decides whether this launch attaches or starts a supervisor.
     // A cohort other than this one is not in the way: it listens somewhere else.
     endpointPaths = resolveCohortEndpoint(paths, candidate.releaseId, environment);
     endpoint = await readEndpointMetadata(endpointPaths.endpointMetadataPath);
@@ -326,7 +326,7 @@ export async function releaseVerifiedIdleOwner(metadata, dataDir, operations = {
         return true;
     }
     catch {
-        // The authenticated idle-release handshake authorizes bounded cleanup of
+        // Security: the authenticated idle-release handshake authorizes bounded cleanup of
         // this exact boot when a native handle outlives graceful shutdown.
         const diagnostics = await (operations.cleanup ?? cleanupProvenIdleOwner)(metadata);
         await writeFile(resolve(dataDir, `cleanup-${Date.now()}.json`), JSON.stringify(diagnostics, null, 2));

package/dist/foundation/release/cohort-state.d.ts

@@ -54,6 +54,7 @@ export interface SupervisorEndpointMetadata {
     readonly optionalFeatures: readonly string[];
     readonly contractDigest: string;
 }
+/** Serializes validated cohort-state revisions under a lock and commits each update atomically. */
 export declare class CohortStateStore {
     readonly path: string;
     constructor(dataDir: string);

package/dist/foundation/release/cohort-state.js

@@ -3,6 +3,7 @@ import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 export const RELEASE_COHORT_SCHEMA = PRODUCT_IDENTITY.protocol.releaseCohortSchema;
+/** Serializes validated cohort-state revisions under a lock and commits each update atomically. */
 export class CohortStateStore {
     path;
     constructor(dataDir) {

package/dist/foundation/release/release-gc.js

@@ -13,7 +13,7 @@ paths) {
     const release = state.releases[releaseId];
     if (!release)
         throw new Error(`unknown release ${releaseId}`);
-    // A superseded cohort keeps working until its last session leaves, and it runs from this
+    // Invariant: a superseded cohort keeps working until its last session leaves, and it runs from this
     // content while it does. Collecting it would pull the release out from under live work.
     if (paths && (await liveReleaseIds(paths)).includes(releaseId)) {
         throw new Error(`release ${releaseId} is still running a live cohort`);

package/dist/foundation/release/release.js

@@ -143,7 +143,7 @@ async function findInstalledDependency(root, requesterRoot, name) {
             const metadata = await lstat(candidate).catch(() => null);
             if (metadata?.isDirectory() && !metadata.isSymbolicLink())
                 return candidate;
-            // A linked dependency directory is how this installation unifies a module
+            // Invariant: a linked dependency directory is how this installation unifies a module
             // that would otherwise be present twice, and the link is made by A1 itself
             // at install and at every launch. Follow it to the directory it names and
             // collect from there, so the payload still reads only real files — but

package/dist/foundation/release/update-transaction.d.ts

@@ -14,6 +14,7 @@ export interface UpdateTransaction {
     readonly startedAt: string;
     readonly updatedAt: string;
 }
+/** Persists the durable update journal and permits only validated forward transaction phases. */
 export declare class UpdateTransactionStore {
     #private;
     readonly path: string;

package/dist/foundation/release/update-transaction.js

@@ -3,6 +3,7 @@ import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 export const UPDATE_JOURNAL_SCHEMA = PRODUCT_IDENTITY.protocol.updateJournalSchema;
+/** Persists the durable update journal and permits only validated forward transaction phases. */
 export class UpdateTransactionStore {
     path;
     constructor(dataDir) { this.path = resolve(dataDir, "update-transaction.json"); }