@lardexx/arenacode 2.9.0 → 2.10.0

package/README.md

@@ -170,8 +170,15 @@ screenshots are `XGetImage` + `XGetPixel` encoded to PNG by the client itself (z
 and the X events the server delivered are compared with the requested keycodes, chords, buttons and pixels. On Wayland
 the XWayland display is used. `ui app launch` still starts the program's own `.desktop` command; nothing else is spawned.
 
-**macOS**: grant Accessibility to your terminal, and `brew install cliclick` for the mouse. On macOS/Linux the
-accessibility tree is not read: `ui state` returns windows and geometry as elements.
+**macOS** is native too, again with no helper binaries: mouse with `CGEventCreateMouseEvent` + `CGEventPost`
+(left/right/middle, double and triple click through the click-state field, drag interpolated), keyboard with
+`CGEventCreateKeyboardEvent` plus modifier *flags* (`cmd`, `ctrl`, `alt`, `shift`) and Apple's fixed `kVK_*`
+keycodes, typing through `CGEventKeyboardSetUnicodeString` so any character or emoji goes in without a layout,
+windows from `CGWindowListCopyWindowInfo` (number, bounds, owner pid), screenshots from `CGDisplayCreateImage`
+converted from BGRA to PNG by the client. `brew install cliclick` is gone. Only what CoreGraphics cannot do —
+launch an app, bring a window to the front, resize it — still uses `osascript`, which ships with macOS. Grant the
+terminal **Accessibility** (input) and **Screen Recording** (pixels) in System Settings → Privacy & Security.
+On macOS/Linux the accessibility tree is not read: `ui state` returns windows and geometry as elements.
 
 **Ask and Proceed / Proceed.** The desktop's Settings switch, `ctrl+x a` here (also `/ask`, `/proceed`,
 `--proceed`, and `arenacode config set approval proceed`). The default, **Ask and Proceed**, asks before commands,
@@ -254,7 +261,7 @@ The agent never touches your PC directly: it asks, and this client shows a card.
 
 | Card | Source | Executed here |
 |---|---|---|
-| **terminal** | `POST /task/<id>/local-exec` | PowerShell / `cmd` / WSL on Windows, `/bin/sh` elsewhere — asked before running unless `--yes` |
+| **terminal** | `POST /task/<id>/local-exec` | your shell — zsh/bash/sh/fish on macOS and Linux, PowerShell/pwsh/cmd/WSL/Git Bash on Windows (see [Shells](#shells)) — asked before running unless `--yes` |
 | **files** | `local-fs` | `ls`, `stat`, `read`, `write`, `replace`, `find`, `mkdir`, `mv`, `rm`, `pull`, `git_status`, `git_log`, `git_diff`, `git_commit`, `git_revert`, `git_publish` |
 | **plan** | `local-ui` `plan` | approve / reject / ask for a revision, right in the terminal |
 | **file from the agent** | `local_file` | downloaded from `GET /file?raw=1` into the open folder |
@@ -264,17 +271,30 @@ Every file path is resolved **inside the open folder**; paths that escape it are
 the folder itself. Local operations run with your user's permissions — `--confirm-writes` adds a confirmation for
 mutating file operations, `--yes` skips confirmations for terminal commands.
 
-### Not available in a terminal
+### Shells
 
-The desktop client can drive the whole PC (mouse, keyboard, screenshots, app launching — `local-ui`
-`control` / `type` / `keystroke` / `screenshot` / `app` / `state` / `apps` / `multi_*`). A terminal cannot, so
-those cards are answered with an explicit error instead of silently doing nothing:
+Terminal cards run in a real shell, and which one is not fixed:
 
-```json
-{ "ok": false, "error": "operation \"screenshot\" is not available in the terminal client: the ArenaCode desktop client is required" }
+| Platform | Shells |
+|---|---|
+| **Windows** | `powershell` (default), `pwsh`, `cmd`, `wsl`, `bash` (Git Bash when installed, otherwise the WSL bash) |
+| **macOS / Linux** | `zsh`, `bash`, `sh`, `fish`, `dash`, `ksh` — or any absolute path |
+
+The order is: the shell the **bridge** names in the `local-exec` request → the shell **you pinned** →
+your **login shell** (`$SHELL`, e.g. `zsh` on macOS, `bash` on most Linux boxes; PowerShell on Windows).
+Pin it with any of:
+
+```
+arenacode --shell zsh
+arenacode config set shell zsh
+/shell              # in the TUI: pick from the shells installed on this machine
 ```
 
-Everything else in the protocol is implemented.
+`sysinfo` reports `shell` and the full `shells` list, and the `!command` prompt line in the TUI runs in the
+same shell as the agent's cards. Commands are passed as a single argv entry (`zsh -lc '<command>'`,
+`cmd.exe /d /s /c '<command>'`, `powershell.exe -NoProfile -NonInteractive -Command '<command>'`), so quotes,
+`$variables` and pipes are never re-quoted on the way through. `test/shell.js` checks every mapping and runs
+real commands through `sh`/`bash`.
 
 ## How it talks to the bridge
 
@@ -319,7 +339,8 @@ release it on the bridge with `keys unbind <ID>`).
   "pc_access": true,
   "device": "",
   "vision": false,
-  "idle_timeout": 180
+  "idle_timeout": 180,
+  "shell": ""
 }
 ```
 
@@ -328,7 +349,7 @@ Node client cannot, so the key sits in that file — keep it readable only by yo
 (`arenacode keys` on the bridge side: `python3 bridge_server.py keys create "laptop CLI"`).
 
 Environment variables override the file: `ARENACODE_URL`, `ARENACODE_KEY`, `ARENACODE_FOLDER`,
-`ARENACODE_CONFIG`.
+`ARENACODE_SHELL`, `ARENACODE_CONFIG`.
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lardexx/arenacode",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Terminal client for ArenaCode: talks to an arena-bridge, streams the Agent Mode timeline, and runs local commands, file operations and computer automation on your PC (windows-use.dll on Windows, Xlib/XTest on Linux, osascript on macOS). Node port of the ArenaCode desktop client.",
   "license": "MIT",
   "type": "commonjs",
@@ -20,7 +20,7 @@
     "vendor/"
   ],
   "scripts": {
-    "test": "node test/integration.js && node test/parity.js && node test/automation.js && node test/native.js"
+    "test": "node test/shell.js && node test/integration.js && node test/parity.js && node test/automation.js && node test/native.js"
   },
   "keywords": [
     "arenacode",

package/src/automation/linux.js

@@ -7,9 +7,9 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const zlib = require('node:zlib');
 const { spawn } = require('node:child_process');
 const { lib, fn } = require('./ffi');
+const { encodePng } = require('./png');
 
 const DISPLAY = () => process.env.DISPLAY || ':0';
 
@@ -356,8 +356,7 @@ function pressKeys(combo) {
   requireX();
   const parts = String(combo || '')
     .toLowerCase()
-    .split('+')
-    .map((p) => p.trim())
+    .split(/[\s+]+/)
     .filter(Boolean);
   if (!parts.length) return { ok: false, error: `unreadable key combination: ${combo}` };
   let repeat = 1;
@@ -553,43 +552,6 @@ function resizeWindow(handle, x, y, width, height) {
 
 // ---------------------------------------------------------------- screenshot
 
-function crc32(buf) {
-  let c = 0xffffffff;
-  for (let i = 0; i < buf.length; i += 1) {
-    c ^= buf[i];
-    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
-  }
-  return (c ^ 0xffffffff) >>> 0;
-}
-
-function pngChunk(type, data) {
-  const len = Buffer.alloc(4);
-  len.writeUInt32BE(data.length);
-  const body = Buffer.concat([Buffer.from(type, 'ascii'), data]);
-  const crc = Buffer.alloc(4);
-  crc.writeUInt32BE(crc32(body));
-  return Buffer.concat([len, body, crc]);
-}
-
-function encodePng(rgb, width, height) {
-  const raw = Buffer.alloc((width * 3 + 1) * height);
-  for (let y = 0; y < height; y += 1) {
-    raw[y * (width * 3 + 1)] = 0;
-    rgb.copy(raw, y * (width * 3 + 1) + 1, y * width * 3, (y + 1) * width * 3);
-  }
-  const ihdr = Buffer.alloc(13);
-  ihdr.writeUInt32BE(width, 0);
-  ihdr.writeUInt32BE(height, 4);
-  ihdr[8] = 8;
-  ihdr[9] = 2;
-  return Buffer.concat([
-    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
-    pngChunk('IHDR', ihdr),
-    pngChunk('IDAT', zlib.deflateSync(raw, { level: 6 })),
-    pngChunk('IEND', Buffer.alloc(0)),
-  ]);
-}
-
 function screenshot(dest) {
   openDisplay();
   const XGetImage = fn(

package/src/automation/mac.js

@@ -0,0 +1,657 @@
+'use strict';
+
+// macOS backend: CoreGraphics through koffi. Same idea as the Linux one — no helper
+// binaries, no `brew install cliclick`: the mouse is CGEventCreateMouseEvent + CGEventPost,
+// the keyboard is CGEventCreateKeyboardEvent (chords) and CGEventKeyboardSetUnicodeString
+// (any character, emoji included), windows come from CGWindowListCopyWindowInfo and the
+// screenshot from CGDisplayCreateImage. Only what CoreGraphics cannot do at all —
+// launching an app, bringing a window to the front, resizing it — still goes through
+// `osascript`, which ships with macOS.
+//
+// Permissions: posting events needs Accessibility for the terminal (System Settings →
+// Privacy & Security → Accessibility); window titles and pixels need Screen Recording.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { fn, lib } = require('./ffi');
+const { encodePng } = require('./png');
+
+const CG = '/System/Library/Frameworks/CoreGraphics.framework/CoreGraphics';
+const CF = '/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation';
+
+const K_CG_HID_EVENT_TAP = 0;
+const K_CG_SESSION_EVENT_TAP = 1;
+
+const EVENT = {
+  leftDown: 1,
+  leftUp: 2,
+  rightDown: 3,
+  rightUp: 4,
+  mouseMoved: 5,
+  leftDragged: 6,
+  rightDragged: 7,
+  keyDown: 10,
+  keyUp: 11,
+  scrollWheel: 22,
+};
+const FIELD_CLICK_STATE = 1;
+
+const FLAG = {
+  shift: 0x20000,
+  control: 0x40000,
+  option: 0x80000,
+  command: 0x100000,
+};
+
+// kVK_* — fixed virtual keycodes; they do not depend on the keyboard layout.
+const VK = {
+  a: 0, s: 1, d: 2, f: 3, h: 4, g: 5, z: 6, x: 7, c: 8, v: 9,
+  b: 11, q: 12, w: 13, e: 14, r: 15, y: 16, t: 17,
+  1: 18, 2: 19, 3: 20, 4: 21, 6: 22, 5: 23, equal: 24, 9: 25, 7: 26, minus: 27,
+  8: 28, 0: 29, bracketright: 30, o: 31, u: 32, bracketleft: 33, i: 34, p: 35,
+  return: 36, l: 37, j: 38, quote: 39, k: 40, semicolon: 41, backslash: 42,
+  comma: 43, slash: 44, n: 45, m: 46, period: 47, tab: 48, space: 49, grave: 50,
+  backspace: 51, escape: 53, command: 55, shift: 56, capslock: 57, option: 58,
+  control: 59, rightshift: 60, rightoption: 61, rightcontrol: 62,
+  help: 114, home: 115, pageup: 116, delete: 117, end: 119, pagedown: 121,
+  left: 123, right: 124, down: 125, up: 126,
+  f1: 122, f2: 120, f3: 99, f4: 118, f5: 96, f6: 97, f7: 98, f8: 100,
+  f9: 101, f10: 109, f11: 103, f12: 111,
+  enter: 76,
+};
+
+const MODIFIERS = {
+  cmd: FLAG.command, command: FLAG.command, meta: FLAG.command, win: FLAG.command, super: FLAG.command,
+  ctrl: FLAG.control, control: FLAG.control,
+  alt: FLAG.option, option: FLAG.option, opt: FLAG.option,
+  shift: FLAG.shift,
+};
+
+// Names that AppleScript/linux-style tasks use, mapped to the kVK_* table.
+const ALIASES = {
+  esc: 'escape', delete: 'backspace', backspace: 'backspace', del: 'delete',
+  arrowup: 'up', arrowdown: 'down', arrowleft: 'left', arrowright: 'right',
+  up: 'up', down: 'down', left: 'left', right: 'right',
+  pgup: 'pageup', pgdn: 'pagedown', page_up: 'pageup', page_down: 'pagedown',
+  home: 'home', end: 'end', space: 'space', spacebar: 'space',
+  return: 'return', enter: 'return', tab: 'tab', capslock: 'capslock',
+  '[': 'bracketleft', ']': 'bracketright', ';': 'semicolon', '=': 'equal',
+  '-': 'minus', '`': 'grave', '\\': 'backslash', ',': 'comma', '.': 'period',
+  '/': 'slash', "'": 'quote',
+};
+
+let bound = null;
+
+function bindings() {
+  if (bound) return bound;
+  if (!lib(CG) || !lib(CF)) throw new Error('CoreGraphics not available (not macOS?)');
+  bound = {
+    CGMainDisplayID: fn(CG, 'CGMainDisplayID', 'unsigned int CGMainDisplayID(void)'),
+    CGDisplayPixelsWide: fn(CG, 'CGDisplayPixelsWide', 'unsigned long CGDisplayPixelsWide(unsigned int display)'),
+    CGDisplayPixelsHigh: fn(CG, 'CGDisplayPixelsHigh', 'unsigned long CGDisplayPixelsHigh(unsigned int display)'),
+    CGEventCreateMouseEvent: fn(
+      CG,
+      'CGEventCreateMouseEvent',
+      'void* CGEventCreateMouseEvent(void* source, int mouseType, double x, double y, int mouseButton)'
+    ),
+    CGEventCreateKeyboardEvent: fn(
+      CG,
+      'CGEventCreateKeyboardEvent',
+      'void* CGEventCreateKeyboardEvent(void* source, unsigned short virtualKey, bool keyDown)'
+    ),
+    CGEventCreateScrollWheelEvent2: fn(
+      CG,
+      'CGEventCreateScrollWheelEvent2',
+      'void* CGEventCreateScrollWheelEvent2(void* source, int units, unsigned int wheelCount, int wheel1, int wheel2, int wheel3)'
+    ),
+    CGEventPost: fn(CG, 'CGEventPost', 'void CGEventPost(int tap, void* event)'),
+    CGEventSetFlags: fn(CG, 'CGEventSetFlags', 'void CGEventSetFlags(void* event, unsigned long long flags)'),
+    CGEventSetIntegerValueField: fn(
+      CG,
+      'CGEventSetIntegerValueField',
+      'void CGEventSetIntegerValueField(void* event, int field, long long value)'
+    ),
+    CGEventKeyboardSetUnicodeString: fn(
+      CG,
+      'CGEventKeyboardSetUnicodeString',
+      'void CGEventKeyboardSetUnicodeString(void* event, unsigned long length, void* unicodeString)'
+    ),
+    CGWindowListCopyWindowInfo: fn(
+      CG,
+      'CGWindowListCopyWindowInfo',
+      'void* CGWindowListCopyWindowInfo(unsigned int option, unsigned int relativeToWindow)'
+    ),
+    CGDisplayCreateImage: fn(CG, 'CGDisplayCreateImage', 'void* CGDisplayCreateImage(unsigned int display)'),
+    CGImageGetWidth: fn(CG, 'CGImageGetWidth', 'unsigned long CGImageGetWidth(void* image)'),
+    CGImageGetHeight: fn(CG, 'CGImageGetHeight', 'unsigned long CGImageGetHeight(void* image)'),
+    CGImageGetBytesPerRow: fn(CG, 'CGImageGetBytesPerRow', 'unsigned long CGImageGetBytesPerRow(void* image)'),
+    CGImageGetBitsPerPixel: fn(CG, 'CGImageGetBitsPerPixel', 'unsigned long CGImageGetBitsPerPixel(void* image)'),
+    CGImageGetDataProvider: fn(CG, 'CGImageGetDataProvider', 'void* CGImageGetDataProvider(void* image)'),
+    CFDataGetBytePtr: fn(CF, 'CFDataGetBytePtr', 'const unsigned char* CFDataGetBytePtr(void* data)'),
+    CFDataGetLength: fn(CF, 'CFDataGetLength', 'long CFDataGetLength(void* data)'),
+    CFDataGetBytes: fn(CF, 'CFDataGetBytes', 'void CFDataGetBytes(void* data, void* buffer, unsigned long length)'),
+    CGDataProviderCopyData: fn(CF, 'CGDataProviderCopyData', 'void* CGDataProviderCopyData(void* provider)'),
+    CFRelease: fn(CF, 'CFRelease', 'void CFRelease(void* ref)'),
+    // CF containers are only aliases of the CoreFoundation types we read windows with
+    CFArrayGetCount: fn(CF, 'CFArrayGetCount', 'long CFArrayGetCount(void* array)'),
+    CFArrayGetValueAtIndex: fn(CF, 'CFArrayGetValueAtIndex', 'void* CFArrayGetValueAtIndex(void* array, long index)'),
+    CFDictionaryGetValue: fn(CF, 'CFDictionaryGetValue', 'void* CFDictionaryGetValue(void* dict, void* key)'),
+    CFStringCreateWithCString: fn(
+      CF,
+      'CFStringCreateWithCString',
+      'void* CFStringCreateWithCString(void* allocator, const char* cString, unsigned int encoding)'
+    ),
+    CFStringGetCString: fn(
+      CF,
+      'CFStringGetCString',
+      'bool CFStringGetCString(void* string, void* buffer, long bufferSize, unsigned int encoding)'
+    ),
+    CFStringGetLength: fn(CF, 'CFStringGetLength', 'long CFStringGetLength(void* string)'),
+    CFNumberGetValue: fn(CF, 'CFNumberGetValue', 'bool CFNumberGetValue(void* number, int type, void* valuePtr)'),
+    CFBooleanGetValue: fn(CF, 'CFBooleanGetValue', 'bool CFBooleanGetValue(void* boolean)'),
+  };
+  return bound;
+}
+
+function requireCG() {
+  if (process.platform !== 'darwin') throw new Error('the macOS backend runs on macOS only');
+  return bindings();
+}
+
+const K_CF_STRING_ENCODING_UTF8 = 0x08000100;
+
+function cfString(text) {
+  const b = bindings();
+  return b.CFStringCreateWithCString(null, String(text), K_CF_STRING_ENCODING_UTF8);
+}
+
+function cfToString(ref) {
+  if (!ref) return '';
+  const koffi = require('koffi');
+  const b = bindings();
+  const length = Number(b.CFStringGetLength(ref));
+  if (!Number.isFinite(length) || length < 0) return '';
+  const size = Math.max(16, length * 4 + 1);
+  const buffer = koffi.alloc('uint8_t', size);
+  if (!b.CFStringGetCString(ref, buffer, size, K_CF_STRING_ENCODING_UTF8)) return '';
+  return String(koffi.decode(buffer, 'uint8_t', size)).split('\0')[0];
+}
+
+function cfNumber(ref) {
+  if (!ref) return 0;
+  const koffi = require('koffi');
+  const out = koffi.alloc('double', 1);
+  const b = bindings();
+  // kCFNumberDoubleType = 13, kCFNumberSInt64Type = 4
+  if (b.CFNumberGetValue(ref, 13, out)) return Number(koffi.decode(out, 'double', 1));
+  return 0;
+}
+
+/** Reads a key out of the CGWindowList dictionaries. */
+function dictValue(dict, key, stringKey) {
+  const b = bindings();
+  const name = cfString(key);
+  let raw = null;
+  try {
+    raw = b.CFDictionaryGetValue(dict, name);
+    if (!raw) return stringKey ? '' : 0;
+    return stringKey ? cfToString(raw) : cfNumber(raw);
+  } finally {
+    if (name) b.CFRelease(name);
+  }
+}
+
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+// ------------------------------------------------------------------- input --
+
+function post(event, tap = K_CG_HID_EVENT_TAP) {
+  const b = bindings();
+  b.CGEventPost(tap, event);
+  if (event) b.CFRelease(event);
+  // let the window server digest the event before the next one
+  sleep(2);
+}
+
+function moveMouse(x, y) {
+  const b = requireCG();
+  const event = b.CGEventCreateMouseEvent(null, EVENT.mouseMoved, Number(x), Number(y), 0);
+  if (!event) return { ok: false, error: 'CGEventCreateMouseEvent failed' };
+  post(event);
+  return { ok: true, x, y };
+}
+
+function buttonEvent(type, x, y, button = 'left') {
+  const b = bindings();
+  const which = button === 'right' ? 1 : button === 'middle' ? 2 : 0;
+  return b.CGEventCreateMouseEvent(null, type, Number(x), Number(y), which);
+}
+
+function click(x, y, { button = 'left', count = 1 } = {}) {
+  const b = requireCG();
+  const clicks = Math.max(1, Math.trunc(count) || 1);
+  const down = button === 'right' ? EVENT.rightDown : EVENT.leftDown;
+  const up = button === 'right' ? EVENT.rightUp : EVENT.leftUp;
+  moveMouse(x, y);
+  for (let i = 1; i <= Math.min(3, clicks); i += 1) {
+    const press = buttonEvent(down, x, y, button);
+    if (press) {
+      b.CGEventSetIntegerValueField(press, FIELD_CLICK_STATE, i);
+      post(press);
+    }
+    const release = buttonEvent(up, x, y, button);
+    if (release) {
+      b.CGEventSetIntegerValueField(release, FIELD_CLICK_STATE, i);
+      post(release);
+    }
+  }
+  return { ok: true, x, y, button, count: clicks };
+}
+
+function mouseButton(x, y, button, down) {
+  const b = requireCG();
+  moveMouse(x, y);
+  const type = button === 'right' ? (down ? EVENT.rightDown : EVENT.rightUp) : down ? EVENT.leftDown : EVENT.leftUp;
+  const event = buttonEvent(type, x, y, button);
+  if (!event) return { ok: false, error: 'CGEventCreateMouseEvent failed' };
+  post(event);
+  return { ok: true, x, y, button };
+}
+
+function drag(x, y, x2, y2) {
+  const b = requireCG();
+  const downEvent = buttonEvent(EVENT.leftDown, x, y, 'left');
+  if (!downEvent) return { ok: false, error: 'CGEventCreateMouseEvent failed' };
+  post(downEvent);
+  const steps = 12;
+  for (let i = 1; i <= steps; i += 1) {
+    const px = Math.round(x + ((x2 - x) * i) / steps);
+    const py = Math.round(y + ((y2 - y) * i) / steps);
+    const moved = b.CGEventCreateMouseEvent(null, EVENT.leftDragged, px, py, 0);
+    if (moved) post(moved);
+  }
+  const upEvent = buttonEvent(EVENT.leftUp, x2, y2, 'left');
+  if (upEvent) post(upEvent);
+  const released = b.CGEventCreateMouseEvent(null, EVENT.mouseMoved, x2, y2, 0);
+  if (released) post(released);
+  return { ok: true, from: [x, y], to: [x2, y2] };
+}
+
+function scroll(amount, x = null, y = null) {
+  const b = requireCG();
+  if (x !== null && y !== null) moveMouse(x, y);
+  const lines = Math.max(1, Math.abs(Math.trunc(amount) || 1));
+  const signed = (Math.trunc(amount) || 1) > 0 ? lines : -lines;
+  const event = b.CGEventCreateScrollWheelEvent2(null, 1 /* line */, 1, signed, 0, 0);
+  if (!event) return { ok: false, error: 'CGEventCreateScrollWheelEvent2 failed' };
+  post(event);
+  return { ok: true, amount };
+}
+
+/** Types text as unicode: layout-independent, works for é, ü, 中文, emoji. */
+function typeText(text, x = null, y = null) {
+  const b = requireCG();
+  if (x !== null && y !== null) click(x, y);
+  const value = String(text || '');
+  let typed = 0;
+  for (const ch of value) {
+    const utf16 = Buffer.from(ch, 'utf16le');
+    const length = utf16.length / 2;
+    const down = b.CGEventCreateKeyboardEvent(null, 0, true);
+    const up = b.CGEventCreateKeyboardEvent(null, 0, false);
+    if (!down || !up) return { ok: false, error: 'CGEventCreateKeyboardEvent failed' };
+    const koffi = require('koffi');
+    const buffer = koffi.alloc('uint16_t', length);
+    koffi.encode(buffer, koffi.array('uint16_t', length), [...Array(length).keys()].map((i) => utf16.readUInt16LE(i * 2)));
+    b.CGEventKeyboardSetUnicodeString(down, length, buffer);
+    b.CGEventKeyboardSetUnicodeString(up, length, buffer);
+    post(down);
+    post(up);
+    typed += 1;
+  }
+  return { ok: true, chars: value.length, typed };
+}
+
+function keycodeFor(name) {
+  const key = String(name || '').toLowerCase();
+  const alias = ALIASES[key] || key;
+  if (alias in VK) return VK[alias];
+  if (key.length === 1) {
+    const lower = key.toLowerCase();
+    if (lower in VK) return VK[lower];
+  }
+  return null;
+}
+
+/**
+ * `ctrl+shift+t`, `cmd+space`, `alt+f4 x2` → { flags, keys, repeat }. Pure, so it is
+ * checked on every platform by test/native.js.
+ */
+function parseChord(combo) {
+  const parts = String(combo || '')
+    .toLowerCase()
+    .split(/[\s+]+/)
+    .filter(Boolean);
+  if (!parts.length) return { ok: false, error: `unreadable key combination: ${combo}` };
+  let repeat = 1;
+  let flags = 0;
+  const keys = [];
+  const modifiers = [];
+  for (const part of parts) {
+    if (part === 'repeat') {
+      repeat = 2;
+      continue;
+    }
+    if (/^x\d+$/.test(part)) {
+      repeat = Number(part.slice(1));
+      continue;
+    }
+    if (MODIFIERS[part] !== undefined) {
+      flags |= MODIFIERS[part];
+      modifiers.push(part);
+      continue;
+    }
+    const code = keycodeFor(part);
+    if (code !== null) keys.push(code);
+  }
+  if (!keys.length && !modifiers.length) return { ok: false, error: `unreadable key combination: ${combo}` };
+  if (!keys.length) keys.push(VK.space); // a bare modifier: press it
+  return { ok: true, flags, keys, modifiers, repeat: Math.min(50, Math.max(1, repeat)) };
+}
+
+function pressKeys(combo) {
+  const b = requireCG();
+  const chord = parseChord(combo);
+  if (!chord.ok) return chord;
+  const { flags, keys, repeat } = chord;
+  for (let i = 0; i < repeat; i += 1) {
+    for (const code of keys) {
+      const down = b.CGEventCreateKeyboardEvent(null, code, true);
+      const up = b.CGEventCreateKeyboardEvent(null, code, false);
+      if (!down || !up) return { ok: false, error: 'CGEventCreateKeyboardEvent failed' };
+      if (flags) {
+        b.CGEventSetFlags(down, flags);
+        b.CGEventSetFlags(up, flags);
+      }
+      post(down);
+      post(up);
+    }
+  }
+  return { ok: true, keys: combo };
+}
+
+// ------------------------------------------------------------------ screen --
+
+function screenSize() {
+  const b = requireCG();
+  const display = b.CGMainDisplayID();
+  return { ok: true, width: Number(b.CGDisplayPixelsWide(display)), height: Number(b.CGDisplayPixelsHigh(display)) };
+}
+
+function windows() {
+  const b = requireCG();
+  const options = 1 | 16; // kCGWindowListOptionOnScreenOnly | kCGWindowListExcludeDesktopElements
+  const list = b.CGWindowListCopyWindowInfo(options, 0);
+  if (!list) return { ok: true, windows: [] };
+  const out = [];
+  try {
+    const count = Number(b.CFArrayGetCount(list));
+    for (let i = 0; i < count; i += 1) {
+      const dict = b.CFArrayGetValueAtIndex(list, i);
+      if (!dict) continue;
+      const name = dictValue(dict, 'kCGWindowName', true) || dictValue(dict, 'kCGWindowOwnerName', true);
+      if (!name) continue;
+      const layer = dictValue(dict, 'kCGWindowLayer', false);
+      if (layer !== 0) continue; // menu bar, dock, overlays
+      // kCGWindowBounds is a nested dictionary with X/Y/Width/Height numbers
+      const boundsRef = (() => {
+        const key = cfString('kCGWindowBounds');
+        try {
+          return b.CFDictionaryGetValue(dict, key);
+        } finally {
+          if (key) b.CFRelease(key);
+        }
+      })();
+      const x = boundsRef ? dictValue(boundsRef, 'X', false) : 0;
+      const y = boundsRef ? dictValue(boundsRef, 'Y', false) : 0;
+      const width = boundsRef ? dictValue(boundsRef, 'Width', false) : 0;
+      const height = boundsRef ? dictValue(boundsRef, 'Height', false) : 0;
+      if (!width || !height) continue;
+      out.push({
+        name,
+        handle: dictValue(dict, 'kCGWindowNumber', false),
+        hwnd: dictValue(dict, 'kCGWindowNumber', false),
+        x: Math.round(x),
+        y: Math.round(y),
+        width: Math.round(width),
+        height: Math.round(height),
+        process_id: dictValue(dict, 'kCGWindowOwnerPID', false),
+        status: 'normal',
+      });
+    }
+  } finally {
+    b.CFRelease(list);
+  }
+  return { ok: true, windows: out };
+}
+
+function activeWindow() {
+  const res = osascript('tell application "System Events" to get name of first application process whose frontmost is true');
+  if (!res.ok || !res.out) return { ok: true, name: '', handle: null };
+  const hit = windows().windows.find((w) => w.name === res.out) || null;
+  return { ok: true, name: res.out, handle: hit ? hit.handle : null };
+}
+
+/** CoreGraphics hands out BGRA (little endian, alpha first) with a padded row stride. */
+function bgraToRgb(raw, width, height, bytesPerRow, bitsPerPixel = 32) {
+  const rgb = Buffer.alloc(width * height * 3);
+  const bpp = Math.max(4, Math.floor(bitsPerPixel / 8));
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const src = y * bytesPerRow + x * bpp;
+      const dst = (y * width + x) * 3;
+      rgb[dst] = raw[src + 2];
+      rgb[dst + 1] = raw[src + 1];
+      rgb[dst + 2] = raw[src];
+    }
+  }
+  return rgb;
+}
+
+function screenshot(dest) {
+  const b = requireCG();
+  const display = b.CGMainDisplayID();
+  const image = b.CGDisplayCreateImage(display);
+  if (!image) return { ok: false, error: 'CGDisplayCreateImage failed (grant Screen Recording to the terminal)' };
+  try {
+    const width = Number(b.CGImageGetWidth(image));
+    const height = Number(b.CGImageGetHeight(image));
+    const bytesPerRow = Number(b.CGImageGetBytesPerRow(image));
+    const bits = Number(b.CGImageGetBitsPerPixel(image));
+    const provider = b.CGImageGetDataProvider(image);
+    const data = provider ? b.CGDataProviderCopyData(provider) : null;
+    if (!data) return { ok: false, error: 'CGDataProviderCopyData failed' };
+    const koffi = require('koffi');
+    try {
+      const length = Number(b.CFDataGetLength(data));
+      const ptr = b.CFDataGetBytePtr(data);
+      if (!ptr) return { ok: false, error: 'CFDataGetBytePtr failed' };
+      const raw = koffi.decode(ptr, 'uint8_t', length);
+      const rgb = bgraToRgb(raw, width, height, bytesPerRow, bits);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, encodePng(rgb, width, height));
+      return { ok: true, file: dest, width, height, mime: 'image/png' };
+    } finally {
+      b.CFRelease(data);
+    }
+  } finally {
+    b.CFRelease(image);
+  }
+}
+
+// ----------------------------------------------------- what CoreGraphics cannot do --
+
+function osascript(script) {
+  const res = spawnSync('osascript', ['-e', script], { encoding: 'utf8', timeout: 20000 });
+  return { ok: res.status === 0, out: String(res.stdout || '').trim(), error: String(res.stderr || '').trim() };
+}
+
+function launchApp(name) {
+  const res = spawnSync('open', ['-a', String(name)], { encoding: 'utf8', timeout: 30000 });
+  return res.status === 0 ? { ok: true, app: name } : { ok: false, error: String(res.stderr || 'open -a failed').trim() };
+}
+
+function focusWindow(name) {
+  const res = osascript(
+    `tell application "System Events" to set frontmost of (first application process whose name is ${JSON.stringify(
+      String(name)
+    )}) to true`
+  );
+  return res.ok ? { ok: true, name } : { ok: false, error: res.error || `window not found: ${name}` };
+}
+
+function resizeWindow(name, x, y, width, height) {
+  const res = osascript(
+    `tell application "System Events" to tell (first application process whose name is ${JSON.stringify(
+      String(name)
+    )}) to set {position, size} of window 1 to {{${x}, ${y}}, {${width}, ${height}}}`
+  );
+  return res.ok ? { ok: true, name, x, y, width, height } : { ok: false, error: res.error || 'resize failed' };
+}
+
+function listApps() {
+  const out = [];
+  for (const dir of ['/Applications', '/System/Applications', path.join(os.homedir(), 'Applications')]) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith('.app')) continue;
+      out.push({ name: entry.replace(/\.app$/, ''), app_id: path.join(dir, entry) });
+    }
+  }
+  return { ok: true, apps: out };
+}
+
+function state(handle = null) {
+  const wins = windows();
+  const size = screenSize();
+  const active = activeWindow();
+  const list = wins.ok ? wins.windows : [];
+  const focused = handle || active.handle;
+  const elements = list
+    .filter((w) => !focused || w.handle === focused)
+    .map((w) => ({
+      name: w.name,
+      control_type: 'Window',
+      kind: 'Window',
+      bounding_box: { left: w.x, top: w.y, right: w.x + w.width, bottom: w.y + w.height },
+      center: { x: w.x + Math.floor(w.width / 2), y: w.y + Math.floor(w.height / 2) },
+      value: '',
+      enabled: true,
+      automation_id: '',
+    }));
+  return {
+    ok: true,
+    windows: list,
+    active_window: active.handle ? list.find((w) => w.handle === active.handle) || { name: active.name, handle: active.handle } : null,
+    interactive_elements: elements,
+    scrollable_elements: [],
+    interactive_elements_text: elements
+      .map((e, i) => `${i + 1}. ${e.control_type} '${e.name}' at (${e.center.x}, ${e.center.y})`)
+      .join('\n'),
+    scrollable_elements_text: '',
+    tree_status: 'coregraphics',
+    system: {
+      windows_version: `darwin ${os.release()}`,
+      os_version: os.release(),
+      screen_size: { width: size.width, height: size.height },
+      user_account_type: 'Local Account',
+      default_language: process.env.LANG || 'en',
+      dpi_scaling: 1,
+    },
+    metadata: { depth: 'top-level', kind: 'windows-list', all_desktops: false },
+  };
+}
+
+function available() {
+  if (process.platform !== 'darwin') return { ok: false, backend: 'macos', error: 'macOS only' };
+  try {
+    const size = screenSize();
+    if (!size.width || !size.height) throw new Error('no display');
+    return { ok: true, backend: 'macos', detail: 'CoreGraphics via FFI (no external tools)', screen: size };
+  } catch (err) {
+    return { ok: false, backend: 'macos', error: err.message };
+  }
+}
+
+function sysinfo() {
+  const size = screenSize();
+  return {
+    ok: true,
+    system: {
+      windows_version: `darwin ${os.release()}`,
+      os_version: os.release(),
+      screen_size: { width: size.width, height: size.height },
+      user_account_type: 'Local Account',
+      default_language: process.env.LANG || 'en',
+      dpi_scaling: 1,
+    },
+  };
+}
+
+const backend = {
+  name: 'coregraphics-ffi',
+  available,
+  screenSize,
+  windows,
+  activeWindow,
+  state,
+  moveMouse,
+  click,
+  mouseButton,
+  drag,
+  scroll,
+  typeText,
+  pressKeys,
+  focusWindow,
+  resizeWindow,
+  screenshot,
+  launchApp,
+  listApps,
+  sysinfo,
+};
+
+module.exports = {
+  backend,
+  available,
+  screenSize,
+  windows,
+  activeWindow,
+  state,
+  moveMouse,
+  click,
+  mouseButton,
+  drag,
+  scroll,
+  typeText,
+  pressKeys,
+  focusWindow,
+  resizeWindow,
+  screenshot,
+  launchApp,
+  listApps,
+  sysinfo,
+  VK,
+  FLAG,
+  MODIFIERS,
+  EVENT,
+  keycodeFor,
+  parseChord,
+  bgraToRgb,
+};

package/src/automation/png.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// PNG encoding without dependencies: the screenshots of the Linux and macOS backends
+// are RGB rasters, wrapped here in IHDR/IDAT/IEND with zlib.
+
+const zlib = require('node:zlib');
+
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i += 1) {
+    c ^= buf[i];
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  }
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function pngChunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body));
+  return Buffer.concat([len, body, crc]);
+}
+
+/** rgb: width*height*3 bytes, top-down, no padding. */
+function encodePng(rgb, width, height) {
+  const stride = width * 3;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y += 1) {
+    raw[y * (stride + 1)] = 0; // filter: none
+    rgb.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 2; // truecolour
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    pngChunk('IHDR', ihdr),
+    pngChunk('IDAT', zlib.deflateSync(raw, { level: 6 })),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+module.exports = { encodePng, crc32 };

package/src/automation.js

@@ -1003,11 +1003,24 @@ let nativeKind = null;
 
 try {
   if (isLinux) {
+    // Linux has no fallback any more: the FFI backend *is* the backend (the old one
+    // shelled out to xdotool, which is exactly what we do not want).
     nativeBackend = require('./automation/linux').backend;
     nativeKind = 'x11';
   } else if (isWin) {
-    nativeBackend = require('./automation/win-dll').backend;
-    nativeKind = 'dll';
+    // The DLL ships in the package; PowerShell stays only as a safety net for the case
+    // where it cannot be loaded at all.
+    const dll = require('./automation/win-dll');
+    if (dll.load()) {
+      nativeBackend = dll.backend;
+      nativeKind = 'dll';
+    }
+  } else if (isMac) {
+    const mac = require('./automation/mac');
+    if (mac.available().ok) {
+      nativeBackend = mac.backend;
+      nativeKind = 'mac';
+    }
   }
 } catch (err) {
   nativeBackend = null;
@@ -1023,7 +1036,11 @@ if (nativeBackend) {
   };
 
   Object.assign(automation, {
-    native: { kind: nativeKind, name: nativeBackend.name, dll: nativeKind === 'dll' ? require('./automation/win-dll').locate() : null },
+    native: {
+      kind: nativeKind,
+      name: nativeBackend.name,
+      dll: nativeKind === 'dll' ? require('./automation/win-dll').locate() : null,
+    },
     available: () => nativeBackend.available(),
     screenSize: () => nativeBackend.screenSize(),
     windows: () => nativeBackend.windows(),

package/src/cli.js

@@ -103,6 +103,7 @@ function context(flags) {
     json: Boolean(flags.json),
     confirmWrites: Boolean(flags['confirm-writes']),
     approval: normaliseApproval(flags.proceed ? 'proceed' : flags.ask ? 'ask' : cfg.approval),
+    shell: String(flags.shell || process.env.ARENACODE_SHELL || cfg.shell || '').trim(),
     idleTimeout: Number(flags['idle-timeout'] || cfg.idle_timeout || 180),
     bridge: new Bridge(url, key, device),
   };
@@ -194,7 +195,7 @@ function cmdConfig(positional, flags) {
     const name = key;
     const val = rest.join(' ');
     if (!name || val === '') {
-      write(`usage: ${SELF} config set <url|key|lang|mode|approval|pc_access> <value>`);
+      write(`usage: ${SELF} config set <url|key|lang|mode|approval|pc_access|shell> <value>`);
       return 2;
     }
     if (name === 'approval' && !['ask', 'proceed'].includes(String(val))) {
@@ -337,6 +338,7 @@ async function runInstruction(ctx, text, { attachments = [] } = {}) {
     const result = await followTask(ctx.bridge, taskId, {
       folder: ctx.folder,
       lang: ctx.lang,
+      shell: ctx.shell,
       yes: ctx.yes,
       approval: ctx.approval,
       confirmWrites: ctx.confirmWrites,
@@ -400,6 +402,7 @@ async function cmdUi(flags) {
     yes: ctx.yes,
     approval: ctx.approval,
     confirmWrites: ctx.confirmWrites,
+    shell: ctx.shell,
   });
   await app.start();
   return 0;
@@ -688,7 +691,7 @@ async function cmdHandshake(flags) {
 const USAGE = {
   init:      [['init', 'configure bridge URL + API key, then test the connection']],
   config:    [['config [show|path]', 'read the saved configuration'],
-              ['config set <key> <value>', 'url · key · lang · mode · pc_access']],
+              ['config set <key> <value>', 'url · key · lang · mode · pc_access · shell']],
   ping:      [['ping', 'bridge status and API key check']],
   doctor:    [['doctor', 'local checks: node, platform, folder, git, bridge']],
   ask:       [['ask "instruction"', 'run one task and stream the timeline']],

package/src/config.js

@@ -34,6 +34,7 @@ const DEFAULTS = {
   device: '',
   vision: false,
   idle_timeout: 180,
+  shell: '',
 };
 
 function readConfig() {

package/src/local.js

@@ -48,22 +48,110 @@ function relativize(root, abs) {
 // Local terminal (local-exec)
 // --------------------------------------------------------------------------- //
 
-function shellCommand(shell, command) {
-  if (process.platform === 'win32') {
-    switch (shell) {
+// Every shell the client can drive. The bridge may ask for one by name (`shell` in the
+// local-exec request), the user can pin one (`arenacode config set shell zsh`, `/shell`),
+// and otherwise the client takes the user's login shell, like a terminal would.
+const UNIX_SHELLS = {
+  sh: '/bin/sh',
+  bash: '/bin/bash',
+  zsh: '/bin/zsh',
+  fish: '/usr/bin/fish',
+  dash: '/bin/dash',
+  ksh: '/bin/ksh',
+};
+
+const WINDOWS_SHELLS = ['powershell', 'pwsh', 'cmd', 'wsl', 'bash'];
+
+function shellExists(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** sh/bash/zsh/dash/ksh: -l login, -c command. fish spells the same as -l -c. */
+function unixShell(name) {
+  const wanted = String(name || '').toLowerCase().replace(/\.exe$/, '');
+  const alias = { 'git-bash': 'bash', gitbash: 'bash' }[wanted] || wanted;
+  let file = UNIX_SHELLS[alias];
+  if (!file && (alias === 'sh' || alias.startsWith('/'))) file = alias === 'sh' ? '/bin/sh' : alias;
+  if (!file) file = whichPath(alias);
+  if (!file) file = UNIX_SHELLS[alias] || null;
+  if (!file) return null;
+  const base = path.basename(file);
+  const args = base === 'fish' ? ['-l', '-c', null] : ['-lc', null];
+  return { file, args };
+}
+
+function whichPath(name) {
+  for (const dir of ['/bin', '/usr/bin', '/usr/local/bin', '/opt/homebrew/bin']) {
+    const file = path.join(dir, name);
+    if (shellExists(file)) return file;
+  }
+  return null;
+}
+
+/** The shell to use when nobody asked for a specific one. */
+function detectShell(platform = process.platform) {
+  if (platform === 'win32') {
+    if (shellExists('pwsh.exe') || whichPath('pwsh')) return 'pwsh';
+    return 'powershell';
+  }
+  const login = path.basename(process.env.SHELL || '');
+  if (login && (UNIX_SHELLS[login] || whichPath(login))) return login;
+  return 'sh';
+}
+
+/** What the client can offer on this machine — for `sysinfo`, `/shell` and the help. */
+function availableShells(platform = process.platform) {
+  if (platform === 'win32') {
+    return WINDOWS_SHELLS.filter((name) => name === 'powershell' || name === 'cmd' || Boolean(whichPath(name)));
+  }
+  const found = Object.keys(UNIX_SHELLS).filter((name) => shellExists(UNIX_SHELLS[name]) || Boolean(whichPath(name)));
+  return found.length ? found : ['sh'];
+}
+
+/**
+ * Command template for one shell. `command` is passed as its own argv entry, never
+ * through a second round of quoting, so quotes and `$` survive.
+ */
+function shellCommand(shell, command, platform = process.platform) {
+  const name = String(shell || detectShell(platform)).toLowerCase().replace(/\.exe$/, '');
+  if (platform === 'win32') {
+    switch (name) {
       case 'cmd':
         return { file: 'cmd.exe', args: ['/d', '/s', '/c', command] };
       case 'wsl':
         return { file: 'wsl.exe', args: ['sh', '-lc', command] };
+      case 'bash': {
+        // Git Bash when it is installed, otherwise the WSL bash
+        const gitBash = [
+          'C:\\Program Files\\Git\\bin\\bash.exe',
+          'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+        ].find((file) => {
+          try {
+            return fs.existsSync(file);
+          } catch {
+            return false;
+          }
+        });
+        return gitBash
+          ? { file: gitBash, args: ['-lc', command] }
+          : { file: 'wsl.exe', args: ['bash', '-lc', command] };
+      }
+      case 'pwsh':
+        return { file: 'pwsh.exe', args: ['-NoProfile', '-NonInteractive', '-Command', command] };
       case 'powershell':
+      case 'ps':
       default:
-        return {
-          file: shell === 'pwsh' ? 'pwsh.exe' : 'powershell.exe',
-          args: ['-NoProfile', '-NonInteractive', '-Command', command],
-        };
+        return { file: 'powershell.exe', args: ['-NoProfile', '-NonInteractive', '-Command', command] };
     }
   }
-  return { file: '/bin/sh', args: ['-lc', command] };
+  const template = unixShell(name) || unixShell('sh');
+  const args = template.args.map((arg) => (arg === null ? command : arg));
+  return { file: template.file, args };
 }
 
 /** Runs a command and collects stdout+stderr and the exit code. */
@@ -96,9 +184,12 @@ async function handleLocalExec(bridge, taskId, request, opts) {
   const { rid, command, cwd: reqCwd, shell, admin, sandbox_reason: sandboxReason } = request;
   const lang = opts.lang;
   const dir = reqCwd ? resolveInRoot(opts.folder, reqCwd) : opts.folder;
+  // the bridge names the shell it wrote the command for; otherwise the user's choice
+  // from `arenacode config set shell …` / `/shell`, otherwise the login shell
+  const chosenShell = shell || opts.shell || detectShell();
 
   write('');
-  write(`  ${c.bold(c.yellow('⌘ terminal'))} ${c.dim('·')} ${c.cyan(shell || 'shell')} ${c.dim('·')} ${c.gray(dir)}`);
+  write(`  ${c.bold(c.yellow('⌘ terminal'))} ${c.dim('·')} ${c.cyan(chosenShell)} ${c.dim('·')} ${c.gray(dir)}`);
   write(indentLines(command, '    '));
   if (admin) write(`  ${c.yellow('!')} ${t(lang, 'Richiede i permessi di amministratore: qui il comando gira senza UAC.', 'Needs administrator rights: here it runs without UAC.', 'Necesita permisos de administrador: aquí se ejecuta sin UAC.')}`);
   if (sandboxReason) write(`  ${c.yellow('!')} ${t(lang, 'L’agente chiede di installare sul PC', 'The agent asks to install on the PC', 'El agente pide instalar en el PC')}: ${c.gray(sandboxReason)}`);
@@ -125,7 +216,7 @@ async function handleLocalExec(bridge, taskId, request, opts) {
     return true;
   }
 
-  const { output, code } = await runShell(command, { cwd: dir, shell });
+  const { output, code } = await runShell(command, { cwd: dir, shell: chosenShell });
   await bridge.localResult(taskId, { rid, output, code });
   write(`  ${code === 0 ? c.green('✓') : c.red('✗')} ${c.gray(`exit ${code}`)}`);
   return true;
@@ -495,7 +586,8 @@ async function handleLocalUi(bridge, taskId, request, opts) {
       cpus: os.cpus().length,
       memory_mb: Math.round(os.totalmem() / 1048576),
       node: process.version,
-      shell: require('./meta').which('pwsh') ? 'pwsh' : process.platform === 'win32' ? 'powershell' : 'sh',
+      shell: detectShell(),
+      shells: availableShells(),
     };
     await bridge.localResult(taskId, { rid, output: JSON.stringify(info), code: 0 });
     write(`  ${c.green('✓')} ${c.gray('sysinfo')}`);
@@ -683,6 +775,9 @@ async function handleLocalFile(bridge, taskId, request, opts) {
 
 module.exports = {
   runUiAction,
+  shellCommand,
+  detectShell,
+  availableShells,
   REFUSED,
   resolveInRoot,
   runShell,

package/src/tui/app.js

@@ -14,7 +14,7 @@ const { getTheme, themeNames } = require('./theme');
 
 const { Bridge } = require('../bridge');
 const { buildMeta, readProjectContext } = require('../meta');
-const { runShell, runFsOp, resolveInRoot } = require('../local');
+const { runShell, runFsOp, resolveInRoot, detectShell, availableShells, shellCommand } = require('../local');
 const { readConfig, patchConfig, deviceId, resolveUrl, resolveKey, openFolder, VERSION } = require('../config');
 
 const { MODE_LINES, modeLabel, nextMode, normaliseMode } = require('../modes');
@@ -49,6 +49,7 @@ class App {
     this.autoApprove = Boolean(opts.yes);
     this.confirmWrites = Boolean(opts.confirmWrites);
     this.approval = normaliseApproval(opts.approval);
+    this.shell = String(opts.shell || cfg.shell || '').trim() || detectShell();
 
     this.state = {
       mode: normaliseMode(opts.mode || cfg.mode || 'agent'),
@@ -493,6 +494,7 @@ class App {
       { slash: '/ask', title: 'Ask and Proceed: ask before commands, files and plans', hint: '', group: 'Session', run: () => this.setApproval('ask') },
       { slash: '/proceed', title: 'Proceed: approve the plan and run everything without asking', hint: '', group: 'Session', run: () => this.setApproval('proceed') },
       { slash: '/theme', title: 'Cycle the colour theme', hint: 'ctrl+x t', group: 'Session', run: by('Theme') },
+      { slash: '/shell', title: 'Show or change the shell commands run in', hint: '', group: 'Session', run: () => this.pickShell() },
       { slash: '/status', title: 'Ping the bridge', hint: '', group: 'Session', run: by('Bridge status') },
       { slash: '/help', title: 'Every keybinding', hint: 'f1', group: 'Session', run: () => this.openHelp() },
       { slash: '/quit', title: 'Leave arenacode', hint: 'ctrl+x q', group: 'Session', run: () => this.quit() },
@@ -538,6 +540,42 @@ class App {
     this.toast(`approval: ${next === 'proceed' ? 'Proceed' : 'Ask and Proceed'}`, next === 'proceed' ? 'warn' : 'ok');
   }
 
+  /** `/shell` (and the double-click on a card's shell line): pick from the shells here. */
+  async pickShell(name = '') {
+    const shells = availableShells();
+    const wanted = String(name || '').trim().toLowerCase();
+    if (wanted) {
+      if (!shells.includes(wanted)) {
+        this.toast(`shell: ${wanted} not found (${shells.join(', ')})`, 'warn');
+        return;
+      }
+      this.setShell(wanted);
+      return;
+    }
+    // a free-text prompt instead of a dialog: esc keeps the current shell
+    this.toast(`shell: ${this.shell} (${shells.join(', ')})`);
+    const current = shellCommand(this.shell).file;
+    const answer = String(await this.prompt(`shell [${current}]`)).trim().toLowerCase();
+    if (!answer) return;
+    if (!shells.includes(answer)) {
+      this.toast(`shell: ${answer} not found (${shells.join(', ')})`, 'warn');
+      return;
+    }
+    this.setShell(answer);
+  }
+
+  setShell(name) {
+    this.shell = name;
+    try {
+      patchConfig({ shell: name });
+    } catch {
+      /* a read-only HOME keeps the choice in memory only */
+    }
+    const { file } = shellCommand(name);
+    this.push({ kind: 'system', text: `shell: ${name} · ${file}` });
+    this.toast(`shell: ${name}`, 'ok');
+  }
+
   onOverlayKey(key) {
     const ov = this.state.overlay;
     if (key.name === 'escape') {
@@ -672,7 +710,7 @@ class App {
       const cmd = text.slice(1).trim();
       this.push({ kind: 'user', text: cmd, shell: true });
       const item = this.push({ kind: 'tool', icon: 'terminal', label: cmd, state: 'running', detail: '' });
-      const { output, code } = await runShell(cmd, { cwd: this.folder, shell: undefined, quiet: true });
+      const { output, code } = await runShell(cmd, { cwd: this.folder, shell: this.shell, quiet: true });
       item.state = code === 0 ? 'done' : 'failed';
       item.detail = output.trim();
       item.secs = undefined;