@timurproko/a1 0.2.7-dev.1245 → 0.2.7-dev.1252

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

@@ -1,27 +0,0 @@
-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)
-            throw new TypeError("inspected PID must be a positive safe integer");
-        let stat;
-        try {
-            stat = await readFile(`/proc/${pid}/stat`, "utf8");
-        }
-        catch (error) {
-            if (error instanceof Error && "code" in error && error.code === "ENOENT")
-                return null;
-            throw error;
-        }
-        const commandEnd = stat.lastIndexOf(")");
-        const fields = commandEnd >= 0 ? stat.slice(commandEnd + 1).trim().split(/\s+/) : [];
-        const startTicks = fields[19];
-        if (!startTicks || !/^\d+$/.test(startTicks))
-            throw new Error("process stat has no valid start-time field");
-        return { pid, startIdentity: `linux-proc-start:${startTicks}` };
-    }
-    async matches(identity) {
-        const observed = await this.observe(identity.pid);
-        return observed !== null && observed.startIdentity === identity.startIdentity;
-    }
-}

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

@@ -1,4 +0,0 @@
-import type { ProcessGuardianAddon } from "./addon.js";
-import type { NativeProcessInspector } from "./contracts.js";
-/** Resolve only the platform's exact-process inspector used by cooperative session ownership. */
-export declare function createNativeProcessInspector(environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, releaseRoot?: string, loadAddon?: (path: string) => ProcessGuardianAddon): Promise<NativeProcessInspector>;

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

@@ -1,21 +0,0 @@
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
-/** Resolve only the platform's exact-process inspector used by cooperative session ownership. */
-export async function createNativeProcessInspector(environment = process.env, platform = process.platform, releaseRoot, loadAddon) {
-    if (platform === "linux") {
-        const { LinuxNativeProcessInspector } = await import("./linux-process-inspector.js");
-        return new LinuxNativeProcessInspector();
-    }
-    if (platform !== "win32" && platform !== "darwin")
-        throw new Error(`native process identity is unsupported on ${platform}`);
-    if (releaseRoot === undefined && !environment[PRODUCT_IDENTITY.environment.processGuardianPath]) {
-        throw new Error("native process identity addon is unavailable");
-    }
-    const [{ resolveProcessGuardianPath }, { loadProcessGuardianAddon }, { AddonProcessInspector }] = await Promise.all([
-        import("./addon-containment.js"),
-        import("./addon.js"),
-        import("./addon-process-inspector.js"),
-    ]);
-    const addonPath = resolveProcessGuardianPath(releaseRoot ?? process.cwd(), environment, platform);
-    const addon = (loadAddon ?? loadProcessGuardianAddon)(addonPath);
-    return new AddonProcessInspector(addon, platform === "win32" ? "windows-filetime:" : "darwin-proc-start:");
-}

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

@@ -1,18 +0,0 @@
-import { EventEmitter } from "node:events";
-import type { CommandResult, LaunchInstanceStopIntent, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
-interface ClientEvents {
-    snapshot: [SupervisorSnapshot];
-    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}`;
-    readonly releaseId?: string;
-    constructor(releaseId?: string);
-    connect(endpoint: string, timeoutMs?: number): Promise<SupervisorSnapshot>;
-    command(command: SupervisorCommand): Promise<CommandResult>;
-    close(): void;
-}
-export {};

package/dist/foundation/protocol/client.js

@@ -1,130 +0,0 @@
-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;
-    constructor(releaseId) {
-        super();
-        if (releaseId !== undefined)
-            this.releaseId = releaseId;
-    }
-    #socket = null;
-    #pending = new Map();
-    async connect(endpoint, timeoutMs = 5_000) {
-        if (this.#socket)
-            throw new Error("client is already connected");
-        const deadline = Date.now() + timeoutMs;
-        let lastError = null;
-        while (Date.now() < deadline) {
-            try {
-                return await this.#connectOnce(endpoint, Math.max(1, deadline - Date.now()));
-            }
-            catch (error) {
-                lastError = error instanceof Error ? error : new Error(String(error));
-                if (!isTransientEndpointError(lastError))
-                    throw lastError;
-                await new Promise(resolve => setTimeout(resolve, Math.min(40, Math.max(1, deadline - Date.now()))));
-            }
-        }
-        throw new Error(`supervisor endpoint ${endpoint} remained unavailable for ${timeoutMs}ms`, { cause: lastError ?? undefined });
-    }
-    #connectOnce(endpoint, timeoutMs) {
-        const socket = connect(endpoint);
-        this.#socket = socket;
-        socket.setNoDelay(true);
-        const decoder = new LineFrameDecoder();
-        return new Promise((resolve, reject) => {
-            let welcomed = false;
-            const timeout = setTimeout(() => {
-                const error = transientError(`supervisor connection timed out after ${timeoutMs}ms`, "ETIMEDOUT");
-                fail(error);
-                socket.destroy();
-            }, timeoutMs);
-            const fail = (error) => {
-                clearTimeout(timeout);
-                if (!welcomed)
-                    reject(error);
-            };
-            socket.once("error", fail);
-            socket.on("close", () => {
-                if (this.#socket === socket)
-                    this.#socket = null;
-                if (!welcomed) {
-                    fail(transientError("supervisor disconnected before completing its handshake", "ECONNRESET"));
-                    return;
-                }
-                for (const pending of this.#pending.values())
-                    pending.reject(new Error("supervisor disconnected"));
-                this.#pending.clear();
-                this.emit("disconnect");
-            });
-            socket.on("data", chunk => {
-                try {
-                    for (const value of decoder.push(chunk)) {
-                        const message = value;
-                        if (message.type === "server-hello" && message.snapshot) {
-                            const hello = message;
-                            if (hello.envelope !== CONTROL_ENVELOPE || hello.envelopeRevision !== CONTROL_ENVELOPE_REVISION || !Array.isArray(hello.requiredFeatures) || !Array.isArray(hello.optionalFeatures) || typeof hello.contractDigest !== "string") {
-                                fail(new Error("supervisor returned an invalid control handshake"));
-                                socket.destroy();
-                                continue;
-                            }
-                            const negotiation = negotiateControlFeatures(localControlHello(this.releaseId), hello);
-                            if (!negotiation.ok) {
-                                fail(new Error(negotiation.diagnostic));
-                                socket.destroy();
-                                continue;
-                            }
-                            welcomed = true;
-                            clearTimeout(timeout);
-                            resolve(message.snapshot);
-                        }
-                        else if (message.type === "snapshot" && message.snapshot) {
-                            this.emit("snapshot", message.snapshot);
-                        }
-                        else if (message.type === "command-result" && message.result) {
-                            const pending = this.#pending.get(message.result.requestId);
-                            if (pending) {
-                                this.#pending.delete(message.result.requestId);
-                                pending.resolve(message.result);
-                            }
-                        }
-                        else if (message.type === "stop-launch-instance" && message.instanceId && message.requestId && message.reason) {
-                            this.emit("stopIntent", message);
-                        }
-                        else if (message.type === "protocol-error") {
-                            fail(new Error(message.message ?? "protocol error"));
-                        }
-                    }
-                }
-                catch (error) {
-                    fail(error instanceof Error ? error : new Error(String(error)));
-                    socket.destroy();
-                }
-            });
-            socket.once("connect", () => socket.write(encodeFrame({ type: "client-hello", clientId: this.clientId, ...localControlHello(this.releaseId) })));
-        });
-    }
-    command(command) {
-        if (!this.#socket)
-            return Promise.reject(new Error("supervisor is not connected"));
-        return new Promise((resolve, reject) => {
-            this.#pending.set(command.requestId, { resolve, reject });
-            this.#socket?.write(encodeFrame({ type: "command", command }));
-        });
-    }
-    close() {
-        this.#socket?.end();
-        this.#socket = null;
-    }
-}
-function isTransientEndpointError(error) {
-    const code = "code" in error ? String(error.code) : "";
-    return ["ENOENT", "ECONNREFUSED", "ECONNRESET", "EPIPE", "ETIMEDOUT"].includes(code);
-}
-function transientError(message, code) {
-    return Object.assign(new Error(message), { code });
-}

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

@@ -1,3 +0,0 @@
-export { SupervisorClient } from "./client.js";
-export { CONTROL_ENVELOPE, CONTROL_ENVELOPE_REVISION, GENERATED_CONTRACT_DIGEST, LineFrameDecoder, MAX_CONTROL_FRAME_BYTES, OPTIONAL_CONTROL_FEATURES, REQUIRED_CONTROL_FEATURES, encodeFrame, isCommandMessage, isControlHello, localControlHello, negotiateControlFeatures, } from "./messages.js";
-export type { ClientMessage, ControlFeature, ControlHello, ControlNegotiation, ServerMessage } from "./messages.js";

package/dist/foundation/protocol/index.js

@@ -1,2 +0,0 @@
-export { SupervisorClient } from "./client.js";
-export { CONTROL_ENVELOPE, CONTROL_ENVELOPE_REVISION, GENERATED_CONTRACT_DIGEST, LineFrameDecoder, MAX_CONTROL_FRAME_BYTES, OPTIONAL_CONTROL_FEATURES, REQUIRED_CONTROL_FEATURES, encodeFrame, isCommandMessage, isControlHello, localControlHello, negotiateControlFeatures, } from "./messages.js";

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

@@ -1,90 +0,0 @@
-import type { CommandResult, LaunchInstanceStopIntent, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
-export declare const CONTROL_ENVELOPE: string;
-export declare const CONTROL_ENVELOPE_REVISION: 1;
-export declare const REQUIRED_CONTROL_FEATURES: readonly ["handshake.features.v1", "snapshot.revision.v1", "commands.request-identity.v1", "generation.lifecycle.v1", "launch.instance-lifecycle.v1"];
-export declare const OPTIONAL_CONTROL_FEATURES: readonly ["messages.unknown-additive-ignore.v1", "snapshot.resynchronize.v1"];
-export type ControlFeature = string;
-export declare const GENERATED_CONTRACT_DIGEST: string;
-export declare const MAX_CONTROL_FRAME_BYTES: number;
-export interface ControlHello {
-    readonly envelope: typeof CONTROL_ENVELOPE;
-    readonly envelopeRevision: typeof CONTROL_ENVELOPE_REVISION;
-    readonly requiredFeatures: readonly ControlFeature[];
-    readonly optionalFeatures: readonly ControlFeature[];
-    readonly contractDigest: string;
-    readonly releaseId?: string;
-}
-export type ClientMessage = {
-    readonly type: "identity-probe";
-} | {
-    readonly type: "release-idle-ownership";
-    readonly bootNonce: string;
-    readonly candidateReleaseId: string;
-} | {
-    readonly type: "release-update-ownership";
-    readonly bootNonce: string;
-    readonly targetVersion: string;
-} | ({
-    readonly type: "client-hello";
-    readonly clientId: string;
-} & ControlHello) | {
-    readonly type: "command";
-    readonly command: SupervisorCommand;
-};
-export type ServerMessage = {
-    readonly type: "identity";
-    readonly supervisorId: string;
-    readonly bootNonce: string;
-    readonly pidStartIdentity: string;
-    readonly releaseId: string;
-} | {
-    readonly type: "release-ownership-result";
-    readonly released: boolean;
-    readonly reason: string;
-    readonly liveInstanceIds: readonly string[];
-} | {
-    readonly type: "release-update-result";
-    readonly accepted: boolean;
-    readonly reason: string;
-    readonly liveInstanceIds: readonly string[];
-} | ({
-    readonly type: "server-hello";
-    readonly supervisorId: string;
-    readonly bootNonce: string;
-    readonly pidStartIdentity: string;
-    readonly negotiatedFeatures: readonly string[];
-    readonly snapshot: SupervisorSnapshot;
-} & ControlHello) | {
-    readonly type: "snapshot";
-    readonly snapshot: SupervisorSnapshot;
-} | {
-    readonly type: "command-result";
-    readonly result: CommandResult;
-} | LaunchInstanceStopIntent | {
-    readonly type: "protocol-error";
-    readonly code: string;
-    readonly message: string;
-    readonly diagnostics?: unknown;
-};
-export interface ControlNegotiation {
-    readonly ok: boolean;
-    readonly negotiatedFeatures: readonly string[];
-    readonly missingFromClient: readonly string[];
-    readonly missingFromServer: readonly string[];
-    readonly diagnostic: string;
-}
-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[];
-}
-export declare function isControlHello(value: unknown): value is {
-    readonly type: "client-hello";
-    readonly clientId: string;
-} & ControlHello;
-export declare function isCommandMessage(value: unknown): value is Extract<ClientMessage, {
-    type: "command";
-}>;

package/dist/foundation/protocol/messages.js

@@ -1,100 +0,0 @@
-import { createHash } from "node:crypto";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
-export const CONTROL_ENVELOPE = PRODUCT_IDENTITY.protocol.controlEnvelope;
-export const CONTROL_ENVELOPE_REVISION = 1;
-export const REQUIRED_CONTROL_FEATURES = [
-    "handshake.features.v1",
-    "snapshot.revision.v1",
-    "commands.request-identity.v1",
-    "generation.lifecycle.v1",
-    "launch.instance-lifecycle.v1",
-];
-export const OPTIONAL_CONTROL_FEATURES = [
-    "messages.unknown-additive-ignore.v1",
-    "snapshot.resynchronize.v1",
-];
-export const GENERATED_CONTRACT_DIGEST = createHash("sha256").update(JSON.stringify({
-    envelope: CONTROL_ENVELOPE,
-    revision: CONTROL_ENVELOPE_REVISION,
-    required: [...REQUIRED_CONTROL_FEATURES].sort(),
-    optional: [...OPTIONAL_CONTROL_FEATURES].sort(),
-})).digest("hex");
-export const MAX_CONTROL_FRAME_BYTES = 4 * 1024 * 1024;
-export function localControlHello(releaseId) {
-    return {
-        envelope: CONTROL_ENVELOPE,
-        envelopeRevision: CONTROL_ENVELOPE_REVISION,
-        requiredFeatures: REQUIRED_CONTROL_FEATURES,
-        optionalFeatures: OPTIONAL_CONTROL_FEATURES,
-        contractDigest: GENERATED_CONTRACT_DIGEST,
-        ...(releaseId ? { releaseId } : {}),
-    };
-}
-export function negotiateControlFeatures(client, server = localControlHello()) {
-    if (client.envelope !== server.envelope || client.envelopeRevision !== server.envelopeRevision) {
-        return {
-            ok: false,
-            negotiatedFeatures: [],
-            missingFromClient: [],
-            missingFromServer: [],
-            diagnostic: `control envelope mismatch: client ${client.envelope}/${client.envelopeRevision}; server ${server.envelope}/${server.envelopeRevision}`,
-        };
-    }
-    const clientFeatures = new Set([...client.requiredFeatures, ...client.optionalFeatures]);
-    const serverFeatures = new Set([...server.requiredFeatures, ...server.optionalFeatures]);
-    const missingFromClient = server.requiredFeatures.filter(feature => !clientFeatures.has(feature));
-    const missingFromServer = client.requiredFeatures.filter(feature => !serverFeatures.has(feature));
-    const negotiatedFeatures = [...clientFeatures].filter(feature => serverFeatures.has(feature)).sort();
-    return {
-        ok: missingFromClient.length === 0 && missingFromServer.length === 0,
-        negotiatedFeatures,
-        missingFromClient,
-        missingFromServer,
-        diagnostic: missingFromClient.length === 0 && missingFromServer.length === 0
-            ? `control features negotiated (${negotiatedFeatures.join(", ")}); contract client=${client.contractDigest} server=${server.contractDigest}`
-            : `required control features unavailable; client missing [${missingFromClient.join(", ")}], server missing [${missingFromServer.join(", ")}]; contract client=${client.contractDigest} server=${server.contractDigest}`,
-    };
-}
-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) {
-        this.#buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-        if (Buffer.byteLength(this.#buffer, "utf8") > MAX_CONTROL_FRAME_BYTES) {
-            this.#buffer = "";
-            throw new Error("control frame exceeds maximum size");
-        }
-        const messages = [];
-        let newline = this.#buffer.indexOf("\n");
-        while (newline >= 0) {
-            const line = this.#buffer.slice(0, newline);
-            this.#buffer = this.#buffer.slice(newline + 1);
-            if (line.length > 0)
-                messages.push(JSON.parse(line));
-            newline = this.#buffer.indexOf("\n");
-        }
-        return messages;
-    }
-}
-export function isControlHello(value) {
-    if (!isRecord(value) || value.type !== "client-hello" || typeof value.clientId !== "string")
-        return false;
-    return value.envelope === CONTROL_ENVELOPE
-        && value.envelopeRevision === CONTROL_ENVELOPE_REVISION
-        && isStringArray(value.requiredFeatures)
-        && isStringArray(value.optionalFeatures)
-        && typeof value.contractDigest === "string"
-        && (value.releaseId === undefined || typeof value.releaseId === "string");
-}
-export function isCommandMessage(value) {
-    return isRecord(value) && value.type === "command" && isRecord(value.command) && typeof value.command.type === "string";
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null;
-}
-function isStringArray(value) {
-    return Array.isArray(value) && value.every(item => typeof item === "string" && item.length > 0);
-}

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

@@ -1,33 +0,0 @@
-import type { CohortState, SupervisorEndpointMetadata } from "./cohort-state.js";
-import type { MaterializedRelease } from "./release-store.js";
-export type OwnershipProbe = "live-verified" | "dead" | "unresponsive" | "identity-mismatch";
-export type CohortLaunchDecision = {
-    readonly action: "launch-retained-ui";
-    readonly releaseId: string;
-    readonly releaseRoot: string;
-    readonly reason: string;
-    readonly recordPending: boolean;
-} | {
-    readonly action: "activate-candidate";
-    readonly releaseId: string;
-    readonly releaseRoot: string;
-    readonly reason: string;
-} | {
-    readonly action: "replace-idle-cohort";
-    readonly releaseId: string;
-    readonly releaseRoot: string;
-    readonly reason: string;
-    readonly pid: number;
-} | {
-    readonly action: "start-active";
-    readonly releaseId: string;
-    readonly releaseRoot: string;
-    readonly reason: string;
-} | {
-    readonly action: "blocked";
-    readonly releaseId: string;
-    readonly releaseRoot: string;
-    readonly reason: string;
-    readonly pid: number | null;
-};
-export declare function selectCohortLaunch(candidate: MaterializedRelease, state: CohortState, endpoint: SupervisorEndpointMetadata | null, probe: OwnershipProbe): CohortLaunchDecision;

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

@@ -1,67 +0,0 @@
-export function selectCohortLaunch(candidate, state, endpoint, probe) {
-    if (endpoint && probe === "live-verified") {
-        const retained = state.releases[endpoint.releaseId];
-        if (!retained || retained.releaseRoot !== endpoint.releaseRoot || retained.contentDigest !== endpoint.contentDigest) {
-            return {
-                action: "blocked",
-                releaseId: endpoint.releaseId,
-                releaseRoot: endpoint.releaseRoot,
-                reason: "live supervisor identity does not match a retained verified release record",
-                pid: endpoint.pid,
-            };
-        }
-        if (endpoint.releaseId !== candidate.releaseId && endpoint.ownership.liveInstanceIds.length === 0) {
-            return {
-                action: "replace-idle-cohort",
-                releaseId: candidate.releaseId,
-                releaseRoot: candidate.releaseRoot,
-                reason: "older cohort is idle and can release ownership for verified candidate activation",
-                pid: endpoint.pid,
-            };
-        }
-        return {
-            action: "launch-retained-ui",
-            releaseId: endpoint.releaseId,
-            releaseRoot: endpoint.releaseRoot,
-            reason: endpoint.releaseId === candidate.releaseId
-                ? "live supervisor already owns the installed release cohort"
-                : "live supervisor owns a non-resumable generation; candidate remains pending",
-            recordPending: endpoint.releaseId !== candidate.releaseId,
-        };
-    }
-    if (endpoint && probe === "unresponsive") {
-        // Security: even an empty persisted list cannot authorize killing an unresponsive process.
-        return {
-            action: "blocked",
-            releaseId: endpoint.releaseId,
-            releaseRoot: endpoint.releaseRoot,
-            reason: "the background service did not respond after automatic recovery; retry shortly",
-            pid: endpoint.pid,
-        };
-    }
-    if (endpoint && probe === "identity-mismatch") {
-        return {
-            action: "blocked",
-            releaseId: endpoint.releaseId,
-            releaseRoot: endpoint.releaseRoot,
-            reason: "endpoint handshake, boot nonce, or process start identity did not match durable ownership metadata",
-            pid: endpoint.pid,
-        };
-    }
-    const active = state.references.active ? state.releases[state.references.active] : undefined;
-    const approvedCandidate = state.releases[candidate.releaseId]?.approval === "approved";
-    if (approvedCandidate || !active) {
-        return {
-            action: "activate-candidate",
-            releaseId: candidate.releaseId,
-            releaseRoot: candidate.releaseRoot,
-            reason: approvedCandidate ? "approved candidate can become the active cohort" : "initial verified release can be certified and activated",
-        };
-    }
-    return {
-        action: "start-active",
-        releaseId: active.releaseId,
-        releaseRoot: active.releaseRoot,
-        reason: "candidate is not approved; retaining the active release",
-    };
-}

package/dist/foundation/release/endpoint-lock.d.ts

@@ -1,2 +0,0 @@
-/** Serialize endpoint publication and retirement using a lock released by the OS on process death. */
-export declare function withEndpointLock<T>(metadataPath: string, operation: () => Promise<T>): Promise<T>;

package/dist/foundation/release/endpoint-lock.js

@@ -1,37 +0,0 @@
-import { mkdir, realpath } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
-import { acquireSupervisorGate } from "./supervisor-identity.js";
-/** Serialize endpoint publication and retirement using a lock released by the OS on process death. */
-export async function withEndpointLock(metadataPath, operation) {
-    let authority;
-    try {
-        await mkdir(dirname(metadataPath), { recursive: true, mode: 0o700 });
-        authority = join(await realpath(dirname(metadataPath)), `${basename(metadataPath)}.authority`);
-    }
-    catch (cause) {
-        throw Object.assign(new Error("cannot access A1 startup state; check runtime-directory permissions and free disk space", { cause }), { code: "SUPERVISOR_RECOVERY_UNAVAILABLE" });
-    }
-    const deadline = Date.now() + 3_000;
-    for (;;) {
-        let gate;
-        try {
-            gate = acquireSupervisorGate(authority);
-        }
-        catch (cause) {
-            throw Object.assign(new Error("cannot access A1 startup coordination; check installation and runtime-directory permissions", { cause }), { code: "SUPERVISOR_RECOVERY_UNAVAILABLE" });
-        }
-        if (gate.acquired) {
-            try {
-                return await operation();
-            }
-            finally {
-                gate.release();
-            }
-        }
-        gate.release();
-        if (Date.now() >= deadline)
-            throw Object.assign(new Error("another A1 startup is still preparing; retry shortly"), { code: "SUPERVISOR_RECOVERY_BUSY" });
-        await delay(20);
-    }
-}

package/dist/foundation/release/endpoint-recovery.d.ts

@@ -1,10 +0,0 @@
-import type { SupervisorEndpointMetadata } from "./cohort-state.js";
-interface SupervisorRecoveryOptions {
-    readonly metadataPath: string;
-    readonly endpoint: string;
-    readonly matches: (metadata: SupervisorEndpointMetadata) => boolean;
-    readonly startAndWait: () => Promise<void>;
-}
-/** Recover all launch routes identically; a retry never grants permission to kill a live process. */
-export declare function recoverSupervisorEndpoint(options: SupervisorRecoveryOptions): Promise<void>;
-export {};

package/dist/foundation/release/endpoint-recovery.js

@@ -1,45 +0,0 @@
-import { writeFile } from "node:fs/promises";
-import { probeOwnership, readEndpointMetadata, removeEndpointArtifacts } from "./endpoints.js";
-/** Recover all launch routes identically; a retry never grants permission to kill a live process. */
-export async function recoverSupervisorEndpoint(options) {
-    const { metadataPath, endpoint } = options;
-    let recovered = false;
-    for (let attempt = 0; attempt < 3; attempt++) {
-        const metadata = await readEndpointMetadata(metadataPath);
-        if (metadata) {
-            const probe = await probeOwnership(metadata);
-            if (probe === "live-verified" && options.matches(metadata)) {
-                if (recovered)
-                    await diagnostic(metadataPath, "recovered", attempt + 1);
-                return;
-            }
-            // Concurrency: another owner may have published while an earlier identity probe was pending.
-            if (JSON.stringify(await readEndpointMetadata(metadataPath)) !== JSON.stringify(metadata))
-                continue;
-            if (probe !== "dead") {
-                await diagnostic(metadataPath, probe, attempt + 1);
-                throw Object.assign(new Error(probe === "unresponsive"
-                    ? "A1's background service is not responding; retry shortly. Your sessions have been preserved."
-                    : "A1's background service identity changed; retry startup. Your sessions have been preserved."), {
-                    code: "SUPERVISOR_RECOVERY_BLOCKED",
-                });
-            }
-            recovered = true;
-            if (!await removeEndpointArtifacts(metadataPath, endpoint, metadata))
-                continue;
-            await diagnostic(metadataPath, "stale-owner-retired", attempt + 1);
-        }
-        // Concurrency: the child takes the same endpoint gate before binding/publication. If another launch wins,
-        // startAndWait joins its authenticated endpoint; it never unlinks that winner's socket.
-        await options.startAndWait();
-        if (recovered)
-            await diagnostic(metadataPath, "recovered", attempt + 1);
-        return;
-    }
-    await diagnostic(metadataPath, "ownership-changing", 3);
-    throw Object.assign(new Error("A1 startup changed repeatedly; retry shortly"), { code: "SUPERVISOR_RECOVERY_BUSY" });
-}
-async function diagnostic(path, reason, attempts) {
-    // Security: one bounded summary per endpoint, no raw metadata, user paths, or session content.
-    await writeFile(`${path}.recovery.json`, JSON.stringify({ reason, attempts, at: new Date().toISOString() }), { mode: 0o600 }).catch(() => undefined);
-}

package/dist/foundation/release/endpoints.d.ts

@@ -1,32 +0,0 @@
-import type { OwnershipProbe } from "./cohort-selection.js";
-import { type ObserveSupervisorProcess } from "./supervisor-identity.js";
-import type { SupervisorEndpointMetadata } from "./cohort-state.js";
-import type { CohortEndpointPaths, ProductPaths } from "../lifecycle/index.js";
-export interface RecordedEndpoint {
-    readonly metadata: SupervisorEndpointMetadata;
-    readonly paths: CohortEndpointPaths;
-}
-/**
- * Every endpoint recorded under this runtime directory: one per cohort, plus the single
- * endpoint published by releases that predate cohort-scoped identity. More than one can be
- * live at a time, and each is validated on its own identity rather than by being the only one.
- */
-export declare function listRecordedEndpoints(paths: ProductPaths): Promise<readonly RecordedEndpoint[]>;
-/**
- * Removes the records of cohorts whose processes are gone. A record left by a cohort that
- * exited without cleaning up is not evidence of ownership, and a later launch should not have
- * to reason about it. Returns the release ids whose records were removed.
- */
-export declare function sweepDeadEndpoints(paths: ProductPaths): Promise<readonly string[]>;
-/** The releases that an identity-verified live cohort runs from and that must be retained. */
-export declare function liveReleaseIds(paths: ProductPaths): Promise<readonly string[]>;
-export declare function readEndpointMetadata(path: string): Promise<SupervisorEndpointMetadata | null>;
-export interface OwnershipProbeOptions {
-    readonly observe?: ObserveSupervisorProcess;
-    readonly attempts?: number;
-    readonly timeoutMs?: number;
-}
-/** Reprobe transient failures; only native absence or a replaced generation establishes death. */
-export declare function probeOwnership(metadata: SupervisorEndpointMetadata, options?: OwnershipProbeOptions): Promise<OwnershipProbe>;
-/** Retire only a still-dead exact publication. Socket removal belongs to the gated listener. */
-export declare function removeEndpointArtifacts(metadataPath: string, endpoint: string, expected: SupervisorEndpointMetadata): Promise<boolean>;