aegis-desktop 0.8.18 → 0.8.20

package/lib/local/engine.js

@@ -240,6 +240,57 @@ function providerKeyFromEnv(provider) {
 const DEEPSEEK_REASONING_MODEL_RE = /^deepseek-(v4(\.\d+)?-(flash|pro)|flash|pro|reasoner)$/;
 const EFFORT_TOKEN_BUDGET = { low: 8192, medium: 16384, high: 32768 };
 
+/**
+ * DeepSeek native reasoning level per config rung.
+ *
+ * The field is `reasoning_effort`, NOT `effort`. Verified live 2026-10-02: a
+ * DeepSeek body carrying `effort` returns HTTP 200 and is ignored, while
+ * `reasoning_effort` binds and rejects an unknown value with a 422 naming its
+ * enum (none|minimal|low|medium|high|xhigh|ultra|max). Behaviourally,
+ * `reasoning_effort:"none"` produced 0 reasoning_content chars and `"max"`
+ * produced 138, whereas `effort:"none"` still produced 112 — thinking stayed
+ * on. So the old field was inert on every turn, and inertness is the worst
+ * failure here: it 200s, nothing surfaces, and the model merely thinks at the
+ * wrong depth.
+ *
+ * Every rung of the knob has a namesake in that enum, so the map is 1:1 rather
+ * than the earlier (low|max, no medium) fold, which rested on the mistaken
+ * belief that DeepSeek had no `medium`. `max_tokens` (EFFORT_TOKEN_BUDGET)
+ * still scales as the output ceiling, since hidden chain-of-thought shares that
+ * budget on DeepSeek.
+ *
+ * Mirrors the upstream engine's src/backend.js DEEPSEEK_EFFORT verbatim;
+ * desktop/renderer/budget.js carries the renderer's copy for the same
+ * no-drift guarantee as DEEPSEEK_REASONING_MODEL_RE above.
+ */
+const DEEPSEEK_EFFORT = { low: 'low', medium: 'medium', high: 'high' };
+
+/**
+ * Per-family effort translation, mirroring the upstream engine's
+ * EFFORT_DIALECTS. The knob is one rung here (low|medium|high) but it is NOT
+ * portable across vendors, and passing it through untranslated is a correctness
+ * bug rather than a no-op: Groq 400s any level outside a model's supported set,
+ * and Gemini 3 fails on `medium` outright while low/high succeed. So each
+ * family states its own wire field and level map, and a family with no such
+ * field gets NOTHING — an unknown body field either 400s or is silently
+ * dropped, and both are worse than stating no opinion.
+ *
+ * xAI's `*-non-reasoning` row is left alone entirely: the model exists to not
+ * reason, and sending it an effort field is precisely the request the user
+ * picked that row to avoid. grok-4.20 and gemini-2.0 stay bare too — no
+ * documented level field exists for them, and guessing on a strict validator
+ * is a 400 rather than an upgrade.
+ */
+const EFFORT_IDENTITY = { low: 'low', medium: 'medium', high: 'high' };
+const EFFORT_INERT_RE = /non-reasoning/i;
+const EFFORT_DIALECTS = [
+  { provider: 'deepseek', re: DEEPSEEK_REASONING_MODEL_RE, field: 'reasoning_effort', map: DEEPSEEK_EFFORT },
+  { provider: 'openai', re: /^(gpt-5|o[0-9])/i, field: 'reasoning_effort', map: EFFORT_IDENTITY },
+  { provider: 'groq', re: /^(openai\/gpt-oss|qwen\/qwen3)/i, field: 'reasoning_effort', map: EFFORT_IDENTITY },
+  { provider: 'xai', re: /^grok-(4\.[5-9]|[5-9])/, field: 'reasoning_effort', map: EFFORT_IDENTITY },
+  { provider: 'google', re: /^gemini-(2\.5|3|[4-9])/, field: 'reasoning_effort', map: { ...EFFORT_IDENTITY, medium: 'high' } },
+];
+
 /**
  * Idle-stream budget for a pooled brain call ("work autonomously"). The
  * generic watchdog in vendor/aegis.js kills a stream that goes 60s without a
@@ -296,6 +347,24 @@ function reasoningBudget(model, maxTokens, effort) {
   return undefined;
 }
 
+/**
+ * The native effort verdict for this provider+model: `{ field, level }`, or
+ * `undefined` when the family has no effort knob. `undefined` means "say
+ * nothing", never "send a default" — inventing a level is how the knob silently
+ * overrides the vendor's own default. Supersedes the DeepSeek-only
+ * deepseekEffort() it replaces: same DeepSeek mapping, now stated for every
+ * family that has one instead of only the one that used to be wired.
+ */
+function nativeEffort(provider, model, effort) {
+  const m = String(model || '');
+  if (EFFORT_INERT_RE.test(m)) return undefined;
+  const eff = effort === 'low' || effort === 'medium' ? effort : 'high';
+  for (const d of EFFORT_DIALECTS) {
+    if (d.provider === provider && d.re.test(m)) return { field: d.field, level: d.map[eff] };
+  }
+  return undefined;
+}
+
 /** Relay model entries arrive as ids or objects; keep only real model ids. */
 function normalizeCatalog(models) {
   if (!Array.isArray(models)) return [];
@@ -741,7 +810,7 @@ function createLocalEngine({
     // direction too: a path wrongly claimed stops being reported as foreign.
     const result = await T.executeTool(name, args, toolCtx);
     if (guard && (name === 'writeFile' || name === 'editFile') && result && result.ok !== false) {
-      recordWrite(guard, args && args.path);
+      recordWrite(guard, args && args.file_path);
     }
     return result;
   }
@@ -790,7 +859,7 @@ function createLocalEngine({
       // unconditionally, making every line below it unreachable — the
       // approved-write path recorded nothing at all.)
       if (res && res.ok !== false && toolCtx && toolCtx.guard) {
-        recordWrite(toolCtx.guard, args && args.path);
+        recordWrite(toolCtx.guard, args && args.file_path);
       }
       return res;
     }
@@ -1146,6 +1215,12 @@ function createLocalEngine({
       // automatically by byokChatCompletion() as X-AEGIS-Key so the account
       // gets billed the handling fee; see client/aegis.js.
       const { provider, model: bareModel } = splitByokModel(opts.model);
+      // Translate the rung for THIS vendor once, and carry the verdict rather
+      // than a bare level: the relay validates strictly upstream and the field
+      // name is not portable (DeepSeek's OpenAI-compatible surface takes
+      // `reasoning_effort`, same spelling as OpenAI's). Undefined for a family
+      // with no dialect, which the transport then omits entirely.
+      const effort = nativeEffort(provider, bareModel, opts.effort);
       try {
         return await aegis.byokChatCompletion({
           provider,
@@ -1155,6 +1230,13 @@ function createLocalEngine({
           system: opts.system,
           messages: opts.messages,
           maxTokens: opts.maxTokens,
+          // Native effort knob, field and level both from the dialect table.
+          // `bareModel` is already provider-less, so it matches the dialect
+          // regexes without further stripping. Only a dialect whose field is
+          // `reasoning_effort` is forwarded: DeepSeek used to ride a separate
+          // `effort` body key, which the API 200s and ignores, so that whole
+          // second channel is gone rather than left as a way to reintroduce it.
+          reasoningEffort: effort && effort.field === 'reasoning_effort' ? effort.level : undefined,
           stream: true,
           onStream: opts.onDelta,
           signal: opts.signal,
@@ -1856,4 +1938,4 @@ function createLocalEngine({
   };
 }
 
-module.exports = { CLASSES, createLocalEngine, extractToolCalls, parseArgs, reasoningBudget };
+module.exports = { CLASSES, createLocalEngine, extractToolCalls, parseArgs, reasoningBudget, nativeEffort };

package/lib/local/shell.js

@@ -7,26 +7,308 @@
  * The desktop `exec` tool used to spawn ONE process per call: `cd /foo` in
  * one turn had no effect on the next call, so a model that wanted to work
  * inside a subdirectory had to prefix every single command with `cd X &&`.
- * This keeps ONE long-lived shell per chat turn — bash on macOS/Linux,
- * PowerShell on Windows (no bash there by default) — feeding it commands over
- * stdin and framing each command's output with a per-session random sentinel
- * printed alongside the exit code. On bash, stderr is merged into stdout
- * (`exec 2>&1`) so ordering is preserved; PowerShell's stderr pipe is merged
- * the same way by listening on both streams.
+ * This keeps ONE long-lived shell per chat turn — a probed POSIX sh/bash on
+ * macOS/Linux, PowerShell on Windows (no bash there by default) — feeding it
+ * commands over stdin and framing each command's output with a per-session
+ * random sentinel printed alongside the exit code. On POSIX, stderr is merged
+ * into stdout (`exec 2>&1`) so ordering is preserved; PowerShell's stderr pipe
+ * is merged the same way by listening on both streams.
  *
- * Self-contained (node:child_process + node:crypto only) and never throws:
- * run() always resolves { content, isError }. If the session can't start or
- * dies, run() falls back to a one-shot spawn so `exec` keeps working.
+ * Phase 30.3 — the shell is PROBED, never assumed. Until this step the session
+ * spawned `process.env.SHELL || '/bin/bash'` and then fed it brace groups, `exec
+ * 2>&1` and `$?` — all POSIX-only. Windows was handled; a POSIX host whose
+ * `$SHELL` is fish, csh or nushell was not, and those three reject that syntax
+ * outright (a brace group to fish is not a syntax error you can ignore: it
+ * silently runs the wrong thing and eats the sentinel, hanging the session to
+ * its timeout). So `resolveSessionShell()` below only ever returns a shell it
+ * has actually EXECUTED once with a POSIX-only probe script, and the dialect the
+ * script builder uses follows the verified dialect — `this.shell.kind` — rather
+ * than the OS. A `$SHELL` naming a known-non-POSIX shell (fish/csh/tcsh/nu/
+ * xonsh) is never adopted and never probed; it is named in the evidence trail
+ * and in the caveat, and if no sh/bash can be verified at all the session
+ * REFUSES with a message naming it, instead of quietly feeding it POSIX syntax.
+ *
+ * Self-contained (node:child_process + node:crypto + the shared
+ * client/platform.js) and never throws: run() always resolves
+ * { content, isError }. If the session can't start or dies, run() falls back to
+ * a one-shot spawn so `exec` keeps working.
  */
 
-const { spawn } = require('node:child_process');
+const { spawn, spawnSync } = require('node:child_process');
 const crypto = require('node:crypto');
 
-const IS_WIN32 = process.platform === 'win32';
+// The ONE platform module (client/platform.js, Phase 30.1) — resolved the same
+// two ways this repo resolves every shared module (see tools.js/engine.js):
+// repo-relative in a checkout and in the CLI's mirrored vendor tree, then the
+// staged app-dir copy a packaged desktop build carries. Executable lookup goes
+// through it (`resolveExecutable`) rather than through a path literal, so the
+// Windows half of that search is exercised by tests on this Linux host.
+let platform;
+try {
+  platform = require('../../../client/platform.js');
+} catch (err) {
+  try {
+    platform = require('../../vendor/platform.js');
+  } catch {
+    throw new Error(
+      `shell.js: cannot load the shared platform module (client/platform.js, ` +
+        `or its staged copy): ${err && err.message ? err.message : err}`
+    );
+  }
+}
+
+const IS_WIN32 = platform.IS_WIN32;
 const OUTPUT_CAP = 30_000;
 const MAX_TIMEOUT = 600_000;
 const DEFAULT_TIMEOUT = 120_000;
 
+// ---------------------------------------------------------------------------
+// Dialect resolution (Phase 30.3)
+// ---------------------------------------------------------------------------
+
+/**
+ * The shells whose `-c` we are allowed to treat as POSIX sh. Anything else —
+ * fish, csh/tcsh, nushell, xonsh, elvish, pwsh — is a different LANGUAGE, not a
+ * differently-named sh: it is never spawned for a session and never handed the
+ * brace-group framing below.
+ */
+const POSIX_SHELL_NAMES = ['bash', 'sh', 'dash', 'ksh', 'zsh'];
+
+/** Substitute candidates, in order, when `$SHELL` is unusable. */
+const POSIX_FALLBACK_NAMES = ['bash', 'sh'];
+
+/**
+ * The probe script: builtins only (no PATH, no filesystem, no output), and
+ * POSIX-only syntax — fish, csh and nu all reject this construct, so a clean
+ * exit 0 is evidence that `-c` really runs POSIX sh here, rather than evidence
+ * that a binary with the right name exists. Same probe the engine's Phase 21b
+ * resolution uses.
+ */
+const POSIX_PROBE = 'if [ 1 -eq 1 ]; then exit 0; fi';
+const SHELL_PROBE_TIMEOUT = 4000;
+
+/** Last path segment of a shell reference, minus a `.exe`, lower-cased. */
+function shellName(cmd) {
+  return String(cmd || '')
+    .trim()
+    .split(/[\\/]/)
+    .pop()
+    .toLowerCase()
+    .replace(/\.exe$/, '');
+}
+
+/** True for the shells whose `-c` may be treated as POSIX sh. */
+function isPosixShellName(cmd) {
+  return POSIX_SHELL_NAMES.includes(shellName(cmd));
+}
+
+/** The real probe: spawn `cmd -c <POSIX_PROBE>`, true only on a clean exit 0. */
+function probePosixShell(cmd, { env, timeout = SHELL_PROBE_TIMEOUT } = {}) {
+  try {
+    const res = spawnSync(cmd, ['-c', POSIX_PROBE], {
+      env,
+      encoding: 'utf8',
+      timeout,
+      windowsHide: true,
+      stdio: 'ignore',
+    });
+    return !res.error && res.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Normalize the injected seams, defaulting each to the real thing. */
+function shellSeams(options) {
+  const o = options && typeof options === 'object' ? options : {};
+  return {
+    platform: typeof o.platform === 'string' && o.platform ? o.platform : process.platform,
+    env: o.env && typeof o.env === 'object' ? o.env : process.env,
+    exists: typeof o.exists === 'function' ? o.exists : undefined,
+    probe: typeof o.probe === 'function' ? o.probe : undefined,
+    injected: typeof o.probe === 'function' || typeof o.exists === 'function',
+  };
+}
+
+/**
+ * Try one candidate. Returns a verified spec or null, recording why in `tried`
+ * and every shell it actually executed in `executed`.
+ *
+ * The name gate comes FIRST and applies to every candidate, including `$SHELL`:
+ * fish is refused on its name, before a probe could ever adopt it, so there is
+ * no ordering in which a fish gets spawned and then handed POSIX syntax.
+ */
+function considerPosixCandidate(o, candidate, tried, executed) {
+  const raw = String(candidate.cmd || '').trim();
+  if (!raw) {
+    tried.push({ candidate: candidate.source || '(unset)', ok: false, reason: 'unset' });
+    return null;
+  }
+  if (!isPosixShellName(raw)) {
+    tried.push({
+      candidate: raw,
+      ok: false,
+      reason:
+        `${candidate.source || 'candidate'} is not a POSIX shell — ${shellName(raw) || raw} is a ` +
+        'different language (fish/csh/nu), so it was never executed and never sent POSIX syntax',
+    });
+    return null;
+  }
+  const resolved = platform.resolveExecutable(raw, {
+    platform: o.platform,
+    env: o.env,
+    exists: o.exists,
+  });
+  if (!resolved) {
+    tried.push({
+      candidate: raw,
+      ok: false,
+      reason: /[\\/]/.test(raw) ? 'not present' : 'not found on PATH',
+    });
+    return null;
+  }
+  const ok = o.probe
+    ? Boolean(o.probe(resolved, ['-c', POSIX_PROBE]))
+    : probePosixShell(resolved, { env: o.env });
+  executed.push(resolved);
+  if (!ok) {
+    tried.push({
+      candidate: resolved,
+      ok: false,
+      reason: `failed the POSIX probe (\`-c\` with \`${POSIX_PROBE}\` did not exit 0) — refused`,
+    });
+    return null;
+  }
+  tried.push({
+    candidate: resolved,
+    ok: true,
+    reason: 'verified: one `-c` POSIX script exited 0',
+  });
+  return { ok: true, cmd: resolved, arg: '-c', kind: 'posix-sh', source: candidate.source, verified: true };
+}
+
+/**
+ * Resolve the session shell on a POSIX host, with the evidence for the answer.
+ *
+ * Returns { ok, cmd, arg, kind, source, verified, unsupported, caveat, error,
+ * tried[] }:
+ *
+ *   - `$SHELL` wins when it NAMES a POSIX shell and passes the probe;
+ *   - a `$SHELL` naming fish/csh/nu/xonsh (or anything else non-POSIX, including
+ *     garbage) is refused by name, recorded in `tried`, and named in `caveat`
+ *     when a substitute is found and in `error` when none can be;
+ *   - when `$SHELL` is unusable the POSIX dialect runs through an explicit
+ *     `bash`/`sh` found on PATH — resolved by client/platform.js, not by a path
+ *     literal — and only after that substitute passed the probe itself;
+ *   - `ok:false` means NO shell was verified: the caller must report `error`
+ *     (which names the unsupported `$SHELL`) instead of spawning anything.
+ */
+function resolvePosixSessionShell(o) {
+  const tried = [];
+  const executed = [];
+  const envShell = String((o.env && o.env.SHELL) || '').trim();
+  const candidates = [];
+
+  if (!envShell) {
+    tried.push({ candidate: '$SHELL', ok: false, reason: '$SHELL is unset' });
+  } else {
+    candidates.push({ cmd: envShell, source: '$SHELL' });
+  }
+  for (const name of POSIX_FALLBACK_NAMES) {
+    candidates.push({ cmd: name, source: `PATH:${name}` });
+  }
+
+  let hit = null;
+  for (const candidate of candidates) {
+    hit = considerPosixCandidate(o, candidate, tried, executed);
+    if (hit) break;
+  }
+
+  const unsupported = envShell && !isPosixShellName(envShell) ? envShell : null;
+  if (hit) {
+    return {
+      ...hit,
+      unsupported,
+      caveat: unsupported
+        ? `$SHELL is ${unsupported}, which is not a POSIX shell — the session runs the POSIX ` +
+          `dialect through ${hit.cmd} instead, and ${unsupported} is never sent brace groups, ` +
+          '`exec 2>&1` or `$?`'
+        : null,
+      error: null,
+      executed,
+      tried,
+    };
+  }
+
+  const error = unsupported
+    ? `exec: refusing to run — $SHELL is "${unsupported}", which is not a POSIX shell ` +
+      '(fish/csh/nushell are a different language), and no sh/bash could be verified on PATH ' +
+      'to run the POSIX dialect instead. Set SHELL to bash or sh, or put one on PATH.'
+    : `exec: no POSIX shell available — $SHELL is ${envShell ? `"${envShell}"` : 'unset'} and no ` +
+      'sh/bash passed the POSIX probe; set SHELL to bash or sh, or put one on PATH.';
+  return {
+    ok: false,
+    cmd: null,
+    arg: null,
+    kind: null,
+    source: 'refused',
+    verified: false,
+    unsupported,
+    caveat: null,
+    error,
+    executed,
+    tried,
+  };
+}
+
+// Verified verdicts are cached per (platform, $SHELL, PATH) so the probe runs
+// once per process — but never when a seam was injected: a test double must not
+// be able to poison the real verdicts.
+const SHELL_CACHE = new Map();
+
+/**
+ * Which shell runs the session here, and the evidence for that answer.
+ *
+ * Windows keeps PowerShell (there is no bash there by default), exactly as
+ * before; everywhere else the answer comes from resolvePosixSessionShell above
+ * and is only ever a shell that passed the POSIX probe. `options` is the same
+ * injected seam the shared platform module takes —
+ * `{ platform, env, exists, probe }` — so every branch is exercised on this
+ * Linux host (test/shell-dialect.test.mjs) rather than on a runner this project
+ * does not have.
+ */
+function resolveSessionShell(options = {}) {
+  const o = shellSeams(options);
+  if (o.platform === 'win32') {
+    const spec = platform.shellSpec({ platform: 'win32', env: o.env });
+    const powershell =
+      platform.resolveExecutable('powershell', { platform: 'win32', env: o.env, exists: o.exists }) ||
+      'powershell.exe';
+    return {
+      ok: true,
+      cmd: powershell,
+      arg: '-',
+      kind: 'powershell',
+      source: 'powershell.exe',
+      verified: true,
+      unsupported: null,
+      caveat: null,
+      error: null,
+      // One-shot commands on Windows stay cmd.exe: that is what the pre-session
+      // `exec` always used, and PowerShell is only the session's dialect.
+      oneShot: spec,
+      executed: [],
+      tried: [{ candidate: powershell, ok: true, reason: 'the Windows default (PowerShell session, cmd.exe one-shot)' }],
+    };
+  }
+
+  const key = [o.platform, o.env && o.env.SHELL, o.env && o.env.PATH].join('\u0000');
+  if (!o.injected && SHELL_CACHE.has(key)) return SHELL_CACHE.get(key);
+  const spec = resolvePosixSessionShell(o);
+  if (!o.injected) SHELL_CACHE.set(key, spec);
+  return spec;
+}
+
 function cap(s) {
   return s.length > OUTPUT_CAP ? `${s.slice(0, OUTPUT_CAP)}\n… (truncated)` : s;
 }
@@ -65,14 +347,49 @@ function appendBounded(prev, chunk) {
   return next.slice(0, OUTPUT_CAP) + ELISION + next.slice(-TAIL_KEEP);
 }
 
-/** One-shot fallback — the pre-session behavior, used when no live session. */
-function oneShotShell({ command, timeout = DEFAULT_TIMEOUT, working_directory } = {}) {
+/**
+ * The spec for a ONE-SHOT command (no live session) — the same resolution, so
+ * the `exec` tool's no-session path and this module's fallback cannot disagree
+ * about which shell speaks the dialect the command was written in.
+ *
+ * Windows keeps cmd.exe (`/d /s /c`), exactly what it used before; everywhere
+ * else the answer is a PROBED POSIX sh/bash, and `{ ok:false, error }` when
+ * nothing could be verified — the caller reports `error` (which names the
+ * unsupported `$SHELL`) instead of shelling out in a language it does not speak.
+ */
+function oneShotShellSpec(options = {}) {
+  const spec = resolveSessionShell(options);
+  if (!spec.ok) {
+    return { ok: false, cmd: null, arg: null, kind: null, error: spec.error, spec };
+  }
+  if (spec.kind === 'powershell') {
+    const cmdSpec = platform.shellSpec({ platform: 'win32', env: shellSeams(options).env });
+    return { ok: true, cmd: cmdSpec.cmd, arg: cmdSpec.arg, kind: 'cmd', error: null, spec };
+  }
+  return { ok: true, cmd: spec.cmd, arg: spec.arg, kind: 'posix-sh', error: null, spec };
+}
+
+/**
+ * One-shot fallback — the pre-session behavior, used when no live session.
+ *
+ * The dialect is resolved the same way the session's is: a POSIX `-c` runs in a
+ * verified sh/bash (never in an unprobed `$SHELL`), and when nothing can be
+ * verified the refusal names the shell that was refused rather than shelling out
+ * to it in a language it does not speak.
+ */
+function oneShotShell({ command, timeout = DEFAULT_TIMEOUT, working_directory, shellOptions } = {}) {
   return new Promise((resolve) => {
-    const cmd = IS_WIN32 ? (process.env.ComSpec || 'cmd.exe') : (process.env.SHELL || '/bin/sh');
-    const arg = IS_WIN32 ? '/d /s /c' : '-c';
-    const child = spawn(cmd, [arg, String(command || '')], {
+    const o = shellSeams(shellOptions);
+    const spec = resolveSessionShell(shellOptions);
+    if (!spec || !spec.ok) {
+      resolve({ content: (spec && spec.error) || 'exec: no usable shell', isError: true });
+      return;
+    }
+    const call = spec.kind === 'powershell' ? spec.oneShot : spec;
+    const child = spawn(call.cmd, [call.arg, String(command || '')], {
       cwd: working_directory || process.cwd(),
       timeout: Math.min(Number(timeout) || DEFAULT_TIMEOUT, MAX_TIMEOUT),
+      env: o.env,
     });
     let out = '';
     let err = '';
@@ -89,30 +406,44 @@ function oneShotShell({ command, timeout = DEFAULT_TIMEOUT, working_directory }
 }
 
 class ShellSession {
-  constructor({ cwd } = {}) {
+  constructor({ cwd, shellOptions } = {}) {
     this.sentinel = `__AEGIS_SH_${crypto.randomBytes(8).toString('hex')}__`;
     this.marker = `${this.sentinel}EXIT:`;
     this.buf = '';
     this.alive = false;
     this._pending = null; // resolver-scan for the in-flight command
+    this.shellOptions = shellOptions || {};
+    // Resolved BEFORE anything is spawned or written: `shell.kind` is what the
+    // command framing below branches on, so an unverified `$SHELL` can never
+    // receive POSIX syntax — it is never spawned at all.
+    this.shell = resolveSessionShell(this.shellOptions);
+    this.shellError = this.shell.ok ? null : this.shell.error;
     this._start(cwd);
   }
 
   _start(cwd) {
+    if (!this.shell || !this.shell.ok) {
+      // Refused: no shell was verified, so nothing is spawned. run() reports
+      // this.shellError (which names the unsupported $SHELL).
+      this.alive = false;
+      return;
+    }
+    const env = shellSeams(this.shellOptions).env;
     try {
-      this.child = IS_WIN32
+      this.child = this.shell.kind === 'powershell'
         // -Command - reads the script from stdin as a non-interactive session,
         // so there are no prompts to pollute output, but state still persists.
-        ? spawn('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '-'], {
+        ? spawn(this.shell.cmd, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '-'], {
           cwd: cwd || process.cwd(),
-          env: process.env,
+          env,
           stdio: ['pipe', 'pipe', 'pipe'],
         })
         // No args → the shell reads commands from stdin as a non-interactive
         // script, so there are no prompts to pollute output, but state persists.
-        : spawn(process.env.SHELL || '/bin/bash', [], {
+        // This is a shell that PASSED the POSIX probe (see resolveSessionShell).
+        : spawn(this.shell.cmd, [], {
           cwd: cwd || process.cwd(),
-          env: process.env,
+          env,
           stdio: ['pipe', 'pipe', 'pipe'],
         });
     } catch {
@@ -133,8 +464,10 @@ class ShellSession {
     // Merge stderr into stdout for the whole session so output ordering is
     // faithful and the sentinel (printed to fd1) always lands after it.
     // PowerShell errors already arrive on the stderr pipe onData folds in
-    // above, so only bash needs the explicit redirect.
-    if (!IS_WIN32) {
+    // above, so only a POSIX session needs the explicit redirect — and `exec`
+    // redirection is POSIX, which is why this is gated on the VERIFIED dialect
+    // rather than on `!IS_WIN32`.
+    if (this.shell.kind === 'posix-sh') {
       try { this.child.stdin.write('exec 2>&1\n'); } catch { this.alive = false; }
     }
   }
@@ -143,12 +476,16 @@ class ShellSession {
    * Run one command in the session. Resolves { content, isError }. A dead or
    * unstartable session (or a working_directory that must not persist)
    * degrades gracefully. `working_directory` is scoped to this one command (a
-   * subshell on bash, Push-Location/Pop-Location on PowerShell) so it doesn't
+   * subshell on POSIX, Push-Location/Pop-Location on PowerShell) so it doesn't
    * move the session's cwd.
    */
   run(command, { timeout = DEFAULT_TIMEOUT, working_directory } = {}) {
-    if (!this.alive || !this.child) {
-      return oneShotShell({ command, timeout, working_directory });
+    const posixSession = this.shell && this.shell.kind === 'posix-sh' && this.shell.verified;
+    if (!this.alive || !this.child || ((this.shell && this.shell.kind === 'posix-sh') && !posixSession)) {
+      if (!this.alive && this.shellError) {
+        return Promise.resolve({ content: this.shellError, isError: true });
+      }
+      return oneShotShell({ command, timeout, working_directory, shellOptions: this.shellOptions });
     }
     let cmd = String(command || '');
 
@@ -188,7 +525,7 @@ class ShellSession {
 
       // Send the command, then print the sentinel + exit code on its own line.
       let script;
-      if (IS_WIN32) {
+      if (!posixSession) {
         // Push-Location/Pop-Location scope working_directory to this one
         // command without moving the session's persistent cwd. $__c captures
         // the real exit status before Pop-Location's own success would
@@ -201,15 +538,17 @@ class ShellSession {
           : `${body}\n${exitCapture}\n`;
         script += `Write-Output ("${this.marker}" + $__c)\n`;
       } else {
-        // The command runs in a brace group with its stdin redirected from
-        // /dev/null: a group (not a subshell) keeps cd/export state
-        // persisting, and `</dev/null` stops the command from consuming the
-        // control channel. Without this, any stdin-reading command (cat,
-        // read, a REPL, ssh, a y/n prompt) swallows the sentinel line that
-        // follows it — hanging the whole session until the timeout, and
-        // echoing commands (cat) even splice the sentinel into their output
-        // and mis-resolve with garbage. working_directory runs in a subshell
-        // (parens, not the brace group) so it doesn't move the session's cwd.
+        // POSIX dialect, sent ONLY to a shell that passed the POSIX probe
+        // (posixSession above) — never to fish/csh/nu. The command runs in a
+        // brace group with its stdin redirected from /dev/null: a group (not a
+        // subshell) keeps cd/export state persisting, and `</dev/null` stops the
+        // command from consuming the control channel. Without this, any
+        // stdin-reading command (cat, read, a REPL, ssh, a y/n prompt) swallows
+        // the sentinel line that follows it — hanging the whole session until
+        // the timeout, and echoing commands (cat) even splice the sentinel into
+        // their output and mis-resolve with garbage. working_directory runs in a
+        // subshell (parens, not the brace group) so it doesn't move the
+        // session's cwd.
         if (working_directory) cmd = `( cd ${shq(working_directory)} && ${cmd} )`;
         const body = cmd.trim() ? cmd : ':';
         script = `{ ${body}\n} </dev/null\nprintf '\\n%s%d\\n' '${this.sentinel}EXIT:' "$?"\n`;
@@ -218,7 +557,7 @@ class ShellSession {
         this.child.stdin.write(script);
       } catch {
         this.alive = false;
-        oneShotShell({ command, timeout, working_directory }).then(finish);
+        oneShotShell({ command, timeout, working_directory, shellOptions: this.shellOptions }).then(finish);
         return;
       }
       // Data may already be buffered (fast commands) — scan once now.
@@ -246,4 +585,19 @@ function pshq(s) {
   return `'${String(s).replace(/'/g, "''")}'`;
 }
 
-module.exports = { ShellSession, oneShotShell, IS_WIN32, appendBounded, OUTPUT_CAP, BUFFER_CEILING, TAIL_KEEP };
+module.exports = {
+  ShellSession,
+  oneShotShell,
+  IS_WIN32,
+  // Phase 30.3: the dialect probe and its verdict, exported so a test can
+  // assert on the resolution without spawning a session.
+  resolveSessionShell,
+  oneShotShellSpec,
+  isPosixShellName,
+  POSIX_SHELL_NAMES,
+  POSIX_PROBE,
+  appendBounded,
+  OUTPUT_CAP,
+  BUFFER_CEILING,
+  TAIL_KEEP,
+};