Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix: bind the focus restore to the canvas on screen, and leave its guard armed
Bas Milius72157c6d0665
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 328b47b38..fa40d3108 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -7282,12 +7282,20 @@ export function Canvas() {const onWindowFocus = () => {if (timer) clearTimeout(timer)timer = setTimeout(() => {+ // Only the nodes we can prove belong to the canvas on screen: `nodesRef` and+ // `activeProjectId` do not turn over in one commit, and an id we cannot place must not+ // become a request that waits for its project to come back.+ const activeProjectId = useProjects.getState().activeProjectId+ const liveIds = new Set(+ nodesProjectIdRef.current === activeProjectId ? nodesRef.current.map((n) => n.id) : []+ )const target = nodeToRefocus({lastNodeId: useTerminalFocus.getState().lastNodeId,activeElement: document.activeElement as unknown as ContextElement | null,openDialogs: openDialogCount(),- boardOpen: isKanbanOpen(useProjects.getState().activeProjectId),- settingsOpen: settingsOpenRef.current+ boardOpen: isKanbanOpen(activeProjectId),+ settingsOpen: settingsOpenRef.current,+ liveIds})if (target) {useTerminalFocus.getState().request(target, { ack: false })diff --git a/src/renderer/lib/focusRestore.test.ts b/src/renderer/lib/focusRestore.test.tsindex 258ab9d6b..f8083b656 100644--- a/src/renderer/lib/focusRestore.test.ts+++ b/src/renderer/lib/focusRestore.test.ts@@ -14,6 +14,7 @@ const state = (over: Partial<FocusRestoreState> = {}): FocusRestoreState => ({openDialogs: 0,boardOpen: false,settingsOpen: false,+ liveIds: new Set(['term-1']),...over})@@ -60,4 +61,22 @@ describe('nodeToRefocus', () => {it('restores when nothing at all is focused', () => {expect(nodeToRefocus(state({ activeElement: null }))).toBe('term-1')})++ it('refuses a remembered node that belongs to another project', () => {+ // `lastNodeId` survives a project switch on purpose, and a request for an unmounted node is+ // not dropped: it stays latent and fires when that node next mounts. Leaving project A with a+ // terminal focused, switching to B and Cmd+Tabbing back would otherwise park a request that+ // takes the keyboard on the next switch back to A, minutes after the activation.+ expect(nodeToRefocus(state({ liveIds: new Set(['other-1', 'other-2']) }))).toBeNull()+ })++ it('refuses when the live nodes cannot be resolved at all', () => {+ // Empty means "we do not know which project's nodes we are holding", not "the canvas is+ // empty": the node array and the active project id do not turn over in one commit.+ expect(nodeToRefocus(state({ liveIds: new Set() }))).toBeNull()+ })++ it('restores a node that is on the canvas alongside others', () => {+ expect(nodeToRefocus(state({ liveIds: new Set(['other-1', 'term-1']) }))).toBe('term-1')+ })})diff --git a/src/renderer/lib/focusRestore.ts b/src/renderer/lib/focusRestore.tsindex 10b44ae93..faaa1fca0 100644--- a/src/renderer/lib/focusRestore.ts+++ b/src/renderer/lib/focusRestore.ts@@ -30,6 +30,13 @@ export interface FocusRestoreState {boardOpen: boolean/** The settings page is up. Also outside the dialog stack, for the same reason as `boardOpen`. */settingsOpen: boolean+ /**+ * The nodes of the project currently on screen, by id.+ *+ * Empty means "we cannot tell which project's nodes we are holding", which refuses rather than+ * guesses: `nodesRef` is only trustworthy while its epoch tag still matches the active project.+ */+ liveIds: ReadonlySet<string>}/**@@ -49,12 +56,21 @@ export interface FocusRestoreState {* user having left the app from a text field; it is not ours to override.* - **A terminal already has focus**: the pointer never left, so nothing was lost. Restoring* would be a no-op at best and could move focus to a DIFFERENT node at worst.+ * - **The remembered node is not on the canvas we are looking at**: `lastNodeId` deliberately+ * survives a project switch, and a request for an unmounted node is not dropped, it stays+ * LATENT until that node mounts (`TerminalNode`'s `lastFocusReqRef` starts at 0, and only the+ * consumer clears the store). So restoring a node that belongs to another project queues a+ * focus that fires minutes later, the next time the user switches back to it. Refusing here is+ * what keeps the restore bound to the canvas the activation actually returned to.*/export function nodeToRefocus(state: FocusRestoreState): string | null {- const { lastNodeId, activeElement, openDialogs, boardOpen, settingsOpen } = state+ const { lastNodeId, activeElement, openDialogs, boardOpen, settingsOpen, liveIds } = stateif (!lastNodeId || openDialogs > 0) {return null}+ if (!liveIds.has(lastNodeId)) {+ return null+ }if (boardOpen || settingsOpen) {return null}diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsxindex fc5626d99..a975879f3 100644--- a/src/renderer/nodes/TerminalNode.tsx+++ b/src/renderer/nodes/TerminalNode.tsx@@ -4334,21 +4334,29 @@ export function TerminalNode({// ---- hover guard: dwell before entering the terminal ----/**- * Take the keyboard: leave the guard, focus xterm, and report the node active.+ * Take the keyboard: focus xterm, leave the guard, and report the node active.** Split out of `onBodyEnter` so a deliberate CLICK can run it with no delay — see `onGuardUp`.*- * `ack` (default true) also marks the node's finish read. Every gesture that reaches here aims- * at THIS node — a dwell, a click, a sidebar or notification jump — so the read is real. The one- * caller that passes false is the window-activation restore, which nobody aimed at anything.+ * `ack` (default true) says a human AIMED at this node, and two things follow from it. It marks+ * the node's finish read, which reaches past this machine (`clearUnread` → `ackDone` → the notch+ * capsule and the paired phone). And it drops the hover guard, which is a POINTER contract: the+ * guard makes a quick scroll pan the canvas until the dwell has elapsed, so a restore nobody+ * pointed at must leave it armed, or the next pointer entry silently skips its dwell and the+ * first wheel scrolls tmux instead. Keyboard focus does not need the guard down: it is an+ * overlay, and a programmatic `focus()` is not hit-tested.+ *+ * Every gesture that reaches here aims at THIS node: a dwell, a click, a sidebar or notification+ * jump. The one caller that passes false is the window-activation restore.*/const enterNow = (opts?: { ack?: boolean }) => {+ const aimed = opts?.ack !== falseif (dwellRef.current) clearTimeout(dwellRef.current)- setArmed(false)+ if (aimed) setArmed(false)termRef.current?.focus()useTerminalFocus.getState().remember(id)useAgentStatus.getState().setActive(id, true)- if (opts?.ack !== false) {+ if (aimed) {useAgentStatus.getState().clearUnread(id)}presence.reportFocus(id)diff --git a/src/renderer/state/terminalFocus.ts b/src/renderer/state/terminalFocus.tsindex e667478a1..560bff320 100644--- a/src/renderer/state/terminalFocus.ts+++ b/src/renderer/state/terminalFocus.ts@@ -35,11 +35,17 @@ export const useTerminalFocus = create<{* that is gone or unmounted simply misses the request, the same fail-open as `request`.** It therefore also survives a PROJECT SWITCH, so the remembered node can belong to another- * project. That fails open today because the request is consumed by a mounted `TerminalNode`- * and the node of an inactive project is unmounted. Load-bearing: a change that starts routing- * a focus request across projects (switching to the node's project first, as `focusNodeById`- * does) has to clear or qualify this, or a window activation would yank the user out of the- * project they are looking at.+ * project. That does NOT fail open: a request for an unmounted node stays LATENT rather than+ * being dropped. `nodeId` is cleared only by the consumer, and `TerminalNode`'s `lastFocusReqRef`+ * starts at 0, so the node consumes the request the moment it mounts. The cross-project+ * `pendingFocusRef` path in `Canvas` relies on exactly that, requesting right after a project+ * loads and before the node exists.+ *+ * So the restore, not this field, is where the staleness is refused: `nodeToRefocus` takes the+ * live nodes of the project on screen and returns null for an id that is not among them. Without+ * it, leaving project A with a terminal focused, switching to B and Cmd+Tabbing back would park a+ * request that fires on the next switch to A, handing a node the keyboard minutes after the+ * activation nobody aimed at it.*/lastNodeId: string | null/**