Skip to content

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.

feat(kanban): agent session actions on cards and the card modal (#1185)

Mina Sameh433271f74c73
diff --git a/CLAUDE.md b/CLAUDE.md
index 2f1a6fb4e..d52edec82 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10016,7 +10016,15 @@ hooks never fired and every agent message to it expired as `targetStatusStale`.
carries the node's actions (search / dictate / AI-name / comments), accepts file drops
(`terminal/file-drop.ts`), renders browser webviews (`BrowserSurface`), and its cards support
right-click actions + `+ New`. When you touch a node's UI, ask "does the board need this too?"
- and wire it through `KanbanView`/`SessionCard`/`CardModal` in the SAME change. Node menu rows live in ONE builder, `renderer/lib/nodeActionItems.tsx` (canvas menu, sessions sidebar, both boards' card menus via `kanban/cardMenu.tsx`); a card takes only `BOARD_NODE_ACTION_IDS` and writes through `nodeWritesFor(projectId)`, because the Omni board acts on nodes of projects that are not on the canvas. Kanban itself is
+ and wire it through `KanbanView`/`SessionCard`/`CardModal` in the SAME change. Node menu rows live in ONE builder, `renderer/lib/nodeActionItems.tsx` (canvas menu, sessions sidebar, both boards' card menus via `kanban/cardMenu.tsx`); a card takes only `BOARD_NODE_ACTION_IDS` and writes through `nodeWritesFor(projectId)`, because the Omni board acts on nodes of projects that are not on the canvas.
+ The card modal's ⋯ menu takes `BOARD_MODAL_ACTION_IDS` and closes the modal before any action
+ runs, because restart-and-shell, switch model, account switch and pause-and-end recycle the tmux
+ session its terminal is attached to; a card of a project the canvas does not hold shows these
+ rows disabled with 'This terminal is not attached right now.', and a card with no session row
+ (a plain shell, a non-resumable agent) gets no ⋯ button at all. A node the canvas holds but
+ whose terminal was released while off screen is a different case (`NodeActionCtx.onCanvas`
+ true, `attached` false): Refresh stays enabled, since its respawn is what revives the node,
+ and the session rows say the terminal was released (`RELEASED_HINT`). Kanban itself is
desktop+Server-Edition (pure renderer + `workspace.save`); the iOS board is a separate read/move
mirror (`nodeterm-ios`, `KanbanGrouping`/`ProjectBoardView`).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2f1ef4ef7..2ebb54386 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -166,7 +166,9 @@ picker — goes in `renderer/lib/nodeActionItems.tsx`, never inline in `Canvas.t
menu, the sessions-sidebar row menu and both kanban card menus (through
`components/kanban/cardMenu.tsx`) build from it. Decide in the same change whether a card offers
the new row: a card takes only `BOARD_NODE_ACTION_IDS`, and a row that acts on canvas position goes
-in `BOARD_SPATIAL_ROW_IDS` instead. Remember the board acts on nodes of projects that are NOT on the
+in `BOARD_SPATIAL_ROW_IDS` instead. The card modal's ⋯ menu takes `BOARD_MODAL_ACTION_IDS` through
+its `sessionActions` prop, closes the modal before the action runs, and is absent when the card has
+no session row. Remember the board acts on nodes of projects that are NOT on the
canvas (the Omni board): write through Canvas's `nodeWritesFor(projectId)` (built on
`createNodeWriteRouter`, `lib/nodeWriteRouter.ts`), never a live-canvas callback, and report a failure with a `nodeterm:toast`.
`lib/nodeActionItems.guard.test.ts` fails on a second copy of the rows.
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index e68a5064f..facb19a53 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -132,6 +132,7 @@ import {
type NodeWrites
} from '../lib/nodeWriteRouter'
import {
+ BOARD_MODAL_ACTION_IDS,
BOARD_NODE_ACTION_IDS,
buildNodeActionItems,
offCanvasNodeActionCtx,
@@ -10424,6 +10425,8 @@ export function Canvas() {
nodes: nodesRef.current as CanvasNode[],
sessionSource: session.source,
attached: (nodeId) => !!agentRestartFn(nodeId),
+ // Held by React Flow — true while its terminal is released off screen, unlike `attached`.
+ onCanvas: (nodeId) => nodesRef.current.some((n) => n.id === nodeId),
agentIdOf,
gatewayModels,
gatewayStatus,
@@ -10578,6 +10581,18 @@ export function Canvas() {
(nodeId: string): MenuItem[] => boardNodeActionItems(nodeId, activeProjectId),
[boardNodeActionItems, activeProjectId]
)
+ // The card modal's session rows (restart / switch model / account / pause), for a node of
+ // `projectId`. Refresh is not offered there: the modal's terminal has its own.
+ const boardSessionActionItems = useCallback(
+ (nodeId: string, projectId: string): MenuItem[] =>
+ buildNodeActionItems([nodeId], undefined, nodeActionCtxFor(projectId), { allow: BOARD_MODAL_ACTION_IDS }),
+ [nodeActionCtxFor]
+ )
+ // Stable identity for the memoized per-project board, same reason as above.
+ const activeBoardSessionActionItems = useCallback(
+ (nodeId: string): MenuItem[] => boardSessionActionItems(nodeId, activeProjectId),
+ [boardSessionActionItems, activeProjectId]
+ )
/** "New <agent>" creation entries shared by the pane, sidebar and group context menus.
* `at` is the flow position to create at; with `groupId` the node is parented into that group.
@@ -18938,6 +18953,7 @@ export function Canvas() {
live={globalKanbanLive}
onModalNodeChange={setKanbanModalNode}
nodeActionItems={boardNodeActionItems}
+ sessionActionItems={boardSessionActionItems}
onAiName={aiNameFromKanban}
onSetColor={setCardColor}
onRunQueued={runQueuedFromOmni}
@@ -18956,6 +18972,7 @@ export function Canvas() {
onBrowserNav={browserNavFromKanban}
onSetIcon={setActiveCardIcon}
nodeActionItems={activeBoardNodeActionItems}
+ sessionActionItems={activeBoardSessionActionItems}
onAiName={aiNameFromActiveKanban}
onSetColor={setActiveCardColor}
onRunQueued={runActiveQueuedFromBoard}
diff --git a/src/renderer/canvas/node-action-ctx-for.source.test.ts b/src/renderer/canvas/node-action-ctx-for.source.test.ts
index 5ec91b726..3280751b7 100644
--- a/src/renderer/canvas/node-action-ctx-for.source.test.ts
+++ b/src/renderer/canvas/node-action-ctx-for.source.test.ts
@@ -54,4 +54,20 @@ describe('Canvas nodeActionCtxFor', () => {
'buildNodeActionItems([nodeId], undefined, nodeActionCtxFor(projectId), { allow: BOARD_NODE_ACTION_IDS })'
)
})
+
+ it('card modal session rows are BOARD_MODAL_ACTION_IDS through nodeActionCtxFor, wired to both boards', () => {
+ const start = src.indexOf('const boardSessionActionItems = useCallback(')
+ expect(start).toBeGreaterThan(-1)
+ const decl = src.slice(start, src.indexOf('\n )\n', start))
+ expect(decl).toContain(
+ 'buildNodeActionItems([nodeId], undefined, nodeActionCtxFor(projectId), { allow: BOARD_MODAL_ACTION_IDS })'
+ )
+ // The per-project board is bound to the active project with a stable identity.
+ expect(src).toMatch(
+ /const activeBoardSessionActionItems = useCallback\(\n\s+\(nodeId: string\): MenuItem\[\] => boardSessionActionItems\(nodeId, activeProjectId\),/
+ )
+ // The Omni board asks per lane; the per-project board gets the active binding.
+ expect(src).toContain('sessionActionItems={boardSessionActionItems}')
+ expect(src).toContain('sessionActionItems={activeBoardSessionActionItems}')
+ })
})
diff --git a/src/renderer/canvas/node-menu-golden.source.test.ts b/src/renderer/canvas/node-menu-golden.source.test.ts
index 960fcda5b..2d914693e 100644
--- a/src/renderer/canvas/node-menu-golden.source.test.ts
+++ b/src/renderer/canvas/node-menu-golden.source.test.ts
@@ -81,7 +81,8 @@ const GOLDEN_STRINGS = [
'This session is busy — restart it once its turn (or permission prompt) is done.',
'This session is busy — switch it once its turn (or permission prompt) is done.',
'This session is busy — try again once its turn (or permission prompt) is done.',
- 'This terminal is not attached right now.'
+ 'This terminal is not attached right now.',
+ 'This terminal was released while off screen — refresh the terminal or bring it into view on the canvas.'
]
const GOLDEN_TEMPLATES = [
diff --git a/src/renderer/components/kanban/CardModal.actions.test.tsx b/src/renderer/components/kanban/CardModal.actions.test.tsx
index ee9736de0..789f71453 100644
--- a/src/renderer/components/kanban/CardModal.actions.test.tsx
+++ b/src/renderer/components/kanban/CardModal.actions.test.tsx
@@ -10,6 +10,7 @@ import { resetDialogStack } from '../dialog-stack'
import { useSessionNaming } from '../../state/sessionNaming'
import { CardModal } from './CardModal'
import type { KanbanSession } from './KanbanView'
+import type { MenuItem } from '../ContextMenu'
const generateName = vi.fn()
vi.mock('../../session/session', () => ({
@@ -109,6 +110,114 @@ describe('CardModal — node actions in the header', () => {
})
})
+describe('CardModal — session actions menu', () => {
+ const actionsButton = (): HTMLButtonElement | null =>
+ document.body.querySelector<HTMLButtonElement>('[data-action="session-actions"]')
+ const row = (label: string): HTMLElement | undefined =>
+ Array.from(document.querySelectorAll<HTMLElement>('.ctx-item')).find((e) => e.textContent?.includes(label))
+
+ it('shows a session actions button only when sessionActions is given, for terminal cards', () => {
+ render()
+ expect(actionsButton()).toBeNull()
+ render({ sessionActions: () => [{ label: 'Restart agent', onClick: vi.fn() }] })
+ expect(actionsButton()).not.toBeNull()
+ render({
+ sessionActions: () => [{ label: 'Restart agent', onClick: vi.fn() }],
+ session: { ...session, kind: 'sticky' }
+ })
+ expect(actionsButton()).toBeNull()
+ })
+
+ it('no button when the card has no session rows (empty or separator-only)', () => {
+ render({ sessionActions: () => [] })
+ expect(actionsButton()).toBeNull()
+ render({ sessionActions: () => [{ type: 'separator' }, { type: 'separator' }] })
+ expect(actionsButton()).toBeNull()
+ render({ sessionActions: () => [{ type: 'separator' }, { label: 'Pause', onClick: vi.fn() }] })
+ expect(actionsButton()).not.toBeNull()
+ })
+
+ it('choosing a row closes the modal first and then runs the action once', () => {
+ const order: string[] = []
+ render({
+ onClose: () => order.push('close'),
+ sessionActions: () => [{ label: 'Restart agent', onClick: () => order.push('run') }]
+ })
+ act(() => actionsButton()!.click())
+ act(() => row('Restart agent')!.click())
+ expect(order).toEqual(['close', 'run'])
+ })
+
+ it('a disabled row neither closes nor runs', () => {
+ const onClose = vi.fn()
+ const run = vi.fn()
+ render({
+ onClose,
+ sessionActions: () => [{ label: 'Pause', disabled: true, hint: 'busy', onClick: run }]
+ })
+ act(() => actionsButton()!.click())
+ act(() => row('Pause')!.click())
+ expect(onClose).not.toHaveBeenCalled()
+ expect(run).not.toHaveBeenCalled()
+ })
+
+ it('builds the rows fresh on each open', () => {
+ const sessionActions = vi.fn(() => [{ label: 'Restart agent', onClick: vi.fn() }])
+ render({ sessionActions })
+ act(() => actionsButton()!.click())
+ const afterFirst = sessionActions.mock.calls.length
+ expect(afterFirst).toBeGreaterThan(0)
+ // Dismiss by clicking away (the menu's backdrop).
+ act(() => document.querySelector<HTMLElement>('.ctx-backdrop')!.click())
+ expect(row('Restart agent')).toBeUndefined()
+ act(() => actionsButton()!.click())
+ expect(sessionActions.mock.calls.length).toBeGreaterThan(afterFirst)
+ })
+
+ it('click-away and Esc dismiss the menu without closing the modal or running anything', () => {
+ const onClose = vi.fn()
+ const run = vi.fn()
+ render({ onClose, sessionActions: () => [{ label: 'Restart agent', onClick: run }] })
+ act(() => actionsButton()!.click())
+ act(() => document.querySelector<HTMLElement>('.ctx-backdrop')!.click())
+ expect(row('Restart agent')).toBeUndefined()
+ act(() => actionsButton()!.click())
+ act(() => {
+ window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+ })
+ expect(row('Restart agent')).toBeUndefined()
+ expect(onClose).not.toHaveBeenCalled()
+ expect(run).not.toHaveBeenCalled()
+ })
+
+ it('a menu opened for one card is gone after the modal steps to another card', () => {
+ const run = vi.fn()
+ render({ sessionActions: () => [{ label: 'Restart agent', onClick: run }] })
+ act(() => actionsButton()!.click())
+ expect(row('Restart agent')).toBeDefined()
+ render({
+ sessionActions: () => [{ label: 'Restart agent', onClick: run }],
+ session: { ...session, id: 'n2', title: 'Other' }
+ })
+ expect(row('Restart agent')).toBeUndefined()
+ })
+
+ it('menus closed by a J/K step do not reappear when the modal steps back', () => {
+ const sessionActions = (): MenuItem[] => [{ label: 'Restart agent', onClick: vi.fn() }]
+ render({ sessionActions, onSetColor: vi.fn() })
+ act(() => actionsButton()!.click())
+ expect(row('Restart agent')).toBeDefined()
+ render({ sessionActions, onSetColor: vi.fn(), session: { ...session, id: 'n2', title: 'Other' } })
+ render({ sessionActions, onSetColor: vi.fn() })
+ expect(row('Restart agent')).toBeUndefined()
+ act(() => button('Color')!.click())
+ expect(document.body.querySelector('button[aria-label="Blue"]')).not.toBeNull()
+ render({ sessionActions, onSetColor: vi.fn(), session: { ...session, id: 'n2', title: 'Other' } })
+ render({ sessionActions, onSetColor: vi.fn() })
+ expect(document.body.querySelector('button[aria-label="Blue"]')).toBeNull()
+ })
+})
+
describe('CardModal — review fixes (header Color, ✦, ⌘M first paint)', () => {
const blue = (): HTMLButtonElement | null =>
document.body.querySelector<HTMLButtonElement>('button[aria-label="Blue"]')
diff --git a/src/renderer/components/kanban/CardModal.tsx b/src/renderer/components/kanban/CardModal.tsx
index ae73470ac..f7d609a7d 100644
--- a/src/renderer/components/kanban/CardModal.tsx
+++ b/src/renderer/components/kanban/CardModal.tsx
@@ -10,12 +10,14 @@ import {
IconMarkdown,
IconMaximize,
IconMic,
+ IconMore,
IconRestoreSize,
IconSearch,
IconSmiley,
IconTrash
} from '../icons'
-import { ContextMenu } from '../ContextMenu'
+import { ContextMenu, type MenuItem } from '../ContextMenu'
+import { closeThen } from './closeThen'
import { NodeIconView } from '../NodeIcon'
import { nodeIconDialog } from '../NodeIconPicker'
import { applyIconChoice } from '../../lib/nodeIconChoice'
@@ -137,6 +139,10 @@ interface CardModalProps {
* row uses, so the header ✦ and the menu row cannot disagree: it reports a failure, asks the
* card's OWN core, and drives the shared per-node naming spinner. */
onAiName?: () => void
+ /** Session-management rows for the header ⋯ button (Canvas: `BOARD_MODAL_ACTION_IDS`). Called
+ * each time the menu renders, so the rows are fresh; every runnable row closes the modal before
+ * it acts (`closeThen`). Terminal cards only. Absent = no button. */
+ sessionActions?: () => MenuItem[]
/** ▶ on the header's QUEUED chip (the card's held launch). Absent = chip without ▶. */
onRunQueued?: () => void
}
@@ -145,7 +151,7 @@ interface CardModalProps {
* canvas under it) stay mounted. Terminal cards carry the node header's actions too:
* search / dictate / AI-name / the ⌘M view — ChatPanel or the output markdown, the same face the
* canvas node shows (the node itself is hidden under the board). */
-export function CardModal({ session, projectId, projectName, projectColor, columnTitle, board, onChangeBoard, onClose, portsProjectId, onOpenCanvas, onRename, onEditSticky, onBrowserNav, onSetIcon, onOpenIssue, mentionables, team, onTravel, initialView, onSetColor, onDelete, onAiName, onRunQueued }: CardModalProps) {
+export function CardModal({ session, projectId, projectName, projectColor, columnTitle, board, onChangeBoard, onClose, portsProjectId, onOpenCanvas, onRename, onEditSticky, onBrowserNav, onSetIcon, onOpenIssue, mentionables, team, onTravel, initialView, onSetColor, onDelete, onAiName, sessionActions, onRunQueued }: CardModalProps) {
const { api, source: coreSource } = useSession()
// The header slot decides "icon or smiley" on the NORMALIZED value, the answer NodeIconView
// itself gives — on the raw one, an invalid stored icon drew an empty, un-muted slot.
@@ -194,11 +200,19 @@ export function CardModal({ session, projectId, projectName, projectColor, colum
// would recolor the card the modal moved TO, not the one the menu was opened for.
const [colorMenu, setColorMenu] = useState<{ x: number; y: number; id: string } | null>(null)
const colorMenuOpen = colorMenu !== null && colorMenu.id === session.id
+ // The header ⋯ session-actions menu, keyed by node id for the same reason as the swatches: rows
+ // opened for one card must never act on the card a J/K step moved to.
+ const [actionsMenu, setActionsMenu] = useState<{ x: number; y: number; id: string } | null>(null)
+ const actionsMenuOpen = actionsMenu !== null && actionsMenu.id === session.id
// Comments & activity panel: OPEN by default in the modal; the header 💬 collapses it. The
// choice is remembered (localStorage) — once collapsed, later cards open collapsed too.
const panelOpen = useCardPanel((s) => s.open)
const togglePanel = useCardPanel((s) => s.toggle)
const isTerminal = session.kind === 'terminal'
+ // Built every render so the rows are always current. A card with no session rows (a plain shell,
+ // an agent we cannot quit and resume) gets NO button: an empty menu would be a dead click.
+ const sessionRows = isTerminal && sessionActions ? sessionActions() : []
+ const hasSessionRows = sessionRows.some((r) => r.type !== 'separator')
const isBrowser = session.kind === 'browser'
// ── The ⌘M view (board parity with the canvas node's markdown / chat face) ─────────────────
@@ -347,6 +361,16 @@ export function CardModal({ session, projectId, projectName, projectColor, colum
useEffect(() => {
colorMenuOpenRef.current = colorMenuOpen
}, [colorMenuOpen])
+ // A J/K step drops both header menus. Keying them by id hides them on the next card, but without
+ // this a step back to the card they were opened for would show them again.
+ useEffect(() => {
+ setColorMenu(null)
+ setActionsMenu(null)
+ }, [session.id])
+ const actionsMenuOpenRef = useRef(false)
+ useEffect(() => {
+ actionsMenuOpenRef.current = actionsMenuOpen
+ }, [actionsMenuOpen])
// Ref mirrors: the capture-phase listener below closes over stale state otherwise.
const editingTitleRef = useRef(false)
useEffect(() => {
@@ -377,6 +401,13 @@ export function CardModal({ session, projectId, projectName, projectColor, colum
setColorMenu(null)
return
}
+ // …and so does the ⋯ session-actions menu.
+ if (actionsMenuOpenRef.current) {
+ e.preventDefault()
+ e.stopPropagation()
+ setActionsMenu(null)
+ return
+ }
// A rename in progress owns Esc first (cancel the edit, not the modal).
if (editingTitleRef.current) {
e.preventDefault()
@@ -633,6 +664,20 @@ export function CardModal({ session, projectId, projectName, projectColor, colum
>
<IconBroadcast />
</button>
+ {hasSessionRows && (
+ <button
+ className="kanban-modal__action"
+ data-action="session-actions"
+ title="Session actions"
+ aria-label="Session actions"
+ onClick={(e) => {
+ const r = e.currentTarget.getBoundingClientRect()
+ setActionsMenu({ x: r.left, y: r.bottom, id: session.id })
+ }}
+ >
+ <IconMore />
+ </button>
+ )}
</>
)}
{onSetColor && (
@@ -693,6 +738,15 @@ export function CardModal({ session, projectId, projectName, projectColor, colum
onClose={() => setColorMenu(null)}
/>
)}
+ {actionsMenu && actionsMenuOpen && hasSessionRows && (
+ <ContextMenu
+ x={actionsMenu.x}
+ y={actionsMenu.y}
+ zIndex={65}
+ items={closeThen(sessionRows, onClose)}
+ onClose={() => setActionsMenu(null)}
+ />
+ )}
<CardMetaBar nodeId={session.id} board={board} onChange={onChangeBoard} />
<CardPullRequests session={session} board={board} onChangeBoard={onChangeBoard} />
<div className="kanban-modal__body">
diff --git a/src/renderer/components/kanban/GlobalKanbanView.tsx b/src/renderer/components/kanban/GlobalKanbanView.tsx
index 963d6ec9f..373efcebc 100644
--- a/src/renderer/components/kanban/GlobalKanbanView.tsx
+++ b/src/renderer/components/kanban/GlobalKanbanView.tsx
@@ -87,6 +87,8 @@ interface SwimlaneProps {
* lane's project: a background lane gets its stored nodes, its own session source and its own
* write router, so nothing acts on the canvas of another project. */
nodeActionItems?: (nodeId: string, projectId: string) => MenuItem[]
+ /** The card modal's ⋯ session rows (BOARD_MODAL_ACTION_IDS), asked for this lane's project. */
+ sessionActionItems?: (nodeId: string, projectId: string) => MenuItem[]
/** "Name with AI" on a card of this lane. */
onAiName?: (projectId: string, nodeId: string) => void
/** Set a card's node color (the card modal's Color button), routed by the lane's project. */
@@ -97,7 +99,7 @@ interface SwimlaneProps {
}
const Swimlane = memo(function Swimlane({
- projectId, projectName, projectIndex, projectColor, board, sessions, ropes, nodes, onChangeBoard, onOpenNode, onCreateNode, onDeleteNode, onRenameNode, onEditSticky, onBrowserNav, onSetIcon, modalNodeId, modalView, onModalChange, liveTeams, highlight, nodeActionItems, onAiName, onSetColor, onRunQueued
+ projectId, projectName, projectIndex, projectColor, board, sessions, ropes, nodes, onChangeBoard, onOpenNode, onCreateNode, onDeleteNode, onRenameNode, onEditSticky, onBrowserNav, onSetIcon, modalNodeId, modalView, onModalChange, liveTeams, highlight, nodeActionItems, sessionActionItems, onAiName, onSetColor, onRunQueued
}: SwimlaneProps) {
const dragRef = useRef<{ kind: 'column'; id: string } | { kind: 'card'; id: string } | null>(null)
const setModalNodeId = useCallback(
@@ -363,6 +365,7 @@ const Swimlane = memo(function Swimlane({
onBrowserNav={(patch) => onBrowserNav(projectId, modalNodeId, patch)}
onSetIcon={(icon) => onSetIcon(projectId, modalNodeId, icon)}
onSetColor={onSetColor ? (color) => onSetColor(projectId, modalNodeId, color) : undefined}
+ sessionActions={sessionActionItems ? () => sessionActionItems(modalNodeId, projectId) : undefined}
onRunQueued={runQueued ? () => runQueued(modalNodeId) : undefined}
onDelete={() => onDeleteNode(projectId, modalNodeId)}
onAiName={onAiName ? () => onAiName(projectId, modalNodeId) : undefined}
@@ -392,6 +395,9 @@ export interface GlobalKanbanViewProps {
/** Canvas's node rows for a card (`boardNodeActionItems`), asked per lane's project.
* Optional: an overview with no canvas behind it offers none. */
nodeActionItems?: (nodeId: string, projectId: string) => MenuItem[]
+ /** Canvas's card-modal ⋯ session rows (`boardSessionActionItems`), asked per lane's project.
+ * Optional: no ⋯ button without it. */
+ sessionActionItems?: (nodeId: string, projectId: string) => MenuItem[]
/** Canvas's "Name with AI" for a card of any lane (`aiNameFromKanban`). Optional. */
onAiName?: (projectId: string, nodeId: string) => void
/** Canvas's color write for a card of any lane (`setCardColor`, routed per project). Optional. */
@@ -405,7 +411,7 @@ export interface GlobalKanbanViewProps {
onModalNodeChange?: (nodeId: string | null) => void
}
-export const GlobalKanbanView = memo(function GlobalKanbanView({ live = null, onModalNodeChange, nodeActionItems, onAiName, onSetColor, onRunQueued }: GlobalKanbanViewProps) {
+export const GlobalKanbanView = memo(function GlobalKanbanView({ live = null, onModalNodeChange, nodeActionItems, sessionActionItems, onAiName, onSetColor, onRunQueued }: GlobalKanbanViewProps) {
// Same rule as the per-project board: the canvas is covered but mounted underneath.
useEffect(() => markCanvasCovered(document.documentElement), [])
const boardStyle = useBoardWallpaperStyle()
@@ -558,6 +564,7 @@ export const GlobalKanbanView = memo(function GlobalKanbanView({ live = null, on
liveTeams={isLive ? live.teams : undefined}
highlight={highlightId === p.id}
nodeActionItems={nodeActionItems}
+ sessionActionItems={sessionActionItems}
onAiName={onAiName}
onSetColor={onSetColor}
onRunQueued={onRunQueued}
diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsx
index 21a86320a..1a2aef40f 100644
--- a/src/renderer/components/kanban/KanbanView.tsx
+++ b/src/renderer/components/kanban/KanbanView.tsx
@@ -140,10 +140,14 @@ export interface KanbanViewProps {
/**
* The node's own rows for its card menu — the SAME builder the canvas node menu and the sessions
* sidebar use (lib/nodeActionItems), narrowed by Canvas to `BOARD_NODE_ACTION_IDS`: stop agent
- * control, color, icon, Share live link…, Switch Claude/Codex account. Optional: a board with no
- * canvas behind it (a test, a future read-only view) shows none.
+ * control, color, icon, refresh terminal, Share live link…, restart, switch model, Switch
+ * Claude/Codex account, pause. Optional: a board with no canvas behind it (a test, a future
+ * read-only view) shows none.
*/
nodeActionItems?: (nodeId: string) => MenuItem[]
+ /** The card modal's ⋯ session rows (same builder, narrowed to `BOARD_MODAL_ACTION_IDS`).
+ * Optional: no ⋯ button without it. */
+ sessionActionItems?: (nodeId: string) => MenuItem[]
/** "Name with AI" on a card (Canvas `aiNameSession`, the sessions sidebar's funnel). Optional. */
onAiName?: (nodeId: string) => void
/** Set a card's node color — the card modal's Color button. Optional: no button without it. */
@@ -249,7 +253,7 @@ function useCanvasCovered(): void {
export const KanbanView = memo(function KanbanView({
board, sessions, onChange, onOpenNode, onCreateNode, onRenameNode, onEditSticky, onDeleteNode,
- onModalNodeChange, onBrowserNav, onSetIcon, nodeActionItems, onAiName, onSetColor, onRunQueued, onAutoMoveFromPulls, issueAgentMenu,
+ onModalNodeChange, onBrowserNav, onSetIcon, nodeActionItems, sessionActionItems, onAiName, onSetColor, onRunQueued, onAutoMoveFromPulls, issueAgentMenu,
issueWorktreeMenu, teams, onIssueMoved
}: KanbanViewProps) {
useCanvasCovered()
@@ -1296,6 +1300,7 @@ export const KanbanView = memo(function KanbanView({
onBrowserNav={(patch) => onBrowserNav(modalNodeId, patch)}
onSetIcon={(icon) => onSetIcon(modalNodeId, icon)}
onSetColor={onSetColor ? (color) => onSetColor(modalNodeId, color) : undefined}
+ sessionActions={sessionActionItems ? () => sessionActionItems(modalNodeId) : undefined}
onRunQueued={onRunQueued ? () => onRunQueued(modalNodeId) : undefined}
onDelete={() => onDeleteNode(modalNodeId)}
onAiName={onAiName ? () => onAiName(modalNodeId) : undefined}
diff --git a/src/renderer/components/kanban/closeThen.test.ts b/src/renderer/components/kanban/closeThen.test.ts
new file mode 100644
index 000000000..d983ef3e1
--- /dev/null
+++ b/src/renderer/components/kanban/closeThen.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { MenuItem } from '../ContextMenu'
+import { closeThen } from './closeThen'
+
+describe('closeThen', () => {
+ it('closes first, then runs the leaf, exactly once', () => {
+ const order: string[] = []
+ const items: MenuItem[] = [{ label: 'Restart agent', onClick: () => order.push('run') }]
+ const [wrapped] = closeThen(items, () => order.push('close')) as Extract<MenuItem, { label: string }>[]
+ ;(wrapped as Extract<MenuItem, { onClick: () => void }>).onClick()
+ expect(order).toEqual(['close', 'run'])
+ })
+
+ it('wraps submenu children and leaves separators and disabled rows alone', () => {
+ const close = vi.fn()
+ const run = vi.fn()
+ const disabledRun = vi.fn()
+ const items: MenuItem[] = [
+ { type: 'separator' },
+ {
+ type: 'submenu',
+ label: 'Restart',
+ children: [
+ { label: 'Restart agent', onClick: run },
+ { label: 'Restart agent and shell', disabled: true, onClick: disabledRun }
+ ]
+ }
+ ]
+ const out = closeThen(items, close)
+ expect(out[0]).toEqual({ type: 'separator' })
+ const kids = (out[1] as Extract<MenuItem, { type: 'submenu' }>).children as Extract<
+ MenuItem,
+ { onClick: () => void }
+ >[]
+ kids[0].onClick()
+ expect(close).toHaveBeenCalledTimes(1)
+ expect(run).toHaveBeenCalledTimes(1)
+ expect(kids[1].onClick).toBe(disabledRun)
+ })
+
+ it('leaves labels and colour strips untouched', () => {
+ const onPick = vi.fn()
+ const items: MenuItem[] = [{ type: 'label', label: 'Session' }, { type: 'colors', onPick }]
+ const out = closeThen(items, vi.fn())
+ expect(out[0]).toBe(items[0])
+ expect(out[1]).toBe(items[1])
+ })
+})
diff --git a/src/renderer/components/kanban/closeThen.ts b/src/renderer/components/kanban/closeThen.ts
new file mode 100644
index 000000000..363256c7e
--- /dev/null
+++ b/src/renderer/components/kanban/closeThen.ts
@@ -0,0 +1,25 @@
+import type { MenuItem } from '../ContextMenu'
+
+/**
+ * Wrap every runnable row so the card modal's `close()` is called BEFORE the action runs.
+ * Restarting the shell, switching model, ending a paused session or moving to another account
+ * recycles the tmux session the modal's terminal is co-attached to, so the modal is asked to go
+ * first (the call order the modal's Delete already uses). This guarantees only call order, not
+ * when React actually unmounts the modal. A disabled row is returned unchanged: clicking it must
+ * neither close the modal nor act.
+ */
+export function closeThen(items: MenuItem[], close: () => void): MenuItem[] {
+ return items.map((it): MenuItem => {
+ if (it.type === 'separator' || it.type === 'colors' || it.type === 'label') return it
+ if (it.type === 'submenu') return { ...it, children: closeThen(it.children, close) }
+ if (it.disabled || !it.onClick) return it
+ const run = it.onClick
+ return {
+ ...it,
+ onClick: () => {
+ close()
+ run()
+ }
+ }
+ })
+}
diff --git a/src/renderer/lib/nodeActionItems.guard.test.ts b/src/renderer/lib/nodeActionItems.guard.test.ts
index d933fec3e..34de81b8c 100644
--- a/src/renderer/lib/nodeActionItems.guard.test.ts
+++ b/src/renderer/lib/nodeActionItems.guard.test.ts
@@ -19,6 +19,19 @@ function sources(dir: string, out: string[] = []): string[] {
return out
}
+/** Every `import … from '…'` statement of a file: the module specifiers and the bound names. */
+function imports(src: string): { specifiers: string[]; names: string[] } {
+ const specifiers: string[] = []
+ const names: string[] = []
+ for (const m of src.matchAll(/^import\s+(type\s+)?([\s\S]*?)\s+from\s+['"]([^'"]+)['"]/gm)) {
+ specifiers.push(m[3])
+ for (const part of m[2].replace(/[{}*]/g, ' ').split(/[\s,]+/)) {
+ if (part && part !== 'type' && part !== 'as') names.push(part)
+ }
+ }
+ return { specifiers, names }
+}
+
/** The source of one `const name = useCallback(…)` up to the next `const` at the same depth. */
function callback(src: string, name: string): string {
const at = src.indexOf(`const ${name} = useCallback(`)
@@ -48,6 +61,20 @@ describe('node actions: one builder for every surface', () => {
expect(callback(canvas, 'boardNodeActionItems')).toContain('{ allow: BOARD_NODE_ACTION_IDS }')
})
+ it('the card modal renders only the rows its sessionActions prop hands it', () => {
+ const modal = imports(read('components/kanban/CardModal.tsx'))
+ for (const name of ['buildNodeActionItems', 'sessionRows', 'restartEligibility']) {
+ expect(modal.names, name).not.toContain(name)
+ }
+ expect(modal.specifiers.filter((s) => /lib\/nodeActionItems$/.test(s))).toEqual([])
+ })
+
+ it('neither board imports the builder directly; Canvas hands them the rows', () => {
+ for (const file of ['components/kanban/KanbanView.tsx', 'components/kanban/GlobalKanbanView.tsx']) {
+ expect(imports(read(file)).specifiers.filter((s) => /lib\/nodeActionItems$/.test(s)), file).toEqual([])
+ }
+ })
+
it('no other renderer file defines the node rows again', () => {
const owned = join(RENDERER, 'lib/nodeActionItems.tsx')
const rows = ["label: 'Restart agent'", "label: 'Pause & end session'", "label: 'Switch Claude account'"]
diff --git a/src/renderer/lib/nodeActionItems.offCanvas.test.tsx b/src/renderer/lib/nodeActionItems.offCanvas.test.tsx
index 82cbc5ac8..c584aec7e 100644
--- a/src/renderer/lib/nodeActionItems.offCanvas.test.tsx
+++ b/src/renderer/lib/nodeActionItems.offCanvas.test.tsx
@@ -110,6 +110,22 @@ describe('offCanvasNodeActionCtx — a card of a background project', () => {
expect(i.refuse).toHaveBeenCalledTimes(2)
})
+ it('an Omni card of a background project shows session rows disabled as not attached', () => {
+ // Idle, with a session id, so the ONLY reason for disabling is the missing attachment.
+ useAgentStatus.setState({ byId: { a1: { state: 'done', sessionId: 's1' } } } as never)
+ const items = buildNodeActionItems(
+ ['a1'],
+ undefined,
+ offCanvasNodeActionCtx(input([stored('a1', { agentId: 'claude', agentSessionId: 's1' } as never)])),
+ { allow: BOARD_NODE_ACTION_IDS }
+ )
+ for (const label of ['Restart agent', 'Restart agent and shell', 'Pause', 'Pause & end session', 'Refresh terminal']) {
+ const r = row(items, label)
+ expect(r && 'disabled' in r && r.disabled, label).toBe(true)
+ expect(r && 'hint' in r && r.hint, label).toBe('This terminal is not attached right now.')
+ }
+ })
+
it('a node of the stored copy that names its agent only by the legacy claude tag is still an agent', () => {
const ctx = offCanvasNodeActionCtx(input([stored('a1', { tags: ['claude'] } as never)]))
expect(ctx.agentIdOf('a1')).toBe('claude')
diff --git a/src/renderer/lib/nodeActionItems.test.tsx b/src/renderer/lib/nodeActionItems.test.tsx
index 7f185e85c..92b01c6a0 100644
--- a/src/renderer/lib/nodeActionItems.test.tsx
+++ b/src/renderer/lib/nodeActionItems.test.tsx
@@ -9,6 +9,8 @@ import {
BOARD_NODE_ACTION_IDS,
BOARD_SPATIAL_ROW_IDS,
buildNodeActionItems,
+ NOT_ATTACHED_HINT,
+ RELEASED_HINT,
type NodeActionCtx
} from './nodeActionItems'
@@ -21,6 +23,8 @@ function fakeCtx(nodes: CanvasNode[], over: Partial<NodeActionCtx> = {}): NodeAc
nodes,
sessionSource: 'local',
attached: () => true,
+ // Like the live canvas: the canvas holds every node it was given.
+ onCanvas: (id) => nodes.some((n) => n.id === id),
agentIdOf: (id) => nodes.find((n) => n.id === id)?.data.agentId as never,
gatewayModels: [],
gatewayStatus: 'idle',
@@ -135,12 +139,12 @@ describe('buildNodeActionItems — the canvas node menu, moved verbatim', () =>
expect(hintOf(items, 'Restart agent')).toBe('Nothing to resume yet — this session has not reported an id.')
})
- it('an unmounted agent says its terminal is not attached', () => {
+ it('an agent not on the canvas says its terminal is not attached', () => {
useAgentStatus.setState({ byId: { a1: { state: 'done', sessionId: 's1' } } } as never)
const items = buildNodeActionItems(
['a1'],
undefined,
- fakeCtx([term('a1', { agentId: 'claude' })], { attached: () => false })
+ fakeCtx([term('a1', { agentId: 'claude' })], { attached: () => false, onCanvas: () => false })
)
expect(hintOf(items, 'Restart agent')).toBe('This terminal is not attached right now.')
})
@@ -217,7 +221,7 @@ describe('buildNodeActionItems — filters', () => {
allow: BOARD_NODE_ACTION_IDS
})
)
- ).toEqual(['[colors]', 'Set icon…', '—', 'Share live link…'])
+ ).toEqual(['[colors]', 'Set icon…', '—', 'Refresh terminal', 'Share live link…'])
})
it('on the board list the live-link row comes before the account switch', () => {
@@ -243,3 +247,185 @@ describe('buildNodeActionItems — filters', () => {
for (const id of ['label', 'markdown-view', 'delete'] as const) expect(BOARD_NODE_ACTION_IDS).not.toContain(id)
})
})
+
+describe('session rows when the terminal is not attached', () => {
+ const NOT_ATTACHED = 'This terminal is not attached right now.'
+ const claude = term('a', { agentId: 'claude', agentSessionId: 'sess-1' })
+ // Not on the canvas at all: an Omni lane of a project the canvas does not hold.
+ const ctxDetached = (): NodeActionCtx =>
+ fakeCtx([claude], { attached: () => false, onCanvas: () => false })
+ // On the live canvas, its terminal released while off screen.
+ const ctxReleased = (): NodeActionCtx => fakeCtx([claude], { attached: () => false })
+
+ it('a node released off screen keeps Refresh terminal enabled (the respawn revives it)', () => {
+ const items = buildNodeActionItems(['a'], undefined, ctxReleased())
+ expect(disabledOf(items, 'Refresh terminal')).toBe(false)
+ expect(hintOf(items, 'Refresh terminal')).not.toBe(NOT_ATTACHED_HINT)
+ })
+
+ it('a node not on the canvas disables Refresh terminal with the not-attached reason', () => {
+ const items = buildNodeActionItems(['a'], undefined, ctxDetached())
+ expect(disabledOf(items, 'Refresh terminal')).toBe(true)
+ expect(hintOf(items, 'Refresh terminal')).toBe(NOT_ATTACHED_HINT)
+ })
+
+ it('released on the canvas: session rows say the terminal was released, not that it is unattached', () => {
+ useAgentStatus.setState({ byId: { a: { state: 'done', sessionId: 'sess-1' } as never } })
+ const items = buildNodeActionItems(['a'], undefined, ctxReleased())
+ for (const label of ['Restart agent', 'Restart agent and shell', 'Restart on subscription', 'Pause', 'Pause & end session']) {
+ expect(disabledOf(items, label)).toBe(true)
+ expect(hintOf(items, label)).toBe(RELEASED_HINT)
+ }
+ useAgentStatus.setState({ byId: { a: { sessionId: 'sess-1', paused: true } as never } })
+ const paused = buildNodeActionItems(['a'], undefined, ctxReleased())
+ expect(disabledOf(paused, 'Resume session')).toBe(true)
+ expect(hintOf(paused, 'Resume session')).toBe(RELEASED_HINT)
+ })
+
+ it('the released hint names no single surface (canvas menu, sidebar and board all show it)', () => {
+ expect(RELEASED_HINT).not.toMatch(/card menu/i)
+ expect(RELEASED_HINT).toMatch(/refresh the terminal/i)
+ })
+
+ it('not on the canvas: the same rows keep the not-attached reason', () => {
+ useAgentStatus.setState({ byId: { a: { state: 'done', sessionId: 'sess-1' } as never } })
+ const items = buildNodeActionItems(['a'], undefined, ctxDetached())
+ for (const label of ['Restart agent', 'Restart agent and shell', 'Restart on subscription', 'Pause', 'Pause & end session']) {
+ expect(hintOf(items, label)).toBe(NOT_ATTACHED_HINT)
+ }
+ })
+
+ it('disables Pause and Pause & end session with the not-attached reason', () => {
+ useAgentStatus.setState({ byId: { a: { state: 'done', sessionId: 'sess-1' } as never } })
+ const items = buildNodeActionItems(['a'], undefined, ctxDetached())
+ expect(disabledOf(items, 'Pause')).toBe(true)
+ expect(hintOf(items, 'Pause')).toBe(NOT_ATTACHED)
+ expect(disabledOf(items, 'Pause & end session')).toBe(true)
+ expect(hintOf(items, 'Pause & end session')).toBe(NOT_ATTACHED)
+ })
+
+ it('disables Resume session when detached, enables it when attached', () => {
+ useAgentStatus.setState({
+ byId: { a: { state: undefined, sessionId: 'sess-1', paused: true } as never }
+ })
+ const detached = buildNodeActionItems(['a'], undefined, ctxDetached())
+ expect(disabledOf(detached, 'Resume session')).toBe(true)
+ expect(hintOf(detached, 'Resume session')).toBe(NOT_ATTACHED)
+ const attached = buildNodeActionItems(['a'], undefined, fakeCtx([claude]))
+ expect(disabledOf(attached, 'Resume session')).toBeFalsy()
+ })
+
+ it('disables Refresh terminal for one detached node and keeps the busy reason ahead of it', () => {
+ const items = buildNodeActionItems(['a'], undefined, ctxDetached())
+ expect(disabledOf(items, 'Refresh terminal')).toBe(true)
+ expect(hintOf(items, 'Refresh terminal')).toBe(NOT_ATTACHED)
+ useAgentStatus.setState({ byId: { a: { state: 'working', sessionId: 'sess-1' } as never } })
+ const busy = buildNodeActionItems(['a'], undefined, fakeCtx([claude]))
+ expect(hintOf(busy, 'Pause')).toMatch(/busy/)
+ })
+
+ it('busy and no-id outrank not-attached on a detached node', () => {
+ useAgentStatus.setState({ byId: { a: { state: 'working', sessionId: 'sess-1' } as never } })
+ expect(hintOf(buildNodeActionItems(['a'], undefined, ctxDetached()), 'Pause')).toMatch(/busy/)
+ useAgentStatus.setState({ byId: { a: { state: 'done' } as never } })
+ expect(hintOf(buildNodeActionItems(['a'], undefined, ctxDetached()), 'Pause')).toBe(
+ 'Nothing to resume yet — this session has not reported an id.'
+ )
+ })
+
+ it('a selection of several detached terminals keeps Refresh terminal enabled', () => {
+ const items = buildNodeActionItems(['t1', 't2'], undefined, fakeCtx([term('t1'), term('t2')], { attached: () => false }))
+ expect(disabledOf(items, 'Refresh terminal')).toBe(false)
+ })
+})
+
+describe('board allowlist carries the session sections', () => {
+ const labels = (items: MenuItem[]): string[] => top(items)
+
+ it('offers refresh, restart, pause for an idle attached claude card, and no node-creating rows', () => {
+ useAgentStatus.setState({ byId: { a: { state: 'done', sessionId: 's' } as never } })
+ const n = term('a', { agentId: 'claude', agentSessionId: 's' })
+ const l = labels(buildNodeActionItems(['a'], undefined, fakeCtx([n]), { allow: BOARD_NODE_ACTION_IDS }))
+ expect(l).toEqual(expect.arrayContaining(['Refresh terminal', 'Restart ▸', 'Pause session ▸']))
+ for (const never of ['Duplicate', 'Branch conversation', 'Group node', 'Collapse'])
+ expect(l.some((x) => x.startsWith(never))).toBe(false)
+ for (const id of BOARD_SPATIAL_ROW_IDS) expect(BOARD_NODE_ACTION_IDS).not.toContain(id)
+ })
+
+ it('a working agent: restarts and pauses are disabled with the busy reason and nothing runs', () => {
+ useAgentStatus.setState({ byId: { a: { state: 'working', sessionId: 's' } as never } })
+ const restartAgentNode = vi.fn(async () => {})
+ const pauseAgentNode = vi.fn(async () => {})
+ const n = term('a', { agentId: 'claude', agentSessionId: 's' })
+ const items = buildNodeActionItems(['a'], undefined, fakeCtx([n], { restartAgentNode, pauseAgentNode }), {
+ allow: BOARD_NODE_ACTION_IDS
+ })
+ for (const label of ['Restart agent', 'Restart agent and shell', 'Pause', 'Pause & end session']) {
+ expect(disabledOf(items, label)).toBe(true)
+ expect(hintOf(items, label)).toMatch(/busy/)
+ }
+ // Building the menu never runs a session action on its own.
+ expect(restartAgentNode).not.toHaveBeenCalled()
+ expect(pauseAgentNode).not.toHaveBeenCalled()
+ })
+
+ it('a relay card: recycling rows are disabled with the host wording', () => {
+ useAgentStatus.setState({ byId: { a: { state: 'done', sessionId: 's' } as never } })
+ const n = term('a', { agentId: 'claude', agentSessionId: 's' })
+ const items = buildNodeActionItems(['a'], undefined, fakeCtx([n], { sessionSource: 'relay' }), {
+ allow: BOARD_NODE_ACTION_IDS
+ })
+ expect(disabledOf(items, 'Restart agent and shell')).toBe(true)
+ expect(hintOf(items, 'Restart agent and shell')).toBe('Restart the shell on the machine hosting this relay session.')
+ expect(disabledOf(items, 'Pause & end session')).toBe(true)
+ expect(hintOf(items, 'Pause & end session')).toBe(
+ 'Ends the tmux session on the machine hosting this relay session, not here.'
+ )
+ expect(disabledOf(items, 'Restart on subscription')).toBe(true)
+ expect(hintOf(items, 'Restart on subscription')).toBe('Restart the shell on the machine hosting this relay session.')
+ expect(disabledOf(items, 'Restart agent')).toBeFalsy()
+ })
+
+ it('a browser card gets no session rows', () => {
+ const browser = {
+ id: 'b1',
+ type: 'browser',
+ position: { x: 0, y: 0 },
+ data: { title: 'b1', url: 'https://example.com' }
+ } as unknown as CanvasNode
+ const l = labels(buildNodeActionItems(['b1'], undefined, fakeCtx([browser]), { allow: BOARD_NODE_ACTION_IDS }))
+ expect(l.some((x) => /Restart|Pause|Switch model|Refresh/.test(x))).toBe(false)
+ })
+
+ it('a paused node shows Resume and never Pause', () => {
+ useAgentStatus.setState({ byId: { a: { sessionId: 's', paused: true } as never } })
+ const n = term('a', { agentId: 'claude', agentSessionId: 's' })
+ const l = labels(buildNodeActionItems(['a'], undefined, fakeCtx([n]), { allow: BOARD_NODE_ACTION_IDS }))
+ expect(l).toContain('Resume session')
+ expect(l).not.toContain('Pause session ▸')
+ })
+
+ it('sticky and plain-shell cards get no agent rows; the shell still refreshes', () => {
+ const sticky = { id: 's1', type: 'sticky', position: { x: 0, y: 0 }, data: {} } as unknown as CanvasNode
+ const shell = term('t')
+ const l1 = labels(buildNodeActionItems(['s1'], undefined, fakeCtx([sticky]), { allow: BOARD_NODE_ACTION_IDS }))
+ expect(l1.some((x) => /Restart|Pause|Refresh/.test(x))).toBe(false)
+ const l2 = labels(buildNodeActionItems(['t'], undefined, fakeCtx([shell]), { allow: BOARD_NODE_ACTION_IDS }))
+ expect(l2).toContain('Refresh terminal')
+ expect(l2.some((x) => /Restart|Pause/.test(x))).toBe(false)
+ })
+
+ it('hiding refresh-terminal in Settings hides it on the card', () => {
+ useSettings.setState({
+ settings: { ...DEFAULT_SETTINGS, hiddenNodeMenuItems: ['refresh-terminal'] }
+ })
+ const l = labels(buildNodeActionItems(['t'], undefined, fakeCtx([term('t')]), { allow: BOARD_NODE_ACTION_IDS }))
+ expect(l).not.toContain('Refresh terminal')
+ })
+
+ it('the modal allowlist is a subset without refresh', async () => {
+ const mod = await import('./nodeActionItems')
+ expect(mod.BOARD_MODAL_ACTION_IDS).toEqual(['restart', 'switch-model', 'switch-account', 'pause'])
+ for (const id of mod.BOARD_MODAL_ACTION_IDS) expect(BOARD_NODE_ACTION_IDS).toContain(id)
+ })
+})
diff --git a/src/renderer/lib/nodeActionItems.tsx b/src/renderer/lib/nodeActionItems.tsx
index d81574734..133dcdff3 100644
--- a/src/renderer/lib/nodeActionItems.tsx
+++ b/src/renderer/lib/nodeActionItems.tsx
@@ -126,17 +126,57 @@ export const BOARD_SPATIAL_ROW_IDS = [
* The sections a kanban card menu takes from this builder. Everything else is either spatial
* (above), owned by the card menu itself (`label` — a card is always one node; `markdown-view` —
* the board opens the card modal in its chat/markdown view instead of flipping the canvas node's
- * `data.mdMode`; `delete` — the board keeps its own confirm-first Delete), or not offered on a card
- * yet (session management and node-creating rows).
+ * `data.mdMode`; `delete` — the board keeps its own confirm-first Delete), or creates a node
+ * (`duplicate`, `branch`, `transfer` — Plan C: they need a placement policy and, on the Omni
+ * board, a create path that does not switch the user's tab).
+ *
+ * The session-management rows (`refresh-terminal`, `restart`, `switch-model`, `pause`) are here
+ * because the canvas keeps the terminal MOUNTED under the board: for a card of the project the
+ * canvas holds, the live context's closures act on the same node. For any other project (an Omni
+ * lane) `ctx.attached` is false, so they render disabled with "This terminal is not attached
+ * right now." — they are never hidden and never reach the canvas.
*/
export const BOARD_NODE_ACTION_IDS = [
'stop-agent-control',
'colors',
'icon',
+ 'refresh-terminal',
'live-link',
- 'switch-account'
+ 'restart',
+ 'switch-model',
+ 'switch-account',
+ 'pause'
+] as const satisfies readonly NodeActionId[]
+
+/**
+ * The card MODAL's actions menu. The modal header already has search, dictate, AI name, color,
+ * icon and live link, and its terminal has its own refresh (it re-attaches only the modal's own
+ * pty, which is a different action from the canvas node's `respawnNonce` bump), so only the
+ * session-management sections are offered here.
+ */
+export const BOARD_MODAL_ACTION_IDS = [
+ 'restart',
+ 'switch-model',
+ 'switch-account',
+ 'pause'
] as const satisfies readonly NodeActionId[]
+/** The reason a session row gives when the node is not on the canvas at all (an Omni lane of a
+ * project the canvas does not hold), so nothing can be wired to it from here. */
+export const NOT_ATTACHED_HINT = 'This terminal is not attached right now.'
+/** The reason a session row gives when the node IS on the live canvas but its terminal was
+ * released while off screen (the offscreen release): the pane is alive (the card modal shows it),
+ * only the canvas node's client is gone. Refresh, or bringing it into view, wires it again. */
+export const RELEASED_HINT =
+ 'This terminal was released while off screen — refresh the terminal or bring it into view on the canvas.'
+
+/** Why a session row cannot act on this node right now because nothing is wired to it, or
+ * undefined when it is. The ONE place that tells "released on the canvas" from "not on it". */
+function detachedHint(ctx: NodeActionCtx, nodeId: string): string | undefined {
+ if (ctx.attached(nodeId)) return undefined
+ return ctx.onCanvas(nodeId) ? RELEASED_HINT : NOT_ATTACHED_HINT
+}
+
/** Everything the node rows read from, or do through, the canvas that owns the node. */
export interface NodeActionCtx {
/** The node array of the project the rows act on: React Flow's live array for the project it
@@ -147,6 +187,10 @@ export interface NodeActionCtx {
/** Is the node's terminal mounted and wired (its restart closure registered)? Always false for a
* project the canvas does not hold. */
attached: (nodeId: string) => boolean
+ /** Does the canvas hold this node (it is in React Flow's live array)? True even while the node's
+ * terminal is released off screen — which is exactly when Refresh is needed. Always false for a
+ * project the canvas does not hold. */
+ onCanvas: (nodeId: string) => boolean
agentIdOf: (nodeId: string) => AgentId | undefined
gatewayModels: GatewayModel[]
gatewayStatus: ModelDiscoveryStatus
@@ -398,7 +442,15 @@ export function buildNodeActionSections(
{
label: 'Refresh terminal',
icon: <IconReload />,
- hint: 'Rebuilds the view and re-attaches to the same session. Nothing running is interrupted.',
+ // One node: it can be rebuilt while the canvas holds it — including a terminal
+ // released off screen, which the respawn revives (so NOT `attached`, which is false
+ // for exactly that node). A node of a project the canvas does not hold cannot. A
+ // selection of several keeps the old always-enabled row.
+ disabled: ids.length === 1 && !ctx.onCanvas(ids[0]),
+ hint:
+ ids.length === 1 && !ctx.onCanvas(ids[0])
+ ? NOT_ATTACHED_HINT
+ : 'Rebuilds the view and re-attaches to the same session. Nothing running is interrupted.',
onClick: () => ctx.reloadTerminals(ids)
}
]
@@ -499,15 +551,13 @@ function sessionRows(nodeId: string, ctx: NodeActionCtx, hidden: readonly string
? gate.reason === 'working'
? 'This session is busy — restart it once its turn (or permission prompt) is done.'
: 'Nothing to resume yet — this session has not reported an id.'
- : !ctx.attached(ids[0])
- ? 'This terminal is not attached right now.'
- : // Not every dead end is visible from here: the closure ALSO refuses a tmux
- // session that is closed / ended / gone, and a pane it cannot observe at all
- // (tmux off / absent — it pre-flights one `pane_current_command` before writing
- // anything). Only the node knows the first, and the second costs an IPC that must
- // not run per menu RENDER. Both reach the user through `restartAgentNode`'s skip
- // notice, which names them, rather than through a hint this row cannot compute.
- undefined
+ : // Not every dead end is visible from here: the closure ALSO refuses a tmux
+ // session that is closed / ended / gone, and a pane it cannot observe at all
+ // (tmux off / absent — it pre-flights one `pane_current_command` before writing
+ // anything). Only the node knows the first, and the second costs an IPC that must
+ // not run per menu RENDER. Both reach the user through `restartAgentNode`'s skip
+ // notice, which names them, rather than through a hint this row cannot compute.
+ detachedHint(ctx, ids[0])
// Pause/Resume have their OWN eligibility, computed on `st?.sessionId` alone — NOT
// `sessionId` above, which also falls back to `n?.data.agentSessionId` (the id
// nodeterm minted at node creation, for a node whose hooks never landed). The `pause`/
@@ -522,7 +572,7 @@ function sessionRows(nodeId: string, ctx: NodeActionCtx, hidden: readonly string
? pauseGate.reason === 'working'
? 'This session is busy — try again once its turn (or permission prompt) is done.'
: 'Nothing to resume yet — this session has not reported an id.'
- : undefined
+ : detachedHint(ctx, ids[0])
const restartRows: MenuItem[] = [
{
label: 'Restart agent',
@@ -581,9 +631,8 @@ function sessionRows(nodeId: string, ctx: NodeActionCtx, hidden: readonly string
? 'Nothing to resume yet — this session has not reported an id.'
: ctx.sessionSource === 'relay'
? 'Restart the shell on the machine hosting this relay session.'
- : !ctx.attached(ids[0])
- ? 'This terminal is not attached right now.'
- : 'Restarts the session with gateway/provider env stripped — uses your own subscription/credentials.',
+ : detachedHint(ctx, ids[0]) ??
+ 'Restarts the session with gateway/provider env stripped — uses your own subscription/credentials.',
onClick: () => void ctx.restartAgentNode(ids[0], undefined, undefined, undefined, true)
}
]
@@ -670,7 +719,8 @@ function sessionRows(nodeId: string, ctx: NodeActionCtx, hidden: readonly string
{
label: 'Resume session',
icon: <IconPower />,
- hint: 'Brings the conversation back.',
+ disabled: !ctx.attached(ids[0]),
+ hint: detachedHint(ctx, ids[0]) ?? 'Brings the conversation back.',
onClick: () => void ctx.resumeAgentNode(ids[0])
}
] as MenuItem[])
@@ -727,9 +777,7 @@ export function buildAccountSwitchRows(nodeId: string, ctx: NodeActionCtx): Menu
? gate.reason === 'working'
? 'This session is busy — switch it once its turn (or permission prompt) is done.'
: 'Nothing to resume yet — this session has not reported an id.'
- : !ctx.attached(nodeId)
- ? 'This terminal is not attached right now.'
- : undefined
+ : detachedHint(ctx, nodeId)
return [
// Switch this running Claude node onto another account already logged in on its
// machine — this one, or the SSH host its pane runs on — with no /login in the pane
@@ -865,6 +913,7 @@ export function offCanvasNodeActionCtx(o: OffCanvasCtxInput): NodeActionCtx {
nodes: o.nodes,
sessionSource: o.sessionSource,
attached: () => false,
+ onCanvas: () => false,
// Canvas `agentIdOf`, over the stored copy.
agentIdOf: (nodeId) => {
const n = o.nodes.find((x) => x.id === nodeId)