Skip to content

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

fix: the server discards all logs unless --verbose (PIN-072)

Luigi Agosti810e5b1d0583
diff --git a/cmd/pinchtab/cmd_server.go b/cmd/pinchtab/cmd_server.go
index 07d3316a..5067a47b 100644
--- a/cmd/pinchtab/cmd_server.go
+++ b/cmd/pinchtab/cmd_server.go
@@ -2,12 +2,14 @@ package main
import (
"fmt"
+ "log/slog"
"os"
"strings"
"github.com/pinchtab/pinchtab/internal/cli"
"github.com/pinchtab/pinchtab/internal/config"
"github.com/pinchtab/pinchtab/internal/config/workflow"
+ "github.com/pinchtab/pinchtab/internal/safelog"
"github.com/pinchtab/pinchtab/internal/server"
"github.com/spf13/cobra"
)
@@ -51,7 +53,10 @@ var serverCmd = &cobra.Command{
cfg.ExtensionPaths = append(cfg.ExtensionPaths, exts...)
}
verbose, _ := cmd.Flags().GetBool("verbose")
- cfg.VerboseStartup = verbose
+ cfg.VerboseBanner = verbose
+ logLevel, _ := cmd.Flags().GetString("log-level")
+ cfg.LogLevel = logLevel
+ applyLogLevel(cfg, verbose)
browserName, _ := cmd.Flags().GetString("browser")
if browserName != "" {
@@ -68,6 +73,7 @@ var serverCmd = &cobra.Command{
Yolo: yolo,
Headed: headed,
Verbose: verbose,
+ LogLevel: logLevel,
Extensions: append([]string(nil), exts...),
Browser: browserName,
Bind: bind,
@@ -94,6 +100,23 @@ func applyServerAddressFlags(cfg *config.RuntimeConfig, bind, port string) {
}
}
+func applyLogLevel(cfg *config.RuntimeConfig, verbose bool) {
+ if strings.TrimSpace(cfg.LogLevel) != "" {
+ level, err := safelog.ParseLevel(cfg.LogLevel)
+ if err != nil {
+ fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, "pinchtab: "+err.Error()))
+ os.Exit(1)
+ }
+ safelog.SetLevel(level)
+ return
+ }
+ if verbose {
+ safelog.SetLevel(slog.LevelDebug)
+ return
+ }
+ safelog.SetLevel(safelog.DefaultLevel)
+}
+
func init() {
serverCmd.GroupID = "primary"
serverCmd.Flags().String("bind", "", "Bind address for the HTTP server (overrides config server.bind)")
@@ -101,7 +124,8 @@ func init() {
serverCmd.Flags().StringArrayP("extension", "e", nil, "Load browser extension (repeatable)")
serverCmd.Flags().BoolP("headed", "H", false, "Start default instance in headed mode")
serverCmd.Flags().BoolP("yolo", "y", false, "Apply guards down preset (enables evaluate, macro, download, cookies)")
- serverCmd.Flags().BoolP("verbose", "v", false, "Show full startup banner and logs")
+ serverCmd.Flags().BoolP("verbose", "v", false, "Show the full startup banner and log at debug level")
+ serverCmd.Flags().String("log-level", "", "Minimum log level: debug, info (default), warn or error")
serverCmd.Flags().String("browser", "", "Browser to use: chrome, cloak, or ghost-chrome (overrides config)")
serverCmd.Flags().BoolP("background", "b", false, "Spawn the server detached and return JSON with pid/url/token")
serverCmd.Flags().String("background-child", "", "Internal marker for background server ownership")
diff --git a/cmd/pinchtab/cmd_server_background.go b/cmd/pinchtab/cmd_server_background.go
index 00155441..030b3d1a 100644
--- a/cmd/pinchtab/cmd_server_background.go
+++ b/cmd/pinchtab/cmd_server_background.go
@@ -38,6 +38,7 @@ type serverBackgroundOptions struct {
Yolo bool
Headed bool
Verbose bool
+ LogLevel string
Extensions []string
Browser string
Bind string
@@ -209,6 +210,9 @@ func backgroundServerArgs(marker string, opts serverBackgroundOptions) []string
if opts.Verbose {
args = append(args, "-v")
}
+ if opts.LogLevel != "" {
+ args = append(args, "--log-level", opts.LogLevel)
+ }
for _, ext := range opts.Extensions {
args = append(args, "-e", ext)
}
diff --git a/cmd/pinchtab/cmd_server_background_test.go b/cmd/pinchtab/cmd_server_background_test.go
index 40ca41f8..47b9270c 100644
--- a/cmd/pinchtab/cmd_server_background_test.go
+++ b/cmd/pinchtab/cmd_server_background_test.go
@@ -6,6 +6,7 @@ import (
"net/http/httptest"
"os"
"reflect"
+ "slices"
"strings"
"testing"
@@ -313,3 +314,24 @@ func TestPortBusyErrorFreePort(t *testing.T) {
t.Errorf("free port should yield nil, got %v", err)
}
}
+
+// The mode built to be diagnosed from a file must not need -v to record anything:
+// the child inherits the default level, and only an explicit level travels.
+func TestBackgroundServerArgsLogLevelForwarding(t *testing.T) {
+ plain := backgroundServerArgs("marker-123", serverBackgroundOptions{})
+ if slices.Contains(plain, "-v") {
+ t.Errorf("a default background run should not force verbose: %#v", plain)
+ }
+ if slices.Contains(plain, "--log-level") {
+ t.Errorf("a default background run should not pin a level: %#v", plain)
+ }
+ if !reflect.DeepEqual(plain, []string{"server", "--background-child", "marker-123"}) {
+ t.Errorf("backgroundServerArgs() = %#v, want just the child marker", plain)
+ }
+
+ explicit := backgroundServerArgs("marker-123", serverBackgroundOptions{LogLevel: "warn"})
+ want := []string{"server", "--background-child", "marker-123", "--log-level", "warn"}
+ if !reflect.DeepEqual(explicit, want) {
+ t.Errorf("backgroundServerArgs() = %#v, want %#v", explicit, want)
+ }
+}
diff --git a/cmd/pinchtab/cmd_server_test.go b/cmd/pinchtab/cmd_server_test.go
index c18b3b7f..e20222cc 100644
--- a/cmd/pinchtab/cmd_server_test.go
+++ b/cmd/pinchtab/cmd_server_test.go
@@ -1,10 +1,12 @@
package main
import (
+ "log/slog"
"reflect"
"testing"
"github.com/pinchtab/pinchtab/internal/config"
+ "github.com/pinchtab/pinchtab/internal/safelog"
)
func TestApplyServerAddressFlagsPrecedence(t *testing.T) {
@@ -75,3 +77,50 @@ func TestBackgroundServerArgsForwardsAddressFlags(t *testing.T) {
t.Fatalf("backgroundServerArgs() = %#v, want %#v", got, want)
}
}
+
+func TestApplyLogLevelResolvesTheRunThreshold(t *testing.T) {
+ t.Cleanup(func() { safelog.SetLevel(safelog.DefaultLevel) })
+
+ for _, tc := range []struct {
+ name string
+ level string
+ verbose bool
+ want slog.Level
+ }{
+ {name: "no flags keeps the default", want: safelog.DefaultLevel},
+ {name: "verbose means debug", verbose: true, want: slog.LevelDebug},
+ {name: "explicit level wins over verbose", level: "error", verbose: true, want: slog.LevelError},
+ {name: "explicit warn", level: "warn", want: slog.LevelWarn},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ safelog.SetLevel(slog.LevelInfo)
+ applyLogLevel(&config.RuntimeConfig{LogLevel: tc.level}, tc.verbose)
+ if got := safelog.CurrentLevel(); got != tc.want {
+ t.Errorf("level = %v, want %v", got, tc.want)
+ }
+ })
+ }
+}
+
+func TestDefaultLogLevelRecordsRequestsAndErrors(t *testing.T) {
+ if safelog.DefaultLevel > slog.LevelInfo {
+ t.Fatalf("DefaultLevel = %v, want info or lower so request lines survive", safelog.DefaultLevel)
+ }
+}
+
+// A quiet startup banner and recorded errors must be reachable together: the
+// banner is a separate field from the level, and neither flag touches the other.
+func TestQuietBannerKeepsDefaultLogging(t *testing.T) {
+ t.Cleanup(func() { safelog.SetLevel(safelog.DefaultLevel) })
+ safelog.SetLevel(slog.LevelError)
+
+ cfg := &config.RuntimeConfig{VerboseBanner: false}
+ applyLogLevel(cfg, false)
+
+ if cfg.VerboseBanner {
+ t.Errorf("applyLogLevel must not touch the banner")
+ }
+ if got := safelog.CurrentLevel(); got != safelog.DefaultLevel {
+ t.Errorf("level = %v, want the default with a quiet banner", got)
+ }
+}
diff --git a/docs/commands.md b/docs/commands.md
index 2831e4c5..4265a1ae 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -4,6 +4,9 @@
```bash
pinchtab server # Start the full server (dashboard + API)
+pinchtab server -b # Start it detached; logs go to <stateDir>/server.log
+pinchtab server -v # Full startup banner, and log at debug level
+pinchtab server --log-level warn # Record warnings and errors only
pinchtab server stop # Stop the running server (foreground or background)
pinchtab server restart # Stop + restart in background (applies config changes)
pinchtab bridge # Start the bridge-only runtime
@@ -17,6 +20,12 @@ pinchtab daemon uninstall # Remove the background service
pinchtab completion <shell> # Generate shell completions
```
+Logging is a level, not an on/off switch. Every run — foreground or `--background`
+— records the per-request access log (with its `requestId`), instance lifecycle
+transitions, warnings and errors. `-v` adds debug detail and the full startup
+banner; `--log-level debug|info|warn|error` sets the threshold explicitly and is
+the only thing that can drop request lines or warnings.
+
## Navigation
```bash
diff --git a/internal/config/config_types.go b/internal/config/config_types.go
index b4f6aeb9..cb1f2ffa 100644
--- a/internal/config/config_types.go
+++ b/internal/config/config_types.go
@@ -13,9 +13,10 @@ type RuntimeConfig struct {
InstancePortEnd int // Ending port for instances (default 9968)
Token string
StateDir string
- TrustProxyHeaders bool // Only trust X-Forwarded-*/Forwarded headers when behind a trusted reverse proxy
- CookieSecure *bool // Nil = auto-detect based on request scheme/host for backward compatibility
- VerboseStartup bool // Show full banner and slog output on server start
+ TrustProxyHeaders bool // Only trust X-Forwarded-*/Forwarded headers when behind a trusted reverse proxy
+ CookieSecure *bool // Nil = auto-detect based on request scheme/host for backward compatibility
+ VerboseBanner bool // Show the full startup banner and security warnings
+ LogLevel string // Minimum log level: debug, info (default), warn or error
BackgroundMarker string
AllowEvaluate bool
diff --git a/internal/safelog/handler.go b/internal/safelog/handler.go
index 7f89bdc2..2f2856b8 100644
--- a/internal/safelog/handler.go
+++ b/internal/safelog/handler.go
@@ -3,6 +3,7 @@ package safelog
import (
"context"
"fmt"
+ "io"
"log/slog"
"os"
"strings"
@@ -12,6 +13,9 @@ import (
"github.com/pinchtab/pinchtab/internal/sanitize"
)
+// DefaultLevel is what a run records with no level set.
+const DefaultLevel = slog.LevelInfo
+
const (
MaxStringValueBytes = 2 * 1024
MaxRecordTextBytes = 8 * 1024
@@ -22,7 +26,10 @@ type Handler struct {
next slog.Handler
}
-var installOnce sync.Once
+var (
+ installOnce sync.Once
+ levelVar = new(slog.LevelVar)
+)
func NewHandler(next slog.Handler) *Handler {
if next == nil {
@@ -31,13 +38,44 @@ func NewHandler(next slog.Handler) *Handler {
return &Handler{next: next}
}
+// InstallDefault is the only owner of the process default logger; nothing else
+// may call slog.SetDefault.
func InstallDefault() {
installOnce.Do(func() {
- base := slog.NewTextHandler(os.Stderr, nil)
- slog.SetDefault(slog.New(NewHandler(base)))
+ slog.SetDefault(slog.New(NewDefaultHandler(os.Stderr)))
})
}
+func NewDefaultHandler(w io.Writer) slog.Handler {
+ return NewHandler(slog.NewTextHandler(w, &slog.HandlerOptions{Level: levelVar}))
+}
+
+// SetLevel adjusts the installed threshold after flags are parsed, which is why
+// the level is a LevelVar and not a second slog.SetDefault.
+func SetLevel(l slog.Level) {
+ levelVar.Set(l)
+}
+
+func CurrentLevel() slog.Level {
+ return levelVar.Level()
+}
+
+func ParseLevel(value string) (slog.Level, error) {
+ switch strings.ToLower(strings.TrimSpace(value)) {
+ case "":
+ return DefaultLevel, nil
+ case "debug":
+ return slog.LevelDebug, nil
+ case "info":
+ return slog.LevelInfo, nil
+ case "warn", "warning":
+ return slog.LevelWarn, nil
+ case "error":
+ return slog.LevelError, nil
+ }
+ return DefaultLevel, fmt.Errorf("unknown log level %q (want debug, info, warn or error)", value)
+}
+
func (h *Handler) Enabled(ctx context.Context, level slog.Level) bool {
return h.next.Enabled(ctx, level)
}
diff --git a/internal/safelog/handler_test.go b/internal/safelog/handler_test.go
index bdc791a5..69703d5a 100644
--- a/internal/safelog/handler_test.go
+++ b/internal/safelog/handler_test.go
@@ -42,3 +42,75 @@ func TestHandlerTruncatesOversizedStrings(t *testing.T) {
t.Fatalf("expected oversized value to be truncated, got %q", out)
}
}
+
+func TestDefaultLevelRecordsRequestsWarningsAndErrors(t *testing.T) {
+ var buf bytes.Buffer
+ logger := slog.New(NewDefaultHandler(&buf))
+ SetLevel(DefaultLevel)
+ t.Cleanup(func() { SetLevel(DefaultLevel) })
+
+ logger.Debug("chatty detail")
+ logger.Info("request", "requestId", "b5fc54c8642370c7", "status", 200)
+ logger.Warn("instance stopped deliberately")
+ logger.Error("TARGET CRASHED")
+
+ out := buf.String()
+ for _, want := range []string{"msg=request", "requestId=b5fc54c8642370c7", "level=WARN", "level=ERROR", "TARGET CRASHED"} {
+ if !strings.Contains(out, want) {
+ t.Errorf("default level dropped %q:\n%s", want, out)
+ }
+ }
+ if strings.Contains(out, "chatty detail") {
+ t.Errorf("default level should not record debug lines:\n%s", out)
+ }
+}
+
+func TestSetLevelAdjustsTheInstalledHandler(t *testing.T) {
+ var buf bytes.Buffer
+ logger := slog.New(NewDefaultHandler(&buf))
+ t.Cleanup(func() { SetLevel(DefaultLevel) })
+
+ SetLevel(slog.LevelError)
+ logger.Info("request", "requestId", "abc")
+ logger.Error("still recorded")
+ if strings.Contains(buf.String(), "msg=request") {
+ t.Errorf("an explicit error level should drop request lines:\n%s", buf.String())
+ }
+ if !strings.Contains(buf.String(), "still recorded") {
+ t.Errorf("errors must survive every level:\n%s", buf.String())
+ }
+
+ buf.Reset()
+ SetLevel(slog.LevelDebug)
+ logger.Debug("chatty detail")
+ if !strings.Contains(buf.String(), "chatty detail") {
+ t.Errorf("debug level should record debug lines:\n%s", buf.String())
+ }
+ if got := CurrentLevel(); got != slog.LevelDebug {
+ t.Errorf("CurrentLevel() = %v, want debug", got)
+ }
+}
+
+func TestParseLevel(t *testing.T) {
+ for _, tc := range []struct {
+ in string
+ want slog.Level
+ wantErr bool
+ }{
+ {in: "", want: DefaultLevel},
+ {in: "debug", want: slog.LevelDebug},
+ {in: "INFO", want: slog.LevelInfo},
+ {in: " warn ", want: slog.LevelWarn},
+ {in: "warning", want: slog.LevelWarn},
+ {in: "error", want: slog.LevelError},
+ {in: "silent", want: DefaultLevel, wantErr: true},
+ } {
+ got, err := ParseLevel(tc.in)
+ if (err != nil) != tc.wantErr {
+ t.Errorf("ParseLevel(%q) error = %v, wantErr %v", tc.in, err, tc.wantErr)
+ }
+ if got != tc.want {
+ t.Errorf("ParseLevel(%q) = %v, want %v", tc.in, got, tc.want)
+ }
+ }
+}
diff --git a/internal/server/fatal_test.go b/internal/server/fatal_test.go
index 3180f6c8..6b9c4a13 100644
--- a/internal/server/fatal_test.go
+++ b/internal/server/fatal_test.go
@@ -21,7 +21,7 @@ func runFatal(t *testing.T, fn func()) fatalRun {
t.Helper()
origLogger := slog.Default()
- slog.SetDefault(slog.New(slog.NewTextHandler(io.Discard, nil)))
+ slog.SetDefault(slog.New(slog.NewTextHandler(new(bytes.Buffer), nil)))
origExit := exitProcess
var codes []int
exitProcess = func(code int) { codes = append(codes, code) }
diff --git a/internal/server/server.go b/internal/server/server.go
index 4ff2d794..38a974b3 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -4,7 +4,6 @@ import (
"context"
"errors"
"fmt"
- "io"
"log/slog"
"net"
"net/http"
@@ -39,9 +38,7 @@ import (
var exitProcess = os.Exit
-// fatalStartup reports a startup failure on stderr and exits. Startup failures
-// must not travel through slog: the non-verbose default replaces the logger
-// with a discard handler, which would leave the process exiting in silence.
+// fatalStartup writes styled operator output with hints, not a log record.
func fatalStartup(stage string, err error) {
fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, fmt.Sprintf("pinchtab: %s: %v", stage, err)))
for _, hint := range startupFatalHints(err) {
@@ -61,10 +58,6 @@ func startupFatalHints(err error) []string {
}
func RunDashboard(cfg *config.RuntimeConfig, version string) {
- if !cfg.VerboseStartup {
- slog.SetDefault(slog.New(slog.NewTextHandler(io.Discard, nil)))
- }
-
providerhooks.CleanupProfile(config.NormalizeBrowser(cfg.DefaultBrowser), cfg.ProfileDir)
dashPort := cfg.Port
@@ -254,7 +247,7 @@ func RunDashboard(cfg *config.RuntimeConfig, version string) {
listenStatus = "running"
}
- if cfg.VerboseStartup {
+ if cfg.VerboseBanner {
cli.PrintStartupBanner(cfg, cli.StartupBannerOptions{
Mode: "server",
ListenAddr: cfg.Bind + ":" + dashPort,
@@ -327,7 +320,7 @@ func RunDashboard(cfg *config.RuntimeConfig, version string) {
),
),
)
- if cfg.VerboseStartup {
+ if cfg.VerboseBanner {
cli.LogSecurityWarnings(cfg)
}
diff --git a/internal/server/server_test.go b/internal/server/server_test.go
new file mode 100644
index 00000000..a302b35e
--- /dev/null
+++ b/internal/server/server_test.go
@@ -0,0 +1,123 @@
+package server
+
+import (
+ "bytes"
+ "io/fs"
+ "log/slog"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "reflect"
+ "strings"
+ "testing"
+
+ "github.com/pinchtab/pinchtab/internal/handlers"
+ "github.com/pinchtab/pinchtab/internal/safelog"
+)
+
+// installCapturedDefault captures the process logger through the very handler
+// InstallDefault builds, so these tests observe what a real run records.
+func installCapturedDefault(t *testing.T) *bytes.Buffer {
+ t.Helper()
+ var buf bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(safelog.NewDefaultHandler(&buf)))
+ safelog.SetLevel(safelog.DefaultLevel)
+ t.Cleanup(func() {
+ slog.SetDefault(previous)
+ safelog.SetLevel(safelog.DefaultLevel)
+ })
+ return &buf
+}
+
+func TestDefaultRunRecordsTheRequestLine(t *testing.T) {
+ buf := installCapturedDefault(t)
+
+ handler := handlers.LoggingMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("X-Request-Id", "b5fc54c8642370c7")
+ w.WriteHeader(http.StatusNotFound)
+ }))
+ handler.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/click", nil))
+
+ out := buf.String()
+ for _, want := range []string{"msg=request", "requestId=b5fc54c8642370c7", "method=POST", "path=/click", "status=404"} {
+ if !strings.Contains(out, want) {
+ t.Errorf("a default run dropped %q from the access log:\n%s", want, out)
+ }
+ }
+}
+
+func TestDefaultRunRecordsErrorsAndWarnings(t *testing.T) {
+ buf := installCapturedDefault(t)
+
+ slog.Warn("always-on: instance stopped deliberately", "id", "inst_ccb22b39")
+ slog.Error("🔥 TARGET CRASHED", "target", "page")
+
+ out := buf.String()
+ if !strings.Contains(out, "instance stopped deliberately") {
+ t.Errorf("a default run dropped a warning:\n%s", out)
+ }
+ if !strings.Contains(out, "TARGET CRASHED") {
+ t.Errorf("a default run dropped an error:\n%s", out)
+ }
+}
+
+// RunDashboard starts a server, so no unit test calls it; the second-owner
+// regression is only reachable as a structural guard.
+func TestOnlySafelogInstallsTheProcessLogger(t *testing.T) {
+ root, err := filepath.Abs("../..")
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ installers := []string{}
+ scanned := 0
+ walkErr := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if d.IsDir() || !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+ return nil
+ }
+ raw, err := os.ReadFile(path)
+ if err != nil {
+ return err
+ }
+ scanned++
+ rel := filepath.ToSlash(mustRel(t, root, path))
+ for _, line := range strings.Split(string(raw), "\n") {
+ trimmed := strings.TrimSpace(line)
+ if strings.HasPrefix(trimmed, "//") {
+ continue
+ }
+ if strings.Contains(trimmed, "slog.SetDefault(") {
+ installers = append(installers, rel)
+ }
+ }
+ if strings.HasPrefix(rel, "internal/server/") && strings.Contains(string(raw), "io."+"Discard") {
+ t.Errorf("%s discards log output; a run must record its requests and errors without a flag", rel)
+ }
+ return nil
+ })
+ if walkErr != nil {
+ t.Fatal(walkErr)
+ }
+ if scanned == 0 {
+ t.Fatal("no Go file scanned — this guard is checking nothing")
+ }
+
+ want := []string{"internal/safelog/handler.go"}
+ if !reflect.DeepEqual(installers, want) {
+ t.Errorf("slog.SetDefault callers = %v, want only %v; two writers to the process default logger is what silenced the server", installers, want)
+ }
+}
+
+func mustRel(t *testing.T, root, path string) string {
+ t.Helper()
+ rel, err := filepath.Rel(root, path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ return rel
+}