@atomic-chat/core 0.5.1 → 0.13.2

package/dist/config/paths.js

@@ -6,20 +6,60 @@
  *   <data>/llamacpp/lib/                                                        (turboquant cudart)
  *   <data>/llamacpp-upstream/backends/<version>/<backend>/build/bin/llama-server
  *   <data>/llamacpp-upstream/tmp/
+ *   <data>/atomic-prism/backends/<version>/<backend>/build/bin/llama-server  (PrismML llama.cpp, Bonsai)
+ *   <data>/atomic-prism/tmp/
+ *   <data>/atomic-core/prism-setups/<operation id>.json  (Bonsai setup operations)
  *   <data>/mlx/models/<id>/{model.yml, config.json, *.safetensors}
  *   <data>/diffusion/{backends/<tag>/<backend>/, models/, scratch/}, <data>/images/  (image generation; the app's paths since v2.0.38)
  *   <data>/videos/  (video generation; the folder the app's ADR of 2026-09-10 reserved)
  *   <data>/local-api-server.json, <data>/atomic-chatgpt-auth.json
  *   <data>/remote-access-tunnel.json  (the app's 2.0.40 tunnel journal: reaped once at startup, never written)
  *   <data>/atomic-core/  — the only new folder (settings, credentials, lock, journal, logs)
+ *   <dataDir>/atomic-managed-runtimes/{environment.json, environment.lock, installations/, operations/,
+ *                                       descriptors/<descriptor_id>.json, descriptors/latest.json,
+ *                                       environment-manifests/<manifest_id>.json, environment-manifests/latest.json}
+ *                                                        (managed text runtimes, shared by the app and CLI scopes)
+ *   <data>/atomic-core/managed-runtimes/executions/  (task 2.10 execution journal: this scope's own
+ *                                                      model containers, one file per container id)
+ *   <data>/atomic-core/managed-runtimes/{heartbeats/<generation>/, caches/<descriptor_id>/<model id>/,
+ *                                        docker-config/, watchdog/atomic-watchdog-entrypoint.sh}
+ *                                                     (task 2.12: the managed-text load lifecycle)
  */
 import { join, relative, sep } from 'node:path';
+import { AtomicCoreError } from '../contracts/index.js';
+import { dataDir } from './data-folder.js';
 /** Subfolder holding the shared GGUF tree: `<data>/llamacpp/models`. Not the provider id. */
 export const MODELS_ROOT = 'llamacpp';
+/** The managed engines' one model store under `<data>` (change `add-vllm-runtime`, design D4). */
+export const MANAGED_MODELS_DIR = 'managed-models';
 export const CORE_DIR = 'atomic-core';
 export const MODEL_YML = 'model.yml';
 export const LOCAL_API_SERVER_STATE_FILE = 'local-api-server.json';
 export const CHATGPT_AUTH_FILE = 'atomic-chatgpt-auth.json';
+/** Per-scope subtree under `<data>/atomic-core/` for the managed text runtimes (task 2.10). */
+export const MANAGED_SCOPE_DIR = 'managed-runtimes';
+function managedScopePaths(coreDir) {
+    const root = join(coreDir, MANAGED_SCOPE_DIR);
+    const executionsDir = join(root, 'executions');
+    const heartbeatsDir = join(root, 'heartbeats');
+    const cachesDir = join(root, 'caches');
+    const descriptorCachesDir = (descriptorId) => join(cachesDir, encodeManagedId(descriptorId));
+    return {
+        root,
+        executionsDir,
+        executionFile: (containerId) => join(executionsDir, `${containerId}.json`),
+        heartbeatsDir,
+        heartbeatDir: (generation) => join(heartbeatsDir, encodeManagedId(generation)),
+        cachesDir,
+        descriptorCachesDir,
+        engineCacheDir: (descriptorId, modelId) => join(descriptorCachesDir(descriptorId), encodeManagedId(modelId)),
+        dockerConfigDir: join(root, 'docker-config'),
+        // `WATCHDOG_SCRIPT_FILENAME` in `runtime/container/watchdog.ts`; spelled here because `config/`
+        // never imports a runtime module.
+        watchdogScript: join(root, 'watchdog', 'atomic-watchdog-entrypoint.sh'),
+        guestScopeFile: join(root, 'guest-scope.json'),
+    };
+}
 export function dataLayout(root) {
     const coreDir = join(root, CORE_DIR);
     const diffusionDir = join(root, 'diffusion');
@@ -28,6 +68,9 @@ export function dataLayout(root) {
         serverStateFile: join(root, LOCAL_API_SERVER_STATE_FILE),
         chatgptAuthFile: join(root, CHATGPT_AUTH_FILE),
         legacyRemoteAccessTunnel: join(root, 'remote-access-tunnel.json'),
+        managed: managedScopePaths(coreDir),
+        managedModelsDir: join(root, MANAGED_MODELS_DIR),
+        legacyTensorrtLlmModelsDir: join(root, 'tensorrt-llm', 'models'),
         core: {
             dir: coreDir,
             publicServerState: join(coreDir, LOCAL_API_SERVER_STATE_FILE),
@@ -43,6 +86,7 @@ export function dataLayout(root) {
             cloudflaredEmptyConfig: join(coreDir, 'cloudflared-empty.yml'),
             /** The core's own error-reporting state: the user's stored choice, the install id. */
             telemetry: join(coreDir, 'telemetry.json'),
+            prismSetupsDir: join(coreDir, 'prism-setups'),
         },
         diffusion: {
             root: diffusionDir,
@@ -64,12 +108,24 @@ export function dataLayout(root) {
                         modelsDir: join(root, MODELS_ROOT, 'models'),
                     };
                 case 'llamacpp-upstream':
+                case 'atomic-prism':
                     return {
                         root: providerRoot,
                         backendsDir: join(providerRoot, 'backends'),
                         tmpDir: join(providerRoot, 'tmp'),
                         modelsDir: join(root, MODELS_ROOT, 'models'),
                     };
+                // A managed engine's models are the store's (`<data>/managed-models/<id>/`): a Hugging Face
+                // checkpoint directory plus `model.yml`, written by the app and the CLI, read by core (spec
+                // `managed-model-store`), and the same folder for every managed engine.
+                case 'tensorrt-llm':
+                case 'vllm':
+                    return {
+                        root: providerRoot,
+                        backendsDir: join(providerRoot, 'backends'),
+                        tmpDir: join(providerRoot, 'tmp'),
+                        modelsDir: join(root, MANAGED_MODELS_DIR),
+                    };
                 case 'mlx':
                 case 'foundation-models':
                     return {
@@ -106,4 +162,111 @@ export function modelDirFromId(modelsDir, modelId) {
 export function resolveDataRelative(root, path, isAbsolute) {
     return isAbsolute(path) ? path : join(root, path);
 }
+// ── Managed text runtimes ────────────────────────────────────────────────────────────────────────
+/**
+ * The container environment a managed text runtime (e.g. TensorRT-LLM) runs in — the Docker engine
+ * on Linux, or the Docker inside the WSL distribution the core owns on Windows — belongs to the
+ * machine's user account, not to a data folder. Both the app scope and the CLI scope drive the same
+ * one, so its record lives at a fixed per-user location and survives a data-folder move untouched:
+ * duplicating it per scope would mean two copies of a multi-gigabyte image for one user.
+ *
+ * Only that shared half is laid out here (openspec change `add-tensorrt-llm-linux`, task 2.2, design
+ * D12): core neither downloads model weights nor keeps a per-scope artifact/cache store for them —
+ * that stays the app's and the CLI's job, so there is no per-scope managed subtree to add yet.
+ */
+/** Overrides the shared per-user root. Tests and e2e set it so they never touch a real machine. */
+export const MANAGED_ROOT_ENV = 'ATOMIC_CORE_MANAGED_ROOT';
+/** Shared per-user root under `dataDir`, beside the app's own folders. */
+export const MANAGED_SHARED_DIR = 'atomic-managed-runtimes';
+const UNRESERVED = /^[A-Za-z0-9._-]$/;
+/** Names Windows refuses whatever the extension follows them: `CON`, `nul.json`, `LPT1.txt`. */
+const WINDOWS_DEVICE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+const percent = (byte) => `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+/**
+ * One identifier as one directory name. Managed ids are opaque values that may hold anything an
+ * operation or effect id does — `/`, `:`, spaces, any script — so they are never spelled onto disk
+ * raw. Every byte outside `[A-Za-z0-9._-]` becomes `%XX` of its UTF-8 encoding, which keeps the
+ * common case readable, keeps the result a single path segment, and is reversible because `%` itself
+ * is always encoded.
+ *
+ * The three shapes that are legal characters but illegal names are escaped too: `.` and `..`, a
+ * trailing dot, and the Windows device names.
+ *
+ * The result is therefore always exactly one path segment — it holds no separator and is never `.`
+ * or `..` — which is what lets every builder below join it onto a root without re-checking. That
+ * invariant is asserted directly in `paths.test.ts`; loosening the character set breaks it.
+ */
+export function encodeManagedId(id) {
+    if (id === '')
+        throw new AtomicCoreError('INVALID_ARGUMENT', 'A managed id cannot be empty.');
+    let out = '';
+    for (const byte of encoder.encode(id)) {
+        const ch = String.fromCharCode(byte);
+        out += UNRESERVED.test(ch) ? ch : percent(byte);
+    }
+    if (/^\.+$/.test(out))
+        return out.replace(/\./g, '%2E');
+    out = out.replace(/\.+$/, (run) => '%2E'.repeat(run.length));
+    if (WINDOWS_DEVICE.test(out))
+        out = percent(out.charCodeAt(0)) + out.slice(1);
+    return out;
+}
+/** The inverse of `encodeManagedId`, for reading an id back off a directory listing. */
+export function decodeManagedId(segment) {
+    const bytes = [];
+    for (let i = 0; i < segment.length; i += 1) {
+        const ch = segment[i];
+        if (ch !== '%') {
+            bytes.push(ch.charCodeAt(0));
+            continue;
+        }
+        const hex = segment.slice(i + 1, i + 3);
+        if (!/^[0-9A-Fa-f]{2}$/.test(hex)) {
+            throw new AtomicCoreError('INVALID_ARGUMENT', `Not an encoded managed id: ${segment}`);
+        }
+        bytes.push(Number.parseInt(hex, 16));
+        i += 2;
+    }
+    try {
+        return decoder.decode(new Uint8Array(bytes));
+    }
+    catch {
+        throw new AtomicCoreError('INVALID_ARGUMENT', `Not an encoded managed id: ${segment}`);
+    }
+}
+export function managedSharedPaths(root) {
+    const installationsDir = join(root, 'installations');
+    const operationsDir = join(root, 'operations');
+    const descriptorsDir = join(root, 'descriptors');
+    const environmentManifestsDir = join(root, 'environment-manifests');
+    return {
+        root,
+        environmentFile: join(root, 'environment.json'),
+        lockFile: join(root, 'environment.lock'),
+        descriptorsDir,
+        installationsDir,
+        operationsDir,
+        installationFile: (installationId) => join(installationsDir, encodeManagedId(installationId), 'installation.json'),
+        operationFile: (operationId) => join(operationsDir, `${encodeManagedId(operationId)}.json`),
+        descriptorFile: (descriptorId) => join(descriptorsDir, `${encodeManagedId(descriptorId)}.json`),
+        descriptorLatestFile: join(descriptorsDir, 'latest.json'),
+        descriptorLatestFileFor: (engineId) => join(descriptorsDir, `latest-${encodeManagedId(engineId)}.json`),
+        environmentManifestsDir,
+        environmentManifestFile: (manifestId) => join(environmentManifestsDir, `${encodeManagedId(manifestId)}.json`),
+        environmentManifestLatestFile: join(environmentManifestsDir, 'latest.json'),
+    };
+}
+/**
+ * The shared root: the env override, else a fixed folder under `dataDir`. Deliberately not derived
+ * from `<data>` — the environment is the user's, and moving the data folder must not strand the
+ * containers, nor make the CLI scope install its own copy of the same image.
+ */
+export function managedSharedRoot(e) {
+    const override = e.env[MANAGED_ROOT_ENV];
+    if (override !== undefined && override.trim() !== '')
+        return override;
+    return join(dataDir(e), MANAGED_SHARED_DIR);
+}
 //# sourceMappingURL=paths.js.map

package/dist/config/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/config/paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/config/paths.ts"],"names":[],"mappings":"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"}

package/dist/contracts/backend-advisor.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Backend advisor contracts: the shapes `backend/` shares with the app (moved here from
+ * `backend/types.ts` so `client/` can import them without pulling `node:fs`), and the wire envelopes
+ * of the three advisor routes (`POST /backends/:provider/{catalog,recommendation,updates}`, see the
+ * 2026-09-27 ADR "the core advises on backends, the app decides").
+ *
+ * Envelopes are snake_case like every other control-API body. The optimal record itself stays
+ * camelCase: the app persists it verbatim under its `localStorage` key and an older app must still
+ * read what a newer core wrote.
+ *
+ * Browser-safe: types only.
+ */
+/** The llama.cpp providers the advisor answers for. */
+export type LlamacppProviderId = 'llamacpp-upstream' | 'llamacpp' | 'atomic-prism';
+/**
+ * One backend build. Rust `BackendInfo { version, backend, #[serde(default)] order: u32 }`: `order`
+ * is the directory mtime in seconds for a build found on disk and 0 (or absent) for a manifest entry.
+ */
+export interface BackendVersion {
+    version: string;
+    backend: string;
+    order?: number;
+}
+/**
+ * Rust `SystemFeatures` (input of `determine_supported_backends`) and the guest-js
+ * `BackendFeatures`. `cuda11` is accepted for wire compatibility but never expands into a backend.
+ */
+export interface BackendFeatures {
+    cuda11: boolean;
+    cuda12: boolean;
+    cuda13: boolean;
+    vulkan: boolean;
+    rocm: boolean;
+    /** Windows on ARM with a Qualcomm Adreno GPU: the `win-opencl-adreno-arm64` build can run. */
+    opencl?: boolean;
+}
+/** Rust `SupportedFeatures` (output of `get_supported_features`). */
+export interface SupportedFeatures extends BackendFeatures {
+    avx: boolean;
+    avx2: boolean;
+    avx512: boolean;
+}
+/** Rust `UpdateCheckResult`; `target_backend` serialises as `null` when no update is offered. */
+export interface UpdateCheckResult {
+    update_needed: boolean;
+    new_version: string;
+    target_backend: string | null;
+}
+/**
+ * Outcome of `detectIdealBackendType` (ATO-161): a better GPU backend exists, CPU genuinely is the
+ * best this hardware can do, or detection could not complete and the current backend must stay.
+ */
+export type IdealBackendResult = {
+    kind: 'gpu';
+    backend: string;
+} | {
+    kind: 'cpu-optimal';
+} | {
+    kind: 'detection-failed';
+};
+export interface OptimalBackendCacheBase {
+    schemaVersion: 1;
+    provider: LlamacppProviderId;
+    detectedAt: number;
+    currentBackend: string;
+    recommendedCategory: string;
+}
+/** Persisted under `OPTIMAL_BACKEND_CACHE_KEY` (app: `localStorage`; core: `<data>/atomic-core/`). */
+export type OptimalBackendCacheRecord = (OptimalBackendCacheBase & {
+    detectionKind: 'gpu';
+    idealBackendId: string;
+    recommendedBackend?: string;
+}) | (OptimalBackendCacheBase & {
+    detectionKind: 'cpu-optimal';
+});
+/** Payload of `AppEvent.onBetterBackendDetected` and of `llama_cpp_better_backend_recommendation`. */
+export interface BackendRecommendation {
+    currentBackend: string;
+    recommendedBackend: string;
+    recommendedCategory: string;
+    provider: string;
+    version: string;
+    backendId: string;
+}
+/**
+ * The app's proxy policy for one network operation (Rust `ProxyConfig` of `download_files`). Sent
+ * in request bodies, never persisted by the core and never echoed back. `downloads/` re-exports it;
+ * `validateProxyConfig` there holds the rules.
+ */
+export interface ProxyConfig {
+    url: string;
+    username?: string | null;
+    password?: string | null;
+    no_proxy?: string[] | null;
+    ignore_ssl?: boolean | null;
+}
+export interface BackendCatalogRequest {
+    /** Drop the session cache (upstream manifest / fork release index) before answering. */
+    force?: boolean;
+    /** The app's version, for the fork's `min_app_version` gate; `null` or absent = any. */
+    app_version?: string | null;
+    /** The provider's `version_backend`; only the macOS static variants depend on it. */
+    current_backend?: string;
+    proxy?: ProxyConfig | null;
+}
+/** One release of the TurboQuant fork or of PrismML, for the dropdown's release notes. */
+export interface BackendCatalogRelease {
+    tag: string;
+    title?: string;
+    highlights?: string[];
+    min_app_version?: string;
+    /** PrismML: the release page and the one-line note the update banner shows. */
+    notes_url?: string;
+    notes?: string;
+    /** PrismML: present when the release was pulled; its packs are never offered. */
+    withdrawn?: {
+        reason: string;
+    };
+    variants: Array<{
+        id: string;
+        asset?: string;
+        size?: number;
+        validation?: 'candidate' | 'approved';
+    }>;
+}
+/** Where the remote half of the catalog came from. */
+export type BackendCatalogSource = 'live' | 'session-cache' | 'bundled-baseline' | 'index' | 'redirect' | 'legacy-manifest' | 'disk-cache' | 'none';
+export interface BackendCatalogResponse {
+    provider: LlamacppProviderId;
+    os_type: string;
+    arch_suffix: 'x64' | 'arm64';
+    /** `probe` or `override`: which hardware description gated the catalog. */
+    hardware_source: string;
+    features: SupportedFeatures;
+    /** Backend ids this host can run (`determine_supported_backends`). */
+    supported_backends: string[];
+    /** The remote catalog for this OS + arch, before the hardware gate. */
+    remote: BackendVersion[];
+    /** Every pack on disk, `order` = install mtime. */
+    installed: BackendVersion[];
+    /** Remote + installed, hardware-gated, merged and sorted newest first. */
+    available: BackendVersion[];
+    /** `determineBestBackend(available)`, `null` for an empty catalog. */
+    recommended: string | null;
+    /** The best *installed* build among `available` — the app's disk-recovery pick. */
+    recommended_installed: string | null;
+    /** Newest `<tag>/<id>` per normalised backend type present in `available`. */
+    latest_by_type: Record<string, string>;
+    /** Ids behind the static "Latest <variant>" dropdown entries (upstream only; fork `[]`). */
+    static_variants: string[];
+    source: BackendCatalogSource;
+    /** Fork and PrismML: the releases with their notes. */
+    releases?: BackendCatalogRelease[];
+}
+export type BackendRecommendationMode = 'refresh' | 'recheck';
+export interface BackendRecommendationRequest {
+    /** `refresh`: the silent startup pass. `recheck`: the user asked; forces a catalog refresh and emits. */
+    mode: BackendRecommendationMode;
+    current_backend?: string;
+    app_version?: string | null;
+    proxy?: ProxyConfig | null;
+    /** Defaults to `mode === 'recheck'`. */
+    force?: boolean;
+    /** The host already knows it has no GPU: skip detection and record `cpu-optimal`. */
+    assume_no_gpu?: boolean;
+}
+/**
+ * Why the recommendation did or did not surface. `detection_failed` is an ordinary outcome, not an
+ * error: the store is left untouched and the app keeps its current backend.
+ */
+export type BackendRecommendationOutcome = 'mac' | 'detection_failed' | 'cpu_optimal' | 'already_optimal' | 'no_catalog_entry' | 'recommend';
+export interface BackendRecommendationResponse {
+    provider: LlamacppProviderId;
+    mode: BackendRecommendationMode;
+    outcome: BackendRecommendationOutcome;
+    /** What detection concluded; `null` on macOS. */
+    detection: IdealBackendResult | null;
+    /** The record this pass built; `null` when nothing was built (macOS, detection failed). */
+    record: OptimalBackendCacheRecord | null;
+    /** The store after this pass: its revision and what it holds now. */
+    revision: number;
+    optimal: OptimalBackendCacheRecord | null;
+    /** Non-null only for `outcome: 'recommend'`. */
+    recommendation: BackendRecommendation | null;
+    elapsed_ms: number;
+}
+export interface BackendUpdateCheckRequest {
+    /** The provider's `version_backend`; defaults to what the core's settings hold. */
+    current?: string;
+    force?: boolean;
+    app_version?: string | null;
+    proxy?: ProxyConfig | null;
+    /**
+     * PrismML only: the build a model the user wants needs (`engine_update_required`). An update that
+     * reaches it is reported with `reason: 'model_requires'`.
+     */
+    requires_build?: number;
+}
+/**
+ * PrismML only: why an update is offered. `newer`: an approved newer build; `withdrawn`: the current
+ * release was pulled; `model_requires`: a model the user wants needs a newer build.
+ */
+export type BackendUpdateReason = 'newer' | 'withdrawn' | 'model_requires';
+/** What `current` looked like: a `<tag>/<id>`, a parked `latest/<id>` sentinel, or nothing usable. */
+export type BackendCurrentKind = 'concrete' | 'sentinel' | 'missing';
+export interface BackendUpdateCheckResponse extends UpdateCheckResult {
+    provider: LlamacppProviderId;
+    current: string;
+    current_kind: BackendCurrentKind;
+    /** Whether `target_backend` stays in the current backend's family (a tag bump never switches types). */
+    same_family: boolean;
+    /** The target the app may offer: `target_backend` when an update is needed and the family holds. */
+    offer: string | null;
+    /** PrismML only, set with an offer. */
+    reason?: BackendUpdateReason;
+    /** PrismML only: the target release's page and banner note. */
+    notes_url?: string;
+    notes?: string;
+    /** PrismML only: bytes to download for the target (the pack plus its companion). */
+    download_size?: number;
+    /** PrismML only: present when the current release was withdrawn, offer or not. */
+    current_withdrawn?: {
+        reason: string;
+    };
+}

package/dist/contracts/backend-advisor.js

@@ -0,0 +1,14 @@
+/**
+ * Backend advisor contracts: the shapes `backend/` shares with the app (moved here from
+ * `backend/types.ts` so `client/` can import them without pulling `node:fs`), and the wire envelopes
+ * of the three advisor routes (`POST /backends/:provider/{catalog,recommendation,updates}`, see the
+ * 2026-09-27 ADR "the core advises on backends, the app decides").
+ *
+ * Envelopes are snake_case like every other control-API body. The optimal record itself stays
+ * camelCase: the app persists it verbatim under its `localStorage` key and an older app must still
+ * read what a newer core wrote.
+ *
+ * Browser-safe: types only.
+ */
+export {};
+//# sourceMappingURL=backend-advisor.js.map

package/dist/contracts/backend-advisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-advisor.js","sourceRoot":"","sources":["../../src/contracts/backend-advisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/contracts/control-api.d.ts

@@ -3,7 +3,13 @@
  */
 import type { ErrorBody } from './errors.js';
 export declare const CONTROL_API_PREFIX = "/atomic/v1";
-export declare const CONTROL_PROTOCOL_VERSION = 1;
+/**
+ * The wire contract's version. Bumped to 2 when a session stopped having to be a process on this
+ * machine: `SessionInfo.pid` became nullable, so a core that reports a container session would hand
+ * an app built against version 1 a field it cannot deserialize, and that app would quietly drop the
+ * session rather than fail. The protocol check is what turns that into a refusal to attach.
+ */
+export declare const CONTROL_PROTOCOL_VERSION = 2;
 /**
  * The core's first and only stdout line, printed by `daemon` once the control listener is bound
  * (PLAN.md §3.6). It describes *control* readiness only: the public `/v1` listener is separate and

package/dist/contracts/control-api.js

@@ -2,6 +2,12 @@
  * Control API (`/atomic/v1/*`) shapes and the sidecar handshake. PLAN.md §3.6.
  */
 export const CONTROL_API_PREFIX = '/atomic/v1';
-export const CONTROL_PROTOCOL_VERSION = 1;
+/**
+ * The wire contract's version. Bumped to 2 when a session stopped having to be a process on this
+ * machine: `SessionInfo.pid` became nullable, so a core that reports a container session would hand
+ * an app built against version 1 a field it cannot deserialize, and that app would quietly drop the
+ * session rather than fail. The protocol check is what turns that into a refusal to attach.
+ */
+export const CONTROL_PROTOCOL_VERSION = 2;
 export const LOCAL_API_SERVER_STATE_FILE = 'local-api-server.json';
 //# sourceMappingURL=control-api.js.map

package/dist/contracts/control-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-api.js","sourceRoot":"","sources":["../../src/contracts/control-api.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAA;AAC9C,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAA;AAuCzC,MAAM,CAAC,MAAM,2BAA2B,GAAG,uBAAuB,CAAA"}
+{"version":3,"file":"control-api.js","sourceRoot":"","sources":["../../src/contracts/control-api.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAA;AAC9C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAA;AAuCzC,MAAM,CAAC,MAAM,2BAA2B,GAAG,uBAAuB,CAAA"}