wip(handoff): start issue cleanup plan sections 1 and 2

Co-Authored-By: Codex <noreply@openai.com>

frontend/src/components/assistant/TaskLane.tsx

@@ -31,6 +31,62 @@ interface ActionResponse {
 
 type TaskResponse = QuestionResponse | ActionResponse
 
+interface DiagnosticHelp {
+  what: string
+  lookFor: string
+  usefulWhen: string
+}
+
+function getDiagnosticHelp(action: ActionResponse): DiagnosticHelp {
+  const command = (action.command || '').toLowerCase()
+
+  if (command.includes('test-netconnection') || command.includes('ping ')) {
+    return {
+      what: action.description || 'Checks whether the target is reachable over the network.',
+      lookFor: 'Successful replies, low packet loss, and whether the expected port shows as open.',
+      usefulWhen: 'Use it when you need to separate a service problem from a basic connectivity problem.',
+    }
+  }
+
+  if (command.includes('nslookup') || command.includes('resolve-dnsname')) {
+    return {
+      what: action.description || 'Checks how DNS resolves the hostname or record.',
+      lookFor: 'Wrong IPs, NXDOMAIN responses, timeout errors, or different answers from different resolvers.',
+      usefulWhen: 'Use it when names fail but direct IP access may still work.',
+    }
+  }
+
+  if (command.includes('ipconfig') || command.includes('get-netipconfiguration')) {
+    return {
+      what: action.description || 'Shows local IP, gateway, DNS, and adapter configuration.',
+      lookFor: 'APIPA addresses, missing gateways, wrong DNS servers, disconnected adapters, or stale leases.',
+      usefulWhen: 'Use it early when the symptom may be local network configuration.',
+    }
+  }
+
+  if (command.includes('get-eventlog') || command.includes('get-winevent') || command.includes('eventlog')) {
+    return {
+      what: action.description || 'Reads Windows event logs for recent errors or warnings.',
+      lookFor: 'Events matching the failure time, repeated error IDs, service crashes, or permission failures.',
+      usefulWhen: 'Use it when the UI only shows a generic error and you need system-level evidence.',
+    }
+  }
+
+  if (command.includes('get-service') || command.includes('restart-service')) {
+    return {
+      what: action.description || 'Checks service state on the affected machine.',
+      lookFor: 'Stopped services, restart loops, disabled startup types, or dependency failures.',
+      usefulWhen: 'Use it when a feature depends on a Windows service or background agent.',
+    }
+  }
+
+  return {
+    what: action.description || 'Runs the diagnostic check suggested by FlowPilot.',
+    lookFor: 'Errors, unexpected values, failed checks, or output that differs from a known-good machine.',
+    usefulWhen: 'Use it when you need evidence before choosing the next troubleshooting step.',
+  }
+}
+
 interface TaskLaneProps {
   questions: QuestionItem[]
   actions: ActionItem[]
@@ -98,6 +154,7 @@ export function TaskLane({ questions, actions, sessionId, onSubmit, onClose, loa
   const [showRunAll, setShowRunAll] = useState(false)
   const [showPreview, setShowPreview] = useState(false)
   const [copiedKey, setCopiedKey] = useState<string | null>(null)
+  const [expandedHelpKey, setExpandedHelpKey] = useState<string | null>(null)
 
   // ── Resize state ──
   const DEFAULT_WIDTH = 340
@@ -166,22 +223,22 @@ export function TaskLane({ questions, actions, sessionId, onSubmit, onClose, loa
         questions: questionsRef.current.map(q => ({ text: q.text, context: q.context })),
         actions: actionsRef.current.map(a => ({ label: a.label, command: a.command, description: a.description })),
         responses: tasksRef.current as unknown as Array<Record<string, unknown>>,
-      }).catch(() => { /* silent — best-effort save */ })
+      }).catch(() => { /* silent - best-effort save */ })
     }, 2000)
     return () => { if (saveTimerRef.current) clearTimeout(saveTimerRef.current) }
-  }, [sessionId, tasks]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [sessionId, tasks])
 
   // Reset when new tasks come in from AI response — but preserve saved state
   useEffect(() => {
     if (sessionId) {
       const saved = loadTaskState(sessionId)
       if (saved && saved.length > 0) {
-        // eslint-disable-next-line react-hooks/set-state-in-effect -- intentional: syncs derived state from prop changes
+        // eslint-disable-next-line react-hooks/set-state-in-effect -- intentional: syncs task UI from persisted session state
         setTasks(saved)
         return
       }
     }
-    // eslint-disable-next-line react-hooks/set-state-in-effect -- intentional: syncs derived state from prop changes
+
     setTasks([
       ...questions.map((q): QuestionResponse => ({
         type: 'question', text: q.text, context: q.context, state: 'pending', value: '',
@@ -190,7 +247,7 @@ export function TaskLane({ questions, actions, sessionId, onSubmit, onClose, loa
         type: 'action', label: a.label, command: a.command, description: a.description, state: 'pending', value: '',
       })),
     ])
-  }, [questions, actions]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [questions, actions, sessionId])
 
   const updateTask = (idx: number, updates: Partial<TaskResponse>) => {
     setTasks(prev => prev.map((t, i) => i === idx ? { ...t, ...updates } as TaskResponse : t))
@@ -490,10 +547,49 @@ export function TaskLane({ questions, actions, sessionId, onSubmit, onClose, loa
 
               return (
                 <div key={idx} id={`task-lane-card-${idx}`} className="rounded-lg border border-default bg-card p-3 mb-2 hover:border-hover transition-colors">
-                  <div className="text-[0.8125rem] font-medium text-heading">{a.label}</div>
-                  {a.description && (
-                    <div className="text-[0.6875rem] text-muted-foreground mt-0.5 leading-relaxed">{a.description}</div>
-                  )}
+                  <div className="flex items-start justify-between gap-2">
+                    <div className="min-w-0 flex-1">
+                      <div className="text-[0.8125rem] font-medium text-heading">{a.label}</div>
+                      {a.description && (
+                        <div className="text-[0.6875rem] text-muted-foreground mt-0.5 leading-relaxed">{a.description}</div>
+                      )}
+                    </div>
+                    <button
+                      type="button"
+                      onClick={() => setExpandedHelpKey(expandedHelpKey === `${idx}` ? null : `${idx}`)}
+                      className={cn(
+                        'shrink-0 rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-elevated/50 hover:text-heading',
+                        expandedHelpKey === `${idx}` && 'bg-accent-dim text-accent-text',
+                      )}
+                      title="Explain this check"
+                      aria-label="Explain this diagnostic check"
+                      aria-expanded={expandedHelpKey === `${idx}`}
+                    >
+                      <MessageCircleQuestion size={13} />
+                    </button>
+                  </div>
+
+                  {expandedHelpKey === `${idx}` && (() => {
+                    const help = getDiagnosticHelp(a)
+                    return (
+                      <div className="mt-2 rounded-lg border border-info/20 bg-info-dim/20 p-2.5 text-[0.6875rem] leading-relaxed">
+                        <div className="space-y-1.5">
+                          <p>
+                            <span className="font-semibold text-heading">What it checks: </span>
+                            <span className="text-muted-foreground">{help.what}</span>
+                          </p>
+                          <p>
+                            <span className="font-semibold text-heading">What to look for: </span>
+                            <span className="text-muted-foreground">{help.lookFor}</span>
+                          </p>
+                          <p>
+                            <span className="font-semibold text-heading">When to use it: </span>
+                            <span className="text-muted-foreground">{help.usefulWhen}</span>
+                          </p>
+                        </div>
+                      </div>
+                    )
+                  })()}
 
                   {a.command && (
                     <div className="mt-2 flex items-center gap-2 rounded bg-code px-2.5 py-1.5">