cli-jaw 2.2.9 → 2.2.11

package/scripts/pi-rpc-probe.mts

@@ -0,0 +1,361 @@
+#!/usr/bin/env -S npx tsx
+
+import { spawn, spawnSync, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import {
+    DEFAULT_PI_PROFILE,
+    DEFAULT_PI_SETTINGS,
+    ensurePiRuntimeConfig,
+    parsePiRpcRecord,
+    resolvePiCommand,
+    type PiCommand,
+} from '../src/agent/pi-runtime.js';
+import { JAW_HOME } from '../src/core/config.js';
+import {
+    classifySecondPromptOutcome,
+    type PiRpcVerdict,
+    type PiRpcVerdictRecord,
+} from '../src/agent/pi-rpc-verdict.js';
+
+const GET_STATE_ID = 1;
+const FIRST_PROMPT_ID = 2;
+const SECOND_PROMPT_ID = 3;
+const THIRD_PROMPT_ID = 4;
+const ABORT_ID = 5;
+const FIRST_TIMEOUT_MS = 60_000;
+const SECOND_TIMEOUT_MS = 30_000;
+const ABORT_START_TIMEOUT_MS = 30_000;
+const ABORT_TERMINAL_TIMEOUT_MS = 15_000;
+
+type RawRecord = Record<string, unknown>;
+type ObservedRecord = { raw: RawRecord; normalized: PiRpcVerdictRecord };
+type WaitResult = { matched: boolean; closed: boolean; timedOut: boolean };
+type AttemptResult = {
+    verdict: PiRpcVerdict;
+    abortEffective: boolean;
+    firstPromptSucceeded: boolean;
+    selfExited: boolean;
+    secondTimedOut: boolean;
+    recordCount: number;
+};
+
+function normalizeRecord(raw: RawRecord): PiRpcVerdictRecord {
+    const parsed = parsePiRpcRecord(raw);
+    const normalized: PiRpcVerdictRecord = {};
+    if (typeof raw['id'] === 'number') normalized.id = raw['id'];
+    if (typeof raw['type'] === 'string') normalized.type = raw['type'];
+    if (raw['type'] === 'response') {
+        if (typeof raw['command'] === 'string') normalized.command = raw['command'];
+        if (typeof raw['success'] === 'boolean') normalized.success = raw['success'];
+    }
+    const error = raw['error'];
+    if (error && typeof error === 'object') {
+        const message = (error as Record<string, unknown>)['message'];
+        normalized.error = typeof message === 'string' ? { message } : {};
+    }
+    if (parsed.done !== undefined) normalized.done = parsed.done;
+    if (parsed.text !== undefined) normalized.text = parsed.text;
+    if (raw['type'] === 'agent_end') {
+        // user echo 추출 — 모델이 text 파트를 생략하는 비결정성에 강건한 턴 상관 증거
+        const messages = raw['messages'];
+        if (Array.isArray(messages)) {
+            normalized.userEcho = messages
+                .filter((entry) => !!entry && typeof entry === 'object' && (entry as Record<string, unknown>)['role'] === 'user')
+                .map((entry) => extractProbeText((entry as Record<string, unknown>)['content']))
+                .join('');
+        }
+    }
+    return normalized;
+}
+
+function extractProbeText(value: unknown): string {
+    if (typeof value === 'string') return value;
+    if (Array.isArray(value)) return value.map(extractProbeText).join('');
+    if (!value || typeof value !== 'object') return '';
+    const obj = value as Record<string, unknown>;
+    if (obj['type'] === 'thinking') return '';
+    return extractProbeText(obj['text']) || extractProbeText(obj['content']) || '';
+}
+
+function isSuccessfulStateResponse(record: ObservedRecord): boolean {
+    return record.normalized.id === GET_STATE_ID
+        && record.raw['type'] === 'response'
+        && record.raw['command'] === 'get_state'
+        && record.raw['success'] === true;
+}
+
+function isGenerationEvent(record: ObservedRecord): boolean {
+    const type = record.raw['type'];
+    if (type === 'agent_end') return false;
+    if (record.normalized.text) return true;
+    return typeof type === 'string' && type !== 'response';
+}
+
+function isAbortAccepted(record: ObservedRecord): boolean {
+    return record.normalized.id === ABORT_ID
+        && record.raw['type'] === 'response'
+        && record.raw['command'] === 'abort'
+        && record.raw['success'] === true;
+}
+
+function isTerminalRecord(record: ObservedRecord): boolean {
+    if (record.normalized.done) return true;
+    const data = record.raw['data'];
+    if (!data || typeof data !== 'object') return false;
+    const state = data as Record<string, unknown>;
+    if (state['running'] === false || state['isRunning'] === false) return true;
+    return typeof state['state'] === 'string' && !['running', 'active', 'generating'].includes(state['state'].toLowerCase());
+}
+
+class RpcProbeProcess {
+    readonly records: ObservedRecord[] = [];
+    readonly child: ChildProcessWithoutNullStreams;
+    private readonly listeners = new Set<() => void>();
+    private buffer = '';
+    private readonly decoder = new StringDecoder('utf8');
+    private closed = false;
+    private closeCode: number | null = null;
+
+    constructor(command: PiCommand, runtimeDir: string) {
+        const args = [
+            ...command.baseArgs,
+            '--mode', 'rpc',
+            '--no-context-files',
+            '--provider', DEFAULT_PI_PROFILE.id,
+            '--model', DEFAULT_PI_PROFILE.model,
+            '--api-key', DEFAULT_PI_PROFILE.apiKey || 'dummy',
+        ];
+        console.log(`[probe:spawn] ${JSON.stringify([command.command, ...args])}`);
+        this.child = spawn(command.command, args, {
+            cwd: process.cwd(),
+            env: { ...process.env, PI_CODING_AGENT_DIR: runtimeDir },
+            stdio: ['pipe', 'pipe', 'pipe'],
+            ...(process.platform === 'win32' && !command.command.toLowerCase().endsWith('.exe') ? { shell: true } : {}),
+        });
+        this.child.stdout.on('data', (chunk: Buffer) => this.consumeStdout(chunk));
+        this.child.stderr.on('data', (chunk: Buffer) => process.stderr.write(`[probe:stderr] ${chunk.toString()}`));
+        this.child.on('error', (error) => {
+            console.error(`[probe:error] ${error.message}`);
+            this.notify();
+        });
+        this.child.on('close', (code) => {
+            this.buffer += this.decoder.end();
+            if (this.buffer.trim()) this.consumeLine(this.buffer.trim());
+            this.buffer = '';
+            this.closed = true;
+            this.closeCode = code;
+            console.log(`[probe:close] code=${String(code)}`);
+            this.notify();
+        });
+    }
+
+    get didClose(): boolean { return this.closed; }
+    get exitedNormally(): boolean { return this.closed && this.closeCode === 0; }
+
+    send(id: number, type: string, fields: RawRecord = {}): Promise<void> {
+        const line = JSON.stringify({ id, type, ...fields });
+        console.log(`[probe:send] ${line}`);
+        return new Promise((resolve, reject) => {
+            if (!this.child.stdin.writable) {
+                reject(new Error('pi rpc stdin is not writable'));
+                return;
+            }
+            this.child.stdin.write(`${line}\n`, (error) => error ? reject(error) : resolve());
+        });
+    }
+
+    async waitFrom(start: number, predicate: (records: ObservedRecord[]) => boolean, timeoutMs: number): Promise<WaitResult> {
+        if (predicate(this.records.slice(start))) return { matched: true, closed: this.closed, timedOut: false };
+        if (this.closed) return { matched: false, closed: true, timedOut: false };
+        return new Promise((resolve) => {
+            const finish = (result: WaitResult) => {
+                clearTimeout(timer);
+                this.listeners.delete(check);
+                resolve(result);
+            };
+            const check = () => {
+                if (predicate(this.records.slice(start))) finish({ matched: true, closed: this.closed, timedOut: false });
+                else if (this.closed) finish({ matched: false, closed: true, timedOut: false });
+            };
+            const timer = setTimeout(() => finish({ matched: false, closed: this.closed, timedOut: true }), timeoutMs);
+            this.listeners.add(check);
+        });
+    }
+
+    async stop(): Promise<void> {
+        try { this.child.stdin.end(); } catch { /* already closed */ }
+        if (this.closed) return;
+        if (!this.child.killed) this.child.kill('SIGTERM');
+        const stopped = await this.waitFrom(this.records.length, () => false, 2_000);
+        if (!stopped.closed) {
+            this.child.kill('SIGKILL');
+            await this.waitFrom(this.records.length, () => false, 1_000);
+        }
+    }
+
+    private consumeStdout(chunk: Buffer): void {
+        this.buffer += this.decoder.write(chunk);
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() ?? '';
+        for (const line of lines) if (line.trim()) this.consumeLine(line.trim());
+    }
+
+    private consumeLine(line: string): void {
+        process.stdout.write(`${line}\n`);
+        try {
+            const raw = JSON.parse(line) as unknown;
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return;
+            this.records.push({ raw: raw as RawRecord, normalized: normalizeRecord(raw as RawRecord) });
+            this.notify();
+        } catch {
+            console.error(`[probe:parse-error] ${line.slice(0, 200)}`);
+        }
+    }
+
+    private notify(): void {
+        for (const listener of [...this.listeners]) listener();
+    }
+}
+
+async function probeAbort(rpc: RpcProbeProcess): Promise<boolean> {
+    if (rpc.didClose) return false;
+    const thirdStart = rpc.records.length;
+    try {
+        await rpc.send(THIRD_PROMPT_ID, 'prompt', { message: 'Write a very long story, at least 2000 words.' });
+    } catch (error) {
+        console.error(`[probe:abort] third prompt write failed: ${(error as Error).message}`);
+        return false;
+    }
+    const started = await rpc.waitFrom(thirdStart, (records) => records.some(isGenerationEvent), ABORT_START_TIMEOUT_MS);
+    if (!started.matched || rpc.didClose) return false;
+
+    const abortStart = rpc.records.length;
+    try {
+        await rpc.send(ABORT_ID, 'abort');
+    } catch (error) {
+        console.error(`[probe:abort] abort write failed: ${(error as Error).message}`);
+        return false;
+    }
+    const terminal = await rpc.waitFrom(abortStart, (records) => {
+        const accepted = records.some(isAbortAccepted);
+        return accepted && records.some(isTerminalRecord);
+    }, ABORT_TERMINAL_TIMEOUT_MS);
+    return terminal.matched;
+}
+
+async function runAttempt(command: PiCommand, attempt: number): Promise<AttemptResult> {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), `cli-jaw-pi-rpc-probe-${attempt}-`));
+    const runtimeDir = ensurePiRuntimeConfig(DEFAULT_PI_SETTINGS, DEFAULT_PI_PROFILE.id, '', tempRoot);
+    const rpc = new RpcProbeProcess(command, runtimeDir);
+    let firstPromptSucceeded = false;
+    let selfExited = false;
+    let secondTimedOut = false;
+    let abortEffective = false;
+    let secondRecords: ObservedRecord[] = [];
+    try {
+        const stateStart = rpc.records.length;
+        await rpc.send(GET_STATE_ID, 'get_state');
+        const state = await rpc.waitFrom(stateStart, (records) => records.some(isSuccessfulStateResponse), 15_000);
+        if (!state.matched) {
+            return { verdict: 'inconclusive', abortEffective, firstPromptSucceeded, selfExited, secondTimedOut: state.timedOut, recordCount: rpc.records.length };
+        }
+
+        const firstStart = rpc.records.length;
+        await rpc.send(FIRST_PROMPT_ID, 'prompt', { message: 'Reply with the single token: FIRST' });
+        const first = await rpc.waitFrom(firstStart, (records) => records.some((record) => record.normalized.done === true), FIRST_TIMEOUT_MS);
+        firstPromptSucceeded = first.matched;
+
+        const secondStart = rpc.records.length;
+        if (firstPromptSucceeded) {
+            try {
+                await rpc.send(SECOND_PROMPT_ID, 'prompt', { message: 'Reply with the single token: SECOND' });
+            } catch (error) {
+                console.error(`[probe:second] write failed: ${(error as Error).message}`);
+                selfExited = rpc.exitedNormally;
+            }
+            if (!selfExited) {
+                const second = await rpc.waitFrom(secondStart, (records) => records.some((record) =>
+                    record.normalized.done === true
+                    || (record.normalized.id === SECOND_PROMPT_ID && record.normalized.error !== undefined)
+                ), SECOND_TIMEOUT_MS);
+                secondTimedOut = second.timedOut;
+                secondRecords = rpc.records.slice(secondStart);
+                if (second.closed && rpc.exitedNormally && !second.matched) selfExited = true;
+                if (!secondTimedOut && !rpc.didClose) abortEffective = await probeAbort(rpc);
+            }
+        }
+
+        const verdict = classifySecondPromptOutcome({
+            records: secondRecords.map((record) => record.normalized),
+            secondPromptId: SECOND_PROMPT_ID,
+            timedOut: secondTimedOut,
+            selfExited,
+            firstPromptSucceeded,
+        });
+        if (process.env['PI_RPC_PROBE_DEBUG']) {
+            console.error(`[probe:debug] classifier input: ${JSON.stringify({
+                firstPromptSucceeded, selfExited, secondTimedOut,
+                doneRecords: secondRecords.filter((r) => r.normalized.done).map((r) => r.normalized),
+                secondRecordCount: secondRecords.length,
+            })}`);
+        }
+        return { verdict, abortEffective, firstPromptSucceeded, selfExited, secondTimedOut, recordCount: rpc.records.length };
+    } catch (error) {
+        console.error(`[probe:attempt-${attempt}] ${(error as Error).stack || String(error)}`);
+        return { verdict: 'inconclusive', abortEffective, firstPromptSucceeded, selfExited, secondTimedOut, recordCount: rpc.records.length };
+    } finally {
+        await rpc.stop();
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+}
+
+function resolveCommandIdentity(command: PiCommand): string {
+    const result = spawnSync(command.command, [...command.baseArgs, '--version'], {
+        encoding: 'utf8',
+        env: process.env,
+        timeout: 15_000,
+    });
+    const version = `${result.stdout || ''}\n${result.stderr || ''}`.trim() || `exit:${String(result.status)}`;
+    return JSON.stringify({ source: command.source, command: command.command, baseArgs: command.baseArgs, version });
+}
+
+function writeCapability(commandId: string, result: AttemptResult, attempts: AttemptResult[]): void {
+    const targetDir = path.join(JAW_HOME, 'pi');
+    const target = path.join(targetDir, 'rpc-capabilities.json');
+    const temp = `${target}.${process.pid}.tmp`;
+    const evidence = attempts.map((attempt, index) =>
+        `attempt=${index + 1},verdict=${attempt.verdict},first=${attempt.firstPromptSucceeded},selfExited=${attempt.selfExited},secondTimedOut=${attempt.secondTimedOut},abort=${attempt.abortEffective},records=${attempt.recordCount}`
+    ).join('; ');
+    fs.mkdirSync(targetDir, { recursive: true });
+    fs.writeFileSync(temp, `${JSON.stringify({
+        schemaVersion: 1,
+        commandId,
+        probedAt: new Date().toISOString(),
+        profileId: DEFAULT_PI_PROFILE.id,
+        abortEffective: result.abortEffective,
+        evidence,
+    }, null, 2)}\n`, 'utf8');
+    fs.renameSync(temp, target);
+    console.log(`[probe:capabilities] ${target}`);
+}
+
+async function main(): Promise<void> {
+    const command = resolvePiCommand();
+    const commandId = resolveCommandIdentity(command);
+    const attempts: AttemptResult[] = [];
+    attempts.push(await runAttempt(command, 1));
+    if (attempts[0]?.verdict === 'inconclusive') attempts.push(await runAttempt(command, 2));
+    const result = attempts.at(-1);
+    if (!result) throw new Error('pi rpc probe produced no result');
+    writeCapability(commandId, result, attempts);
+    console.log(`[probe:verdict] ${result.verdict} abortEffective=${result.abortEffective}`);
+    process.exitCode = result.verdict === 'supported' ? 0 : result.verdict === 'proven-unsupported' ? 1 : 2;
+}
+
+void main().catch((error: unknown) => {
+    console.error(`[probe:fatal] ${(error as Error).stack || String(error)}`);
+    process.exitCode = 2;
+});

package/scripts/pick-gyp-python.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Print a python3 that node-gyp can actually run under.
+#
+# node-gyp's bundled gyp still does `from distutils.version import StrictVersion`,
+# and distutils was removed in Python 3.12. On a machine whose default python3 is
+# Homebrew 3.12+ the native rebuild dies with:
+#
+#   ModuleNotFoundError: No module named 'distutils'
+#   ⨯ node-gyp failed to rebuild '.../node_modules/node-pty'
+#
+# Observed on macOS 27 with Homebrew Python 3.14.6 while building the desktop app
+# on a second machine. macOS still ships /usr/bin/python3 (3.9.6), which has
+# distutils, so a working interpreter is usually present -- it just is not the
+# one on PATH.
+#
+# CI already knew: .github/workflows/desktop-release.yml pins actions/setup-python
+# to 3.11 with exactly this reasoning in a comment. The local build path never got
+# the same treatment, so `npm run electron:dist:mac` on a developer machine was the
+# one route into node-gyp with no defense.
+#
+# Candidates are TESTED, not assumed: a hardcoded path is the same bet that broke
+# here, one Python release later. An explicit $PYTHON still wins, because the
+# caller may know something this script does not.
+set -euo pipefail
+
+has_distutils() {
+  [ -x "$1" ] || return 1
+  "$1" -c 'import distutils' >/dev/null 2>&1
+}
+
+if [ -n "${PYTHON:-}" ]; then
+  printf '%s\n' "$PYTHON"
+  exit 0
+fi
+
+for candidate in \
+  /usr/bin/python3 \
+  "$(command -v python3.11 2>/dev/null || true)" \
+  "$(command -v python3.10 2>/dev/null || true)" \
+  "$(command -v python3.9 2>/dev/null || true)" \
+  "$(command -v python3 2>/dev/null || true)"
+do
+  [ -n "$candidate" ] || continue
+  if has_distutils "$candidate"; then
+    printf '%s\n' "$candidate"
+    exit 0
+  fi
+done
+
+# Nothing usable. Fall back to whatever python3 exists so the caller fails with
+# node-gyp's own message rather than an empty variable, and say why.
+fallback="$(command -v python3 2>/dev/null || true)"
+if [ -n "$fallback" ]; then
+  echo "[gyp-python] no python3 with distutils found; falling back to $fallback" >&2
+  echo "[gyp-python] node-gyp will likely fail. Install python@3.11 or set PYTHON=<path>." >&2
+  printf '%s\n' "$fallback"
+  exit 0
+fi
+
+echo "[gyp-python] no python3 on PATH at all" >&2
+exit 1

package/scripts/release-gates.mjs

@@ -67,6 +67,10 @@ const GATES = {
                 'tests/unit/browser-web-ai-source-audit.test.ts',
                 'tests/unit/browser-web-ai-cli-contract.test.ts',
                 'tests/unit/release-gates.test.ts',
+                // Guards the release/build scripts themselves, so it belongs in
+                // the suite gate:all actually runs rather than npm test only.
+                'tests/unit/electron-version-sync.test.ts',
+                'tests/unit/gyp-python-pick.test.ts',
             ].filter((p) => fs.existsSync(path.join(repoRoot, p)));
             if (targets.length === 0) {
                 return { ok: false, detail: 'no Phase 22 mirror tests found' };
@@ -394,6 +398,99 @@ const GATES = {
             return { ok: true, detail: 'live any/debt/allow counts within frozen baseline' };
         },
     },
+    'redaction-sinks': {
+        description: 'channel replies, sends and loggers route through a credential masker',
+        check() {
+            const r = run('node', ['scripts/check-redaction-sinks.mjs'], { timeout: 60_000 });
+            if (r.status !== 0) {
+                return { ok: false, detail: `unmasked channel sink:\n${(r.stdout || r.stderr || '').slice(-1500)}` };
+            }
+            return { ok: true, detail: 'no unmasked sink in telegram/discord/slack/telegram-hub' };
+        },
+    },
+    'electron-version': {
+        description: 'electron/package.json version matches the root package.json',
+        check() {
+            const r = run('node', ['scripts/sync-electron-version.cjs', '--check'], { timeout: 60_000 });
+            if (r.status !== 0) {
+                return { ok: false, detail: (r.stdout || r.stderr || '').trim().slice(-500) };
+            }
+            return { ok: true, detail: 'desktop artifacts will carry the release version' };
+        },
+    },
+    'sidecar-prune-safety': {
+        description: 'the sidecar prune list never deletes a package the server imports',
+        check() {
+            const r = run('node', ['scripts/check-sidecar-prune-safety.mjs'], { timeout: 60_000 });
+            if (r.status !== 0) {
+                return { ok: false, detail: (r.stdout || r.stderr || '').trim().slice(-800) };
+            }
+            return { ok: true, detail: 'packaged sidecar keeps every runtime dependency' };
+        },
+    },
+    'gate-docs': {
+        description: 'structure/INDEX.md documents exactly the gates that exist, and each is npm-addressable',
+        check() {
+            // structure/INDEX.md hardcodes the gate count and enumerates every
+            // name. Adding the 16th gate made that row wrong, and nothing
+            // noticed: check-docs.mts counts only routes and endpoints, and
+            // check-doc-drift.sh never looks at gates. Fixing the row by hand
+            // cleared one instance; this closes the class.
+            //
+            // This gate lives inside release-gates.mjs rather than in its own
+            // script because the module calls main() unconditionally at the
+            // bottom, so importing GATES from outside would run every gate.
+            const names = Object.keys(GATES);
+            const doc = readFile('structure/INDEX.md');
+            const row = doc.split('\n').find((line) =>
+                line.includes('named gates') && line.includes('runs all'));
+            if (!row) {
+                return { ok: false, detail: 'the release-gates row is gone from structure/INDEX.md' };
+            }
+
+            const problems = [];
+
+            const claimed = row.match(/runs all (\d+) named gates/);
+            if (!claimed) {
+                problems.push('the row no longer states a gate count');
+            } else if (Number(claimed[1]) !== names.length) {
+                problems.push(`count says ${claimed[1]}, GATES has ${names.length}`);
+            }
+
+            // Read ONLY the parenthesised list, not the whole row. The row also
+            // carries `scripts/release-gates.mjs`, `package.json`, `gate:all`
+            // and `gate:<name>` in prose; scanning the row and filtering those
+            // out by shape both accuses innocent prose and lets a phantom like
+            // `gate:retired-name` through, because a filter keyed on the token
+            // shape cannot tell a stale gate from an ordinary mention.
+            const list = row.match(/named gates \(([^)]*)\)/);
+            if (!list) {
+                problems.push('the parenthesised gate list is gone from the row');
+            } else {
+                const documented = [...list[1].matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+                const missing = names.filter((name) => !documented.includes(name));
+                const stale = documented.filter((name) => !names.includes(name));
+                if (missing.length > 0) problems.push(`undocumented: ${missing.join(', ')}`);
+                if (stale.length > 0) problems.push(`documented but gone: ${stale.join(', ')}`);
+            }
+
+            // The same row promises `gate:<name>` addressability. A gate added
+            // without its npm script makes that sentence false while gate:all
+            // stays green -- the hand-maintained invariant this gate exists to
+            // stop being hand-maintained.
+            const pkg = JSON.parse(readFile('package.json'));
+            const unaddressable = names.filter((name) =>
+                pkg.scripts?.[`gate:${name}`] !== `node scripts/release-gates.mjs ${name}`);
+            if (unaddressable.length > 0) {
+                problems.push(`no npm script: ${unaddressable.map((n) => `gate:${n}`).join(', ')}`);
+            }
+
+            if (problems.length > 0) {
+                return { ok: false, detail: `${problems.join('\n')}\nFix structure/INDEX.md / package.json` };
+            }
+            return { ok: true, detail: `${names.length} gates documented and addressable` };
+        },
+    },
 };
 
 function printResult(name, result) {

package/scripts/release-preview.sh

@@ -148,6 +148,13 @@ npm version "$PREVIEW_VERSION" --no-git-tag-version
 VERSION=$(node -p "require('./package.json').version")
 echo "📌 package.json version: $VERSION"
 
+# Same reason as release.sh: the committed Electron version names the desktop
+# artifacts. This also has to run BEFORE gate:all below -- the electron-version
+# gate compares the two manifests, and the bump above has just moved the root
+# one, so skipping this would fail the preview release outright.
+echo "🖥️  Syncing Electron version to $VERSION..."
+node scripts/sync-electron-version.cjs
+
 echo "🔎 Type checking..."
 pnpm exec tsc --noEmit
 
@@ -169,7 +176,7 @@ npm pack --dry-run >/dev/null
 
 # ─── Commit + Push ────────────────────────────────────
 echo "📝 Creating local commit..."
-git add package.json package-lock.json
+git add package.json package-lock.json electron/package.json electron/package-lock.json
 git commit -m "[agent] chore: preview v$VERSION" --allow-empty
 
 echo "⬆️  Pushing preview branch..."

package/scripts/release.sh

@@ -129,6 +129,12 @@ fi
 VERSION=$(node -p "require('./package.json').version")
 echo "📌 New version: $VERSION"
 
+# Desktop artifacts are named from the version COMMITTED in
+# electron/package.json, and desktop-release.yml builds from a tag checkout --
+# so this has to happen here, before the release commit, not at build time.
+echo "🖥️  Syncing Electron version to $VERSION..."
+node scripts/sync-electron-version.cjs
+
 # ─── Collect changelog ─────────────────────────────────
 if [ -n "$PREV_TAG" ]; then
   CHANGELOG=$(git log "$PREV_TAG"..HEAD --pretty=format:"- %s" --no-merges | head -50)
@@ -155,10 +161,15 @@ fi
 
 # ─── Commit + Tag + Push ──────────────────────────────
 echo "🏷️  Creating git tag v$VERSION..."
-git add package.json package-lock.json
+git add package.json package-lock.json electron/package.json electron/package-lock.json
 git commit -m "[agent] chore: release v$VERSION" --allow-empty
 git tag "v$VERSION"
-git push origin main
+# HEAD:main, not main. `git push origin main` pushes the LOCAL main branch,
+# which is not necessarily the tree just built, committed and tagged: releases
+# are cut from whatever branch is checked out, and a local main left behind at
+# an older release would be published instead. Caught before a real release
+# with local main at v2.2.7 while the release commit sat on dev.
+git push origin HEAD:main
 git push origin "v$VERSION"
 
 # ─── GitHub Release with changelog ─────────────────────

package/scripts/sync-electron-version.cjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Keep electron/package.json's version equal to the root package.json's.
+ *
+ * Without this the two drifted freely: the root reached 2.2.7 while the
+ * Electron shell sat at 0.1.0 since its first commit, so every desktop release
+ * produced identically-named artifacts (cli-jaw-0.1.0-arm64.dmg) and the file
+ * you downloaded told you nothing about which release it came from.
+ *
+ * Why the version has to be COMMITTED rather than injected at build time:
+ * electron-builder's default artifact name is `${productName}-${version}-...`
+ * resolved from the packaged app's own package.json, and
+ * .github/workflows/desktop-release.yml builds from a release-tag checkout. A
+ * build-time flag would work on a developer machine and silently do nothing in
+ * the workflow that actually publishes the assets.
+ *
+ * One implementation serves both the writer and the gate on purpose. A gate
+ * that computed the expected value separately could pass while the release
+ * wrote something else.
+ */
+const { readFileSync } = require('node:fs');
+const { join } = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const repoRoot = join(__dirname, '..');
+const electronDir = join(repoRoot, 'electron');
+
+/** Version field of the package.json in `dir`. */
+function readVersion(dir) {
+    const file = join(dir, 'package.json');
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    } catch (error) {
+        throw new Error(`cannot read ${file}: ${error.message}`);
+    }
+    try {
+        return JSON.parse(raw).version;
+    } catch (error) {
+        throw new Error(`${file} is not valid JSON: ${error.message}`);
+    }
+}
+
+function main() {
+    let rootVersion;
+    let electronVersion;
+    try {
+        rootVersion = readVersion(repoRoot);
+        electronVersion = readVersion(electronDir);
+    } catch (error) {
+        // Fails closed either way -- an unreadable manifest already exited
+        // non-zero via the uncaught throw. What this adds is a first line the
+        // reader can act on instead of a Node stack trace.
+        console.error(`ERROR: ${error.message}`);
+        return 1;
+    }
+    const check = process.argv.includes('--check');
+
+    if (electronVersion === rootVersion) {
+        console.log(`[electron-version] OK ${rootVersion}`);
+        return 0;
+    }
+
+    if (check) {
+        // Name both values. "versions differ" leaves the reader guessing which
+        // side is authoritative.
+        console.error(
+            `ERROR: electron/package.json version ${electronVersion} != root package.json ${rootVersion}`);
+        console.error('Run: npm run sync:electron-version');
+        return 1;
+    }
+
+    // Delegate to npm instead of editing JSON by hand: `npm version` updates
+    // package.json and the root entries of package-lock.json together. Writing
+    // both files directly means reimplementing the lockfile's shape, and
+    // getting it subtly wrong surfaces later as unexplained churn in someone
+    // else's dependency diff.
+    const result = spawnSync(
+        'npm',
+        ['version', rootVersion, '--no-git-tag-version', '--allow-same-version'],
+        { cwd: electronDir, encoding: 'utf8', timeout: 60_000 },
+    );
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || '').trim();
+        console.error(`ERROR: npm version failed in electron/: ${detail}`);
+        return 1;
+    }
+
+    console.log(`[electron-version] synced ${electronVersion} -> ${rootVersion}`);
+    return 0;
+}
+
+process.exit(main());