Add in-place agent reconnect to recover from a hung child

When the agent child hangs (e.g. the machine resumes from suspend with a dead connection) the only recovery was to quit Neovim and restore, since quitting is what actually killed the child. Agentic.reconnect() does that in place: stop the child, which drains the stuck request callbacks and resets the generating UI, respawn and re-initialize, then reload the current session so the conversation continues. The agent process is shared per provider, so this also resets other tabs on that provider; they re-establish on next use.

Author: schmoelder

lua/agentic/acp/acp_client.lua

@@ -698,6 +698,17 @@ function ACPClient:stop()
     self.transport:stop()
 end
 
+--- Force a fresh agent process in place: kill the current (possibly hung)
+--- child, then respawn and re-initialize. `stop()` drains every pending
+--- callback and moves the state to "disconnected", which `_connect()` requires.
+--- Sessions are not restored here; the caller re-establishes them once the
+--- client reaches "ready" again (via `when_ready`).
+function ACPClient:reconnect()
+    self.transport:stop()
+    self.reconnect_count = 0
+    self:_connect()
+end
+
 function ACPClient:_connect()
     if self.state ~= "disconnected" then
         return

lua/agentic/acp/acp_client.test.lua

@@ -575,4 +575,88 @@ describe("ACPClient", function()
             assert.is_nil(watched_client._watchdog_timer)
         end)
     end)
+
+    describe("reconnect", function()
+        local original_schedule
+
+        before_each(function()
+            -- The drain on disconnect defers rejection via vim.schedule; run it
+            -- inline so it resolves within the test.
+            original_schedule = vim.schedule
+            vim.schedule = function(fn)
+                fn()
+            end
+        end)
+
+        after_each(function()
+            vim.schedule = original_schedule
+        end)
+
+        it("stops the transport and re-initializes back to ready", function()
+            local client = create_ready_client(LOAD_CAPS)
+            assert.equal("ready", client.state)
+
+            -- stop() drives the connection down; _connect() needs "disconnected".
+            transport_stop_stub:invokes(function()
+                if captured_on_state_change then
+                    captured_on_state_change("disconnected")
+                end
+            end)
+
+            -- A fresh start() reconnects and answers the new initialize.
+            transport_start_stub:reset()
+            transport_start_stub:invokes(function()
+                if captured_on_state_change then
+                    captured_on_state_change("connected")
+                end
+            end)
+            transport_send_stub:reset()
+            transport_send_stub:invokes(function(_self, data)
+                local decoded = vim.json.decode(data)
+                if decoded.method == "initialize" and captured_on_message then
+                    captured_on_message({
+                        jsonrpc = "2.0",
+                        id = decoded.id,
+                        result = {
+                            protocolVersion = 1,
+                            agentCapabilities = LOAD_CAPS,
+                            agentInfo = { name = "test" },
+                        },
+                    })
+                end
+            end)
+
+            client:reconnect()
+
+            assert.spy(transport_stop_stub).was.called(1)
+            assert.spy(transport_start_stub).was.called(1)
+            assert.equal("ready", client.state)
+        end)
+
+        it(
+            "rejects in-flight requests when it tears the connection down",
+            function()
+                local client = create_ready_client(LOAD_CAPS)
+
+                --- @type agentic.acp.ACPError|nil
+                local prompt_err
+                client:send_prompt("sess-1", {}, function(_result, err)
+                    prompt_err = err
+                end)
+
+                -- stop() reports the drop, which must drain pending callbacks.
+                transport_stop_stub:invokes(function()
+                    if captured_on_state_change then
+                        captured_on_state_change("disconnected")
+                    end
+                end)
+                transport_start_stub:reset()
+                transport_start_stub:invokes(function() end)
+
+                client:reconnect()
+
+                assert.is_not_nil(prompt_err)
+            end
+        )
+    end)
 end)

lua/agentic/acp/acp_transport.test.lua

@@ -101,6 +101,74 @@ describe("ACPTransport process lifecycle", function()
     )
 end)
 
+describe("ACPTransport reconnect-in-place", function()
+    local child
+
+    before_each(function()
+        child = MiniTest.new_child_neovim()
+        child.restart({ "-i", "NONE", "-u", "NONE" })
+        child.lua("vim.opt.rtp:prepend(...)", { vim.fn.getcwd() })
+    end)
+
+    after_each(function()
+        child.stop()
+    end)
+
+    it(
+        "can stop and start the same transport, yielding a fresh live child",
+        function()
+            -- The reconnect feature reuses one transport object: stop() kills the
+            -- child and start() spawns a new one. stop() closes the process
+            -- handle, which cancels the dead child's exit callback, so the killed
+            -- child can never disturb the connection that replaced it.
+            local result = child.lua([[
+                local Transport = require("agentic.acp.acp_transport")
+                _G.states = {}
+                _G.reconnects = 0
+                _G.transport = Transport.create_stdio_transport({
+                    command = "/bin/cat",
+                }, {
+                    on_state_change = function(s)
+                        table.insert(_G.states, s)
+                    end,
+                    on_message = function() end,
+                    on_reconnect = function()
+                        _G.reconnects = _G.reconnects + 1
+                    end,
+                })
+
+                _G.transport:start()           -- child A
+                local pid_a = _G.transport.pid
+                _G.transport:stop()            -- kill A
+                _G.transport:start()           -- child B, same transport object
+                local pid_b = _G.transport.pid
+
+                -- Let any stale callback from A fire before we assert.
+                vim.wait(800)
+
+                local function alive(pid)
+                    vim.fn.system({ "kill", "-0", tostring(pid) })
+                    return vim.v.shell_error == 0
+                end
+
+                return {
+                    final_state = _G.states[#_G.states],
+                    reconnects = _G.reconnects,
+                    different_pid = pid_a ~= pid_b,
+                    b_alive = alive(pid_b),
+                }
+            ]])
+
+            assert.is_true(result.different_pid)
+            assert.equal("connected", result.final_state)
+            assert.equal(0, result.reconnects)
+            assert.is_true(result.b_alive)
+
+            child.lua([[ _G.transport:stop() ]])
+        end
+    )
+end)
+
 describe("ACPTransport.decode_line", function()
     local Transport = require("agentic.acp.acp_transport")
 

lua/agentic/init.lua

@@ -315,6 +315,15 @@ function Agentic.restore_session()
     end)
 end
 
+--- Recover from an unresponsive agent: respawn the agent process and reload the
+--- current session in place, without quitting Neovim. Use when the agent stops
+--- responding (e.g. after the machine resumes from suspend).
+function Agentic.reconnect()
+    SessionRegistry.get_session_for_tab_page(nil, function(session)
+        session:reconnect()
+    end)
+end
+
 --- Restore a session by its ID.
 --- @param session_id string
 function Agentic.restore_session_by_id(session_id)

lua/agentic/session_manager.lua

@@ -1383,6 +1383,36 @@ function SessionManager:destroy()
     end
 end
 
+--- Recover from an unresponsive agent without quitting Neovim: kill and
+--- respawn the agent process, then reload the current session so the
+--- conversation continues. This is the in-place equivalent of quitting Neovim
+--- and restoring the session, the only recovery available when the child is
+--- hung (e.g. after the machine resumes from suspend with a dead connection).
+---
+--- Note: the agent process is shared per provider, so this also resets other
+--- tabs' sessions on the same provider; they re-establish on their next use.
+function SessionManager:reconnect()
+    local session_id = self.session_id
+
+    -- Reset the local UI immediately. The respawn also drains the dead request
+    -- callbacks, but don't make the user wait for that to see the spinner stop.
+    self.is_generating = false
+    self.status_animation:stop()
+
+    Logger.notify("Reconnecting to agent…", vim.log.levels.INFO)
+
+    self.agent:reconnect()
+
+    self.agent:when_ready(function()
+        local caps = self.agent.agent_capabilities
+        if session_id and caps and caps.loadSession then
+            self:load_acp_session(session_id)
+        else
+            self:new_session()
+        end
+    end)
+end
+
 --- Load an existing ACP session by ID, subscribing to its updates
 --- @param session_id string
 --- @param title string|nil

lua/agentic/session_manager.test.lua

@@ -1,4 +1,4 @@
---- @diagnostic disable: invisible, missing-fields, assign-type-mismatch, cast-local-type, param-type-mismatch
+--- @diagnostic disable: invisible, missing-fields, assign-type-mismatch, cast-local-type, param-type-mismatch, return-type-mismatch
 local assert = require("tests.helpers.assert")
 local spy = require("tests.helpers.spy")
 
@@ -1757,4 +1757,74 @@ describe("agentic.SessionManager", function()
             handlers.on_request_permission(mock_request, mock_callback)
         end)
     end)
+
+    describe("reconnect", function()
+        --- @type TestStub
+        local notify_stub
+
+        before_each(function()
+            notify_stub = spy.stub(Logger, "notify")
+        end)
+
+        after_each(function()
+            notify_stub:revert()
+        end)
+
+        --- @param overrides table
+        --- @return agentic.SessionManager session, table calls
+        local function make_session(overrides)
+            local calls =
+                { reconnected = false, loaded_with = nil, new = false }
+            local session = {
+                session_id = overrides.session_id,
+                is_generating = true,
+                status_animation = { stop = function() end },
+                agent = {
+                    reconnect = function()
+                        calls.reconnected = true
+                    end,
+                    -- Fire the ready callback synchronously.
+                    when_ready = function(_self, cb)
+                        cb()
+                    end,
+                    agent_capabilities = overrides.caps,
+                },
+                reconnect = SessionManager.reconnect,
+                load_acp_session = function(_self, id)
+                    calls.loaded_with = id
+                end,
+                new_session = function()
+                    calls.new = true
+                end,
+            } --[[@as agentic.SessionManager]]
+            return session, calls
+        end
+
+        it("respawns the agent and reloads the current session", function()
+            local session, calls = make_session({
+                session_id = "sess-1",
+                caps = { loadSession = true },
+            })
+
+            session:reconnect()
+
+            assert.is_true(calls.reconnected)
+            assert.is_false(session.is_generating)
+            assert.equal("sess-1", calls.loaded_with)
+            assert.is_false(calls.new)
+        end)
+
+        it("starts a fresh session when there is none to reload", function()
+            local session, calls = make_session({
+                session_id = nil,
+                caps = { loadSession = true },
+            })
+
+            session:reconnect()
+
+            assert.is_true(calls.reconnected)
+            assert.is_nil(calls.loaded_with)
+            assert.is_true(calls.new)
+        end)
+    end)
 end)