cli-jaw 2.2.11 → 2.2.13

package/public/manager/src/settings/pages/components/PerCliRow.tsx

@@ -4,6 +4,7 @@ import { useState } from 'react';
 import { TextField, SelectField, ToggleField } from '../../fields';
 import type { SettingsClient } from '../../types';
 import type { DirtyEntry } from '../../types';
+import { coerceEffortForModel, effortChoicesForModel } from './agent/agent-meta';
 import type { CliMeta, PerCliEntry } from './agent/agent-meta';
 import { PiProfileDialog } from './PiProfileDialog';
 import { piModelOptions, piProfileOptions, type PiSettingsView } from './pi-profile';
@@ -36,9 +37,10 @@ export function PerCliRow({ cli, meta, original, value, setValue, setEntry, clie
         : hasProviders
         ? (meta.modelsByProvider?.[provider] ?? meta.models)
         : meta.models;
-    const effortOptions = hasProviders
-        ? (meta.effortsByProvider?.[provider] ?? meta.efforts)
-        : meta.efforts;
+    const providerEfforts = hasProviders ? (meta.effortsByProvider?.[provider] ?? meta.efforts) : undefined;
+    // Per-model effort sets from a live opencodex catalog win over the
+    // provider/registry lists; the chosen value is forwarded to the wire.
+    const effortOptions = effortChoicesForModel(meta, value.model || '', providerEfforts, hasProviders ? provider : undefined);
 
     return (
         <div className="settings-percli-row" data-cli={cli}>
@@ -68,7 +70,9 @@ export function PerCliRow({ cli, meta, original, value, setValue, setEntry, clie
                             const nextModels = meta.modelsByProvider?.[next] ?? [];
                             const nextEfforts = meta.effortsByProvider?.[next] ?? [];
                             const nextModel = nextModels.includes(value.model || '') ? (value.model || '') : (nextModels[0] || '');
-                            const nextEffort = nextEfforts.includes(value.effort || '') ? (value.effort || '') : '';
+                            // Resolve against the NEW provider+model pair: the same
+                            // model id can allow different efforts per provider.
+                            const nextEffort = coerceEffortForModel(meta, nextModel, value.effort ?? '', nextEfforts, next);
                             setValue({ ...value, provider: next, model: nextModel, effort: nextEffort });
                             setEntry(`perCli.${cli}.provider`, entryFor(next, original.provider ?? meta.defaultProvider ?? 'claude'));
                             setEntry(`perCli.${cli}.model`, entryFor(nextModel, original.model ?? ''));
@@ -84,8 +88,12 @@ export function PerCliRow({ cli, meta, original, value, setValue, setEntry, clie
                             value={value.model ?? modelOptions[0] ?? ''}
                             options={modelOptions.map((m) => ({ value: m, label: m }))}
                             onChange={(next) => {
-                                setValue({ ...value, model: next });
+                                const nextEffort = coerceEffortForModel(meta, next, value.effort ?? '', providerEfforts, hasProviders ? provider : undefined);
+                                setValue({ ...value, model: next, effort: nextEffort });
                                 setEntry(`perCli.${cli}.model`, entryFor(next, original.model ?? ''));
+                                if (nextEffort !== (value.effort ?? '')) {
+                                    setEntry(`perCli.${cli}.effort`, entryFor(nextEffort, original.effort ?? ''));
+                                }
                             }}
                         />
                     ) : (

package/public/manager/src/settings/pages/components/agent/agent-meta.ts

@@ -6,6 +6,22 @@ export type CliMeta = {
     providers?: ReadonlyArray<string>;
     modelsByProvider?: Record<string, ReadonlyArray<string>>;
     effortsByProvider?: Record<string, ReadonlyArray<string>>;
+    /**
+     * Per-model reasoning-effort sets from a live opencodex catalog. An entry
+     * that exists but is EMPTY means the model takes no effort at all, so it
+     * must not fall back to `efforts`.
+     */
+    effortsByModel?: Record<string, ReadonlyArray<string>>;
+    defaultEffortByModel?: Record<string, string>;
+    /**
+     * Provider-scoped per-model efforts, used by runtimes whose model list is
+     * split by provider (`ai-e`). A flat map would collide on ids shared across
+     * providers — `gpt-5.6-sol` exists under both codex and kiro with different
+     * allowed efforts.
+     */
+    effortsByModelByProvider?: Record<string, Record<string, ReadonlyArray<string>>>;
+    defaultEffortByModelByProvider?: Record<string, Record<string, string>>;
+    modelSource?: string;
     effortNote?: string;
     modelNote?: string;
 };
@@ -230,6 +246,35 @@ function stringArrayRecord(value: unknown): Record<string, string[]> | undefined
     return out;
 }
 
+function stringRecord(value: unknown): Record<string, string> | undefined {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const out: Record<string, string> = {};
+    for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+        if (typeof raw === 'string') out[key] = raw;
+    }
+    return out;
+}
+
+function nestedStringArrayRecord(value: unknown): Record<string, Record<string, string[]>> | undefined {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const out: Record<string, Record<string, string[]>> = {};
+    for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+        const inner = stringArrayRecord(raw);
+        if (inner) out[key] = inner;
+    }
+    return out;
+}
+
+function nestedStringRecord(value: unknown): Record<string, Record<string, string>> | undefined {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const out: Record<string, Record<string, string>> = {};
+    for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+        const inner = stringRecord(raw);
+        if (inner) out[key] = inner;
+    }
+    return out;
+}
+
 export function normalizeCliMetaRegistry(raw: unknown): Record<string, CliMeta> {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
     const out: Record<string, CliMeta> = {};
@@ -238,6 +283,10 @@ export function normalizeCliMetaRegistry(raw: unknown): Record<string, CliMeta>
         const record = value as Record<string, unknown>;
         const modelsByProvider = stringArrayRecord(record['modelsByProvider']);
         const effortsByProvider = stringArrayRecord(record['effortsByProvider']);
+        const effortsByModel = stringArrayRecord(record['effortsByModel']);
+        const defaultEffortByModel = stringRecord(record['defaultEffortByModel']);
+        const effortsByModelByProvider = nestedStringArrayRecord(record['effortsByModelByProvider']);
+        const defaultEffortByModelByProvider = nestedStringRecord(record['defaultEffortByModelByProvider']);
         out[key] = {
             label: typeof record['label'] === 'string' ? record['label'] : key,
             models: stringArray(record['models']),
@@ -246,6 +295,11 @@ export function normalizeCliMetaRegistry(raw: unknown): Record<string, CliMeta>
             ...(record['providers'] ? { providers: stringArray(record['providers']) } : {}),
             ...(modelsByProvider ? { modelsByProvider } : {}),
             ...(effortsByProvider ? { effortsByProvider } : {}),
+            ...(effortsByModel ? { effortsByModel } : {}),
+            ...(defaultEffortByModel ? { defaultEffortByModel } : {}),
+            ...(effortsByModelByProvider ? { effortsByModelByProvider } : {}),
+            ...(defaultEffortByModelByProvider ? { defaultEffortByModelByProvider } : {}),
+            ...(typeof record['modelSource'] === 'string' ? { modelSource: record['modelSource'] } : {}),
             ...(typeof record['effortNote'] === 'string' ? { effortNote: record['effortNote'] } : {}),
             ...(typeof record['modelNote'] === 'string' ? { modelNote: record['modelNote'] } : {}),
         };
@@ -253,6 +307,50 @@ export function normalizeCliMetaRegistry(raw: unknown): Record<string, CliMeta>
     return out;
 }
 
+/**
+ * Effort choices for one model.
+ *
+ * A live opencodex catalog advertises a different effort set per model, and the
+ * chosen value reaches the wire as `-c model_reasoning_effort=`, so the
+ * per-model set wins. An entry that exists but is EMPTY means the model takes
+ * no effort and must not fall back to the provider/registry lists.
+ */
+export function effortChoicesForModel(
+    meta: CliMeta,
+    model: string,
+    providerEfforts?: ReadonlyArray<string>,
+    provider?: string,
+): ReadonlyArray<string> {
+    const key = (model || '').trim();
+    // Provider-scoped map wins for provider-split runtimes. When the map exists
+    // but the model is absent (e.g. a Claude model under ai-e/claude), fall back
+    // to the provider list rather than inventing an empty "no effort" set.
+    if (provider) {
+        const scoped = meta.effortsByModelByProvider?.[provider]?.[key];
+        if (scoped) return scoped;
+    }
+    const byModel = meta.effortsByModel?.[key];
+    if (byModel) return byModel;
+    return providerEfforts ?? meta.efforts;
+}
+
+/** Keep a saved effort only when the model still advertises it. */
+export function coerceEffortForModel(
+    meta: CliMeta,
+    model: string,
+    effort: string,
+    providerEfforts?: ReadonlyArray<string>,
+    provider?: string,
+): string {
+    const choices = effortChoicesForModel(meta, model, providerEfforts, provider);
+    if (effort && choices.includes(effort)) return effort;
+    const key = (model || '').trim();
+    const fallback = (provider ? meta.defaultEffortByModelByProvider?.[provider]?.[key] : undefined)
+        ?? meta.defaultEffortByModel?.[key]
+        ?? '';
+    return choices.includes(fallback) ? fallback : '';
+}
+
 export function metaFor(cli: string, registry?: Record<string, CliMeta> | null): CliMeta {
     return registry?.[cli] || CLI_META[cli] || { label: cli, models: [], efforts: [] };
 }

package/scripts/bundle-sidecar.sh

@@ -165,5 +165,13 @@ fi
 
 node "$PROJECT_ROOT/scripts/check-electron-sidecar-no-jwc.cjs" --server-root "$SIDECAR_DIR"
 
+# Static prune analysis runs before the build; this runs after, on the artifact
+# that will actually ship. The prune guard reasons about bare specifiers and
+# cannot see a computed `import(spec)`, so it can only ever be as complete as
+# its manual RUNTIME_LOADED list. Importing the critical modules for real
+# closes that gap by construction — a dashboard returning 200 never proved the
+# Telegram bot could load.
+node "$PROJECT_ROOT/scripts/check-sidecar-smoke.mjs" --server-root "$SIDECAR_DIR"
+
 echo "=== Sidecar ready ==="
 du -sh "$SIDECAR_DIR"

package/scripts/check-electron-no-native.cjs

@@ -1,7 +1,18 @@
 #!/usr/bin/env node
 const { execSync } = require('node:child_process');
-const NATIVE = ['better-sqlite3', 'playwright-core', 'sharp', 'canvas'];
-const pat = NATIVE.join('|');
+
+// Split, because a single list encoded a false invariant. node-pty IS a native
+// addon, IS an electron dependency, and IS imported by the terminal module —
+// so "electron source has no native deps" was simply untrue, and the one addon
+// that actually ships was the one nothing checked.
+//
+// FORBIDDEN: must never appear in electron/src. Any of these would drag a
+// second native build into the Electron ABI.
+const FORBIDDEN = ['better-sqlite3', 'playwright-core', 'sharp', 'canvas'];
+// EXPECTED_NATIVE: legitimately shipped. Presence here is not a failure, but it
+// IS a promise that a runtime load probe covers it — see check-native-load.cjs.
+const EXPECTED_NATIVE = ['node-pty'];
+const pat = FORBIDDEN.join('|');
 // Match any of:
 //   from "pkg" / from 'pkg'
 //   require("pkg") / require('pkg')
@@ -13,7 +24,82 @@ try {
 } catch (e) { out = ''; }
 const matches = out.trim();
 if (matches) {
-  console.error('❌ Native dep imports detected in electron/src:\n' + matches);
+  console.error('❌ Forbidden native dep imports detected in electron/src:\n' + matches);
   process.exit(1);
 }
-console.log('✅ Electron source has no native deps');
+
+// A bare-specifier grep only sees the first hop. electron/src already reaches
+// across the tree boundary with relative paths (electron/src/main/lib/folder/ipc.ts
+// imports into src/manager/git/*), and src/manager/reminders/store.ts imports
+// better-sqlite3 — so the guard is one careless import away from being wrong
+// while still printing a pass. Follow the relative graph transitively.
+const { existsSync, readFileSync } = require('node:fs');
+const { dirname, resolve, join } = require('node:path');
+
+function resolveModule(spec, fromFile) {
+  const base = resolve(dirname(fromFile), spec.replace(/\.js$/, ''));
+  for (const candidate of [
+    `${base}.ts`, `${base}.tsx`, `${base}.mts`, `${base}.cts`,
+    join(base, 'index.ts'), join(base, 'index.tsx'),
+    `${base}.js`,
+  ]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** `sharp` and `sharp/lib/x.js` are the same dependency. */
+function isForbidden(spec) {
+  return FORBIDDEN.some(pkg => spec === pkg || spec.startsWith(`${pkg}/`));
+}
+
+function crawl(entryFiles) {
+  const seen = new Set();
+  const queue = [...entryFiles];
+  const violations = [];
+  let unresolved = 0;
+  while (queue.length > 0) {
+    const file = queue.pop();
+    if (!file || seen.has(file)) continue;
+    seen.add(file);
+    let source = '';
+    try { source = readFileSync(file, 'utf8'); } catch { continue; }
+    // Covers `from 'x'`, `require('x')`, `import('x')`, and the bare
+    // side-effect form `import 'x';` — the last one is easy to miss and is
+    // exactly how an unnoticed dependency creeps in.
+    const specRe = /(?:from|require\(|import\(|^\s*import)\s*['"]([^'"]+)['"]/gm;
+    let match;
+    while ((match = specRe.exec(source)) !== null) {
+      const spec = match[1];
+      if (isForbidden(spec)) {
+        violations.push(`${file}: imports ${spec}`);
+        continue;
+      }
+      if (!spec.startsWith('.')) continue;
+      const resolved = resolveModule(spec, file);
+      if (resolved) queue.push(resolved);
+      // A silently dropped specifier is a hole in the crawl that looks
+      // identical to a clean result, so count and report them.
+      else unresolved += 1;
+    }
+  }
+  return { violations, scanned: seen.size, unresolved };
+}
+
+let entries = [];
+try {
+  entries = execSync('find electron/src -name "*.ts" -o -name "*.tsx"', { encoding: 'utf8' })
+    .split('\n').map(s => s.trim()).filter(Boolean).map(f => resolve(f));
+} catch { entries = []; }
+
+const { violations, scanned, unresolved } = crawl(entries);
+if (violations.length > 0) {
+  console.error('❌ Forbidden native dep reachable from electron/src via relative imports:');
+  for (const line of violations) console.error(`   - ${line}`);
+  console.error('\nThese would need an Electron-ABI rebuild; the sidecar builds for Node.');
+  process.exit(1);
+}
+// Known limit, stated rather than implied: computed specifiers
+// (`import(`../${name}.js`)`) and `createRequire(...)('pkg')` are invisible to
+// a text scan — the same blind spot the sidecar prune guard documents.
+console.log(`✅ Electron source has no forbidden native deps (scanned ${scanned} files transitively${unresolved ? `, ${unresolved} relative specifiers unresolved` : ''}; expected native: ${EXPECTED_NATIVE.join(', ')})`);

package/scripts/check-native-load.cjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Runtime load probe for shipped native addons (260803 unit, 040 phase D1).
+ *
+ * Static grep proves a module is imported. It does not prove the binary loads.
+ * The v2.2.10 incident made that concrete: the dashboard returned HTTP 200
+ * while the Telegram bot could not resolve a pruned dependency. Presence is
+ * not liveness.
+ *
+ * node-pty@1.1.0 is N-API based (node-addon-api, 38 napi_ symbols, zero v8/Nan),
+ * so a NODE_MODULE_VERSION mismatch is NOT the risk here. What can still break
+ * is architecture, asarUnpack placement, and the executable bit on
+ * `spawn-helper` — none of which a grep can see. So we dlopen the binary and,
+ * where possible, actually run a pty.
+ *
+ * Usage:
+ *   node scripts/check-native-load.cjs                      # check the repo tree
+ *   node scripts/check-native-load.cjs --app <path/to.app>   # check a packaged app
+ */
+const { existsSync, statSync, readdirSync, constants, accessSync } = require('node:fs');
+const { join } = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const args = process.argv.slice(2);
+const appIndex = args.indexOf('--app');
+const appPath = appIndex >= 0 ? args[appIndex + 1] : null;
+
+const failures = [];
+const notes = [];
+
+function fail(message) { failures.push(message); }
+function note(message) { notes.push(message); }
+
+function findPtyRoot() {
+  if (appPath) {
+    // electron-builder unpacks asarUnpack entries next to the asar.
+    const unpacked = join(appPath, 'Contents', 'Resources', 'app.asar.unpacked', 'node_modules', 'node-pty');
+    if (existsSync(unpacked)) return unpacked;
+    const plain = join(appPath, 'Contents', 'Resources', 'app', 'node_modules', 'node-pty');
+    if (existsSync(plain)) return plain;
+    return null;
+  }
+  const local = join(process.cwd(), 'electron', 'node_modules', 'node-pty');
+  return existsSync(local) ? local : null;
+}
+
+const ptyRoot = findPtyRoot();
+// Exit 3 = nothing was probed. The caller must not present this as a pass;
+// a green "loads fine" when nothing loaded is the exact dishonesty this
+// script exists to remove.
+const EXIT_SKIPPED = 3;
+if (!ptyRoot) {
+  if (appPath) {
+    fail(`node-pty not found in ${appPath}. asarUnpack must keep it outside the asar (electron-builder.yml asarUnpack: node_modules/node-pty/**/*); a packed addon cannot be dlopen'd.`);
+  } else if (process.env.JAW_GATE_REQUIRE_NATIVE === '1') {
+    // Opt-in requirement rather than a blanket CI check. The node-tests
+    // workflow runs `npm ci --ignore-scripts` at the root only, so it never
+    // has electron/node_modules at all: keying on CI made this gate demand an
+    // artifact that context cannot produce, and every PR went red for it.
+    // The flag is set where the artifact really exists (desktop-release, right
+    // after `npm ci --prefix electron`), so a miss there is a genuine failure.
+    fail('electron/node_modules/node-pty is absent but JAW_GATE_REQUIRE_NATIVE=1 demanded a real probe (run npm i in electron/)');
+  } else {
+    console.log('ℹ node-pty not installed in electron/node_modules — nothing probed (run npm i in electron/)');
+    process.exit(EXIT_SKIPPED);
+  }
+} else {
+  const binary = join(ptyRoot, 'build', 'Release', 'pty.node');
+  if (!existsSync(binary)) {
+    fail(`missing native binary: ${binary}`);
+  } else {
+    // 1. The binary must actually dlopen under this runtime.
+    try {
+      const handle = { exports: {} };
+      process.dlopen(handle, binary, constants.dlopen?.RTLD_NOW ?? undefined);
+      note(`dlopen ok: ${binary}`);
+    } catch (error) {
+      fail(`dlopen failed for ${binary}: ${(error && error.message) || error}`);
+    }
+
+    // 2. spawn-helper must be present AND executable, or every pty dies at
+    //    runtime with a permission error that no import check would catch.
+    const helper = join(ptyRoot, 'build', 'Release', 'spawn-helper');
+    if (process.platform !== 'win32') {
+      if (!existsSync(helper)) {
+        fail(`missing spawn-helper: ${helper}`);
+      } else {
+        try {
+          accessSync(helper, constants.X_OK);
+          note(`spawn-helper executable: mode ${(statSync(helper).mode & 0o777).toString(8)}`);
+        } catch {
+          fail(`spawn-helper is not executable: ${helper} (mode ${(statSync(helper).mode & 0o777).toString(8)})`);
+        }
+      }
+    }
+
+    // 3. Architecture must match the host, or dlopen succeeds nowhere useful.
+    try {
+      const prebuilds = join(ptyRoot, 'prebuilds');
+      if (existsSync(prebuilds)) {
+        note(`prebuilds present: ${readdirSync(prebuilds).join(', ')}`);
+      }
+    } catch { /* informational only */ }
+
+    // 4. Actually spawn a pty and read from it. access(X_OK) says the bit is
+    //    set; it does not say codesign, quarantine, or arch let the helper run.
+    //    Only a real spawn covers that, and it is the failure a user would hit
+    //    on their first terminal session in the shipped app.
+    if (!appPath) {
+      // Run the round-trip in a child so we can wait on it without blocking
+      // this process's event loop — pty data arrives via callbacks, so a
+      // synchronous wait here would guarantee a false negative.
+      const probe = `
+        const pty = require(${JSON.stringify(ptyRoot)});
+        // cmd.exe does not understand POSIX -c; it needs /c (with /d /s to skip
+        // AutoRun and keep quote handling predictable). Passing -c made the
+        // shell exit non-zero and print usage, so the probe would have reported
+        // a broken spawn-helper on Windows even when the addon was healthy.
+        const isWin = process.platform === 'win32';
+        const shell = isWin ? 'cmd.exe' : '/bin/sh';
+        const shellArgs = isWin ? ['/d', '/s', '/c', 'echo jaw-pty-ok'] : ['-c', 'echo jaw-pty-ok'];
+        const term = pty.spawn(shell, shellArgs, {
+          name: 'xterm-color', cols: 80, rows: 24, cwd: process.cwd(), env: process.env,
+        });
+        let seen = '';
+        const done = (code) => { try { term.kill(); } catch {} process.exit(code); };
+        term.onData((chunk) => { seen += chunk; if (seen.includes('jaw-pty-ok')) done(0); });
+        setTimeout(() => done(seen.includes('jaw-pty-ok') ? 0 : 7), 5000);
+      `;
+      try {
+        execFileSync(process.execPath, ['-e', probe], { timeout: 15_000, stdio: 'ignore' });
+        note('pty spawn round-trip ok (spawn-helper genuinely executes)');
+      } catch (error) {
+        const status = error && error.status;
+        if (status === 7) {
+          fail('pty spawned but produced no output within 5s — spawn-helper may be blocked by codesign/quarantine');
+        } else {
+          // The child's message embeds the whole probe source; keep only the
+          // first meaningful line so the build log stays readable.
+          const raw = String((error && error.message) || error);
+          const firstLine = raw.split('\n').find(l => /Error|EACCES|EPERM|ENOENT/.test(l)) || raw.split('\n')[0];
+          fail(`pty spawn failed: ${firstLine.trim()}`);
+        }
+      }
+    } else {
+      note('packaged app: spawn round-trip skipped (needs the Electron runtime); dlopen + permissions checked');
+    }
+  }
+}
+
+for (const line of notes) console.log(`   ${line}`);
+if (failures.length > 0) {
+  console.error('❌ native load probe failed:');
+  for (const line of failures) console.error(`   - ${line}`);
+  process.exit(1);
+}
+console.log(`✅ native addons load${appPath ? ` in ${appPath}` : ''}`);

package/scripts/check-sidecar-smoke.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Post-bundle import smoke for the packaged sidecar (260803 unit, 040 phase D3).
+ *
+ * `check-sidecar-prune-safety.mjs` reasons about the prune list statically: it
+ * parses PRUNE_PKGS out of the shell script, scans source for bare specifiers,
+ * and walks the transitive closure through dependencies/optionalDependencies/
+ * peerDependencies. That closure is what catches the second half of the v2.2.10
+ * incident (`node-fetch → fetch-blob → web-streams-polyfill`).
+ *
+ * What it cannot see is a computed specifier — `import(someVariable)`. The
+ * authors knew, which is why RUNTIME_LOADED exists as a manual escape hatch
+ * with exactly one entry. Any future dynamic import that nobody remembers to
+ * register reproduces the incident in a new shape.
+ *
+ * This closes that by construction: after the bundle exists, actually import
+ * the modules whose failure was invisible last time. A dashboard returning 200
+ * never proved the Telegram bot could load; importing it does.
+ *
+ * Usage: node scripts/check-sidecar-smoke.mjs [--server-root <dir>]
+ */
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+
+const args = process.argv.slice(2);
+const rootIndex = args.indexOf('--server-root');
+// An explicit --server-root means the caller built the bundle and knows where
+// it should be (bundle-sidecar.sh passes it immediately after bundling), so a
+// missing tree there is a real failure rather than "nothing to check".
+const explicitServerRoot = rootIndex >= 0;
+if (explicitServerRoot && !args[rootIndex + 1]) {
+    console.error('❌ --server-root requires a directory argument');
+    process.exit(2);
+}
+const serverRoot = resolve(explicitServerRoot ? args[rootIndex + 1] : 'electron/sidecar/server');
+
+/**
+ * Entry surfaces whose load failure would be silent in a running app: each is
+ * reached only on a specific user action, so a healthy dashboard says nothing
+ * about them. `telegram/bot.js` is the exact module the v2.2.10 prune broke.
+ */
+const CRITICAL_MODULES = [
+    'dist/src/telegram/bot.js',
+    'dist/server.js',
+    'dist/src/manager/server.js',
+];
+
+/**
+ * Exit code 3 = "nothing to check". The caller must NOT report this as a pass:
+ * a gate that says "imports verified" when it imported nothing is the same
+ * dishonest-green this script exists to eliminate.
+ */
+const EXIT_SKIPPED = 3;
+
+if (!existsSync(serverRoot)) {
+    // Keying this on CI made the gate demand a bundle that the node-tests
+    // workflow never builds, so every PR failed here. Require a real check
+    // only where the caller actually produced (or explicitly named) the tree.
+    if (explicitServerRoot || process.env['JAW_GATE_REQUIRE_SIDECAR'] === '1') {
+        console.error(`❌ sidecar not bundled at ${serverRoot} but the caller required a real smoke test`);
+        process.exit(1);
+    }
+    console.log(`ℹ sidecar not bundled at ${serverRoot} — skipping smoke (run scripts/bundle-sidecar.sh first)`);
+    process.exit(EXIT_SKIPPED);
+}
+
+const failures = [];
+let checked = 0;
+const seenCauses = new Set();
+
+// Redirect the probe's home to a throwaway directory. Importing these modules
+// regenerates AGENTS.md and touches the DB; a gate must not mutate the
+// developer's real ~/.cli-jaw just by checking that the bundle loads.
+const probeHome = mkdtempSync(join(tmpdir(), 'jaw-smoke-home-'));
+
+for (const relative of CRITICAL_MODULES) {
+    const target = join(serverRoot, relative);
+    if (!existsSync(target)) {
+        failures.push(`${relative}: not present in the bundle`);
+        continue;
+    }
+    checked += 1;
+    // Import in a CHILD process, never in-process. These modules are not inert:
+    // dist/server.js binds ports, opens the DB, starts timers and writes user
+    // state. Importing them here would hang the build forever and mutate the
+    // developer's ~/.cli-jaw. We only need to know that resolution + top-level
+    // evaluation get far enough to not throw, so a bounded child that we kill
+    // is both sufficient and safe.
+    const child = spawnSync(
+        process.execPath,
+        ['--input-type=module', '-e', `await import(${JSON.stringify(pathToFileURL(target).href)}); process.exit(0);`],
+        {
+            encoding: 'utf8',
+            timeout: 30_000,
+            killSignal: 'SIGKILL',
+            env: {
+                ...process.env,
+                JAW_SMOKE_PROBE: '1',
+                CLI_JAW_HOME: probeHome,
+                // Keep the probe off any port the developer or CI is using.
+                PORT: '0',
+                DASHBOARD_PORT: '0',
+            },
+        },
+    );
+
+    // A module that boots a server never exits on its own; the timeout kill is
+    // the SUCCESS signal there, because it means the import itself resolved.
+    const timedOut = child.error && child.error.code === 'ETIMEDOUT';
+    const importFailed = !timedOut
+        && child.status !== 0
+        && /ERR_MODULE_NOT_FOUND|ERR_REQUIRE_ESM|Cannot find package|Cannot find module/.test(child.stderr || '');
+
+    if (importFailed) {
+        // Prefer the human-readable "Cannot find package 'x'" line over the
+        // internal `throw new ERR_MODULE_NOT_FOUND(...)` frame, which names no
+        // package and is useless in a build log.
+        const stderrLines = (child.stderr || '').split('\n');
+        const line = stderrLines.find(l => /Cannot find (package|module)/.test(l))
+            || stderrLines.find(l => /ERR_[A-Z_]+/.test(l))
+            || `exit ${child.status}`;
+        const cause = line.trim();
+        if (!seenCauses.has(cause)) {
+            seenCauses.add(cause);
+            failures.push(`${relative}: ${cause}`);
+        } else {
+            failures.push(`${relative}: (same cause as above)`);
+        }
+        continue;
+    }
+    console.log(`   loaded: ${relative}${timedOut ? ' (kept running — import resolved)' : ''}`);
+}
+
+try {
+    rmSync(probeHome, { recursive: true, force: true });
+} catch {
+    // best effort
+}
+
+if (failures.length > 0) {
+    console.error('❌ sidecar smoke failed — the bundle is missing something it needs at runtime:');
+    for (const line of failures) console.error(`   - ${line}`);
+    console.error('\nThis is the v2.2.10 class: the app would start and look healthy, then fail');
+    console.error('on first use of the affected surface. Check the prune list in scripts/bundle-sidecar.sh.');
+    process.exit(1);
+}
+
+console.log(`✅ sidecar smoke ok (${checked} critical modules imported from ${serverRoot})`);