Refactor error handling to use platform-specific worker restart instructions

- Updated multiple hooks (context-hook, new-hook, save-hook, summary-hook, user-message-hook) to throw errors using `getWorkerRestartInstructions` for improved user guidance on worker connection issues.
- Enhanced `handleWorkerError` function to utilize the new error message generator for consistent error reporting.
- Modified `ensureWorkerRunning` function to provide detailed instructions based on the worker's state, including port information.
- Introduced `getWorkerRestartInstructions` utility in `error-messages.ts` to generate platform-aware error messages for worker failures.

src/hooks/context-hook.ts

@@ -11,6 +11,7 @@ import { stdin } from "process";
 import { ensureWorkerRunning, getWorkerPort } from "../shared/worker-utils.js";
 import { HOOK_TIMEOUTS } from "../shared/hook-constants.js";
 import { handleWorkerError } from "../shared/hook-error-handler.js";
+import { getWorkerRestartInstructions } from "../utils/error-messages.js";
 
 export interface SessionStartInput {
   session_id: string;
@@ -34,7 +35,7 @@ async function contextHook(input?: SessionStartInput): Promise<string> {
 
     if (!response.ok) {
       const errorText = await response.text();
-      throw new Error(`Failed to fetch context: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
     }
 
     const result = await response.text();

src/hooks/new-hook.ts

@@ -4,6 +4,7 @@ import { createHookResponse } from './hook-response.js';
 import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
 import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
 import { handleWorkerError } from '../shared/hook-error-handler.js';
+import { getWorkerRestartInstructions } from '../utils/error-messages.js';
 
 export interface UserPromptSubmitInput {
   session_id: string;
@@ -52,7 +53,7 @@ async function newHook(input?: UserPromptSubmitInput): Promise<void> {
 
     if (!initResponse.ok) {
       const errorText = await initResponse.text();
-      throw new Error(`Failed to initialize session: ${initResponse.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
     }
 
     const initResult = await initResponse.json();
@@ -86,7 +87,7 @@ async function newHook(input?: UserPromptSubmitInput): Promise<void> {
 
     if (!response.ok) {
       const errorText = await response.text();
-      throw new Error(`Failed to start SDK agent: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
     }
   } catch (error: any) {
     handleWorkerError(error);

src/hooks/save-hook.ts

@@ -13,6 +13,7 @@ import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
 import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';
 import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
 import { handleWorkerError } from '../shared/hook-error-handler.js';
+import { getWorkerRestartInstructions } from '../utils/error-messages.js';
 
 export interface PostToolUseInput {
   session_id: string;
@@ -67,7 +68,7 @@ async function saveHook(input?: PostToolUseInput): Promise<void> {
       logger.failure('HOOK', 'Failed to send observation', {
         status: response.status
       }, errorText);
-      throw new Error(`Failed to send observation to worker: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
     }
 
     logger.debug('HOOK', 'Observation sent successfully', { toolName: tool_name });

src/hooks/summary-hook.ts

@@ -17,6 +17,7 @@ import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';
 import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
 import { handleWorkerError } from '../shared/hook-error-handler.js';
 import { extractLastMessage } from '../shared/transcript-parser.js';
+import { getWorkerRestartInstructions } from '../utils/error-messages.js';
 
 export interface StopInput {
   session_id: string;
@@ -72,7 +73,7 @@ async function summaryHook(input?: StopInput): Promise<void> {
       logger.failure('HOOK', 'Failed to generate summary', {
         status: response.status
       }, errorText);
-      throw new Error(`Failed to request summary from worker: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
     }
 
     logger.debug('HOOK', 'Summary request sent successfully');

src/hooks/user-message-hook.ts

@@ -9,6 +9,7 @@
 import { basename } from "path";
 import { ensureWorkerRunning, getWorkerPort } from "../shared/worker-utils.js";
 import { HOOK_EXIT_CODES } from "../shared/hook-constants.js";
+import { getWorkerRestartInstructions } from "../utils/error-messages.js";
 
 try {
   // Ensure worker is running
@@ -24,7 +25,7 @@ try {
   );
 
   if (!response.ok) {
-    throw new Error(`Worker error ${response.status}`);
+    throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
   }
 
   const output = await response.text();

src/shared/hook-error-handler.ts

@@ -1,3 +1,5 @@
+import { getWorkerRestartInstructions } from '../utils/error-messages.js';
+
 /**
  * Handles fetch errors by providing user-friendly messages for connection issues
  * @throws Error with helpful message if worker is unreachable, re-throws original otherwise
@@ -8,9 +10,7 @@ export function handleWorkerError(error: any): never {
       error.name === 'TimeoutError' ||
       error.message?.includes('fetch failed') ||
       error.message?.includes('Unable to connect')) {
-    throw new Error(
-      "There's a problem with the worker. Try: npm run worker:restart"
-    );
+    throw new Error(getWorkerRestartInstructions());
   }
   throw error;
 }

src/shared/worker-utils.ts

@@ -6,6 +6,7 @@ import { logger } from "../utils/logger.js";
 import { HOOK_TIMEOUTS, getTimeout } from "./hook-constants.js";
 import { ProcessManager } from "../services/process/ProcessManager.js";
 import { SettingsDefaultsManager } from "./SettingsDefaultsManager.js";
+import { getWorkerRestartInstructions } from "../utils/error-messages.js";
 
 const MARKETPLACE_ROOT = path.join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
 
@@ -197,9 +198,10 @@ export async function ensureWorkerRunning(): Promise<void> {
   if (!started) {
     const port = getWorkerPort();
     throw new Error(
-      `Worker service failed to start on port ${port}.\n\n` +
-      `To start manually, run: npm run worker:start\n` +
-      `If already running, try: npm run worker:restart`
+      getWorkerRestartInstructions({
+        port,
+        customPrefix: `Worker service failed to start on port ${port}.`
+      })
     );
   }
 
@@ -217,7 +219,9 @@ export async function ensureWorkerRunning(): Promise<void> {
   const port = getWorkerPort();
   logger.error('SYSTEM', 'Worker started but not responding to health checks');
   throw new Error(
-    `Worker service started but is not responding on port ${port}.\n\n` +
-    `Try: npm run worker:restart`
+    getWorkerRestartInstructions({
+      port,
+      customPrefix: `Worker service started but is not responding on port ${port}.`
+    })
   );
 }

src/utils/error-messages.ts

@@ -0,0 +1,53 @@
+/**
+ * Platform-aware error message generator for worker connection failures
+ */
+
+export interface WorkerErrorMessageOptions {
+  port?: number;
+  includeSkillFallback?: boolean;
+  customPrefix?: string;
+}
+
+/**
+ * Generate platform-specific worker restart instructions
+ * @param options Configuration for error message generation
+ * @returns Formatted error message with platform-specific paths and commands
+ */
+export function getWorkerRestartInstructions(
+  options: WorkerErrorMessageOptions = {}
+): string {
+  const {
+    port,
+    includeSkillFallback = false,
+    customPrefix
+  } = options;
+
+  const isWindows = process.platform === 'win32';
+
+  // Platform-specific directory paths
+  const pluginDir = isWindows
+    ? '%USERPROFILE%\\.claude\\plugins\\marketplaces\\thedotmack'
+    : '~/.claude/plugins/marketplaces/thedotmack';
+
+  // Platform-specific terminal name
+  const terminal = isWindows
+    ? 'Command Prompt or PowerShell'
+    : 'Terminal';
+
+  // Build error message
+  const prefix = customPrefix || 'Worker service connection failed.';
+  const portInfo = port ? ` (port ${port})` : '';
+
+  let message = `${prefix}${portInfo}\n\n`;
+  message += `To restart the worker:\n`;
+  message += `1. Exit Claude Code completely\n`;
+  message += `2. Open ${terminal}\n`;
+  message += `3. Navigate to: ${pluginDir}\n`;
+  message += `4. Run: npm run worker:restart`;
+
+  if (includeSkillFallback) {
+    message += `\n\nIf that doesn't work, try: /troubleshoot`;
+  }
+
+  return message;
+}