fix: surface actionable hint when Claude model unavailable on Vertex

src/agent/agent-lifecycle.js

@@ -573,13 +573,43 @@ async function runTaskAttempt(agent, triggeringMessage) {
   await executeOnCompleteHookWithRetry(agent, triggeringMessage, result);
 }
 
+function detectVertexModelError(errorMessage) {
+  try {
+    const parsed = JSON.parse(errorMessage);
+    if (parsed.api_error_status !== 404) return null;
+    const result = parsed.result || '';
+    const isVertexModelError =
+      result.includes('vertex deployment') ||
+      result.includes('may not exist or you may not have access');
+    if (!isVertexModelError) return null;
+    const modelMatch = result.match(/model\s+\(([^)]+)\)/);
+    return { model: modelMatch ? modelMatch[1] : null };
+  } catch {
+    return null;
+  }
+}
+
 function logTaskAttemptFailure(agent, attempt, maxRetries, error) {
   // Log attempt failure
   console.error(`
 ${'='.repeat(80)}`);
   console.error(`🔴 TASK EXECUTION FAILED - AGENT: ${agent.id} (Attempt ${attempt}/${maxRetries})`);
   console.error(`${'='.repeat(80)}`);
   console.error(`Error: ${error.message}`);
+
+  const vertexError = detectVertexModelError(error.message);
+  if (vertexError) {
+    const model = vertexError.model ? `"${vertexError.model}" is` : 'Selected model is';
+    console.error(`
+⚠️  ${model} not available on your Vertex AI deployment.
+    Fix: set explicit model IDs that are enabled on your deployment:
+
+    zeroshot settings set providerSettings.claude.levelOverrides '{"level1": {"model": "claude-sonnet-4-6"}, "level2": {"model": "claude-sonnet-4-6"}, "level3": {"model": "claude-sonnet-4-6"}}'
+
+    Replace "claude-sonnet-4-6" with whichever Claude model your deployment has enabled.
+    You can test a model with: claude --dangerously-skip-permissions -p "hi" --model <model-id>
+`);
+  }
 }
 
 async function handleLockContention() {
@@ -846,6 +876,11 @@ async function executeTask(agent, triggeringMessage) {
         await handleFinalFailure(agent, triggeringMessage, error, 1);
         return;
       }
+      if (detectVertexModelError(error.message)) {
+        // Model unavailability on Vertex is deterministic — retrying wastes nothing but time.
+        await handleFinalFailure(agent, triggeringMessage, error, 1);
+        return;
+      }
       const updated = maybeExtendMaxRetries({
         error,
         attempt,