@piagent/platform 1.3.1 → 1.4.1

package/packages/piagent-webui/extension/terminal-session-adapter.ts

@@ -0,0 +1,73 @@
+import { randomBytes } from "node:crypto";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { gatewayProfileState, readOrCreateCatalogKey } from "../ownership/profile-state.ts";
+import { sessionRefForPath } from "../ownership/session-refs.ts";
+import { SessionLeaseStore, type SessionLeaseSnapshot } from "../ownership/session-lease-store.ts";
+
+type Binding = {
+  rawSessionId: string;
+  sessionRef: string;
+  lease: SessionLeaseSnapshot;
+};
+
+/**
+ * Registers the Pi TUI as the exact session writer in the same durable lease
+ * authority used by the Gateway. A failed registration is fail-closed for new
+ * input/tool work; it never claims that two runtimes can safely share JSONL.
+ */
+export class TerminalSessionAdapter {
+  readonly #terminalInstanceRef = `terminal_${process.pid}_${randomBytes(16).toString("base64url")}`;
+  readonly #runtimeInstanceRef: string;
+  readonly #leases: SessionLeaseStore;
+  readonly #key: Buffer;
+  #binding: Binding | null = null;
+  #reasonCode: string | null = "terminal-session-not-bound";
+
+  constructor(runtimeInstanceRef: string, agentDir?: string) {
+    this.#runtimeInstanceRef = runtimeInstanceRef;
+    const state = gatewayProfileState(agentDir);
+    this.#key = readOrCreateCatalogKey(state);
+    this.#leases = new SessionLeaseStore(state.root, this.#key);
+  }
+
+  bind(ctx: ExtensionContext): void {
+    const file = ctx.sessionManager.getSessionFile();
+    if (!file) { this.#reasonCode = "terminal-session-not-persisted"; throw new Error(this.#reasonCode); }
+    const rawSessionId = ctx.sessionManager.getSessionId();
+    const sessionRef = sessionRefForPath(this.#key, file);
+    if (this.#binding?.rawSessionId === rawSessionId && this.#binding.sessionRef === sessionRef
+      && this.#leases.inspect(sessionRef).ownerEpoch === this.#binding.lease.ownerEpoch) {
+      this.#reasonCode = null; return;
+    }
+    this.release();
+    const lease = this.#leases.acquireTerminal(sessionRef, this.#terminalInstanceRef, this.#runtimeInstanceRef);
+    this.#binding = { rawSessionId, sessionRef, lease };
+    this.#reasonCode = null;
+  }
+
+  dispatchAllowed(ctx: ExtensionContext): boolean {
+    const binding = this.#binding;
+    if (!binding || binding.rawSessionId !== ctx.sessionManager.getSessionId()) return false;
+    const current = this.#leases.inspect(binding.sessionRef);
+    const exact = current.state === "terminal-owned" && current.ownerEpoch === binding.lease.ownerEpoch
+      && current.gatewayInstanceRef === this.#terminalInstanceRef && current.runtimeInstanceRef === this.#runtimeInstanceRef;
+    if (!exact) this.#reasonCode = current.state === "gateway-owned" ? "session-owned-by-gateway" : "terminal-session-lease-lost";
+    return exact;
+  }
+
+  reasonCode(): string { return this.#reasonCode ?? "terminal-session-lease-unavailable"; }
+
+  release(): void {
+    const binding = this.#binding;
+    this.#binding = null;
+    if (!binding?.lease.ownerEpoch) return;
+    try {
+      this.#leases.releaseTerminal(binding.sessionRef, binding.lease.ownerEpoch, this.#terminalInstanceRef, this.#runtimeInstanceRef);
+      this.#reasonCode = "terminal-session-released";
+    } catch {
+      this.#reasonCode = "terminal-session-release-unproven";
+    }
+  }
+}

package/packages/piagent-webui/extension/vscode-handoff.ts

@@ -0,0 +1,51 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type VSCodeHandoffResult = { state: "settled" | "rejected" | "uncertain"; reasonCode: string | null };
+
+function executable(candidate: string): string | null {
+  try {
+    if (!path.isAbsolute(candidate)) return null;
+    const resolved = fs.realpathSync.native(candidate), stat = fs.lstatSync(resolved);
+    if (!stat.isFile() || stat.isSymbolicLink()) return null;
+    fs.accessSync(resolved, fs.constants.X_OK); return resolved;
+  } catch { return null; }
+}
+
+export function discoverVSCodeCli(input: { platform?: NodeJS.Platform; pathValue?: string } = {}): string | null {
+  const platform = input.platform ?? process.platform, candidates: string[] = [];
+  if (platform === "darwin") candidates.push("/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code",
+    path.join(os.homedir(), "Applications/Visual Studio Code.app/Contents/Resources/app/bin/code"));
+  for (const directory of String(input.pathValue ?? process.env.PATH ?? "").split(path.delimiter))
+    if (directory && path.isAbsolute(directory)) candidates.push(path.join(directory, platform === "win32" ? "code.exe" : "code"));
+  for (const candidate of [...new Set(candidates)]) { const resolved = executable(candidate); if (resolved) return resolved; }
+  return null;
+}
+
+export class VSCodeHandoff {
+  readonly #cli: string | null; readonly #timeoutMs: number;
+  constructor(options: { cli?: string | null; timeoutMs?: number } = {}) {
+    this.#cli = options.cli === undefined ? discoverVSCodeCli() : options.cli ? executable(options.cli) : null;
+    this.#timeoutMs = Math.max(500, Math.min(30_000, options.timeoutMs ?? 8_000));
+  }
+  available(): boolean { return this.#cli !== null; }
+  async open(absolutePath: string, line: number | null, column: number | null): Promise<VSCodeHandoffResult> {
+    if (!this.#cli) return { state: "rejected", reasonCode: "vscode-cli-unavailable" };
+    const location = line === null ? absolutePath : `${absolutePath}:${line}${column === null ? "" : `:${column}`}`;
+    return new Promise((resolve) => {
+      let settled = false, stderrBytes = 0, timedOut = false;
+      const child = spawn(this.#cli!, ["--reuse-window", "--goto", location], { shell: false, windowsHide: true,
+        env: { PATH: process.env.PATH, HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE, TMPDIR: process.env.TMPDIR,
+          SystemRoot: process.env.SystemRoot, ComSpec: process.env.ComSpec }, stdio: ["ignore", "ignore", "pipe"] });
+      child.stderr.on("data", (chunk: Buffer) => { stderrBytes += chunk.length; if (stderrBytes > 64 * 1024) child.kill("SIGKILL"); });
+      const timer = setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, this.#timeoutMs); timer.unref?.();
+      child.once("error", () => { clearTimeout(timer); if (!settled) { settled = true; resolve({ state: "rejected", reasonCode: "vscode-launch-failed" }); } });
+      child.once("close", (code) => { clearTimeout(timer); if (settled) return; settled = true;
+        resolve(timedOut ? { state: "uncertain", reasonCode: "vscode-launch-timeout" }
+          : code === 0 && stderrBytes <= 64 * 1024 ? { state: "settled", reasonCode: null }
+            : { state: "rejected", reasonCode: "vscode-launch-failed" }); });
+    });
+  }
+}

package/packages/piagent-webui/gateway/control-socket.ts

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import net from "node:net";
+
+const MAX_MESSAGE_BYTES = 4_096;
+
+export type GatewayControlRequest = { action: "health" | "issue-launch-url" | "stop" };
+export type GatewayControlResponse = { ok: true; value: unknown } | { ok: false; error: string };
+
+export async function requestGatewayControl(socketPath: string, request: GatewayControlRequest, timeoutMs = 1_500): Promise<GatewayControlResponse> {
+  return await new Promise((resolve, reject) => {
+    const socket = net.createConnection({ path: socketPath });
+    let body = "", settled = false;
+    const finish = (callback: () => void) => { if (settled) return; settled = true; clearTimeout(timer); socket.destroy(); callback(); };
+    const timer = setTimeout(() => finish(() => reject(new Error("gateway-control-timeout"))), timeoutMs);
+    socket.setEncoding("utf8");
+    socket.once("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on("data", (chunk) => {
+      body += chunk;
+      if (Buffer.byteLength(body) > MAX_MESSAGE_BYTES) return finish(() => reject(new Error("gateway-control-response-limit")));
+      const newline = body.indexOf("\n");
+      if (newline < 0) return;
+      finish(() => {
+        try { resolve(JSON.parse(body.slice(0, newline)) as GatewayControlResponse); }
+        catch { reject(new Error("gateway-control-response-invalid")); }
+      });
+    });
+    socket.once("error", (error) => finish(() => reject(error)));
+  });
+}
+
+async function removeStaleSocket(socketPath: string): Promise<void> {
+  let before: fs.Stats;
+  try { before = fs.lstatSync(socketPath); }
+  catch { return; }
+  if (!before.isSocket() || before.isSymbolicLink()) throw new Error("gateway-control-path-invalid");
+  try {
+    const live = await requestGatewayControl(socketPath, { action: "health" }, 500);
+    if (live.ok) throw new Error("gateway-already-running");
+  } catch (error) {
+    if (error instanceof Error && error.message === "gateway-already-running") throw error;
+  }
+  const after = fs.lstatSync(socketPath);
+  if (!after.isSocket() || after.dev !== before.dev || after.ino !== before.ino) throw new Error("gateway-control-path-race");
+  fs.unlinkSync(socketPath);
+}
+
+export async function startGatewayControlSocket(options: {
+  socketPath: string;
+  handle(request: GatewayControlRequest): Promise<GatewayControlResponse> | GatewayControlResponse;
+}): Promise<{ close(): Promise<void> }> {
+  await removeStaleSocket(options.socketPath);
+  const server = net.createServer((socket) => {
+    socket.setEncoding("utf8");
+    let body = "", finished = false;
+    const fail = (error: string) => { if (finished) return; finished = true; socket.end(`${JSON.stringify({ ok: false, error })}\n`); };
+    socket.on("data", (chunk) => {
+      if (finished) return;
+      body += chunk;
+      if (Buffer.byteLength(body) > MAX_MESSAGE_BYTES) return fail("request-limit");
+      const newline = body.indexOf("\n");
+      if (newline < 0) return;
+      finished = true;
+      void (async () => {
+        let request: GatewayControlRequest;
+        try {
+          const parsed = JSON.parse(body.slice(0, newline)) as Partial<GatewayControlRequest>;
+          if (!parsed || !["health", "issue-launch-url", "stop"].includes(String(parsed.action))
+            || Object.keys(parsed).some((key) => key !== "action")) throw new Error("invalid");
+          request = parsed as GatewayControlRequest;
+        } catch { socket.end(`${JSON.stringify({ ok: false, error: "invalid-request" })}\n`); return; }
+        try { socket.end(`${JSON.stringify(await options.handle(request))}\n`); }
+        catch { socket.end(`${JSON.stringify({ ok: false, error: "control-failed" })}\n`); }
+      })();
+    });
+    socket.once("error", () => { socket.destroy(); });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.socketPath, resolve);
+  });
+  fs.chmodSync(options.socketPath, 0o600);
+  const identity = fs.lstatSync(options.socketPath);
+  return {
+    close: async () => {
+      await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+      try {
+        const current = fs.lstatSync(options.socketPath);
+        if (current.isSocket() && current.dev === identity.dev && current.ino === identity.ino) fs.unlinkSync(options.socketPath);
+      } catch { /* already removed */ }
+    }
+  };
+}

package/packages/piagent-webui/gateway/extension-authority.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+
+type ExtensionLoadResult = {
+  extensions: Array<{ path: string; resolvedPath: string }>;
+  errors: Array<{ path: string; error: string }>;
+  runtime: unknown;
+};
+
+const PIAGENT_GUARD_SUFFIX = path.join("packages", "piagent-core", "extensions", "piagent-guard.ts");
+
+function canonicalExtensionPath(value: string): string {
+  try { return fs.realpathSync.native(value); }
+  catch { return path.resolve(value); }
+}
+
+function isPiagentGuardPath(value: string): boolean {
+  const normalized = path.normalize(value);
+  return normalized === PIAGENT_GUARD_SUFFIX || normalized.endsWith(`${path.sep}${PIAGENT_GUARD_SUFFIX}`);
+}
+
+export function preferAuthoritativePiagentGuard(
+  guardPath: string
+): (base: ExtensionLoadResult) => ExtensionLoadResult {
+  const authoritative = canonicalExtensionPath(guardPath);
+  const authorityAliases = [guardPath, path.resolve(guardPath), authoritative].map((value) => path.normalize(value));
+  return (base) => {
+    const loadedAuthoritative = base.extensions.some((extension) =>
+      canonicalExtensionPath(extension.resolvedPath || extension.path) === authoritative);
+    if (!loadedAuthoritative) return base;
+    const removed = new Set<string>();
+    const extensions = base.extensions.filter((extension) => {
+      const resolved = canonicalExtensionPath(extension.resolvedPath || extension.path);
+      const duplicate = resolved !== authoritative && isPiagentGuardPath(resolved);
+      if (duplicate) removed.add(resolved);
+      return !duplicate;
+    });
+    if (removed.size === 0) return base;
+    const errors = base.errors.filter((diagnostic) => {
+      const diagnosticPath = canonicalExtensionPath(diagnostic.path);
+      return !(removed.has(diagnosticPath)
+        && diagnostic.error.includes("conflicts with")
+        && authorityAliases.some((value) => diagnostic.error.includes(value)));
+    });
+    return { ...base, extensions, errors };
+  };
+}

package/packages/piagent-webui/gateway/gateway-events.ts

@@ -0,0 +1,60 @@
+export type GatewayEventKind = "catalog.changed" | "session.changed" | "runtime.changed" | "message.delta"
+  | "message.completed" | "tool.started" | "tool.completed";
+
+export type GatewayProtocolEvent = {
+  schemaVersion: 1;
+  version: "piagent-gateway-protocol-v1";
+  messageType: "event";
+  sequence: number;
+  stateVersion: number;
+  generatedAt: string;
+  kind: GatewayEventKind | "resync.required";
+  payload: Record<string, unknown>;
+};
+
+export class GatewayEventStore {
+  readonly #maximumCount: number;
+  readonly #maximumAgeMs: number;
+  #events: GatewayProtocolEvent[] = [];
+  #sequence = 0;
+  #listeners = new Set<(event: GatewayProtocolEvent) => void>();
+
+  constructor(options: { maximumCount?: number; maximumAgeMs?: number } = {}) {
+    this.#maximumCount = Math.max(1, Math.min(10_000, options.maximumCount ?? 1_000));
+    this.#maximumAgeMs = Math.max(1_000, Math.min(24 * 60 * 60_000, options.maximumAgeMs ?? 60 * 60_000));
+  }
+
+  get stateVersion(): number { return this.#sequence; }
+
+  #prune(now: number): void {
+    const cutoff = now - this.#maximumAgeMs;
+    while (this.#events.length > this.#maximumCount || this.#events[0] && Date.parse(this.#events[0].generatedAt) < cutoff) this.#events.shift();
+  }
+
+  publish(kind: GatewayEventKind, payload: Record<string, unknown>, now = new Date()): GatewayProtocolEvent {
+    if (!Number.isFinite(now.getTime())) throw new Error("gateway-event-time-invalid");
+    this.#sequence += 1;
+    const event: GatewayProtocolEvent = {
+      schemaVersion: 1, version: "piagent-gateway-protocol-v1", messageType: "event",
+      sequence: this.#sequence, stateVersion: this.#sequence, generatedAt: now.toISOString(), kind, payload
+    };
+    this.#events.push(event); this.#prune(now.getTime());
+    for (const listener of this.#listeners) { try { listener(event); } catch { /* observers cannot block truth */ } }
+    return event;
+  }
+
+  subscribe(listener: (event: GatewayProtocolEvent) => void): () => void {
+    this.#listeners.add(listener);
+    return () => { this.#listeners.delete(listener); };
+  }
+
+  replay(after: number | null): { state: "current" | "resync-required"; events: GatewayProtocolEvent[]; earliestSequence: number; currentSequence: number } {
+    this.#prune(Date.now());
+    const earliestSequence = this.#events[0]?.sequence ?? this.#sequence;
+    if (after !== null && after < Math.max(0, earliestSequence - 1)) {
+      return { state: "resync-required", events: [], earliestSequence, currentSequence: this.#sequence };
+    }
+    return { state: "current", events: after === null ? [] : this.#events.filter((event) => event.sequence > after), earliestSequence,
+      currentSequence: this.#sequence };
+  }
+}

package/packages/piagent-webui/gateway/gateway-protocol-service.ts

@@ -0,0 +1,64 @@
+import type { PiagentGatewayCapabilityHandshakeV1 } from "../contracts/generated/gateway-capabilities-v1.ts";
+import type { Catalog, SessionDetail } from "../contracts/generated/session-catalog-v1.ts";
+import type { GatewayProtocolHandler, GatewayRequest } from "../server/gateway-websocket.ts";
+import { GatewayEventStore } from "./gateway-events.ts";
+
+type ListParams = { cursor: string | null; limit: number; filter: "active" | "archived" | "all"; query: string | null; projectRef: string | null };
+
+export class GatewayProtocolFailure extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+  constructor(code: string, retryable = false) { super(code); this.code = code; this.retryable = retryable; }
+}
+
+export class GatewayProtocolService implements GatewayProtocolHandler {
+  readonly events: GatewayEventStore;
+  readonly #capabilities: () => PiagentGatewayCapabilityHandshakeV1;
+  readonly #catalog: () => Promise<Catalog>;
+  readonly #command?: { execute(command: unknown): Promise<unknown> };
+
+  constructor(options: {
+    capabilities(): PiagentGatewayCapabilityHandshakeV1;
+    catalog(): Promise<Catalog>;
+    events?: GatewayEventStore;
+    command?: { execute(command: unknown): Promise<unknown> };
+  }) {
+    this.#capabilities = options.capabilities;
+    this.#catalog = options.catalog;
+    this.#command = options.command;
+    this.events = options.events ?? new GatewayEventStore();
+  }
+
+  capabilities(): PiagentGatewayCapabilityHandshakeV1 { return this.#capabilities(); }
+
+  async execute(request: GatewayRequest): Promise<unknown> {
+    if (request.method === "gateway.health") return this.#capabilities();
+    if (request.method === "sessions.command") {
+      if (!this.#command) throw new GatewayProtocolFailure("session-actions-unavailable");
+      try { return await this.#command.execute(request.params.command); }
+      catch (error) { throw new GatewayProtocolFailure(error instanceof Error ? error.message : "invalid-session-command"); }
+    }
+    const catalog = await this.#catalog();
+    if (catalog.state !== "ready") throw new GatewayProtocolFailure(catalog.reasonCode ?? "catalog-unavailable", true);
+    if (request.method === "sessions.get") {
+      const session = catalog.sessions.find((item) => item.sessionRef === request.params.sessionRef);
+      if (!session) throw new GatewayProtocolFailure("session-not-found");
+      const detail: SessionDetail = {
+        schemaVersion: 1, version: "piagent-session-detail-v1", generatedAt: new Date().toISOString(),
+        gatewayInstanceRef: catalog.gatewayInstanceRef, catalogRevision: catalog.catalogRevision!, session
+      };
+      return detail;
+    }
+    const params = request.params as ListParams;
+    if (params.cursor !== null) throw new GatewayProtocolFailure("catalog-cursor-unavailable", true);
+    const query = params.query?.toLocaleLowerCase() ?? null;
+    const filtered = catalog.sessions.filter((item) => (params.filter === "all" || (params.filter === "archived") === item.archived)
+      && (!params.projectRef || item.projectRef === params.projectRef)
+      && (!query || `${item.title} ${item.projectLabel} ${item.preview}`.toLocaleLowerCase().includes(query)));
+    const sessions = filtered.slice(0, params.limit);
+    return {
+      ...catalog, sessions,
+      page: { limit: params.limit, returned: sessions.length, total: filtered.length, nextCursor: null, truncated: filtered.length > sessions.length }
+    } satisfies Catalog;
+  }
+}

package/packages/piagent-webui/gateway/gateway-service.ts

@@ -0,0 +1,215 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+import type { PiagentGatewayCapabilityHandshakeV1 } from "../contracts/generated/gateway-capabilities-v1.ts";
+import { startLoopbackServer } from "../server/loopback-server.ts";
+import { startGatewayControlSocket, type GatewayControlResponse } from "./control-socket.ts";
+import { loadPinnedPiHost } from "./pi-host.ts";
+import {
+  gatewayProfileState,
+  profileRef,
+  readOrCreateCatalogKey,
+  removeGatewayDescriptor,
+  writeGatewayDescriptor,
+  type GatewayDescriptor
+} from "./profile-state.ts";
+import { buildSessionCatalog } from "./session-catalog.ts";
+import { SessionMetadataStore } from "./session-metadata-store.ts";
+import { GatewayProtocolService } from "./gateway-protocol-service.ts";
+import { SessionLeaseStore } from "./session-lease-store.ts";
+import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
+import { SessionCommandStore } from "./session-command-store.ts";
+import { SessionCommandController } from "./session-command-controller.ts";
+import { GatewayEventStore } from "./gateway-events.ts";
+import { SessionInspectionRegistry } from "./session-inspection-registry.ts";
+import { ProjectRegistry } from "./project-registry.ts";
+import { pickNativeProjectFolders } from "./native-project-picker.ts";
+import { ProviderAuthBroker } from "./provider-auth-broker.ts";
+import { McpAuthBroker } from "./mcp-auth-broker.ts";
+
+function unavailable(reasonCode: string) {
+  return { status: "unavailable" as const, version: null, reasonCode };
+}
+
+function available(version = 1) { return { status: "available" as const, version, reasonCode: null }; }
+
+function safeModelLabel(value: unknown): string {
+  return (redactSensitiveText(String(value ?? "Model")).text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim() || "Model").slice(0, 120);
+}
+
+function capabilities(gatewayInstanceRef: string, runtimeAvailable = false): PiagentGatewayCapabilityHandshakeV1 {
+  return {
+    schemaVersion: 1,
+    version: "piagent-gateway-capabilities-v1",
+    generatedAt: new Date().toISOString(),
+    gatewayInstanceRef,
+    protocol: { minimum: 1, maximum: 1, selected: 1, compatibility: "ready" },
+    mode: runtimeAvailable ? "full" : "read-only",
+    capabilities: {
+      catalog: available(),
+      events: available(),
+      terminalAdapter: runtimeAvailable ? available() : unavailable("terminal-adapter-not-enabled"),
+      sessionRuntime: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+      sessionActions: {
+        create: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        send: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        abort: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        setModel: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        setThinking: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        setPermission: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        rename: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        pin: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        archive: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        unarchive: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        fork: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        acquire: runtimeAvailable ? available() : unavailable("session-owner-lease-not-enabled"),
+        release: runtimeAvailable ? available() : unavailable("session-owner-lease-not-enabled")
+      }
+    },
+    reasonCode: null
+  };
+}
+
+export async function startPiagentGateway(options: {
+  packageRoot: string;
+  expectedPiVersion: string;
+  agentDir?: string;
+}): Promise<{ descriptor: GatewayDescriptor; wait(): Promise<void>; close(): Promise<void> }> {
+  const state = gatewayProfileState(options.agentDir);
+  process.env.PI_CODING_AGENT_DIR = state.agentDir;
+  const key = readOrCreateCatalogKey(state);
+  const metadata = new SessionMetadataStore(state.root, key);
+  const projects = new ProjectRegistry(state.root, key);
+  const gatewayInstanceRef = `gateway_${process.pid}_${randomBytes(24).toString("base64url")}`;
+  const staticRoot = path.join(options.packageRoot, "packages", "piagent-webui", "dist", "client");
+  if (!fs.existsSync(path.join(staticRoot, "index.html"))) throw new Error("gateway-webui-build-missing");
+
+  let descriptor: GatewayDescriptor | null = null;
+  let loopback: Awaited<ReturnType<typeof startLoopbackServer>> | null = null;
+  let control: Awaited<ReturnType<typeof startGatewayControlSocket>> | null = null;
+  let runtimes: SessionRuntimeSupervisor | null = null;
+  let mcpAuth: McpAuthBroker | null = null;
+  let closing: Promise<void> | null = null;
+  let settleWait: (() => void) | null = null;
+  const waited = new Promise<void>((resolve) => { settleWait = resolve; });
+
+  const close = async () => {
+    if (closing) return await closing;
+    closing = (async () => {
+      removeGatewayDescriptor(state, gatewayInstanceRef);
+      await loopback?.close().catch(() => undefined);
+      await mcpAuth?.close().catch(() => undefined);
+      await runtimes?.close().catch(() => undefined);
+      await control?.close().catch(() => undefined);
+      settleWait?.();
+    })();
+    return await closing;
+  };
+
+  const reply = (value: unknown): GatewayControlResponse => ({ ok: true, value });
+  control = await startGatewayControlSocket({
+    socketPath: state.controlSocket,
+    handle(request) {
+      if (request.action === "health") return reply(descriptor ?? { state: "starting", gatewayInstanceRef });
+      if (request.action === "issue-launch-url") {
+        if (!loopback) return { ok: false, error: "gateway-starting" };
+        return reply({ launchUrl: loopback.issueLaunchUrl(), gatewayInstanceRef });
+      }
+      setImmediate(() => { void close(); });
+      return reply({ stopping: true, gatewayInstanceRef });
+    }
+  });
+
+  try {
+    const host = await loadPinnedPiHost(options.expectedPiVersion);
+    const inspectionModels = await host.ModelRuntime.create({
+      authPath: path.join(state.agentDir, "auth.json"),
+      modelsPath: path.join(state.agentDir, "models.json"),
+      allowModelNetwork: false
+    });
+    const providerAuth = new ProviderAuthBroker(inspectionModels);
+    mcpAuth = new McpAuthBroker(state.agentDir);
+    const leases = new SessionLeaseStore(state.root, key);
+    const events = new GatewayEventStore();
+    runtimes = new SessionRuntimeSupervisor({
+      gatewayInstanceRef, key, leases, listSessions: () => host.SessionManager.listAll(),
+      host, agentDir: state.agentDir, packageRoot: options.packageRoot, modelRuntime: inspectionModels, events,
+      resolveProject: (projectRef) => projects.resolve(projectRef)
+    });
+    const readCatalog = () => buildSessionCatalog({
+      gatewayInstanceRef,
+      key,
+      listSessions: () => runtimes!.listSessions(),
+      readMetadata: () => metadata.read(),
+      readOwnership: (sessionRef) => runtimes!.ownership(sessionRef),
+      readSessionOptions: (info) => {
+        try {
+          const context = host.SessionManager.open(info.path).buildSessionContext();
+          const model = context.model ? inspectionModels.getModel(context.model.provider, context.model.modelId) : null;
+          const thinking = ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(context.thinkingLevel))
+            ? context.thinkingLevel : "unknown";
+          return { modelLabel: model ? safeModelLabel(model.name ?? model.id ?? context.model?.modelId) : null,
+            thinkingLevel: thinking };
+        } catch { return { modelLabel: null, thinkingLevel: "unknown" }; }
+      }
+    });
+    runtimes.setProjectionReader(async (sessionRef) => {
+      const catalog = await readCatalog(), session = catalog.sessions.find((item) => item.sessionRef === sessionRef);
+      if (catalog.state !== "ready" || !session) throw new Error("session-projection-unavailable");
+      return { sessionRevision: session.sessionRevision, liveState: session.liveState };
+    });
+    const commands = new SessionCommandController({ catalog: readCatalog, runtimes, metadata,
+      store: new SessionCommandStore(state.root, key), events });
+    const protocol = new GatewayProtocolService({ capabilities: () => capabilities(gatewayInstanceRef, true), catalog: readCatalog,
+      events, command: commands });
+    const inspections = new SessionInspectionRegistry({ gatewayInstanceRef, host, key, packageRoot: options.packageRoot,
+      models: inspectionModels, projects, mcpAuth });
+    loopback = await startLoopbackServer({
+      staticRoot,
+      mode: "gateway",
+      readCapabilities: () => capabilities(gatewayInstanceRef, true),
+      readSessionCatalog: readCatalog,
+      readSessionCreationOptions: () => inspections.creationOptions(),
+      readSessionModel: (sessionRef) => inspections.provider(sessionRef),
+      readSessionConnections: (sessionRef) => inspections.connections(sessionRef),
+      executeSessionConnection: (command) => inspections.executeConnectionCommand(command),
+      executeApproval: (approvalRef, decision) => runtimes!.decideApproval(approvalRef, decision),
+      readMcpAuthJob: (jobRef) => mcpAuth!.read(jobRef),
+      cancelMcpAuthJob: (jobRef) => mcpAuth!.cancel(jobRef),
+      readProviderAuthCatalog: () => providerAuth.catalog(),
+      readProviderAuthJob: (jobRef) => providerAuth.read(jobRef),
+      executeProviderAuth: (command) => {
+        const action = command && typeof command === "object" && !Array.isArray(command) ? (command as Record<string, unknown>).action : null;
+        if (action === "provider-auth.start") return providerAuth.start(command);
+        if (action === "provider-auth.respond") return providerAuth.respond(command);
+        if (action === "provider-auth.cancel") return providerAuth.cancel(command);
+        throw new Error("provider-auth-command-invalid");
+      },
+      executeProjectImport: async () => {
+        const imported = await pickNativeProjectFolders();
+        const registered = imported.map((folder) => projects.register(folder));
+        const project = registered[0]!;
+        events.publish("catalog.changed", { reasonCode: "project-imported" });
+        return { schemaVersion: 1, version: "piagent-project-import-result-v1", importedAt: new Date().toISOString(), project, projects: registered };
+      },
+      gatewayProtocol: protocol
+    });
+    descriptor = {
+      version: "piagent-gateway-descriptor-v1",
+      gatewayInstanceRef,
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+      origin: loopback.origin,
+      controlSocket: state.controlSocket,
+      profileRef: profileRef(state, key)
+    };
+    writeGatewayDescriptor(state, descriptor);
+  } catch (error) {
+    await close();
+    throw error;
+  }
+
+  return { descriptor, wait: () => waited, close };
+}