@timurproko/a1 0.1.8-dev.182 → 0.1.8-dev.218

package/dist/foundation/release/update.js

@@ -96,18 +96,18 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
                 await removeEndpointArtifacts(owner.paths.endpointMetadataPath, owner.paths.endpoint);
                 return { priorActiveVersion };
             }
-            // Leaving sessions alone is the expected outcome, and saying so mid-update tears
+            // Rationale: leaving sessions alone is the expected outcome, and saying so mid-update tears
             // the progress bar; only ending a session (below) is worth interrupting it for.
             if (plan === "leave-running")
                 return { priorActiveVersion };
-            // Say whose work is ending before it ends.
+            // Rationale: say whose work is ending before it ends.
             const live = endpoint.ownership.liveInstanceIds.length;
             if (live > 0) {
                 output.stderr(`${PRODUCT_TEXT.diagnostic(`ending ${live === 1 ? "one session" : `${live} sessions`} that run from the installation being replaced; a session started by an installed release would have been left alone.`)}\n`);
             }
             const identity = await requestUpdateShutdown(endpoint, targetVersion, 2_000);
             if (!identity.accepted && processIsAlive(endpoint.pid)) {
-                // Explicit update consent permits bounded cleanup of an authenticated
+                // Security: explicit update consent permits bounded cleanup of an authenticated
                 // older owner that predates the update-shutdown message.
                 const cleanup = await cleanupVerifiedOwner(endpoint, { allowLiveInstances: true, reason: "legacy-mutable-install" });
                 if (!cleanup.terminated)
@@ -133,7 +133,7 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
                 await rename(probe, packageRoot);
             }
             catch (error) {
-                // Best-effort rollback if the first rename succeeded and the second did not.
+                // Invariant: best-effort rollback runs if the first rename succeeded and the second did not.
                 await rename(probe, packageRoot).catch(() => { });
                 throw new Error(PRODUCT_TEXT.diagnostic(`package remains locked after verified shutdown: ${errorMessage(error)}`));
             }
@@ -214,7 +214,7 @@ function createUpdateProgress(output, enabled) {
             draw();
             if (creepTo <= current)
                 return;
-            // Creep asymptotically toward (but never reach) the next milestone so
+            // Rationale: creep asymptotically toward (but never reach) the next milestone so
             // long opaque phases such as npm install still show visible motion. The
             // ceiling stays a whole point below the milestone: settling on `creepTo`
             // itself would render as that milestone and make arriving at it invisible,
@@ -225,7 +225,7 @@ function createUpdateProgress(output, enabled) {
             }, PROGRESS_TICK_MS);
             timer.unref?.();
         },
-        // The bar exists to say the update is still moving. Once it has finished
+        // Rationale: the bar exists to say the update is still moving. Once it has finished
         // there is a better line to occupy that row — the one naming what is now
         // installed — so the bar gives the row back rather than leaving a full
         // meter above a message that already implies it.
@@ -283,7 +283,7 @@ async function resolveRequestedPreview(runner, requested, output) {
     const versions = (Array.isArray(published) ? published : [published]).filter((value) => typeof value === "string");
     const exact = versions.find(version => version === requested);
     if (exact !== undefined) {
-        // Naming a release here would install it through the preview path, which is a
+        // Rationale: naming a release here would install it through the preview path, which is a
         // different command with a different meaning.
         if (!exact.includes("-dev.")) {
             output.stderr(`${PRODUCT_TEXT.diagnostic(`${exact} is a release, not a preview; run ${PRODUCT_TEXT.commandName} update to move to the current release.`)}\n`);
@@ -336,7 +336,7 @@ export async function runSelfUpdate(options) {
     if (resolved.version === null)
         return resolved.exitCode;
     const targetVersion = resolved.version;
-    // No full stop after a version: it already ends in a dot-separated identifier,
+    // Rationale: no full stop after a version: it already ends in a dot-separated identifier,
     // and a trailing one reads as part of the version rather than as punctuation.
     output.stdout(`${PRODUCT_TEXT.commandName} update: ${runningVersion} → ${targetVersion}\n`);
     const progress = createUpdateProgress(output, options.progress ?? (options.output === undefined && process.stdout.isTTY === true));
@@ -375,7 +375,7 @@ export async function runSelfUpdate(options) {
             output.stdout(`${PRODUCT_TEXT.commandName} is up to date — no update needed.\n`);
             return 0;
         }
-        // The bar first appears here so a no-change run never flashes it.
+        // Rationale: the bar first appears here so a no-change run never flashes it.
         progress.set(3, 15);
         const cohortState = await new CohortStateStore(paths.dataDir).read();
         transaction = await transactionStore.begin({
@@ -403,7 +403,7 @@ export async function runSelfUpdate(options) {
             }
             transaction = await transactionStore.advance("package-installed");
         }
-        // npm 12 blocks install scripts unless allowScripts covers the package, so
+        // Compatibility: npm 12 blocks install scripts unless allowScripts covers the package, so
         // the postinstall that points the #pi-tui proxy at the tree npm just built
         // may never have run. Run the shipped script directly: the proxy must be
         // correct before the release store copies this tree. A failure is reported
@@ -417,7 +417,7 @@ export async function runSelfUpdate(options) {
             output.stderr(`${PRODUCT_TEXT.diagnostic(`could not point the #pi-tui proxy at the installed tree: ${errorMessage(error)}`)}\n`);
         }
         progress.set(70, 75);
-        // Ownership can be reacquired after an interrupted installation (for
+        // Concurrency: ownership can be reacquired after an interrupted installation (for
         // example, if bare A1 is launched before the update is resumed). Recheck
         // immediately before activation so recovery cannot start a second cohort.
         await measure("ownership-release", async () => { await lifecycle.shutdownVerifiedOwners(targetVersion); });
@@ -530,7 +530,7 @@ async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
     }
     const release = await readMaterializedRelease(prior.releaseRoot);
     const paths = resolveProductPaths(environment);
-    // Rollback re-points the active reference and starts the prior cohort on its own endpoint;
+    // Invariant: rollback re-points the active reference and starts the prior cohort on its own endpoint;
     // a cohort that survived the update keeps serving the work it already had.
     await startSupervisor(release, environment);
     await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, release.releaseId, environment).endpointMetadataPath, release, 8_000);

package/dist/foundation/storage/control-store.d.ts

@@ -14,6 +14,7 @@ export interface StoredWorkspaceAgent {
     readonly agent: ManagedAgentDescriptor;
     readonly presentation: WorkspaceAgentPresentation;
 }
+/** Owns WAL-backed control persistence and reconciles prior-boot records before current use. */
 export declare class ControlStore {
     #private;
     readonly bootNonce: string | null;

package/dist/foundation/storage/control-store.js

@@ -6,6 +6,7 @@ import { assertManagedAgentDescriptor, assertRecoveryAuthority, assertTerminalSe
 import { assertLaunchInstance, assertLaunchInstanceOutcome, assertNativeProcessIdentity, assertProcessContainmentIdentity, } from "../lifecycle/index.js";
 export const DEFAULT_WORKSPACE_ID = "workspace-default";
 const INITIAL_WORKSPACE_ID = DEFAULT_WORKSPACE_ID;
+/** Owns WAL-backed control persistence and reconciles prior-boot records before current use. */
 export class ControlStore {
     bootNonce;
     database;

package/dist/foundation/structured-agent-runtime/backpressure.d.ts

@@ -33,6 +33,7 @@ export type StructuredBackpressureReleaseResult = {
     readonly code: "unknown-lease" | "invalid-request";
     readonly diagnostic: string;
 };
+/** Issues bounded resource leases and selects the negotiated backpressure action on exhaustion. */
 export declare class StructuredBackpressureController {
     #private;
     readonly adapterId: string;

package/dist/foundation/structured-agent-runtime/backpressure.js

@@ -1,4 +1,5 @@
 import { assertStructuredCapability, } from "../../contracts/workspace/index.js";
+/** Issues bounded resource leases and selects the negotiated backpressure action on exhaustion. */
 export class StructuredBackpressureController {
     adapterId;
     #budgets;

package/dist/foundation/structured-agent-runtime/commands.d.ts

@@ -38,6 +38,7 @@ export type StructuredCommandOutcomeResult = {
     readonly code: string;
     readonly diagnostic: string;
 };
+/** Tracks structured commands by correlation identity through one idempotent terminal outcome. */
 export declare class StructuredCommandTracker {
     #private;
     readonly agentId: string;

package/dist/foundation/structured-agent-runtime/commands.js

@@ -1,4 +1,5 @@
 import { assertStructuredCapability, assertWorkspaceCommand, } from "../../contracts/workspace/index.js";
+/** Tracks structured commands by correlation identity through one idempotent terminal outcome. */
 export class StructuredCommandTracker {
     agentId;
     #capability;

package/dist/foundation/structured-agent-runtime/reconnection.d.ts

@@ -30,6 +30,7 @@ export type StructuredReconnectionResult = {
     readonly code: string;
     readonly diagnostic: string;
 };
+/** Accepts a recovery boundary once after validating negotiated identity, proof, and protocol continuity. */
 export declare class StructuredReconnectionManager {
     #private;
     constructor(capability: StructuredCapabilityContract);

package/dist/foundation/structured-agent-runtime/reconnection.js

@@ -1,5 +1,6 @@
 import { WORKSPACE_CONTRACT_VERSION, assertRecoveryAuthority, assertStructuredAgentSnapshot, assertStructuredCapability, } from "../../contracts/workspace/index.js";
 import { StructuredEventReducer } from "./state.js";
+/** Accepts a recovery boundary once after validating negotiated identity, proof, and protocol continuity. */
 export class StructuredReconnectionManager {
     #capability;
     #acceptedBoundaries = new Set();

package/dist/foundation/structured-agent-runtime/state.d.ts

@@ -44,6 +44,7 @@ export type StructuredSnapshotApplyResult = {
     readonly code: string;
     readonly diagnostic: string;
 };
+/** Applies ordered structured events and snapshots while exposing gaps as explicit resynchronization. */
 export declare class StructuredEventReducer {
     #private;
     readonly agentId: string;

package/dist/foundation/structured-agent-runtime/state.js

@@ -1,4 +1,5 @@
 import { assertStructuredAgentSnapshot, assertStructuredCapability, assertWorkspaceEvent, } from "../../contracts/workspace/index.js";
+/** Applies ordered structured events and snapshots while exposing gaps as explicit resynchronization. */
 export class StructuredEventReducer {
     agentId;
     #capability;

package/dist/foundation/supervision/main.js

@@ -19,7 +19,7 @@ export async function runSupervisor() {
         throw new Error(PRODUCT_TEXT.diagnostic("supervisor must be launched from a verified immutable release"));
     const release = await readCertifiedReleaseManifest({ releaseRoot, releaseId, contentDigest }, resolve(paths.dataDir, "releases"));
     await assertImmutableExecutionRoot(release, paths.dataDir);
-    // One endpoint per cohort: a superseded cohort keeps serving what it already has while the
+    // Protocol: one endpoint per cohort: a superseded cohort keeps serving what it already has while the
     // installed release listens on its own address.
     paths = { ...productPaths, ...resolveCohortEndpoint(productPaths, release.releaseId) };
     const bootNonce = randomUUID();

package/dist/foundation/supervision/server.d.ts

@@ -2,6 +2,7 @@ import { type SupervisorSnapshot } from "../lifecycle/index.js";
 import { type MaterializedRelease } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
 import { type ProductPaths } from "./paths.js";
+/** Owns one release-cohort endpoint and the authenticated launch instances registered through it. */
 export declare class SupervisorServer {
     #private;
     readonly store: ControlStore;

package/dist/foundation/supervision/server.js

@@ -8,6 +8,7 @@ import { processIsAlive } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
 import { resolveProductPaths } from "./paths.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+/** Owns one release-cohort endpoint and the authenticated launch instances registered through it. */
 export class SupervisorServer {
     store;
     release;
@@ -90,10 +91,7 @@ export class SupervisorServer {
             this.#supersededPoll = poll;
         }
     }
-    /**
-     * Notices that another release has become the one new sessions start on. Nothing is
-     * interrupted by that: this cohort finishes what it is holding and then leaves.
-     */
+    // Invariant: superseding a cohort never interrupts its held instances; it retires only when empty.
     async #refreshCohortRole() {
         if (this.#closing || !this.readActiveReleaseId)
             return;
@@ -327,7 +325,7 @@ export class SupervisorServer {
         this.#uncertainInstances.delete(stored.id);
         this.#unbindOwner(stored.id, socket);
         this.#mutated();
-        // The last session on a superseded cohort has left; there is nothing here to keep.
+        // Invariant: the last session on a superseded cohort has left; there is nothing here to keep.
         if (this.#superseded && this.#instances.size === 0)
             void this.retire();
     }
@@ -421,7 +419,7 @@ export class SupervisorServer {
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             if (this.#instances.size === 0) {
-                // Let the terminal command result flush before closing owner sockets.
+                // Concurrency: allow the terminal command result to flush before closing owner sockets.
                 await new Promise(resolvePromise => setTimeout(resolvePromise, 25));
                 return this.#instances.size === 0;
             }

package/dist/integrations/pi/components/conformance.d.ts

@@ -10,6 +10,7 @@ export interface PiComponentConformanceReport {
     readonly componentResults: readonly PiComponentConformanceResult[];
     readonly componentFamilies: readonly string[];
 }
+/** Identifies the Pi presentation-conformance stage that failed against the pinned component surface. */
 export declare class PiComponentConformanceError extends Error {
     readonly stage: "theme" | "components";
     constructor(stage: "theme" | "components", cause: unknown);

package/dist/integrations/pi/components/conformance.js

@@ -5,6 +5,7 @@ import { AssistantMessageComponent, ExtensionSelectorComponent, initTheme, Login
 import { OWNED_UI_CONTRACT_VERSION } from "../../../contracts/owned-ui/index.js";
 import { createTuiFacade, validatedAssistantMessage } from "./shell-components.js";
 import { PRODUCT_IDENTITY } from "../../../product-identity.js";
+/** Identifies the Pi presentation-conformance stage that failed against the pinned component surface. */
 export class PiComponentConformanceError extends Error {
     stage;
     constructor(stage, cause) {

package/dist/integrations/pi/components/shell-footer-status.d.ts

@@ -2,6 +2,6 @@ import type { OwnedUiSessionViewModel } from "../../../contracts/owned-ui/index.
 import { type PiShellViewComponentPort, type PiShellStatusPort, type PiShellQueuedInputPort, type PiShellHeaderPort, type PiShellResourceEntry, type PiShellLoadedResourcesPort, type PiShellHeaderOptions, type PiShellEditorOptions } from "./shell-shared-facade.js";
 export declare function createPiShellHeader(options?: PiShellHeaderOptions): PiShellHeaderPort;
 export declare function createPiShellLoadedResources(resources: readonly PiShellResourceEntry[], initialExpanded?: boolean): PiShellLoadedResourcesPort;
-export declare function createPiShellStatus(view: OwnedUiSessionViewModel, runtime?: Pick<PiShellEditorOptions, "getColumns" | "getRows" | "requestRender">): PiShellStatusPort;
+export declare function createPiShellStatus(view: OwnedUiSessionViewModel, formatProgressStatus: (message: string) => string, runtime?: Pick<PiShellEditorOptions, "getColumns" | "getRows" | "requestRender">): PiShellStatusPort;
 export declare function createPiShellFooter(view: OwnedUiSessionViewModel, cwd: string): PiShellViewComponentPort;
 export declare function createPiQueuedInputStatus(submissions: readonly string[], presentation?: "pinned" | "custom-viewport"): PiShellQueuedInputPort;

package/dist/integrations/pi/components/shell-footer-status.js

@@ -67,12 +67,12 @@ export function createPiShellLoadedResources(resources, initialExpanded = false)
         invalidate() { },
     };
 }
-export function createPiShellStatus(view, runtime) {
+export function createPiShellStatus(view, formatProgressStatus, runtime) {
     ensureTheme();
     const statusUi = createTuiFacade(runtime ?? { getColumns: () => 80, getRows: () => 24, requestRender() { } });
     let workingOverride;
     let outputPad = PINNED_PI_LAYOUT.outputPad;
-    let component = statusComponent(view, statusUi, workingOverride, outputPad);
+    let component = statusComponent(view, statusUi, workingOverride, outputPad, formatProgressStatus);
     let signature = statusSignature(view, workingOverride, outputPad);
     const rebuild = () => {
         const nextSignature = statusSignature(view, workingOverride, outputPad);
@@ -81,7 +81,7 @@ export function createPiShellStatus(view, runtime) {
         if (component !== undefined && "dispose" in component && typeof component.dispose === "function")
             component.dispose();
         signature = nextSignature;
-        component = statusComponent(view, statusUi, workingOverride, outputPad);
+        component = statusComponent(view, statusUi, workingOverride, outputPad, formatProgressStatus);
     };
     return {
         render: width => component?.render(width) ?? [],
@@ -126,9 +126,10 @@ export function createPiQueuedInputStatus(submissions, presentation = "pinned")
         },
     };
 }
-function statusComponent(view, ui, workingOverride, outputPad) {
-    if (view.lifecycle === "busy")
-        return new WorkingStatusIndicator(ui, workingOverride ?? view.status.workingMessage ?? "Working...");
+function statusComponent(view, ui, workingOverride, outputPad, formatProgressStatus) {
+    if (view.lifecycle === "busy") {
+        return new WorkingStatusIndicator(ui, formatProgressStatus(workingOverride ?? view.status.workingMessage ?? "Working"));
+    }
     if (view.lifecycle === "failed") {
         return new Text(piTheme().fg("error", view.status.diagnostics.at(-1) ?? "Session failed"), outputPad, 0);
     }
@@ -149,7 +150,7 @@ function queuedInputText(submissions, presentation) {
     }
     const messages = submissions.map(submission => theme.fg("dim", `Steering: ${submission.replaceAll("\n", " ⏎ ")}`));
     const dequeueHint = theme.fg("dim", "↳ Alt+Up to edit all queued messages");
-    // The custom viewport matches Pi's interactive queue presentation while the
+    // Compatibility: the custom viewport matches Pi's interactive queue presentation while the
     // comparison shell remains byte-for-byte compatible with its pinned fixture.
     return ["", ...messages, dequeueHint].join("\n");
 }

package/dist/integrations/pi/components/shell-shared-facade.js

@@ -3,7 +3,7 @@ import { KeybindingsManager, } from "./upstream/adjacent/core/keybindings.js";
 import { ensurePiTheme, } from "./theme.js";
 /** Terminal-cell width authority used by Pi-rendered component rows. */
 export const piShellVisibleWidth = visibleWidth;
-// Pinned from packages/coding-agent/src/core/slash-commands.ts at 914cf14.
+// Provenance: pinned from packages/coding-agent/src/core/slash-commands.ts at 914cf14.
 export function createTuiFacade(options) {
     const children = [];
     const terminal = {

package/dist/integrations/pi/engine/adapter.d.ts

@@ -46,6 +46,11 @@ export interface PiTreeSelectorContext {
     readonly skipSummaryPrompt: boolean;
     readonly appendLabelChange: (entryId: string, label: string | undefined) => void;
 }
+export interface PiSessionResumeMetadata {
+    readonly sessionId: string;
+    readonly sessionDir: string;
+    readonly usesDefaultSessionDir: boolean;
+}
 export interface PiSessionSelectorContext {
     readonly currentSessionFilePath: string | undefined;
     readonly loadCurrentSessions: (onProgress?: (loaded: number, total: number) => void) => Promise<SessionInfo[]>;
@@ -116,6 +121,7 @@ export interface AdapterCommandResult {
     readonly outcome: OwnedUiCommandOutcome;
     readonly diagnostic: string | null;
 }
+/** Owns the pinned Pi session lifecycle and translates its events into the neutral agent-engine contract. */
 export declare class PiEngineAdapter {
     #private;
     constructor(options?: PiEngineAdapterOptions);
@@ -125,6 +131,7 @@ export declare class PiEngineAdapter {
     get agentDir(): string;
     resolveTranscriptImage(assetId: string): OwnedUiImageAttachment | null;
     currentSessionFile(): string | null;
+    currentSessionResumeMetadata(): PiSessionResumeMetadata | null;
     get disposed(): boolean;
     start(): Promise<OwnedUiSessionViewModel>;
     onEvent(listener: (event: OwnedUiEvent) => void): () => void;

package/dist/integrations/pi/engine/adapter.js

@@ -18,7 +18,7 @@ const execFileAsync = promisify(execFile);
  * that a streaming burst never holds input, large enough that an ordinary turn is one
  * batch.
  */
-// Deliver at most one engine event per event-loop turn. Transcript updates can
+// Performance: deliver at most one engine event per event-loop turn. Transcript updates can
 // be expensive in long sessions; a larger synchronous batch starves terminal
 // input and makes an in-progress mouse selection appear frozen.
 const EVENT_DELIVERY_BATCH = 1;
@@ -29,6 +29,7 @@ const DEFAULT_SURFACE = {
     focusedRegion: "editor",
     hardwareCursor: false,
 };
+/** Owns the pinned Pi session lifecycle and translates its events into the neutral agent-engine contract. */
 export class PiEngineAdapter {
     #runtimeFactory;
     #checkPackageUpdates;
@@ -92,7 +93,6 @@ export class PiEngineAdapter {
     #projectTrustPrompt;
     #settingsIntegration;
     #settingsIntegrationManager;
-    /** Lists the themes installed on this machine, when the caller supplies one. */
     #availableThemes;
     constructor(options = {}) {
         this.#cwd = options.cwd ?? process.cwd();
@@ -129,6 +129,22 @@ export class PiEngineAdapter {
         const value = this.#session?.sessionManager?.getSessionFile?.();
         return typeof value === "string" && value.length > 0 ? value : null;
     }
+    currentSessionResumeMetadata() {
+        const manager = this.#session?.sessionManager;
+        if (manager === undefined
+            || typeof manager.isPersisted !== "function"
+            || typeof manager.getSessionId !== "function"
+            || typeof manager.getSessionDir !== "function"
+            || typeof manager.usesDefaultSessionDir !== "function"
+            || manager.isPersisted() !== true
+            || this.currentSessionFile() === null)
+            return null;
+        const sessionId = manager.getSessionId();
+        const sessionDir = manager.getSessionDir();
+        if (!sessionId || !sessionDir)
+            return null;
+        return { sessionId, sessionDir, usesDefaultSessionDir: manager.usesDefaultSessionDir() };
+    }
     get disposed() {
         return this.#disposed;
     }
@@ -502,7 +518,7 @@ export class PiEngineAdapter {
                     } },
             });
             this.#settingsIntegration.bindOwner("startup", {
-                // Deferred application is the owner operation: the next preflight reads
+                // Invariant: deferred application is the owner operation: the next preflight reads
                 // the persisted default before constructing project-backed services.
                 defaultProjectTrust: { apply() { } },
                 collapseChangelog: { apply() { } },
@@ -541,7 +557,7 @@ export class PiEngineAdapter {
                 httpIdleTimeoutMs: { apply: value => {
                         if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
                             throw new TypeError("HTTP idle timeout is invalid");
-                        // Provider streaming reads the manager per request; global fetch uses
+                        // Invariant: provider streaming reads the manager per request; global fetch uses
                         // the matching owned dispatcher and zero maps to disabled semantics.
                         configureOwnedHttpDispatcher(value);
                         settings.setHttpIdleTimeoutMs(value);
@@ -1550,11 +1566,7 @@ export class PiEngineAdapter {
             this.#emitView();
         }
     }
-    /**
-     * Replaces the transcript and the index that finds a block by its identifier. Every
-     * lookup goes through the index, so streaming a chunk costs the same in a long session
-     * as in a new one.
-     */
+    // Performance: replacing the transcript rebuilds its index so block lookup stays constant-time.
     #setTranscript(blocks) {
         this.#transcript = blocks;
         this.#transcriptIndex.clear();
@@ -1571,7 +1583,7 @@ export class PiEngineAdapter {
         const index = this.#transcriptIndex.get(id);
         return index === undefined ? undefined : this.#transcript[index];
     }
-    /** Shows the state named by `kind`, which becomes the state a later end can clear. */
+    // Invariant: the named work state is the only state a matching end may clear.
     #enterWorkState(kind, message) {
         const wasBusy = this.#lifecycle === "busy";
         this.#statusKind = kind;
@@ -1581,21 +1593,16 @@ export class PiEngineAdapter {
             this.#emitEvent({ type: "session-lifecycle", lifecycle: "busy", reason: null });
         this.#emitEvent({ type: "status", status: this.#status });
     }
-    /**
-     * Ends one named state. A state the shell is not in is left alone, so a finished
-     * compaction or retry cannot clear the working state it never replaced. While the run
-     * continues, ending either of those returns to working rather than to idle.
-     */
+    // Invariant: ending retry or compaction cannot clear a different active work state.
     #endWorkState(kind) {
         if (this.#statusKind !== kind)
             return;
         if (this.#agentRunActive) {
-            this.#enterWorkState("working", "Working...");
+            this.#enterWorkState("working", "Working");
             return;
         }
         this.#leaveWorkStates();
     }
-    /** Leaves every work state and reports the session idle. */
     #leaveWorkStates() {
         this.#statusKind = null;
         this.#lifecycle = "ready";
@@ -1606,7 +1613,7 @@ export class PiEngineAdapter {
     #handlePiEvent(event) {
         if (!isRecord(event) || typeof event.type !== "string")
             return;
-        // Usage moves at message and lifecycle boundaries, not with stream chunks, so the
+        // Invariant: usage moves at message and lifecycle boundaries, not with stream chunks, so the
         // two streaming event kinds keep the memo and everything else drops it.
         if (event.type !== "message_update" && event.type !== "tool_execution_update")
             this.#usageCache = undefined;
@@ -1614,7 +1621,7 @@ export class PiEngineAdapter {
             case "agent_start":
                 this.#agentRunActive = true;
                 this.#emitEvent({ type: "agent-run-started" });
-                this.#enterWorkState("working", "Working...");
+                this.#enterWorkState("working", "Working");
                 return;
             case "message_start":
                 this.#upsertMessageBlock(event.message, "live");
@@ -1623,7 +1630,7 @@ export class PiEngineAdapter {
                 const delta = isRecord(event.assistantMessageEvent) && typeof event.assistantMessageEvent.delta === "string"
                     ? event.assistantMessageEvent.delta
                     : undefined;
-                // The delta is folded in before the block is stored, so a chunk is one update to
+                // Invariant: the delta is folded in before the block is stored, so a chunk is one update to
                 // one block rather than a store without the delta followed by a store with it.
                 const blocks = this.#messageBlocks(event.message, "live", this.#transcript.length);
                 for (const [index, block] of blocks.entries()) {
@@ -1635,7 +1642,7 @@ export class PiEngineAdapter {
             }
             case "message_end":
                 this.#upsertMessageBlock(event.message, "finalized");
-                // Preserve the same semantic boundary v2 counted. Transcript block
+                // Compatibility: preserve the same semantic boundary v2 counted. Transcript block
                 // finalization is intentionally not a substitute: rebuilds, retries,
                 // thinking parts, and tool rows can all finalize independently.
                 if (isRecord(event.message) && event.message.role === "assistant") {
@@ -1651,7 +1658,7 @@ export class PiEngineAdapter {
                 return;
             case "tool_execution_start":
             case "tool_execution_end": {
-                // The end supersedes any update still waiting on the coalescing timer.
+                // Concurrency: the end supersedes any update still waiting on the coalescing timer.
                 const toolCallId = stringValue(event.toolCallId);
                 if (toolCallId !== undefined)
                     this.#pendingToolUpdates.delete(toolCallId);
@@ -1672,7 +1679,7 @@ export class PiEngineAdapter {
                     this.#rebuildTranscript(finalMessages, "finalized");
                 else
                     this.#setTranscript(this.#transcript.map(block => block.status === "live" ? { ...block, status: "finalized" } : block));
-                // Ending a turn leaves the working state, as the recorded pinned baseline does, but
+                // Compatibility: ending a turn leaves the working state, as the recorded pinned baseline does, but
                 // it leaves only that state: a compaction or retry being shown outlives the turn
                 // that ended under it. Settlement ends the run, and with it every state — the
                 // engine ends a turn for each continuation it makes and settles once.
@@ -1698,13 +1705,13 @@ export class PiEngineAdapter {
                 return;
             }
             case "auto_retry_start":
-                this.#enterWorkState("retry", "Retrying…");
+                this.#enterWorkState("retry", "Retrying");
                 return;
             case "auto_retry_end":
                 this.#endWorkState("retry");
                 return;
             case "compaction_start":
-                this.#enterWorkState("compaction", "Compacting…");
+                this.#enterWorkState("compaction", "Compacting");
                 return;
             case "compaction_end":
                 this.#endWorkState("compaction");
@@ -1797,7 +1804,7 @@ export class PiEngineAdapter {
                 }
             }
         }
-        // An authoritative rebuild restates most of what is already there. Reusing the block
+        // Performance: an authoritative rebuild restates most of what is already there. Reusing the block
         // that already says it keeps its revision, and with it the rows the shell rendered for
         // it — otherwise every turn that ends re-renders the whole session.
         this.#setTranscript(blocks.map(block => {
@@ -1976,12 +1983,7 @@ export class PiEngineAdapter {
         }
         return references;
     }
-    /**
-     * A busy tool streams far more output chunks than a terminal frame can show, and every
-     * chunk restates the whole accumulated output. Keeping only the newest chunk per tool
-     * and applying it on a short timer bounds the per-command work by frames rather than
-     * by chunks, which is what keeps typed input and the spinner alive under the stream.
-     */
+    // Performance: coalescing each tool to its newest chunk bounds work by frames, not stream events.
     #coalesceToolExecutionUpdate(event) {
         const toolCallId = stringValue(event.toolCallId);
         if (!toolCallId)
@@ -2024,7 +2026,7 @@ export class PiEngineAdapter {
                 toolCallId,
                 toolName: stringValue(event.toolName) ?? "unknown",
                 arguments: jsonSummary(event.args),
-                // A partial result repeats the whole accumulated output on every chunk;
+                // Performance: a partial result repeats the whole accumulated output on every chunk;
                 // summarizing it each time would cost quadratic work over the stream.
                 result: ended ? jsonSummary(source) : { summary: "", json: null },
                 partialResult: event.type === "tool_execution_update",
@@ -2037,7 +2039,7 @@ export class PiEngineAdapter {
         const index = this.#transcriptIndex.get(block.id);
         if (index !== undefined) {
             const existing = this.#transcript[index];
-            // Nothing to tell the shell about a block that repeats itself, and keeping the
+            // Performance: nothing is emitted for a block that repeats itself, and keeping the
             // revision keeps the rows it already rendered.
             if (existing !== undefined && sameBlockContent(existing, block))
                 return;
@@ -2154,7 +2156,7 @@ export class PiEngineAdapter {
                     }
                 }
                 deliveredSinceYield += 1;
-                // A microtask chain runs to exhaustion before the loop turns, so a streaming
+                // Concurrency: a microtask chain runs to exhaustion before the loop turns, so a streaming
                 // burst would hold typed input, pointer reports, and timed indicators until it
                 // drained. Yielding on a macrotask hands those their turn between batches.
                 if (deliveredSinceYield >= EVENT_DELIVERY_BATCH && this.#eventQueue.length > 0) {

package/dist/integrations/pi/engine/conformance.d.ts

@@ -13,6 +13,7 @@ export declare const REQUIRED_PI_CAPABILITY_OPERATIONS: Readonly<{
     readonly workflows: readonly ["workflow.route", "workflow.validate", "workflow.diagnostics"];
     readonly disposal: readonly ["subscription.dispose", "session.dispose", "services.cleanup"];
 }>;
+/** Identifies one required Pi capability operation that differs from the accepted integration contract. */
 export declare class PiCapabilityCompatibilityError extends Error {
     readonly packageVersion: string;
     readonly capability: string;
@@ -29,6 +30,7 @@ export interface PiUpgradeConformanceReport {
     readonly commandSurface: readonly string[];
     readonly capabilities: readonly PiCapabilityConformanceResult[];
 }
+/** Identifies the public Pi SDK stage that failed during upgrade conformance. */
 export declare class PiUpgradeConformanceError extends Error {
     readonly stage: "exports" | "services" | "session";
     constructor(stage: "exports" | "services" | "session", cause: unknown);

package/dist/integrations/pi/engine/conformance.js

@@ -14,6 +14,7 @@ export const REQUIRED_PI_CAPABILITY_OPERATIONS = Object.freeze({
     workflows: ["workflow.route", "workflow.validate", "workflow.diagnostics"],
     disposal: ["subscription.dispose", "session.dispose", "services.cleanup"],
 });
+/** Identifies one required Pi capability operation that differs from the accepted integration contract. */
 export class PiCapabilityCompatibilityError extends Error {
     packageVersion;
     capability;
@@ -26,6 +27,7 @@ export class PiCapabilityCompatibilityError extends Error {
         this.name = "PiCapabilityCompatibilityError";
     }
 }
+/** Identifies the public Pi SDK stage that failed during upgrade conformance. */
 export class PiUpgradeConformanceError extends Error {
     stage;
     constructor(stage, cause) {

package/dist/integrations/pi/engine/http-dispatcher.js

@@ -1,4 +1,4 @@
-// Mechanically adapted from Pi commit 914cf14
+// Provenance: mechanically adapted from Pi commit 914cf14
 // packages/coding-agent/src/core/http-dispatcher.ts (MIT).
 // Local modifications: expose only A1's owned timeout seam and retain no private Pi imports.
 import { EnvHttpProxyAgent, install, setGlobalDispatcher } from "undici";

package/dist/integrations/pi/engine/model-auth-integration.d.ts

@@ -9,6 +9,7 @@ export interface PiModelAuthenticationOptions {
     readonly timeoutMs?: number;
     readonly scopedModelIds?: () => readonly string[] | undefined;
 }
+/** Adapts the pinned model runtime to neutral model selection and authentication operations. */
 export declare class PiModelAuthenticationIntegration implements AgentModelPort, AgentAuthenticationPort {
     #private;
     private readonly options;