gentle-pi 3.7.0 → 4.1.0

package/lib/gentle-shell-update-panel.ts

@@ -0,0 +1,231 @@
+import type { Readable, Writable } from "node:stream";
+
+export type StartupUpdateChoice = "update" | "skip" | "omit" | "cancel";
+type TerminalInput = Readable & { isRaw?: boolean; setRawMode?: (raw: boolean) => unknown };
+type TerminalOutput = Writable & { columns?: number; rows?: number; isTTY?: boolean };
+type UpdateOffer = { current: string; latest: string; notesUrl: string };
+type PromptOptions = { input?: TerminalInput; output?: TerminalOutput; color?: boolean };
+
+const choices: StartupUpdateChoice[] = ["update", "skip", "omit"];
+const labels = ["Update now (gentle-shell upgrade)", "Not now", "Skip this version"];
+
+function sanitize(value: string, limit: number): string {
+  // Bound work before parsing, remove whole escape sequences (including OSC titles),
+  // then remove remaining control and bidi characters. Never emit an OSC hyperlink.
+  return value.slice(0, 2048)
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\|$)/g, "")
+    .replace(/(?:\x1b\[|\x9b)[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/\x1b[ -/]*[@-~]/g, "")
+    .replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g, "")
+    .slice(0, limit);
+}
+
+function cells(char: string): number {
+  const code = char.codePointAt(0)!;
+  if (/\p{Mark}/u.test(char) || code === 0x200d || code === 0xfe0f) return 0;
+  return code >= 0x1100 && (
+    code <= 0x115f || code === 0x2329 || code === 0x232a ||
+    (code >= 0x2e80 && code <= 0xa4cf) || (code >= 0xac00 && code <= 0xd7a3) ||
+    (code >= 0xf900 && code <= 0xfaff) || (code >= 0xfe10 && code <= 0xfe6f) ||
+    (code >= 0xff00 && code <= 0xff60) || (code >= 0xffe0 && code <= 0xffe6) ||
+    code >= 0x1f000
+  ) ? 2 : 1;
+}
+
+function wrap(text: string, width: number): string[] {
+  const lines: string[] = [];
+  let line = "";
+  let used = 0;
+  for (const original of text) {
+    const char = cells(original) > width ? "?" : original;
+    const size = cells(char);
+    if (used + size > width) {
+      lines.push(line);
+      line = "";
+      used = 0;
+    }
+    line += char;
+    used += size;
+  }
+  lines.push(line);
+  return lines;
+}
+
+/** A pre-Pi chooser: returns intent only; it never invokes upgrade or persists policy. */
+export function promptStartupUpdate(offer: UpdateOffer, options: PromptOptions = {}): Promise<StartupUpdateChoice> {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const color = options.color ?? output.isTTY === true;
+  const rose = (text: string) => color ? `\x1b[38;2;255;118;195m${text}\x1b[39m` : text;
+  const current = sanitize(offer.current, 40);
+  const latest = sanitize(offer.latest, 40);
+  const notes = sanitize(offer.notesUrl, 160);
+
+  return new Promise((resolve, reject) => {
+    const wasRaw = input.isRaw === true;
+    const wasFlowing = input.readableFlowing === true;
+    let rawAttempted = false;
+    let cursorHidden = false;
+    let selected = 1;
+    let done = false;
+    let failure: unknown;
+    let outcome: StartupUpdateChoice = "skip";
+    let pendingWrites = 0;
+    let settlementScheduled = false;
+    let escape = "";
+    let escapeTimer: ReturnType<typeof setTimeout> | undefined;
+    let previousMenuLines = 0;
+    let previousWidth = 0;
+
+    function settle() {
+      if (!done || pendingWrites || settlementScheduled) return;
+      settlementScheduled = true;
+      // Writable callback errors can be followed by an error event. Keep our
+      // listener until that event is drained, including during cursor cleanup.
+      setImmediate(() => {
+        output.removeListener("error", onError);
+        if (failure) reject(failure);
+        else resolve(outcome);
+      });
+    }
+
+    function write(text: string) {
+      pendingWrites++;
+      try {
+        output.write(text, (error?: Error | null) => {
+          pendingWrites--;
+          if (error) onError(error);
+          settle();
+        });
+      } catch (error) {
+        pendingWrites--;
+        onError(error);
+      }
+    }
+
+    function finish(choice: StartupUpdateChoice, error?: unknown) {
+      if (error && !failure) failure = error;
+      if (done) return;
+      done = true;
+      outcome = choice;
+      clearTimeout(escapeTimer);
+      input.removeListener("data", onData);
+      input.removeListener("end", onEnd);
+      input.removeListener("close", onEnd);
+      input.removeListener("error", onError);
+      try {
+        if (rawAttempted) input.setRawMode?.(wasRaw);
+      } catch (error) {
+        failure ??= error;
+      }
+      if (!wasFlowing) input.pause();
+      if (cursorHidden) write("\x1b[?25h");
+      settle();
+    }
+
+    function onError(error: unknown) {
+      if (!failure) failure = error;
+      finish("skip", error);
+    }
+    function onEnd() { finish("skip"); }
+
+    function terminalWidth(): number {
+      const width = output.columns;
+      return typeof width === "number" && Number.isFinite(width) ? Math.max(1, Math.min(76, Math.floor(width))) : 76;
+    }
+
+    function render(initial = false) {
+      const width = terminalWidth();
+      const bordered = width >= 6;
+      const inner = bordered ? width - 4 : width;
+      const row = (text: string) => wrap(text, inner).map(line => {
+        const used = [...line].reduce((sum, char) => sum + cells(char), 0);
+        return bordered ? `| ${line}${" ".repeat(Math.max(0, inner - used))} |` : line;
+      });
+      const border = bordered ? rose(`+${"-".repeat(width - 2)}+`) : "";
+      const menu = labels.flatMap((label, index) => row(`${index === selected ? ">" : " "} ${index + 1}. ${label}`));
+      if (bordered) menu.push(border);
+      let prefix = "";
+      if (initial) {
+        // Start on a fresh line so the existing shell prompt is never erased.
+        const header = [
+          ...(bordered ? [border] : []),
+          ...row("Gentle Shell update available").map(rose),
+          ...row(`${current} -> ${latest}`),
+          ...row("Release notes:"),
+          ...row(notes),
+          ...row("Arrows / 1-3: select; Enter: confirm"),
+          ...row("Esc: not now; Ctrl+C: cancel"),
+        ];
+        prefix = `\r\n${header.join("\r\n")}\r\n`;
+      } else {
+        const rows = output.rows ?? 24;
+        // On resize or a very short terminal, append rather than moving above
+        // our visible menu. Never clear a screen or enter an alternate screen.
+        if (width === previousWidth && previousMenuLines < rows) {
+          prefix = `\x1b[${previousMenuLines}A\r`;
+        }
+      }
+      const clear = !initial && prefix.startsWith("\x1b[") ? "\x1b[2K" : "";
+      write(prefix + menu.map(line => `${clear}${line}\r\n`).join(""));
+      previousMenuLines = menu.length;
+      previousWidth = width;
+    }
+
+    function select(index: number) {
+      selected = (index + choices.length) % choices.length;
+      render();
+    }
+
+    function onData(chunk: Buffer | string) {
+      for (const char of chunk.toString()) {
+        if (done) break;
+        if (char === "\x03") { finish("cancel"); break; }
+        if (escape) {
+          clearTimeout(escapeTimer);
+          escape += char;
+          if (escape === "\x1b[" || escape === "\x1bO") {
+            escapeTimer = setTimeout(() => finish("skip"), 40);
+            continue;
+          }
+          if (/^\x1b[\[O][ABCD]$/.test(escape)) {
+            select(selected + (char === "A" || char === "D" ? -1 : 1));
+            escape = "";
+            continue;
+          }
+          finish("skip");
+          break;
+        }
+        if (char === "\x1b") {
+          escape = char;
+          escapeTimer = setTimeout(() => finish("skip"), 40);
+        } else if (/^[123]$/.test(char)) select(Number(char) - 1);
+        else if (char === "\r" || char === "\n") finish(choices[selected]);
+      }
+    }
+
+    output.on("error", onError);
+    input.on("error", onError);
+    input.on("end", onEnd);
+    input.on("close", onEnd);
+    try {
+      if (input.readableEnded || input.destroyed || output.destroyed) {
+        finish("skip");
+        return;
+      }
+      if (input.setRawMode) {
+        rawAttempted = true;
+        input.setRawMode(true);
+      }
+      cursorHidden = true;
+      write("\x1b[?25l");
+      if (!done) render(true);
+      if (!done) {
+        input.on("data", onData);
+        input.resume();
+      }
+    } catch (error) {
+      finish("skip", error);
+    }
+  });
+}

package/lib/herdr-activity.ts

@@ -0,0 +1,183 @@
+import { execFile } from "node:child_process";
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { stripTerminalSequences, visibleWidth } from "@earendil-works/pi-tui";
+
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+const FALLBACK_COLUMNS = 24;
+const MAX_SNAPSHOT_BYTES = 256 * 1024;
+
+/** Read only a bounded local snapshot, never poll Herdr's CLI/socket for geometry. */
+export function createActivityColumns(socket: string, now: () => number = Date.now): () => number {
+	const path = isAbsolute(socket) ? join(dirname(socket), "session.json") : undefined;
+	let refreshAt = -Infinity;
+	let columns = FALLBACK_COLUMNS;
+	return () => {
+		const time = now();
+		if (time < refreshAt) return columns;
+		refreshAt = time + 5000;
+		columns = FALLBACK_COLUMNS;
+		if (!path) return columns;
+		let fd: number | undefined;
+		try {
+			// Reject FIFOs after opening without waiting for a writer; unsupported flags are omitted.
+			fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+			const stat = fstatSync(fd);
+			if (!stat.isFile() || stat.size > MAX_SNAPSHOT_BYTES) return columns;
+			// One extra byte rejects files that grew after fstat, without unlimited reads.
+			const buffer = Buffer.alloc(MAX_SNAPSHOT_BYTES + 1);
+			const size = readSync(fd, buffer, 0, buffer.length, 0);
+			if (size > MAX_SNAPSHOT_BYTES) return columns;
+			const snapshot = JSON.parse(buffer.toString("utf8", 0, size));
+			const width: unknown = snapshot?.sidebar_width;
+			if (typeof width === "number" && Number.isInteger(width) && width >= 6 && width <= 512) {
+				// Divider + possible scrollbar + three-space agent detail prefix.
+				columns = width - 5;
+			}
+		} catch { /* Missing/malformed snapshots use conservative geometry. */ }
+		finally {
+			try { if (fd !== undefined) closeSync(fd); } catch { /* Best effort close. */ }
+		}
+		return columns;
+	};
+}
+
+/** Fit whole graphemes within cell, UTF-8 byte and Unicode scalar budgets. */
+function fit(parts: string[], columns: number, bytes: number, characters: number, preferWords = true): number {
+	let cells = 0;
+	let used = 0;
+	let scalars = 0;
+	let count = 0;
+	let space = -1;
+	for (const part of parts) {
+		const width = visibleWidth(part);
+		const size = Buffer.byteLength(part);
+		const length = Array.from(part).length;
+		if (cells + width > columns || used + size > bytes || scalars + length > characters) break;
+		if (part === " ") space = count;
+		cells += width;
+		used += size;
+		scalars += length;
+		count++;
+	}
+	if (preferWords && count < parts.length && parts[count] !== " " && space > 0) return space;
+	return count;
+}
+
+/** Only the active Todo title is free text. LF is private framing, not a token. */
+export function activitySummary(tasks: unknown, columns = FALLBACK_COLUMNS): string | null {
+	if (!Array.isArray(tasks)) return null;
+	const title: unknown = tasks.find((task) => task?.status === "in_progress")?.title;
+	if (typeof title !== "string") return null;
+	const clipped = title.length > 4096;
+	// Bound sanitization/segmentation work, preserve ZWJ emoji but strip bidi controls.
+	/* eslint-disable no-control-regex */
+	const clean = stripTerminalSequences(title.slice(0, 4096))
+		.replace(/[\x00-\x1f\x7f-\x9f\u061c\u200b-\u200c\u200e-\u200f\u202a-\u202e\u2060-\u206f\ufeff]/g, " ")
+		.replace(/\s+/g, " ").trim();
+	/* eslint-enable no-control-regex */
+	if (!clean) return null;
+	const parts = Array.from(graphemes.segment(clean), ({ segment }) => segment);
+	// The bounded sample may end inside a grapheme; never publish that fragment.
+	if (clipped) parts.pop();
+	columns = Number.isFinite(columns) ? Math.max(1, Math.min(512, Math.floor(columns))) : FALLBACK_COLUMNS;
+	if (columns <= 2) return columns === 1 ? "…" : "◐…";
+	// Herdr caps each token at 80 scalars; count our icon/indent before its trim.
+	const whole = fit(parts, columns - 2, 252, 78, false);
+	if (!clipped && whole === parts.length) return `◐ ${parts.join("")}`;
+	// Reserve the second-row indent and ellipsis; private LF framing is not a token byte.
+	let firstCount = fit(parts, columns - 2, 247, 78);
+	if (!firstCount) return columns === 3 ? "◐…" : "◐ …";
+	const restFits = (count: number): boolean => {
+		const first = `◐ ${parts.slice(0, count).join("").trimEnd()}`;
+		const rest = parts.slice(count);
+		while (rest[0] === " ") rest.shift();
+		return fit(rest, columns - 2, 256 - Buffer.byteLength(first) - 2, 78, false) === rest.length;
+	};
+	// Prefer words unless splitting one would preserve the entire two-row title.
+	if (!clipped && !restFits(firstCount)) {
+		const hardCount = fit(parts, columns - 2, 247, 78, false);
+		if (restFits(hardCount)) firstCount = hardCount;
+	}
+	const first = `◐ ${parts.slice(0, firstCount).join("").trimEnd()}`;
+	const rest = parts.slice(firstCount);
+	while (rest[0] === " ") rest.shift();
+	const bytes = 256 - Buffer.byteLength(first) - 2; // Two-space indent.
+	let count = fit(rest, columns - 2, bytes, 78, false);
+	const overflow = clipped || count < rest.length;
+	if (overflow) count = fit(rest, columns - 3, bytes - 3, 77);
+	const second = rest.slice(0, count).join("").trimEnd();
+	return `${first}\n  ${second}${overflow ? "…" : ""}`;
+}
+
+export function metadataArgs(pane: string, summary: string | null, seq: number): string[] {
+	const rows = summary?.split("\n") ?? [];
+	const tokens = ["summary", "summary2"].flatMap((token, index) => rows[index]
+		? ["--token", `${token}=${rows[index]}`] : ["--clear-token", token]);
+	return ["pane", "report-metadata", pane, "--source", "gentle:activity", "--agent", "pi",
+		"--seq", String(seq), "--ttl-ms", "30000", ...tokens];
+}
+
+export function metadataTransport(env: NodeJS.ProcessEnv): (summary: string | null, seq: number) => Promise<void> {
+	return (summary, seq) => new Promise((resolve) => {
+		// No shell, bounded output/time, and failure never blocks Pi's handlers.
+		execFile(env.HERDR_BIN_PATH ?? "herdr", metadataArgs(env.HERDR_PANE_ID!, summary, seq), {
+			env, timeout: 1500, maxBuffer: 4096, windowsHide: true,
+		}, () => resolve());
+	});
+}
+
+/** One in flight, one pending value; a clear supersedes queued active work. */
+export class ActivityPublisher {
+	private pending: string | null | undefined;
+	private last: string | null | undefined;
+	private running = false;
+	private closed = false;
+	private cancel: (() => void) | undefined;
+	private seq = Date.now();
+	private readonly send: (summary: string | null, seq: number) => Promise<void>;
+	private readonly schedule: (fn: () => void) => () => void;
+	constructor(send: (summary: string | null, seq: number) => Promise<void>,
+		schedule: (fn: () => void) => () => void = (fn) => {
+			const timer = setTimeout(fn, 150);
+			timer.unref();
+			return () => clearTimeout(timer);
+		}) {
+		this.send = send;
+		this.schedule = schedule;
+	}
+
+	update(summary: string | null, force = false): void {
+		if (this.closed || (!force && (this.pending !== undefined
+			? summary === this.pending : !this.running && summary === this.last))) return;
+		this.pending = summary;
+		if (summary === null) {
+			this.cancel?.();
+			this.cancel = undefined;
+			if (!this.running) void this.flush();
+			return;
+		}
+		this.enqueue();
+	}
+	private enqueue(): void {
+		if (this.running || this.cancel || this.pending === undefined) return;
+		this.cancel = this.schedule(() => { this.cancel = undefined; void this.flush(); });
+	}
+	private async flush(): Promise<void> {
+		if (this.pending === undefined) return;
+		const summary = this.pending;
+		this.pending = undefined;
+		this.running = true;
+		try { await this.send(summary, ++this.seq); this.last = summary; }
+		catch { /* Best effort; a refresh retries active state. */ }
+		finally { this.running = false; this.enqueue(); }
+	}
+	close(): void {
+		if (this.closed) return;
+		this.update(null, true);
+		this.closed = true;
+		this.cancel?.(); this.cancel = undefined;
+		if (!this.running) void this.flush();
+	}
+}

package/lib/history-capture-policy.ts

@@ -0,0 +1,95 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { gentlePiConfigHome } from "./agent-home.ts";
+
+// Prompt history capture is default-off. An explicit GENTLE_PI_HISTORY_CAPTURE
+// value wins, then the Gentle → Customize preference, then off. Any missing,
+// malformed or unreadable preference fails closed. Turning capture off only
+// stops new captures; stored history is never deleted here.
+export const HISTORY_CAPTURE_POLICY = { ON: "on", OFF: "off" } as const;
+export type HistoryCapturePolicy = (typeof HISTORY_CAPTURE_POLICY)[keyof typeof HISTORY_CAPTURE_POLICY];
+export const HISTORY_CAPTURE_SCHEMA = "gentle-pi.history-capture/v1";
+export const HISTORY_CAPTURE_ENV = "GENTLE_PI_HISTORY_CAPTURE";
+interface HistoryCaptureOptions { gentlePiConfigHome?: string }
+export interface HistoryCapturePolicyResolution {
+	policy: HistoryCapturePolicy;
+	source: "global_file" | "default";
+	malformed: boolean;
+	globalFile: string;
+}
+export interface HistoryCaptureResolution {
+	enabled: boolean;
+	source: "env" | "global_file" | "default";
+	/** The persisted Customize preference, reported even while the env overrides it. */
+	preference: HistoryCapturePolicy;
+	envOverride: HistoryCapturePolicy | undefined;
+	malformed: boolean;
+	globalFile: string;
+}
+
+/** Only explicit on/off values override; anything else defers to the preference. */
+export function historyCaptureEnvOverride(env: NodeJS.ProcessEnv = process.env): HistoryCapturePolicy | undefined {
+	const value = env[HISTORY_CAPTURE_ENV]?.trim().toLowerCase();
+	if (value === "1" || value === "true" || value === "on") return "on";
+	if (value === "0" || value === "false" || value === "off") return "off";
+	return undefined;
+}
+
+export function parseHistoryCaptureFile(raw: string): HistoryCapturePolicy | undefined {
+	try {
+		const value: unknown = JSON.parse(raw);
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+		if (Object.keys(value).length !== 2 || !("schema" in value) || value.schema !== HISTORY_CAPTURE_SCHEMA || !("policy" in value)) return undefined;
+		return value.policy === "on" || value.policy === "off" ? value.policy : undefined;
+	} catch { return undefined; }
+}
+
+export function resolveHistoryCapturePolicy(options: HistoryCaptureOptions = {}): HistoryCapturePolicyResolution {
+	const globalFile = join(options.gentlePiConfigHome ?? gentlePiConfigHome(), "history-capture.json");
+	try {
+		const policy = parseHistoryCaptureFile(readFileSync(globalFile, "utf8"));
+		return { policy: policy ?? "off", source: "global_file", malformed: policy === undefined, globalFile };
+	} catch (error) {
+		const missing = typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+		return { policy: "off", source: missing ? "default" : "global_file", malformed: !missing, globalFile };
+	}
+}
+
+/** Full resolution for status surfaces; always reads the preference. */
+export function resolveHistoryCapture(options: { env?: NodeJS.ProcessEnv; gentlePiConfigHome?: string } = {}): HistoryCaptureResolution {
+	const env = options.env ?? process.env;
+	const saved = resolveHistoryCapturePolicy({ gentlePiConfigHome: options.gentlePiConfigHome ?? gentlePiConfigHome(env) });
+	const envOverride = historyCaptureEnvOverride(env);
+	return {
+		enabled: (envOverride ?? saved.policy) === "on",
+		source: envOverride ? "env" : saved.source,
+		preference: saved.policy,
+		envOverride,
+		malformed: saved.malformed,
+		globalFile: saved.globalFile,
+	};
+}
+
+/** Per-prompt gate: an explicit env value never reads the preference file. */
+export function historyCaptureEnabled(options: { env?: NodeJS.ProcessEnv; gentlePiConfigHome?: string } = {}): boolean {
+	const env = options.env ?? process.env;
+	const override = historyCaptureEnvOverride(env);
+	if (override) return override === "on";
+	return resolveHistoryCapturePolicy({ gentlePiConfigHome: options.gentlePiConfigHome ?? gentlePiConfigHome(env) }).policy === "on";
+}
+
+export function writeHistoryCapturePolicy(policy: HistoryCapturePolicy, options: HistoryCaptureOptions = {}): string {
+	if (policy !== "on" && policy !== "off") throw new TypeError("Invalid history capture policy");
+	const home = options.gentlePiConfigHome ?? gentlePiConfigHome();
+	const path = join(home, "history-capture.json");
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	mkdirSync(home, { recursive: true });
+	try {
+		writeFileSync(temporary, `${JSON.stringify({ schema: HISTORY_CAPTURE_SCHEMA, policy })}\n`, { flag: "wx", mode: 0o600 });
+		renameSync(temporary, path);
+	} finally {
+		try { unlinkSync(temporary); } catch { /* Rename consumed the temporary file. */ }
+	}
+	return path;
+}

package/lib/inprocess-reviewer.ts

@@ -73,6 +73,8 @@ export interface InProcessReviewerRequest {
 	readonly selection: string;
 	/** Routing thinking label: off | minimal | low | medium | high | xhigh | max. Omitted is treated as "off". */
 	readonly thinking?: string;
+	/** Effective Pi transport preference; absent preserves the provider default. */
+	readonly transport?: SimpleStreamOptions["transport"];
 	/** Frozen Go-materialized prompt bytes, submitted verbatim as the one user message. */
 	readonly prompt: Buffer;
 	readonly timeoutMs: number;
@@ -272,6 +274,7 @@ export async function runInProcessReviewer(request: InProcessReviewerRequest, de
 		...(auth.apiKey === undefined ? {} : { apiKey: auth.apiKey }),
 		...(auth.headers === undefined && attributionHeaders === undefined ? {} : { headers: attributionHeaders === undefined ? auth.headers : { ...attributionHeaders, ...auth.headers } }),
 		...(reasoning.reasoning === undefined ? {} : { reasoning: reasoning.reasoning }),
+		...(request.transport === undefined ? {} : { transport: request.transport }),
 	};
 
 	// An abort is classified by which signal actually fired, never by the

package/lib/jobs-sidebar-state.ts

@@ -0,0 +1,20 @@
+/** Session-scoped display data only; never command output or process control. */
+export const JOBS_SIDEBAR_EVENT = "gentle-ai:jobs-sidebar";
+export const JOBS_STATUS_KEY = "gentle-jobs";
+
+export interface RunningJobDisplay {
+	id: string;
+	label: string;
+	startedAt: number;
+}
+
+export interface JobsSidebarSnapshot {
+	jobs: RunningJobDisplay[];
+}
+
+export function isJobsSidebarSnapshot(value: unknown): value is JobsSidebarSnapshot {
+	if (!value || typeof value !== "object" || !Array.isArray((value as JobsSidebarSnapshot).jobs)) return false;
+	return (value as JobsSidebarSnapshot).jobs.every((job) => job && typeof job === "object" &&
+		typeof job.id === "string" && job.id.length > 0 && typeof job.label === "string" &&
+		typeof job.startedAt === "number" && Number.isFinite(job.startedAt));
+}