@llblab/pi-telegram 0.39.2 → 0.39.3

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.39.3: Windows IPC And Outbound Voice Hotfix
+
+- `Windows IPC Replacement`: Replaces an older same-process Named Pipe server before a new session generation listens on the stable endpoint, preventing `EADDRINUSE` during reload while keeping a late stop from invalidating its successor.
+- `Windows IPC Fencing`: Applies the ownership commit fence before publishing a Named Pipe, so a stale generation that loses authority cannot expose an endpoint or block its replacement.
+- `Windows Voice Commands`: Executes trusted `.cmd` and `.bat` outbound-handler wrappers through escaped `%ComSpec%` adaptation while preserving direct shell-free execution for native executables, bounded process controls, npm command-shim argument isolation, and paths containing spaces.
+- `Windows Template Paths`: Preserves backslashes in quoted and unquoted Windows executable and artifact paths without breaking intentional escaped whitespace or quotes, allowing configured TTS handlers to produce and upload OGG/Opus voice replies through direct and follower transport.
+
 ## 0.39.2: Deleted Thread Receipt Hotfix
 
 - `Deleted Thread Receipt`: Terminally settles the currently executing durable update when Telegram returns exact HTTP 400 stale/deleted-thread evidence for its `{chatId, threadId}`, including leader-first shared-store invalidation followed by follower settlement. Transient, ambiguous, unrelated, and stale-looking HTTP 5xx failures retain indefinite retry authority; persisted follower records remain restart hints rather than speculative live registrations.

package/lib/bus.ts

@@ -950,6 +950,18 @@ export interface TelegramBusLocalServer {
   ensureEndpoint: () => Promise<boolean>;
 }
 
+const TELEGRAM_ACTIVE_LOCAL_SERVERS = Symbol.for(
+  "@llblab/pi-telegram/active-local-servers",
+);
+type TelegramBusServerGlobal = typeof globalThis & {
+  [TELEGRAM_ACTIVE_LOCAL_SERVERS]?: Map<string, TelegramBusLocalServer>;
+};
+
+function getActiveTelegramBusLocalServers(): Map<string, TelegramBusLocalServer> {
+  const root = globalThis as TelegramBusServerGlobal;
+  return (root[TELEGRAM_ACTIVE_LOCAL_SERVERS] ??= new Map());
+}
+
 export type TelegramBusSocketPathSource = string | (() => string);
 
 const TELEGRAM_BUS_MAX_DIRECT_UNIX_ENDPOINT_BYTES = 80;
@@ -1563,6 +1575,11 @@ export function createTelegramBusLocalServer(
     start: async () => {
       if (server) return;
       const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
+      const activeServers = getActiveTelegramBusLocalServers();
+      const replacedServer = activeServers.get(socketPath);
+      if (replacedServer && replacedServer !== runtime) {
+        await replacedServer.stop();
+      }
       const usesWindowsPipe = isTelegramBusPipePath(socketPath);
       const endpointGeneration = randomBytes(8).toString("hex");
       const listenPath = usesWindowsPipe
@@ -1601,6 +1618,19 @@ export function createTelegramBusLocalServer(
           await delayTelegramBusTransportRetry(25);
         }
       }
+      if (usesWindowsPipe) {
+        await deps.beforeEndpointPublication?.();
+        const committed = deps.commitEndpointPublication
+          ? deps.commitEndpointPublication(() => {})
+          : true;
+        if (!committed) {
+          activeSocketPath = undefined;
+          activeListenPath = undefined;
+          throw new Error(
+            "Telegram bus endpoint publication lost transport ownership.",
+          );
+        }
+      }
       server = createServer((socket) => {
         sockets.add(socket);
         let buffer = "";
@@ -1634,6 +1664,7 @@ export function createTelegramBusLocalServer(
           server?.once("error", reject);
           server?.listen(listenPath, resolve);
         });
+        activeServers.set(socketPath, runtime);
         deps.recordTransportEvent?.(
           "server-started",
           getTelegramBusEndpointDiagnostics(socketPath),
@@ -1674,6 +1705,9 @@ export function createTelegramBusLocalServer(
           server = undefined;
           activeSocketPath = undefined;
           activeListenPath = undefined;
+          if (activeServers.get(socketPath) === runtime) {
+            activeServers.delete(socketPath);
+          }
           if (failedServer) {
             await new Promise<void>((resolve) =>
               failedServer.close(() => resolve()),
@@ -1689,6 +1723,12 @@ export function createTelegramBusLocalServer(
       const activeServer = server;
       const socketPath = activeSocketPath;
       const listenPath = activeListenPath;
+      if (
+        socketPath &&
+        getActiveTelegramBusLocalServers().get(socketPath) === runtime
+      ) {
+        getActiveTelegramBusLocalServers().delete(socketPath);
+      }
       server = undefined;
       activeSocketPath = undefined;
       activeListenPath = undefined;

package/lib/command-templates.ts

@@ -6,7 +6,7 @@
 
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
-import { isAbsolute, resolve } from "node:path";
+import { extname, isAbsolute, normalize, resolve } from "node:path";
 
 export type CommandTemplateFailureScope = "continue" | "branch" | "root";
 
@@ -541,7 +541,8 @@ export function splitCommandTemplate(input: string): string[] {
   let quote: "'" | '"' | undefined;
   let escaped = false;
   let active = false;
-  for (const char of input) {
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index] ?? "";
     if (escaped) {
       current += char;
       escaped = false;
@@ -549,7 +550,16 @@ export function splitCommandTemplate(input: string): string[] {
       continue;
     }
     if (char === "\\" && quote !== "'") {
-      escaped = true;
+      const next = input[index + 1];
+      const escapesNext = quote === '"'
+        ? next === '"' || next === "\\"
+        : next !== undefined &&
+          (/\s/u.test(next) || next === "'" || next === '"' || next === "\\");
+      if (escapesNext) {
+        escaped = true;
+      } else {
+        current += "\\";
+      }
       active = true;
       continue;
     }
@@ -844,15 +854,66 @@ export async function execCommandTemplate(
   return lastResult;
 }
 
+const WINDOWS_COMMAND_META_CHARS = /([()\][%!^"`<>&|;, *?])/g;
+
+function escapeWindowsCommand(value: string): string {
+  return value.replace(WINDOWS_COMMAND_META_CHARS, "^$1");
+}
+
+function escapeWindowsCommandArgument(
+  value: string,
+  doubleEscapeMetaChars: boolean,
+): string {
+  let escaped = value
+    .replace(/(?=(\\+?)?)\1"/g, "$1$1\\\"")
+    .replace(/(?=(\\+?)?)\1$/g, "$1$1");
+  escaped = `"${escaped}"`.replace(WINDOWS_COMMAND_META_CHARS, "^$1");
+  return doubleEscapeMetaChars
+    ? escaped.replace(WINDOWS_COMMAND_META_CHARS, "^$1")
+    : escaped;
+}
+
+function resolveCommandTemplateSpawn(
+  command: string,
+  args: string[],
+): {
+  command: string;
+  args: string[];
+  windowsVerbatimArguments?: boolean;
+} {
+  if (
+    process.platform !== "win32" ||
+    ![".bat", ".cmd"].includes(extname(command).toLowerCase())
+  ) {
+    return { command, args };
+  }
+  const normalizedCommand = normalize(command);
+  const isNodeModulesShim = /[\\/]node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/iu
+    .test(normalizedCommand);
+  const shellCommand = [
+    escapeWindowsCommand(normalizedCommand),
+    ...args.map((arg) =>
+      escapeWindowsCommandArgument(arg, isNodeModulesShim)
+    ),
+  ].join(" ");
+  return {
+    command: process.env.ComSpec ?? process.env.COMSPEC ?? "cmd.exe",
+    args: ["/d", "/s", "/c", `"${shellCommand}"`],
+    windowsVerbatimArguments: true,
+  };
+}
+
 function execCommandTemplateOnce(
   command: string,
   args: string[],
   options: CommandTemplateExecOptions = {},
 ): Promise<CommandTemplateExecResult> {
   return new Promise((resolve) => {
-    const proc = spawn(command, args, {
+    const invocation = resolveCommandTemplateSpawn(command, args);
+    const proc = spawn(invocation.command, invocation.args, {
       cwd: options.cwd,
       shell: false,
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
       stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
     });
     let stdout = "";

package/lib/locks.ts

@@ -423,7 +423,12 @@ function reclaimAbandonedDirectoryGuard(
     // Claim inside the still-occupied guard before making its stable path free.
     renameRecovery(sourcePath, reclaimPath);
   } catch (error) {
-    if ((error as { code?: unknown })?.code === "ENOENT") return false;
+    const code = (error as { code?: unknown })?.code;
+    if (code === "ENOENT") return false;
+    // macOS may report EINVAL instead of ENOENT when another process wins
+    // the same source rename. Only classify it as contention once the
+    // observed source is actually gone; preserve unrelated EINVAL failures.
+    if (code === "EINVAL" && !existsSync(sourcePath)) return false;
     throw error;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.39.2",
+  "version": "0.39.3",
   "private": false,
   "publishConfig": {
     "access": "public"