@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

package/packages/server/src/home-lock.js

@@ -0,0 +1,330 @@
+/**
+ * Per-HOME advisory lock for the dashboard server.
+ *
+ * Ensures one dashboard instance per HOME (`<realpath(os.homedir())>/.pi/`).
+ * See change: single-dashboard-per-home.
+ *
+ * Responsibilities:
+ *   - Canonicalize HOME (avoid symlink/Git-Bash drift)
+ *   - Acquire the lock via `proper-lockfile` (non-blocking, stale-aware)
+ *   - Write / read an atomic metadata sidecar
+ *   - Verify a held lock's liveness via identity-checked health probe
+ *   - Return an `acquired` or `attach` result for the caller to dispatch
+ *
+ * Signal handlers and release-on-exit plumbing live in
+ * `home-lock-release.ts` to keep this module pure + testable.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import properLockfile from "proper-lockfile";
+import { isDashboardRunning } from "@blackbelt-technology/pi-dashboard-shared/server-identity.js";
+import { isProcessAlive } from "@blackbelt-technology/pi-dashboard-shared/platform/process.js";
+/** Thrown when port is held by an unrelated process. Non-fatal to this
+ *  module; caller decides (exit with message / retry / override). */
+export class InstanceLockMismatchError extends Error {
+    meta;
+    observedIdentity;
+    code = "E_INSTANCE_MISMATCH";
+    constructor(meta, observedIdentity) {
+        super(`Port ${meta.httpPort} is in use by an unrelated process (PID ${meta.pid}). ` +
+            `Configure a different port or stop that process.`);
+        this.meta = meta;
+        this.observedIdentity = observedIdentity;
+    }
+}
+// ──────────────────────────────────────────────────────────
+// Paths
+// ──────────────────────────────────────────────────────────
+/**
+ * Canonical HOME directory.
+ *
+ * Uses `os.userInfo().homedir` in preference to `os.homedir()` because on
+ * POSIX the latter honors the `$HOME` environment variable (Node docs say:
+ * "On POSIX, it uses the `$HOME` environment variable if defined"), which
+ * the design (§4) explicitly prohibits — a GUI-launched process and a
+ * shell-launched process would otherwise disagree on "where HOME is".
+ * `userInfo().homedir` consults `getpwuid(3)` on POSIX, immune to `$HOME`.
+ *
+ * On Windows, both APIs ultimately use `USERPROFILE`, so the Git Bash
+ * drift case (`$HOME=/c/Users/R` vs `USERPROFILE=C:\Users\R`) is handled
+ * either way; keeping `userInfo().homedir` first is still correct.
+ *
+ * Result is then passed through `fs.realpathSync` to collapse symlinks,
+ * FileVault migrations, and other canonicalization drift. Tolerant: falls
+ * back to the raw path if realpath fails.
+ */
+export function canonicalHomedir() {
+    let raw;
+    try {
+        raw = os.userInfo().homedir;
+    }
+    catch {
+        raw = os.homedir();
+    }
+    try {
+        return fs.realpathSync(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/**
+ * Lock file path. This is what `proper-lockfile` locks.
+ */
+export function getLockPath(homedir = canonicalHomedir()) {
+    return path.join(homedir, ".pi", "dashboard", "server.lock");
+}
+/**
+ * Metadata sidecar path (`<lockPath>.meta.json`).
+ */
+export function getMetaPath(lockPath = getLockPath()) {
+    return `${lockPath}.meta.json`;
+}
+// ──────────────────────────────────────────────────────────
+// Metadata I/O
+// ──────────────────────────────────────────────────────────
+/**
+ * Atomically write the metadata sidecar via tmp + rename.
+ * Never leaves a partial file visible.
+ */
+export function writeMetadataAtomic(meta, metaPath = getMetaPath()) {
+    const dir = path.dirname(metaPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = `${metaPath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(meta, null, 2));
+    fs.renameSync(tmpPath, metaPath);
+}
+/**
+ * Read the metadata sidecar. Returns null on any failure (missing, corrupt,
+ * permission-denied). Callers MUST treat null as "assume stale."
+ */
+export function readMetadata(metaPath = getMetaPath()) {
+    try {
+        const raw = fs.readFileSync(metaPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!isLockMetadata(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function isLockMetadata(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const m = value;
+    return (typeof m.pid === "number" &&
+        typeof m.httpPort === "number" &&
+        typeof m.piPort === "number" &&
+        typeof m.startedAt === "number" &&
+        typeof m.identity === "string" &&
+        typeof m.version === "string" &&
+        typeof m.url === "string");
+}
+/**
+ * Remove the metadata sidecar. Silent on any error (missing is fine).
+ */
+export function removeMetadata(metaPath = getMetaPath()) {
+    try {
+        fs.unlinkSync(metaPath);
+    }
+    catch {
+        /* ignore */
+    }
+}
+// ──────────────────────────────────────────────────────────
+// Liveness
+// ──────────────────────────────────────────────────────────
+/**
+ * Determine if the recorded lock holder is a responsive, identity-matching
+ * dashboard. Returns:
+ *   - `"alive-match"`: attach to it
+ *   - `"alive-mismatch"`: someone else is on that port
+ *   - `"dead"`: treat as stale, proceed to acquire
+ */
+export async function isLockHolderResponsive(meta, hooks = {}) {
+    const aliveCheck = hooks.isProcessAlive ?? isProcessAlive;
+    if (!aliveCheck(meta.pid))
+        return "dead";
+    const probe = hooks.probeHealth ?? defaultProbeHealth;
+    const res = await probe(meta.httpPort);
+    if (!res || !res.running)
+        return "dead";
+    // Identity check: `identity` field is preferred; fall back to PID match
+    // to stay compatible with older dashboards that predate identity.
+    if (res.identity) {
+        return res.identity === meta.identity ? "alive-match" : "alive-mismatch";
+    }
+    if (typeof res.pid === "number") {
+        return res.pid === meta.pid ? "alive-match" : "alive-mismatch";
+    }
+    // Running but no verifiable identity — conservative: mismatch.
+    return "alive-mismatch";
+}
+async function defaultProbeHealth(port) {
+    const status = await isDashboardRunning(port);
+    if (!status.running)
+        return { running: false };
+    // `isDashboardRunning` doesn't expose identity today. Re-fetch to peek at
+    // the full health body for the `identity` field. Best-effort.
+    try {
+        const res = await fetch(`http://localhost:${port}/api/health`, {
+            signal: AbortSignal.timeout(1500),
+        });
+        if (res.ok) {
+            const body = (await res.json());
+            return { running: true, pid: body.pid, identity: body.identity };
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return { running: true, pid: status.pid };
+}
+// ──────────────────────────────────────────────────────────
+// Acquire
+// ──────────────────────────────────────────────────────────
+/**
+ * Acquire the per-HOME lock, or fall back to attach semantics if a live
+ * dashboard already holds it.
+ *
+ * Flow:
+ *   1. Ensure `~/.pi/dashboard/` exists (proper-lockfile requires parent).
+ *   2. `proper-lockfile.lock(path, { stale, retries: 0 })`
+ *      ↪ on success: write metadata, return { mode: "acquired", release }
+ *      ↪ on ELOCKED: read metadata, check liveness
+ *         - dead: steal via `proper-lockfile.lock({ realpath:false, stale: 0 })`
+ *                 (Note: proper-lockfile already does stale-stealing when
+ *                 `stale` is configured — we just retry once.)
+ *         - alive-match: return { mode: "attach", meta }
+ *         - alive-mismatch: throw InstanceLockMismatchError
+ */
+export async function acquireOrAttach(config) {
+    const hooks = config.hooks ?? {};
+    const lockPath = hooks.lockPath ?? getLockPath();
+    const metaPath = hooks.metaPath ?? getMetaPath(lockPath);
+    const staleMs = hooks.staleMs ?? 10_000;
+    const now = hooks.now ?? Date.now;
+    const hostname = hooks.hostname ?? os.hostname;
+    // Ensure the lock file's parent directory exists. proper-lockfile wants
+    // either the target file (which it creates alongside as `<path>.lock/`)
+    // or an existing file — we create an empty sentinel so the API is
+    // deterministic.
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    if (!fs.existsSync(lockPath)) {
+        fs.writeFileSync(lockPath, "# pi-dashboard per-HOME advisory lock\n");
+    }
+    const buildMeta = () => ({
+        pid: process.pid,
+        ppid: process.ppid,
+        httpPort: config.httpPort,
+        piPort: config.piPort,
+        startedAt: now(),
+        identity: config.identity ?? randomUUID(),
+        version: config.version,
+        url: `http://localhost:${config.httpPort}`,
+        hostname: hostname(),
+    });
+    const tryAcquire = async () => {
+        const release = await properLockfile.lock(lockPath, {
+            stale: staleMs,
+            retries: 0,
+            // proper-lockfile uses realpath by default; we already pass a
+            // realpath-based directory, so this is a no-op but kept explicit.
+            realpath: false,
+        });
+        const meta = buildMeta();
+        writeMetadataAtomic(meta, metaPath);
+        const releaseOnce = (() => {
+            let released = false;
+            return async () => {
+                if (released)
+                    return;
+                released = true;
+                try {
+                    await release();
+                }
+                catch {
+                    /* ignore — lock may have been compromised */
+                }
+                removeMetadata(metaPath);
+            };
+        })();
+        return { mode: "acquired", meta, release: releaseOnce };
+    };
+    try {
+        return await tryAcquire();
+    }
+    catch (err) {
+        if (!isELocked(err))
+            throw err;
+        // Someone else holds the lock. Decide: attach or error.
+        //
+        // Concurrent-launch race: if two callers race, the winner writes the
+        // metadata sidecar a few ms after acquiring. The loser hits ELOCKED
+        // faster and can read the sidecar BEFORE the winner has written it.
+        // Short-poll for metadata to land before concluding "no metadata = stale."
+        let meta = null;
+        for (let i = 0; i < 20; i++) {
+            meta = readMetadata(metaPath);
+            if (meta)
+                break;
+            await new Promise(r => setTimeout(r, 25));
+        }
+        if (!meta) {
+            // Truly no metadata after 500ms → assume stale/corrupt. Force steal.
+            removeMetadata(metaPath);
+            try {
+                return await tryAcquire();
+            }
+            catch (err2) {
+                if (!isELocked(err2))
+                    throw err2;
+                try {
+                    await properLockfile.unlock(lockPath, { realpath: false });
+                }
+                catch {
+                    /* ignore */
+                }
+                return await tryAcquire();
+            }
+        }
+        const liveness = await isLockHolderResponsive(meta, hooks);
+        if (liveness === "alive-match") {
+            return { mode: "attach", meta };
+        }
+        if (liveness === "alive-mismatch") {
+            throw new InstanceLockMismatchError(meta, null);
+        }
+        // Dead holder — steal.
+        try {
+            await properLockfile.unlock(lockPath, { realpath: false });
+        }
+        catch {
+            /* ignore */
+        }
+        removeMetadata(metaPath);
+        return await tryAcquire();
+    }
+}
+function isELocked(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const code = err.code;
+    return code === "ELOCKED";
+}
+// ──────────────────────────────────────────────────────────
+// Escape hatch
+// ──────────────────────────────────────────────────────────
+/**
+ * True when the user has opted out of the per-HOME lock. Caller should
+ * log a warning and skip acquireOrAttach when set.
+ */
+export function isLockDisabled(env = process.env) {
+    const raw = env.PI_DASHBOARD_ALLOW_MULTIPLE;
+    return raw === "1" || raw === "true";
+}
+//# sourceMappingURL=home-lock.js.map

package/packages/server/src/home-lock.js.map

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

package/packages/server/src/idle-timer.ts

@@ -12,9 +12,19 @@ export interface IdleTimer {
   setStopFn(fn: () => Promise<void>): void;
 }
 
+/**
+ * Predicate that returns true when one or more terminal PTYs are alive.
+ * The idle timer SHALL NOT shut down while terminals are active — a user
+ * with a long-running command (cargo build, tail -f, etc.) and no
+ * attached agent still expects the server to stay up.
+ * See change: fix-terminal-half-height-dual-mount.
+ */
+export type HasActiveTerminals = () => boolean;
+
 export function createIdleTimer(
   config: ServerConfig,
   piGateway: PiGateway,
+  hasActiveTerminals: HasActiveTerminals = () => false,
 ): IdleTimer {
   let idleTimer: ReturnType<typeof setTimeout> | null = null;
   let stopServer: (() => Promise<void>) | null = null;
@@ -25,7 +35,11 @@ export function createIdleTimer(
     cancel();
     idleTimer = setTimeout(async () => {
       const realIdleMs = Date.now() - lastConnectionTimestamp;
-      if (piGateway.connectionCount() > 0 || realIdleMs < config.shutdownIdleSeconds * 1000) {
+      if (
+        piGateway.connectionCount() > 0 ||
+        realIdleMs < config.shutdownIdleSeconds * 1000 ||
+        hasActiveTerminals()
+      ) {
         start();
         return;
       }

package/packages/server/src/pending-client-correlations.ts

@@ -0,0 +1,73 @@
+/**
+ * Maps `spawnToken` (server-minted UUID) → `requestId` (client-minted UUID).
+ *
+ * Recorded by `handleSpawnSession` / `handleResumeSession` when the browser
+ * supplied a `requestId`. Consumed by `event-wiring.ts` after a successful
+ * `linkByToken` so the eventual `session_added` broadcast can carry
+ * `spawnRequestId` for client-side auto-select / placeholder dismissal.
+ *
+ * In-memory only. 60s TTL aligned with `spawn-register-watchdog` recovery
+ * window so late registers can still surface the correlation.
+ *
+ * See change: spawn-correlation-token.
+ */
+
+const DEFAULT_TTL_MS = 60_000;
+
+interface Entry {
+  requestId: string;
+  recordedAt: number;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export interface PendingClientCorrelations {
+  /** Record `spawnToken → requestId` mapping. Overwrites any prior entry for the same token. */
+  record(spawnToken: string, requestId: string): void;
+  /** Consume the requestId for a spawnToken, or undefined if none / expired. */
+  consume(spawnToken: string): string | undefined;
+  /** Drop all entries (server shutdown / tests). */
+  dispose(): void;
+  /** Number of tracked entries (for tests). */
+  size(): number;
+}
+
+export interface PendingClientCorrelationsOptions {
+  ttlMs?: number;
+}
+
+export function createPendingClientCorrelations(
+  options?: PendingClientCorrelationsOptions,
+): PendingClientCorrelations {
+  const ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
+  const store = new Map<string, Entry>();
+
+  return {
+    record(spawnToken: string, requestId: string): void {
+      if (!spawnToken || !requestId) return;
+      const prior = store.get(spawnToken);
+      if (prior) clearTimeout(prior.timer);
+      const timer = setTimeout(() => {
+        store.delete(spawnToken);
+      }, ttlMs);
+      store.set(spawnToken, { requestId, recordedAt: Date.now(), timer });
+    },
+
+    consume(spawnToken: string): string | undefined {
+      if (!spawnToken) return undefined;
+      const entry = store.get(spawnToken);
+      if (!entry) return undefined;
+      clearTimeout(entry.timer);
+      store.delete(spawnToken);
+      return entry.requestId;
+    },
+
+    dispose(): void {
+      for (const entry of store.values()) clearTimeout(entry.timer);
+      store.clear();
+    },
+
+    size(): number {
+      return store.size;
+    },
+  };
+}

package/packages/server/src/pending-fork-registry.ts

@@ -1,6 +1,16 @@
 /**
  * Tracks pending fork operations to place forked sessions after their parent.
+ *
+ * Keyed by `spawnToken` (UUID minted at fork time). When the forked session's
+ * bridge sends `session_register.spawnToken`, the server consumes the entry
+ * and places the new sessionId after `parentSessionId` in the cwd's order.
+ *
+ * Replaces the prior cwd-FIFO keying which suffered the multi-fork-in-same-cwd
+ * race (second fork's `recordFork` would overwrite the first).
+ *
  * Entries expire after 30 seconds if not consumed.
+ *
+ * See change: spawn-correlation-token.
  */
 
 const EXPIRY_MS = 30_000;
@@ -11,10 +21,10 @@ interface PendingFork {
 }
 
 export interface PendingForkRegistry {
-  /** Record that a fork was initiated from parentSessionId in the given cwd. */
-  recordFork(cwd: string, parentSessionId: string): void;
-  /** Consume and return the parent session ID for a cwd, or undefined if none pending. */
-  consumeFork(cwd: string): string | undefined;
+  /** Record that a fork was initiated from `parentSessionId`, keyed by the spawn token. */
+  recordFork(spawnToken: string, parentSessionId: string): void;
+  /** Consume the parent session id for a spawn token, or undefined if none pending. */
+  consumeFork(spawnToken: string): string | undefined;
   /** Clear all pending entries and timers. */
   dispose(): void;
 }
@@ -23,23 +33,25 @@ export function createPendingForkRegistry(): PendingForkRegistry {
   const pending = new Map<string, PendingFork>();
 
   return {
-    recordFork(cwd: string, parentSessionId: string): void {
-      // Clear previous entry for same cwd
-      const existing = pending.get(cwd);
+    recordFork(spawnToken: string, parentSessionId: string): void {
+      if (!spawnToken) return;
+      // Clear any prior entry for the same token (idempotent re-record).
+      const existing = pending.get(spawnToken);
       if (existing) {
         clearTimeout(existing.timer);
       }
       const timer = setTimeout(() => {
-        pending.delete(cwd);
+        pending.delete(spawnToken);
       }, EXPIRY_MS);
-      pending.set(cwd, { parentSessionId, timer });
+      pending.set(spawnToken, { parentSessionId, timer });
     },
 
-    consumeFork(cwd: string): string | undefined {
-      const entry = pending.get(cwd);
+    consumeFork(spawnToken: string): string | undefined {
+      if (!spawnToken) return undefined;
+      const entry = pending.get(spawnToken);
       if (!entry) return undefined;
       clearTimeout(entry.timer);
-      pending.delete(cwd);
+      pending.delete(spawnToken);
       return entry.parentSessionId;
     },