@harness-mix/cli 0.2.3 → 0.3.0

package/scripts/native-update-apply-test.cjs

@@ -1,215 +1,269 @@
-// Update v2 coverage: state file / lock / channel detection / semver, plus the
-// runUpdateFlow orchestration with mocked deps. Fully offline; no real npm/git.
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const {
-  acquireLock, compareVersions, detectChannel, markBootOk, readState, writeState,
-} = require('../src/main/native/update-state');
-const { fetchLatestVersion, runUpdateFlow } = require('../src/main/native/updater');
-
-const tmp = prefix => fs.mkdtempSync(path.join(os.tmpdir(), prefix));
-const quiet = () => {};
-const delay = () => Promise.resolve();
-const fetchVersion = version => async () => ({
-  ok: true, status: 200,
-  json: async () => ({ 'dist-tags': { latest: version } }),
-  headers: { get: () => null },
-});
-const npmFixture = (version = '0.1.0') => {
-  const root = path.join(tmp('hm-npm-'), 'node_modules', 'harness-mix');
-  fs.mkdirSync(root, { recursive: true });
-  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'harness-mix', version }));
-  return root;
-};
-const npmRun = (root, { install = { status: 0 } } = {}) => (cmd, args) => {
-  if (args[0] === 'root') return { status: 0, stdout: `${path.dirname(root)}\n` };
-  if (args[0] === 'config') return { status: 0, stdout: 'https://registry.test/\n' };
-  if (args[0] === 'install') return install;
-  return { status: 0, stdout: '' };
-};
-
-(async () => {
-  // --- semver / channel detection ---
-  assert.equal(compareVersions('0.2.0', '0.1.1'), 1);
-  assert.equal(compareVersions('0.1.1', '0.1.1'), 0);
-  assert.equal(compareVersions('0.1.10', '0.1.9'), 1);
-  assert.equal(compareVersions('0.10.0', '0.9.9'), 1);
-  assert.equal(compareVersions('0.2.0-rc.1', '0.2.0'), -1);
-  assert.equal(compareVersions('0.2.0', '0.2.0-rc.1'), 1);
-
-  const gitRoot = tmp('hm-git-');
-  fs.mkdirSync(path.join(gitRoot, '.git'));
-  assert.equal(detectChannel(gitRoot), 'git');
-  assert.equal(detectChannel(npmFixture()), 'npm');
-  assert.equal(detectChannel(tmp('hm-plain-')), 'portable');
-
-  // --- state file tolerates corruption; lock lifecycle incl. stale reap ---
-  const data = tmp('hm-data-');
-  fs.writeFileSync(path.join(data, 'update-state.json'), '{not json');
-  assert.equal(readState(data).phase, 'idle');
-  const release = acquireLock(data, 'test');
-  assert.throws(() => acquireLock(data, 'test'), /更新锁/);
-  release();
-  acquireLock(data, 'test')();
-  fs.writeFileSync(path.join(data, 'update.lock'), JSON.stringify({ pid: process.pid, ts: Date.now() - 31 * 60 * 1000, op: 'stale' }));
-  acquireLock(data, 'test')(); // stale locks are reaped even when the pid still lives
-  writeState(data, { ...readState(data), appliedVersion: '0.2.0', appliedAt: Date.now() - 1000, attempts: 3 });
-  markBootOk(data);
-  assert.equal(readState(data).attempts, 0);
-  assert.ok(readState(data).lastBootOkAt > 0);
-
-  // --- fetchLatestVersion: etag cache answers 304 from disk ---
-  {
-    const dir = tmp('hm-etag-');
-    const first = await fetchLatestVersion({
-      registry: 'https://registry.test/', dataDir: dir,
-      fetchImpl: async () => ({ ok: true, status: 200, json: async () => ({ 'dist-tags': { latest: '9.9.9' } }), headers: { get: name => (name === 'etag' ? '"e1"' : null) } }),
-    });
-    assert.equal(first, '9.9.9');
-    const second = await fetchLatestVersion({
-      registry: 'https://registry.test/', dataDir: dir,
-      fetchImpl: async () => ({ ok: false, status: 304, headers: { get: () => null } }),
-    });
-    assert.equal(second, '9.9.9');
-  }
-
-  // --- npm: update available -> applied, restart required ---
-  {
-    const root = npmFixture();
-    const dir = tmp('hm-flow-');
-    const calls = [];
-    const run = (cmd, args) => { calls.push(args.join(' ')); return npmRun(root)(cmd, args); };
-    let stopped = 0;
-    const outcome = await runUpdateFlow({
-      root, dataDir: dir, log: quiet, stopDesktop: async () => { stopped += 1; }, mode: 'apply',
-      deps: { run, fetchImpl: fetchVersion('0.2.0'), delay, env: {} },
-    });
-    assert.equal(outcome.updated, true);
-    assert.equal(outcome.to, '0.2.0');
-    assert.equal(outcome.restartRequired, true);
-    assert.equal(stopped, 1);
-    assert.ok(calls.some(call => call.startsWith('install -g harness-mix@0.2.0')));
-    const state = readState(dir);
-    assert.equal(state.appliedVersion, '0.2.0');
-    assert.equal(state.prevVersion, '0.1.0');
-    assert.equal(state.phase, 'idle');
-  }
-
-  // --- npm: install failure -> pending for the next launch, never blocks ---
-  {
-    const root = npmFixture();
-    const dir = tmp('hm-flow-');
-    const outcome = await runUpdateFlow({
-      root, dataDir: dir, log: quiet, stopDesktop: async () => {}, mode: 'apply',
-      deps: { run: npmRun(root, { install: { status: 1, stderr: 'EBUSY: file locked' } }), fetchImpl: fetchVersion('0.2.0'), delay, env: {} },
-    });
-    assert.equal(outcome.updated, false);
-    assert.equal(outcome.pending, '0.2.0');
-    assert.equal(outcome.restartRequired, undefined);
-    assert.equal(readState(dir).pendingVersion, '0.2.0');
-  }
-
-  // --- npm: registry offline -> failed, launch continues ---
-  {
-    const root = npmFixture();
-    const dir = tmp('hm-flow-');
-    const outcome = await runUpdateFlow({
-      root, dataDir: dir, log: quiet, stopDesktop: async () => {}, mode: 'apply',
-      deps: { run: npmRun(root), fetchImpl: async () => { throw new Error('getaddrinfo ENOTFOUND'); }, delay, env: {} },
-    });
-    assert.equal(outcome.failed, true);
-    assert.equal(outcome.restartRequired, undefined);
-  }
-
-  // --- update lock held elsewhere -> skip without touching the desktop ---
-  {
-    const root = npmFixture();
-    const dir = tmp('hm-flow-');
-    fs.writeFileSync(path.join(dir, 'update.lock'), JSON.stringify({ pid: process.pid, ts: Date.now(), op: 'other' }));
-    let stopped = 0;
-    const outcome = await runUpdateFlow({
-      root, dataDir: dir, log: quiet, stopDesktop: async () => { stopped += 1; }, mode: 'apply',
-      deps: { run: npmRun(root), fetchImpl: fetchVersion('0.2.0'), delay, env: {} },
-    });
-    assert.equal(outcome.failed, true);
-    assert.equal(outcome.reason, 'lock');
-    assert.equal(stopped, 0);
-  }
-
-  // --- crash loop: second failed boot rolls back to prevVersion ---
-  {
-    const root = npmFixture('0.2.0'); // the installed tree currently runs 0.2.0
-    const dir = tmp('hm-flow-');
-    writeState(dir, { ...readState(dir), channel: 'npm', appliedVersion: '0.2.0', prevVersion: '0.1.0', appliedAt: Date.now() - 1000, lastBootOkAt: 0, attempts: 1 });
-    const calls = [];
-    const run = (cmd, args) => { calls.push(args.join(' ')); return npmRun(root)(cmd, args); };
-    const outcome = await runUpdateFlow({
-      root, dataDir: dir, log: quiet, stopDesktop: async () => {}, mode: 'apply',
-      deps: { run, fetchImpl: async () => { throw new Error('offline'); }, delay, env: {} },
-    });
-    assert.equal(outcome.rolledBack, true);
-    assert.equal(outcome.restartRequired, true);
-    assert.ok(calls.some(call => call.startsWith('install -g harness-mix@0.1.0')));
-    const state = readState(dir);
-    assert.equal(state.appliedVersion, null);
-    assert.equal(state.prevVersion, null);
-    assert.equal(state.attempts, 0);
-  }
-
-  // --- git: fast-forward applies and asks for a restart ---
-  {
-    const root = tmp('hm-git-flow-');
-    fs.mkdirSync(path.join(root, '.git'), { recursive: true });
-    fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'harness-mix', version: '0.1.1' }));
-    const dir = tmp('hm-flow-');
-    const script = {
-      'rev-parse HEAD': 'aaa111\n',
-      'rev-parse --abbrev-ref': 'origin/main\n',
-      fetch: '',
-      'rev-parse origin/main': 'bbb222\n',
-      'merge-base': 'aaa111\n',
-      status: '',
-      'diff --name-only': 'docs/x.md\n',
-      'merge --ff-only': '',
-    };
-    const calls = [];
-    const exec = (cmd, args) => {
-      const key = args.join(' ');
-      calls.push(key);
-      for (const [prefix, stdout] of Object.entries(script)) if (key.startsWith(prefix)) return { status: 0, stdout, stderr: '' };
-      return { status: 0, stdout: '', stderr: '' };
-    };
-    const outcome = await runUpdateFlow({
-      root, dataDir: dir, log: quiet, stopDesktop: async () => {}, mode: 'apply',
-      deps: { gitExec: exec, delay, env: {} },
-    });
-    assert.equal(outcome.updated, true);
-    assert.equal(outcome.restartRequired, true);
-    assert.ok(calls.some(call => call.startsWith('merge --ff-only')));
-    assert.equal(readState(dir).appliedVersion, 'bbb222');
-    assert.equal(readState(dir).prevVersion, 'aaa111');
-  }
-
-  // --- git: interrupted apply is repaired from preUpdateHead ---
-  {
-    const root = tmp('hm-git-repair-');
-    fs.mkdirSync(path.join(root, '.git'), { recursive: true });
-    fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'harness-mix', version: '0.1.1' }));
-    const dir = tmp('hm-flow-');
-    writeState(dir, { ...readState(dir), channel: 'git', phase: 'applying', preUpdateHead: 'aaa111', appliedVersion: 'bbb222' });
-    const calls = [];
-    const exec = (cmd, args) => { calls.push(args.join(' ')); return { status: 0, stdout: '', stderr: '' }; };
-    const outcome = await runUpdateFlow({
-      root, dataDir: dir, log: quiet, stopDesktop: async () => {}, mode: 'apply',
-      deps: { gitExec: exec, delay, env: {} },
-    });
-    assert.equal(outcome.repaired, true);
-    assert.equal(outcome.restartRequired, true);
-    assert.ok(calls.some(call => call.startsWith('reset --hard aaa111')));
-    assert.equal(readState(dir).phase, 'idle');
-  }
-
-  console.log('native-update-apply: semver/channel/state/lock/etag/npm-apply/pending/offline/lock-skip/crash-loop-rollback/git-ff/git-repair all covered');
-})().catch(error => { console.error(error); process.exitCode = 1; });
+// Update v2 coverage: state file / lock / channel detection / semver, plus the
+// runUpdateFlow orchestration with mocked deps. Fully offline; no real npm/git.
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const {
+  acquireLock, compareVersions, detectChannel, markBootOk, readState, writeState,
+} = require('../src/main/native/update-state');
+const { fetchLatestVersion, runUpdateFlow } = require('../src/main/native/updater');
+
+const tmp = prefix => fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+const quiet = () => {};
+const delay = () => Promise.resolve();
+const fetchVersion = version => async () => ({
+  ok: true, status: 200,
+  json: async () => ({ 'dist-tags': { latest: version } }),
+  headers: { get: () => null },
+});
+const npmFixture = (version = '0.1.0') => {
+  const root = path.join(tmp('hm-npm-'), 'node_modules', 'harness-mix');
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'harness-mix', version }));
+  return root;
+};
+const npmRun = (root, { install = { status: 0 } } = {}) => (cmd, args) => {
+  if (args[0] === 'root') return { status: 0, stdout: `${path.dirname(root)}\n` };
+  if (args[0] === 'config') return { status: 0, stdout: 'https://registry.test/\n' };
+  if (args[0] === 'install') return install;
+  return { status: 0, stdout: '' };
+};
+
+(async () => {
+  // --- semver / channel detection ---
+  assert.equal(compareVersions('0.2.0', '0.1.1'), 1);
+  assert.equal(compareVersions('0.1.1', '0.1.1'), 0);
+  assert.equal(compareVersions('0.1.10', '0.1.9'), 1);
+  assert.equal(compareVersions('0.10.0', '0.9.9'), 1);
+  assert.equal(compareVersions('0.2.0-rc.1', '0.2.0'), -1);
+  assert.equal(compareVersions('0.2.0', '0.2.0-rc.1'), 1);
+
+  const gitRoot = tmp('hm-git-');
+  fs.mkdirSync(path.join(gitRoot, '.git'));
+  assert.equal(detectChannel(gitRoot), 'git');
+  assert.equal(detectChannel(npmFixture()), 'npm');
+  assert.equal(detectChannel(tmp('hm-plain-')), 'portable');
+
+  // --- state file tolerates corruption; lock lifecycle incl. stale reap ---
+  const data = tmp('hm-data-');
+  fs.writeFileSync(path.join(data, 'update-state.json'), '{not json');
+  assert.equal(readState(data).phase, 'idle');
+  const release = acquireLock(data, 'test');
+  assert.throws(() => acquireLock(data, 'test'), /更新锁/);
+  release();
+  acquireLock(data, 'test')();
+  fs.writeFileSync(path.join(data, 'update.lock'), JSON.stringify({ pid: process.pid, ts: Date.now() - 31 * 60 * 1000, op: 'stale' }));
+  acquireLock(data, 'test')(); // stale locks are reaped even when the pid still lives
+  writeState(data, { ...readState(data), appliedVersion: '0.2.0', appliedAt: Date.now() - 1000, attempts: 3 });
+  markBootOk(data);
+  assert.equal(readState(data).attempts, 0);
+  assert.ok(readState(data).lastBootOkAt > 0);
+
+  // --- fetchLatestVersion: etag cache answers 304 from disk ---
+  {
+    const dir = tmp('hm-etag-');
+    const first = await fetchLatestVersion({
+      registry: 'https://registry.test/', dataDir: dir,
+      fetchImpl: async () => ({ ok: true, status: 200, json: async () => ({ 'dist-tags': { latest: '9.9.9' } }), headers: { get: name => (name === 'etag' ? '"e1"' : null) } }),
+    });
+    assert.equal(first, '9.9.9');
+    const second = await fetchLatestVersion({
+      registry: 'https://registry.test/', dataDir: dir,
+      fetchImpl: async () => ({ ok: false, status: 304, headers: { get: () => null } }),
+    });
+    assert.equal(second, '9.9.9');
+  }
+
+  // --- npm: update available -> applied, restart required ---
+  {
+    const root = npmFixture();
+    const dir = tmp('hm-flow-');
+    const calls = [];
+    const run = (cmd, args) => { calls.push(args.join(' ')); return npmRun(root)(cmd, args); };
+    let stopped = 0;
+    const outcome = await runUpdateFlow({
+      root, dataDir: dir, log: quiet, stopDesktop: async () => { stopped += 1; }, mode: 'apply',
+      deps: { run, fetchImpl: fetchVersion('0.2.0'), delay, env: {} },
+    });
+    assert.equal(outcome.updated, true);
+    assert.equal(outcome.to, '0.2.0');
+    assert.equal(outcome.restartRequired, true);
+    assert.equal(stopped, 1);
+    assert.ok(calls.some(call => call.startsWith('install -g harness-mix@0.2.0')));
+    const state = readState(dir);
+    assert.equal(state.appliedVersion, '0.2.0');
+    assert.equal(state.prevVersion, '0.1.0');
+    assert.equal(state.phase, 'idle');
+  }
+
+  // --- npm: install failure -> pending for the next launch, never blocks ---
+  {
+    const root = npmFixture();
+    const dir = tmp('hm-flow-');
+    const outcome = await runUpdateFlow({
+      root, dataDir: dir, log: quiet, stopDesktop: async () => {}, mode: 'apply',
+      deps: { run: npmRun(root, { install: { status: 1, stderr: 'EBUSY: file locked' } }), fetchImpl: fetchVersion('0.2.0'), delay, env: {} },
+    });
+    assert.equal(outcome.updated, false);
+    assert.equal(outcome.pending, '0.2.0');
+    assert.equal(outcome.restartRequired, undefined);
+    assert.equal(readState(dir).pendingVersion, '0.2.0');
+  }
+
+  // --- npm: registry offline -> failed, launch continues ---
+  {
+    const root = npmFixture();
+    const dir = tmp('hm-flow-');
+    const outcome = await runUpdateFlow({
+      root, dataDir: dir, log: quiet, stopDesktop: async () => {}, mode: 'apply',
+      deps: { run: npmRun(root), fetchImpl: async () => { throw new Error('getaddrinfo ENOTFOUND'); }, delay, env: {} },
+    });
+    assert.equal(outcome.failed, true);
+    assert.equal(outcome.restartRequired, undefined);
+  }
+
+  // --- update lock held elsewhere -> skip without touching the desktop ---
+  {
+    const root = npmFixture();
+    const dir = tmp('hm-flow-');
+    fs.writeFileSync(path.join(dir, 'update.lock'), JSON.stringify({ pid: process.pid, ts: Date.now(), op: 'other' }));
+    let stopped = 0;
+    const outcome = await runUpdateFlow({
+      root, dataDir: dir, log: quiet, stopDesktop: async () => { stopped += 1; }, mode: 'apply',
+      deps: { run: npmRun(root), fetchImpl: fetchVersion('0.2.0'), delay, env: {} },
+    });
+    assert.equal(outcome.failed, true);
+    assert.equal(outcome.reason, 'lock');
+    assert.equal(stopped, 0);
+  }
+
+  // --- crash loop: second failed boot rolls back to prevVersion ---
+  {
+    const root = npmFixture('0.2.0'); // the installed tree currently runs 0.2.0
+    const dir = tmp('hm-flow-');
+    writeState(dir, { ...readState(dir), channel: 'npm', appliedVersion: '0.2.0', prevVersion: '0.1.0', appliedAt: Date.now() - 1000, lastBootOkAt: 0, attempts: 1 });
+    const calls = [];
+    const run = (cmd, args) => { calls.push(args.join(' ')); return npmRun(root)(cmd, args); };
+    const outcome = await runUpdateFlow({
+      root, dataDir: dir, log: quiet, stopDesktop: async () => {}, mode: 'apply',
+      deps: { run, fetchImpl: async () => { throw new Error('offline'); }, delay, env: {} },
+    });
+    assert.equal(outcome.rolledBack, true);
+    assert.equal(outcome.restartRequired, true);
+    assert.ok(calls.some(call => call.startsWith('install -g harness-mix@0.1.0')));
+    const state = readState(dir);
+    assert.equal(state.appliedVersion, null);
+    assert.equal(state.prevVersion, null);
+    assert.equal(state.attempts, 0);
+  }
+
+  // --- git: fast-forward applies and asks for a restart ---
+  {
+    const root = tmp('hm-git-flow-');
+    fs.mkdirSync(path.join(root, '.git'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'harness-mix', version: '0.1.1' }));
+    const dir = tmp('hm-flow-');
+    const script = {
+      'rev-parse HEAD': 'aaa111\n',
+      'rev-parse --abbrev-ref': 'origin/main\n',
+      fetch: '',
+      'rev-parse origin/main': 'bbb222\n',
+      'merge-base': 'aaa111\n',
+      status: '',
+      'diff --name-only': 'docs/x.md\n',
+      'merge --ff-only': '',
+    };
+    const calls = [];
+    const exec = (cmd, args) => {
+      const key = args.join(' ');
+      calls.push(key);
+      for (const [prefix, stdout] of Object.entries(script)) if (key.startsWith(prefix)) return { status: 0, stdout, stderr: '' };
+      return { status: 0, stdout: '', stderr: '' };
+    };
+    const outcome = await runUpdateFlow({
+      root, dataDir: dir, log: quiet, stopDesktop: async () => {}, mode: 'apply',
+      deps: { gitExec: exec, delay, env: {} },
+    });
+    assert.equal(outcome.updated, true);
+    assert.equal(outcome.restartRequired, true);
+    assert.ok(calls.some(call => call.startsWith('merge --ff-only')));
+    assert.equal(readState(dir).appliedVersion, 'bbb222');
+    assert.equal(readState(dir).prevVersion, 'aaa111');
+  }
+
+  // --- git: interrupted apply is repaired from preUpdateHead + rebuilt ---
+  {
+    const root = tmp('hm-git-repair-');
+    fs.mkdirSync(path.join(root, '.git'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'harness-mix', version: '0.1.1' }));
+    const dir = tmp('hm-flow-');
+    writeState(dir, { ...readState(dir), channel: 'git', phase: 'applying', preUpdateHead: 'aaa111', appliedVersion: 'bbb222' });
+    const calls = [];
+    const exec = (cmd, args) => { calls.push(args.join(' ')); return { status: 0, stdout: '', stderr: '' }; };
+    const outcome = await runUpdateFlow({
+      root, dataDir: dir, log: quiet, stopDesktop: async () => {}, mode: 'apply',
+      hooks: { build: () => calls.push('build-hook') },
+      deps: { gitExec: exec, delay, env: {} },
+    });
+    assert.equal(outcome.repaired, true);
+    assert.equal(outcome.restartRequired, true);
+    assert.ok(calls.some(call => call.startsWith('reset --hard aaa111')));
+    assert.ok(calls.includes('build-hook'), 'repair must rebuild so binaries match the reset sources');
+    assert.equal(readState(dir).phase, 'idle');
+  }
+
+  // --- deferred build (desktop-held locks) completes at the next boot ---
+  {
+    const root = tmp('hm-git-defer-');
+    fs.mkdirSync(path.join(root, '.git'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'harness-mix', version: '0.1.2' }));
+    const dir = tmp('hm-flow-');
+    writeState(dir, { ...readState(dir), channel: 'git', appliedVersion: 'bbb222', prevVersion: 'aaa111', pendingBuild: { since: Date.now() - 1000 }, preUpdateHead: 'aaa111' });
+    const calls = [];
+    const exec = (cmd, args) => { calls.push(args.join(' ')); return { status: 0, stdout: '', stderr: '' }; };
+    let stopped = 0;
+    const outcome = await runUpdateFlow({
+      root, dataDir: dir, log: quiet, mode: 'apply', completePendingBuild: true,
+      stopDesktop: async () => { stopped += 1; },
+      hooks: { build: () => calls.push('build-hook') },
+      deps: { gitExec: exec, delay, env: {} },
+    });
+    assert.equal(outcome.repaired, true);
+    assert.equal(outcome.restartRequired, undefined);
+    assert.ok(calls.includes('build-hook'));
+    assert.equal(stopped, 1, 'boot completion stops the desktop before rebuilding');
+    assert.equal(readState(dir).pendingBuild, null);
+  }
+
+  // --- deferred build completion failure rolls back to the pre-update head ---
+  {
+    const root = tmp('hm-git-defer-fail-');
+    fs.mkdirSync(path.join(root, '.git'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'harness-mix', version: '0.1.2' }));
+    const dir = tmp('hm-flow-');
+    writeState(dir, { ...readState(dir), channel: 'git', appliedVersion: 'bbb222', prevVersion: 'aaa111', pendingBuild: { since: Date.now() - 1000 }, preUpdateHead: 'aaa111' });
+    const calls = [];
+    const exec = (cmd, args) => { calls.push(args.join(' ')); return { status: 0, stdout: '', stderr: '' }; };
+    const outcome = await runUpdateFlow({
+      root, dataDir: dir, log: quiet, mode: 'apply', completePendingBuild: true,
+      stopDesktop: async () => {},
+      hooks: { build: () => { throw new Error('cargo failed'); } },
+      deps: { gitExec: exec, delay, env: {} },
+    });
+    assert.equal(outcome.failed, true);
+    assert.ok(calls.some(call => call.startsWith('reset --hard aaa111')));
+    const state = readState(dir);
+    assert.equal(state.pendingBuild, null);
+    assert.equal(state.appliedVersion, null);
+  }
+
+  // --- a corrupt lock file is reaped, not treated as a live holder ---
+  {
+    const data = tmp('hm-lock-');
+    fs.writeFileSync(path.join(data, 'update.lock'), '{not json');
+    acquireLock(data, 'test')();
+  }
+
+  console.log('native-update-apply: semver/channel/state/lock/etag/npm-apply/pending/offline/lock-skip/crash-loop-rollback/git-ff/git-repair+build/deferred-build/defer-fail/corrupt-lock all covered');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/scripts/native-update.cjs

@@ -0,0 +1,78 @@
+// Desktop-triggered update helper, spawned detached by the native host
+// (harnessmix/update/start). Everything here runs outside the host process:
+// - host stdout is the JSONL protocol channel; updater and child output must
+//   never mix into it, so this process writes <dataDir>/update.log instead;
+// - the host sits inside the shim's kill-on-close job: stopping the Desktop
+//   from inside the host would kill the update together with the host, so the
+//   flow applies with stopDesktop disabled and stops the Desktop only as its
+//   last act, and only when work was parked for the next `npm start`;
+// - native binaries locked by the running Desktop defer their rebuild via the
+//   pendingBuild state; the launcher completes it at the next boot.
+const fs = require('node:fs');
+const path = require('node:path');
+const { nativeEnvironment } = require('../src/main/native/config');
+const { runUpdateFlow, defaultHooks } = require('../src/main/native/updater');
+const { readState, updateState } = require('../src/main/native/update-state');
+const { inspect, stopDesktopProcesses } = require('../src/main/native/launcher');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+// build-native.cjs surfaces EBUSY as "... is locked by a running Codex Desktop";
+// EPERM covers antivirus transient holds on the same files.
+const LOCKED_BUILD = /locked by a running Codex Desktop|EBUSY|EPERM|being used by another process/i;
+
+const dataDir = nativeEnvironment().HARNESSMIX_DATA_DIR;
+const logFile = path.join(dataDir, 'update.log');
+const log = message => {
+  try { fs.appendFileSync(logFile, `[${new Date().toISOString()}] ${message}\n`); } catch { /* best-effort */ }
+};
+
+async function main() {
+  fs.mkdirSync(dataDir, { recursive: true });
+  log('--- 桌面触发的更新开始 ---');
+  const base = defaultHooks(REPO_ROOT);
+  const hooks = {
+    install: () => base.install(),
+    build: () => {
+      try {
+        base.build();
+      } catch (error) {
+        if (!LOCKED_BUILD.test(String((error && error.message) || ''))) throw error;
+        updateState(dataDir, { pendingBuild: { since: Date.now() } });
+        log(`[Harness Mix] 原生组件被运行中的 Desktop 锁定，构建推迟到下次启动：${error.message}`);
+      }
+    },
+  };
+  let outcome;
+  try {
+    outcome = await runUpdateFlow({
+      root: REPO_ROOT,
+      dataDir,
+      mode: 'apply',
+      log,
+      stopDesktop: async () => {},
+      hooks,
+    });
+  } catch (error) {
+    log(`[Harness Mix] 更新流程异常退出：${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  log(`[Harness Mix] 更新流程结束：${JSON.stringify(outcome)}`);
+  const state = readState(dataDir);
+  // Parked work (deferred build / npm pendingVersion) can only complete once
+  // the Desktop releases its file locks, i.e. at the next `npm start` boot.
+  if (state.pendingBuild || state.pendingVersion) {
+    log('[Harness Mix] 存在待下次启动完成的工作，正在关闭 Codex Desktop…');
+    try {
+      stopDesktopProcesses(await inspect());
+      log('[Harness Mix] 已请求关闭 Codex Desktop；请重新运行 npm start 完成更新。');
+    } catch (error) {
+      log(`[Harness Mix] 关闭 Desktop 失败（可手动关闭后运行 npm start）：${error.message}`);
+    }
+  }
+}
+
+main().catch(error => {
+  log(`[Harness Mix] 更新助手崩溃：${(error && error.stack) || error}`);
+  process.exitCode = 1;
+});