@blackbelt-technology/pi-agent-dashboard 0.5.3 → 0.5.4

package/packages/shared/src/recommended-extensions.ts

@@ -61,6 +61,16 @@ export interface RecommendedExtension {
 	 * start working.
 	 */
 	autowired?: boolean;
+
+	/**
+	 * Companion dashboard plugin id, if this extension is paired with one
+	 * (e.g. `pi-memory-honcho` extension <-> `honcho` dashboard plugin).
+	 * The recommended-extensions enricher carries this through alongside a
+	 * computed `dashboardPluginInstalled: boolean` so the install browser
+	 * can render a "+plugin: <id>" badge.
+	 * See change: add-plugin-activation-ui (Layer 1.5).
+	 */
+	dashboardPlugin?: string;
 }
 
 /** Enriched manifest entry returned by GET /api/packages/recommended. */
@@ -77,6 +87,12 @@ export interface EnrichedRecommendedExtension extends RecommendedExtension {
 	activeInPi: boolean;
 	/** True iff a newer version is available upstream. */
 	updateAvailable: boolean;
+	/**
+	 * True iff the entry declares a `dashboardPlugin` and the named plugin is
+	 * present in the dashboard's plugin status store.
+	 * See change: add-plugin-activation-ui.
+	 */
+	dashboardPluginInstalled?: boolean;
 }
 
 export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
@@ -96,21 +112,24 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
 		autowired: true,
 	},
 	{
-		id: "tintinweb-pi-subagents",
-		source: "npm:@tintinweb/pi-subagents",
-		displayName: "@tintinweb/pi-subagents",
+		id: "pi-dashboard-subagents",
+		source: "https://github.com/BlackBeltTechnology/pi-dashboard-subagents.git",
+		displayName: "pi-dashboard-subagents",
 		fallbackDescription:
-			"Claude Code-style autonomous sub-agents for pi. Registers " +
-			"the Agent tool and its companions. The dashboard has custom " +
-			"card UI for it.",
-		status: "strongly-suggested",
+			"Foreground in-memory subagents for pi with a streamed timeline " +
+			"(every tool call, reasoning step, and assistant text). Pairs with " +
+			"the dashboard's subagent-inspector plugin for inline-expand + popout " +
+			"card UI. Producer of the Agent tool; no background spawning.",
+		status: "optional",
 		unlocks: [
 			"Agent tool card UI",
-			"Subagent activity badge",
-			"get_subagent_result / steer_subagent renderers",
+			"Subagent inspector (inline expand + popout)",
+			"agent-md path display",
 		],
-		toolsRegistered: ["Agent", "get_subagent_result", "steer_subagent"],
+		toolsRegistered: ["Agent"],
 		autowired: true,
+		// Companion dashboard plugin id. See change: add-subagent-inspector.
+		dashboardPlugin: "subagents",
 	},
 	{
 		id: "pi-flows",
@@ -182,6 +201,8 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
 		],
 		toolsRegistered: ["honcho_search", "honcho_context", "honcho_profile"],
 		autowired: true,
+		// Companion dashboard plugin id. See change: add-plugin-activation-ui.
+		dashboardPlugin: "honcho",
 	},
 ];
 
@@ -198,6 +219,9 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
  */
 export const BUNDLED_EXTENSION_IDS: readonly string[] = [
 	"pi-anthropic-messages",
+	// Foreground subagent producer. Git source + MIT license = bundle eligible.
+	// See change: add-subagent-inspector §13.
+	"pi-dashboard-subagents",
 	// "pi-flows" is intentionally NOT bundled until the upstream repo declares
 	// an SPDX-conformant license (`LICENSE` file or `package.json#license`).
 	// The bundle-recommended-extensions.mjs license allowlist enforcement

package/packages/shared/src/server-identity.ts

@@ -1,26 +1,94 @@
 /**
  * Server identity verification via HTTP health check.
  * Replaces bare TCP port probes with identity-verified dashboard detection.
+ *
+ * Retry semantics (cherry-pick 2 of harvest-bootstrap-survivor-fixes):
+ * the pre-wizard probe in Electron's main process fires while a *previous*
+ * server instance may still be mid-bootstrap (jiti TypeScript transpile +
+ * cold-cache extraction can block the event loop for 5–15 s). The default
+ * 2 s timeout + 1 attempt produces false negatives in that window.
+ * Callers can opt into a bounded retry loop via `opts.retries` /
+ * `opts.timeoutMs` / `opts.retryDelayMs`. Defaults preserve legacy
+ * behaviour (single attempt, 2 s timeout) so existing call sites are
+ * unaffected.
  */
 
-const HEALTH_TIMEOUT = 2000;
+const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_RETRIES = 0;
+const DEFAULT_RETRY_DELAY_MS = 500;
 
 export interface DashboardStatus {
   /** Whether the dashboard server is running on this port */
   running: boolean;
   /** PID of the running server (if detected) */
   pid?: number;
+  /** Server version from /api/health (when detected) */
+  version?: string;
   /** Port is occupied by a non-dashboard service */
   portConflict?: boolean;
 }
 
+export interface DashboardCheckOpts {
+  /**
+   * Per-attempt fetch timeout. Default 2000 ms — preserves legacy single-shot behaviour.
+   * Bootstrap-aware callers should pass ~8000 ms to absorb event-loop hiccups
+   * during cold-cache install.
+   */
+  timeoutMs?: number;
+  /**
+   * Number of additional attempts after the first. Default 0 (no retries).
+   * On `AbortError` (timeout) or 5xx the loop sleeps `retryDelayMs` and
+   * retries. `portConflict: true` (HTTP 200 with foreign JSON shape)
+   * short-circuits — that's a deterministic conflict, not a transient
+   * fault, and retrying would mask a real port collision.
+   * ECONNREFUSED is *not* retried (no process to talk to).
+   */
+  retries?: number;
+  /** Sleep between retries. Default 500 ms. */
+  retryDelayMs?: number;
+  /**
+   * Test seam: replace `setTimeout`-based sleep. Receives the configured
+   * `retryDelayMs`. Must return a promise that resolves after the sleep.
+   */
+  _sleep?: (ms: number) => Promise<void>;
+}
+
 /**
  * Check if a dashboard server is running on the given port by hitting GET /api/health.
  * Returns identity-verified status instead of just "port is open".
  */
-export async function isDashboardRunning(port: number, host = "localhost"): Promise<DashboardStatus> {
+export async function isDashboardRunning(
+  port: number,
+  host: string = "localhost",
+  opts?: DashboardCheckOpts,
+): Promise<DashboardStatus> {
+  const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retries = opts?.retries ?? DEFAULT_RETRIES;
+  const retryDelayMs = opts?.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+  const sleep = opts?._sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+
+  const attempts = retries + 1;
+  let lastResult: DashboardStatus = { running: false };
+
+  for (let i = 0; i < attempts; i++) {
+    const result = await probeOnce(port, host, timeoutMs);
+    // Success — return immediately.
+    if (result.running) return result;
+    // Deterministic conflict — short-circuit (retrying would mask it).
+    if (result.portConflict) return result;
+    lastResult = result;
+    if (i < attempts - 1) await sleep(retryDelayMs);
+  }
+  return lastResult;
+}
+
+async function probeOnce(
+  port: number,
+  host: string,
+  timeoutMs: number,
+): Promise<DashboardStatus> {
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), HEALTH_TIMEOUT);
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
 
   try {
     const res = await fetch(`http://${host}:${port}/api/health`, {
@@ -32,9 +100,10 @@ export async function isDashboardRunning(port: number, host = "localhost"): Prom
       return { running: false, portConflict: true };
     }
 
-    const data = await res.json() as Record<string, unknown>;
+    const data = (await res.json()) as Record<string, unknown>;
     if (data && data.ok === true && typeof data.pid === "number") {
-      return { running: true, pid: data.pid };
+      const version = typeof data.version === "string" ? data.version : undefined;
+      return { running: true, pid: data.pid, version };
     }
 
     // HTTP 200 but not our format — another service

package/packages/shared/src/server-launcher.ts

@@ -136,6 +136,19 @@ export interface LaunchOpts {
   _now?: () => number;
   /** Override the sleep function used between polls. */
   _sleep?: (ms: number) => Promise<void>;
+  /**
+   * Called once when the spawned child exits (any exit — crash or graceful).
+   * Attached via `child.on("exit", …)` before the readiness loop so the
+   * handler fires even if the child exits during the health-wait window.
+   * No-op when omitted — existing callers are unaffected.
+   *
+   * Callers that need to distinguish crash from graceful shutdown should
+   * maintain their own flag (see `setGracefulShutdownInProgress` in
+   * `electron/server-lifecycle.ts`) and consult it inside the callback.
+   *
+   * See change: harvest-bootstrap-survivor-fixes (cherry-pick 6a).
+   */
+  onChildExit?: (code: number | null, signal: NodeJS.Signals | null) => void;
 }
 
 export interface LaunchResult {
@@ -242,6 +255,13 @@ export async function launchDashboardServer(opts: LaunchOpts): Promise<LaunchRes
 
   try { child.unref(); } catch { /* ignore */ }
 
+  // Attach caller's exit handler before the readiness loop so it fires
+  // even for exits that happen during the health-wait window.
+  // See change: harvest-bootstrap-survivor-fixes (cherry-pick 6a).
+  if (opts.onChildExit) {
+    child.once("exit", opts.onChildExit);
+  }
+
   if (!child.pid) {
     throw new EarlyExitError(child.exitCode ?? null, child.signalCode ?? null);
   }

package/packages/shared/src/source-matching.ts

@@ -9,7 +9,7 @@
 // Input sources take one of these forms:
 //
 //   npm:<name>[@<version>]
-//     e.g.  "npm:pi-web-access", "npm:@tintinweb/pi-subagents@0.5.2"
+//     e.g.  "npm:pi-web-access", "npm:@scope/example-pkg@0.5.2"
 //
 //   git@<host>:<owner>/<repo>[.git]
 //     e.g.  "git@github.com:BlackBeltTechnology/pi-flows.git"

package/packages/shared/src/tool-registry/__tests__/node-script-toargv-fallback.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Regression: `nodeScriptToArgv` MUST always prepend a Node interpreter
+ * on Windows + `.js` paths.
+ *
+ * Live repro on Windows 11: when the registry's `node` strategy chain
+ * failed (no managed runtime, no PATH hit), `nodeScriptToArgv`
+ * previously returned `[cli.js]` and `spawn(cli.js)` crashed with
+ * `EFTYPE`. The fix falls back to `process.execPath` — the dashboard
+ * server's own Node — which is by definition spawn-able.
+ *
+ * See change: fix-windows-standalone-spawn.
+ */
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  ToolRegistry,
+  registerDefaultTools,
+  OverridesStore,
+} from "../index.js";
+
+function freshRegistry(opts: {
+  platform: NodeJS.Platform;
+  exists?: (p: string) => boolean;
+  which?: (name: string) => string | null;
+  npmRootGlobal?: () => string;
+  overrides?: Record<string, string>;
+}) {
+  const store = new OverridesStore({
+    filePath: path.join(os.tmpdir(), `node-script-toargv-${Math.random()}.json`),
+    warn: () => {},
+  });
+  for (const [k, v] of Object.entries(opts.overrides ?? {})) store.set(k, v);
+
+  const r = new ToolRegistry({
+    overrides: store,
+    platform: opts.platform,
+  });
+  registerDefaultTools(r, {
+    exists: opts.exists ?? (() => false),
+    which: opts.which ?? (() => null),
+    npmRootGlobal: opts.npmRootGlobal ?? (() => ""),
+  });
+  return r;
+}
+
+describe("nodeScriptToArgv — Windows fallback (Bug 3)", () => {
+  it("falls back to process.execPath when registry.resolve('node') returns ok:false", () => {
+    // Locate pi via an explicit override pointing at a fake cli.js, so
+    // the pi executor resolves successfully. The `node` chain has no
+    // sources (no managed runtime, no PATH hit) so it must fail —
+    // forcing nodeScriptToArgv into the process.execPath fallback.
+    const fakePiCli = "C:\\Users\\u\\.pi-dashboard\\node_modules\\@earendil-works\\pi-coding-agent\\dist\\cli.js";
+    const r = freshRegistry({
+      platform: "win32",
+      // Only the pi override path exists; node has no candidates.
+      exists: (p) => p === fakePiCli,
+      overrides: { pi: fakePiCli },
+    });
+
+    const nodeRes = r.resolve("node");
+    expect(nodeRes.ok).toBe(false);
+
+    const piExec = r.resolveExecutor("pi");
+    expect(piExec.ok).toBe(true);
+    expect(piExec.path).toBe(fakePiCli);
+    expect(piExec.argv).toEqual([process.execPath, fakePiCli]);
+  });
+
+  it("uses the registry node.path when registry.resolve('node') succeeds", () => {
+    const fakePiCli = "C:\\Users\\u\\.pi-dashboard\\node_modules\\@earendil-works\\pi-coding-agent\\dist\\cli.js";
+    const fakeNode = "C:\\Program Files\\nodejs\\node.exe";
+    const r = freshRegistry({
+      platform: "win32",
+      exists: (p) => p === fakePiCli || p === fakeNode,
+      overrides: { pi: fakePiCli, node: fakeNode },
+    });
+
+    const piExec = r.resolveExecutor("pi");
+    expect(piExec.ok).toBe(true);
+    expect(piExec.argv[0]).toBe(fakeNode);
+    expect(piExec.argv[1]).toBe(fakePiCli);
+  });
+});

package/packages/shared/src/tool-registry/definitions.ts

@@ -11,6 +11,7 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ToolDefinition, Source } from "./types.js";
 import type { ToolRegistry } from "./registry.js";
 import {
@@ -110,15 +111,64 @@ function bareImportPackageDirStrategy(
   return {
     name: "bare-import",
     run() {
-      const pkgJson = resolveModule(`${pkgName}/package.json`, import.meta.url);
+      const pkgJson =
+        resolveModule(`${pkgName}/package.json`, import.meta.url)
+        ?? findPackageJsonByDirWalk(pkgName, import.meta.url, searchPaths, deps?.exists);
       if (!pkgJson) {
-        return { ok: false, reason: `cannot resolve ${pkgName}/package.json` };
+        return { ok: false, reason: `cannot resolve ${pkgName} package directory` };
       }
       return { ok: true, path: path.dirname(pkgJson) };
     },
   };
 }
 
+/**
+ * Helper: walks up from `fromUrl`'s directory looking for
+ * `node_modules/<pkgName>/package.json` directly on the filesystem.
+ *
+ * Exports-map-immune: required because both `@earendil-works/pi-coding-agent`
+ * and `@fission-ai/openspec` declare `exports` blocks that omit
+ * `./package.json`, so `createRequire(from).resolve("<pkg>/package.json")`
+ * returns `ERR_PACKAGE_PATH_NOT_EXPORTED` in modern Node. This walk is
+ * a deliberate end-run around the resolver — we already know the file
+ * we want and just need its absolute path.
+ *
+ * Honors the injected `exists` predicate so tests with mocked
+ * filesystems stay deterministic; falls back to `existsSync` when
+ * none is injected.
+ *
+ * See change: eliminate-electron-runtime-install (F9 follow-on).
+ */
+function findPackageJsonByDirWalk(
+  pkgName: string,
+  fromUrl: string,
+  searchPaths?: readonly string[],
+  exists?: StrategyDeps["exists"],
+): string | null {
+  const check = exists ?? existsSync;
+  const candidates: string[] = [];
+  try {
+    candidates.push(path.dirname(fileURLToPath(fromUrl)));
+  } catch {
+    // fromUrl might not be a file: URL in synthetic test contexts.
+  }
+  for (const sp of searchPaths ?? []) candidates.push(sp);
+  for (const start of candidates) {
+    let dir = start;
+    // Bound the walk: stop at filesystem root or once dirname is
+    // unchanged. Defensive cap at 64 levels covers any plausible
+    // workspace nesting without an infinite-loop risk on broken paths.
+    for (let i = 0; i < 64; i += 1) {
+      const candidate = path.join(dir, "node_modules", pkgName, "package.json");
+      if (check(candidate)) return candidate;
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return null;
+}
+
 /** Module def that returns the package directory (containing package.json). */
 function packageDirModuleDef(
   toolName: string,
@@ -168,11 +218,24 @@ function packageDirModuleDef(
  * registered with this `toArgv` so the spawn becomes
  * `node.exe <script.js>` (pure console-subsystem inherit, no new
  * window ever).
+ *
+ * Node resolution order on Windows (see change:
+ * fix-windows-standalone-spawn):
+ *   1. `registry.resolve("node")` when it returns ok with a non-null
+ *      path (the strategy chain has already validated existence via
+ *      its injected `exists` dep).
+ *   2. `process.execPath` — the dashboard server's own Node — as a
+ *      guaranteed-working fallback. Live repro: Windows 11 standalone
+ *      install where the registry chain failed to find node and the
+ *      spawn argv became `[cli.js]` → `spawn EFTYPE`. Falling back to
+ *      execPath keeps the spawn argv well-formed because the dashboard
+ *      server is itself running on a compatible Node.
  */
 const nodeScriptToArgv: ToolDefinition["toArgv"] = (resolvedPath, { platform, registry }) => {
   if (platform === "win32" && /\.js$/i.test(resolvedPath)) {
     const node = registry.resolve("node");
     if (node.ok && node.path) return [node.path, resolvedPath];
+    return [process.execPath, resolvedPath];
   }
   return [resolvedPath];
 };
@@ -185,7 +248,17 @@ const nodeScriptToArgv: ToolDefinition["toArgv"] = (resolvedPath, { platform, re
  * `node.exe` to produce `[node.exe, cli.js]`. Falls back to `pi.cmd`
  * on PATH when the cli.js is nowhere to be found.
  *
- * On Unix, the chain finds `pi` on PATH; argv = [pi].
+ * On Unix, the chain first tries `bare-import` so a bundled
+ * `<server>/node_modules/@earendil-works/pi-coding-agent/dist/cli.js`
+ * wins over a system install. This is load-bearing for the Electron
+ * immutable-bundle architecture (see openspec change
+ * `eliminate-electron-runtime-install` finding F9). On a clean machine
+ * with no system `pi` and no managed `~/.pi-dashboard/node/bin/`,
+ * bare-import resolves the bundled cli.js (`#!/usr/bin/env node`
+ * shebang, executable) and `nodeScriptToArgv` returns `[cli.js]`
+ * directly. Without this strategy, the server falls into
+ * `bootstrapInstall(...)` and writes to `~/.pi-dashboard/` — the
+ * exact failure mode the immutable-bundle architecture eliminates.
  */
 function piExecutorDef(deps?: StrategyDeps): ToolDefinition {
   const piPkgAliases = ["@earendil-works/pi-coding-agent", "@mariozechner/pi-coding-agent"];
@@ -202,6 +275,7 @@ function piExecutorDef(deps?: StrategyDeps): ToolDefinition {
 
   const unixStrategies = [
     overrideStrategy("pi", deps),
+    ...piPkgAliases.map((pkg) => bareImportCliStrategy(pkg, cliEntry, deps)),
     managedBinStrategy("pi", deps),
     whereStrategy("pi", deps),
   ];
@@ -221,7 +295,10 @@ function piExecutorDef(deps?: StrategyDeps): ToolDefinition {
  *
  * On Windows: finds `@fission-ai/openspec/bin/openspec.js` via managed
  * → bare-import → npm-global. `toArgv` wraps with node.exe.
- * On Unix: finds `openspec` binary on PATH.
+ * On Unix: tries bare-import first (bundled
+ * `<server>/node_modules/@fission-ai/openspec/bin/openspec.js`), then
+ * managed-bin, then PATH. Symmetric with pi; same Electron
+ * immutable-bundle rationale (F9).
  */
 function openspecExecutorDef(deps?: StrategyDeps): ToolDefinition {
   const pkgName = "@fission-ai/openspec";
@@ -229,7 +306,7 @@ function openspecExecutorDef(deps?: StrategyDeps): ToolDefinition {
 
   const winStrategies = [
     overrideStrategy("openspec", deps),
-    bareImportCliStrategy(pkgName, cliEntry),
+    bareImportCliStrategy(pkgName, cliEntry, deps),
     managedModuleStrategy(pkgName, cliEntry, deps),
     npmGlobalStrategy(pkgName, cliEntry, deps),
     managedBinStrategy("openspec", deps),
@@ -238,6 +315,7 @@ function openspecExecutorDef(deps?: StrategyDeps): ToolDefinition {
 
   const unixStrategies = [
     overrideStrategy("openspec", deps),
+    bareImportCliStrategy(pkgName, cliEntry, deps),
     managedBinStrategy("openspec", deps),
     whereStrategy("openspec", deps),
   ];
@@ -330,6 +408,10 @@ function bareImportCliStrategy(
 ) {
   // Default uses the real module resolver anchored to this file;
   // tests inject a fake via deps.resolveModule.
+  // Fallback to a filesystem walk because both pi-coding-agent and
+  // openspec declare exports maps that omit ./package.json (modern Node
+  // resolver returns ERR_PACKAGE_PATH_NOT_EXPORTED). See change:
+  // eliminate-electron-runtime-install (F9 follow-on).
   const resolveModule: NonNullable<StrategyDeps["resolveModule"]> =
     deps?.resolveModule
     ?? ((id, from) => {
@@ -342,9 +424,11 @@ function bareImportCliStrategy(
   return {
     name: "bare-import",
     run(): { ok: true; path: string } | { ok: false; reason: string } {
-      const pkgJson = resolveModule(`${pkgName}/package.json`, import.meta.url);
+      const pkgJson =
+        resolveModule(`${pkgName}/package.json`, import.meta.url)
+        ?? findPackageJsonByDirWalk(pkgName, import.meta.url, undefined, deps?.exists);
       if (!pkgJson) {
-        return { ok: false, reason: `cannot resolve ${pkgName}/package.json` };
+        return { ok: false, reason: `cannot locate ${pkgName} package directory` };
       }
       const entry = path.join(path.dirname(pkgJson), entryRelative);
       return { ok: true, path: entry };

package/packages/shared/src/types.ts

@@ -89,14 +89,6 @@ export interface DashboardSession {
   firstMessage?: string;
   dataUnavailable?: boolean;
   resuming?: boolean;
-  /** Active flow name (set during flow execution) */
-  activeFlowName?: string;
-  /** Number of completed agents in the active flow */
-  flowAgentsDone?: number;
-  /** Total number of agents in the active flow */
-  flowAgentsTotal?: number;
-  /** Flow execution status */
-  flowStatus?: FlowStatus;
   /** Last known bridge entry count (for skip-wipe comparison on reconnect) */
   lastEntryCount?: number;
   /** OS process ID of the pi agent — used for force-kill escalation */
@@ -134,6 +126,14 @@ export interface DashboardSession {
    * See change: chat-markdown-local-images-and-math.
    */
   assets?: Record<string, { data: string; mimeType: string }>;
+  /**
+   * Mirror of pi's native steering + follow-up queues for this session.
+   * Populated from pi's `queue_update` event, forwarded by the bridge.
+   * `steering[]` typically empties every turn boundary (1-15 s); `followUp`
+   * is dashboard-enforced capacity 1 and drains on `agent_end`.
+   * See capability `mid-turn-prompt-queue`. See change: add-followup-edit-and-steer-cancel.
+   */
+  pendingQueues?: { steering: string[]; followUp: string[] };
 }
 
 // ── Extension UI System (Phase 1: management-modal slot) ───────────
@@ -316,6 +316,10 @@ export interface ImageContent {
   mimeType: string;
 }
 
+// PendingPrompt removed in change: add-followup-edit-and-steer-cancel.
+// Pi's native queues are now the single source of truth; `Session.pendingQueues`
+// holds `string[]` arrays directly from pi's `queue_update` event.
+
 /** File entry from directory listing */
 export interface FileEntry {
   path: string;

package/scripts/maybe-patch-package.cjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Conditionally runs `patch-package` only when both (a) the patch-package
+// module is resolvable and (b) a `patches/` directory exists in cwd.
+//
+// Why: this repo wires `patch-package` into the root `postinstall` so dev
+// installs (and CI `npm ci`) replay patches in node_modules. End-users who
+// run `npm install --omit=dev` against the published tarball have neither
+// `patch-package` in node_modules nor a `patches/` dir (it isn't published).
+// Without this guard the postinstall fails with exit 127 (`patch-package:
+// not found`), breaking standalone installs and Docker smoke tests.
+//
+// See change: fix-electron-appimage-maker (regression of CI standalone-install-smoke).
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const patchesDir = path.resolve(process.cwd(), "patches");
+if (!fs.existsSync(patchesDir)) {
+  process.exit(0);
+}
+
+let patchPackageBin;
+try {
+  // Resolve the patch-package binary path via its package.json's `bin` field
+  // without invoking npm; works on Windows where `which patch-package` is unreliable.
+  const pkgJsonPath = require.resolve("patch-package/package.json");
+  const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+  const binEntry = typeof pkgJson.bin === "string"
+    ? pkgJson.bin
+    : (pkgJson.bin && pkgJson.bin["patch-package"]);
+  if (!binEntry) {
+    process.exit(0);
+  }
+  patchPackageBin = path.resolve(path.dirname(pkgJsonPath), binEntry);
+} catch {
+  // patch-package not installed (e.g. `npm install --omit=dev`). No-op.
+  process.exit(0);
+}
+
+const result = spawnSync(process.execPath, [patchPackageBin], { stdio: "inherit" });
+process.exit(result.status ?? 1);