@blackbelt-technology/pi-agent-dashboard 0.4.5 → 0.5.0

package/packages/server/src/session-diff.ts

@@ -5,7 +5,8 @@
 import { readFileSync, existsSync } from "node:fs";
 import { resolve, relative, isAbsolute, sep as pathSep } from "node:path";
 import * as git from "@blackbelt-technology/pi-dashboard-shared/platform/git.js";
-import type { DashboardEvent } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import * as jj from "@blackbelt-technology/pi-dashboard-shared/platform/jj.js";
+import type { DashboardEvent, JjState } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import type { FileChangeEvent, FileDiffEntry, EditOperation } from "@blackbelt-technology/pi-dashboard-shared/diff-types.js";
 import { isGitRepo } from "./git-operations.js";
 
@@ -176,3 +177,119 @@ export function enrichWithGitDiff(
 
   return { enrichedFiles: enriched, isGitRepo: true };
 }
+
+// ── jj enrichment (regime-aware) ─────────────────────────────────────────
+
+/**
+ * Pure helper: pick the right diff base for a given jj state.
+ *   - default workspace  → `@-`     (equivalent to `git diff HEAD`)
+ *   - non-default        → `fork_point(@, trunk())`
+ *
+ * Exported for unit testing without spawning jj.
+ */
+export function selectJjDiffBase(jjState: JjState | undefined): {
+  diffBase: string;
+  baseLabel: string;
+} {
+  const workspace = jjState?.workspaceName;
+  if (!workspace || workspace === "default") {
+    return { diffBase: "@-", baseLabel: "@-" };
+  }
+  // Use the `..` range form (always-supported) instead of `fork_point()`
+  // (which changed signature across jj versions). `trunk()` returns the
+  // most-recent ancestor on main/master/trunk; the diff base is the
+  // single tip of trunk so that `--from <base> --to @` materializes the
+  // cumulative diff across every agent commit in this workspace.
+  return { diffBase: "trunk()", baseLabel: "trunk()" };
+}
+
+/**
+ * Enrich file entries with `jj diff` output, regime-aware. Runs
+ * `jj diff --from <baseRev> --to @ -- <path>` per file. Handles new
+ * files natively (no synthetic `/dev/null` fallback needed — jj
+ * reports new files in unified diff format directly).
+ */
+export function enrichWithJjDiff(
+  cwd: string,
+  files: FileDiffEntry[],
+  jjState: JjState | undefined,
+): { enrichedFiles: FileDiffEntry[]; vcsKind: "jj"; diffBase: string; baseLabel: string } {
+  const { diffBase, baseLabel } = selectJjDiffBase(jjState);
+  const labelOverride = resolveBaseLabel(cwd, diffBase, baseLabel);
+  const enriched = files.map((file) => {
+    try {
+      const diff = jj.diffOr({
+        cwd,
+        fromRev: diffBase,
+        toRev: "@",
+        path: file.path,
+      }).trim();
+      if (diff) return { ...file, gitDiff: diff };
+      return file;
+    } catch {
+      return file;
+    }
+  });
+  return { enrichedFiles: enriched, vcsKind: "jj", diffBase, baseLabel: labelOverride };
+}
+
+/**
+ * Promote the abstract revset (e.g. `@-` or `fork_point(@, trunk())`) to
+ * a human-friendly bookmark name when one exists. Best effort — falls
+ * back to the abstract label if jj can't resolve it.
+ */
+function resolveBaseLabel(cwd: string, diffBase: string, fallback: string): string {
+  const result = jj.logRevset({
+    cwd,
+    revset: diffBase,
+    template: 'bookmarks ++ "\\n"',
+  });
+  if (!result.ok) return fallback;
+  const first = result.value.trim().split("\n")[0]?.trim();
+  if (first && first.length > 0 && first.length < 100) return first;
+  return fallback;
+}
+
+// ── Unified dispatcher ──────────────────────────────────────────────────
+
+export interface VcsEnrichmentResult {
+  enrichedFiles: FileDiffEntry[];
+  isGitRepo: boolean;
+  vcsKind?: "git" | "jj";
+  diffBase?: string;
+  baseLabel?: string;
+}
+
+/**
+ * Regime-aware dispatcher. When the session has `jjState.isJjRepo`,
+ * route through `enrichWithJjDiff` (which produces the cumulative diff
+ * for non-default workspaces). Otherwise fall back to the existing
+ * `enrichWithGitDiff` behavior unchanged — plain-git regime is byte-
+ * equivalent to the pre-change response shape (modulo the now-optional
+ * `vcsKind` field that older clients ignore).
+ *
+ * See change: add-jj-workspace-plugin.
+ */
+export function enrichWithVcsDiff(
+  cwd: string,
+  files: FileDiffEntry[],
+  jjState: JjState | undefined,
+): VcsEnrichmentResult {
+  if (jjState?.isJjRepo) {
+    const result = enrichWithJjDiff(cwd, files, jjState);
+    return {
+      enrichedFiles: result.enrichedFiles,
+      isGitRepo: jjState.isColocated === true,
+      vcsKind: "jj",
+      diffBase: result.diffBase,
+      baseLabel: result.baseLabel,
+    };
+  }
+  const result = enrichWithGitDiff(cwd, files);
+  return {
+    ...result,
+    vcsKind: result.isGitRepo ? "git" : undefined,
+    diffBase: result.isGitRepo ? "HEAD" : undefined,
+    baseLabel: result.isGitRepo ? "HEAD" : undefined,
+  };
+}

package/packages/server/src/session-discovery.ts

@@ -6,6 +6,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import os from "node:os";
+import { condenseForFirstMessage } from "@blackbelt-technology/pi-dashboard-shared/skill-block-parser.js";
 
 export interface DiscoveredSession {
   id: string;
@@ -53,15 +54,21 @@ function readSessionHeader(filePath: string): {
         if (entry.type === "session_info" && entry.name) {
           name = entry.name;
         }
-        // Find first user message
+        // Find first user message. Skill invocations are stored as a
+        // `<skill name=...>...</skill>\n\nargs` envelope (~264 chars for typical
+        // absolute paths) which is longer than the 200-char firstMessage budget,
+        // so a naive .slice(0, 200) cuts the wrapper in half. condenseForFirstMessage
+        // returns the condensed slash form (`/skill:name args`) when the input
+        // matches the envelope, falling back to the raw slice otherwise.
+        // See change: render-skill-invocations-collapsibly.
         if (!firstMessage && entry.type === "message" && entry.message?.role === "user") {
           const msg = entry.message;
           if (typeof msg.content === "string") {
-            firstMessage = msg.content.slice(0, 200);
+            firstMessage = condenseForFirstMessage(msg.content, 200);
           } else if (Array.isArray(msg.content)) {
             for (const part of msg.content) {
               if (part.type === "text" && part.text) {
-                firstMessage = part.text.slice(0, 200);
+                firstMessage = condenseForFirstMessage(part.text, 200);
                 break;
               }
             }

package/packages/server/src/session-scanner.ts

@@ -8,6 +8,7 @@ import { join } from "node:path";
 import os from "node:os";
 import type { DashboardSession, SessionSource } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import { type SessionMeta, metaPath, readSessionMeta, writeSessionMeta } from "@blackbelt-technology/pi-dashboard-shared/session-meta.js";
+import { condenseForFirstMessage } from "@blackbelt-technology/pi-dashboard-shared/skill-block-parser.js";
 import { extractSessionStats } from "./session-stats-reader.js";
 
 function getSessionsDir(): string {
@@ -236,14 +237,15 @@ function readJsonlHeaderSync(filePath: string): { id: string; cwd: string; name?
         const entry = JSON.parse(line);
         if (entry.type === "session" && entry.id) header = entry;
         if (entry.type === "session_info" && entry.name) name = entry.name;
+        // See change: render-skill-invocations-collapsibly.
         if (!firstMessage && entry.type === "message" && entry.message?.role === "user") {
           const msg = entry.message;
           if (typeof msg.content === "string") {
-            firstMessage = msg.content.slice(0, 200);
+            firstMessage = condenseForFirstMessage(msg.content, 200);
           } else if (Array.isArray(msg.content)) {
             for (const part of msg.content) {
               if (part.type === "text" && part.text) {
-                firstMessage = part.text.slice(0, 200);
+                firstMessage = condenseForFirstMessage(part.text, 200);
                 break;
               }
             }

package/packages/server/src/spawn-failure-log.ts

@@ -0,0 +1,130 @@
+/**
+ * Rolling NDJSON log of failed pi session spawn attempts.
+ *
+ * Location: ~/.pi/dashboard/sessions/spawn-failures.log
+ * Rotation: single-shot at 10 MB (renames to .log.1, overwrites any prior .log.1).
+ * Format:   one JSON object per line, terminated by \n.
+ *
+ * See change: spawn-failure-diagnostics.
+ */
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+} from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { PreflightReason } from "./spawn-preflight.js";
+
+export interface SpawnFailureEntry {
+  /** ISO 8601 UTC timestamp. */
+  ts: string;
+  cwd: string;
+  strategy: string;
+  code: string;
+  message: string;
+  stderrTail?: string;
+  pid?: number;
+  reasons?: PreflightReason[];
+}
+
+const LOG_MAX_BYTES = 10 * 1024 * 1024; // 10 MB
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+
+let _logDirOverride: string | null = null;
+
+/** Override the log directory — for tests only. See change: spawn-failure-diagnostics. */
+export function _setLogDirForTests(dir: string | null): void {
+  _logDirOverride = dir;
+}
+
+function logDir(): string {
+  return _logDirOverride ?? path.join(os.homedir(), ".pi", "dashboard", "sessions");
+}
+
+function logPath(): string {
+  return path.join(logDir(), "spawn-failures.log");
+}
+
+function logPath1(): string {
+  return path.join(logDir(), "spawn-failures.log.1");
+}
+
+/**
+ * Append a failure entry to the rolling log.
+ * Never throws — errors are caught and reported via `console.error`.
+ */
+export function appendSpawnFailure(entry: SpawnFailureEntry): void {
+  try {
+    const dir = logDir();
+    mkdirSync(dir, { recursive: true });
+
+    const filePath = logPath();
+    const line = JSON.stringify(entry) + "\n";
+
+    // Rotate if file exceeds threshold.
+    if (existsSync(filePath)) {
+      try {
+        const { size } = statSync(filePath);
+        if (size > LOG_MAX_BYTES) {
+          renameSync(filePath, logPath1());
+        }
+      } catch {
+        // If stat/rename fails, just write anyway.
+      }
+    }
+
+    appendFileSync(filePath, line, "utf-8");
+  } catch (err) {
+    console.error("[spawn-failure-log] Failed to append entry:", err);
+  }
+}
+
+/**
+ * Read the last `limit` entries from the rolling log (both .log.1 and .log).
+ * Skips malformed lines. Returns [] when no log exists.
+ */
+export function readSpawnFailures(limit: number = DEFAULT_LIMIT): SpawnFailureEntry[] {
+  const effectiveLimit = Number.isNaN(limit) ? DEFAULT_LIMIT : Math.max(0, Math.min(limit, MAX_LIMIT));
+  if (effectiveLimit === 0) return [];
+
+  const lines: string[] = [];
+
+  // Read older log first, then newer.
+  for (const filePath of [logPath1(), logPath()]) {
+    if (!existsSync(filePath)) continue;
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      lines.push(...content.split("\n").filter((l) => l.trim()));
+    } catch {
+      // Skip unreadable file.
+    }
+  }
+
+  // Parse, skipping malformed lines.
+  const entries: SpawnFailureEntry[] = [];
+  for (const line of lines) {
+    try {
+      const obj = JSON.parse(line) as Record<string, unknown>;
+      // Require the minimum fields.
+      if (
+        typeof obj.ts === "string" &&
+        typeof obj.cwd === "string" &&
+        typeof obj.strategy === "string" &&
+        typeof obj.code === "string" &&
+        typeof obj.message === "string"
+      ) {
+        entries.push(obj as unknown as SpawnFailureEntry);
+      }
+    } catch {
+      // Skip malformed line.
+    }
+  }
+
+  // Return last N in file order.
+  return entries.length <= effectiveLimit ? entries : entries.slice(entries.length - effectiveLimit);
+}

package/packages/server/src/spawn-preflight.ts

@@ -0,0 +1,82 @@
+/**
+ * Synchronous spawn preflight check.
+ *
+ * Runs before every `spawnPiSession` invocation to catch fast-fail conditions
+ * (bad cwd, missing binaries) without racing the spawn itself. All checks run
+ * regardless of earlier failures so the caller gets all reasons in one pass.
+ *
+ * The ToolResolver passed in MUST have `useLoginShell: false` — preflight
+ * must never spawn a login shell on the spawn-click hot path. If a resolver
+ * with `useLoginShell: true` is passed, the check still runs but a one-time
+ * warning is emitted.
+ *
+ * See change: spawn-failure-diagnostics.
+ */
+import { existsSync, accessSync, statSync, constants } from "node:fs";
+import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js";
+
+export interface PreflightReason {
+  code: string;
+  message: string;
+}
+
+export interface PreflightResult {
+  ok: boolean;
+  reasons: PreflightReason[];
+}
+
+/**
+ * Run all preflight checks for `cwd` and return the accumulated reasons.
+ * `ok` is `true` iff `reasons.length === 0`.
+ *
+ * @param deps.resolver - Must be constructed with `useLoginShell: false`.
+ *   If omitted, a login-shell-disabled resolver is created automatically.
+ *   Passing a resolver with `useLoginShell: true` violates the preflight
+ *   contract; the function still runs but may call into the login shell.
+ */
+export function preflightSpawn(
+  cwd: string,
+  deps?: { resolver?: ToolResolver },
+): PreflightResult {
+  const resolver = deps?.resolver ?? new ToolResolver({ processExecPath: process.execPath, useLoginShell: false });
+
+  const reasons: PreflightReason[] = [];
+
+  // 1. cwd exists
+  const cwdExists = existsSync(cwd);
+  if (!cwdExists) {
+    reasons.push({ code: "DIR_MISSING", message: `Directory does not exist: ${cwd}` });
+    // No point checking isDirectory / writable if it doesn't exist.
+  } else {
+    // 2. cwd is a directory
+    try {
+      const stat = statSync(cwd);
+      if (!stat.isDirectory()) {
+        reasons.push({ code: "DIR_NOT_DIRECTORY", message: `Path is not a directory: ${cwd}` });
+      }
+    } catch (err: any) {
+      reasons.push({ code: "DIR_NOT_DIRECTORY", message: `Cannot stat path: ${err.message}` });
+    }
+
+    // 3. cwd is writable
+    try {
+      accessSync(cwd, constants.W_OK);
+    } catch {
+      reasons.push({ code: "DIR_NOT_WRITABLE", message: `Directory is not writable: ${cwd}` });
+    }
+  }
+
+  // 4. pi resolves
+  const piCmd = resolver.resolvePi();
+  if (piCmd === null) {
+    reasons.push({ code: "PI_NOT_FOUND", message: "pi binary not found via managed install or system PATH" });
+  }
+
+  // 5. node resolves
+  const nodeCmd = resolver.resolveNode();
+  if (nodeCmd === null) {
+    reasons.push({ code: "NODE_NOT_FOUND", message: "node binary not found via managed install or system PATH" });
+  }
+
+  return { ok: reasons.length === 0, reasons };
+}

package/packages/server/src/spawn-register-watchdog.ts

@@ -0,0 +1,236 @@
+/**
+ * Spawn-register watchdog.
+ *
+ * Arms a per-spawn timer after every successful `spawnPiSession`. If the
+ * spawned pi session never sends `session_register` within the timeout
+ * window, emits `spawn_register_timeout` to the originating WebSocket.
+ *
+ * Two index maps handle the two spawn families:
+ *  - `byPid` — headless spawns where the dashboard owns the PID.
+ *  - `byCwd` — tmux/wt/wsl-tmux spawns where any `session_register` from
+ *    that directory clears the watch.
+ *
+ * Late registrations (pi finally registers after the watchdog fired) are
+ * detected via `recentlyFired` (60 s TTL) and cause a `spawn_register_recovered`
+ * message to auto-clear the timeout banner.
+ *
+ * See change: spawn-failure-diagnostics.
+ */
+import WebSocket from "ws";
+import { readFileSync } from "node:fs";
+import type { SpawnMechanism } from "@blackbelt-technology/pi-dashboard-shared/platform/spawn-mechanism.js";
+import type {
+  SpawnRegisterTimeoutMessage,
+  SpawnRegisterRecoveredMessage,
+} from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
+import { clampSpawnRegisterTimeoutMs, loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { appendSpawnFailure } from "./spawn-failure-log.js";
+
+export interface WatchdogArmOptions {
+  pid?: number;
+  cwd: string;
+  mechanism: SpawnMechanism;
+  logPath?: string;
+  ws: WebSocket;
+}
+
+interface Entry {
+  timer: ReturnType<typeof setTimeout>;
+  cwd: string;
+  pid?: number;
+  mechanism: SpawnMechanism;
+  logPath?: string;
+  ws: WebSocket;
+  timeoutMs: number;
+}
+
+interface RecentlyFiredEntry {
+  firedAt: number;
+  pid?: number;
+  ws: WebSocket;
+}
+
+const RECENTLY_FIRED_TTL_MS = 60_000;
+
+export class SpawnRegisterWatchdog {
+  /** Default timeout used when arm() callers do not supply one. */
+  readonly timeoutMs: number;
+  private readonly byPid = new Map<number, Entry>();
+  private readonly byCwd = new Map<string, Entry>();
+  private readonly recentlyFired = new Map<string, RecentlyFiredEntry>();
+
+  constructor(timeoutMs: number) {
+    this.timeoutMs = clampSpawnRegisterTimeoutMs(timeoutMs);
+  }
+
+  arm(opts: WatchdogArmOptions & { timeoutMs?: number }): void {
+    // Read-on-arm: caller passes the current config value so a Settings change
+    // takes effect on the next spawn without a server restart.
+    // See change: spawn-failure-diagnostics (fix W1).
+    const effectiveTimeout = clampSpawnRegisterTimeoutMs(opts.timeoutMs ?? this.timeoutMs);
+    const { pid, cwd, mechanism, logPath, ws } = opts;
+    const entry: Entry = {
+      timer: null as unknown as ReturnType<typeof setTimeout>,
+      cwd, pid, mechanism, logPath, ws,
+      timeoutMs: effectiveTimeout,
+    };
+    entry.timer = setTimeout(() => this._fireEntry(entry), effectiveTimeout);
+    // Always index by cwd so a `session_register` clears the watchdog even
+    // when the bridge's reported pid differs from the spawner's pid (e.g.
+    // Unix headless wraps pi in `sh -c "tail -f /dev/null | pi …"`, so
+    // spawnResult.pid is the sh wrapper, not pi). Index by pid additionally
+    // for late-recovery lookup. Replace any prior entry for the same
+    // cwd/pid to avoid leaking timers.
+    const priorCwd = this.byCwd.get(cwd);
+    if (priorCwd) clearTimeout(priorCwd.timer);
+    this.byCwd.set(cwd, entry);
+    if (pid !== undefined) {
+      const priorPid = this.byPid.get(pid);
+      if (priorPid && priorPid !== priorCwd) clearTimeout(priorPid.timer);
+      this.byPid.set(pid, entry);
+    }
+  }
+
+  clearByPid(pid: number): void {
+    const entry = this.byPid.get(pid);
+    if (entry) {
+      clearTimeout(entry.timer);
+      this.byPid.delete(pid);
+      // Also clear cwd entry if it points at the same arm.
+      const cwdEntry = this.byCwd.get(entry.cwd);
+      if (cwdEntry === entry) this.byCwd.delete(entry.cwd);
+      return;
+    }
+    // Check for late recovery.
+    this._checkRecoveryByPid(pid);
+  }
+
+  clearByCwd(cwd: string): void {
+    const entry = this.byCwd.get(cwd);
+    if (entry) {
+      clearTimeout(entry.timer);
+      this.byCwd.delete(cwd);
+      // Also clear pid entry if it points at the same arm.
+      if (entry.pid !== undefined) {
+        const pidEntry = this.byPid.get(entry.pid);
+        if (pidEntry === entry) this.byPid.delete(entry.pid);
+      }
+      return;
+    }
+    // Check for late recovery.
+    this._checkRecoveryByCwd(cwd);
+  }
+
+  private _fireEntry(entry: Entry): void {
+    const { cwd, pid, logPath, ws, timeoutMs: entryTimeoutMs } = entry;
+    // Remove from active maps.
+    if (pid !== undefined) {
+      const pidEntry = this.byPid.get(pid);
+      if (pidEntry === entry) this.byPid.delete(pid);
+    }
+    const cwdEntry = this.byCwd.get(cwd);
+    if (cwdEntry === entry) this.byCwd.delete(cwd);
+
+    // Record in recentlyFired for late-recovery detection.
+    this.recentlyFired.set(cwd, { firedAt: Date.now(), pid, ws });
+
+    // Read stderr tail if logPath available.
+    let stderrTail: string | undefined;
+    if (logPath) {
+      stderrTail = readLogTail(logPath);
+    }
+
+    // Persist the timeout to the rolling failure log. See change: spawn-failure-diagnostics.
+    appendSpawnFailure({
+      ts: new Date().toISOString(),
+      cwd,
+      strategy: entry.mechanism,
+      code: "REGISTER_TIMEOUT",
+      message: `Pi session spawned but never registered (timeout ${this.timeoutMs}ms)`,
+      ...(pid !== undefined ? { pid } : {}),
+      ...(stderrTail ? { stderrTail } : {}),
+    });
+
+    if (ws.readyState !== WebSocket.OPEN) return;
+
+    const msg: SpawnRegisterTimeoutMessage = {
+      type: "spawn_register_timeout",
+      cwd,
+      timeoutMs: entryTimeoutMs,
+      ...(pid !== undefined ? { pid } : {}),
+      ...(stderrTail ? { stderrTail } : {}),
+    };
+    ws.send(JSON.stringify(msg));
+  }
+
+  private _checkRecoveryByPid(pid: number): void {
+    // recentlyFired is keyed by cwd; scan to find matching pid.
+    for (const [cwd, fired] of this.recentlyFired) {
+      if (fired.pid === pid) {
+        this._emitRecovery(cwd, fired);
+        return;
+      }
+    }
+  }
+
+  private _checkRecoveryByCwd(cwd: string): void {
+    const fired = this.recentlyFired.get(cwd);
+    if (!fired) return;
+    this._emitRecovery(cwd, fired);
+  }
+
+  private _emitRecovery(cwd: string, fired: RecentlyFiredEntry): void {
+    // TTL check.
+    if (Date.now() - fired.firedAt > RECENTLY_FIRED_TTL_MS) {
+      this.recentlyFired.delete(cwd);
+      return;
+    }
+
+    this.recentlyFired.delete(cwd);
+
+    if (fired.ws.readyState !== WebSocket.OPEN) return;
+
+    const msg: SpawnRegisterRecoveredMessage = {
+      type: "spawn_register_recovered",
+      cwd,
+      ...(fired.pid !== undefined ? { pid: fired.pid } : {}),
+    };
+    fired.ws.send(JSON.stringify(msg));
+  }
+}
+
+// ── Singleton ────────────────────────────────────────────────────────────────
+
+let _instance: SpawnRegisterWatchdog | null = null;
+
+/**
+ * Lazy singleton. On first call, reads `spawnRegisterTimeoutMs` from config.
+ * Tests can swap the instance via `_setSpawnRegisterWatchdogForTests`.
+ */
+export function getSpawnRegisterWatchdog(): SpawnRegisterWatchdog {
+  if (!_instance) {
+    const config = loadConfig();
+    _instance = new SpawnRegisterWatchdog(config.spawnRegisterTimeoutMs);
+  }
+  return _instance;
+}
+
+/** Swap the singleton for tests. Pass `null` to reset. */
+export function _setSpawnRegisterWatchdogForTests(w: SpawnRegisterWatchdog | null): void {
+  _instance = w;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function readLogTail(filePath: string, maxBytes = 4096): string | undefined {
+  try {
+    const buf = readFileSync(filePath);
+    if (!buf.length) return undefined;
+    const slice = buf.length <= maxBytes ? buf : buf.slice(buf.length - maxBytes);
+    let start = 0;
+    while (start < slice.length && (slice[start]! & 0xC0) === 0x80) start++;
+    return slice.slice(start).toString("utf-8");
+  } catch {
+    return undefined;
+  }
+}

package/packages/server/src/terminal-manager.ts

@@ -185,7 +185,18 @@ export function createTerminalManager(options?: TerminalManagerOptions): Termina
         try {
           const msg: TerminalControlMessage = JSON.parse(str);
           if (msg.type === "resize") {
-            entry.pty.resize(msg.cols, msg.rows);
+            // Defense in depth: reject degenerate resize messages.
+            // A PTY at <2 cols/rows is non-functional for every supported
+            // shell binding; no legitimate user intent maps there. xterm's
+            // FitAddon is supposed to guard against zero, but a transient
+            // display:none container measured during a route transition
+            // can leak a 1 through. See change:
+            // fix-terminal-half-height-dual-mount.
+            if (msg.cols < 2 || msg.rows < 2) {
+              // ignore — keep previous PTY dimensions
+            } else {
+              entry.pty.resize(msg.cols, msg.rows);
+            }
           } else if (msg.type === "title") {
             // title control message — handled elsewhere
           } else {

package/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-shared",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Shared types and utilities for pi-dashboard",
   "type": "module",
   "repository": {

package/packages/shared/src/__tests__/bootstrap/__snapshots__/cube.test.ts.snap

@@ -352,6 +352,7 @@ source: system
 path:   C:/Program Files/nodejs/node.exe
 tried:
   override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node/node.exe
   managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/node.cmd
   where        ok
 argv:

package/packages/shared/src/__tests__/bootstrap/families/__snapshots__/g-windows-specifics.test.ts.snap

@@ -39,6 +39,7 @@ source: system
 path:   C:/Program Files/nodejs/node.exe
 tried:
   override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node/node.exe
   managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/node.cmd
   where        ok
 argv: