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(windows): reach canvas-control and context-link shims from PowerShell-run agents
reviewf8cf23db67b7
diff --git a/src/core/agent-integrations.test.ts b/src/core/agent-integrations.test.tsindex f914e30d3..b46f79e7e 100644--- a/src/core/agent-integrations.test.ts+++ b/src/core/agent-integrations.test.ts@@ -10,10 +10,12 @@ import path from 'path'import { initPlatform, resetPlatformForTests } from './platform'import { fakePlatform } from './platform-fake'import { DEFAULT_SETTINGS, type Settings } from '../shared/types'+import { shimDialectFor } from '../shared/agents/shim-invocation'import {CANVAS_SKILL,CONTEXT_SKILL,createIntegrationLifecycle,+ skillsFor,detectExistingIntegrations,resolveIntegrationConsentAtBoot} from './agent-integrations'@@ -132,23 +134,25 @@ describe('discovery: every capable agent still finds canvas control and contextconst all = { claude: 'enabled', codex: 'enabled', gemini: 'enabled', grok: 'enabled', copilot: 'enabled', opencode: 'enabled' } as constconst { lc, hookCalls } = lifecycle(() => withAgents(all))lc.reconcile()- const canvas = buildCanvasSkillBody(SHIMS().canvas)- const context = buildContextLinkSkillBody(SHIMS().context)- const dirs: Record<string, [boolean, boolean]> = {- [path.join(home, '.claude', 'skills')]: [true, true],- [path.join(home, 'codex-home', 'skills')]: [true, true],- [path.join(home, '.gemini', 'skills')]: [true, true],- [path.join(home, 'grok-home', 'skills')]: [true, true],- [path.join(home, 'copilot-home', 'skills')]: [true, false], // copilot: canvas control only- [path.join(home, 'xdg', 'opencode', 'skills')]: [true, true]+ // The body depends on THIS host (a Windows runner tells non-claude agents to run the `.cmd`+ // launcher), so the expectation is derived the same way the installer derives it.+ const canvas = (agent: string) => buildCanvasSkillBody(SHIMS().canvas, shimDialectFor(agent, process.platform))+ const context = (agent: string) => buildContextLinkSkillBody(SHIMS().context, shimDialectFor(agent, process.platform))+ const dirs: Record<string, [string, boolean, boolean]> = {+ [path.join(home, '.claude', 'skills')]: ['claude', true, true],+ [path.join(home, 'codex-home', 'skills')]: ['codex', true, true],+ [path.join(home, '.gemini', 'skills')]: ['gemini', true, true],+ [path.join(home, 'grok-home', 'skills')]: ['grok', true, true],+ [path.join(home, 'copilot-home', 'skills')]: ['copilot', true, false], // copilot: canvas control only+ [path.join(home, 'xdg', 'opencode', 'skills')]: ['opencode', true, true]}- for (const [dir, [hasCanvas, hasContext]] of Object.entries(dirs)) {+ for (const [dir, [agent, hasCanvas, hasContext]] of Object.entries(dirs)) {const c = path.join(dir, CANVAS_SKILL, 'SKILL.md')const x = path.join(dir, CONTEXT_SKILL, 'SKILL.md')expect(existsSync(c), c).toBe(hasCanvas)expect(existsSync(x), x).toBe(hasContext)- if (hasCanvas) expect(read(c)).toBe(canvas)- if (hasContext) expect(read(x)).toBe(context)+ if (hasCanvas) expect(read(c)).toBe(canvas(agent))+ if (hasContext) expect(read(x)).toBe(context(agent))}for (const f of ['.codex/AGENTS.md', '.gemini/GEMINI.md', 'codex-home/AGENTS.md', 'copilot-home/copilot-instructions.md', 'xdg/opencode/AGENTS.md']) {expect(existsSync(path.join(home, f)), f).toBe(false)@@ -298,3 +302,33 @@ describe('the existing-vs-new default', () => {expect(resolveIntegrationConsentAtBoot(answered, true)).toBeNull()})})++describe('skillsFor — the invocation follows the host and the agent\'s tool shell', () => {+ const shims = { canvas: 'C:\\nt\\canvas-control\\nodeterm.sh', context: 'C:\\nt\\context-links\\context.sh' }++ it('win32: a PowerShell-run agent is told to run the .cmd launcher', () => {+ for (const agent of ['codex', 'gemini', 'grok', 'opencode'] as const) {+ const skills = skillsFor(agent, shims, 'win32')+ expect(skills.get(CANVAS_SKILL), agent).toContain('& "C:\\nt\\canvas-control\\nodeterm.cmd" <verb> [args]')+ expect(skills.get(CONTEXT_SKILL), agent).toContain('& "C:\\nt\\context-links\\context.cmd" <command>')+ expect(skills.get(CANVAS_SKILL), agent).not.toContain('```sh\nsh "')+ }+ expect(skillsFor('copilot', shims, 'win32').get(CANVAS_SKILL)).toContain('nodeterm.cmd')+ })++ it('win32: claude keeps `sh` (its Bash tool is Git Bash) — the exact POSIX body', () => {+ const skills = skillsFor('claude', shims, 'win32')+ expect(skills.get(CANVAS_SKILL)).toBe(buildCanvasSkillBody(shims.canvas))+ expect(skills.get(CONTEXT_SKILL)).toBe(buildContextLinkSkillBody(shims.context))+ })++ it('every non-win32 host gets the byte-identical POSIX bodies for every agent', () => {+ for (const host of ['darwin', 'linux']) {+ for (const agent of ['claude', 'codex', 'gemini', 'grok', 'opencode'] as const) {+ const skills = skillsFor(agent, { canvas: '/u/nodeterm.sh', context: '/u/context.sh' }, host)+ expect(skills.get(CANVAS_SKILL)).toBe(buildCanvasSkillBody('/u/nodeterm.sh'))+ expect(skills.get(CONTEXT_SKILL)).toBe(buildContextLinkSkillBody('/u/context.sh'))+ }+ }+ })+})diff --git a/src/core/agent-integrations.ts b/src/core/agent-integrations.tsindex cf3eb598c..e73ab828f 100644--- a/src/core/agent-integrations.ts+++ b/src/core/agent-integrations.ts@@ -23,6 +23,7 @@ import {type IntegrationAgentId} from '../shared/agent-integrations'import { canContextLink, canControlCanvas } from '../shared/agents/config'+import { shimDialectFor } from '../shared/agents/shim-invocation'import type { Settings } from '../shared/types'import { installManagedAgentHooks, removeManagedAgentHooks } from './agents/hooks'import {@@ -164,11 +165,21 @@ export function skillRootsFor(}}-/** The skills one agent gets, as (file name → body). */-export function skillsFor(agent: IntegrationAgentId, shims: IntegrationShims): Map<string, string> {+/**+ * The skills one agent gets, as (file name → body). `hostPlatform` is THIS machine's — these skills+ * are written into its own config dirs and point at its own shims — and it picks the invocation:+ * on Windows every agent but claude is told to run the `.cmd` launcher (`shimDialectFor`). The SSH+ * installers build their bodies themselves, without a dialect, so a host always gets `sh`.+ */+export function skillsFor(+ agent: IntegrationAgentId,+ shims: IntegrationShims,+ hostPlatform: string = process.platform+): Map<string, string> {const out = new Map<string, string>()- if (shims.canvas && canControlCanvas(agent)) out.set(CANVAS_SKILL, buildCanvasSkillBody(shims.canvas))- if (canContextLink(agent)) out.set(CONTEXT_SKILL, buildContextLinkSkillBody(shims.context))+ const dialect = shimDialectFor(agent, hostPlatform)+ if (shims.canvas && canControlCanvas(agent)) out.set(CANVAS_SKILL, buildCanvasSkillBody(shims.canvas, dialect))+ if (canContextLink(agent)) out.set(CONTEXT_SKILL, buildContextLinkSkillBody(shims.context, dialect))return out}diff --git a/src/core/agents/hooks/install-helper.test.ts b/src/core/agents/hooks/install-helper.test.tsindex 3143a7200..fa36906e8 100644--- a/src/core/agents/hooks/install-helper.test.ts+++ b/src/core/agents/hooks/install-helper.test.ts@@ -7,6 +7,7 @@ import {buildManagedHookCommand,mergeManagedHook,stripManagedHook,+ syncWindowsShLauncher,writeManagedHookConfig,writeManagedHookFileAtomic,type HookSettings@@ -315,3 +316,22 @@ describe('buildManagedHookCommand — Windows wrapper (gemini / grok / copilot)'})})+describe('syncWindowsShLauncher — the .cmd beside a CLI shim', () => {+ it('win32 writes nodeterm.cmd running nodeterm.sh; another platform removes a stray copy', () => {+ const dir = mkdtempSync(join(tmpdir(), 'nt-launcher-'))+ try {+ syncWindowsShLauncher(dir, 'nodeterm.sh', 'win32')+ const text = readFileSync(join(dir, 'nodeterm.cmd'), 'utf8')+ expect(text).toContain('set "NT_SCRIPT=%~dp0nodeterm.sh"')+ expect(text).toContain('"%NT_SH%" "%NT_ARG%" %*')+ expect(text).not.toContain(dir) // no baked absolute path+ syncWindowsShLauncher(dir, 'nodeterm.sh', 'linux')+ expect(readdirSync(dir)).toEqual([])+ // Removing what is not there is not an error.+ syncWindowsShLauncher(dir, 'context.sh', 'darwin')+ } finally {+ rmSync(dir, { recursive: true, force: true })+ }+ })+})+diff --git a/src/core/agents/hooks/install-helper.ts b/src/core/agents/hooks/install-helper.tsindex d3e060b04..aeb3b904a 100644--- a/src/core/agents/hooks/install-helper.ts+++ b/src/core/agents/hooks/install-helper.ts@@ -19,7 +19,8 @@ import { readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync } from 'fs'import { managedEventName, type ManagedHookEvent } from '@shared/agents/hook-events'import { renameAtomicSync, tempNameFor } from '../../fs-atomic'import { buildManagedScript } from './managed-script'-import { buildWindowsHookInvocation, buildWindowsHookWrapper, windowsHookWrapperFile } from './windows-hook-wrapper'+import { buildWindowsHookInvocation, buildWindowsHookWrapper, buildWindowsShLauncher, windowsHookWrapperFile } from './windows-hook-wrapper'+import { cmdShimPathFor } from '@shared/agents/shim-invocation'type HookDef = { matcher?: string; hooks?: { type: string; command: string; timeout?: number }[] }type Settings = { hooks?: Record<string, HookDef[]>; [k: string]: unknown }@@ -46,6 +47,23 @@ export function writeManagedHookFileAtomic(}}+/**+ * Keep the `.cmd` launcher beside a user-invoked POSIX CLI shim (`nodeterm.sh`, `context.sh`) in+ * step with the platform: written on Windows — where every agent but claude runs tools in+ * PowerShell/cmd.exe and is told to run it (`shimDialectFor`) — and removed anywhere else, so a+ * data dir carried across machines holds no stale launcher. Throws on a failed write, like the+ * shim write it accompanies.+ */+export function syncWindowsShLauncher(+ dir: string,+ scriptFileName: string,+ platformName: NodeJS.Platform | string = process.platform+): void {+ const target = path.join(dir, cmdShimPathFor(scriptFileName))+ if (platformName === 'win32') writeManagedHookFileAtomic(target, buildWindowsShLauncher(scriptFileName))+ else rmSync(target, { force: true })+}+/*** Legacy direct writer for owned config callers. Shared Claude/Gemini settings use the guarded* updateSettingsFile transaction instead. Grok opts into atomic replacement for its owned file.diff --git a/src/core/agents/hooks/windows-hook-wrapper.test.ts b/src/core/agents/hooks/windows-hook-wrapper.test.tsindex 645ea16c6..04261506e 100644--- a/src/core/agents/hooks/windows-hook-wrapper.test.ts+++ b/src/core/agents/hooks/windows-hook-wrapper.test.ts@@ -1,3 +1,7 @@+import { execFileSync } from 'child_process'+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'+import { tmpdir } from 'os'+import path from 'path'import { describe, expect, it } from 'vitest'import {buildWindowsHookInvocation,@@ -93,3 +97,39 @@ describe('buildWindowsShLauncher', () => {expect(l.split('\n').slice(0, -1).every((x) => x.endsWith('\r'))).toBe(true)})})++// The real thing, on the windows-latest runner: cmd.exe runs the generated batch files against Git+// for Windows' sh.exe. Skipped elsewhere (no cmd.exe) and where no Git sh is installed.+const gitSh = (): boolean =>+ WINDOWS_SH_CANDIDATES.some((c) =>+ existsSync(c.replace(/%([^%]+)%/g, (_, name: string) => process.env[name] ?? `%${name}%`))+ )+describe.skipIf(process.platform !== 'win32' || !gitSh())('Windows wrappers under a real cmd.exe', () => {+ it('the CLI launcher passes every argument through to the POSIX script', () => {+ const dir = mkdtempSync(path.join(tmpdir(), 'nt-launcher-real-'))+ try {+ writeFileSync(path.join(dir, 'nodeterm.sh'), 'for a in "$@"; do printf "[%s]" "$a"; done\n')+ writeFileSync(path.join(dir, 'nodeterm.cmd'), buildWindowsShLauncher('nodeterm.sh'))+ const out = execFileSync('cmd.exe', ['/d', '/c', path.join(dir, 'nodeterm.cmd'), 'list', '--cmd=--version', '--node', 'b1'], {+ encoding: 'utf8'+ })+ expect(out).toBe('[list][--cmd=--version][--node][b1]')+ } finally {+ rmSync(dir, { recursive: true, force: true })+ }+ })++ it('the hook wrapper hands the payload on stdin to the script', () => {+ const dir = mkdtempSync(path.join(tmpdir(), 'nt-hookwrap-real-'))+ try {+ const sink = path.join(dir, 'got.txt').replaceAll('\\', '/')+ writeFileSync(path.join(dir, 'gemini.sh'), `cat > '${sink}'\n`)+ writeFileSync(path.join(dir, 'gemini-hook.cmd'), buildWindowsHookWrapper('gemini.sh', 'gemini'))+ execFileSync('cmd.exe', ['/d', '/c', path.join(dir, 'gemini-hook.cmd')], { input: '{"hook_event_name":"AfterTool"}' })+ expect(readFileSync(sink, 'utf8')).toBe('{"hook_event_name":"AfterTool"}')+ } finally {+ rmSync(dir, { recursive: true, force: true })+ }+ })+})+diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.tsindex 5727a414a..8c3307938 100644--- a/src/core/canvas-control-core.ts+++ b/src/core/canvas-control-core.ts@@ -15,6 +15,7 @@ import {import { codexSandboxGuidanceLines } from './context-link-core'import { NODE_TOKEN_READ_SH } from './agents/node-token-sh'import { AGENT_CONFIG, AGENT_HOOK_TARGETS, BUILTIN_AGENT_IDS } from '@shared/agents/config'+import { shimCommand, shimFence, windowsShimNoteLines, type ShimDialect } from '@shared/agents/shim-invocation'import { RETRYABLE } from './agents/agent-message-decide'import { FANOUT_PER_TURN, PAIR_MIN_INTERVAL_MS } from './agents/agent-message-flow'import { BROWSER_RETRYABLE, BROWSER_OUTCOME_LABEL } from './browser-outcomes'@@ -1383,8 +1384,11 @@ export const CONTROL_SHIM_SCRIPT = buildControlShimScript()/** The manage-nodeterm-canvas SKILL.md body, pointing at the shim at `shimPath`.* Parameterized because the same skill is installed twice with different paths: into the- * desktop's config dirs, and onto an SSH host for remote agent nodes. */-export function buildCanvasSkillBody(shimPath: string): string {+ * desktop's config dirs, and onto an SSH host for remote agent nodes. `dialect` is how the agent+ * reaching it must run it (`shimDialectFor`): `windows-cmd` only for a non-claude agent on a+ * Windows host; the default keeps every POSIX and SSH body byte-identical. */+export function buildCanvasSkillBody(shimPath: string, dialect: ShimDialect = 'posix'): string {+ const windowsNote = windowsShimNoteLines(shimPath, dialect, '--prompt-file')const agentChoices = `${BUILTIN_AGENT_IDS.join('|')}|<custom-id>`const statusAgents = AGENT_HOOK_TARGETS.join('/')const agentLabels = BUILTIN_AGENT_IDS.map((id) => AGENT_CONFIG[id].label).join(' / ')@@ -1400,10 +1404,10 @@ running the local CLI shim below. Every node you open is connected to your nodeRun the shim (absolute path):-\`\`\`sh-sh "${shimPath}" <verb> [args]+\`\`\`${shimFence(dialect)}+${shimCommand(shimPath, dialect)} <verb> [args]\`\`\`-+${windowsNote.length ? `\n${windowsNote.join('\n')}\n` : ''}Flags take a value: \`--flag value\`, or \`--flag=value\`. Use the \`=\` form when the value itselfstarts with \`--\` (\`--cmd=--version\`); written as two tokens, a leading \`--\` is read as thenext flag, so \`--text --oops\` sends an empty \`--text\` plus a stray \`--oops\`. A flag with nodiff --git a/src/core/context-link-core.test.ts b/src/core/context-link-core.test.tsindex aece95227..c90b59efd 100644--- a/src/core/context-link-core.test.ts+++ b/src/core/context-link-core.test.ts@@ -282,3 +282,20 @@ describe('the context-link shim', () => {expect(CONTEXT_SHIM_SCRIPT).not.toContain('nt_node_token=$(head -n 1 "$NODETERM_NODE_TOKEN_DIR')})})++describe('buildContextLinkSkillBody — shim invocation dialect', () => {+ it('the default is the historical `sh` block, unchanged', () => {+ const body = buildContextLinkSkillBody('/x/context.sh')+ expect(body).toContain('```sh\nsh "/x/context.sh" <command> [--node <id|title>] [-n <N>]\n```\n\nCommands:')+ expect(body).toBe(buildContextLinkSkillBody('/x/context.sh', 'posix'))+ })++ it('windows-cmd: names context.cmd through PowerShell and keeps the command reference', () => {+ const body = buildContextLinkSkillBody('C:\\d\\context.sh', 'windows-cmd')+ expect(body).toContain('```powershell\n& "C:\\d\\context.cmd" <command> [--node <id|title>] [-n <N>]\n```')+ expect(body).toContain('Git for Windows')+ const tail = (b: string) => b.slice(b.indexOf('Commands:'))+ expect(tail(body)).toBe(tail(buildContextLinkSkillBody('C:\\d\\context.sh')))+ })+})+diff --git a/src/core/context-link-core.ts b/src/core/context-link-core.tsindex eaa1bca4d..18a3e4c11 100644--- a/src/core/context-link-core.ts+++ b/src/core/context-link-core.ts@@ -15,6 +15,7 @@ import {} from './agents/hook-endpoint-failover-sh'import { NODE_TOKEN_READ_SH } from './agents/node-token-sh'import { codexThreadIdentityResolverSh } from './codex-thread-identity-sh'+import { shimCommand, shimFence, windowsShimNoteLines, type ShimDialect } from '../shared/agents/shim-invocation'/** The shim's generic transport-failure sentence — exported so the agent-facing docs below can* quote it verbatim and the parity test holds the two ends together. */@@ -353,7 +354,10 @@ export const CONTEXT_SHIM_SCRIPT = buildContextShimScript()/** The get-linked-context SKILL.md body, pointing at the shim at `shimPath`. Parameterized* because the same skill is installed twice with different paths: into the desktop's config* dirs, and onto an SSH host for remote agent nodes. */-export function buildContextLinkSkillBody(shimPath: string): string {+export function buildContextLinkSkillBody(shimPath: string, dialect: ShimDialect = 'posix'): string {+ // `dialect` as in buildCanvasSkillBody: only a non-claude agent on a Windows host gets the `.cmd`+ // line; the default keeps the POSIX and SSH bodies byte-identical.+ const windowsNote = windowsShimNoteLines(shimPath, dialect)return `---name: get-linked-contextdescription: Read the conversation/transcript, a recent summary, or the terminal output of another agent node (Claude, Codex or Gemini) you are linked to on the nodeterm canvas. Use when you need to know what a connected node has been doing, hand off, or continue its work. Only meaningful inside a nodeterm session with a context-link edge. Also reads sticky notes linked to this node as context.@@ -367,10 +371,10 @@ running the local CLI shim below. Nothing is pushed to you automatically — pulRun the shim (absolute path):-\`\`\`sh-sh "${shimPath}" <command> [--node <id|title>] [-n <N>]+\`\`\`${shimFence(dialect)}+${shimCommand(shimPath, dialect)} <command> [--node <id|title>] [-n <N>]\`\`\`-+${windowsNote.length ? `\n${windowsNote.join('\n')}\n` : ''}Commands:- \`list\` — list the nodes you are linked to (start here).- \`summary [--node X] [-n 15]\` — the last N lines of a linked node's conversation.diff --git a/src/core/context-link.ts b/src/core/context-link.tsindex d3c926e72..0e654cf41 100644--- a/src/core/context-link.ts+++ b/src/core/context-link.ts@@ -17,7 +17,7 @@import fs from 'fs'import path from 'path'import { platform } from './platform'-import { writeManagedHookFileAtomic } from './agents/hooks/install-helper'+import { syncWindowsShLauncher, writeManagedHookFileAtomic } from './agents/hooks/install-helper'import { IPC } from '../shared/ipc'import type { ContextLinkInfo, ContextLinkMap } from '../shared/types'import { type PtyManager } from './pty-manager'@@ -63,6 +63,8 @@ function writeCliFiles(): void {fs.mkdirSync(d, { recursive: true })// Temp + rename, never a truncating write: agents execute this file (see canvas-control.ts).writeManagedHookFileAtomic(cliShimPath(), buildContextShimScript(codexThreadIdentityRoot()), undefined, 0o755)+ // Windows: `context.cmd` beside it for PowerShell-run agents (see canvas-control.ts).+ syncWindowsShLauncher(d, 'context.sh')// Sweep the retired Electron-as-Node CLI off upgraders' disks: the shim no longer execs it,// and it would sit there pointing at a binary path that moves with every app update.try {@@ -317,5 +319,7 @@ export function initContextLink(ptyManager: PtyManager, platformDeps: ContextLinreturn}platform().handle(IPC.contextLinkSetLinks, (map: ContextLinkMap) => setContextLinks(map))- platform().handle(IPC.contextLinkInfo, () => ({ shimPath: cliShimPath() }))+ // `platform` is THIS core's: the renderer words the connect-time note for the machine whose shim+ // it names (a Windows core's non-claude agents run the `.cmd` launcher), never the viewer's.+ platform().handle(IPC.contextLinkInfo, () => ({ shimPath: cliShimPath(), platform: process.platform }))}diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.tsindex e29bdf838..2629c595b 100644--- a/src/main/canvas-control-core.test.ts+++ b/src/main/canvas-control-core.test.ts@@ -1684,3 +1684,27 @@ describe('one-way context links (issue #852) — agent-facing docs', () => {expect(buildCanvasSkillBody('/x/nodeterm.sh')).toContain('--one-way')})})++// Windows (`windows-cmd` dialect): what a PowerShell-run agent reads. The POSIX default is pinned+// byte-for-byte, because every SSH-host skill is built without a dialect.+describe('buildCanvasSkillBody — shim invocation dialect', () => {+ it('the default is the historical `sh` block, unchanged', () => {+ const body = buildCanvasSkillBody('/x/nodeterm.sh')+ expect(body).toContain('```sh\nsh "/x/nodeterm.sh" <verb> [args]\n```\n\nFlags take a value')+ expect(body).toBe(buildCanvasSkillBody('/x/nodeterm.sh', 'posix'))+ expect(body).not.toContain('nodeterm.cmd')+ })++ it('windows-cmd: PowerShell call of the .cmd launcher, plus the cmd/Git Bash spellings and the batch limit', () => {+ const body = buildCanvasSkillBody('C:\\d\\nodeterm.sh', 'windows-cmd')+ expect(body).toContain('```powershell\n& "C:\\d\\nodeterm.cmd" <verb> [args]\n```')+ expect(body).toContain('Git for Windows')+ expect(body).toContain('In cmd.exe drop the leading `& `')+ expect(body).toContain('`sh "C:\\d\\nodeterm.sh"`')+ expect(body).toContain('`--prompt-file`')+ // Only the invocation block changes: the verb reference after it is the same text.+ const tail = (b: string) => b.slice(b.indexOf('Flags take a value'))+ expect(tail(body)).toBe(tail(buildCanvasSkillBody('C:\\d\\nodeterm.sh')))+ })+})+diff --git a/src/main/canvas-control.ts b/src/main/canvas-control.tsindex e1dd534c7..339424d4f 100644--- a/src/main/canvas-control.ts+++ b/src/main/canvas-control.ts@@ -13,7 +13,7 @@ import path from 'path'import { app } from 'electron'import { buildControlShimScript } from '../core/canvas-control-core'import { codexThreadIdentityRoot } from '../core/codex-identity-proxy'-import { writeManagedHookFileAtomic } from '../core/agents/hooks/install-helper'+import { syncWindowsShLauncher, writeManagedHookFileAtomic } from '../core/agents/hooks/install-helper'function dir(): string {return path.join(app.getPath('userData'), 'canvas-control')@@ -30,6 +30,9 @@ function writeCliFiles(): void {// Temp + rename, never a truncating write: agents execute this file, and a shim caught half// written is a canvas call that exits 0 having done nothing.writeManagedHookFileAtomic(canvasControlShimPath(), buildControlShimScript(codexThreadIdentityRoot()), undefined, 0o755)+ // Windows: `nodeterm.cmd` beside it, which PowerShell-run agents are told to call (it runs this+ // same script through Git for Windows' sh.exe). Elsewhere a stray copy is removed.+ syncWindowsShLauncher(d, 'nodeterm.sh')// Sweep the retired Electron-as-Node CLI off upgraders' disks — the shim no longer execs it,// so it would sit there forever pointing at a binary path that moves with every app update.try {diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 011d2fd9e..bc4d855d8 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -4757,10 +4757,13 @@ export function Canvas() {async (selfId: string, otherId: string) => {if (useAgentStatus.getState().byId[selfId]?.state === 'working') returnconst title = (nodesRef.current.find((n) => n.id === otherId)?.data.title as string) || 'a linked node'- const { shimPath } = await window.nodeTerminal.contextLink.info()+ const { shimPath, platform: shimHost } = await window.nodeTerminal.contextLink.info()+ // The shim named here is the LOCAL core's; an SSH node's agent runs on its host, whose skill+ // is POSIX, so only a local node gets the host-platform wording (`.cmd` on Windows).+ const selfData = nodesRef.current.find((n) => n.id === selfId)?.datavoid api.pty.sendText(selfId,- buildContextLinkNote(agentIdOf(selfId), title, shimPath)+ buildContextLinkNote(agentIdOf(selfId), title, shimPath, isRemoteSessionNode(selfData) ? undefined : shimHost)).then(reportTextDelivery)},[agentIdOf]@@ -14571,7 +14574,10 @@ export function Canvas() {}const lenses = parseLenses(args.lenses)const wantJudge = (args.synthesis ?? 'on').trim().toLowerCase() !== 'off'- const { shimPath: vShim } = await window.nodeTerminal.contextLink.info()+ const { shimPath: vShim, platform: vShimHost } = await window.nodeTerminal.contextLink.info()+ // Reviewers open where the target's cwd says; an SSH-project panel runs on the host,+ // whose shim is POSIX, so only a local panel gets the host-platform wording.+ const vHost = sshFor(target.data.cwd as string | undefined) ? undefined : vShimHostconst targetTitle = (target.data.title as string) || targetIdconst targetCwd = target.data.cwd as string | undefinedconst live = nodesRef.current as CanvasNode[]@@ -14600,6 +14606,7 @@ export function Canvas() {targetId,agentId: reviewAgent,shimPath: vShim,+ hostPlatform: vHost,focus: args.focus}))@@ -14632,7 +14639,8 @@ export function Canvas() {lenses,targetTitle,agentId: reviewAgent,- shimPath: vShim+ shimPath: vShim,+ hostPlatform: vHost}))const judge = wantJudgediff --git a/src/renderer/lib/noteLink.test.ts b/src/renderer/lib/noteLink.test.tsindex f79c75c8b..034bab609 100644--- a/src/renderer/lib/noteLink.test.ts+++ b/src/renderer/lib/noteLink.test.ts@@ -231,6 +231,22 @@ describe('buildContextLinkNote', () => {expect(msg).toContain('Builder')expect(msg).not.toContain('\n')})+ it('a Windows core: codex/gemini are told to run the .cmd launcher; claude keeps the skill line', () => {+ const msg = buildContextLinkNote('codex', 'Builder', 'C:\\d\\context.sh', 'win32')+ expect(msg).toContain('run: & "C:\\d\\context.cmd" list')+ expect(msg).not.toContain('sh "')+ expect(msg).not.toContain('\n')+ expect(buildContextLinkNote('claude', 'Builder', 'C:\\d\\context.sh', 'win32')).toBe(+ buildContextLinkNote('claude', 'Builder', 'C:\\d\\context.sh')+ )+ })+ it('a POSIX or unknown core (remote node, older core) keeps the exact sh line', () => {+ for (const host of [undefined, 'linux', 'darwin']) {+ expect(buildContextLinkNote('gemini', 'Builder', '/x/context.sh', host)).toBe(+ buildContextLinkNote('gemini', 'Builder', '/x/context.sh')+ )+ }+ })it('every variant says the note is informational — no action now', () => {// The message is injected + submitted as a prompt, so an agent that reads it as a task// launches an unsolicited investigation (observed with gemini). It must self-defuse.diff --git a/src/renderer/lib/noteLink.ts b/src/renderer/lib/noteLink.tsindex 1eeeb521b..2fe06502c 100644--- a/src/renderer/lib/noteLink.ts+++ b/src/renderer/lib/noteLink.ts@@ -5,6 +5,7 @@import type { Edge } from '@xyflow/react'import { oneLine } from '@shared/one-line'import type { BridgeLink } from '@shared/types'+import { shimCommand, shimDialectFor } from '@shared/agents/shim-invocation'import {classifyLink,planBridges,@@ -165,7 +166,10 @@ export function buildNotePushMessage(title: string, text: string, agentId?: striexport function buildContextLinkNote(agentId: string | undefined,otherTitle: string,- shimPath: string+ shimPath: string,+ /** `process.platform` of the core whose shim this is (`contextLink.info()`); undefined for a+ * remote node or an older core ⇒ the POSIX line. On win32 a non-claude agent gets the `.cmd`. */+ hostPlatform?: string): string {const other = oneLine(otherTitle)// Both variants must self-defuse: the note is injected + submitted as a prompt, and an@@ -174,7 +178,7 @@ export function buildContextLinkNote(if (!agentId || agentId === 'claude') {return `[nodeterm] You are now linked to "${other}". Use the get-linked-context skill to read its context when you need it. No action needed now — just acknowledge briefly.`}- return `[nodeterm] You are now linked to "${other}". When you need its context (and only then) run: sh "${shimPath}" list — then summary | transcript | terminal --node <id>. Details are in the get-linked-context section of your global agent instructions. No action needed now — acknowledge briefly and do not run these commands yet.`+ return `[nodeterm] You are now linked to "${other}". When you need its context (and only then) run: ${shimCommand(shimPath, shimDialectFor(agentId, hostPlatform))} list — then summary | transcript | terminal --node <id>. Details are in the get-linked-context section of your global agent instructions. No action needed now — acknowledge briefly and do not run these commands yet.`}// The link-map builders moved to @shared: the Server Edition derives the same map from persisteddiff --git a/src/renderer/lib/verifyPanel.test.ts b/src/renderer/lib/verifyPanel.test.tsindex be6db0039..6d21ed152 100644--- a/src/renderer/lib/verifyPanel.test.ts+++ b/src/renderer/lib/verifyPanel.test.ts@@ -47,6 +47,19 @@ describe('verifyLensPrompt', () => {expect(codex).not.toContain('get-linked-context skill')})+ it('on a Windows core, a non-claude reviewer is told to run the .cmd launcher', () => {+ const win = { ...base, shimPath: 'C:\\d\\context.sh', hostPlatform: 'win32' }+ const codex = verifyLensPrompt({ ...win, lens: 'tests', agentId: 'codex' })+ expect(codex).toContain('running: & "C:\\d\\context.cmd" summary --node <id>')+ expect(verifySynthesisPrompt({ ...win, lenses: ['tests'], agentId: 'gemini' })).toContain('& "C:\\d\\context.cmd"')+ // claude and every POSIX/unknown host keep their exact text.+ expect(verifyLensPrompt({ ...win, lens: 'tests', agentId: 'claude' })).toContain('get-linked-context skill')+ expect(verifyLensPrompt({ ...base, lens: 'tests', agentId: 'codex', hostPlatform: 'linux' })).toBe(+ verifyLensPrompt({ ...base, lens: 'tests', agentId: 'codex' })+ )+ expect(verifyLensPrompt({ ...base, lens: 'tests', agentId: 'codex' })).toContain('running: sh "/x/nodeterm.sh" summary')+ })+it('gives an unknown lens a generic brief instead of dropping it', () => {expect(verifyLensPrompt({ ...base, lens: 'accessibility' })).toContain('problems of this kind: accessibility'diff --git a/src/renderer/lib/verifyPanel.ts b/src/renderer/lib/verifyPanel.tsindex 6aba438a1..4db73069a 100644--- a/src/renderer/lib/verifyPanel.ts+++ b/src/renderer/lib/verifyPanel.ts@@ -4,6 +4,7 @@// agree with each other, which reads as confirmation while adding no evidence.//// Kept free of React/store imports so the lens table and the prompt wording are unit-testable.+import { shimCommand, shimDialectFor } from '@shared/agents/shim-invocation'/** Lens id → what that reviewer is told to hunt for. */const LENS_BRIEFS: Record<string, string> = {@@ -50,10 +51,10 @@ export function parseLenses(raw: string | undefined): string[] {}/** How a given agent is told to read a linked node's work. */-function readInstruction(agentId: string | undefined, shimPath: string): string {+function readInstruction(agentId: string | undefined, shimPath: string, hostPlatform?: string): string {return !agentId || agentId === 'claude'? 'read its work with the get-linked-context skill (summary first, then transcript if you need detail)'- : `read its work by running: sh "${shimPath}" summary --node <id> (then transcript --node <id> for detail) — see the get-linked-context section of your global agent instructions`+ : `read its work by running: ${shimCommand(shimPath, shimDialectFor(agentId, hostPlatform))} summary --node <id> (then transcript --node <id> for detail) — see the get-linked-context section of your global agent instructions`}/**@@ -71,13 +72,15 @@ export function verifyLensPrompt(opts: {targetId: stringagentId?: stringshimPath: string+ /** `process.platform` of the core whose shim this is; undefined (remote, unknown) ⇒ POSIX. */+ hostPlatform?: stringfocus?: string}): string {const brief = LENS_BRIEFS[opts.lens] ?? `problems of this kind: ${opts.lens}`const focus = opts.focus?.trim() ? ` The work under review is specifically about: ${opts.focus.trim()}.` : ''return [`You are one reviewer on a verification panel, looking at the work of the linked node "${opts.targetTitle}" (${opts.targetId}) through a single lens: ${opts.lens}.`,- `First ${readInstruction(opts.agentId, opts.shimPath)}, and read enough of the actual code it touched to judge it for yourself rather than trusting its summary.${focus}`,+ `First ${readInstruction(opts.agentId, opts.shimPath, opts.hostPlatform)}, and read enough of the actual code it touched to judge it for yourself rather than trusting its summary.${focus}`,`Then hunt specifically for ${brief}.`,`Report only what you can point at — a file:line, a concrete input that breaks it, or a command you ran and its output. If this lens turns up nothing real, say "nothing found" and stop; do not pad the report to look thorough.`,`Do NOT change any files and do NOT fix anything — other reviewers are reading the same checkout right now, and repairing is a separate job from finding.`@@ -90,10 +93,11 @@ export function verifySynthesisPrompt(opts: {targetTitle: stringagentId?: stringshimPath: string+ hostPlatform?: string}): string {return [`You are the judge of a verification panel on the work of "${opts.targetTitle}". ${opts.lenses.length} reviewers each examined it through one lens: ${opts.lenses.join(', ')}.`,- `Each reviewer is linked to you — ${readInstruction(opts.agentId, opts.shimPath)} for each of them.`,+ `Each reviewer is linked to you — ${readInstruction(opts.agentId, opts.shimPath, opts.hostPlatform)} for each of them.`,`Then produce ONE verdict: drop every finding the reviewer could not point at concretely, merge the duplicates that several lenses reported, and rank what survives by what it would actually cost to ship.`,`Say plainly which lenses found nothing, and say plainly if nothing survived at all — an empty verdict is a real result, not a failed one.`,`Do NOT fix anything; report.`diff --git a/src/server/canvas-control.ts b/src/server/canvas-control.tsindex e34e6fe41..794a7ca6e 100644--- a/src/server/canvas-control.ts+++ b/src/server/canvas-control.ts@@ -28,6 +28,7 @@ import {} from '../core/agent-status-mirror'import type { BoardLogHandlers } from '../core/board-log-handlers'import { buildControlShimScript } from '../core/canvas-control-core'+import { syncWindowsShLauncher } from '../core/agents/hooks/install-helper'import { codexIdentityCaps } from '../core/codex-identity-caps'import { codexThreadIdentityRoot } from '../core/codex-identity-proxy'import { claudeCliCaps, type ClaudeCliCaps } from '../core/claude-cli'@@ -109,6 +110,9 @@ function writeShim(): void {} catch {/* best effort on filesystems without POSIX modes */}+ // The `.cmd` launcher the skill names on a Windows host (skillsFor picks that dialect from this+ // core's platform); a no-op removal on the Linux hosts the Server Edition targets.+ syncWindowsShLauncher(dir, 'nodeterm.sh')// Same upgrade sweep as desktop: the POSIX shim replaced this Electron-as-Node script.try {fs.rmSync(path.join(dir, 'canvas-control-cli.mjs'), { force: true })diff --git a/src/shared/agents/config.ts b/src/shared/agents/config.tsindex a82d7f408..b6327d351 100644--- a/src/shared/agents/config.ts+++ b/src/shared/agents/config.ts@@ -411,6 +411,12 @@ export const SHARED_IDENTITY_CAPABLE = ['codex'] as const// session env (hook-server's buildPtyEnv, remoteHookEnvArgs), i.e. what makes the shim anything// other than a no-op.export const CANVAS_CONTROL_CAPABLE = ['claude', 'codex', 'gemini', 'opencode', 'grok', 'copilot'] as const+// Agents whose TOOL shell on Windows is POSIX: Claude Code runs its Bash tool (and its hooks)+// through Git Bash, so `sh "<shim>.sh"` works there exactly as on macOS/Linux. Every other agent+// runs tools in PowerShell (codex, gemini, copilot — measured in their sources) or cmd.exe, where+// `sh` is not on PATH on a stock Git install; they are told to run the `.cmd` launcher instead+// (`shimDialectFor` in ./shim-invocation.ts). Membership only matters on a win32 host.+export const POSIX_TOOL_SHELL_ON_WINDOWS = ['claude'] as const// Agents whose session start-up permission mode we can set (see AgentPermissionMode below).// claude and grok share the flag SPELLING and the value vocabulary// (`--permission-mode auto|plan|acceptEdits|bypassPermissions`; our `manual` = no flag = grok's own@@ -572,6 +578,7 @@ export const reportsSessionEnd = (id: AgentId): boolean => includes(SESSION_END_export const canRename = (id: AgentId): boolean => includes(RENAME_CAPABLE, id)export const canReadTitle = (id: AgentId): boolean => includes(TITLE_READ_CAPABLE, id)export const canControlCanvas = (id: AgentId): boolean => includes(CANVAS_CONTROL_CAPABLE, id)+export const usesPosixToolShellOnWindows = (id: AgentId): boolean => includes(POSIX_TOOL_SHELL_ON_WINDOWS, id)export const hasPermissionMode = (id: AgentId): boolean => includes(PERMISSION_MODE_CAPABLE, id)export const canSwitchModel = (id: AgentId): boolean => includes(MODEL_SWITCH_CAPABLE, id)export const hasSharedIdentity = (id: AgentId): boolean => includes(SHARED_IDENTITY_CAPABLE, id)diff --git a/src/shared/agents/shim-invocation.test.ts b/src/shared/agents/shim-invocation.test.tsnew file mode 100644index 000000000..e2b5b9adc--- /dev/null+++ b/src/shared/agents/shim-invocation.test.ts@@ -0,0 +1,46 @@+import { describe, expect, it } from 'vitest'+import { cmdShimPathFor, shimCommand, shimDialectFor, shimFence, windowsShimNoteLines } from './shim-invocation'+import { setCustomAgentBaseResolver } from './config'++describe('shimDialectFor', () => {+ it('only a win32 host changes anything', () => {+ for (const host of ['darwin', 'linux', undefined, null, 'freebsd']) {+ for (const agent of ['claude', 'codex', 'gemini', 'grok', 'copilot', 'opencode', undefined]) {+ expect(shimDialectFor(agent, host), `${agent}@${host}`).toBe('posix')+ }+ }+ })++ it('win32: claude stays POSIX (Git Bash), every other agent runs the .cmd launcher', () => {+ expect(shimDialectFor('claude', 'win32')).toBe('posix')+ for (const agent of ['codex', 'gemini', 'grok', 'copilot', 'opencode', 'my-custom', undefined]) {+ expect(shimDialectFor(agent, 'win32'), String(agent)).toBe('windows-cmd')+ }+ })++ it('a custom agent inherits its base harness\'s tool shell', () => {+ setCustomAgentBaseResolver((id) => (id === 'my-claude' ? 'claude' : undefined))+ try {+ expect(shimDialectFor('my-claude', 'win32')).toBe('posix')+ } finally {+ setCustomAgentBaseResolver(null)+ }+ })+})++describe('shim invocation strings', () => {+ it('posix is the historical `sh "<path>"`', () => {+ expect(shimCommand('/u/nodeterm.sh')).toBe('sh "/u/nodeterm.sh"')+ expect(shimCommand('/u/nodeterm.sh', 'posix')).toBe('sh "/u/nodeterm.sh"')+ expect(shimFence()).toBe('sh')+ expect(windowsShimNoteLines('/u/nodeterm.sh', 'posix')).toEqual([])+ })++ it('windows-cmd calls the .cmd beside the shim with PowerShell\'s call operator', () => {+ expect(cmdShimPathFor('C:\\d\\nodeterm.sh')).toBe('C:\\d\\nodeterm.cmd')+ expect(cmdShimPathFor('context.sh')).toBe('context.cmd')+ expect(shimCommand('C:\\d\\context.sh', 'windows-cmd')).toBe('& "C:\\d\\context.cmd"')+ expect(shimFence('windows-cmd')).toBe('powershell')+ expect(windowsShimNoteLines('C:\\d\\context.sh', 'windows-cmd').join(' ')).toContain('Git for Windows')+ })+})diff --git a/src/shared/agents/shim-invocation.ts b/src/shared/agents/shim-invocation.tsnew file mode 100644index 000000000..48edf5950--- /dev/null+++ b/src/shared/agents/shim-invocation.ts@@ -0,0 +1,56 @@+// How an agent is told to RUN one of nodeterm's CLI shims (canvas control's `nodeterm.sh`, context+// link's `context.sh`). The shims are POSIX `sh` scripts everywhere; on a Windows host each one+// also gets a `.cmd` launcher beside it (`buildWindowsShLauncher`) that finds Git for Windows'+// `sh.exe` and runs the same script — because every agent except claude runs its tool calls in+// PowerShell or cmd.exe, where `sh "<path>"` is "not recognized".+//+// The dialect is decided by the platform of the machine whose shim it is (the core that wrote it,+// never the viewer), and per agent through `usesPosixToolShellOnWindows`. Every caller defaults to+// `posix`, so macOS/Linux and every SSH-host skill stay byte-identical.+import { usesPosixToolShellOnWindows, type AgentId } from './config'++export type ShimDialect = 'posix' | 'windows-cmd'++/** The dialect `agentId`'s tool shell needs on a host running `hostPlatform` (`process.platform`+ * of the core that owns the shim; undefined = unknown or remote ⇒ posix, the historical line). */+export function shimDialectFor(agentId: AgentId | undefined, hostPlatform: string | null | undefined): ShimDialect {+ if (hostPlatform !== 'win32') return 'posix'+ return agentId && usesPosixToolShellOnWindows(agentId) ? 'posix' : 'windows-cmd'+}++/** The `.cmd` launcher's path (or file name) for a `.sh` shim: `nodeterm.sh` → `nodeterm.cmd`. The+ * ONE spelling of that rule — the writer and every instruction derive from it. */+export function cmdShimPathFor(shPath: string): string {+ return shPath.replace(/\.sh$/, '') + '.cmd'+}++/**+ * The leading command an agent types to run the shim. `posix` is the historical `sh "<path>"`.+ * `windows-cmd` is `& "<path>.cmd"` — PowerShell's call operator, which every PowerShell-run agent+ * needs (a bare quoted path is a string literal there, the #685 lesson). cmd.exe would need the+ * same line without the `& `; the skill text says so (`windowsShimNoteLines`).+ */+export function shimCommand(shPath: string, dialect: ShimDialect = 'posix'): string {+ return dialect === 'windows-cmd' ? `& "${cmdShimPathFor(shPath)}"` : `sh "${shPath}"`+}++/** The code-fence language for the shim block. */+export function shimFence(dialect: ShimDialect = 'posix'): string {+ return dialect === 'windows-cmd' ? 'powershell' : 'sh'+}++/**+ * The paragraph a Windows (`windows-cmd`) skill adds under its shim block: what the launcher needs,+ * the other two shells' spelling, and the batch quoting limit. Empty for posix.+ */+export function windowsShimNoteLines(shPath: string, dialect: ShimDialect, fileFlagHint?: string): string[] {+ if (dialect !== 'windows-cmd') return []+ const fileHint = fileFlagHint ? ` (\`${fileFlagHint}\`)` : ''+ return [+ `This machine runs Windows. \`${cmdShimPathFor(shPath)}\` runs the same POSIX shim through Git for`,+ 'Windows\' `sh.exe`, so Git for Windows must be installed (the launcher says so if it is not).',+ 'The line above is PowerShell. In cmd.exe drop the leading `& `; in Git Bash run',+ `\`sh "${shPath}"\` instead. The launcher is a batch file, which re-reads its arguments: keep \`%\`,`,+ `\`^\`, \`&\`, \`|\`, \`<\`, \`>\` and double quotes out of inline values and put such text in a file${fileHint}.`+ ]+}diff --git a/src/shared/types.ts b/src/shared/types.tsindex 679d2e87a..9b6c290e3 100644--- a/src/shared/types.ts+++ b/src/shared/types.ts@@ -2886,8 +2886,10 @@ export type ContextLinkMap = Record<string, ContextLinkInfo[]>export interface ContextLinkApi {/** Push the current link map to main; main rewrites the per-node link files. */setLinks(map: ContextLinkMap): Promise<void>- /** Static facts the renderer needs to compose link messages: the CLI shim's absolute path. */- info(): Promise<{ shimPath: string }>+ /** Static facts the renderer needs to compose link messages: the CLI shim's absolute path, and+ * the `process.platform` of the core that wrote it (absent from an older core ⇒ treat as POSIX).+ * On `win32` a non-claude agent is told to run the `.cmd` launcher beside the shim. */+ info(): Promise<{ shimPath: string; platform?: string }>}/** One usage window (5h session or 7d weekly) as shown in the indicator. */