cli-jaw 2.2.15 → 2.2.17

package/public/manager/src/manager-components.css

@@ -302,6 +302,103 @@ h2 { font-size: 13px; }
 .quick-btn.action-open { text-decoration: none; color: var(--text-secondary); }
 .quick-btn.action-open:hover { color: var(--accent); border-color: color-mix(in srgb, var(--accent) 40%, var(--border-subtle)); }
 .quick-btn:disabled, .quick-btn.is-disabled { opacity: 0.35; pointer-events: none; }
+.quick-btn.action-sessions[aria-expanded="true"] {
+    color: var(--accent);
+    border-color: color-mix(in srgb, var(--accent) 40%, var(--border-subtle));
+}
+
+/* ─── Active-row session disclosure (devlog 260806 D2) ─── */
+.instance-session-list {
+    display: grid;
+    gap: 2px;
+    margin: -2px 0 8px;
+    padding: 6px;
+    border: 1px solid var(--border-subtle);
+    border-radius: 8px;
+    background: var(--row-bg);
+    animation: session-list-in 0.12s ease;
+}
+@keyframes session-list-in {
+    from { opacity: 0; transform: translateY(-2px); }
+    to { opacity: 1; transform: none; }
+}
+@media (prefers-reduced-motion: reduce) {
+    .instance-session-list { animation: none; }
+}
+.instance-session-row {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+    width: 100%;
+    padding: 5px 8px;
+    border: 0;
+    border-radius: 6px;
+    background: transparent;
+    color: var(--text-secondary);
+    font-size: 12px;
+    text-align: left;
+    cursor: pointer;
+}
+.instance-session-row:hover:not(:disabled) { background: var(--row-bg-hover); color: var(--text-primary); }
+.instance-session-row:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
+.instance-session-row:disabled { cursor: default; opacity: 0.6; }
+.instance-session-row.is-active {
+    color: var(--text-primary);
+    box-shadow: inset 3px 0 0 var(--accent);
+    background: color-mix(in srgb, var(--accent) 5%, transparent);
+}
+.instance-session-title {
+    min-width: 0;
+    display: flex;
+    align-items: baseline;
+    gap: 6px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+.session-source-badge {
+    flex-shrink: 0;
+    padding: 1px 5px;
+    border: 1px solid var(--border-subtle);
+    border-radius: 999px;
+    font-size: 10px;
+    color: var(--text-tertiary, var(--text-secondary));
+    text-transform: lowercase;
+}
+.instance-session-meta {
+    flex-shrink: 0;
+    font-size: 11px;
+    color: var(--text-tertiary, var(--text-secondary));
+    font-variant-numeric: tabular-nums;
+}
+.instance-session-error, .instance-session-empty {
+    padding: 5px 8px;
+    font-size: 11px;
+    color: var(--text-secondary);
+}
+.instance-session-error {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+    color: var(--status-error);
+}
+.instance-session-retry {
+    flex: 0 0 auto;
+    padding: 2px 7px;
+    border: 1px solid var(--border-subtle);
+    border-radius: 5px;
+    background: var(--row-bg);
+    color: var(--text-secondary);
+    font: inherit;
+    cursor: pointer;
+}
+.instance-session-retry:hover {
+    color: var(--text-primary);
+    background: var(--surface-raised);
+}
+.instance-session-retry:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
 .instance-row-title { min-width: 0; display: grid; gap: 3px; }
 .instance-row-title-line {
     min-width: 0;

package/public/manager/src/settings/pages/AdvancedExport.tsx

@@ -34,7 +34,17 @@ export function validateImportPayload(text: string): { ok: true; value: Record<s
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         return { ok: false, error: 'Import payload must be a JSON object.' };
     }
-    return { ok: true, value: parsed as Record<string, unknown> };
+    return { ok: true, value: stripServerOwnedSettingsFields(parsed as Record<string, unknown>) };
+}
+
+export function stripServerOwnedSettingsFields(settings: Record<string, unknown>): Record<string, unknown> {
+    const {
+        settingsSchemaVersion: _schema,
+        runtimeDefaultMigration: _migration,
+        multiSessionDefaultMigration: _sessionMigration,
+        ...userOwned
+    } = settings;
+    return userOwned;
 }
 
 export default function AdvancedExport({ port, client, triggerDownload }: ExportImportProps) {
@@ -55,7 +65,7 @@ export default function AdvancedExport({ port, client, triggerDownload }: Export
     const onExport = useCallback(() => {
         if (state.kind !== 'ready') return;
         const filename = `cli-jaw-settings-${port}.json`;
-        download(filename, JSON.stringify(state.data, null, 2));
+        download(filename, JSON.stringify(stripServerOwnedSettingsFields(state.data), null, 2));
     }, [state, port, download]);
 
     const onImport = useCallback(async () => {

package/public/manager/src/settings/pages/Agent.tsx

@@ -35,6 +35,8 @@ import {
     splitAgentSaveBundle,
     type AgentSettingsSnapshot,
 } from './components/agent/agent-save';
+import { SettingsRequestError } from '../settings-client';
+import { describeError } from '../components/error-normalize';
 
 export { splitAgentSaveBundle };
 
@@ -44,8 +46,30 @@ type AgentSnapshot = AgentSettingsSnapshot & {
     permissions?: 'auto' | string[] | unknown;
     perCli?: Record<string, PerCliEntry>;
     activeOverrides?: Record<string, ActiveOverride>;
+    runtimeDefaultMigration?: {
+        id: string;
+        state: 'pending' | 'accepted' | 'kept' | 'already-codex-app';
+        fromCli: string;
+        toCli: 'codex-app';
+    } | null;
 };
 
+type CliStatusInfo = {
+    available: boolean | null;
+    capabilityReady: boolean | null;
+    probeState: 'checking' | 'fresh' | 'stale';
+};
+
+export function conflictSettingsFromError(error: unknown): AgentSnapshot | null {
+    if (!(error instanceof SettingsRequestError) || error.status !== 409) return null;
+    try {
+        const payload = JSON.parse(error.detail) as { settings?: AgentSnapshot };
+        return payload.settings ?? null;
+    } catch {
+        return null;
+    }
+}
+
 type FlushSnapshot = {
     cli?: string;
     model?: string;
@@ -80,6 +104,11 @@ export default function Agent({ port, client, dirty, registerSave }: SettingsPag
     const [employeeLoading, setEmployeeLoading] = useState(true);
     const [employeeError, setEmployeeError] = useState<string | null>(null);
     const [cliMeta, setCliMeta] = useState<Record<string, CliMeta> | null>(null);
+    const [cliStatus, setCliStatus] = useState<Record<string, CliStatusInfo>>({});
+    const [migrationBusy, setMigrationBusy] = useState(false);
+    const [migrationError, setMigrationError] = useState<string | null>(null);
+    const [sessionMigrationBusy, setSessionMigrationBusy] = useState(false);
+    const [sessionMigrationError, setSessionMigrationError] = useState<string | null>(null);
 
     const loadCliMeta = useCallback(async () => {
         try {
@@ -93,6 +122,11 @@ export default function Agent({ port, client, dirty, registerSave }: SettingsPag
         }
     }, [client]);
 
+    const loadCliStatus = useCallback(async () => {
+        try { setCliStatus(await client.get<Record<string, CliStatusInfo>>('/api/cli-status')); }
+        catch { setCliStatus({}); }
+    }, [client]);
+
     const loadFlush = useCallback(async () => {
         setFlushLoading(true);
         setFlushError(null);
@@ -125,9 +159,10 @@ export default function Agent({ port, client, dirty, registerSave }: SettingsPag
 
     useEffect(() => {
         void loadCliMeta();
+        void loadCliStatus();
         void loadFlush();
         void loadEmployees();
-    }, [loadCliMeta, loadEmployees, loadFlush]);
+    }, [loadCliMeta, loadCliStatus, loadEmployees, loadFlush]);
 
     useEffect(() => {
         if (state.kind !== 'ready') return;
@@ -199,6 +234,58 @@ export default function Agent({ port, client, dirty, registerSave }: SettingsPag
         : effortChoicesForModel(activeMeta, draft.model);
     const workingDirError = draft.workingDir.trim() ? null : 'Required';
 
+    const resolveMigration = useCallback(async (action: 'accept' | 'keep') => {
+        setMigrationBusy(true);
+        setMigrationError(null);
+        try {
+            const response = await client.post<AgentSnapshot | { data?: AgentSnapshot; settings?: AgentSnapshot }>(
+                '/api/settings/runtime-default-migration',
+                { action },
+            );
+            let next: AgentSnapshot;
+            if ('settings' in response && response.settings) next = response.settings as AgentSnapshot;
+            else if ('data' in response && response.data) next = response.data as AgentSnapshot;
+            else next = response as AgentSnapshot;
+            setData(next);
+        } catch (error) {
+            const conflictSettings = conflictSettingsFromError(error);
+            if (conflictSettings) {
+                setData(conflictSettings);
+                return;
+            }
+            setMigrationError(describeError(error));
+        } finally {
+            setMigrationBusy(false);
+        }
+    }, [client, setData]);
+
+    // Same shape, its own endpoint and its own busy state, because a v1 install has both
+    // migrations pending and answering one must not look like answering the other.
+    const resolveSessionMigration = useCallback(async (action: 'accept' | 'keep') => {
+        setSessionMigrationBusy(true);
+        setSessionMigrationError(null);
+        try {
+            const response = await client.post<AgentSnapshot | { data?: AgentSnapshot; settings?: AgentSnapshot }>(
+                '/api/settings/multi-session-default-migration',
+                { action },
+            );
+            let next: AgentSnapshot;
+            if ('settings' in response && response.settings) next = response.settings as AgentSnapshot;
+            else if ('data' in response && response.data) next = response.data as AgentSnapshot;
+            else next = response as AgentSnapshot;
+            setData(next);
+        } catch (error) {
+            const conflictSettings = conflictSettingsFromError(error);
+            if (conflictSettings) {
+                setData(conflictSettings);
+                return;
+            }
+            setSessionMigrationError(describeError(error));
+        } finally {
+            setSessionMigrationBusy(false);
+        }
+    }, [client, setData]);
+
     if (state.kind === 'loading') return <PageLoading />;
     if (state.kind === 'offline') return <PageOffline port={port} />;
     if (state.kind === 'error') return <PageError message={state.message} />;
@@ -221,6 +308,31 @@ export default function Agent({ port, client, dirty, registerSave }: SettingsPag
                 void onSave();
             }}
         >
+            {settingsData.runtimeDefaultMigration?.state === 'pending' ? (
+                <div className="settings-inline-notice" role="status">
+                    <strong>기본 런타임 변경 안내</strong>
+                    <p>기존 선택은 유지됩니다. Codex App으로 전환하거나 현재 런타임을 계속 사용할 수 있습니다.</p>
+                    <div className="settings-inline-actions">
+                        <button type="button" className="settings-action settings-action-save" disabled={migrationBusy} onClick={() => void resolveMigration('accept')}>Codex App 사용</button>
+                        <button type="button" className="settings-action settings-action-secondary" disabled={migrationBusy} onClick={() => void resolveMigration('keep')}>현재 런타임 유지</button>
+                    </div>
+                    {migrationError ? <span className="settings-field-error" role="alert">{migrationError}</span> : null}
+                </div>
+            ) : null}
+            {(settingsData['multiSessionDefaultMigration'] as Record<string, unknown> | undefined)?.['state'] === 'pending' ? (
+                <div className="settings-inline-notice" role="status">
+                    <strong>다중 세션 안내</strong>
+                    <p>대화 세션을 여러 개 열 수 있습니다. 켜면 동시 실행도 2로 올라가서, 두 번째 세션이 첫 번째가 끝나기를 기다리지 않습니다. 지금 설정은 그대로 유지됩니다.</p>
+                    <div className="settings-inline-actions">
+                        <button type="button" className="settings-action settings-action-save" disabled={sessionMigrationBusy} onClick={() => void resolveSessionMigration('accept')}>다중 세션 켜기</button>
+                        <button type="button" className="settings-action settings-action-secondary" disabled={sessionMigrationBusy} onClick={() => void resolveSessionMigration('keep')}>지금 설정 유지</button>
+                    </div>
+                    {sessionMigrationError ? <span className="settings-field-error" role="alert">{sessionMigrationError}</span> : null}
+                </div>
+            ) : null}
+            {cliStatus[draft.cli]?.probeState === 'checking' ? (
+                <div className="settings-inline-notice" role="status" aria-live="polite">상태 확인 중</div>
+            ) : null}
             <RuntimeHeader
                 cli={draft.cli}
                 cliOptions={cliOptions.length > 0 ? cliOptions : [draft.cli || 'claude']}

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

@@ -102,7 +102,7 @@ export const CLI_META: Record<string, CliMeta> = {
         // parsed by Claude Code (stripped before send, enables 1M context
         // on Fable 5 + Sonnet 5 + Opus 5 + Opus 4.8/4.7/4.6 + Sonnet 4.6). Mirrors getDefaultClaudeChoices()
         // in src/cli/claude-models.ts. Verified via Grok web research
-        // 2026-05-01 (devlog/_plan/260501_claude_model_passthrough/).
+        // 2026-05-01 (devlog/_fin/260501_claude_model_passthrough/).
         models: [
             'opus',
             'sonnet',

package/scripts/bundle-sidecar.sh

@@ -111,6 +111,16 @@ fi
 echo "Rebuilding better-sqlite3 for bundled Node $NODE_VERSION..."
 while IFS= read -r pkg_json; do
   pkg_dir="$(dirname "$pkg_json")"
+  # better-sqlite3 >= 13 is Node-API: it ships prebuilds/ inside the package,
+  # has NO scripts.install (`npm run install` dies with "Missing script"), and
+  # the prebuild is ABI-independent, so no per-Node rebuild is needed at all.
+  # v12 keeps the old install script ("prebuild-install || node-gyp rebuild").
+  # The verification step below opens the DB with the bundled Node either way.
+  has_install_script="$("$NODE_BIN" -e 'const p=require(process.argv[1]);process.stdout.write(p.scripts&&p.scripts.install?"yes":"no")' "$pkg_json")"
+  if [ "$has_install_script" = "no" ]; then
+    echo "  skip rebuild (v13+ bundled prebuilds): ${pkg_dir#$SIDECAR_DIR/}"
+    continue
+  fi
   echo "  rebuild: ${pkg_dir#$SIDECAR_DIR/}"
   (
     cd "$pkg_dir"
@@ -126,8 +136,23 @@ done < <(find "$SIDECAR_DIR/node_modules" -path '*/better-sqlite3/package.json'
 
 echo "Verifying better-sqlite3 opens with bundled Node..."
 "$NODE_BIN" -e "const Database = require('better-sqlite3'); new Database(':memory:').close()" && echo "  better-sqlite3 OK" || {
-  echo "ERROR: better-sqlite3 failed to open with bundled Node"
-  exit 1
+  echo "  bundled prebuild failed to load — building from source (v13 build-release)..."
+  sidecar_bsql_dir="$SIDECAR_DIR/node_modules/better-sqlite3"
+  if [ -d "$sidecar_bsql_dir" ]; then
+    (
+      cd "$sidecar_bsql_dir"
+      PYTHON="$PYTHON_BIN" \
+      npm_config_python="$PYTHON_BIN" \
+      npm_config_runtime=node \
+      npm_config_target="$NODE_VERSION" \
+      npm_config_disturl="https://nodejs.org/dist" \
+        npm run build-release --foreground-scripts
+    )
+  fi
+  "$NODE_BIN" -e "const Database = require('better-sqlite3'); new Database(':memory:').close()" && echo "  better-sqlite3 OK (source build)" || {
+    echo "ERROR: better-sqlite3 failed to open with bundled Node"
+    exit 1
+  }
 }
 
 echo "Cleaning up Node extract..."
@@ -173,5 +198,28 @@ node "$PROJECT_ROOT/scripts/check-electron-sidecar-no-jwc.cjs" --server-root "$S
 # Telegram bot could load.
 node "$PROJECT_ROOT/scripts/check-sidecar-smoke.mjs" --server-root "$SIDECAR_DIR"
 
+# Sidecar install-state receipt. The sidecar is deliberately built with
+# --ignore-scripts, so postinstall-guard never runs here and its receipt would
+# be absent — which the runtime integrity check would misread as a blocked
+# install and nag every desktop user. This is a controlled build: writing the
+# receipt ourselves, with the sidecar's own package version, is the honest
+# record of what happened.
+echo "Writing sidecar install-state receipt..."
+"$NODE_BIN" -e '
+const fs = require("fs"), path = require("path");
+const root = process.argv[1];
+const packageVersion = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+fs.writeFileSync(path.join(root, ".jaw-install-state.json"), JSON.stringify({
+  schema: 1,
+  state: "completed",
+  sidecar: true,
+  packageVersion,
+  ranAt: new Date().toISOString(),
+  node: process.version,
+  platform: process.platform,
+  arch: process.arch,
+}, null, 2));
+' "$SIDECAR_DIR"
+
 echo "=== Sidecar ready ==="
 du -sh "$SIDECAR_DIR"

package/scripts/burst-scenario.mjs

@@ -0,0 +1,72 @@
+// Burst measurement for the 260806 rate-limit hardening unit (devlog 050).
+// Three sequential phases so before/after runs are deterministic:
+//   0. fetch + validate the Bearer token BEFORE any load (429-impossible here)
+//   1. "sacrificial" lane: 350 unheadered (browser-class) GETs, concurrency 20
+//      — exceeds the browser poll budget (300/min) to force the 429 branch
+//   2. "protected" lane: Bearer (cli-class) chat-sessions/switch/goal traffic
+//      — must see zero 429s after hardening; deterministically 429s before it
+//      (the old single 120/min bucket is already exhausted by phase 1).
+// Usage: node scripts/burst-scenario.mjs --port <P> --switch-seq <N> [--sacrificial-count 350]
+
+const args = process.argv.slice(2);
+function argOf(name, fallback) {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : fallback;
+}
+const PORT = Number(argOf('--port'));
+const SWITCH_SEQ = argOf('--switch-seq', '');
+const SACRIFICIAL = Number(argOf('--sacrificial-count', '350'));
+if (!PORT) { console.error('usage: burst-scenario.mjs --port <P> --switch-seq <N>'); process.exit(1); }
+const BASE = `http://127.0.0.1:${PORT}`;
+
+// Phase 0 — token first: after phase 1 exhausts the shared bucket, a
+// pre-hardening server would 429 the token endpoint itself.
+const tokenRes = await fetch(`${BASE}/api/auth/token`);
+const token = tokenRes.ok ? (await tokenRes.json()).token || '' : '';
+if (!token) { console.error('token fetch failed — aborting'); process.exit(1); }
+const AUTH = { Authorization: `Bearer ${token}` };
+
+async function fire(url, init = {}) {
+    try {
+        const res = await fetch(url, init);
+        return { status: res.status, retryAfter: res.headers.get('retry-after') };
+    } catch {
+        return { status: 0, retryAfter: null };
+    }
+}
+
+// Phase 1 — sacrificial burst, bounded concurrency 20, single-window guard.
+const phase1Start = Date.now();
+const sacrificial = { total: 0, s429: 0, retryAfterSeen: false };
+let inFlight = [];
+for (let i = 0; i < SACRIFICIAL; i++) {
+    inFlight.push(fire(`${BASE}/api/messages/count`).then(r => {
+        sacrificial.total++;
+        if (r.status === 429) {
+            sacrificial.s429++;
+            if (r.retryAfter) sacrificial.retryAfterSeen = true;
+        }
+    }));
+    if (inFlight.length >= 20) { await Promise.all(inFlight); inFlight = []; }
+}
+await Promise.all(inFlight);
+const phase1ElapsedMs = Date.now() - phase1Start;
+if (phase1ElapsedMs > 45_000) {
+    console.error(`phase 1 took ${phase1ElapsedMs}ms — crossed the window boundary, scenario invalid`);
+    process.exit(1);
+}
+
+// Phase 2 — protected lane (cli class via Bearer).
+const protectedLane = { total: 0, s429: 0 };
+function track(promise) {
+    return promise.then(r => { protectedLane.total++; if (r.status === 429) protectedLane.s429++; });
+}
+const protectedCalls = [];
+for (let i = 0; i < 20; i++) protectedCalls.push(track(fire(`${BASE}/api/chat-sessions`, { headers: AUTH })));
+for (let i = 0; i < 5; i++) {
+    protectedCalls.push(track(fire(`${BASE}/api/chat-sessions/${SWITCH_SEQ}/switch`, { method: 'POST', headers: AUTH })));
+}
+for (let i = 0; i < 10; i++) protectedCalls.push(track(fire(`${BASE}/api/goal`, { headers: AUTH })));
+await Promise.all(protectedCalls);
+
+console.log(JSON.stringify({ tokenOk: true, phase1ElapsedMs, sacrificial, protected: protectedLane }, null, 2));

package/scripts/check-redaction-sinks.mjs

@@ -83,6 +83,7 @@ const ALLOWLIST = [
     { contains: '이 토픽은 인스턴스에 연결되지', why: 'fixed string' },
     { contains: 'ctx.answerCallbackQuery(ack', why: 'ack is masked where it is built' },
     { contains: 'ctx.reply(syncText)', why: 'syncText is masked where it is built' },
+    { contains: "persist failed:", why: "a Node.js Error.message from fs write, not a credential" },
     { contains: 'await ctx.reply(syncText)', why: 'syncText is masked where it is built' },
     { contains: 'Chat ID: <code>', why: 'a chat id the user just asked for' },
 ];

package/scripts/check-strict-baseline.mjs

@@ -2,7 +2,7 @@
 // @file scripts/check-strict-baseline.mjs
 // Strict-migration regression gate (AST-aware).
 //
-// Per R2.2 (devlog/_plan/strict-migration/07-pro-review-r2.md), this scanner
+// Per R2.2 (devlog/_fin/strict-migration/07-pro-review-r2.md), this scanner
 // uses the TypeScript Compiler API to walk source files and count AST nodes
 // of kind `AnyKeyword` plus any-typed `TypeReference` (Array<any>, Promise<any>,
 // Record<string, any>, etc.). Comments and string literals are automatically

package/scripts/ensure-native-modules.cjs

@@ -7,7 +7,7 @@
  * rebuild it in-place before build/test steps continue.
  */
 const { execFileSync } = require('child_process');
-const { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } = require('fs');
+const { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } = require('fs');
 const { delimiter, dirname, join } = require('path');
 const { createRequire } = require('module');
 const { createHash } = require('crypto');
@@ -58,7 +58,13 @@ function rebuildBetterSqlite3() {
     const betterSqliteDir = join(root, 'node_modules', 'better-sqlite3');
     if (existsSync(join(betterSqliteDir, 'package.json'))) {
         rmSync(join(betterSqliteDir, 'build'), { recursive: true, force: true });
-        runNpm(['run', 'install', '--foreground-scripts'], {
+        // v12 has scripts.install ("prebuild-install || node-gyp rebuild").
+        // v13+ removed it (prebuilds ship in the package), and `npm rebuild`
+        // returns a no-op success there, so the real source-build script is
+        // build-release. Pick by reading the installed package's manifest.
+        const manifest = JSON.parse(readFileSync(join(betterSqliteDir, 'package.json'), 'utf8'));
+        const script = manifest.scripts && manifest.scripts.install ? 'install' : 'build-release';
+        runNpm(['run', script, '--foreground-scripts'], {
             stdio: 'inherit',
             cwd: betterSqliteDir,
             env: nativeBuildEnv(),
@@ -239,10 +245,51 @@ function releaseRepairLock() {
     try { rmSync(LOCK_DIR, { recursive: true, force: true }); } catch { /* best effort */ }
 }
 
+/**
+ * Can this process write into the install tree at all? A global npm prefix is
+ * often root-owned; telling that user to "rebuild" is advice that cannot work.
+ */
+function canWriteInstallTree() {
+    try {
+        accessSync(join(root, 'node_modules'), constants.W_OK);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Package-manager-aware recovery commands. npm >= 12 blocks unreviewed
+ * dependency install scripts, which is the likeliest reason a fresh global
+ * install is missing its native addon. npm's own printed remediation omits
+ * the package argument (npm/cli#9835), so we print the working form.
+ */
+function recoveryHints() {
+    const lines = [];
+    if (/[\\/]\.bun[\\/]/.test(root)) {
+        lines.push('[jaw:native]    reinstall with lifecycle scripts trusted (bun):');
+        lines.push('[jaw:native]      bun add -g --trust cli-jaw');
+    } else if (/[\\/]pnpm[\\/]|[\\/]\.pnpm[\\/]/.test(root)) {
+        lines.push('[jaw:native]    reinstall with build scripts allowed (pnpm 11+):');
+        lines.push('[jaw:native]      pnpm add -g --allow-build=cli-jaw cli-jaw');
+        lines.push('[jaw:native]      (pnpm <= 10: pnpm approve-builds -g)');
+    } else {
+        lines.push('[jaw:native]    reinstall with install scripts allowed (npm >= 11.16):');
+        lines.push('[jaw:native]      npm install -g cli-jaw --allow-scripts=cli-jaw');
+        lines.push('[jaw:native]      npm config set allow-scripts=cli-jaw --location=user');
+    }
+    return lines;
+}
+
 function reportMissing() {
     console.error('[jaw:native] ❌ dependencies are not installed (cannot resolve better-sqlite3).');
     console.error(`[jaw:native]    install root: ${root}`);
-    console.error('[jaw:native]    run: npm install');
+    if (!canWriteInstallTree()) {
+        console.error('[jaw:native]    install tree is not writable — a rebuild cannot help here.');
+        for (const line of recoveryHints()) console.error(line);
+    } else {
+        console.error('[jaw:native]    run: npm install');
+    }
 }
 
 module.exports = {

package/scripts/install-risk-gate.mjs

@@ -67,6 +67,7 @@ function runPackageContentsCheck() {
   const required = [
     'scripts/install.sh',
     'scripts/install-wsl.sh',
+    'scripts/install.ps1',
     'scripts/verify-fresh-install.sh',
     'scripts/collect-fresh-install-evidence.sh',
     'scripts/audit-fresh-install-evidence.mjs',
@@ -94,6 +95,13 @@ function runPackageContentsCheck() {
     return false;
   }
 
+  // The install-state receipt is written at install time; if it ever ships in
+  // the tarball it always exists, which makes blocked-install detection blind.
+  if ([...files].some((file) => file.endsWith('.jaw-install-state.json'))) {
+    console.error(`[install-risk] FAIL ${label}: .jaw-install-state.json must never ship in the package`);
+    return false;
+  }
+
   console.log(`[install-risk] PASS ${label}`);
   return true;
 }

package/scripts/install-wsl.sh

@@ -37,6 +37,29 @@ HAS_SUDO=false
 NPM_PREFIX="$HOME/.local"
 NPM_PATH_LINE='export PATH="$HOME/.local/bin:$PATH"'
 
+# npm >= 11.16 understands --allow-scripts; npm 12 blocks unreviewed dependency
+# lifecycle scripts by default, so without this flag a global install can
+# succeed while cli-jaw's postinstall silently never runs. Older npm rejects
+# unknown config, so the flag is attached conditionally. (Duplicated from
+# install.sh — both files are standalone curl-run scripts.)
+JAW_ALLOW_SCRIPTS="cli-jaw"
+
+jaw_npm_supports_allow_scripts() {
+  local npm_version major minor
+  npm_version="$(npm --version 2>/dev/null || true)"
+  major="$(printf '%s' "$npm_version" | cut -d. -f1)"
+  minor="$(printf '%s' "$npm_version" | cut -d. -f2)"
+  case "$major" in (''|*[!0-9]*) return 1 ;; esac
+  case "$minor" in (''|*[!0-9]*) minor=0 ;; esac
+  [ "$major" -gt 11 ] || { [ "$major" -eq 11 ] && [ "$minor" -ge 16 ]; }
+}
+
+jaw_allow_scripts_flag() {
+  if jaw_npm_supports_allow_scripts; then
+    printf '%s' "--allow-scripts=${JAW_ALLOW_SCRIPTS}"
+  fi
+}
+
 # Guard: reject Windows HOME (e.g. /mnt/c/Users/...)
 case "$HOME" in
   /mnt/*) fail "HOME points to Windows path: $HOME — launch a proper WSL shell (wsl.exe -d Ubuntu)" ;;
@@ -315,15 +338,17 @@ verify_jaw_command() {
 #  Step 3: Install cli-jaw
 # ═══════════════════════════════════════
 install_jaw() {
+  local allow_flag
+  allow_flag="$(jaw_allow_scripts_flag)"
   if command -v jaw &>/dev/null; then
     ok "cli-jaw already installed ($(jaw --version 2>/dev/null || echo 'unknown version'))"
     info "Updating to latest..."
     CLI_JAW_INSTALL_CLI_TOOLS=1 \
-      npm install -g cli-jaw@latest
+      npm install -g cli-jaw@latest ${allow_flag:+$allow_flag}
   else
     info "Installing cli-jaw globally..."
     CLI_JAW_INSTALL_CLI_TOOLS=1 \
-      npm install -g cli-jaw
+      npm install -g cli-jaw ${allow_flag:+$allow_flag}
   fi
 
   verify_jaw_command