fix(plan-canvas): sanitize PDF failures

scripts/lib/plan-canvas/server.js

@@ -433,8 +433,18 @@ function createPlanCanvasServer({
         });
         return sendPdf(res, pdf);
       } catch (error) {
-        const statusCode = error.code === 'PDF_BROWSER_NOT_FOUND' ? 503 : 500;
-        return sendJson(res, statusCode, { error: error.message, code: error.code || 'PDF_EXPORT_FAILED' });
+        const code = error.code || 'PDF_EXPORT_FAILED';
+        log(`[plan-canvas] PDF export failed (${code}): ${error.stack || error.message}`);
+        if (code === 'PDF_BROWSER_NOT_FOUND') {
+          return sendJson(res, 503, {
+            error: 'PDF export requires Google Chrome, Chromium, or Microsoft Edge; configure ECC_PLAN_CANVAS_CHROME_PATH if auto-discovery cannot find it',
+            code
+          });
+        }
+        return sendJson(res, 500, {
+          error: 'PDF export failed; check the Plan Canvas server log for details',
+          code: 'PDF_EXPORT_FAILED'
+        });
       } finally {
         pdfSnapshot = null;
         pdfExportActive = false;

scripts/plan-canvas.js

@@ -179,19 +179,20 @@ async function withServerStartLock(port, task, {
   const lockPort = validatePort(port);
   const startedAt = Date.now();
   let socket = null;
+  let socketError = null;
 
   while (true) {
     try {
       socket = await new Promise((resolve, reject) => {
         const candidate = dgramImpl.createSocket('udp4');
         const onError = error => {
-          candidate.close();
+          try { candidate.close(); } catch { /* failed bind has no open handle */ }
           reject(error);
         };
         candidate.once('error', onError);
         candidate.bind(lockPort, DEFAULT_HOST, () => {
           candidate.removeListener('error', onError);
-          candidate.on('error', () => {});
+          candidate.on('error', error => { socketError = error; });
           candidate.unref();
           resolve(candidate);
         });
@@ -206,11 +207,23 @@ async function withServerStartLock(port, task, {
     }
   }
 
+  let result;
   try {
-    return await task();
+    result = await task();
   } finally {
-    if (socket) socket.close();
+    if (socket) {
+      await new Promise(resolve => {
+        try { socket.close(resolve); } catch { resolve(); }
+      });
+    }
   }
+  if (socketError) {
+    const error = new Error(`Plan Canvas startup lock failed on port ${port}: ${socketError.message}`);
+    error.code = 'PLAN_CANVAS_START_LOCK_FAILED';
+    error.cause = socketError;
+    throw error;
+  }
+  return result;
 }
 
 function serverIsCompatible(health) {