aegis-desktop 1.0.13 → 1.0.15

package/lib/local/shell.js

@@ -1,682 +1,3 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
-// AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
-// Conveying a modified copy, or running one as a network service, owes the
-// corresponding source under this licence (§5/§13) — see LICENSING.md.
-'use strict';
-
-/**
- * shell.js — a persistent shell session for the `exec` tool, ported from
- * the upstream engine reference (client half of the same design).
- *
- * 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 — 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.
- *
- * 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, spawnSync } = require('node:child_process');
-const crypto = require('node:crypto');
-
-// 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 cmdSpec = platform.shellSpec({ platform: 'win32', env: o.env });
-    const powershell =
-      platform.resolveExecutable('powershell', { platform: 'win32', env: o.env, exists: o.exists }) ||
-      'powershell.exe';
-    // ONE-SHOT NOW SPEAKS THE SESSION'S DIALECT TOO (2026-02-14 report, item 1).
-    //
-    // This used to be `oneShot: cmdSpec` — PowerShell for the session, cmd.exe
-    // for every one-shot — and that mismatch is what made `exec` silently wrong
-    // mid-turn. When the live session died (sentinel timeout, killed child, a
-    // rejected stdin write) the degrade paths below run one-shot, so from that
-    // moment on every remaining command in the turn was parsed by cmd.exe while
-    // the model kept emitting PowerShell quoting. cmd.exe answers
-    // `'"Write-Output \"' is not recognized as an internal or external command`
-    // — localized, so on sv-SE it reads `Felaktig syntax för filnamn, katalognamn
-    // eller volymetikett`, which looks like a filesystem fault and not a shell
-    // change — and nothing in the tool result said the shell had switched.
-    //
-    // `-Command` accepts exactly the quoting the session accepts, so a
-    // degradation is now a transport change and not a language change. cmd.exe
-    // is no longer reachable from this path at all: if PowerShell cannot be
-    // resolved the spawn fails loudly (oneShotShell reports `error: …`) instead
-    // of quietly running the command in a shell that cannot read it.
-    const oneShot = {
-      cmd: powershell,
-      arg: '-Command',
-      kind: 'powershell',
-      source: 'powershell.exe',
-    };
-    return {
-      ok: true,
-      cmd: powershell,
-      arg: '-',
-      kind: 'powershell',
-      source: 'powershell.exe',
-      verified: true,
-      unsupported: null,
-      caveat: null,
-      error: null,
-      oneShot,
-      executed: [],
-      tried: [
-        { candidate: powershell, ok: true, reason: 'the Windows default (PowerShell session AND one-shot)' },
-        {
-          candidate: cmdSpec.cmd,
-          ok: false,
-          reason: 'cmd.exe is never used for one-shot: it cannot parse the PowerShell quoting the session teaches',
-        },
-      ],
-    };
-  }
-
-  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;
-}
-
-// The buffer is BOUNDED WHILE IT FILLS, not just when it is reported.
-//
-// `cap()` above runs on close, which is fine for the text the user sees but
-// useless as a memory bound: between the spawn and the exit the raw stream is
-// accumulated in this process with no ceiling at all, so a command that never
-// stops printing (`yes`, `cat /dev/zero`, a runaway build log) grows the MAIN
-// process's heap for as long as the timeout allows — up to 10 minutes — before
-// the truncation it was always going to get. A tool call must not be able to
-// OOM the app it runs in.
-//
-// The window kept is head + tail, because neither end may be dropped:
-//   - the HEAD is what the user and the model are shown (OUTPUT_CAP already
-//     says only that much is reported);
-//   - the TAIL is where the exit sentinel lives for a session (`printf
-//     '__AEGIS_SH_…EXIT:%d'`) — dropping it would not merely lose output, it
-//     would hang the session until the timeout, because the resolver scans the
-//     buffer for a marker that can never arrive.
-// 64 KiB of tail is ~1500× the sentinel line, and surviving a chunk boundary
-// needs only the sentinel's own length.
-const TAIL_KEEP = 64 * 1024;
-const BUFFER_CEILING = OUTPUT_CAP + TAIL_KEEP;
-const ELISION = '\n… (earlier output elided — command produced more than the buffer ceiling)\n';
-
-/** Append one stream chunk to `prev`, keeping the bounded head+tail window.
- *  Pure, so the streaming paths and their tests agree on the policy. */
-function appendBounded(prev, chunk) {
-  const next = prev + chunk;
-  if (next.length <= BUFFER_CEILING) return next;
-  // Elide the MIDDLE: head stays visible, tail keeps the sentinel reachable.
-  // The marker makes the missing bytes explicit rather than letting the two
-  // halves read as contiguous output.
-  return next.slice(0, OUTPUT_CAP) + ELISION + next.slice(-TAIL_KEEP);
-}
-
-/**
- * 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') {
-    // The session's own one-shot spec (PowerShell `-Command`), so the `exec`
-    // tool's no-session path and this module's fallback cannot disagree about
-    // the dialect — which is exactly how cmd.exe used to sneak back in.
-    const shot = spec.oneShot || platform.shellSpec({ platform: 'win32', env: shellSeams(options).env });
-    return { ok: true, cmd: shot.cmd, arg: shot.arg, kind: shot.kind || 'powershell', 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 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 = '';
-    // Bounded both ways: a one-shot command with no live session is just as
-    // capable of printing forever as a session command (appendBounded's header).
-    child.stdout.on('data', (d) => { out = appendBounded(out, d.toString()); });
-    child.stderr.on('data', (d) => { err = appendBounded(err, d.toString()); });
-    child.on('error', (e) => resolve({ content: `error: ${e.message}`, isError: true }));
-    child.on('close', (code) => {
-      const body = `${out}${err ? `\n${err}` : ''}`.trim() || `(exit ${code})`;
-      resolve({ content: cap(body), isError: code !== 0 });
-    });
-  });
-}
-
-class ShellSession {
-  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.cwd = cwd || process.cwd();
-    this.disposed = false; // an explicit dispose() must NOT be self-healed
-    this._respawns = 0; // one self-heal attempt per session, never a loop
-    this._degradedNoted = false; // the degrade marker is emitted once per session
-    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 = 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(this.shell.cmd, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '-'], {
-          cwd: cwd || process.cwd(),
-          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.
-        // This is a shell that PASSED the POSIX probe (see resolveSessionShell).
-        : spawn(this.shell.cmd, [], {
-          cwd: cwd || process.cwd(),
-          env,
-          stdio: ['pipe', 'pipe', 'pipe'],
-        });
-    } catch {
-      this.alive = false;
-      return;
-    }
-    this.alive = true;
-    const onData = (d) => {
-      // Bounded — see appendBounded. The tail is kept precisely so the sentinel
-      // this session's resolver scans for survives a command that floods stdout.
-      this.buf = appendBounded(this.buf, d.toString());
-      if (this._pending) this._pending();
-    };
-    this.child.stdout.on('data', onData);
-    this.child.stderr.on('data', onData);
-    this.child.on('exit', () => { this.alive = false; if (this._pending) this._pending(true); });
-    this.child.on('error', () => { this.alive = false; if (this._pending) this._pending(true); });
-    // 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 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; }
-    }
-  }
-
-  /**
-   * 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 POSIX, Push-Location/Pop-Location on PowerShell) so it doesn't
-   * move the session's cwd.
-   */
-  run(command, { timeout = DEFAULT_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 });
-      }
-      // SELF-HEAL BEFORE DEGRADING. The old path latched: once the live session
-      // died (a timeout kill, a child exit, a spawn error) every remaining
-      // command in the turn ran one-shot, and on Windows that one-shot used to
-      // be cmd.exe — so the agent stayed silently wrong for the rest of the
-      // turn. Re-probe and re-spawn ONCE instead, and only then fall through.
-      if (!this.alive && !this.disposed && this._respawns < 1) {
-        this._respawns += 1;
-        this.buf = '';
-        this.shell = resolveSessionShell(this.shellOptions);
-        this.shellError = this.shell.ok ? null : this.shell.error;
-        this._start(this.cwd);
-        if (this.alive) return this.run(command, { timeout, working_directory });
-      }
-      return oneShotShell({ command, timeout, working_directory, shellOptions: this.shellOptions })
-        .then((result) => this._noteDegraded(result, !this.alive ? 'the persistent session is not running' : 'no usable session dialect'));
-    }
-    let cmd = String(command || '');
-
-    return new Promise((resolve) => {
-      let settled = false;
-      const finish = (result) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        this._pending = null;
-        resolve(result);
-      };
-
-      const timer = setTimeout(() => {
-        // A hung command (e.g. one that reads stdin) can never reach the
-        // sentinel — kill the poisoned session and report what we have.
-        const partial = cap(this.buf.trim());
-        this.dispose();
-        finish({ content: `${partial}${partial ? '\n' : ''}(timed out after ${timeout}ms)`, isError: true });
-      }, Math.min(Number(timeout) || DEFAULT_TIMEOUT, MAX_TIMEOUT));
-
-      this._pending = (died) => {
-        if (died && !this.buf.includes(this.marker)) {
-          finish({ content: cap(this.buf.trim()) || '(shell session ended)', isError: true });
-          return;
-        }
-        const idx = this.buf.indexOf(this.marker);
-        if (idx === -1) return; // sentinel not here yet — wait for more data
-        const after = this.buf.slice(idx + this.marker.length);
-        const nl = after.indexOf('\n');
-        if (nl === -1) return; // exit-code line still arriving
-        const code = parseInt(after.slice(0, nl), 10);
-        const output = this.buf.slice(0, idx).replace(/\n+$/, '');
-        this.buf = after.slice(nl + 1); // leftover for the next command (usually '')
-        finish({ content: cap(output || `(exit ${code})`), isError: code !== 0 });
-      };
-
-      // Send the command, then print the sentinel + exit code on its own line.
-      let script;
-      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
-        // otherwise overwrite $?/$LASTEXITCODE.
-        const body = cmd.trim() ? cmd : 'Write-Output $null';
-        const exitCapture =
-          '$__c = if ($LASTEXITCODE -ne $null) { $LASTEXITCODE } elseif ($?) { 0 } else { 1 }';
-        script = working_directory
-          ? `Push-Location -LiteralPath ${pshq(working_directory)}\ntry {\n${body}\n${exitCapture}\n} finally {\nPop-Location\n}\n`
-          : `${body}\n${exitCapture}\n`;
-        script += `Write-Output ("${this.marker}" + $__c)\n`;
-      } else {
-        // 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`;
-      }
-      try {
-        this.child.stdin.write(script);
-      } catch {
-        this.alive = false;
-        oneShotShell({ command, timeout, working_directory, shellOptions: this.shellOptions })
-          .then((r) => finish(this._noteDegraded(r, 'the session stdin rejected the command')));
-        return;
-      }
-      // Data may already be buffered (fast commands) — scan once now.
-      if (this._pending) this._pending();
-    });
-  }
-
-  /**
-   * Mark a result that came from the one-shot fallback rather than the live
-   * session, so the model is TOLD the shell changed and can stop trusting its
-   * quoting contract.
-   *
-   * The 2026-02-14 report's worst finding was precisely that this happened
-   * silently: "nothing in the result tells the agent the shell changed" while
-   * the agent "degrades to a one-shot cmd.exe — and stays there for the
-   * remainder of the turn", so it kept emitting PowerShell quoting, got
-   * localized cmd.exe syntax errors, and finally blamed the user's machine.
-   * Emitted ONCE per session so a degraded turn stays readable.
-   */
-  _noteDegraded(result, reason) {
-    const r = result && typeof result === 'object' ? result : { content: String(result == null ? '' : result), isError: true };
-    if (this._degradedNoted) return r;
-    this._degradedNoted = true;
-    const via = this.shell && this.shell.cmd ? this.shell.cmd : 'unknown shell';
-    const was = this.shell && this.shell.kind ? this.shell.kind : 'none';
-    const marker = `[shell_degraded] ran one-shot via ${via} (${reason}); session dialect was ${was} — quoting contracts may differ`;
-    return { ...r, content: `${marker}\n${r.content || ''}` };
-  }
-
-  dispose() {
-    this.disposed = true;
-    this.alive = false;
-    if (this.child) {
-      try { this.child.stdin.end(); } catch { /* already gone */ }
-      try { this.child.kill('SIGKILL'); } catch { /* already gone */ }
-      this.child = null;
-    }
-  }
-}
-
-// Minimal single-quote shell-escape for a path.
-function shq(s) {
-  return `'${String(s).replace(/'/g, `'\\''`)}'`;
-}
-
-// Minimal single-quote escape for a PowerShell -LiteralPath (double up ').
-function pshq(s) {
-  return `'${String(s).replace(/'/g, "''")}'`;
-}
-
-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,
-};
+"use strict";const{spawn:spawn,spawnSync:spawnSync}=require("node:child_process"),crypto=require("node:crypto");let platform;try{platform=require("../../../client/platform.js")}catch(e){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): ${e&&e.message?e.message:e}`)}}const IS_WIN32=platform.IS_WIN32,OUTPUT_CAP=3e4,MAX_TIMEOUT=6e5,DEFAULT_TIMEOUT=12e4,POSIX_SHELL_NAMES=["bash","sh","dash","ksh","zsh"],POSIX_FALLBACK_NAMES=["bash","sh"],POSIX_PROBE="if [ 1 -eq 1 ]; then exit 0; fi",SHELL_PROBE_TIMEOUT=4e3;function shellName(e){return String(e||"").trim().split(/[\\/]/).pop().toLowerCase().replace(/\.exe$/,"")}function isPosixShellName(e){return POSIX_SHELL_NAMES.includes(shellName(e))}function probePosixShell(e,{env:s,timeout:t=SHELL_PROBE_TIMEOUT}={}){try{const n=spawnSync(e,["-c",POSIX_PROBE],{env:s,encoding:"utf8",timeout:t,windowsHide:!0,stdio:"ignore"});return!n.error&&0===n.status}catch{return!1}}function shellSeams(e){const s=e&&"object"==typeof e?e:{};return{platform:"string"==typeof s.platform&&s.platform?s.platform:process.platform,env:s.env&&"object"==typeof s.env?s.env:process.env,exists:"function"==typeof s.exists?s.exists:void 0,probe:"function"==typeof s.probe?s.probe:void 0,injected:"function"==typeof s.probe||"function"==typeof s.exists}}function considerPosixCandidate(e,s,t,n){const i=String(s.cmd||"").trim();if(!i)return t.push({candidate:s.source||"(unset)",ok:!1,reason:"unset"}),null;if(!isPosixShellName(i))return t.push({candidate:i,ok:!1,reason:`${s.source||"candidate"} is not a POSIX shell — ${shellName(i)||i} is a different language (fish/csh/nu), so it was never executed and never sent POSIX syntax`}),null;const o=platform.resolveExecutable(i,{platform:e.platform,env:e.env,exists:e.exists});if(!o)return t.push({candidate:i,ok:!1,reason:/[\\/]/.test(i)?"not present":"not found on PATH"}),null;const r=e.probe?Boolean(e.probe(o,["-c",POSIX_PROBE])):probePosixShell(o,{env:e.env});return n.push(o),r?(t.push({candidate:o,ok:!0,reason:"verified: one `-c` POSIX script exited 0"}),{ok:!0,cmd:o,arg:"-c",kind:"posix-sh",source:s.source,verified:!0}):(t.push({candidate:o,ok:!1,reason:`failed the POSIX probe (\`-c\` with \`${POSIX_PROBE}\` did not exit 0) — refused`}),null)}function resolvePosixSessionShell(e){const s=[],t=[],n=String(e.env&&e.env.SHELL||"").trim(),i=[];n?i.push({cmd:n,source:"$SHELL"}):s.push({candidate:"$SHELL",ok:!1,reason:"$SHELL is unset"});for(const e of POSIX_FALLBACK_NAMES)i.push({cmd:e,source:`PATH:${e}`});let o=null;for(const n of i)if(o=considerPosixCandidate(e,n,s,t),o)break;const r=n&&!isPosixShellName(n)?n:null;return o?{...o,unsupported:r,caveat:r?`$SHELL is ${r}, which is not a POSIX shell — the session runs the POSIX dialect through ${o.cmd} instead, and ${r} is never sent brace groups, \`exec 2>&1\` or \`$?\``:null,error:null,executed:t,tried:s}:{ok:!1,cmd:null,arg:null,kind:null,source:"refused",verified:!1,unsupported:r,caveat:null,error:r?`exec: refusing to run — $SHELL is "${r}", 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 ${n?`"${n}"`:"unset"} and no sh/bash passed the POSIX probe; set SHELL to bash or sh, or put one on PATH.`,executed:t,tried:s}}const SHELL_CACHE=new Map;function resolveSessionShell(e={}){const s=shellSeams(e);if("win32"===s.platform){const e=platform.shellSpec({platform:"win32",env:s.env}),t=platform.resolveExecutable("powershell",{platform:"win32",env:s.env,exists:s.exists})||"powershell.exe";return{ok:!0,cmd:t,arg:"-",kind:"powershell",source:"powershell.exe",verified:!0,unsupported:null,caveat:null,error:null,oneShot:{cmd:t,arg:"-Command",kind:"powershell",source:"powershell.exe"},executed:[],tried:[{candidate:t,ok:!0,reason:"the Windows default (PowerShell session AND one-shot)"},{candidate:e.cmd,ok:!1,reason:"cmd.exe is never used for one-shot: it cannot parse the PowerShell quoting the session teaches"}]}}const t=[s.platform,s.env&&s.env.SHELL,s.env&&s.env.PATH].join("\0");if(!s.injected&&SHELL_CACHE.has(t))return SHELL_CACHE.get(t);const n=resolvePosixSessionShell(s);return s.injected||SHELL_CACHE.set(t,n),n}function cap(e){return e.length>OUTPUT_CAP?`${e.slice(0,OUTPUT_CAP)}\n… (truncated)`:e}const TAIL_KEEP=65536,BUFFER_CEILING=OUTPUT_CAP+TAIL_KEEP,ELISION="\n… (earlier output elided — command produced more than the buffer ceiling)\n";function appendBounded(e,s){const t=e+s;return t.length<=BUFFER_CEILING?t:t.slice(0,OUTPUT_CAP)+ELISION+t.slice(-TAIL_KEEP)}function oneShotShellSpec(e={}){const s=resolveSessionShell(e);if(!s.ok)return{ok:!1,cmd:null,arg:null,kind:null,error:s.error,spec:s};if("powershell"===s.kind){const t=s.oneShot||platform.shellSpec({platform:"win32",env:shellSeams(e).env});return{ok:!0,cmd:t.cmd,arg:t.arg,kind:t.kind||"powershell",error:null,spec:s}}return{ok:!0,cmd:s.cmd,arg:s.arg,kind:"posix-sh",error:null,spec:s}}function oneShotShell({command:e,timeout:s=12e4,working_directory:t,shellOptions:n}={}){return new Promise((i=>{const o=shellSeams(n),r=resolveSessionShell(n);if(!r||!r.ok)return void i({content:r&&r.error||"exec: no usable shell",isError:!0});const l="powershell"===r.kind?r.oneShot:r,h=spawn(l.cmd,[l.arg,String(e||"")],{cwd:t||process.cwd(),timeout:Math.min(Number(s)||12e4,6e5),env:o.env});let c="",d="";h.stdout.on("data",(e=>{c=appendBounded(c,e.toString())})),h.stderr.on("data",(e=>{d=appendBounded(d,e.toString())})),h.on("error",(e=>i({content:`error: ${e.message}`,isError:!0}))),h.on("close",(e=>{const s=`${c}${d?`\n${d}`:""}`.trim()||`(exit ${e})`;i({content:cap(s),isError:0!==e})}))}))}class ShellSession{constructor({cwd:e,shellOptions:s}={}){this.sentinel=`__AEGIS_SH_${crypto.randomBytes(8).toString("hex")}__`,this.marker=`${this.sentinel}EXIT:`,this.buf="",this.alive=!1,this._pending=null,this.cwd=e||process.cwd(),this.disposed=!1,this._respawns=0,this._degradedNoted=!1,this.shellOptions=s||{},this.shell=resolveSessionShell(this.shellOptions),this.shellError=this.shell.ok?null:this.shell.error,this._start(e)}_start(e){if(!this.shell||!this.shell.ok)return void(this.alive=!1);const s=shellSeams(this.shellOptions).env;try{this.child="powershell"===this.shell.kind?spawn(this.shell.cmd,["-NoLogo","-NoProfile","-NonInteractive","-Command","-"],{cwd:e||process.cwd(),env:s,stdio:["pipe","pipe","pipe"]}):spawn(this.shell.cmd,[],{cwd:e||process.cwd(),env:s,stdio:["pipe","pipe","pipe"]})}catch{return void(this.alive=!1)}this.alive=!0;const t=e=>{this.buf=appendBounded(this.buf,e.toString()),this._pending&&this._pending()};if(this.child.stdout.on("data",t),this.child.stderr.on("data",t),this.child.on("exit",(()=>{this.alive=!1,this._pending&&this._pending(!0)})),this.child.on("error",(()=>{this.alive=!1,this._pending&&this._pending(!0)})),"posix-sh"===this.shell.kind)try{this.child.stdin.write("exec 2>&1\n")}catch{this.alive=!1}}run(e,{timeout:s=12e4,working_directory:t}={}){const n=this.shell&&"posix-sh"===this.shell.kind&&this.shell.verified;if(!this.alive||!this.child||this.shell&&"posix-sh"===this.shell.kind&&!n)return!this.alive&&this.shellError?Promise.resolve({content:this.shellError,isError:!0}):!this.alive&&!this.disposed&&this._respawns<1&&(this._respawns+=1,this.buf="",this.shell=resolveSessionShell(this.shellOptions),this.shellError=this.shell.ok?null:this.shell.error,this._start(this.cwd),this.alive)?this.run(e,{timeout:s,working_directory:t}):oneShotShell({command:e,timeout:s,working_directory:t,shellOptions:this.shellOptions}).then((e=>this._noteDegraded(e,this.alive?"no usable session dialect":"the persistent session is not running")));let i=String(e||"");return new Promise((o=>{let r=!1;const l=e=>{r||(r=!0,clearTimeout(h),this._pending=null,o(e))},h=setTimeout((()=>{const e=cap(this.buf.trim());this.dispose(),l({content:`${e}${e?"\n":""}(timed out after ${s}ms)`,isError:!0})}),Math.min(Number(s)||12e4,6e5));let c;if(this._pending=e=>{if(e&&!this.buf.includes(this.marker))return void l({content:cap(this.buf.trim())||"(shell session ended)",isError:!0});const s=this.buf.indexOf(this.marker);if(-1===s)return;const t=this.buf.slice(s+this.marker.length),n=t.indexOf("\n");if(-1===n)return;const i=parseInt(t.slice(0,n),10),o=this.buf.slice(0,s).replace(/\n+$/,"");this.buf=t.slice(n+1),l({content:cap(o||`(exit ${i})`),isError:0!==i})},n)t&&(i=`( cd ${shq(t)} && ${i} )`),c=`{ ${i.trim()?i:":"}\n} </dev/null\nprintf '\\n%s%d\\n' '${this.sentinel}EXIT:' "$?"\n`;else{const e=i.trim()?i:"Write-Output $null",s="$__c = if ($LASTEXITCODE -ne $null) { $LASTEXITCODE } elseif ($?) { 0 } else { 1 }";c=t?`Push-Location -LiteralPath ${pshq(t)}\ntry {\n${e}\n${s}\n} finally {\nPop-Location\n}\n`:`${e}\n${s}\n`,c+=`Write-Output ("${this.marker}" + $__c)\n`}try{this.child.stdin.write(c)}catch{return this.alive=!1,void oneShotShell({command:e,timeout:s,working_directory:t,shellOptions:this.shellOptions}).then((e=>l(this._noteDegraded(e,"the session stdin rejected the command"))))}this._pending&&this._pending()}))}_noteDegraded(e,s){const t=e&&"object"==typeof e?e:{content:String(null==e?"":e),isError:!0};if(this._degradedNoted)return t;this._degradedNoted=!0;const n=`[shell_degraded] ran one-shot via ${this.shell&&this.shell.cmd?this.shell.cmd:"unknown shell"} (${s}); session dialect was ${this.shell&&this.shell.kind?this.shell.kind:"none"} — quoting contracts may differ`;return{...t,content:`${n}\n${t.content||""}`}}dispose(){if(this.disposed=!0,this.alive=!1,this.child){try{this.child.stdin.end()}catch{}try{this.child.kill("SIGKILL")}catch{}this.child=null}}}function shq(e){return`'${String(e).replace(/'/g,"'\\''")}'`}function pshq(e){return`'${String(e).replace(/'/g,"''")}'`}module.exports={ShellSession:ShellSession,oneShotShell:oneShotShell,IS_WIN32:IS_WIN32,resolveSessionShell:resolveSessionShell,oneShotShellSpec:oneShotShellSpec,isPosixShellName:isPosixShellName,POSIX_SHELL_NAMES:POSIX_SHELL_NAMES,POSIX_PROBE:POSIX_PROBE,appendBounded:appendBounded,OUTPUT_CAP:OUTPUT_CAP,BUFFER_CEILING:BUFFER_CEILING,TAIL_KEEP:TAIL_KEEP};