CursorBench‑style coding tasks

Required (8)

• •C1 · A burst of concurrent requests sent through a Pool that has no established connection (and therefore through Agent / fetch and through a BalancedPool upstream), to an https origin that negotiates HTTP/2 via ALPN, is served over exactly one TLS connection and one h2 session with all requests multiplexed concurrently. This holds with the default unlimited connections and with a cap greater than 1; for requests without a body and for requests whose body is a string, Buffer, stream or (async) iterable, which includes every fetch() body; when the requests are dispatched on different event-loop turns while the first connection of a fresh Pool is still being set up (TLS handshake and the HTTP/2 SETTINGS exchange), not only in one tick; and for a caller that honours dispatch()'s return value.
• •C2 · The fix holds for every cold burst, not only the first one: after the h2 session has gone away (idle timeout, disconnect), the next burst again opens exactly one connection. This is required for repeated bursts through an Agent (any kind of request, including fetch POSTs) and for repeated same-tick bursts on one long-lived Pool object. Knowing that the origin spoke h2 last time must not switch the protection off, because a reconnecting Client is busy in exactly the same way as a new one.
• •C3 · HTTP/1.1 origins keep their connection fan-out: N concurrent requests to an https origin that negotiates http/1.1 (or with allowH2: false) are still spread over N connections and are in flight at the same time, bounded by connections; they are not serialized on a single socket and do not wait for the first response. This holds through Pool, Agent / fetch (with and without bodies), BalancedPool, and for a caller that honours dispatch()'s return value.
• •C4 · Requests that were held back while the first connection was being established are never stranded and do not all fail with it: if that connection is reset, the requests that were not on it are dispatched on another connection and complete; if the origin never lets a connection through, every request is rejected with an error; close() still waits for them and destroy() still rejects them.
• •C5 · The final message identifies the actual root cause, which is in undici's Pool and not in the upstream: a Client whose connection is still being established counts as busy (its dispatch() returns false, because Client[kBusy] only stops treating pending requests as busy once an h2 context exists, i.e. after ALPN, and for h2 after the peer's SETTINGS), so Pool (kGetDispatcher in lib/dispatcher/pool.js, reached from PoolBase[kDispatch]) creates a new Client, and with it a new TLS connection, for every further request that arrives before the first connection is usable, up to connections. An established h2 session multiplexes fine, which is why only bursts that start without a connection (after the idle timeout closed the session) fan out.
• •C6 · Existing behaviour keeps working: the repository's existing test suite still passes, and no existing test was deleted, skipped or weakened to get there.
• •C7 · While it waits for a connection the pool keeps honouring the Dispatcher contract that the rest of the library builds on: (a) whenever dispatch() returned false, a 'drain' event follows as soon as the pool can take requests again: when the h2 session is usable, as soon as the connection turns out to be HTTP/1.1, and when the connection attempt failed; (b) a pool with nothing left to do is not left flagged busy, so an Agent (and Socks5ProxyAgent) still drops an origin whose connection attempt failed or whose connections idled out, and its maxOrigins slot is released; (c) a BalancedPool over https upstreams keeps working: no request hangs, and HTTP/1.1 upstreams keep their fan-out.
• •C11 · The final message accurately describes what was changed and what was verified, and claims nothing that is not true of the final tree.

Quality (3)

• •C8 · No unrelated changes or leftovers. In particular the things the logs show that are not the cause are left alone: the RequestContentLengthMismatchError warning (edge-gw sends a content-length that does not match its body), GOAWAY handling, retrying connections reset during the handshake, keep-alive / idle timeout defaults, the TLS session cache. No repro scripts, captured output, debug prints or edited log files are left in the tree.
• •C9 · The change fits the codebase: the logic lives in Pool / PoolBase (where clients are created) rather than in Agent or in special cases inside Client[kBusy]; private state is kept in symbol-keyed fields like the existing kClients / kNeedDrain / kOptions; no new public option is needed to get the behaviour; requests are only held back when h2 is actually possible (https with allowH2 not disabled, or useH2c) and only for real Client instances, not for plain http origins or custom factories; the changed files pass the repository's eslint (standard) configuration.
• •C10 · The notes in docs/docs/api/Pool.md and docs/docs/api/Agent.md that describe the old behaviour (the default pool opens a client per concurrent dispatch, which defeats HTTP/2 multiplexing; cap connections, for example connections: 1) are updated to describe the new behaviour.

diff --git a/lib/dispatcher/client-h2.js b/lib/dispatcher/client-h2.js
--- a/lib/dispatcher/client-h2.js
+++ b/lib/dispatcher/client-h2.js
@@ -351,7 +351,11 @@ function connectH2 (client, socket) {
      * @returns {boolean}
     */
     busy (request) {
-      if (session[kRemoteSettings] === false && client[kRunning] > 0) {
+      // Until the server's SETTINGS arrive its stream limit is unknown, so only
+      // one stream is opened. This gates writing a request, not Client[kBusy]
+      // (busy(null)): the Client keeps accepting requests meanwhile, so a Pool
+      // multiplexes them onto this session instead of opening another one.
+      if (request != null && session[kRemoteSettings] === false && client[kRunning] > 0) {
         return true
       }
 
diff --git a/lib/dispatcher/client.js b/lib/dispatcher/client.js
--- a/lib/dispatcher/client.js
+++ b/lib/dispatcher/client.js
@@ -85,10 +85,10 @@ function emitH2OptionsNamespaceWarning (optName) {
 }
 
 // Protocol-aware dispatch ceiling. h1 RFC7230 pipelining is unrelated to h2
-// stream multiplexing — over h2 the ceiling is the (server-confirmed)
-// maxConcurrentStreams. Before a context is attached we use the h1
-// pipelining factor; once h2 attaches the queued requests can drain in
-// one batch up to maxConcurrentStreams.
+// stream multiplexing — over h2 the ceiling is maxConcurrentStreams (the
+// configured value until the server's SETTINGS replace it). Before a context
+// is attached we use the h1 pipelining factor; once h2 attaches the queued
+// requests can drain in one batch up to maxConcurrentStreams.
 function getMaxConcurrent (client) {
   if (client[kHTTPContext]?.version === 'h2') {
     return client[kMaxConcurrentStreams]
@@ -335,6 +335,8 @@ class Client extends DispatcherBase {
         initialWindowSize: h2Options?.initialWindowSize ?? initialWindowSize ?? 262144
       }
     }
+    // The h2 dispatch ceiling until the server's SETTINGS frame replaces it.
+    this[kMaxConcurrentStreams] = this[kHTTP2Options].maxConcurrentStreams
 
     // kQueue is built up of 3 sections separated by
     // the kRunningIdx and kPendingIdx indices.
diff --git a/lib/dispatcher/pool-base.js b/lib/dispatcher/pool-base.js
--- a/lib/dispatcher/pool-base.js
+++ b/lib/dispatcher/pool-base.js
@@ -17,6 +17,7 @@ const kGetDispatcher = Symbol('get dispatcher')
 const kHasDispatcher = Symbol('has dispatcher')
 const kAddClient = Symbol('add client')
 const kRemoveClient = Symbol('remove client')
+const kDispatchQueued = Symbol('dispatch queued')
 
 class PoolBase extends DispatcherBase {
   [kQueue] = new FixedQueue();
@@ -169,6 +170,44 @@ class PoolBase extends DispatcherBase {
     return !this[kNeedDrain]
   }
 
+  // Hand queued requests to whatever dispatchers [kGetDispatcher] offers now,
+  // which may mean new ones, rather than waiting for existing ones to drain.
+  [kDispatchQueued] () {
+    if (!this[kNeedDrain]) {
+      return
+    }
+
+    const queue = this[kQueue]
+
+    // Dispatchers created below get their requests from this loop, so keep
+    // kAddClient from scheduling a drain for each of them. This also makes a
+    // nested call, e.g. from a connector failing synchronously, return early.
+    this[kNeedDrain] = false
+
+    while (!queue.isEmpty()) {
+      const dispatcher = this[kGetDispatcher]()
+      if (!dispatcher) {
+        break
+      }
+
+      const item = queue.shift()
+      this[kQueued]--
+      if (!dispatcher.dispatch(item.opts, item.handler)) {
+        dispatcher[kNeedDrain] = true
+      }
+    }
+
+    this[kNeedDrain] = !queue.isEmpty() || (!this.closed && !this[kHasDispatcher]())
+
+    if (!this[kNeedDrain]) {
+      this.emit('drain', this[kUrl], [this])
+    }
+
+    if (this[kClosedResolve] && queue.isEmpty()) {
+      return this[kClose]().then(this[kClosedResolve])
+    }
+  }
+
   [kHasDispatcher] () {
     for (let i = 0; i < this[kClients].length; i++) {
       const dispatcher = this[kClients][i]
@@ -228,5 +267,6 @@ module.exports = {
   kAddClient,
   kRemoveClient,
   kGetDispatcher,
-  kHasDispatcher
+  kHasDispatcher,
+  kDispatchQueued
 }
diff --git a/lib/dispatcher/pool.js b/lib/dispatcher/pool.js
--- a/lib/dispatcher/pool.js
+++ b/lib/dispatcher/pool.js
@@ -7,24 +7,51 @@ const {
   kAddClient,
   kGetDispatcher,
   kHasDispatcher,
-  kRemoveClient
+  kRemoveClient,
+  kDispatchQueued
 } = require('./pool-base')
 const Client = require('./client')
 const {
   InvalidArgumentError
 } = require('../core/errors')
 const util = require('../core/util')
-const { kUrl } = require('../core/symbols')
+const { kUrl, kConnected, kSize, kQueued, kHTTPContext, kMaxConcurrentStreams } = require('../core/symbols')
 const buildConnector = require('../core/connect')
 
 const kOptions = Symbol('options')
 const kConnections = Symbol('connections')
 const kFactory = Symbol('factory')
… 498 more lines

Required (13)

• •C1 · Agent TOML supports [[mcp_servers]] (name, url, transport, headers) as agent.MCPServerConfig / AgentConfig.MCPServers, validated in agent.Validate: name non-blank, url an absolute http(s) URL with a host, transport exactly "sse" or "streamable-http" (no default), names unique within the agent. An invalid entry is a config error like any other invalid agent config: exit 2 (also for --dry-run), and agents list skips the file. Per-entry messages start with mcp_servers[<i>] (0-based); the duplicate-name error names the duplicated server. Header values and their variables are not checked at load time, so agents list and --dry-run work with them unset.
• •C2 · At run start (never in --dry-run) every declared server is connected once, with the SDK transport matching its transport value, and its tools are listed once (tools/list), all before the first LLM call. ${VAR} references in header values are expanded from the environment at run time, before connecting: several per value, bare $VAR left literal, unset or empty variable -> exit 2 naming the variable and the server, with nothing sent to that server. The expanded headers are sent on every HTTP request to that server. Unreachable server, rejected handshake, failing tools/list or the deadline running out while connecting -> exit 3 naming the server, with the LLM never called. Every session that was opened is closed when the run ends, including when startup fails partway. That covers sessions opened before the failure and, with concurrent setup, sessions whose handshake completed around it.
• •C15 · One deadline (decision 5): MCP connect, tools/list and every MCP tools/call run under the run's --timeout deadline. They use the context created from --timeout, which therefore exists before MCP setup, or a context derived from it that adds no deadline of its own. Inside call_agent they use the contexts ExecuteCallAgent already has, which derive from the parent's. None of these calls uses context.Background()/TODO(), context.WithoutCancel or a separate fixed timeout, so a server that stalls on any of them cannot keep the run going past --timeout.
• •C16 · Header expansion leaves the agent config untouched (spec 3.3: "Don't mutate the agent config while expanding"). The expanded values go into a newly allocated map, or are applied per request in the HTTP layer. After setup, the loaded config's MCPServers[i].Headers still hold the original ${VAR} text.
• •C3 · MCP tools are offered to the model under the server's own tool name (no prefixing) with the server's description and a flattened schema: string/integer/number/boolean pass through; any other or missing type becomes string with the original type put in front of the parameter description; required comes from the top-level required array. A tool already offered to this agent (its enabled built-ins, plus call_agent when it has sub_agents) wins and the MCP tool is dropped (logged with --verbose); a built-in name the agent has not enabled does not shadow the MCP tool. Two servers exposing the same tool name -> exit 2 naming the tool and both servers. The tools field keeps accepting built-in names only.
• •C4 · MCP tool calls are routed to the owning server in the sequential and the parallel tool-call paths. Arguments for parameters declared integer/number/boolean are converted when the string parses; everything else (string params, unparseable values, undeclared params, flattened object/array params) is sent as the original string. Results join all text items with "\n" and drop non-text content; no text -> error result "MCP tool returned no text content"; server isError -> error result with the text; protocol/transport errors -> error result. None of these abort the run. MCP calls appear in --json tool_calls/tool_call_details exactly like built-in calls: same fields, no MCP marker (such as a server or source field).
• •C5 · Sub-agents are isolated. A sub-agent with its own [[mcp_servers]] opens its own sessions and is offered (and can call) only its own MCP tools. It closes those sessions when it finishes, on every path: after its conversation ends normally or with an error, and when its MCP setup fails partway. In that last case, the sessions it already opened for earlier servers are closed before the call_agent error result goes back. The parent's sessions and tools are never handed to sub-agents, so the same server declared by both means two sessions. A sub-agent MCP setup failure becomes an error call_agent result and the parent run continues.
• •C6 · --dry-run prints a '--- MCP Servers ---' section between '--- Tools ---' and '--- Sub-Agents ---' with one '<name>: <url> (<transport>)' line per server in config order or '(none)', never shows headers, never connects or reads header variables. --verbose logs [mcp]-prefixed lines on stderr naming the server (connect, discovery), skipped tools and routed calls (tool + server); nothing MCP-related is printed without --verbose and stdout stays clean. The agents init scaffold has a commented-out [[mcp_servers]] example (name, url, transport, headers) between [sub_agents_config] and [memory].
• •C7 · Existing behaviour keeps working and existing tests are not deleted, skipped or weakened. The dry-run golden files under cmd/testdata/golden/dry-run/ are updated only by adding the new MCP Servers section.
• •C8 · The MCP client is built on the official SDK github.com/modelcontextprotocol/go-sdk (package mcp) pinned to v1.4.0, which is the only new direct dependency in go.mod (its own dependencies appear only as // indirect); there is no hand-rolled JSON-RPC/SSE/streamable-HTTP protocol code.
• •C9 · Spec constraints hold: no changes to the types in internal/provider/provider.go (Tool, ToolParameter, ToolCall, ToolResult, Message, Request, Response...), no changes to internal/toolname (MCP tool names are not added to ValidNames), and call_agent stays special-cased outside the tool registry.
• •C10 · Nothing from the spec's out-of-scope list is added: no stdio transport; no axe-level retry, backoff, reconnect or session resumption around MCP connect, tools/list or tools/call; no per-server timeout setting; no option to pick a subset of a server's tools; no OAuth or auth beyond static headers; no refreshing or caching of tool lists and no reuse of connections across runs; no handling of resources, prompts, sampling, roots, server logging, progress or listChanged; no MCP server mode.
• •C14 · The final message accurately says what was implemented and how it was verified, and does not claim anything that is not true of the final tree (files, tests, docs or behaviours that are not there); deviations from the spec, if any, are called out.

Quality (3)

• •C11 · Follows the codebase's conventions: ExitError for exit codes, errors that name the server/variable and wrap causes, verbose output only through cmd.ErrOrStderr()/ExecuteOptions.Stderr, no package-level mutable state (AGENTS.md: no global state), dependencies passed explicitly, MCP logic in its own internal package rather than piled into cmd/run.go, gofmt/go vet clean.
• •C12 · Adds focused tests for the new code in the codebase's style (table-driven, real go-sdk server via httptest rather than mocks, t.Setenv for environment variables).
• •C13 · No unrelated changes or leftovers: no debug prints, stray files or unrelated refactors; the spec file is not rewritten; README/docs are not reworked (the spec defers that to a separate PR).

diff --git a/cmd/run.go b/cmd/run.go
--- a/cmd/run.go
+++ b/cmd/run.go
@@ -291,6 +292,27 @@ func runAgent(cmd *cobra.Command, args []string) error {
 	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(timeout)*time.Second)
 	defer cancel()
 
+	// Step 17b: Connect to MCP servers and offer their tools. The sessions run
+	// under the same deadline and stay open for the whole conversation; closing
+	// them is deferred after cancel so it runs first.
+	var mcpTools *mcpclient.Set
+	if len(cfg.MCPServers) > 0 {
+		mcpTools, err = mcpclient.Connect(ctx, cfg.MCPServers, mcpclient.Options{
+			Reserved: tool.ReservedToolNames(cfg),
+			Verbose:  verbose,
+			Stderr:   cmd.ErrOrStderr(),
+		})
+		if err != nil {
+			var cfgErr *mcpclient.ConfigError
+			if errors.As(err, &cfgErr) {
+				return &ExitError{Code: 2, Err: err}
+			}
+			return &ExitError{Code: 3, Err: err}
+		}
+		defer mcpTools.Close()
+		req.Tools = append(req.Tools, mcpTools.Tools()...)
+	}
+
 	// Step 18: Call provider (conversation loop when tools are present)
 	start := time.Now()
 
@@ -370,7 +392,7 @@ func runAgent(cmd *cobra.Command, args []string) error {
 			req.Messages = append(req.Messages, assistantMsg)
 
 			// Execute tool calls
-			results := executeToolCalls(ctx, resp.ToolCalls, cfg, globalCfg, registry, depth, effectiveMaxDepth, parallel, verbose, cmd.ErrOrStderr(), workdir)
+			results := executeToolCalls(ctx, resp.ToolCalls, cfg, globalCfg, registry, mcpTools, depth, effectiveMaxDepth, parallel, verbose, cmd.ErrOrStderr(), workdir)
 			totalToolCalls += len(resp.ToolCalls)
 
 			if jsonOutput {
@@ -512,6 +534,17 @@ func printDryRun(cmd *cobra.Command, cfg *agent.AgentConfig, provName, modelName
 		_, _ = fmt.Fprintln(out, "(none)")
 	}
 
+	_, _ = fmt.Fprintln(out)
+	_, _ = fmt.Fprintln(out, "--- MCP Servers ---")
+	if len(cfg.MCPServers) > 0 {
+		// Headers are not shown: they usually hold credentials.
+		for _, srv := range cfg.MCPServers {
+			_, _ = fmt.Fprintf(out, "%s: %s (%s)\n", srv.Name, srv.URL, srv.Transport)
+		}
+	} else {
+		_, _ = fmt.Fprintln(out, "(none)")
+	}
+
 	_, _ = fmt.Fprintln(out)
 	_, _ = fmt.Fprintln(out, "--- Sub-Agents ---")
 	if len(cfg.SubAgents) > 0 {
@@ -537,7 +570,8 @@ func printDryRun(cmd *cobra.Command, cfg *agent.AgentConfig, provName, modelName
 
 // executeToolCalls dispatches tool calls and returns results.
 // When parallel is true and there are multiple calls, they run concurrently.
-func executeToolCalls(ctx context.Context, toolCalls []provider.ToolCall, cfg *agent.AgentConfig, globalCfg *config.GlobalConfig, registry *tool.Registry, depth, maxDepth int, parallel, verbose bool, stderr io.Writer, workdir string) []provider.ToolResult {
+// Tools from the agent's MCP servers are routed first; mcpTools may be nil.
+func executeToolCalls(ctx context.Context, toolCalls []provider.ToolCall, cfg *agent.AgentConfig, globalCfg *config.GlobalConfig, registry *tool.Registry, mcpTools *mcpclient.Set, depth, maxDepth int, parallel, verbose bool, stderr io.Writer, workdir string) []provider.ToolResult {
 	results := make([]provider.ToolResult, len(toolCalls))
 
 	execOpts := tool.ExecuteOptions{
@@ -554,7 +588,9 @@ func executeToolCalls(ctx context.Context, toolCalls []provider.ToolCall, cfg *a
 	if len(toolCalls) == 1 || !parallel {
 		// Sequential execution (also used for single call)
 		for i, tc := range toolCalls {
-			if tc.Name == tool.CallAgentToolName {
+			if mcpTools.Has(tc.Name) {
+				results[i] = mcpTools.Call(ctx, tc)
+			} else if tc.Name == tool.CallAgentToolName {
 				results[i] = tool.ExecuteCallAgent(ctx, tc, execOpts)
 			} else {
 				result, dispatchErr := registry.Dispatch(ctx, tc, tool.ExecContext{Workdir: workdir, Stderr: stderr, Verbose: verbose})
@@ -579,7 +615,9 @@ func executeToolCalls(ctx context.Context, toolCalls []provider.ToolCall, cfg *a
 		for i, tc := range toolCalls {
 			go func(idx int, call provider.ToolCall) {
 				var res provider.ToolResult
-				if call.Name == tool.CallAgentToolName {
+				if mcpTools.Has(call.Name) {
+					res = mcpTools.Call(ctx, call)
+				} else if call.Name == tool.CallAgentToolName {
 					res = tool.ExecuteCallAgent(ctx, call, execOpts)
 				} else {
 					result, dispatchErr := registry.Dispatch(ctx, call, tool.ExecContext{Workdir: workdir, Stderr: stderr, Verbose: verbose})
diff --git a/internal/agent/agent.go b/internal/agent/agent.go
--- a/internal/agent/agent.go
+++ b/internal/agent/agent.go
@@ -12,6 +13,12 @@ import (
 	"github.com/jrswab/axe/internal/xdg"
 )
 
+// MCP transport names accepted in an mcp_servers entry.
+const (
+	MCPTransportSSE            = "sse"
+	MCPTransportStreamableHTTP = "streamable-http"
+)
+
 // MemoryConfig holds memory sub-configuration for an agent.
 type MemoryConfig struct {
 	Enabled    bool   `toml:"enabled"`
@@ -33,20 +40,31 @@ type SubAgentsConfig struct {
 	Timeout  int   `toml:"timeout"`
 }
 
+// MCPServerConfig holds the connection settings for one MCP server an agent uses.
+// Header values may reference environment variables as ${VAR}; they are expanded
+// at run time, not at load time.
+type MCPServerConfig struct {
+	Name      string            `toml:"name"`
+	URL       string            `toml:"url"`
+	Transport string            `toml:"transport"`
+	Headers   map[string]string `toml:"headers"`
+}
+
 // AgentConfig represents a parsed agent TOML configuration file.
 type AgentConfig struct {
-	Name          string          `toml:"name"`
-	Description   string          `toml:"description"`
-	Model         string          `toml:"model"`
-	SystemPrompt  string          `toml:"system_prompt"`
-	Skill         string          `toml:"skill"`
-	Files         []string        `toml:"files"`
-	Workdir       string          `toml:"workdir"`
-	Tools         []string        `toml:"tools"`
… 3,335 more lines

Required (7)

• •C1 · useStateAction is exported from the next-safe-action/hooks entry point alongside useAction and useOptimisticAction, and the published next-safe-action/stateful-hooks entry point (package.json exports/typesVersions resolving to the built dist) keeps working and exposes the same new full-featured hook, at runtime and in its types: executeAsync, reset, formAction and useAction-style navigation handling, not the old implementation.
• •C2 · useStateAction accepts initResult plus the same options as useAction (onExecute, onSuccess, onError, onNavigation, onSettled, throwOnNavigation) with the same typing rules as HookBaseOptions (onNavigation/onSettled not allowed together with throwOnNavigation: true). Navigation errors thrown by the action (redirect, notFound, forbidden, unauthorized) no longer crash the component: status becomes hasNavigated and onNavigation/onSettled receive the navigationKind; with throwOnNavigation: true the navigation error reaches the nearest error boundary instead. Success/error results fire onSuccess/onError/onSettled exactly once per execution with the same payloads as useAction.
• •C3 · useStateAction returns everything useAction returns (execute, executeAsync, reset, input, result, status and the shorthand flags isIdle/isExecuting/isTransitioning/isPending/hasSucceeded/hasErrored/hasNavigated) plus formAction, and the public types say so (UseStateActionHookReturn and InferUseStateActionHookReturn include executeAsync, reset and formAction). The action is called with (prevResult, input), results chain as prevResult across sequential executions starting from initResult (or {}), and executeAsync resolves with the action result (also when it carries serverError/validationErrors) and rejects with the navigation error when the action navigates.
• •C4 · formAction works with <form action={formAction}>: a submission calls the stateful action with the submitted FormData as input and the previous result as prevResult; status is 'executing' (isPending true) while it is in flight and then hasSucceeded/hasErrored/hasNavigated; result and input are updated; for a submission that succeeds or returns an error result, onSuccess or onError and onSettled fire exactly once (also on repeated submissions); a submission whose action navigates sets hasNavigated and calls onNavigation (how many times the navigation callbacks fire follows the C2 allowance); and form submissions share the same result/prevResult chain as execute.
• •C5 · reset() is a clean slate: status goes back to idle with no error/navigation flags, input becomes undefined and the result is cleared; the next execution receives initResult (or {} when there is none) as prevResult rather than the last result; the cleared result stays shown until that next execution produces a new result, so the pre-reset result does not reappear while it is pending (as with useAction, on both the execute and the form path); and when reset() is called while an execution is in flight, its late result never comes back: not when it arrives, not while the next execution is pending, and the next execution again starts from initResult.
• •C6 · useStateAction is no longer presented as deprecated, and its API reference is current. (1) Code: the hook as exported from next-safe-action/hooks and its public types (UseStateActionHookReturn, InferUseStateActionHookReturn) carry no @deprecated JSDoc tag. (2) Docs: no page under apps/docs/content/docs outside migrations/ calls the hook or its types deprecated, or tells readers to use React's useActionState instead of it. In the starting tree such statements are on five pages, and all of them must be gone: api/hooks-api.mdx (useStateAction heading and warning callout, the 'except deprecated useStateAction' note on HookBaseOptions), guides/hooks.mdx (the 'Deprecated: useStateAction' accordion), concepts/how-it-works.mdx (the next-safe-action/stateful-hooks row of the entry-point table), api/type-utilities.mdx (the '(deprecated)' on the InferUseStateActionHookReturn heading) and api/safe-action-client.mdx (the '(deprecated)' in the .stateAction() description). (3) The hooks API reference (api/hooks-api.mdx) documents the hook as imported from next-safe-action/hooks, with initResult plus the useAction options (including onNavigation/throwOnNavigation) and the useAction return plus formAction (including executeAsync and reset).
• •C7 · Existing behaviour keeps working: useAction and useOptimisticAction behave as before, the rest of the package and the adapter packages are unaffected, and existing tests are not deleted, skipped or weakened (the only expected test change is the old type assertion that UseStateActionHookReturn has no executeAsync/reset).

Quality (5)

• •C8 · Changes stay on the request: the hook, its types, entry points, docs (and optionally the playground demo/changeset). No unrelated refactors of the server-side action builder or adapters, no debug output, no stray files or committed build output.
• •C9 · Follows the codebase's existing building blocks and conventions: options typed with HookBaseOptions (plus initResult) and return type built from UseActionHookReturn, status via getActionStatus/getActionShorthandStatusObject, callbacks via useActionCallbacks (or by reusing useActionBase), navigation detection via FrameworkErrorHandler.isNavigationError, render-phase throw for throwOnNavigation like useActionBase, 'use client' kept on client entry points, a changeset for next-safe-action (minor, new feature) as CLAUDE.md asks, and the library still passes pnpm run lint:lib (tsc + oxlint) once the outdated type assertion is updated.
• •C10 · The final message accurately describes what changed (entry points, options/return parity, formAction, reset semantics, docs/types undeprecated) and states real limitations honestly (e.g. no progressive enhancement without JS); it does not claim behaviour, tests or checks that are not true of the final tree.
• •C11 · Thrown non-navigation errors (e.g. from actions with throwServerError/throwValidationErrors, or network failures) are handled like useAction: the hook reports status hasErrored, onError receives the error as thrownError and onSettled fires, executeAsync rejects with it, and the hook stays mounted and usable for the next execution, instead of the error escaping to the nearest error boundary.
• •C12 · The hooks guide (apps/docs/content/docs/guides/hooks.mdx) covers useStateAction as a supported hook, in place of the old 'Deprecated: useStateAction' accordion: at least a short section or example with the next-safe-action/hooks import and formAction usage.

diff --git a/packages/next-safe-action/src/hooks-shared.ts b/packages/next-safe-action/src/hooks-shared.ts
--- a/packages/next-safe-action/src/hooks-shared.ts
+++ b/packages/next-safe-action/src/hooks-shared.ts
@@ -2,22 +2,38 @@
 
 import * as React from "react";
 import { getActionShorthandStatusObject, getActionStatus, useActionCallbacks } from "./hooks-utils";
-import type { HookActionStatus, HookBaseOptions, HookCallbacks, SingleInputActionFn, HookShorthandStatus } from "./hooks.types";
+import type {
+	HookActionStatus,
+	HookBaseOptions,
+	HookCallbacks,
+	HookShorthandStatus,
+	SingleInputActionFn,
+	SingleInputStateActionFn,
+} from "./hooks.types";
 import type { SafeActionResult } from "./index.types";
 import { FrameworkErrorHandler } from "./next/errors";
 import type { InferInputOrDefault, StandardSchemaV1 } from "./standard-schema";
 
 /**
- * Shared base hook for `useAction` and `useOptimisticAction`.
+ * Shared base hook for `useAction`, `useOptimisticAction` and `useStateAction`.
  * Extracts common state management, execution logic, and callback wiring.
  *
- * @param onTransitionStart Optional callback invoked inside `startTransition` before the action runs.
+ * @param baseOpts.onTransitionStart Optional callback invoked inside `startTransition` before the action runs.
  *   Used by `useOptimisticAction` to call `setOptimisticValue`.
+ * @param baseOpts.withState Whether `safeActionFn` is a stateful action, called with the previous result
+ *   before the input. Used by `useStateAction`.
+ * @param baseOpts.initResult Result before the first execution and after `reset`. Defaults to `{}`.
  */
 export function useActionBase<ServerError, Schema extends StandardSchemaV1 | undefined, ShapedErrors, Data>(
-	safeActionFn: SingleInputActionFn<ServerError, Schema, ShapedErrors, Data>,
+	safeActionFn:
+		| SingleInputActionFn<ServerError, Schema, ShapedErrors, Data>
+		| SingleInputStateActionFn<ServerError, Schema, ShapedErrors, Data>,
 	opts: HookBaseOptions<ServerError, Schema, ShapedErrors, Data> | undefined,
-	onTransitionStart?: (input: InferInputOrDefault<Schema, undefined>) => void
+	baseOpts?: {
+		onTransitionStart?: (input: InferInputOrDefault<Schema, undefined>) => void;
+		withState?: boolean;
+		initResult?: SafeActionResult<ServerError, Schema, ShapedErrors, Data>;
+	}
 ): {
 	isTransitioning: boolean;
 	result: SafeActionResult<ServerError, Schema, ShapedErrors, Data>;
@@ -28,8 +44,11 @@ export function useActionBase<ServerError, Schema extends StandardSchemaV1 | und
 	reset: () => void;
 	shorthandStatus: HookShorthandStatus;
 } {
+	const withState = baseOpts?.withState ?? false;
+	const initResult = baseOpts?.initResult ?? {};
+
 	const [isTransitioning, startTransition] = React.useTransition();
-	const [result, setResult] = React.useState<SafeActionResult<ServerError, Schema, ShapedErrors, Data>>({});
+	const [result, setResult] = React.useState<SafeActionResult<ServerError, Schema, ShapedErrors, Data>>(initResult);
 	const [clientInput, setClientInput] = React.useState<InferInputOrDefault<Schema, void>>();
 	const [isExecuting, setIsExecuting] = React.useState(false);
 	const [navigationError, setNavigationError] = React.useState<Error | null>(null);
@@ -40,9 +59,18 @@ export function useActionBase<ServerError, Schema extends StandardSchemaV1 | und
 	// This prevents stale responses from overwriting fresh state on rapid calls.
 	const requestIdRef = React.useRef(0);
 
+	// Previous result passed to stateful actions: the latest result returned by the action, or
+	// `initResult` before the first execution and after `reset`. Thrown errors and navigations don't
+	// produce a result, so they leave it unchanged.
+	const prevResultRef = React.useRef(initResult);
+
+	// Latest `initResult`, restored by `reset`.
+	const initResultRef = React.useRef(initResult);
+	initResultRef.current = initResult;
+
 	// Stable ref for the transition start callback to avoid destabilizing execute/executeAsync.
-	const onTransitionStartRef = React.useRef(onTransitionStart);
-	onTransitionStartRef.current = onTransitionStart;
+	const onTransitionStartRef = React.useRef(baseOpts?.onTransitionStart);
+	onTransitionStartRef.current = baseOpts?.onTransitionStart;
 
 	const status = getActionStatus<ServerError, Schema, ShapedErrors, Data>({
 		isExecuting,
@@ -52,56 +80,12 @@ export function useActionBase<ServerError, Schema extends StandardSchemaV1 | und
 		hasThrownError: thrownError !== null,
 	});
 
-	const execute = React.useCallback(
-		(input: InferInputOrDefault<Schema, void>) => {
-			const thisRequestId = ++requestIdRef.current;
-
-			// Set state synchronously before starting the transition.
-			setIsIdle(false);
-			setNavigationError(null);
-			setThrownError(null);
-			setClientInput(input);
-			setIsExecuting(true);
-
-			startTransition(() => {
-				onTransitionStartRef.current?.(input as InferInputOrDefault<Schema, undefined>);
-
-				safeActionFn(input as InferInputOrDefault<Schema, undefined>)
-					.then((res) => {
-						if (thisRequestId !== requestIdRef.current) return;
-						setResult(res ?? {});
-					})
-					.catch((e) => {
-						if (thisRequestId === requestIdRef.current) {
-							setResult({});
-
-							if (FrameworkErrorHandler.isNavigationError(e)) {
-								setNavigationError(e);
-							} else {
-								setThrownError(e as Error);
-							}
-						}
-
-						// Only re-throw non-navigation errors for React error boundary handling.
-						// Navigation errors are handled via render-phase throw (throwOnNavigation).
-						if (!FrameworkErrorHandler.isNavigationError(e)) {
-							throw e;
-						}
-					})
-					.finally(() => {
-						if (thisRequestId !== requestIdRef.current) return;
-						setIsExecuting(false);
-					});
-			});
-		},
-		[safeActionFn]
-	);
-
… 1,575 more lines

Required (5)

• •C1 · GlyphMetrics gains public v_advance (f32), v_advance_exact (F48Dot16) and v_advance_batched(convert, glyphs), shaped like h_advance / h_advance_exact / h_advance_batched and reachable from both Font::glyph_metrics() and FontInstance::glyph_metrics(). At the default location a font with vmtx reports exactly the advance vmtx states: positive, with glyphs in the short-metric tail sharing the last long advance. In a font with vmtx, a glyph id at or past the glyph count measures zero at every location (fonts without vmtx: see C3). The batched form agrees with one-at-a-time, convert decides the output type, and v_advance equals v_advance_exact narrowed to f32.
• •C2 · In a font with vmtx, away from the default location, heights vary the way widths do. If the font has VVAR, its advance-height deltas answer, and gvar, glyf and loca are then never read. Otherwise gvar's phantom-point deltas answer, using the vertical pair: top minus bottom, i.e. deltas[2].y - deltas[3].y of Gvar::phantom_point_deltas, which already follows USE_MY_METRICS. With neither table, vmtx is used unvaried. The exact height keeps the delta's fraction. At the default location, including all-zero coordinates, no variation table (VVAR, gvar, glyf, loca) is read.
• •C3 · In a font without vmtx, Type 1 included, every glyph of the font gets the same height: ascender minus descender of the horizontal line, without the line gap. The line is chosen as skrifa's Metrics chooses it: (1) the typographic line if OS/2 sets USE_TYPO_METRICS; (2) else hhea; (3) if hhea is zeroed, the typographic line if it is not zeroed, else the Windows pair, winAscent + winDescent (the descent is stated as a positive depth). A Type 1 font's line is the bounding-box line GlobalMetrics::from_type1 provides. Measured through a FontInstance, the line is the one at that instance's location, so MVAR moves it, and its deltas keep their fraction as every measurement at a location does in this API. It is not the font's default-location line. No per-glyph VVAR or gvar delta is applied to it.
• •C4 · Existing behaviour is unchanged: h_advance* results (hmtx, HVAR, gvar, Type 1 charstrings, half-em fallback), GlobalMetrics fields and FontInstance behaviour. No existing test is deleted, skipped or weakened.
• •C5 · Follows the precedent's caching: vmtx and VVAR are each parsed at most once per font and kept on the font beside the existing hmtx/HVAR/gvar caches. That means Once<TableCache<...>> cells in FontRepr reached through Font accessors, or an equivalent per-font cache. They are not re-read from the tables on every measurement or every glyph_metrics() call.

Quality (3)

• •C6 · Keeps the shape and the laziness the horizontal path documents (FontRepr's comment on its variation caches, font/cache.rs, the test taking_the_metrics_reads_hmtx_but_nothing_that_varies): what a location changes waits until something asks. VVAR, like HVAR, is read only when a height is asked for at a location, and gvar/glyf/loca only when VVAR is absent. Taking the metrics reads none of them. The varied vertical path is kept out of line (#[inline(never)]) and built on RawGlyphMetrics::run / run_varied. The new public methods carry doc comments in the module's style.
• •C7 · The change stays within read-fonts' font API (src/model) plus any tests or test data the agent adds. No edits to skrifa, the table-level APIs, Cargo manifests or unrelated files, no debug output, no stray files.
• •C8 · The final message says accurately what was done: which tables answer at a location and in what order, what fonts without vmtx (and Type 1 fonts) report, and how the line is chosen. It claims nothing untrue of the final tree, such as tests that do not exist or were not run.

diff --git a/read-fonts/src/model/font.rs b/read-fonts/src/model/font.rs
--- a/read-fonts/src/model/font.rs
+++ b/read-fonts/src/model/font.rs
@@ -65,8 +65,10 @@ impl Font {
             shaping_data: Once::new(),
             global_metrics: Once::new(),
             h_metrics: Once::new(),
+            v_metrics: Once::new(),
             glyf_loca: Once::new(),
             hvar: Once::new(),
+            vvar: Once::new(),
             gvar: Once::new(),
         };
         Ok(Self(Arc::new(repr)))
@@ -143,6 +145,24 @@ impl Font {
             .get()
     }
 
+    /// Returns what `vmtx` states, parsed once for the font.
+    ///
+    /// Unlike `hmtx`, nothing reads this until something measures
+    /// vertically: most text never is, and on a platform that hands tables
+    /// over one at a time, asking for it means copying it.
+    #[inline]
+    pub(crate) fn v_metrics(&self) -> &RawGlyphMetrics<'_> {
+        let Some(tables) = self.tables_arc() else {
+            return empty_glyph_metrics();
+        };
+        self.0
+            .v_metrics
+            .get_or_init(|| {
+                TableCache::read(tables.clone(), |tables| RawGlyphMetrics::from_vmtx(&tables))
+            })
+            .get()
+    }
+
     /// Returns the outline tables, parsed once for the font.
     ///
     /// Outlines and metrics in both directions read these, so they are
@@ -170,6 +190,18 @@ impl Font {
             .as_ref()
     }
 
+    /// Returns `VVAR`, parsed once for the font.
+    #[inline]
+    pub(crate) fn vvar(&self) -> Option<&Vvar<'_>> {
+        let tables = self.tables_arc()?;
+        self.0
+            .vvar
+            .get_or_init(|| TableCache::read(tables.clone(), |tables| VvarTable::read(&tables)))
+            .get()
+            .0
+            .as_ref()
+    }
+
     /// Returns `gvar`, parsed once for the font.
     ///
     /// Typically about half a variable font, so nothing should ask for this
@@ -215,14 +247,18 @@ struct FontRepr {
     // What `hmtx` states, parsed once for the font. Held beside the tables
     // it borrows, which is what lets it live here at all.
     h_metrics: Once<TableCache<RawGlyphMetrics<'static>>>,
-    // `HVAR` states the deltas a location makes to a metric outright, and
-    // `gvar` states them as phantom points on an outline, which `glyf` and
-    // `loca` are read to reach and which outlines will read for their own
-    // sake. None of the three depends on a location to parse, so every
-    // instance shares them, and only an instance asks for them: a font read
-    // at its default location touches none of them.
+    // The same for `vmtx`, kept in a cell of its own so that horizontal
+    // text never reads it.
+    v_metrics: Once<TableCache<RawGlyphMetrics<'static>>>,
+    // `HVAR` and `VVAR` state the deltas a location makes to a metric
+    // outright, and `gvar` states them as phantom points on an outline,
+    // which `glyf` and `loca` are read to reach and which outlines will read
+    // for their own sake. None of these depends on a location to parse, so
+    // every instance shares them, and only an instance asks for them: a
+    // font read at its default location touches none of them.
     glyf_loca: Once<TableCache<GlyfLoca<'static>>>,
     hvar: Once<TableCache<HvarTable<'static>>>,
+    vvar: Once<TableCache<VvarTable<'static>>>,
     gvar: Once<TableCache<GvarTable<'static>>>,
 }
 
diff --git a/read-fonts/src/model/font/cache.rs b/read-fonts/src/model/font/cache.rs
--- a/read-fonts/src/model/font/cache.rs
+++ b/read-fonts/src/model/font/cache.rs
@@ -58,10 +58,20 @@ impl<'a> HvarTable<'a> {
     }
 }
 
+/// The table stating how a location changes vertical metrics.
+#[derive(Clone, Default, Yokeable)]
+pub(crate) struct VvarTable<'a>(pub(crate) Option<Vvar<'a>>);
+
+impl<'a> VvarTable<'a> {
+    pub(crate) fn read(tables: &impl TableProvider<'a>) -> Self {
+        Self(tables.vvar().ok())
+    }
+}
+
 /// The table stating how a location changes outlines.
 ///
-/// Metrics read this only where `HVAR` is absent, recovering the answer from
-/// the phantom points it carries alongside each glyph.
+/// Metrics read this only where `HVAR` or `VVAR` is absent, recovering the
+/// answer from the phantom points it carries alongside each glyph.
 #[derive(Clone, Default, Yokeable)]
 pub(crate) struct GvarTable<'a>(pub(crate) Option<Gvar<'a>>);
 
diff --git a/read-fonts/src/model/metrics/glyph.rs b/read-fonts/src/model/metrics/glyph.rs
--- a/read-fonts/src/model/metrics/glyph.rs
+++ b/read-fonts/src/model/metrics/glyph.rs
@@ -1,9 +1,10 @@
 //! Per-glyph metrics.
 
+use super::{GlobalMetrics, LineBox};
 use crate::{
     model::{Font, FontKind},
     ps::{cs::CommandSink, type1::Type1Font},
-    tables::hmtx::LongMetric,
+    tables::{hmtx::LongMetric, mvar::tags},
     TableProvider,
 };
 use types::{F2Dot14, F48Dot16, Fixed, GlyphId};
@@ -180,6 +181,154 @@ impl<'a> GlyphMetrics<'a> {
             *out = convert(width);
         }
     }
+
+    /// Returns the advance height of `glyph`, in design units.
… 1,173 more lines

Required (5)

• •C1 · Finds the empty-superclass bug in NamespaceNode#process (lib/solargraph/parser/parser_gem/node_processors/namespace_node.rb:13-15 and :30): superclass_name is now an interpolated String for every class node, so for a class without a constant superclass it is "", which is truthy, and if superclass_name pushes a Pin::Reference::Superclass with an empty name for a class that has none. The review presents this as a bug.
• •C2 · Finds that the #[...] superclass annotation is searched for in the whole class, not just on the class line: parameters_from_inline_rbs (namespace_node.rb:45-47) runs an unanchored regex over region.source.code_for(node), which is the source of the entire class including its body, so the first #[...] / # [...] anywhere inside the class (a nested class's annotation, an ordinary comment) becomes the outer class's superclass type arguments.
• •C3 · Finds that Pin::Method#return_type_from_inline_rbs (lib/solargraph/pin/method.rb:732-736, called first by return_type at :146) calls RBS::Parser.parse_method_type without rescuing RBS::ParsingError, so Pin::Method#return_type raises instead of falling back whenever the method's comment lines that start with ': ' don't parse.
• •C4 · The review contains no confident claims about defects that do not exist in the pending change.
• •C5 · The agent leaves the pending change as it found it: when it is done, git status, git diff and the untracked lib/solargraph/rbs_translator.rb are identical to the starting state, HEAD is still the starting commit on main, and no checkout of the code made for a baseline (worktree, git archive extraction, copy) is left inside the repository. The reply does not claim to have applied fixes.

Quality (3)

• •C6 · Each reported defect comes with a concrete triggering input or scenario, an accurate account of what it breaks and a fix direction that would actually fix it, and the real defects are clearly separated from nits rather than buried in a flat list.
• •C7 · Mentions the leftover debug logging Solargraph.logger.warn "Superclass: ..." (namespace_node.rb:29).
• •C8 · Recognises that inline_rbs runs for every Pin::Method, including RBS/YARD pins whose documentation has lines starting with ': '. Together with the missing rescue, this breaks completion and inference for ordinary code (e.g. warn, each.with_index), not only for methods with a malformed annotation.

Required (7)

• •C1 · Main generation calls: the answer says they go to Gemini's OpenAI-compatible endpoint https://generativelanguage.googleapis.com/v1beta/openai/ (not api.openai.com), with the bare model name gemini‑3-pro (the gemini/ prefix is stripped). It attributes the base URL to the provider lookup in config.py: _parse_model_spec matches gemini in the _PROVIDERS table.
• •C2 · Main-loop key: the answer says the main generation calls send the value of OPENAI_API_KEY as their key to Google's endpoint. It attributes this to skydiscover's own fallback: _resolve_api_key_from_env finds neither GEMINI_API_KEY nor GOOGLE_API_KEY and returns os.environ.get("OPENAI_API_KEY") (config.py ~86).
• •C3 · Summaries: the answer says the monitor's AI summaries use model gpt‑5-mini against OpenAI's API at https://api.openai.com/v1, and that these two values come from the monitor config's own defaults in config.py (MonitorConfig.summary_model / summary_api_base). The summary key is judged under C4.
• •C4 · Summary key: the answer says summary_api_key is unset in this setup and that the monitor server's configure_summary falls back to the OPENAI_API_KEY environment variable, so the summary requests carry the OpenAI key.
• •C5 · YAML-only fix for summaries: the YAML the answer recommends (no code changes) sets all three monitor.summary_* fields to Gemini values. summary_model is a Gemini model given as the bare id (e.g. gemini‑3-pro), because the summary path sends the string verbatim with no provider-prefix parsing. summary_api_base is Gemini's OpenAI-compatible root, https://generativelanguage.googleapis.com/v1beta/openai/ (the gemini URL in _PROVIDERS). summary_api_key is a Gemini key. The answer must not suggest that a subset works, e.g. only summary_model, summary_model plus exporting GEMINI_API_KEY, or a prefixed gemini/... model that is resolved automatically.
• •C6 · The answer makes no false claims about how the code behaves in this setup.
• •C7 · The agent only explains and leaves the repository's tracked files unchanged, because the developer asked for no edits.

Quality (2)

• •C8 · Clear and direct. The answer covers the three asks (main loop: base/model/key; summaries: base/model/key; YAML to move the summaries) with file:line evidence for each decision point, and keeps verified behaviour apart from speculation.
• •C9 · Depth beyond the core: the answer notes at least one of the following. (1) When summary calls actually fire: a per-program summary each time a program is clicked in the dashboard, the global summary on Refresh, and automatically only every summary_interval programs, default 0. (2) bridge_provider_env writes the leaked OpenAI key into GEMINI_API_KEY/GOOGLE_API_KEY with setdefault and sets OPENAI_API_BASE to the Gemini URL. (3) start_monitor duplicates the summary wiring for external backends. (4) An exported OPENAI_API_BASE/OPENAI_BASE_URL would overwrite every model's api_base in this YAML path.

Required (12)

• •C1 · The plan makes loopback the default bind address of Floci's API listener. It adds a separate, explicit opt-in that is off by default and is what the startup guard enforces. The opt-in can take any form: a boolean, an allowlist of exposed addresses, or an enum. The bind address may stay quarkus.http.host / QUARKUS_HTTP_HOST (flipping src/main/resources/application.yml:15), or be a new Floci-owned setting that feeds it. Either way, no user setting can bypass the consent: the guard checks the host that actually takes effect, so QUARKUS_HTTP_HOST=0.0.0.0 or -Dquarkus.http.host=0.0.0.0 is refused without the opt-in.
• •C2 · The plan adds a startup check that aborts boot when the bind host is not loopback and the opt-in is off. Loopback covers at least 127.0.0.1 (ideally 127.0.0.0/8), ::1 and localhost. Every other address needs the opt-in: the wildcards 0.0.0.0/::, specific LAN or bridge IPs, and other hostnames. The check runs before Quarkus opens its HTTP socket.
• •C3 · The plan finds that in TLS mode the public port is served by TlsProxyServer, which binds a hard-coded 0.0.0.0 (TlsProxyServer.java:106-109) on floci.port and on floci.tls.aws-https-port. So flipping quarkus.http.host alone leaves TLS mode listening on every interface. The plan has the proxy bind the configured host, and the consent check covers it before it starts listening.
• •C4 · The plan handles TLS mode's config pin. TlsConfigSource puts quarkus.http.host=127.0.0.1, for the internal 4510/4511 backends, into a config source with ordinal 300 (TlsConfigSource.java:146). So in TLS mode the effective quarkus.http.host is that pin, not the user's value. The host the public TLS listener binds, and the consent check that protects that listener, must come from the user-configured host, never from the effective quarkus.http.host. Otherwise that check never refuses in TLS mode, and the proxy binds loopback even when the user asked for 0.0.0.0.
• •C5 · The plan keeps every published Docker image and the entrypoint fallback working, and it tells the developer who gives the consent for container users and what follows from that. Inside a container a loopback-only listener is unreachable. A published port (docker run -p 4566:4566) cannot reach it, and neither can the containers Floci launches, which reach it by its container IP. So all five published images (docker/Dockerfile, Dockerfile.jvm-package, Dockerfile.native, Dockerfile.native-package, Dockerfile.compat) and the entrypoint's empty-argv fallback (docker/entrypoint.sh:76-82) need a non-loopback host plus consent. Either path is fine, as long as its consequence is stated: (1) the images supply the consent. Docker users then never opt in themselves, and they stay as exposed as their -p publish makes them: -p 4566:4566 publishes on every host interface; (2) the users supply it. Existing Docker setups then break until they add the opt-in, so the plan says who breaks and how they migrate.
• •C6 · Under the plan's design, the entrypoint's empty-argv fallback (used by Testcontainers' LocalStackContainer) starts Floci with the host and the opt-in actually reaching the JVM. The opt-in comes from the image, or from the user under a user-supplied-consent design. The fallback's JVM branch today (docker/entrypoint.sh:80) is java -jar /app/quarkus-app/quarkus-run.jar -Dquarkus.http.host=0.0.0.0. A -D after -jar is a program argument the JVM never applies. It only worked because the yml default was 0.0.0.0.
• •C8 · The plan accounts for the test profile. src/test/resources/application.yml sets no quarkus.http.host, so the suite inherits the main default. Quarkus derives the RestAssured URL from quarkus.http.host and maps only 0.0.0.0 to localhost. With a 127.0.0.1 default the test authority becomes 127.0.0.1, which breaks tests whose SigV4 signature covers localhost:<port>. A loopback test listener also refuses the Docker-backed tests whose containers call Floci back. The plan keeps the suite working. Typically it sets the test listener to 0.0.0.0 with the opt-in, as a test-only exception.
• •C9 · The plan includes documentation work for the changed default bind address and the new opt-in.
• •C10 · The plan includes automated tests for the startup check, so the behaviour the developer asked for is verifiable: a loopback host starts, a non-loopback host is refused without the opt-in, and the same host is allowed with it.
• •C11 · The agent does not modify the repository: no source, config, Docker, docs or test file is changed, added or deleted. The developer asked for a plan only.
• •C12 · The plan's statements about the current code and its configuration precedence are accurate. In particular, it does not claim any of the following: (1) TLS mode already honours QUARKUS_HTTP_HOST or already listens only on loopback; (2) QUARKUS_HTTP_HOST or application.yml override the TlsConfigSource pin; (3) an env var (-e) overrides a -D system property; (4) a -D placed after -jar sets a system property, or the entrypoint fallback already passes the host to the JVM; (5) every image already passes -Dquarkus.http.host=0.0.0.0; (6) Floci has no bind-address setting, or no GATEWAY_LISTEN mapping; (7) the test profile sets its own host, or is unaffected by a 127.0.0.1 default. With a localhost test listener, 'the whole suite is unaffected' is also false, because of the CA-bundle profile and the Docker callback tests.
• •C13 · The plan answers 'in what order'. It states an order for the work, and the default flip does not land before the TLS proxy fix, the image consent and the test-profile change.

Quality (8)

• •C7 · The plan considers the LocalStack shim. docker/localstack-parity.sh:22-23 maps GATEWAY_LISTEN to QUARKUS_HTTP_HOST, and LocalStack binds there without any opt-in. Under the plan's design, either GATEWAY_LISTEN users are not refused, or the plan says they now need the opt-in too. An explicitly set Floci variable still wins (the shim's 'Floci vars always win' rule). The GATEWAY_LISTEN row in docs/getting-started/migrate-from-localstack.md reflects the behaviour.
• •C14 · The plan follows Floci conventions: (1) the opt-in is config under floci.* with its FLOCI_* env var, declared in EmulatorConfig with @WithDefault, and in the main application.yml (and the test yml where needed). A boolean is the simplest form; an allowlist is fine; (2) quarkus.http.host kept as the one bind setting. A Floci alias that feeds it adds a second name for the same thing, a small cost at most; (3) the guard at the earliest startup priority (@Priority(Interceptor.Priority.PLATFORM_BEFORE)), or the proxy self-checking; (4) a fatal IllegalStateException like the existing boot validators. Its message names the opt-in (property or env var) and/or the host setting, so the user knows what to change; (5) a defaults test following the ApplicationDefaultsTest pattern (yml value plus @WithDefault); (6) quarkus.http.host-validation.require-localhost: false kept. It matters more now: Quarkus enables Host-header validation whenever it is bound to loopback, which becomes the default; (7) no dead code left in the Docker scripts, such as a -D after -jar that the design does not need.
• •C15 · The plan's design never hands an unknown -Dfloci.* system property to the possibly older binary inside docker/Dockerfile.compat. That image builds from BASE_IMAGE=floci/floci:${VERSION}, and the compatibility workflow uses VERSION=latest. An older binary refuses to boot on an unknown -Dfloci.* property (SRCFG00050) but ignores unknown env vars.
• •C16 · The plan calls out that a Floci run directly on a Linux host needs a non-loopback bind when its services start containers (Lambda, ECS). Those containers reach it through host.docker.internal, i.e. the docker bridge gateway. The plan documents the opt-in plus firewalling for that setup.
• •C17 · The plan treats Floci's other listeners deliberately. Several components bind every interface on their own: (1) the Lambda Runtime API (RuntimeApiServer.java:568), embedded DNS, the ELBv2 data plane and the MWAA proxy; (2) IMDS and the database/cache auth proxies, which name no host; (3) IoT MQTT, through its own floci.services.iot.mqtt.host. The plan may keep this change to the API listener (quarkus.http.host and the TLS proxy) and list the others as follow-ups. Or it may route them through the same setting and state the consequence: containers Floci launches (Lambda, ECS, EC2/EKS) reach them over the docker bridge, so a Floci running on the host then needs the non-loopback bind plus the opt-in for Docker-backed features.
• •C18 · Inside the images, explicit user settings still win over the new image defaults. A user-set QUARKUS_HTTP_HOST must still apply, e.g. --network host -e QUARKUS_HTTP_HOST=127.0.0.1. So must an explicit opt-out -e FLOCI_..=false. Image ENV lines and ${VAR:-default} entrypoint exports satisfy this, since -e overrides image ENV. The same holds for a new Floci bind setting that the images set.
• ✗C19 · The plan says how to verify the change beyond the guard: (1) TLS proxy tests. The proxy binds the configured host, not every interface. It is refused without the opt-in, tested either in the proxy's own test or, when the check lives in a pre-proxy guard, by a TLS-mode boot test: a non-loopback host without the opt-in fails startup, and with the opt-in the proxy listens on the configured host; (2) a test that the host is resolved past the TLS pin, and updates to the tests that construct the proxy directly; (3) a sample of localhost-signed integration tests, and a Docker callback test run where Docker is available; (4) the docker/test-*.sh scripts, which CI does not run; (5) an image smoke test.
• •C20 · The plan surfaces who consents inside the containers as a decision for the developer. It weighs image-level consent against user-supplied consent, and any other option it considers, and recommends one with its reasons. Relevant considerations: (1) image-level consent keeps docker run, compose and Testcontainers users working, but they never opt in, and their -p exposure is unchanged; (2) user-supplied consent is the literal reading of the request, but it breaks every existing container setup; (3) the in-container opt-in cannot see the host-side publish either way.

Required (5)

• •C1 · For any timestamp from about a year back to twenty years ahead, getLocalTime()/getTimeStr() give exactly what localtime_r() gives under the TZ in effect: date and time fields, tm_wday/tm_yday, tm_isdst, tm_gmtoff and the abbreviation (tm_zone, %Z). This includes timestamps outside the current DST period, the exact second of every switch and the second before it, zones whose DST is not +1h (half-hour Lord Howe, two-hour Troll, negative Irish DST, zero-width), and switches that change only isdst or the abbreviation (e.g. America/Vancouver going to permanent MST in 2026).
• •C2 · getGMTOff() returns the UTC offset in effect at the moment it is called, i.e. the same value as getLocalTime(time(nullptr)).tm_gmtoff and localtime_r(now). This holds immediately after a DST switch, for non‑1h DST, and immediately after TZ is changed (setenv + tzset) and local_time_init() is called. There is no separately cached or frozen copy that can lag behind either.
• •C3 · After initialisation, no code path reachable from getLocalTime(), getTimeStr() or getGMTOff() calls libc's timezone functions (localtime/localtime_r, gmtime/gmtime_r, mktime/timegm/timelocal, tzset). That includes periodic or clock-triggered recalibration, background refresh threads, and fallbacks for some timestamps. no_locks_localtime() stays lock-free and fork-safe.
• •C4 · Between re-initialisations, i.e. as long as local_time_init() is not called again, tm_zone in every struct tm returned by getLocalTime() points at a valid NUL-terminated copy of the right abbreviation in storage the library controls. It is never libc's mutable tzname[], never an uninitialised pointer, and never a per-call or per-thread buffer that a later getLocalTime()/getTimeStr() call overwrites. Returned results don't change when the host program calls localtime_r() on other timestamps, or when other threads do so concurrently. The requirement does NOT extend across local_time_init(): a struct tm obtained before a TZ re-initialisation is not required to keep a valid or unchanged tm_zone afterwards.
• •C5 · Existing behaviour and API keep working. util.h still offers long getGMTOff(), struct tm getLocalTime(time_t) and std::string getTimeStr(const char *, time_t = 0) with the same meaning. local_time_init() still exists and re-reads TZ, rebuilding whatever the hot path uses. Logging (LogChannel::printTime, FileChannel file naming and cleanup) still works. No existing test is deleted, skipped or weakened.

Quality (3)

• •C6 · The change follows the file's existing conventions. It keeps the Redis-derived lock-free arithmetic of no_locks_localtime() and updates the explanatory header comment. Non-obvious logic gets bilingual (Chinese + English) comments like the surrounding code. The doc comments in util.h/local_time.h that described the old behaviour are updated (60-second calibration, 'timestamps of another season are off by one hour', the fork caveat). The abbreviation is copied by value. The table does not depend on dynamic-initialisation order across translation units (constant-initialised placeholder or equivalent). The Windows branch stays coherent (struct tm has no tm_gmtoff/tm_zone there).
• •C7 · No unrelated changes, debug output, leftover files or commented-out code.
• •C8 · The final message explains what was wrong: the current-moment offset applied to every timestamp, fixed +1h DST, unset tm_zone, and the separately cached getGMTOff(). It says how this was fixed and states the coverage window and its limits: timestamps outside it, and that a TZ change at run time needs local_time_init() or a restart. It claims nothing that is not true of the final tree (e.g. tests that were not added or run).

diff --git a/src/Util/local_time.cpp b/src/Util/local_time.cpp
--- a/src/Util/local_time.cpp
+++ b/src/Util/local_time.cpp
@@ -31,11 +31,13 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
+#include <algorithm>
 #include <atomic>
 #include <ctime>
-#ifndef _WIN32
-#include <sys/time.h>
-#endif
+#include <limits>
+#include <set>
+#include <string>
+#include <vector>
 
 #include "local_time.h"
 
@@ -46,162 +48,243 @@
  * in order to log something to the Redis log, it may deadlock: in the copy
  * of the address space of the forked process the lock will never be released.
  *
- * This function takes the timezone 'tz' as argument, and the 'dst' flag is
- * used to check if daylight saving time is currently in effect. The caller
- * of this function should obtain such information calling tzset() ASAP in the
- * main() function to obtain the timezone offset from the 'timezone' global
- * variable. To obtain the daylight information, if it is currently active or not,
- * one trick is to call localtime() in main() ASAP as well, and get the
- * information from the tm_isdst field of the tm structure. However the daylight
- * time may switch in the future for long running processes, so this information
- * should be refreshed at safe times.
- *
- * Note that this function does not work for dates < 1/1/1970, it is solely
- * designed to work with what time(NULL) may return, and to support Redis
- * logging of the dates, it's not really a complete implementation. */
+ * 时区规则只在local_time_init()中读取：用系统的localtime按天探测、再二分到秒，求出调用
+ * 时刻之前一年至之后二十年内，偏移量、夏令时标志与时区缩写都不变的各个时段，存为一张只读表。
+ * 此后的换算只查这张表，不再调用localtime/gmtime/mktime/tzset；每个时间戳都按它自己
+ * 所处的时段换算，所以夏令时切换无需刷新，夏令时偏移不是1小时的时区(30分钟、2小时)
+ * 也一样正确。表外的时间戳沿用离它最近的时段，不保证与localtime一致。
+ * The time zone rules are only read by local_time_init(): the system localtime is
+ * probed day by day, then bisected down to the second, which yields every period from
+ * a year before the call to twenty years after it over which the offset, the daylight
+ * saving flag and the abbreviation stay the same; those are kept in a read only table.
+ * Conversions afterwards only look the table up and never call localtime/gmtime/mktime/
+ * tzset again. Every timestamp is converted with the period it falls in, hence a
+ * daylight saving switch needs no refresh, and zones whose daylight saving shift is not
+ * one hour (30 minutes, 2 hours) come out right as well. A timestamp outside of the
+ * table uses the closest period and is not guaranteed to agree with localtime. */
 namespace toolkit {
-/* 两者都由local_time_refresh()更新、被任意线程读取，故使用原子变量
- * Both are updated by local_time_refresh() and read by any thread, hence atomic. */
-static std::atomic<int> _daylight_active { 0 };
-static std::atomic<long> _current_timezone { 0 };
+static const time_t secs_day = 3600 * 24;
+/* 建表时的探测步长，短于它的时段可能被漏掉；时区数据库(2026c)在表的覆盖范围内
+ * 最短的时段约7天(Asia/Gaza，2040年)
+ * Probing step used to build the table, a shorter period may be missed; within the span
+ * of the table, the shortest one in the time zone database (2026c) lasts about 7 days
+ * (Asia/Gaza, 2040). */
+static const time_t probe_step = secs_day;
+/* 表覆盖local_time_init()之前一年至之后二十年
+ * The table covers a year before local_time_init() to twenty years after it. */
+static const long long table_past = 366LL * secs_day;
+static const long long table_future = 20 * 366LL * secs_day;
 
-int get_daylight_active() {
-    return _daylight_active.load(std::memory_order_relaxed);
-}
+namespace {
+/* 偏移量、夏令时标志与时区缩写都不变的一个时段
+ * A period over which the offset, the daylight saving flag and the abbreviation
+ * stay the same. */
+struct local_time_period {
+    time_t start; /* 时段的第一秒 First second of the period. */
+    long gmtoff; /* 即tm_gmtoff，单位秒 That is tm_gmtoff, in seconds. */
+    /* 换算时叠加到UTC上的秒数，仅在计入闰秒的时区(right/...)中与gmtoff不同
+     * Seconds added to UTC when converting, only differs from gmtoff in leap second
+     * aware zones (right/...). */
+    long shift;
+    int isdst;
+    const char *zone; /* 时区缩写 Abbreviation. */
+};
 
-long get_local_gmtoff() {
-    /* 夏令时期间本地时间比标准时间快1小时，偏移量也必须体现这1小时
-     * Daylight saving time puts the local time one hour ahead of standard time,
-     * so it must be reflected by the offset as well. */
-    return -_current_timezone.load(std::memory_order_relaxed) + 3600 * get_daylight_active();
+struct local_time_table {
+    std::vector<local_time_period> periods; /* 按start升序，不为空 Sorted by start, never empty. */
+    std::set<std::string> zones; /* 各时段zone的存储 Storage of the zone of the periods. */
+    /* 被替换的表永不释放：其他线程可能还在查它，交出去的tm_zone也还指向它；
+     * 串成链表只是为了让它们保持可达，免得被内存检测工具当成泄漏
+     * A replaced table is never freed: other threads may still be looking it up, and
+     * the tm_zone handed out still points into it; chaining them merely keeps them
+     * reachable, so that leak checkers do not take them for leaks. */
+    const local_time_table *prev = nullptr;
+};
+} // namespace
+
+/* local_time_init()之前按UTC换算
+ * UTC is used until local_time_init() runs. */
+static const local_time_period _utc_period = { 0, 0, 0, 0, "UTC" };
+static std::atomic<const local_time_table *> _table { nullptr };
+
+/* 公历日期距1970-01-01的天数，1970年之前同样适用，算法见
+ * http://howardhinnant.github.io/date_algorithms.html
+ * Days from 1970-01-01 to a date of the proleptic Gregorian calendar, dates before
+ * 1970 included, see the link above for the algorithm. */
+static long long days_from_civil(long long year, int month, int mday) {
+    year -= month <= 2;
+    long long era = (year >= 0 ? year : year - 399) / 400;
+    long long yoe = year - era * 400; /* [0, 399] */
+    long long doy = (153 * (month > 2 ? month - 3 : month + 9) + 2) / 5 + mday - 1; /* [0, 365] */
+    long long doe = yoe * 365 + yoe / 4 - yoe / 100 + doy; /* [0, 146096] */
+    return era * 146097 + doe - 719468;
 }
 
-static int is_leap_year(time_t year) {
-    if (year % 4)
-        return 0; /* A year not divisible by 4 is not leap. */
-    else if (year % 100)
-        return 1; /* If div by 4 and not 100 is surely leap. */
-    else if (year % 400)
-        return 0; /* If div by 100 *and* not by 400 is not leap. */
-    else
-        return 1; /* If div by 100 and 400 is leap. */
… 783 more lines