Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: add browser soft restart API for automatic recovery from lockups (issue #379)

op11350e2daa32e05
diff --git a/cmd/pinchtab/cmd_cli_management.go b/cmd/pinchtab/cmd_cli_management.go
index 83becede..285a102c 100644
--- a/cmd/pinchtab/cmd_cli_management.go
+++ b/cmd/pinchtab/cmd_cli_management.go
@@ -95,6 +95,17 @@ var instanceStopCmd = &cobra.Command{
},
}
+var instanceRestartCmd = &cobra.Command{
+ Use: "restart <id>",
+ Short: "Soft restart the browser process for an instance",
+ Args: cobra.ExactArgs(1),
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ browseractions.InstanceRestart(rt.client, rt.base, rt.token, args)
+ })
+ },
+}
+
var instanceLogsCmd = &cobra.Command{
Use: "logs <id>",
Short: "Get instance logs",
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index 8a2ad361..d3abc351 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -95,7 +95,7 @@ func registerBrowserCommands() {
func registerManagementCommands() {
setCommandGroup("management", instancesCmd, healthCmd, profilesCmd, activityCmd, instanceCmd)
- instanceCmd.AddCommand(startInstanceCmd, instanceNavigateCmd, instanceStopCmd, instanceLogsCmd)
+ instanceCmd.AddCommand(startInstanceCmd, instanceNavigateCmd, instanceStopCmd, instanceRestartCmd, instanceLogsCmd)
activityCmd.AddCommand(activityTabCmd)
configureManagementFlags()
diff --git a/internal/bridge/api.go b/internal/bridge/api.go
index 08fee374..19c594c7 100644
--- a/internal/bridge/api.go
+++ b/internal/bridge/api.go
@@ -36,6 +36,7 @@ type BridgeAPI interface {
Unlock(tabID, owner string) error
EnsureChrome(cfg *config.RuntimeConfig) error
+ RestartBrowser(cfg *config.RuntimeConfig) error
StealthStatus() *stealth.Status
// Memory metrics
diff --git a/internal/bridge/bridge.go b/internal/bridge/bridge.go
index 72d5a71c..b49968be 100644
--- a/internal/bridge/bridge.go
+++ b/internal/bridge/bridge.go
@@ -302,6 +302,83 @@ func (b *Bridge) EnsureChrome(cfg *config.RuntimeConfig) error {
// Cleanup releases browser resources and removes temporary profile directories.
// Must be called on shutdown to prevent Chrome process and disk leaks.
+func (b *Bridge) RestartBrowser(cfg *config.RuntimeConfig) error {
+ if cfg == nil {
+ cfg = b.Config
+ }
+ if cfg == nil {
+ return fmt.Errorf("runtime config is required")
+ }
+
+ b.initMu.Lock()
+
+ if b.BrowserCancel != nil {
+ b.BrowserCancel()
+ slog.Info("browser soft restart: cancelled browser context")
+ }
+ if b.AllocCancel != nil {
+ b.AllocCancel()
+ slog.Info("browser soft restart: cancelled allocator context")
+ }
+
+ profileDir := ""
+ if b.tempProfileDir != "" {
+ profileDir = b.tempProfileDir
+ } else {
+ profileDir = cfg.ProfileDir
+ }
+ if profileDir != "" {
+ time.Sleep(200 * time.Millisecond)
+ killed := killChromeByProfileDir(profileDir)
+ if killed > 0 {
+ slog.Info("browser soft restart: killed surviving chrome processes", "count", killed, "profileDir", profileDir)
+ }
+ ClearChromeSessions(profileDir)
+ }
+ b.ClearSavedState()
+
+ if b.tempProfileDir != "" {
+ if err := os.RemoveAll(b.tempProfileDir); err != nil {
+ slog.Warn("failed to remove temp profile dir during restart", "path", b.tempProfileDir, "err", err)
+ } else {
+ slog.Info("removed temp profile dir during restart", "path", b.tempProfileDir)
+ }
+ b.tempProfileDir = ""
+ }
+
+ b.initialized = false
+ b.BrowserCtx = nil
+ b.BrowserCancel = nil
+ b.AllocCtx = nil
+ b.AllocCancel = nil
+ b.TabManager = nil
+ b.stealthLaunchMode = stealth.LaunchModeUninitialized
+
+ if b.LogStore == nil {
+ b.LogStore = NewConsoleLogStore(1000)
+ } else {
+ b.LogStore = NewConsoleLogStore(1000)
+ }
+ b.netMonitor = NewNetworkMonitor(DefaultNetworkBufferSize)
+ if cfg.NetworkBufferSize > 0 {
+ b.netMonitor = NewNetworkMonitor(cfg.NetworkBufferSize)
+ }
+ b.fingerprintMu.Lock()
+ b.fingerprintOverlays = make(map[string]bool)
+ b.fingerprintMu.Unlock()
+ b.workerStealthTargets = sync.Map{}
+ b.Dialogs = NewDialogManager()
+ b.Locks = NewLockManager()
+ b.Config = cfg
+
+ b.StealthBundle = nil
+ b.Actions = nil
+ b.InitActionRegistry()
+
+ b.initMu.Unlock()
+ return b.EnsureChrome(cfg)
+}
+
func (b *Bridge) Cleanup() {
// Persist open tabs so next startup can restore them
if b.TabManager != nil && b.tempProfileDir == "" {
diff --git a/internal/bridge/state.go b/internal/bridge/state.go
index 5493a4f8..242389aa 100644
--- a/internal/bridge/state.go
+++ b/internal/bridge/state.go
@@ -174,6 +174,16 @@ func (b *Bridge) SaveState() {
}
}
+func (b *Bridge) ClearSavedState() {
+ if b == nil || b.Config == nil || b.Config.StateDir == "" {
+ return
+ }
+ path := filepath.Join(b.Config.StateDir, "sessions.json")
+ if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+ slog.Warn("clear saved state", "path", path, "err", err)
+ }
+}
+
func (b *Bridge) RestoreState() {
path := filepath.Join(b.Config.StateDir, "sessions.json")
data, err := os.ReadFile(path)
diff --git a/internal/cli/actions/actions_instance.go b/internal/cli/actions/actions_instance.go
index 4a0f7d6e..4a60692b 100644
--- a/internal/cli/actions/actions_instance.go
+++ b/internal/cli/actions/actions_instance.go
@@ -56,3 +56,8 @@ func InstanceStop(client *http.Client, base, token string, args []string) {
instID := args[0]
apiclient.DoPost(client, base, token, fmt.Sprintf("/instances/%s/stop", instID), nil)
}
+
+func InstanceRestart(client *http.Client, base, token string, args []string) {
+ instID := args[0]
+ apiclient.DoPost(client, base, token, fmt.Sprintf("/instances/%s/restart", instID), nil)
+}
diff --git a/internal/handlers/actions_test.go b/internal/handlers/actions_test.go
index d7903b1c..bd9efe28 100644
--- a/internal/handlers/actions_test.go
+++ b/internal/handlers/actions_test.go
@@ -33,6 +33,10 @@ func (m *liteActionBridge) EnsureChrome(cfg *config.RuntimeConfig) error {
return fmt.Errorf("ensureChrome should not be called for lite-routed actions")
}
+func (m *liteActionBridge) RestartBrowser(cfg *config.RuntimeConfig) error {
+ return nil
+}
+
type fakeLiteEngine struct {
clickRefs []string
typeCalls []struct {
@@ -79,6 +83,10 @@ func (m *failMockBridge) EnsureChrome(cfg *config.RuntimeConfig) error {
return nil
}
+func (m *failMockBridge) RestartBrowser(cfg *config.RuntimeConfig) error {
+ return nil
+}
+
func (m *failMockBridge) AvailableActions() []string {
return []string{bridge.ActionClick, bridge.ActionType}
}
diff --git a/internal/handlers/find_test.go b/internal/handlers/find_test.go
index 3484ca9d..326d2447 100644
--- a/internal/handlers/find_test.go
+++ b/internal/handlers/find_test.go
@@ -24,7 +24,8 @@ type findMockBridge struct {
refCache *bridge.RefCache
}
-func (m *findMockBridge) EnsureChrome(cfg *config.RuntimeConfig) error { return nil }
+func (m *findMockBridge) EnsureChrome(cfg *config.RuntimeConfig) error { return nil }
+func (m *findMockBridge) RestartBrowser(cfg *config.RuntimeConfig) error { return nil }
func (m *findMockBridge) TabContext(tabID string) (context.Context, string, error) {
if m.failTab {
diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.go
index 072f3024..e82f5d5f 100644
--- a/internal/handlers/handlers.go
+++ b/internal/handlers/handlers.go
@@ -101,6 +101,7 @@ func (h *Handlers) useLite(op engine.Capability, url string) bool {
func (h *Handlers) RegisterRoutes(mux *http.ServeMux, doShutdown func()) {
mux.HandleFunc("GET /health", h.HandleHealth)
mux.HandleFunc("POST /ensure-chrome", h.HandleEnsureChrome)
+ mux.HandleFunc("POST /browser/restart", h.HandleBrowserRestart)
mux.HandleFunc("GET /tabs", h.HandleTabs)
mux.HandleFunc("POST /tabs/{id}/navigate", h.HandleTabNavigate)
mux.HandleFunc("POST /tabs/{id}/back", h.HandleTabBack)
diff --git a/internal/handlers/handlers_test.go b/internal/handlers/handlers_test.go
index 2959054e..32a076ef 100644
--- a/internal/handlers/handlers_test.go
+++ b/internal/handlers/handlers_test.go
@@ -74,6 +74,10 @@ func (m *mockBridge) EnsureChrome(cfg *config.RuntimeConfig) error {
return nil
}
+func (m *mockBridge) RestartBrowser(cfg *config.RuntimeConfig) error {
+ return nil
+}
+
func (m *mockBridge) DeleteRefCache(tabID string) {}
func (m *mockBridge) TabLockInfo(tabID string) *bridge.LockInfo { return nil }
@@ -155,6 +159,9 @@ func TestHandlers(t *testing.T) {
if !strings.Contains(w.Body.String(), "openapi") {
t.Fatalf("expected /openapi.json response to include openapi")
}
+ if !strings.Contains(w.Body.String(), "/browser/restart") {
+ t.Fatalf("expected /openapi.json response to include /browser/restart")
+ }
req = httptest.NewRequest("GET", "/metrics", nil)
w = httptest.NewRecorder()
@@ -462,6 +469,7 @@ func TestRoutesRegistration(t *testing.T) {
{"GET", "/health", 200},
{"GET", "/tabs", 200},
{"GET", "/welcome", 200},
+ {"POST", "/browser/restart", 200},
{"POST", "/navigate", 400}, // missing body
}
diff --git a/internal/handlers/health_tabs.go b/internal/handlers/health_tabs.go
index a26606bb..292f0b1c 100644
--- a/internal/handlers/health_tabs.go
+++ b/internal/handlers/health_tabs.go
@@ -70,6 +70,18 @@ func (h *Handlers) HandleEnsureChrome(w http.ResponseWriter, r *http.Request) {
httpx.JSON(w, 200, map[string]string{"status": "chrome_ready"})
}
+func (h *Handlers) HandleBrowserRestart(w http.ResponseWriter, r *http.Request) {
+ if h.Bridge == nil {
+ httpx.Error(w, 503, fmt.Errorf("bridge not initialized"))
+ return
+ }
+ if err := h.Bridge.RestartBrowser(h.Config); err != nil {
+ httpx.Error(w, 500, fmt.Errorf("browser restart failed: %w", err))
+ return
+ }
+ httpx.JSON(w, 200, map[string]string{"status": "browser_restarted"})
+}
+
func (h *Handlers) HandleMetrics(w http.ResponseWriter, r *http.Request) {
result := map[string]any{"metrics": SnapshotMetrics()}
if hasFailureDiagnostics() {
diff --git a/internal/handlers/health_tabs_test.go b/internal/handlers/health_tabs_test.go
index 8c9af4dd..df654871 100644
--- a/internal/handlers/health_tabs_test.go
+++ b/internal/handlers/health_tabs_test.go
@@ -422,6 +422,13 @@ func (m *MockBridge) EnsureChrome(cfg *config.RuntimeConfig) error {
return nil
}
+func (m *MockBridge) RestartBrowser(cfg *config.RuntimeConfig) error {
+ if m.ensureChromeErr != "" {
+ return fmt.Errorf("%s", m.ensureChromeErr)
+ }
+ return nil
+}
+
func (m *MockBridge) StealthStatus() *stealth.Status {
return &stealth.Status{
Level: stealth.LevelLight,
diff --git a/internal/handlers/network_test.go b/internal/handlers/network_test.go
index 3a197273..11ec39e2 100644
--- a/internal/handlers/network_test.go
+++ b/internal/handlers/network_test.go
@@ -414,6 +414,10 @@ func (m *networkFailTabBridge) EnsureChrome(cfg *config.RuntimeConfig) error {
return nil
}
+func (m *networkFailTabBridge) RestartBrowser(cfg *config.RuntimeConfig) error {
+ return nil
+}
+
func TestHandleNetwork_TabNotFound(t *testing.T) {
nm := bridge.NewNetworkMonitor(100)
b := &networkFailTabBridge{nm: nm}
diff --git a/internal/handlers/openapi.go b/internal/handlers/openapi.go
index 3298dabc..d431e4fd 100644
--- a/internal/handlers/openapi.go
+++ b/internal/handlers/openapi.go
@@ -16,16 +16,17 @@ func (h *Handlers) HandleOpenAPI(w http.ResponseWriter, _ *http.Request) {
},
"x-pinchtab-security": security,
"paths": map[string]any{
- "/health": map[string]any{"get": map[string]any{"summary": "Health"}},
- "/tabs": map[string]any{"get": map[string]any{"summary": "List tabs"}},
- "/metrics": map[string]any{"get": map[string]any{"summary": "Runtime metrics"}},
- "/help": map[string]any{"get": map[string]any{"summary": "Human help"}},
- "/text": map[string]any{"get": map[string]any{"summary": "Extract text", "parameters": []map[string]any{{"name": "maxChars", "in": "query", "schema": map[string]string{"type": "integer"}}, {"name": "format", "in": "query", "schema": map[string]string{"type": "string"}}}}},
- "/navigate": map[string]any{"post": map[string]any{"summary": "Navigate"}, "get": map[string]any{"summary": "Navigate (query params)"}},
- "/nav": map[string]any{"get": map[string]any{"summary": "Navigate alias"}},
- "/action": map[string]any{"post": map[string]any{"summary": "Single action"}, "get": map[string]any{"summary": "Single action (query params)"}},
- "/actions": map[string]any{"post": map[string]any{"summary": "Batch actions"}},
- "/snapshot": map[string]any{"get": map[string]any{"summary": "Accessibility snapshot"}},
+ "/health": map[string]any{"get": map[string]any{"summary": "Health"}},
+ "/browser/restart": map[string]any{"post": map[string]any{"summary": "Soft restart the browser process without restarting the bridge"}},
+ "/tabs": map[string]any{"get": map[string]any{"summary": "List tabs"}},
+ "/metrics": map[string]any{"get": map[string]any{"summary": "Runtime metrics"}},
+ "/help": map[string]any{"get": map[string]any{"summary": "Human help"}},
+ "/text": map[string]any{"get": map[string]any{"summary": "Extract text", "parameters": []map[string]any{{"name": "maxChars", "in": "query", "schema": map[string]string{"type": "integer"}}, {"name": "format", "in": "query", "schema": map[string]string{"type": "string"}}}}},
+ "/navigate": map[string]any{"post": map[string]any{"summary": "Navigate"}, "get": map[string]any{"summary": "Navigate (query params)"}},
+ "/nav": map[string]any{"get": map[string]any{"summary": "Navigate alias"}},
+ "/action": map[string]any{"post": map[string]any{"summary": "Single action"}, "get": map[string]any{"summary": "Single action (query params)"}},
+ "/actions": map[string]any{"post": map[string]any{"summary": "Batch actions"}},
+ "/snapshot": map[string]any{"get": map[string]any{"summary": "Accessibility snapshot"}},
"/evaluate": map[string]any{"post": map[string]any{
"summary": "Run JavaScript in the current tab",
"description": security["evaluate"].Message,
diff --git a/internal/orchestrator/handlers.go b/internal/orchestrator/handlers.go
index 77bb846c..5303ae09 100644
--- a/internal/orchestrator/handlers.go
+++ b/internal/orchestrator/handlers.go
@@ -46,6 +46,7 @@ func (o *Orchestrator) registerHandlers(mux *http.ServeMux, skipLaunch bool) {
if !skipLaunch {
mux.HandleFunc("POST /instances/{id}/start", o.handleStartByInstanceID)
}
+ mux.HandleFunc("POST /instances/{id}/restart", o.handleRestartByInstanceID)
mux.HandleFunc("POST /instances/{id}/stop", o.handleStopByInstanceID)
mux.HandleFunc("GET /instances/{id}/logs", o.handleLogsByID)
mux.HandleFunc("GET /instances/{id}/logs/stream", o.handleLogsStreamByID)
diff --git a/internal/orchestrator/handlers_instances.go b/internal/orchestrator/handlers_instances.go
index b50a3bc7..9e3d613f 100644
--- a/internal/orchestrator/handlers_instances.go
+++ b/internal/orchestrator/handlers_instances.go
@@ -75,6 +75,29 @@ func (o *Orchestrator) handleStopByInstanceID(w http.ResponseWriter, r *http.Req
httpx.JSON(w, 200, map[string]string{"status": "stopped", "id": id})
}
+func (o *Orchestrator) handleRestartByInstanceID(w http.ResponseWriter, r *http.Request) {
+ id := r.PathValue("id")
+
+ o.mu.RLock()
+ inst, ok := o.instances[id]
+ o.mu.RUnlock()
+ if !ok {
+ httpx.Error(w, 404, fmt.Errorf("instance %q not found", id))
+ return
+ }
+ if !instanceIsActive(inst) || inst.Status != "running" {
+ httpx.Error(w, 503, fmt.Errorf("instance %q is not running (status: %s)", id, inst.Status))
+ return
+ }
+
+ targetURL, err := o.instancePathURL(inst, "/browser/restart", "")
+ if err != nil {
+ httpx.Error(w, 502, err)
+ return
+ }
+ o.proxyToURL(w, r, targetURL)
+}
+
func (o *Orchestrator) handleStartByInstanceID(w http.ResponseWriter, r *http.Request) {
id := r.PathValue("id")