High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix(session): split the disabled hint so only the boot-disabled state prescribes a restart (PIN-287)
Luigi Agosti700ee71fd3a6
diff --git a/docs/endpoints.md b/docs/endpoints.mdindex 7d9eaba1..1bb60fa9 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -894,7 +894,9 @@ Scheduler routes are only present when `scheduler.enabled` is true.Create returns `sessionToken` — the plaintext token shown only once.-Agent session routes are only present in full server mode with `sessions.agent.enabled` true. The family always answers, so the state is readable from the error code rather than from a bare 404: a bridge returns `sessions_unavailable_bridge_mode`, whose remedy is to run `pinchtab server`, and a full server with the setting off returns `sessions_disabled`, whose remedy is the config change. No config value mounts the family in bridge mode.+Agent session routes are only present in full server mode with `sessions.agent.enabled` true. The family always answers, so the state is readable from the error code rather than from a bare 404: a bridge returns `sessions_unavailable_bridge_mode`, whose remedy is to run `pinchtab server`, and a full server with the setting off returns `sessions_disabled`. No config value mounts the family in bridge mode.++`sessions_disabled` covers two states, and its `details.hint` says which one. A server that BOOTED with the setting off never mounted the family, so enabling it needs `pinchtab config set sessions.agent.enabled true` and a restart, and the refusal carries no `details.remedy` because that is not one command. A server that booted with it on and was switched off by a config save already mounted the family: `pinchtab config set sessions.agent.enabled true` applies live, needs no restart, and is carried as the refusal's `details.remedy`.Session-authenticated callers cannot reach dashboard/admin endpoint families such as config, dashboard agent listings, dashboard event streams, session management, profile management, instance management, or cache controls. They are intended for trusted automation in controlled environments, not for untrusted multi-tenant isolation.diff --git a/internal/dashboard/agent_session_api.go b/internal/dashboard/agent_session_api.goindex 6219ea00..9cd45563 100644--- a/internal/dashboard/agent_session_api.go+++ b/internal/dashboard/agent_session_api.go@@ -55,13 +55,14 @@ func (a *SessionAPI) registerPatterns(mux *http.ServeMux, patterns []string) {}// whileEnabled re-reads the store on every request, so a save that switches agent-// sessions off is refused by routes a boot with them on already mounted. The-// answer is the one the never-mounted state gives, from the same vocabulary.+// sessions off is refused by routes a boot with them on already mounted. The code+// and message are the never-mounted state's; the guidance is not, because this+// state is the one a config set alone reverses.func (a *SessionAPI) whileEnabled(next http.HandlerFunc) http.HandlerFunc {return func(w http.ResponseWriter, r *http.Request) {if a.store == nil || !a.store.Enabled() {httpx.ErrorCode(w, http.StatusNotFound, session.CodeDisabled, session.MsgDisabled, false,- remedy.Details(session.HintDisabled, remedy.None))+ remedy.Details(session.HintDisabledBySave, session.RemedyEnable()))return}next(w, r)diff --git a/internal/server/agent_session_live_config_test.go b/internal/server/agent_session_live_config_test.goindex 6e4964a6..4ed01db8 100644--- a/internal/server/agent_session_live_config_test.go+++ b/internal/server/agent_session_live_config_test.go@@ -162,3 +162,47 @@ func TestASaveKeepsTheAgentSessionStoreWritingToItsOriginalPath(t *testing.T) {t.Errorf("the store started writing under the edited stateDir %s, splitting live sessions across two files", moved)}}++// Both states answer sessions_disabled and both are genuinely disabled, so the code+// and the message are shared. The GUIDANCE cannot be: only the boot-disabled state+// owes a restart. A shared hint is this card's own defect one direction over — the+// machine-readable restartReasons says nothing is owed while the human-readable+// remedy in the same response family says to restart.+func TestTheTwoDisabledStatesDoNotShareGuidance(t *testing.T) {+ booted := newFrontDoor(t, func(fc *config.FileConfig) { agentSessionsEnabled(fc, false) })+ bootCode, _, bootHint, bootRemedy := decodeSessionRefusal(t, booted.createSessionOverHTTP(t))++ saved := newFrontDoor(t, nil)+ saved.save(t, func(fc *config.FileConfig) { agentSessionsEnabled(fc, false) })+ saveCode, _, saveHint, saveRemedy := decodeSessionRefusal(t, saved.createSessionOverHTTP(t))++ if bootCode != CodeSessionsDisabled || saveCode != CodeSessionsDisabled {+ t.Fatalf("codes = %q and %q, want both %q; the code is the state and both states are disabled",+ bootCode, saveCode, CodeSessionsDisabled)+ }+ if bootHint == saveHint {+ t.Fatalf("both disabled states answer the same hint %q; one of them is told to restart a server that re-enables live", bootHint)+ }+ if !strings.Contains(bootHint, "restart the server") {+ t.Errorf("the boot-disabled hint = %q, want it to say a restart is owed — the family was never mounted", bootHint)+ }+ if !strings.Contains(saveHint, "without a restart") {+ t.Errorf("the save-disabled hint = %q, want it to say no restart is owed", saveHint)+ }+ if bootRemedy != "" {+ t.Errorf("the boot-disabled remedy = %q, want none: a config edit plus a restart is not one command", bootRemedy)+ }+ if saveRemedy == "" {+ t.Error("the save-disabled state carries no remedy, though one command reverses it")+ }++ // The save-disabled hint's claim, checked rather than merely worded.+ reasons := saved.saveReportingReasons(t, func(fc *config.FileConfig) { agentSessionsEnabled(fc, true) })+ if len(reasons) != 0 {+ t.Fatalf("re-enabling after a save reported %v; the hint promises no restart is owed", reasons)+ }+ if create := saved.createSessionOverHTTP(t); create.Code != http.StatusCreated {+ t.Fatalf("POST /sessions answered %d (%s) after re-enabling; the hint promises it applies immediately",+ create.Code, create.Body.String())+ }+}diff --git a/internal/server/sessions_unavailable.go b/internal/server/sessions_unavailable.goindex 9df439ce..ae4aade4 100644--- a/internal/server/sessions_unavailable.go+++ b/internal/server/sessions_unavailable.go@@ -27,7 +27,7 @@ const (hintSessionsUnavailableInBridge = "no config value mounts the session family on a bridge; the full server is what serves it."msgSessionsDisabled = session.MsgDisabled- hintSessionsDisabled = session.HintDisabled+ hintSessionsDisabled = session.HintDisabledAtBoot)// Running the full server is the bridge's whole remedy. The verb it used to lead with —diff --git a/internal/session/routes.go b/internal/session/routes.goindex 6a507d7e..ea0f5086 100644--- a/internal/session/routes.go+++ b/internal/session/routes.go@@ -1,6 +1,10 @@package session-import "slices"+import (+ "slices"++ "github.com/pinchtab/pinchtab/internal/remedy"+)// routePatterns is the ONE definition of the agent-session family's mux patterns. Three// call sites range over it: the live registration in the dashboard package, and the two@@ -26,8 +30,24 @@ func RoutePatterns() []string {// registrars answer for it: the server package when the store booted disabled and// never mounted the family, and the dashboard's SessionAPI when a save switched// it off in a process that did mount it.+//+// The code and the message are shared because both states genuinely are disabled.+// The HINT is not, and must not be: whether a restart is owed is exactly what+// separates them. A boot-disabled process never mounted the family, so enabling it+// cannot reach the running process; a process disabled by a save already mounted+// the family, so switching it back on applies immediately. One hint serving both+// tells an operator to restart a server that does not need it.const (CodeDisabled = "sessions_disabled"MsgDisabled = "agent sessions are not enabled on this server"- HintDisabled = "set sessions.agent.enabled = true and restart the server; the route family is mounted at startup, so enabling it cannot take effect in the running process."++ HintDisabledAtBoot = "set sessions.agent.enabled = true and restart the server; the route family is mounted at startup, so enabling it cannot take effect in the running process."+ HintDisabledBySave = "agent sessions were switched off by a config save; set sessions.agent.enabled = true to switch them back on — this server already mounted the route family, so it applies without a restart.")++// enableAgentSessions is the remedy the save-disabled state has and the boot-disabled+// state does not: one command, applying live, with no restart to pair it with.+var enableAgentSessions = remedy.Declare("pinchtab config set sessions.agent.enabled true")++// RemedyEnable is the save-disabled state's remedy line.+func RemedyEnable() remedy.Remedy { return enableAgentSessions.Remedy() }