@prismshadow/penguin-server 0.1.5 → 0.2.1

package/README.md

@@ -36,8 +36,8 @@ pnpm --filter @prismshadow/penguin-server start   # node dist/index.js
 ## Security notes (known MVP limits)
 
 - **CSRF**: session cookie is `SameSite=Lax` and writes accept only `Content-Type: application/json`; no CSRF token yet.
-- **No login rate limiting**: add throttling at a reverse proxy for public deployments.
-- **Built-in admin starts as `admin` / `penguin-2026`**: change it immediately (a banner keeps reminding until you do).
+- **Login throttling**: per-username exponential backoff after 5 consecutive failures (1s doubling to a 60s cap, `429 too_many_attempts` inside the window, reset on success; in-memory, so a restart clears it). Unknown usernames are throttled identically, so it is not an account-existence oracle. A reverse proxy can still add IP-level limits for public deployments.
+- **Built-in admin `admin` starts with a random initial password** of the form `penguin-1234`, printed once to the server console at seed time (`PENGUIN_SEED_ADMIN_PASSWORD` pins it for tests/e2e): change it immediately (a banner keeps reminding until you do).
 - Passwords use `node:crypto` scrypt (`scrypt$N$r$p$salt$hash`, timingSafeEqual); login sessions renew on a 7-day sliding window; the DB stores only the token's sha256.
 - Model credentials live in the Project's hidden 0600 config file; the API always masks them.
 - Behind a reverse proxy, disable response buffering for SSE paths (the server already sends `X-Accel-Buffering: no`) and forward `x-forwarded-proto` to enable Secure cookies.

package/dist/api/types.d.ts

@@ -57,9 +57,24 @@ interface MeResponse {
      * request, since it depends on the host the caller is using.
      */
     previewIsolated: boolean;
+    /**
+     * Whether this server runs in desktop mode (spawned by the desktop shell with
+     * PENGUIN_DESKTOP_TOKEN). The web app then hides the logout entry, the
+     * initial-password banner and the self-update entry, and omits the old-password
+     * field when changing the password. See design § "桌面端原型".
+     */
+    desktopMode: boolean;
+    /**
+     * How THIS session was established. Distinct from desktopMode: a browser signed into a
+     * desktop-mode server holds a "password" session and must still provide the old
+     * password when changing it — only "desktop" sessions (opened by the shell's one-shot
+     * token) may omit it.
+     */
+    sessionVia: "password" | "desktop";
 }
 interface PasswordChangeRequest {
-    oldPassword: string;
+    /** Omitted only by desktop-established sessions (desktop mode); required otherwise. */
+    oldPassword?: string;
     /** At least 8 characters. */
     newPassword: string;
 }
@@ -85,6 +100,12 @@ interface UiPrefs {
     lastProjectId?: string;
     /** Whether the "no API key configured" guide has already been shown: once ever (on first visit to the chat page). */
     credentialGuideSeen?: boolean;
+    /**
+     * Also list CLI-created Sessions in the sidebar (`cli=1` on the sessions list). Default
+     * off: the list then serves web rows straight from the DB, with no Trace-directory
+     * scanning (#139).
+     */
+    showCliSessions?: boolean;
     [key: string]: unknown;
 }
 interface PrefsResponse {
@@ -284,6 +305,42 @@ interface ModelTestResponse {
     tps?: number;
     message?: string;
 }
+/**
+ * PUT /api/projects/:p/models/default (owner): narrow default-model switch — flips the same
+ * top-level `default_model` the models page's whole-table PUT writes, without resending the
+ * table (and thus without touching credentials). The pair must name a configured model
+ * entry, exactly like the whole-table route's defaultModel validation.
+ */
+interface DefaultModelUpdateRequest {
+    provider: string;
+    modelId: string;
+}
+/** Response mirrors what GET models reports as `defaultModel`. */
+interface DefaultModelResponse {
+    defaultModel: ModelRefDto;
+}
+/**
+ * Per-Project new-chat defaults: prefill for the chat draft page. Every key is optional —
+ * an absent key means "not set" (the pre-existing behavior). Serves as the GET response,
+ * the PUT request body (whole-block replace: an omitted key clears it) and the PUT
+ * response (the stored block). The default MODEL is deliberately not here: it stays the
+ * top-level `default_model` served/written via the models routes (single-sourced with the
+ * models page).
+ */
+interface ChatDefaultsDto {
+    /** Preselected Agent; must reference an existing Agent of the Project (400 unknown_agent). */
+    agentId?: string;
+    /** Prefilled Workspace directory; absent/empty = auto temp directory. */
+    workspace?: string;
+    /** Prefilled approval mode; absent = the built-in "allow-all". */
+    approvalMode?: ApprovalMode;
+    /**
+     * Fallback thinking level for Agents whose config has no explicit `model.thinking_level`
+     * (resolution chain: Agent explicit > this project default > built-in "medium"). Never
+     * "none" — only the four selectable tiers.
+     */
+    thinkingLevel?: Exclude<ThinkingLevelName, "none">;
+}
 /** Read-only vault entry display: key name + masked value; plaintext is never sent. */
 interface VaultEntryInfo {
     key: string;
@@ -507,15 +564,57 @@ interface MessagesLiveTail {
     cursor: string;
     fragments: OmniMessage[];
 }
+/**
+ * Pagination envelope of a windowed `GET /messages` (`tailLimit` / `before` requests
+ * only; the parameterless full read never carries it). A window is a run of whole
+ * message-bearing units — one unit = one Task in the Web reducer's sense, opened by a
+ * main-session user prompt — cut so that no pairing (tool_call/output), compaction span
+ * or steering group ever splits across windows.
+ */
+interface MessagesPageInfo {
+    /**
+     * Cursor of this window's first unit (`<shardIndex>:<ordinal>`): pass it back as
+     * `before=` to fetch the previous window. Stable across requests and compaction —
+     * rotation opens a NEW shard and closed shards are immutable. Absent = this window
+     * reaches the very beginning of the transcript (no older history).
+     */
+    before?: string;
+    /**
+     * Outline turns (the Web conversation outline's entry rule) opened BEFORE this
+     * window: the client offsets its global `第 N 轮` numbering by this, so a partial
+     * window never mis-numbers. 0 when the window starts at the beginning.
+     */
+    earlierTurns: number;
+    /**
+     * Cumulative stats accrued before this window, seeded into the client's stats
+     * tracker so header chips and per-turn cumulative rows equal a full load:
+     * finished-Task elapsed, subagent token totals, and the last main-session
+     * session/context token readings.
+     */
+    prior: {
+        subagentTokens: number;
+        elapsedMs: number;
+        sessionTokens: number;
+        contextTokens: number;
+    };
+}
 /** Message history: the full messages and events from concatenating all of this Session's Trace files in order (excludes partial_*). */
 interface MessagesResponse {
     messages: OmniMessage[];
     /**
      * Present only while the Session is running/compacting: the in-progress stream tail
      * (open streaming fragments + the channel cursor they cover), so a client joining
-     * mid-stream can render the currently streaming message. Omitted when idle.
+     * mid-stream can render the currently streaming message. Omitted when idle. On
+     * windowed requests it rides TAIL pages only — a `before` page is immutable history
+     * and never carries it.
      */
     live?: MessagesLiveTail;
+    /**
+     * Present exactly on windowed requests (`tailLimit` / `before`): `messages` is then
+     * the requested window (subagent pointers inside it expanded as usual) rather than
+     * the full transcript. See MessagesPageInfo.
+     */
+    page?: MessagesPageInfo;
 }
 /**
  * A single Prompt's input parts: text, image (data: / http(s) URL), or an uploaded file.
@@ -593,16 +692,41 @@ interface TaskCreateResponse {
  * task POST).
  */
 interface SteerRequest {
-    /** Message text (trimmed server-side); may be empty when `images` carries the message. */
+    /** Message text (trimmed server-side); may be empty when `images` or `files` carries the message. */
     text: string;
     /**
      * Images sent with the steering message (`data:` or http(s) URLs, same rule as
      * `TaskInputPart.image_url`): delivered as user image messages right behind the
      * `[user_steering]` text. A model without vision receives them as scratchpad path lines
-     * instead, exactly as it would a Prompt's images. At least one of `text` / `images` must
-     * be non-empty.
+     * instead, exactly as it would a Prompt's images. At least one of `text` / `images` /
+     * `files` must be non-empty.
      */
     images?: string[];
+    /**
+     * File attachments riding the steering message — the same shape, caps and handling as a
+     * task input's `{type:"file"}` parts: written into the Session scratchpad and delivered
+     * as `[attached file: <path>]` lines on the `[user_steering]` text, so a file-only draft
+     * steers exactly like an image-only one instead of falling back to the follow-up queue.
+     */
+    files?: {
+        fileName: string;
+        dataUrl: string;
+    }[];
+}
+/**
+ * One steering message queued on the server but not yet delivered to the model (delivery
+ * happens at the next input assembly between turns). Carried on `task_state` events and the
+ * SSE subscribe snapshot so the composer's "steering queued" hint — including what was sent —
+ * survives reloads; entries leave the list as their `[user_steering]` message appears on the
+ * stream, and the whole list drops when the run exits (core discards undelivered steering).
+ */
+interface PendingSteeringInfo {
+    /** The message text as accepted (trimmed); may be empty when images/files carry the message. */
+    text: string;
+    /** Number of images that rode along. */
+    images: number;
+    /** Number of file attachments that rode along. */
+    files: number;
 }
 interface ApprovalDecisionRequest {
     decision: "allow" | "deny";
@@ -632,6 +756,8 @@ type ServerEvent =
     type: "task_state";
     state: SessionStatus;
     queued?: number;
+    /** Steering messages queued but not yet delivered (absent = none): lets the composer's hint and its content survive reloads. */
+    pendingSteering?: PendingSteeringInfo[];
 }
 /** The model-generated title after the first turn has been persisted (for in-place list updates). */
  | {
@@ -920,9 +1046,56 @@ interface AgentTraceDateGroup {
     date: string;
     sessions: AgentTraceSessionGroup[];
 }
-/** Agent → date → Session → Trace file drill-down browsing structure (reverse chronological). */
+/** One Trace file in the session-centric listing (`date` carried per file: one Session's shards can span date directories). */
+interface AgentTraceSessionFile {
+    index: number;
+    date: string;
+    sizeBytes: number;
+}
+/** One Session's Trace files merged across date directories (the paginated listing's unit). */
+interface AgentTraceSessionEntry {
+    sessionId: string;
+    /**
+     * Display title, resolved only for the returned page: the sessions DB title when one
+     * exists, else derived from the Session's first user prompt (bounded head-read of the
+     * earliest shard); absent when neither yields one (the client falls back to its
+     * default title — raw session ids are never rendered).
+     */
+    title?: string;
+    /**
+     * Sidebar category of this Session, from the same bounded classification the listing
+     * filters and counts with: archived exactly from the DB row; origin from the shared
+     * in-process registry / previously observed session_meta; a DB-untracked Session this
+     * process has not yet head-read falls into `active` until a page surfaces it (its
+     * head-read then registers the true origin for subsequent requests).
+     */
+    category: SessionCategory;
+    /** Workspace path locked at creation (DB row or observed session_meta); "" when unknown — the client's merged temp-group fallback. */
+    workspace: string;
+    /** Sorted by index ascending (a higher index is newer). */
+    files: AgentTraceSessionFile[];
+}
+/**
+ * Agent-level Trace browsing structure. Without `limit` the response is the legacy full
+ * drill-down (`dates`: Agent → date → Session → Trace file, reverse chronological) and the
+ * paging fields are absent. With `offset`/`limit` the response is session-group-centric:
+ * `sessions` carries the requested slice (newest first by sessionId desc — ids embed a
+ * timestamp, so that is reverse chronological) with titles and classification,
+ * `totalSessions` the session-group count (within `category` when one is given, so paging
+ * and the count agree), `counts` / `workspaceCounts` the per-category totals over ALL of
+ * the Agent's session groups (folder labels / workspace-mode group headers), and `dates`
+ * stays empty (per-file stats are only taken for the returned page).
+ */
 interface AgentTracesResponse {
     dates: AgentTraceDateGroup[];
+    /** Present only when the request paginates: the requested slice of Session groups, newest first. */
+    sessions?: AgentTraceSessionEntry[];
+    /** Present only when the request paginates: session-group count of the paged (category-filtered) set. */
+    totalSessions?: number;
+    /** Present only when the request paginates: per-category totals over all of the Agent's session groups. */
+    counts?: SessionCategoryCounts;
+    /** Present only when the request paginates: `counts` broken down by Workspace path ("" = unknown). */
+    workspaceCounts?: Record<string, SessionCategoryCounts>;
 }
 interface TraceImportRequest {
     /** Base64 of the Trace file content (JSON Lines; the first record must be `session_meta`). */
@@ -1174,6 +1347,7 @@ interface BenchmarkSummary {
 interface BenchmarksResponse {
     benchmarks: BenchmarkSummary[];
 }
+type CaseMaterial = "statement" | "rubric";
 /** Public Benchmark Case metadata. Rubric and Gold content are never included. */
 interface BenchmarkCaseSummary {
     id: string;
@@ -1216,6 +1390,18 @@ interface AgentSkillsResponse {
 interface SkillInstallRequest {
     names: string[];
 }
+/**
+ * POST /api/projects/:p/agents/:a/skills/archive: install one Skill from an uploaded zip.
+ * Layout: SKILL.md at the zip root, or exactly one top-level directory containing SKILL.md
+ * (the directory name is then the Skill name). 201 returns the refreshed installed list
+ * (AgentSkillsResponse); an already-installed name without `overwrite` is 409 `skill_exists`.
+ */
+interface SkillArchiveInstallRequest {
+    /** Base64-encoded zip archive (decoded size capped at 14MB, same as the Agent snapshot import). */
+    dataBase64: string;
+    /** Replace an already-installed Skill of the same name (deletes its directory first). */
+    overwrite?: boolean;
+}
 /** GET /api/version: the running server's release identity (from core's VERSION / BUILD_DATE). */
 interface VersionResponse {
     version: string;
@@ -1265,4 +1451,4 @@ interface UpdateRunResponse {
     needsRestart: boolean;
 }
 
-export type { AdminPasswordResetRequest, AdminUserCreateRequest, AdminUserCreateResponse, AdminUsersResponse, AgentCompactionConfigDto, AgentConfigDto, AgentConfigResponse, AgentConfigUpdateRequest, AgentCreateRequest, AgentCreateResponse, AgentImportRequest, AgentImportResponse, AgentModelConfigDto, AgentSkillsResponse, AgentSummary, AgentTraceDateGroup, AgentTraceFileRef, AgentTraceSessionGroup, AgentTracesResponse, AgentsResponse, ApprovalDecisionRequest, ApprovalMode, AuthLoginRequest, AuthResponse, BenchmarkCaseScore, BenchmarkCaseSummary, BenchmarkCasesResponse, BenchmarkEvaluation, BenchmarkRunScore, BenchmarkSummary, BenchmarksResponse, CredentialInfo, DirEntryInfo, DirListResponse, ErrorBody, FilesStatRequest, FilesStatResponse, GoalResponse, GoalServerEvent, GoalStateView, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MessagesLiveTail, MessagesResponse, ModelInfo, ModelPricingDto, ModelRefDto, ModelTestRequest, ModelTestResponse, ModelUpdateEntry, ModelsResponse, ModelsUpdateRequest, PasswordChangeRequest, PrefsResponse, ProjectCreateRequest, ProjectCreateResponse, ProjectRole, ProjectSummary, ProjectUpdateRequest, ProjectUpdateResponse, ProjectsResponse, RequestSpan, RetryNowResponse, ScheduleItem, ScheduleServerEvent, ScheduleStatus, ScheduleUpsertRequest, SchedulesResponse, ServerEvent, SessionCategory, SessionCategoryCounts, SessionCreateRequest, SessionCreateResponse, SessionInfo, SessionPatchRequest, SessionResponse, SessionSource, SessionStatus, SessionTracesResponse, SessionsResponse, SkillGroupItem, SkillInstallRequest, SkillLibraryResponse, SkillMetadataItem, SteerRequest, TaskCreateRequest, TaskCreateResponse, TaskInputPart, ToolCallSpan, TraceAnalysisResponse, TraceEventsResponse, TraceFileInfo, TraceImportRequest, TraceImportResponse, TraceModelSegment, TraceTaskStats, TraceToolSpan, UiPrefs, UpdateCheckResponse, UpdateRunResponse, UsageAgentCount, UsageBucket, UsageErrorCount, UsageErrorItem, UsageErrors, UsageErrorsPage, UsageGroupBy, UsageGroupRow, UsageResponse, UsageSuccessRate, UsageTrendPoint, UsageTrendPointInTrace, UserInfo, VaultEntryInfo, VaultEntryUpdate, VaultResponse, VaultUpdateRequest, VersionResponse, WorkspaceFileEntry, WorkspaceFilesResponse };
+export type { AdminPasswordResetRequest, AdminUserCreateRequest, AdminUserCreateResponse, AdminUsersResponse, AgentCompactionConfigDto, AgentConfigDto, AgentConfigResponse, AgentConfigUpdateRequest, AgentCreateRequest, AgentCreateResponse, AgentImportRequest, AgentImportResponse, AgentModelConfigDto, AgentSkillsResponse, AgentSummary, AgentTraceDateGroup, AgentTraceFileRef, AgentTraceSessionEntry, AgentTraceSessionFile, AgentTraceSessionGroup, AgentTracesResponse, AgentsResponse, ApprovalDecisionRequest, ApprovalMode, AuthLoginRequest, AuthResponse, BenchmarkCaseScore, BenchmarkCaseSummary, BenchmarkCasesResponse, BenchmarkEvaluation, BenchmarkRunScore, BenchmarkSummary, BenchmarksResponse, CaseMaterial, ChatDefaultsDto, CredentialInfo, DefaultModelResponse, DefaultModelUpdateRequest, DirEntryInfo, DirListResponse, ErrorBody, FilesStatRequest, FilesStatResponse, GoalResponse, GoalServerEvent, GoalStateView, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MessagesLiveTail, MessagesPageInfo, MessagesResponse, ModelInfo, ModelPricingDto, ModelRefDto, ModelTestRequest, ModelTestResponse, ModelUpdateEntry, ModelsResponse, ModelsUpdateRequest, PasswordChangeRequest, PendingSteeringInfo, PrefsResponse, ProjectCreateRequest, ProjectCreateResponse, ProjectRole, ProjectSummary, ProjectUpdateRequest, ProjectUpdateResponse, ProjectsResponse, RequestSpan, RetryNowResponse, ScheduleItem, ScheduleServerEvent, ScheduleStatus, ScheduleUpsertRequest, SchedulesResponse, ServerEvent, SessionCategory, SessionCategoryCounts, SessionCreateRequest, SessionCreateResponse, SessionInfo, SessionPatchRequest, SessionResponse, SessionSource, SessionStatus, SessionTracesResponse, SessionsResponse, SkillArchiveInstallRequest, SkillGroupItem, SkillInstallRequest, SkillLibraryResponse, SkillMetadataItem, SteerRequest, TaskCreateRequest, TaskCreateResponse, TaskInputPart, ToolCallSpan, TraceAnalysisResponse, TraceEventsResponse, TraceFileInfo, TraceImportRequest, TraceImportResponse, TraceModelSegment, TraceTaskStats, TraceToolSpan, UiPrefs, UpdateCheckResponse, UpdateRunResponse, UsageAgentCount, UsageBucket, UsageErrorCount, UsageErrorItem, UsageErrors, UsageErrorsPage, UsageGroupBy, UsageGroupRow, UsageResponse, UsageSuccessRate, UsageTrendPoint, UsageTrendPointInTrace, UserInfo, VaultEntryInfo, VaultEntryUpdate, VaultResponse, VaultUpdateRequest, VersionResponse, WorkspaceFileEntry, WorkspaceFilesResponse };

package/dist/chunk-V6KH4FRG.js

@@ -0,0 +1,76 @@
+// src/lock.ts
+import fs from "fs";
+import net from "net";
+import path from "path";
+var PROBE_TIMEOUT_MS = 500;
+function serverLockPath(root) {
+  return path.join(root, "server.lock");
+}
+function readServerLock(root) {
+  let raw;
+  try {
+    raw = fs.readFileSync(serverLockPath(root), "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid) || typeof parsed.port !== "number" || !Number.isInteger(parsed.port)) {
+      return null;
+    }
+    return { pid: parsed.pid, port: parsed.port, startedAt: String(parsed.startedAt ?? "") };
+  } catch {
+    return null;
+  }
+}
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function portAccepts(port) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: "127.0.0.1", port, timeout: PROBE_TIMEOUT_MS });
+    const done = (ok) => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+async function isServerLockAlive(lock) {
+  return pidAlive(lock.pid) && await portAccepts(lock.port);
+}
+async function liveServerLock(root) {
+  const lock = readServerLock(root);
+  if (!lock) return null;
+  return await isServerLockAlive(lock) ? lock : null;
+}
+function acquireServerLock(root, lock) {
+  const target = serverLockPath(root);
+  const tmp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(lock) + "\n");
+  fs.renameSync(tmp, target);
+}
+function releaseServerLock(root) {
+  try {
+    const lock = readServerLock(root);
+    if (lock && lock.pid === process.pid) fs.rmSync(serverLockPath(root));
+  } catch {
+  }
+}
+
+export {
+  serverLockPath,
+  readServerLock,
+  isServerLockAlive,
+  liveServerLock,
+  acquireServerLock,
+  releaseServerLock
+};
+//# sourceMappingURL=chunk-V6KH4FRG.js.map

package/dist/chunk-V6KH4FRG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lock.ts"],"sourcesContent":["/**\n * Root-level server instance lock (`<root>/server.lock`).\n *\n * web.db is single-process / single-writer (see db/database.ts), and two servers on one\n * data root would also double-run the schedule scheduler — so a data root admits one\n * server at a time. The lock records {pid, port, startedAt}; liveness requires BOTH the\n * pid to be alive AND the recorded port to accept a TCP connection, because either signal\n * alone false-positives (pids get recycled, ports get taken by unrelated processes). A\n * lock that fails the liveness check is stale and is simply overwritten by the next\n * server.\n *\n * Published as `@prismshadow/penguin-server/lock` (side-effect-free) so the CLI and the\n * desktop shell can pre-check a root without importing the package entry, which starts\n * listening. Docs: design § \"桌面端原型 · 数据根与实例互斥\".\n */\nimport fs from \"node:fs\";\nimport net from \"node:net\";\nimport path from \"node:path\";\n\nexport interface ServerLock {\n  pid: number;\n  port: number;\n  startedAt: string;\n}\n\n/** TCP probe budget: loopback either connects immediately or the port is dead. */\nconst PROBE_TIMEOUT_MS = 500;\n\nexport function serverLockPath(root: string): string {\n  return path.join(root, \"server.lock\");\n}\n\n/** Reads the lock file; a missing or malformed file reads as \"no lock\". */\nexport function readServerLock(root: string): ServerLock | null {\n  let raw: string;\n  try {\n    raw = fs.readFileSync(serverLockPath(root), \"utf8\");\n  } catch {\n    return null;\n  }\n  try {\n    const parsed = JSON.parse(raw) as Partial<ServerLock>;\n    if (\n      typeof parsed.pid !== \"number\" ||\n      !Number.isInteger(parsed.pid) ||\n      typeof parsed.port !== \"number\" ||\n      !Number.isInteger(parsed.port)\n    ) {\n      return null;\n    }\n    return { pid: parsed.pid, port: parsed.port, startedAt: String(parsed.startedAt ?? \"\") };\n  } catch {\n    return null;\n  }\n}\n\nfunction pidAlive(pid: number): boolean {\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch (err) {\n    // EPERM = the process exists but belongs to another user — still alive.\n    return (err as NodeJS.ErrnoException).code === \"EPERM\";\n  }\n}\n\nfunction portAccepts(port: number): Promise<boolean> {\n  return new Promise((resolve) => {\n    // 127.0.0.1 rather than localhost: this is a raw TCP liveness probe, not an App\n    // request, and the server binds 127.0.0.1 (plus ::1) on loopback setups.\n    const socket = net.connect({ host: \"127.0.0.1\", port, timeout: PROBE_TIMEOUT_MS });\n    const done = (ok: boolean) => {\n      socket.destroy();\n      resolve(ok);\n    };\n    socket.once(\"connect\", () => done(true));\n    socket.once(\"timeout\", () => done(false));\n    socket.once(\"error\", () => done(false));\n  });\n}\n\n/** True when the lock's process is alive AND its port accepts connections. */\nexport async function isServerLockAlive(lock: ServerLock): Promise<boolean> {\n  return pidAlive(lock.pid) && (await portAccepts(lock.port));\n}\n\n/** Convenience for pre-checks: the live lock on this root, or null (absent or stale). */\nexport async function liveServerLock(root: string): Promise<ServerLock | null> {\n  const lock = readServerLock(root);\n  if (!lock) return null;\n  return (await isServerLockAlive(lock)) ? lock : null;\n}\n\n/** Writes the lock atomically (tmp + rename; the parent directory must already exist). */\nexport function acquireServerLock(root: string, lock: ServerLock): void {\n  const target = serverLockPath(root);\n  const tmp = `${target}.${process.pid}.tmp`;\n  fs.writeFileSync(tmp, JSON.stringify(lock) + \"\\n\");\n  fs.renameSync(tmp, target);\n}\n\n/** Removes the lock if it is still ours (best-effort; never throws on shutdown paths). */\nexport function releaseServerLock(root: string): void {\n  try {\n    const lock = readServerLock(root);\n    if (lock && lock.pid === process.pid) fs.rmSync(serverLockPath(root));\n  } catch {\n    // Best-effort: a stale leftover is overwritten by the next server anyway.\n  }\n}\n"],"mappings":";AAeA,OAAO,QAAQ;AACf,OAAO,SAAS;AAChB,OAAO,UAAU;AASjB,IAAM,mBAAmB;AAElB,SAAS,eAAe,MAAsB;AACnD,SAAO,KAAK,KAAK,MAAM,aAAa;AACtC;AAGO,SAAS,eAAe,MAAiC;AAC9D,MAAI;AACJ,MAAI;AACF,UAAM,GAAG,aAAa,eAAe,IAAI,GAAG,MAAM;AAAA,EACpD,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI;AACF,UAAM,SAAS,KAAK,MAAM,GAAG;AAC7B,QACE,OAAO,OAAO,QAAQ,YACtB,CAAC,OAAO,UAAU,OAAO,GAAG,KAC5B,OAAO,OAAO,SAAS,YACvB,CAAC,OAAO,UAAU,OAAO,IAAI,GAC7B;AACA,aAAO;AAAA,IACT;AACA,WAAO,EAAE,KAAK,OAAO,KAAK,MAAM,OAAO,MAAM,WAAW,OAAO,OAAO,aAAa,EAAE,EAAE;AAAA,EACzF,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,SAAS,KAAsB;AACtC,MAAI;AACF,YAAQ,KAAK,KAAK,CAAC;AACnB,WAAO;AAAA,EACT,SAAS,KAAK;AAEZ,WAAQ,IAA8B,SAAS;AAAA,EACjD;AACF;AAEA,SAAS,YAAY,MAAgC;AACnD,SAAO,IAAI,QAAQ,CAAC,YAAY;AAG9B,UAAM,SAAS,IAAI,QAAQ,EAAE,MAAM,aAAa,MAAM,SAAS,iBAAiB,CAAC;AACjF,UAAM,OAAO,CAAC,OAAgB;AAC5B,aAAO,QAAQ;AACf,cAAQ,EAAE;AAAA,IACZ;AACA,WAAO,KAAK,WAAW,MAAM,KAAK,IAAI,CAAC;AACvC,WAAO,KAAK,WAAW,MAAM,KAAK,KAAK,CAAC;AACxC,WAAO,KAAK,SAAS,MAAM,KAAK,KAAK,CAAC;AAAA,EACxC,CAAC;AACH;AAGA,eAAsB,kBAAkB,MAAoC;AAC1E,SAAO,SAAS,KAAK,GAAG,KAAM,MAAM,YAAY,KAAK,IAAI;AAC3D;AAGA,eAAsB,eAAe,MAA0C;AAC7E,QAAM,OAAO,eAAe,IAAI;AAChC,MAAI,CAAC,KAAM,QAAO;AAClB,SAAQ,MAAM,kBAAkB,IAAI,IAAK,OAAO;AAClD;AAGO,SAAS,kBAAkB,MAAc,MAAwB;AACtE,QAAM,SAAS,eAAe,IAAI;AAClC,QAAM,MAAM,GAAG,MAAM,IAAI,QAAQ,GAAG;AACpC,KAAG,cAAc,KAAK,KAAK,UAAU,IAAI,IAAI,IAAI;AACjD,KAAG,WAAW,KAAK,MAAM;AAC3B;AAGO,SAAS,kBAAkB,MAAoB;AACpD,MAAI;AACF,UAAM,OAAO,eAAe,IAAI;AAChC,QAAI,QAAQ,KAAK,QAAQ,QAAQ,IAAK,IAAG,OAAO,eAAe,IAAI,CAAC;AAAA,EACtE,QAAQ;AAAA,EAER;AACF;","names":[]}