@timurproko/a1 0.1.8-dev.ece8cef → 0.2.1-dev.590

package/dist/foundation/launch-guardian/main.js

@@ -0,0 +1,179 @@
+import { randomUUID } from "node:crypto";
+import { PRODUCT_TEXT } from "../../product-identity.js";
+import { readLaunchContext } from "../launch-context/index.js";
+import { resolve } from "node:path";
+import { assertLaunchProfileId, resolveCohortEndpoint, resolveProductPaths, sessionSelectionArguments } from "../lifecycle/index.js";
+import { closeVerifiedContainment, DarwinNativeProcessInspector, LinuxNativeProcessInspector, NativeGuardianContainment, resolveProcessGuardianPath, verifyProcessGuardianArtifact, WindowsNativeProcessInspector, } from "../process-containment/index.js";
+import { SupervisorClient } from "../protocol/index.js";
+import { markStartupPhase } from "../startup/index.js";
+export async function runLaunchGuardian(options) {
+    assertLaunchProfileId(options.profileId);
+    const sessionArgs = sessionSelectionArguments(options.sessionSelection);
+    if (sessionArgs.length > 0 && options.profileId !== "a1")
+        throw new Error("session selection requires the normal A1 profile");
+    const environment = { ...(options.environment ?? process.env) };
+    const paths = resolveProductPaths(environment);
+    const instanceId = randomUUID();
+    const helperPath = options.helperPath ?? resolveProcessGuardianPath(options.releaseRoot, environment);
+    const inspector = options.inspector ?? platformInspector(helperPath);
+    await (options.ensureHelper ?? verifyProcessGuardianArtifact)(helperPath);
+    const guardianIdentity = await inspector.observe(process.pid);
+    if (!guardianIdentity)
+        throw diagnosticError("launch guardian cannot verify its own native process identity", "PROCESS_IDENTITY_UNAVAILABLE");
+    const context = readLaunchContext(environment);
+    const client = options.control ?? new SupervisorClient(context.releaseId);
+    // Invariant: an instance belongs to the cohort that launched it and talks to that cohort's endpoint
+    // for its whole life, whatever release becomes the active one meanwhile.
+    const releaseId = context.releaseId;
+    const endpoint = releaseId
+        ? resolveCohortEndpoint(paths, releaseId, environment).endpoint
+        : paths.endpoint;
+    await client.connect(endpoint);
+    await markStartupPhase(environment, "guardian-connected");
+    const containment = options.containment ?? new NativeGuardianContainment(instanceId, helperPath, resolve(paths.runtimeDir, "launch-instances", `${instanceId}.ready.json`));
+    const stop = stopRequests(client, instanceId);
+    let rootIdentity = null;
+    try {
+        await requireAccepted(client, {
+            type: "create-launch-instance",
+            requestId: randomUUID(),
+            instanceId,
+            profileId: options.profileId,
+            shutdownPolicy: "terminate-tree-on-close",
+            guardianIdentity,
+        });
+        let handle;
+        try {
+            handle = await containment.spawn(process.execPath, [options.uiEntry, ...sessionArgs], {
+                cwd: options.cwd ?? process.cwd(),
+                environment: environmentEntries(environment),
+                ...(environment.TERM ? { terminalType: environment.TERM } : {}),
+            });
+            rootIdentity = handle.identity;
+            await requireAccepted(client, {
+                type: "activate-launch-instance",
+                requestId: randomUUID(),
+                instanceId,
+                rootIdentity,
+                containmentIdentity: containment.identity,
+            });
+        }
+        catch (error) {
+            const outcome = failureOutcome(error, "guardian-error");
+            await completeBestEffort(client, instanceId, "completed", outcome);
+            throw error;
+        }
+        const outcome = await Promise.race([
+            handle.outcome,
+            stop.requested.then(async (reason) => {
+                if (reason !== "supervisor-disconnect") {
+                    await requireAccepted(client, {
+                        type: "begin-launch-instance-stop",
+                        requestId: randomUUID(),
+                        instanceId,
+                        reason,
+                    });
+                }
+                if (!rootIdentity)
+                    return failureOutcome(new Error("launch root identity is unavailable"), "cleanup-error");
+                const result = await closeVerifiedContainment(containment, inspector, rootIdentity, reason);
+                await containment.close();
+                if (reason === "supervisor-disconnect" && result.outcome.kind === "stopped") {
+                    return {
+                        kind: "interrupted",
+                        reason,
+                        message: "supervisor disconnected after local launch-instance containment closed",
+                    };
+                }
+                return result.outcome;
+            }),
+        ]);
+        await containment.close();
+        if (outcome.kind !== "interrupted" || outcome.reason !== "supervisor-disconnect") {
+            await completeBestEffort(client, instanceId, outcome.kind === "interrupted" || outcome.kind === "cleanup-error" ? "interrupted" : "completed", outcome);
+        }
+        return exitCode(outcome);
+    }
+    catch (error) {
+        await containment.close().catch(() => undefined);
+        throw error;
+    }
+    finally {
+        stop.dispose();
+        client.close();
+    }
+}
+function platformInspector(helperPath) {
+    if (process.platform === "win32")
+        return new WindowsNativeProcessInspector(helperPath);
+    if (process.platform === "linux")
+        return new LinuxNativeProcessInspector();
+    if (process.platform === "darwin")
+        return new DarwinNativeProcessInspector(helperPath);
+    throw diagnosticError(`launch-instance process containment is unsupported on ${process.platform}`, "CONTAINMENT_UNSUPPORTED");
+}
+function stopRequests(client, instanceId) {
+    let resolveStop;
+    let settled = false;
+    const requested = new Promise(resolvePromise => { resolveStop = resolvePromise; });
+    const request = (reason) => {
+        if (settled)
+            return;
+        settled = true;
+        resolveStop(reason);
+    };
+    const onStopIntent = (intent) => {
+        if (intent.instanceId === instanceId)
+            request(intent.reason);
+    };
+    const onDisconnect = () => request("supervisor-disconnect");
+    const onSigterm = () => request("user-request");
+    const onSigint = () => undefined;
+    client.on("stopIntent", onStopIntent);
+    client.on("disconnect", onDisconnect);
+    process.once("SIGTERM", onSigterm);
+    process.on("SIGINT", onSigint);
+    return {
+        requested,
+        dispose() {
+            client.off("stopIntent", onStopIntent);
+            client.off("disconnect", onDisconnect);
+            process.off("SIGTERM", onSigterm);
+            process.off("SIGINT", onSigint);
+        },
+    };
+}
+async function requireAccepted(client, command) {
+    const result = await client.command(command);
+    if (!result.ok)
+        throw diagnosticError(result.error?.message ?? `supervisor rejected ${command.type}`, result.error?.code ?? "SUPERVISOR_REJECTED");
+}
+async function completeBestEffort(client, instanceId, terminalState, outcome) {
+    await requireAccepted(client, {
+        type: "complete-launch-instance",
+        requestId: randomUUID(),
+        instanceId,
+        terminalState,
+        outcome,
+    }).catch(() => undefined);
+}
+function environmentEntries(environment) {
+    return Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined));
+}
+function failureOutcome(error, kind) {
+    return {
+        kind,
+        message: error instanceof Error ? error.message : String(error),
+        code: error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : null,
+    };
+}
+function exitCode(outcome) {
+    if (outcome.kind === "exited")
+        return outcome.exitCode;
+    if (outcome.kind === "stopped")
+        return 0;
+    return 1;
+}
+function diagnosticError(message, code) {
+    return Object.assign(new Error(`${PRODUCT_TEXT.displayName}: ${message}`), { code });
+}

package/dist/foundation/lifecycle/commands.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,13 @@
+export type { LaunchInstanceStopIntent, SupervisorCommand } from "./commands.js";
+export { assertLaunchInstance, assertLaunchInstanceOutcome, assertLaunchInstanceTransition, assertProcessContainmentIdentity } from "./launch-instance.js";
+export type { LaunchInstance, LaunchInstanceId, LaunchInstanceOutcome, LaunchInstanceShutdownPolicy, LaunchInstanceState, LaunchInstanceStopReason, ProcessContainmentIdentity, } from "./launch-instance.js";
+export { assertDimensions, assertLaunchProfileId, assertNativeProcessIdentity, assertTransparentTerminalLaunchProfile } from "./model.js";
+export type { CommandResult, DriverProfileId, GenerationId, LaunchProfileId, NativeProcessIdentity, RequestId, SupervisorSnapshot, TerminalDimensions, TransparentTerminalLaunchProfile, TransparentTerminalLifecycleOutcome, } from "./model.js";
+export { resolveCohortEndpoint, resolveProductPaths } from "./paths.js";
+export type { CohortEndpointPaths, ProductPaths } from "./paths.js";
+export { parseSessionSelection, sessionSelectionArguments } from "./session-selection.js";
+export type { SessionSelection } from "./session-selection.js";
+export { clearSessionRepositoryContext, readSessionRepositoryContext, setSessionRepositoryContext } from "./session-repository-context.js";
+export type { SessionRepositoryContext, SessionRepositoryContextOptions, SessionRepositoryIdentity } from "./session-repository-context.js";
+export { createSupervisorStartupAttempt, publishSupervisorStartupResult, readSupervisorStartupResult, supervisorStartupFailure, supervisorStartupReady, supervisorStartupResultPath, } from "./supervisor-startup.js";
+export type { SupervisorStartupAttemptIdentity, SupervisorStartupResult } from "./supervisor-startup.js";

package/dist/foundation/lifecycle/index.js

@@ -0,0 +1,6 @@
+export { assertLaunchInstance, assertLaunchInstanceOutcome, assertLaunchInstanceTransition, assertProcessContainmentIdentity } from "./launch-instance.js";
+export { assertDimensions, assertLaunchProfileId, assertNativeProcessIdentity, assertTransparentTerminalLaunchProfile } from "./model.js";
+export { resolveCohortEndpoint, resolveProductPaths } from "./paths.js";
+export { parseSessionSelection, sessionSelectionArguments } from "./session-selection.js";
+export { clearSessionRepositoryContext, readSessionRepositoryContext, setSessionRepositoryContext } from "./session-repository-context.js";
+export { createSupervisorStartupAttempt, publishSupervisorStartupResult, readSupervisorStartupResult, supervisorStartupFailure, supervisorStartupReady, supervisorStartupResultPath, } from "./supervisor-startup.js";

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

@@ -0,0 +1,64 @@
+export type LaunchProfileId = "a1" | "pi";
+export type GenerationId = string;
+export type DriverProfileId = string;
+export type RequestId = string;
+export interface TerminalDimensions {
+    readonly columns: number;
+    readonly rows: number;
+}
+export interface TransparentTerminalLaunchProfile {
+    readonly id: DriverProfileId;
+    readonly terminalCapability: "transparent";
+    readonly executable: string;
+    readonly arguments: readonly string[];
+    readonly cwd: string;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly terminalType: string;
+    readonly dimensions: TerminalDimensions;
+    readonly ownerDisconnect: "stop" | "detach";
+    readonly recovery: "detach-only" | "none";
+    readonly surface: "none";
+    readonly visualReconnection: "none";
+}
+export interface NativeProcessIdentity {
+    readonly pid: number;
+    readonly startIdentity: string;
+}
+export type TransparentTerminalLifecycleOutcome = {
+    readonly kind: "exited";
+    readonly exitCode: number;
+} | {
+    readonly kind: "signaled";
+    readonly signal: string;
+} | {
+    readonly kind: "stopped";
+    readonly reason: "owner-disconnect" | "user-request" | "update";
+} | {
+    readonly kind: "detached";
+    readonly reason: "owner-disconnect";
+} | {
+    readonly kind: "spawn-error" | "broker-error";
+    readonly message: string;
+    readonly code: string | null;
+};
+export interface SupervisorSnapshot {
+    readonly revision: number;
+    readonly activeInstances: readonly {
+        readonly id: string;
+        readonly profileId: LaunchProfileId;
+        readonly state: "requested" | "active" | "stopping";
+    }[];
+}
+export interface CommandResult {
+    readonly requestId: RequestId;
+    readonly ok: boolean;
+    readonly revision: number;
+    readonly error?: {
+        readonly code: "invalid-command" | "not-found" | "stale-generation" | "capability-error" | "containment-unsupported" | "ownership-error" | "release-superseded" | "driver-error";
+        readonly message: string;
+    };
+}
+export declare function assertLaunchProfileId(value: unknown): asserts value is LaunchProfileId;
+export declare function assertDimensions(dimensions: TerminalDimensions): void;
+export declare function assertTransparentTerminalLaunchProfile(profile: TransparentTerminalLaunchProfile): void;
+export declare function assertNativeProcessIdentity(identity: NativeProcessIdentity): void;

package/dist/foundation/lifecycle/model.js

@@ -0,0 +1,40 @@
+import { PRODUCT_TEXT } from "../../product-identity.js";
+export function assertLaunchProfileId(value) {
+    if (value !== "a1" && value !== "pi")
+        throw new TypeError(PRODUCT_TEXT.diagnostic(`launch profile is invalid: ${String(value)}`));
+}
+export function assertDimensions(dimensions) {
+    if (!Number.isInteger(dimensions.columns) || dimensions.columns < 2 || dimensions.columns > 500) {
+        throw new RangeError("terminal columns must be an integer from 2 to 500");
+    }
+    if (!Number.isInteger(dimensions.rows) || dimensions.rows < 1 || dimensions.rows > 300) {
+        throw new RangeError("terminal rows must be an integer from 1 to 300");
+    }
+}
+export function assertTransparentTerminalLaunchProfile(profile) {
+    if (!profile.id || profile.terminalCapability !== "transparent")
+        throw new TypeError("invalid transparent terminal profile identity");
+    if (!profile.executable || profile.executable.includes("\0"))
+        throw new TypeError("transparent executable must be non-empty and contain no null byte");
+    if (!profile.cwd || profile.cwd.includes("\0"))
+        throw new TypeError("transparent working directory must be non-empty and contain no null byte");
+    if (profile.arguments.some(value => typeof value !== "string" || value.includes("\0")))
+        throw new TypeError("transparent arguments must contain no null byte");
+    if (Object.entries(profile.environment).some(([name, value]) => !name || name.includes("=") || name.includes("\0") || value.includes("\0"))) {
+        throw new TypeError("transparent environment contains an invalid name or value");
+    }
+    if (!profile.terminalType || profile.terminalType.includes("\0"))
+        throw new TypeError("transparent terminal type is invalid");
+    assertDimensions(profile.dimensions);
+    if (profile.surface !== "none" || profile.visualReconnection !== "none")
+        throw new TypeError("transparent profiles cannot declare a surface or visual reconnection");
+    if (profile.ownerDisconnect === "detach" && profile.recovery !== "detach-only")
+        throw new TypeError("transparent detach policy requires detach-only recovery");
+    if (profile.ownerDisconnect === "stop" && profile.recovery !== "none")
+        throw new TypeError("transparent stop policy requires no recovery claim");
+}
+export function assertNativeProcessIdentity(identity) {
+    if (!Number.isSafeInteger(identity.pid) || identity.pid <= 0 || !identity.startIdentity || identity.startIdentity.includes("\0")) {
+        throw new TypeError("invalid native process identity");
+    }
+}

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

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

package/dist/foundation/lifecycle/paths.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { homedir, platform } from "node:os";
+import { posix, win32 } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/**
+ * Endpoint identity for one release cohort. Two cohorts can be live at once — an update
+ * leaves a working session on the release it started on — so the name a supervisor listens
+ * on has to name the release as well as the runtime directory, or the two contend for one
+ * endpoint and replacing one means ending the other.
+ *
+ * An explicit endpoint override keeps its single endpoint: it is how an isolated run pins
+ * the address it is going to talk to.
+ */
+export function resolveCohortEndpoint(paths, releaseId, environment = process.env, hostPlatform = platform()) {
+    if (environment[PRODUCT_IDENTITY.environment.endpoint]) {
+        return { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath };
+    }
+    const path = hostPlatform === "win32" ? win32 : posix;
+    const token = createHash("sha256").update(releaseId).digest("hex").slice(0, 16);
+    const endpoint = hostPlatform === "win32"
+        ? `${paths.endpoint}-${token}`
+        : path.join(paths.endpointDirectory ?? paths.runtimeDir, `${token}-${PRODUCT_IDENTITY.endpoint.unixSocketFilename}`);
+    return { endpoint, endpointMetadataPath: path.join(paths.endpointsDir, `${token}.json`) };
+}
+export function resolveProductPaths(environment = process.env, hostPlatform = platform(), fallbackHome = homedir()) {
+    const windows = hostPlatform === "win32";
+    const path = windows ? win32 : posix;
+    const home = environment.HOME ?? environment.USERPROFILE ?? fallbackHome;
+    const configOverride = environment[PRODUCT_IDENTITY.environment.configDir];
+    const dataOverride = environment[PRODUCT_IDENTITY.environment.dataDir];
+    const runtimeOverride = environment[PRODUCT_IDENTITY.environment.runtimeDir];
+    const databaseOverride = environment[PRODUCT_IDENTITY.environment.databasePath];
+    const endpointOverride = environment[PRODUCT_IDENTITY.environment.endpoint];
+    const configDir = path.resolve(configOverride
+        ?? (windows
+            ? path.join(environment.APPDATA ?? home, PRODUCT_IDENTITY.state.windowsControlDirectory)
+            : path.join(environment.XDG_CONFIG_HOME ?? path.join(home, ".config"), PRODUCT_IDENTITY.state.unixControlDirectory)));
+    const dataDir = path.resolve(dataOverride
+        ?? (windows
+            ? path.join(environment.LOCALAPPDATA ?? home, PRODUCT_IDENTITY.state.windowsControlDirectory)
+            : path.join(environment.XDG_DATA_HOME ?? path.join(home, ".local", "share"), PRODUCT_IDENTITY.state.unixControlDirectory)));
+    const runtimeDir = path.resolve(runtimeOverride
+        ?? (windows
+            ? path.join(dataDir, "runtime")
+            : environment.XDG_RUNTIME_DIR
+                ? path.join(environment.XDG_RUNTIME_DIR, PRODUCT_IDENTITY.state.unixControlDirectory)
+                : path.join(dataDir, "runtime")));
+    const namespace = createHash("sha256").update(runtimeDir.toLowerCase()).digest("hex").slice(0, 20);
+    // Platform: Darwin limits Unix-domain socket paths to roughly 104 bytes. Runtime roots
+    // under /var/folders can exceed that before the cohort suffix is added, so only socket
+    // files use a short owned namespace while metadata remains under the selected runtime.
+    const endpointDirectory = !endpointOverride && hostPlatform === "darwin"
+        ? posix.join("/tmp", `${PRODUCT_IDENTITY.state.unixControlDirectory}-${namespace}`)
+        : null;
+    const endpoint = endpointOverride
+        ?? (windows
+            ? `\\\\.\\pipe\\${PRODUCT_IDENTITY.endpoint.windowsPipeStem}-${namespace}`
+            : path.join(endpointDirectory ?? runtimeDir, PRODUCT_IDENTITY.endpoint.unixSocketFilename));
+    return {
+        configDir,
+        dataDir,
+        runtimeDir,
+        databasePath: path.resolve(databaseOverride ?? path.join(dataDir, PRODUCT_IDENTITY.endpoint.databaseFilename)),
+        endpoint,
+        endpointMetadataPath: path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.metadataFilename),
+        endpointsDir: path.join(runtimeDir, "endpoints"),
+        endpointDirectory,
+        supervisorLogPath: path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.supervisorLogFilename),
+    };
+}

package/dist/foundation/lifecycle/session-repository-context.d.ts

@@ -0,0 +1,18 @@
+export interface SessionRepositoryIdentity {
+    readonly sessionId: string;
+    readonly sessionFile: string;
+}
+export interface SessionRepositoryContext {
+    readonly cwd: string;
+    readonly branch: string;
+}
+export interface SessionRepositoryContextOptions {
+    readonly dataDir?: string;
+    readonly signal?: AbortSignal;
+}
+/** Persist one explicit same-repository worktree association for a stable Pi session. */
+export declare function setSessionRepositoryContext(identity: SessionRepositoryIdentity, worktreePath: string, options?: SessionRepositoryContextOptions): Promise<SessionRepositoryContext>;
+/** Remove only the association belonging to the supplied stable session. */
+export declare function clearSessionRepositoryContext(identity: SessionRepositoryIdentity, options?: SessionRepositoryContextOptions): Promise<void>;
+/** Read and revalidate a persisted association; malformed or stale state fails closed to absence. */
+export declare function readSessionRepositoryContext(identity: SessionRepositoryIdentity, options?: SessionRepositoryContextOptions): Promise<SessionRepositoryContext | null>;

package/dist/foundation/lifecycle/session-repository-context.js

@@ -0,0 +1,173 @@
+import { createHash, randomUUID } from "node:crypto";
+import { open, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { resolveProductPaths } from "./paths.js";
+const SCHEMA = "a1-session-repository-context-v1";
+const MAX_RECORD_BYTES = 16 * 1024;
+const MAX_HEADER_BYTES = 64 * 1024;
+const GIT_TIMEOUT_MS = 5_000;
+/** Persist one explicit same-repository worktree association for a stable Pi session. */
+export async function setSessionRepositoryContext(identity, worktreePath, options = {}) {
+    const header = await readSessionHeader(identity);
+    const startup = await readGitWorktreeIdentity(header.cwd, false, options.signal);
+    const selected = await readGitWorktreeIdentity(worktreePath, true, options.signal);
+    if (!samePath(startup.commonDir, selected.commonDir)) {
+        throw new Error("associated worktree belongs to a different Git repository");
+    }
+    const record = {
+        schema: SCHEMA,
+        sessionId: header.id,
+        sessionFile: header.file,
+        startupRoot: startup.root,
+        startupCommonDir: startup.commonDir,
+        worktreeRoot: selected.root,
+        worktreeCommonDir: selected.commonDir,
+        worktreeGitDir: selected.gitDir,
+        updatedAt: new Date().toISOString(),
+    };
+    const destination = recordPath(header, options);
+    const directory = dirname(destination);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        await rename(temporary, destination);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+    return { cwd: selected.root, branch: requireBranch(selected) };
+}
+/** Remove only the association belonging to the supplied stable session. */
+export async function clearSessionRepositoryContext(identity, options = {}) {
+    const header = await readSessionHeader(identity);
+    await rm(recordPath(header, options), { force: true });
+}
+/** Read and revalidate a persisted association; malformed or stale state fails closed to absence. */
+export async function readSessionRepositoryContext(identity, options = {}) {
+    let header;
+    try {
+        header = await readSessionHeader(identity);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const path = recordPath(header, options);
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size === 0 || metadata.size > MAX_RECORD_BYTES)
+            return null;
+        const bytes = await readFile(path, { signal: options.signal });
+        const value = JSON.parse(bytes.toString("utf8"));
+        if (!isRecord(value)
+            || value.schema !== SCHEMA
+            || value.sessionId !== header.id
+            || value.sessionFile !== header.file
+            || !validPath(value.startupRoot)
+            || !validPath(value.startupCommonDir)
+            || !validPath(value.worktreeRoot)
+            || !validPath(value.worktreeCommonDir)
+            || !validPath(value.worktreeGitDir)
+            || typeof value.updatedAt !== "string")
+            return null;
+        const startup = await readGitWorktreeIdentity(header.cwd, false, options.signal);
+        const selected = await readGitWorktreeIdentity(value.worktreeRoot, true, options.signal);
+        if (!samePath(startup.root, value.startupRoot)
+            || !samePath(startup.commonDir, value.startupCommonDir)
+            || !samePath(selected.root, value.worktreeRoot)
+            || !samePath(selected.commonDir, value.worktreeCommonDir)
+            || !samePath(selected.gitDir, value.worktreeGitDir)
+            || !samePath(startup.commonDir, selected.commonDir))
+            return null;
+        return { cwd: selected.root, branch: requireBranch(selected) };
+    }
+    catch {
+        return null;
+    }
+}
+async function readSessionHeader(identity) {
+    if (!validSessionId(identity.sessionId) || !validPath(identity.sessionFile))
+        throw new Error("active session identity is unavailable");
+    const file = await realpath(resolve(identity.sessionFile));
+    const handle = await open(file, "r");
+    try {
+        const buffer = Buffer.alloc(MAX_HEADER_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, 0);
+        const newline = buffer.subarray(0, bytesRead).indexOf(0x0a);
+        if (newline < 0)
+            throw new Error("session header is unavailable");
+        const value = JSON.parse(buffer.subarray(0, newline).toString("utf8"));
+        if (!isRecord(value) || value.type !== "session" || value.id !== identity.sessionId || !validPath(value.cwd)) {
+            throw new Error("active session identity does not match its session file");
+        }
+        return { id: identity.sessionId, cwd: await realpath(resolve(value.cwd)), file };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readGitWorktreeIdentity(path, requireWorktreeRoot, signal) {
+    if (!validPath(path))
+        throw new Error("associated worktree path is invalid");
+    const cwd = await realpath(resolve(path));
+    const { stdout } = await executeGit(["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir", "--git-dir"], cwd, MAX_RECORD_BYTES, signal);
+    const lines = stdout.split(/\r?\n/u).filter(Boolean);
+    if (lines.length !== 3)
+        throw new Error("associated worktree identity is invalid");
+    const [rootValue, commonValue, gitValue] = lines;
+    if (!rootValue || !commonValue || !gitValue)
+        throw new Error("associated worktree identity is incomplete");
+    const root = await realpath(rootValue);
+    if (requireWorktreeRoot && !samePath(root, cwd))
+        throw new Error("associated path must be a Git worktree root");
+    const commonDir = await realpath(commonValue);
+    const gitDir = await realpath(gitValue);
+    let branch = null;
+    if (requireWorktreeRoot) {
+        const branchResult = await executeGit(["symbolic-ref", "--quiet", "--short", "HEAD"], cwd, 4_096, signal);
+        branch = branchResult.stdout.trim();
+        if (branch.length === 0 || branch.length > 256)
+            throw new Error("associated worktree has a detached or invalid branch");
+    }
+    return { root, commonDir, gitDir, branch };
+}
+async function executeGit(arguments_, cwd, maxBuffer, signal) {
+    const { execFile } = await import("node:child_process");
+    const execute = promisify(execFile);
+    return await execute("git", [...arguments_], {
+        cwd,
+        windowsHide: true,
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer,
+        encoding: "utf8",
+        signal,
+    });
+}
+function requireBranch(identity) {
+    if (identity.branch === null)
+        throw new Error("associated worktree branch is unavailable");
+    return identity.branch;
+}
+function recordPath(header, options) {
+    const dataDir = options.dataDir ?? resolveProductPaths().dataDir;
+    const digest = createHash("sha256").update(header.id).update("\0").update(pathKey(header.file)).digest("hex");
+    return join(dataDir, PRODUCT_IDENTITY.state.sessionRepositoryDirectory, `${digest}.json`);
+}
+function samePath(left, right) {
+    return pathKey(left) === pathKey(right);
+}
+function pathKey(value) {
+    const normalized = resolve(value);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function validSessionId(value) {
+    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u.test(value);
+}
+function validPath(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 32_768 && !value.includes("\0") && isAbsolute(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/foundation/lifecycle/session-selection.d.ts

@@ -0,0 +1,9 @@
+/** Invocation-scoped selection; never inferred from a parent's active-session environment. */
+export interface SessionSelection {
+    readonly target: string;
+    readonly sessionDir?: string;
+}
+/** Shared public/internal grammar, deliberately not arbitrary Pi argument passthrough. */
+export declare function parseSessionSelection(arguments_: readonly string[]): SessionSelection | undefined;
+/** Encode only validated values into separate argv entries; no shell quoting or evaluation. */
+export declare function sessionSelectionArguments(selection?: SessionSelection): string[];

package/dist/foundation/lifecycle/session-selection.js

@@ -0,0 +1,39 @@
+/** Shared public/internal grammar, deliberately not arbitrary Pi argument passthrough. */
+export function parseSessionSelection(arguments_) {
+    if (arguments_.length === 0)
+        return undefined;
+    let target;
+    let sessionDir;
+    for (let index = 0; index < arguments_.length; index += 2) {
+        const option = arguments_[index];
+        if (option !== "--session" && option !== "--session-dir")
+            throw new Error("expected --session <path|id> with optional --session-dir <dir>");
+        const value = arguments_[index + 1];
+        if (value === undefined || value.startsWith("-") || !validValue(value))
+            throw new Error(`${option} requires a nonempty value`);
+        if (option === "--session") {
+            if (target !== undefined)
+                throw new Error("--session may occur only once");
+            target = value;
+        }
+        else {
+            if (sessionDir !== undefined)
+                throw new Error("--session-dir may occur only once");
+            sessionDir = value;
+        }
+    }
+    if (target === undefined)
+        throw new Error("--session-dir requires --session <path|id>");
+    return Object.freeze({ target, ...(sessionDir === undefined ? {} : { sessionDir }) });
+}
+/** Encode only validated values into separate argv entries; no shell quoting or evaluation. */
+export function sessionSelectionArguments(selection) {
+    if (selection === undefined)
+        return [];
+    const args = [...(selection.sessionDir === undefined ? [] : ["--session-dir", selection.sessionDir]), "--session", selection.target];
+    parseSessionSelection(args);
+    return args;
+}
+function validValue(value) {
+    return value.trim().length > 0 && value.length <= 32_768 && !/[\u0000\r\n]/.test(value);
+}