Report a stuck workdir lock as a clear error instead of an unhandled rejection

close() on the agent package releases its workdir lock only after
reactor.abort()/sendQueue.drain() and the shutdown-complete race finish. A
throw partway through (most likely right when an operator interrupts
mid-inference, exactly when those paths are stressed) leaves the lock held
forever in-process: the agent is already marked closed, so retrying close()
is a silent no-op that can never release it. The next buildAgent() for that
workdir then throws AgentContextLockError, and reloadIfIdle's rebuild had no
try/catch around it, so the throw escaped as an unhandled rejection and
crashed the process.

Route every rebuild site (interrupt, reload, session rotation) through a
shared close-then-check helper: a failed close now short-circuits the
rebuild instead of attempting a second, doomed acquisition, and the failure
surfaces as a plain-language caught error.

Author: TheGreatAxios

CHANGELOG.md

@@ -29,6 +29,15 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
   the subtree-scoping rule for those is written and tested but not yet wired to
   a live call site. `task()` is unchanged and still the only spawn verb.
 
+### Fixed
+
+- **Interrupting a turn no longer risks a startup crash.** If an interrupt hit
+  the agent mid-teardown, a failed close could leave its in-process workdir
+  lock stuck held, and the immediate rebuild threw "an agent is already open"
+  as an unhandled rejection. A failed close now short-circuits the rebuild
+  with a clear, catchable error instead of retrying a doomed second
+  acquisition.
+
 ## [0.2.107] - 2026-08-24
 
 ### Agent

src/tui/runner.ts

@@ -6,6 +6,7 @@ import {
   defineTool,
   createDirectorRegistry,
   defineDirector,
+  AgentContextLockError,
   type Agent,
 } from "@intx/agent";
 import { noopAuditStore, permissiveAuthorize } from "@intx/agent/testing";
@@ -283,6 +284,42 @@ export function resumeTranscriptLoadErrorBlock(err: unknown): {
   return { type: "error", message: `Could not load prior session transcript: ${message}` };
 }
 
+// The agent package releases its workdir lock at the very end of close(),
+// after reactor.abort()/sendQueue.drain() and the shutdown-complete race have
+// all run. If any of that throws (most likely right when an operator
+// interrupts mid-inference, which is exactly when those paths are under
+// stress), the lock is never released — and because the agent is already
+// marked closed internally, retrying close() is a silent no-op that can
+// never release it either. Every rebuild site must treat that as fatal for
+// the current rebuild instead of calling buildAgent() again: a second
+// createAgent() for the same workdir is then guaranteed to throw
+// AgentContextLockError for a lock nothing will ever free, which is the
+// "agent already open" crash.
+export async function closeAgentForRebuild(agent: Agent, context: string): Promise<boolean> {
+  try {
+    await agent.close();
+    return true;
+  } catch (err) {
+    tuiLogger.debug(`agent.close during ${context} teardown failed: {error}`, {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return false;
+  }
+}
+
+// Every rebuild site funnels its failure (a lock left held by a failed
+// close, or any other buildAgent failure) through here so it surfaces as a
+// plain-language, caught error rather than an unhandled rejection.
+export function agentRebuildFailure(err: unknown): Error {
+  return err instanceof AgentContextLockError
+    ? new Error(
+        "Could not start a new agent: the previous one did not shut down cleanly. Restart Corbits to continue.",
+      )
+    : err instanceof Error
+      ? err
+      : new Error(String(err));
+}
+
 export interface ResumeSeed {
   turnsUsed: number;
   mcpServers: ConnectedMcpServer[];
@@ -1646,21 +1683,25 @@ export async function runTUI(initialConfig: Config): Promise<number> {
       if (!pendingReload || inFlight > 0) return;
       pendingReload = false;
       void enqueueOp(async () => {
-        const old = currentAgent;
-        await old.close().catch((err: unknown) => {
-          tuiLogger.debug("agent.close during reload teardown failed: {error}", {
-            error: err instanceof Error ? err.message : String(err),
-          });
-        });
-        await streamPromise.catch((err: unknown) => {
-          tuiLogger.debug("stream drain during reload teardown failed: {error}", {
-            error: err instanceof Error ? err.message : String(err),
+        try {
+          const old = currentAgent;
+          const closedCleanly = await closeAgentForRebuild(old, "reload");
+          await streamPromise.catch((err: unknown) => {
+            tuiLogger.debug("stream drain during reload teardown failed: {error}", {
+              error: err instanceof Error ? err.message : String(err),
+            });
           });
-        });
-        currentAgent = await buildAgent();
-        streamPromise = consumeStream(currentAgent.stream(), streamSink);
-        // The rebuild made a fresh director; re-attach the active workflow.
-        workflowController.reattach();
+          if (!closedCleanly) {
+            throw new AgentContextLockError(workdir);
+          }
+          currentAgent = await buildAgent();
+          streamPromise = consumeStream(currentAgent.stream(), streamSink);
+          // The rebuild made a fresh director; re-attach the active workflow.
+          workflowController.reattach();
+        } catch (err) {
+          recordRunError(err);
+          fatalBuildError = agentRebuildFailure(err);
+        }
       });
     };
 
@@ -1812,24 +1853,23 @@ export async function runTUI(initialConfig: Config): Promise<number> {
           // and salvages the buffer before that teardown, so it is never lost
           // or misattributed to the rebuilt agent's next cycle.
           await cycleRecorder.dispose("interrupted");
-          await currentAgent.close().catch((err: unknown) => {
-            tuiLogger.debug("agent.close during interrupt teardown failed: {error}", {
-              error: err instanceof Error ? err.message : String(err),
-            });
-          });
+          const closedCleanly = await closeAgentForRebuild(currentAgent, "interrupt");
           await streamPromise.catch((err: unknown) => {
             tuiLogger.debug("stream drain during interrupt teardown failed: {error}", {
               error: err instanceof Error ? err.message : String(err),
             });
           });
+          if (!closedCleanly) {
+            throw new AgentContextLockError(workdir);
+          }
           currentAgent = await buildAgent();
           cycleRecorder.reset();
           streamPromise = consumeStream(currentAgent.stream(), streamSink);
           workflowController.reattach();
           fatalBuildError = null;
         } catch (err) {
           recordRunError(err);
-          fatalBuildError = err instanceof Error ? err : new Error(String(err));
+          fatalBuildError = agentRebuildFailure(err);
         }
       });
     };

tests/unit/tui/runner.test.ts

@@ -1,6 +1,9 @@
 import { test, expect } from "bun:test";
 import { EventEmitter } from "node:events";
+import { AgentContextLockError, type Agent } from "@intx/agent";
 import {
+  agentRebuildFailure,
+  closeAgentForRebuild,
   createTUIEventEmitter,
   getTUIRunSummaryStatus,
   loadLocalSettingsWriteBase,
@@ -97,3 +100,63 @@ test("rotation resets run-sink so a new session starts from a clean state", () =
   expect(runSink.getStatus()).toBe("done");
   expect(collectorAfterReset.getTurns()).toHaveLength(0);
 });
+
+// CL-5753: an interrupt can hit close() while reactor.abort()/sendQueue.drain()
+// are mid-teardown, throwing before @intx/agent's close() ever reaches
+// lock.release(). Once that happens the agent is already marked closed, so a
+// retried close() is a silent no-op that can never free the lock either — the
+// workdir's lock is stuck held for the rest of the process. The next
+// buildAgent() for that same workdir is then guaranteed to throw
+// AgentContextLockError ("an agent is already open for workdir: ..."), which
+// is the crash from the ticket. These tests cover the two functions the
+// runner now routes every rebuild through so that failure is reported in
+// plain language rather than escaping as an unhandled rejection.
+function stubAgent(closeImpl: () => Promise<void>): Agent {
+  return { close: closeImpl } as unknown as Agent;
+}
+
+test("closeAgentForRebuild reports a failed close without throwing", async () => {
+  const agent = stubAgent(() => Promise.reject(new AgentContextLockError("/tmp/workdir")));
+  const closedCleanly = await closeAgentForRebuild(agent, "interrupt");
+  expect(closedCleanly).toBe(false);
+});
+
+test("closeAgentForRebuild reports success when close() resolves", async () => {
+  const agent = stubAgent(() => Promise.resolve());
+  const closedCleanly = await closeAgentForRebuild(agent, "interrupt");
+  expect(closedCleanly).toBe(true);
+});
+
+test("agentRebuildFailure turns a stale-lock AgentContextLockError into a plain-language message", () => {
+  // Simulates the second acquisition throwing after a failed close left the
+  // lock held: buildAgent() surfaces AgentContextLockError, which must not
+  // reach the caller as a raw stack trace.
+  const err = agentRebuildFailure(new AgentContextLockError("/tmp/workdir"));
+  expect(err.message).not.toContain("already open");
+  expect(err.message).toMatch(/restart/i);
+});
+
+test("agentRebuildFailure passes other errors through unchanged", () => {
+  const original = new Error("network unreachable");
+  expect(agentRebuildFailure(original)).toBe(original);
+});
+
+test("a failed close followed by a lock error never surfaces as a raw AgentContextLockError", async () => {
+  // End-to-end shape of the fix: close() throws (lock leaked in-process),
+  // the rebuild site short-circuits instead of calling buildAgent() again,
+  // and the resulting error is the plain-language one — never the raw
+  // AgentContextLockError a bare `throw` would have produced.
+  const agent = stubAgent(() => Promise.reject(new AgentContextLockError("/tmp/workdir")));
+  let rebuildError: Error | null = null;
+  try {
+    const closedCleanly = await closeAgentForRebuild(agent, "interrupt");
+    if (!closedCleanly) {
+      throw new AgentContextLockError("/tmp/workdir");
+    }
+  } catch (err) {
+    rebuildError = agentRebuildFailure(err);
+  }
+  expect(rebuildError).not.toBeNull();
+  expect(rebuildError).not.toBeInstanceOf(AgentContextLockError);
+  expect(rebuildError!.message).toMatch(/restart/i);
+});