dsh-notch 0.3.1

package/src/store.ts

@@ -0,0 +1,49 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+
+const DIR = join(homedir(), '.dsh', 'dsh-notch')
+const RUNTIME = join(DIR, 'runtime.json')
+const SEEN = join(DIR, 'seen.json')
+
+export interface RuntimeFile {
+  origin: string
+  token: string
+  pid: number
+  writtenAt: number
+}
+
+function ensureDir(): void {
+  mkdirSync(DIR, { recursive: true, mode: 0o700 })
+}
+
+function readJson<T>(path: string): T | undefined {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T
+  } catch {
+    return undefined
+  }
+}
+
+export function loadOrCreateToken(): string {
+  const existing = readJson<RuntimeFile>(RUNTIME)
+  if (existing?.token && existing.token.length >= 16) return existing.token
+  return randomBytes(24).toString('hex')
+}
+
+export function writeRuntime(file: RuntimeFile): void {
+  ensureDir()
+  writeFileSync(RUNTIME, `${JSON.stringify(file, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+}
+
+export function loadSeen(): Record<string, number> {
+  const value = readJson<Record<string, number>>(SEEN)
+  if (!value || typeof value !== 'object') return {}
+  return value
+}
+
+export function saveSeen(map: Record<string, number>): void {
+  ensureDir()
+  writeFileSync(SEEN, `${JSON.stringify(map)}\n`, { encoding: 'utf8', mode: 0o600 })
+}

package/src/types.ts

@@ -0,0 +1,65 @@
+/** JSON contract between the Host plugin and the native helper. */
+
+export type ApprovalOutcomeWire = 'allowed-once' | 'rejected'
+
+export interface NotchOption {
+  label: string
+  description?: string
+}
+
+export interface NotchQuestion {
+  id: string
+  question: string
+  detail?: string
+  header?: string
+  options?: NotchOption[]
+  multiSelect?: boolean
+  intent?: { kind: 'plan-review'; approve: string }
+}
+
+export interface NotchApproval {
+  id: string
+  toolName: string
+  reason?: string
+}
+
+export interface NotchAsk {
+  id: string
+  questions: NotchQuestion[]
+}
+
+export interface NotchLastTurn {
+  at: number
+  kind: string
+  failed: boolean
+}
+
+export interface NotchRow {
+  id: string
+  title: string
+  child: boolean
+  busy: boolean
+  unread: boolean
+  lastTurn?: NotchLastTurn
+  approval?: NotchApproval
+  ask?: NotchAsk
+}
+
+export interface NotchSnapshot {
+  ok: true
+  generatedAt: number
+  sidebarSyncedAt?: number
+  origin: string
+  rows: NotchRow[]
+}
+
+export interface NotchAnswerItem {
+  id: string
+  selected: string[]
+  custom?: string
+}
+
+export interface NotchFocus {
+  sessionId: string
+  at: number
+}

package/tests/answer-lifecycle.test.mjs

@@ -0,0 +1,23 @@
+import {test} from 'node:test';import assert from 'node:assert/strict';
+import os from 'node:os';
+import {mkdtempSync, rmSync} from 'node:fs';
+import {syncBuiltinESMExports} from 'node:module';
+import {after} from 'node:test';
+const testDir=mkdtempSync(os.tmpdir()+'/notch-answer-test-');
+const realHomedir=os.homedir;
+os.homedir=()=>testDir; syncBuiltinESMExports();
+const {Board}=await import('../src/board.ts');
+os.homedir=realHomedir; syncBuiltinESMExports();
+after(()=>rmSync(testDir,{recursive:true,force:true}));
+const session={id:'notch-lifecycle-test',header:{},snapshotEvents:()=>[]};
+const ctx={sessions:{list:()=>[session]},agents:{get:()=>({status:'running'})},get:()=>undefined,logger:{warn(){}}};
+test('Notch answer cancels the web wait and preserves caller signal',async()=>{
+ const board=new Board(ctx), owner=new AbortController();const request={agent:{id:session.id},questions:[{id:'q',question:'test'}],signal:owner.signal};let webVisible=true;
+ const pending=board.holdAsk(request,()=>new Promise((resolve,reject)=>{request.signal.addEventListener('abort',()=>{webVisible=false;reject(Error('web wait ended'))},{once:true})}));
+ const ask=board.snapshot('http://localhost').rows[0].ask;assert.ok(ask);assert.equal(board.answerAsk(ask.id,[{id:'q',selected:['test']}]),true);
+ assert.deepEqual(await pending,{answers:[{id:'q',selected:['test']}]});assert.equal(webVisible,false);assert.equal(owner.signal.aborted,false);assert.equal(request.signal,owner.signal);
+});
+test('Web answer removes the Notch request',async()=>{
+ const board=new Board(ctx);let finish;const answer={answers:[{id:'q',selected:[]}]};
+ const pending=board.holdAsk({agent:{id:session.id},questions:[{id:'q',question:'test'}]},()=>new Promise(r=>finish=r));await Promise.resolve();finish(answer);assert.equal(await pending,answer);assert.equal(board.snapshot('http://localhost').rows[0].ask,undefined);
+});

package/tests/board.test.mjs

@@ -0,0 +1,7 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {Board} from '../src/board.ts'
+const session={id:'session-regression',header:{},snapshotEvents:()=>[]}
+const ctx={sessions:{list:()=>[session]},agents:{get:()=>({status:'running'})},get:()=>undefined,logger:{warn:()=>{}}}
+test('snapshot and background notification handle live sessions without missing seen state',()=>{const board=new Board(ctx);let notifications=0;board.onChange(()=>{assert.equal(board.snapshot('http://localhost').rows.length,1);notifications++});board.notify();assert.equal(notifications,1)})
+test('one broken subscriber cannot crash Host or stop other subscribers',()=>{const board=new Board(ctx);let n=0;board.onChange(()=>{throw Error('broken stream')});board.onChange(()=>n++);assert.doesNotThrow(()=>board.notify());assert.equal(n,1)})

package/tests/browse-sync.test.mjs

@@ -0,0 +1,20 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {installBrowseSync} from '../src/browse-sync.ts'
+class Controller { history={page:async()=>({records:[1]}),follow:async function*(){yield {records:[1]}}}; page(request,signal){return this.history.page(request,signal)} follow(request,signal){return this.history.follow(request,signal)} }
+const req={address:{sessionId:'test'}}
+test('legacy synchronous Notch wrapper reproduces exact error; repair removes all nested wrappers',async()=>{
+ const c=new Controller();const board={markSeen(){}};const getTargetSessionId=a=>a.sessionId
+ for(let i=0;i<2;i++){const origFollow=c.follow.bind(c);c.follow=function* (req, signal) {const sid=getTargetSessionId(req.address);if(sid)board.markSeen(sid);return yield* origFollow(req,signal)}}
+ await assert.rejects(async()=>{for await(const x of c.follow(req)){}},/is not iterable/)
+ const stop=installBrowseSync(c,()=>{});const rows=[];for await(const x of c.follow(req))rows.push(x)
+ assert.deepEqual(rows,[{records:[1]}]);stop();assert.equal(Object.hasOwn(c,'follow'),false)
+})
+test('preserves async stream identity, return, cancellation; repeated generations dispose cleanly',async()=>{
+ const c=new Controller();let returned=0;const signal=AbortSignal.abort();const source={async *[Symbol.asyncIterator](){try{yield 1;yield 2}finally{returned++}}}
+ c.history.follow=(r,s)=>{assert.equal(s,signal);return source}
+ let a=0,b=0;const stopA=installBrowseSync(c,()=>a++);const stopB=installBrowseSync(c,()=>b++)
+ assert.equal(c.follow(req,signal),source);stopA();const stream=c.follow(req,signal);for await(const v of stream){break}
+ assert.equal(a,1);assert.equal(b,2);assert.equal(returned,1);stopB();stopB();assert.equal(Object.hasOwn(c,'follow'),false)
+ const stop=installBrowseSync(c,()=>{throw Error('read marker failed')});assert.deepEqual(await c.page(req),{records:[1]});stop()
+})

package/tests/mirror.test.mjs

@@ -0,0 +1,4 @@
+import {test} from 'node:test';import assert from 'node:assert/strict';import {Board} from '../src/board.ts';
+const ctx={sessions:{list:()=>[]},agents:{get:()=>undefined},get:()=>undefined,logger:{warn:()=>{}}};
+test('sidebar completion survives cold session; opening in DSH clears green; background page cannot overwrite',()=>{const b=new Board(ctx);const row={id:'session-cold',title:'Cold',running:false,completed:true};assert.equal(b.syncSidebar({clientId:'app',focused:true,rows:[row]}),true);assert.equal(b.snapshot('').rows[0].unread,true);assert.equal(b.requestFocus(row.id),true);b.syncSidebar({clientId:'app',focused:true,rows:[]});assert.equal(b.snapshot('').rows.length,0);b.syncSidebar({clientId:'browser',focused:false,rows:[row]});assert.equal(b.snapshot('').rows.length,0)});
+test('malformed mirror never replaces previous valid state',()=>{const b=new Board(ctx);assert.equal(b.syncSidebar({clientId:'app',rows:[{id:123}]}),false);assert.deepEqual(b.snapshot('').rows,[])});

package/tests/peer-range.test.mjs

@@ -0,0 +1,21 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+const RANGE = '>=0.1.7-rc.1 <0.1.8'
+const PEERS = [
+  '@deepseek-ai/dsh',
+  '@deepseek-ai/dsh-host-webserver',
+  '@deepseek-ai/dsh-session',
+  '@deepseek-ai/dsh-user-approval',
+  '@deepseek-ai/dsh-user-questions',
+]
+
+test('Harness peer range is the 0.1.7-rc.1 desk pin', () => {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+  assert.equal(pkg.version, '0.3.1')
+  for (const name of PEERS) {
+    assert.equal(pkg.peerDependencies[name], RANGE)
+    assert.equal(pkg.peerDependenciesMeta[name].optional, true)
+  }
+})

package/tests/session-state.test.mjs

@@ -0,0 +1,54 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { foldSession } from '../src/session-state.ts'
+
+function session(events) {
+  return { snapshotEvents: () => events }
+}
+
+test('aborted last turn is not a failure lamp', () => {
+  const folded = foldSession(session([
+    { type: 'turn/start', time: 1 },
+    { type: 'turn/end', time: 2, data: { reason: { kind: 'aborted' } } },
+  ]))
+  assert.equal(folded.busy, false)
+  assert.equal(folded.lastTurn.kind, 'aborted')
+  assert.equal(folded.lastTurn.failed, false)
+})
+
+test('interrupted last turn is not a failure lamp', () => {
+  const folded = foldSession(session([
+    { type: 'turn/start', time: 1 },
+    { type: 'turn/end', time: 2, data: { reason: { kind: 'interrupted' } } },
+  ]))
+  assert.equal(folded.lastTurn.failed, false)
+})
+
+test('a new turn clears the previous abort so a running session cannot stay red', () => {
+  const folded = foldSession(session([
+    { type: 'turn/start', time: 1 },
+    { type: 'turn/end', time: 2, data: { reason: { kind: 'aborted' } } },
+    { type: 'turn/start', time: 3 },
+  ]))
+  assert.equal(folded.busy, true)
+  assert.equal(folded.lastTurn, undefined)
+})
+
+test('a fork-seed closer is not a failure lamp', () => {
+  const folded = foldSession(session([
+    { type: 'turn/start', time: 1 },
+    { type: 'turn/end', time: 2, data: { reason: { kind: 'forked' } } },
+  ]))
+  assert.equal(folded.busy, false)
+  assert.equal(folded.lastTurn.kind, 'forked')
+  assert.equal(folded.lastTurn.failed, false)
+})
+
+test('error still counts as failed after the turn ends', () => {
+  const folded = foldSession(session([
+    { type: 'turn/start', time: 1 },
+    { type: 'turn/end', time: 2, data: { reason: { kind: 'error' } } },
+  ]))
+  assert.equal(folded.busy, false)
+  assert.equal(folded.lastTurn.failed, true)
+})

package/tests/unread-hold.test.mjs

@@ -0,0 +1,90 @@
+import { test, after } from 'node:test'
+import assert from 'node:assert/strict'
+import os from 'node:os'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { syncBuiltinESMExports } from 'node:module'
+
+const testDir = mkdtempSync(os.tmpdir() + '/notch-unread-')
+const realHomedir = os.homedir
+os.homedir = () => testDir
+syncBuiltinESMExports()
+const { Board } = await import('../src/board.ts')
+os.homedir = realHomedir
+syncBuiltinESMExports()
+after(() => rmSync(testDir, { recursive: true, force: true }))
+
+test('a single running task becomes a green unread lamp instead of vanishing', () => {
+  let running = true
+  const events = [{ type: 'turn/start', time: 1 }]
+  const session = {
+    id: 'session-one',
+    header: {},
+    snapshotEvents: () => events,
+  }
+  const ctx = {
+    sessions: { list: () => [session] },
+    agents: { get: () => ({ status: running ? 'running' : 'idle' }) },
+    get: () => undefined,
+    logger: { warn() {} },
+  }
+  const board = new Board(ctx)
+  assert.equal(board.snapshot('').rows[0].busy, true)
+
+  running = false
+  events.push({ type: 'turn/end', time: 2, data: { reason: { kind: 'completed' } } })
+  const done = board.snapshot('').rows[0]
+  assert.equal(done.busy, false)
+  assert.equal(done.unread, true)
+  assert.equal(board.snapshot('').rows[0].unread, true)
+
+  board.markSeen(session.id)
+  assert.equal(board.snapshot('').rows.length, 0)
+})
+
+test('clicking seen clears green even if the sidebar still says completed', () => {
+  let running = true
+  const events = [{ type: 'turn/start', time: 1 }]
+  const session = {
+    id: 'session-sidebar',
+    header: {},
+    snapshotEvents: () => events,
+  }
+  const ctx = {
+    sessions: { list: () => [session] },
+    agents: { get: () => ({ status: running ? 'running' : 'idle' }) },
+    get: () => undefined,
+    logger: { warn() {} },
+  }
+  const board = new Board(ctx)
+  board.snapshot('')
+  running = false
+  events.push({ type: 'turn/end', time: 2, data: { reason: { kind: 'completed' } } })
+  board.snapshot('')
+  board.syncSidebar({
+    clientId: 'app',
+    focused: true,
+    rows: [{ id: session.id, title: 'Done', running: false, completed: true }],
+  })
+  assert.equal(board.snapshot('').rows[0].unread, true)
+  board.markSeen(session.id)
+  assert.equal(board.snapshot('').rows.length, 0)
+})
+
+test('cold completed history is not replayed as green', () => {
+  const session = {
+    id: 'session-old',
+    header: {},
+    snapshotEvents: () => [
+      { type: 'turn/start', time: 1 },
+      { type: 'turn/end', time: 2, data: { reason: { kind: 'completed' } } },
+    ],
+  }
+  const ctx = {
+    sessions: { list: () => [session] },
+    agents: { get: () => ({ status: 'idle' }) },
+    get: () => undefined,
+    logger: { warn() {} },
+  }
+  const board = new Board(ctx)
+  assert.equal(board.snapshot('').rows.length, 0)
+})

package/tools/desktop-shell/README.md

@@ -0,0 +1,56 @@
+# Desktop renderer recovery
+
+This optional thin-shell patch prevents an unexpected renderer exit from leaving
+an existing DSH window permanently blank. It does **not** identify or fix the
+underlying long-idle renderer termination.
+
+The recovery controller listens to `render-process-gone`, including `clean-exit`.
+While the app/window remains open it reloads the original WebContents, preserves
+its navigation/auth context, requests a repaint after load, and records the result.
+It never starts, stops or restarts a Host. Two automatic attempts are allowed per
+minute; further exits and a 15-second load timeout go to a native error prompt.
+App quit/window close cancels pending work. The shell integration adds window and
+system idle metadata to bounded local diagnostic logs.
+
+`child-log.mjs` fixes a separate shutdown race: each child stdout/stderr stream
+pipes with `end: false` so EOF cannot close the shared desktop log before an exit
+callback writes to it. Logging errors cannot raise an uncaught main-process error.
+
+## Checks
+
+```sh
+node --test tools/desktop-shell/*.test.mjs tools/diagnostics/renderer-diagnostics.test.mjs
+"$DSH_TEST_ELECTRON" tools/desktop-shell/recovery-probe.cjs --baseline
+"$DSH_TEST_ELECTRON" tools/desktop-shell/recovery-probe.cjs
+```
+
+Use the target app's matching Electron executable. The baseline is expected to
+fail: it has no recovery handler. The repaired native integration fixture uses a
+temporary profile/static page, crashes only its own renderer, checks both visible
+and hidden windows twice, verifies an actual painted frame against its healthy
+baseline (including display color management), and verifies retry limiting.
+It never reads DSH conversations or invokes models. This is an Electron lifecycle
+test, not an alternative browser automation interface.
+
+## Package and activate
+
+`package-recovery.py <original-app.asar> <staging-directory>` produces a patched
+ASAR, readable main module, and input/output hash manifest. It requires the known
+thin-shell source shape with the earlier diagnostics hook and refuses an already
+patched or unfamiliar archive. Every unrelated archive entry is preserved and
+all output entry bytes are verified. To test packaged recovery, set
+`DSH_RECOVERY_MODULE` to the staged ASAR's `src/renderer-recovery.mjs` before the
+native probe. The script never installs or controls a process.
+
+Keep a verified copy of the original ASAR. Installation is a separate, authorized,
+atomic resource replacement after checking that the current archive still matches
+the reviewed input. Shell-main changes require a controlled App reopen. The current
+App owns its Host: do this only with the applicable task authorization and an idle
+runtime, and prove that the old Host exited before launching the original App.
+Once active, routine renderer recovery does not require another App/Host restart.
+Verify diagnostic attachment plus the actual conversation/composer through the
+normal app. A package checksum or a recovery log is not visual acceptance.
+
+For rollback, restore the exact preserved original archive and perform the same
+controlled App reopen. Never replace the user's checkout, history or Notch assets.
+Do not commit local logs, screenshots, session data or installed-artifact backups.

package/tools/desktop-shell/child-log.mjs

@@ -0,0 +1,6 @@
+// stdout and stderr (and sometimes several children) share one desktop log.
+// EOF belongs to an input stream; it must not end the shared destination.
+export function pipeChildLog(child, log) {
+  child.stdout?.pipe(log, {end: false});
+  child.stderr?.pipe(log, {end: false});
+}

package/tools/desktop-shell/child-log.test.mjs

@@ -0,0 +1,14 @@
+import {test} from 'node:test';import assert from 'node:assert/strict';import {PassThrough} from 'node:stream';
+import {pipeChildLog} from './child-log.mjs';
+test('child EOF leaves shared log open for exit callback and other child',async()=>{
+ const log=new PassThrough(),chunks=[],errors=[];log.on('data',c=>chunks.push(c.toString()));log.on('error',e=>errors.push(e));
+ const first={stdout:new PassThrough(),stderr:new PassThrough()},second={stdout:new PassThrough(),stderr:new PassThrough()};
+ pipeChildLog(first,log);pipeChildLog(second,log);
+ first.stdout.end('first-out\n');first.stderr.end('first-err\n');
+ await new Promise(setImmediate);
+ assert.equal(log.writableEnded,false);
+ log.write('first-exit\n');second.stdout.end('second-out\n');second.stderr.end('second-err\n');
+ await new Promise(setImmediate);
+ log.write('second-exit\n');await new Promise(setImmediate);
+ assert.equal(errors.length,0);assert.match(chunks.join(''),/first-exit/);assert.match(chunks.join(''),/second-exit/);log.end();
+});

package/tools/desktop-shell/package-recovery.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Stage a reviewed thin-shell patch. Never installs or restarts DSH."""
+from pathlib import Path
+import argparse, hashlib, json, struct
+p=argparse.ArgumentParser();p.add_argument('archive',type=Path);p.add_argument('output',type=Path);args=p.parse_args()
+raw=args.archive.read_bytes();hs=struct.unpack_from('<I',raw,4)[0];js=struct.unpack_from('<I',raw,12)[0]
+tree=json.loads(raw[16:16+js]);files={}
+def walk(entries,prefix=''):
+ for name,e in entries.items():
+  key=prefix+name
+  if 'files' in e:walk(e['files'],key+'/')
+  else:
+   assert not e.get('unpacked') and 'link' not in e, 'unsupported archive entry'
+   start=8+hs+int(e['offset']);files[key]=raw[start:start+e['size']]
+walk(tree['files'])
+original=dict(files);source=files['src/main.mjs'].decode()
+assert 'installRendererRecovery' not in source, 'recovery already installed; use the preserved base archive'
+def replace(old,new):
+ global source
+ assert source.count(old)==1, 'unexpected shell source: '+old[:70]
+ source=source.replace(old,new,1)
+replace("import { createDiagnosticLog, installRendererDiagnostics }", "import { pipeChildLog } from './child-log.mjs'\nimport { installRendererRecovery } from './renderer-recovery.mjs'\nimport { createDiagnosticLog, installRendererDiagnostics }")
+replace('const { app, BrowserWindow, Menu, clipboard, session, shell, systemPreferences } = electron','const { app, BrowserWindow, Menu, clipboard, session, shell, systemPreferences, powerMonitor, dialog } = electron')
+replace('''  const attachDiagnostics = contents => installRendererDiagnostics({
+    app, contents, write: diagnosticWrite,
+    related: () => ({hostPid: sidecar?.pid ?? null, notchPid: notch?.pid ?? null}),
+  })''','''  const attachDiagnostics = contents => {
+    const owner = BrowserWindow.fromWebContents(contents)
+    installRendererDiagnostics({
+      app, contents, window: owner, powerMonitor, write: diagnosticWrite,
+      related: () => ({hostPid: sidecar?.pid ?? null, notchPid: notch?.pid ?? null}),
+    })
+    let promptOpen = false
+    installRendererRecovery({
+      app, window: owner, write: diagnosticWrite,
+      onUnavailable: async () => {
+        if (promptOpen || owner.isDestroyed()) return
+        promptOpen = true
+        try {
+          const result = await dialog.showMessageBox(owner, {
+            type: 'error', title: 'DSH 页面未能恢复',
+            message: '页面连续异常退出或重新加载超时。',
+            detail: '后台服务没有因页面恢复而重启。可以重新加载页面，或稍后从 View → Reload 重试。',
+            buttons: ['重新加载页面', '稍后'], defaultId: 0, cancelId: 1, noLink: true,
+          })
+          if (result.response === 0 && !owner.isDestroyed()) contents.reload()
+        } finally { promptOpen = false }
+      },
+    })
+  }''')
+pair="  child.stdout?.pipe(log)\n  child.stderr?.pipe(log)"
+assert source.count(pair)==2
+source=source.replace(pair, '  pipeChildLog(child, log)')
+replace("  return log\n}", "  log.on('error', () => {}) // Logging failure must not crash the desktop shell.\n  return log\n}")
+root=Path(__file__).parent
+files['src/child-log.mjs']=(root/'child-log.mjs').read_bytes()
+files['src/main.mjs']=source.encode()
+files['src/renderer-recovery.mjs']=(root/'renderer-recovery.mjs').read_bytes()
+files['src/renderer-diagnostics.mjs']=(root.parent/'diagnostics/renderer-diagnostics.mjs').read_bytes()
+header={'files':{}};payload=bytearray()
+for name,body in files.items():
+ node=header['files'];parts=name.split('/')
+ for part in parts[:-1]:node=node.setdefault(part,{'files':{}})['files']
+ digest=hashlib.sha256(body).hexdigest()
+ node[parts[-1]]={'size':len(body),'offset':str(len(payload)),'integrity':{'algorithm':'SHA256','hash':digest,'blockSize':4194304,'blocks':[hashlib.sha256(body[i:i+4194304]).hexdigest() for i in range(0,len(body),4194304)]}}
+ payload.extend(body)
+encoded=json.dumps(header,separators=(',',':')).encode();body=struct.pack('<I',len(encoded))+encoded;body+=b'\0'*((-len(body))%4);pickle=struct.pack('<I',len(body))+body
+archive=struct.pack('<II',4,len(pickle))+pickle+payload
+args.output.mkdir(parents=True,exist_ok=True)
+(args.output/'app.asar').write_bytes(archive)
+(args.output/'main.mjs').write_text(source)
+new_hs=struct.unpack_from('<I',archive,4)[0]
+for name,expected in files.items():
+ node=header['files']
+ for part in name.split('/')[:-1]:node=node[part]['files']
+ e=node[name.split('/')[-1]];start=8+new_hs+int(e['offset']);assert archive[start:start+e['size']]==expected
+manifest={'inputSHA256':hashlib.sha256(raw).hexdigest(),'outputSHA256':hashlib.sha256(archive).hexdigest(),'changed':[n for n,b in files.items() if original.get(n)!=b]}
+(args.output/'manifest.json').write_text(json.dumps(manifest,indent=2)+'\n');print(json.dumps(manifest))

package/tools/desktop-shell/recovery-probe.cjs

@@ -0,0 +1,50 @@
+// Native integration test: isolated profile/static fixture, never the user's DSH.
+const {app,BrowserWindow}=require('electron');
+const assert=require('node:assert/strict');
+const fs=require('node:fs'),os=require('node:os'),path=require('node:path');
+const {pathToFileURL}=require('node:url');
+const profile=fs.mkdtempSync(path.join(os.tmpdir(),'dsh-recovery-test-'));
+app.setPath('userData',profile);app.setPath('sessionData',profile);
+app.on('window-all-closed',()=>{});
+const nativePid=process.pid;
+const waitFor=(emitter,event)=>new Promise(resolve=>emitter.once(event,resolve));
+const delay=ms=>new Promise(resolve=>setTimeout(resolve,ms));
+const deadline=setTimeout(()=>{console.error('native recovery timeout');app.exit(2)},20000);
+app.whenReady().then(async()=>{
+ const {installRendererRecovery}=await import(pathToFileURL(process.env.DSH_RECOVERY_MODULE||path.join(__dirname,'renderer-recovery.mjs')));
+ const results=[];
+ for(const hidden of [false,true]){
+  const events=[];let unavailable=0;
+  const window=new BrowserWindow({width:460,height:220,show:false,webPreferences:{sandbox:true,contextIsolation:true,nodeIntegration:false}});
+  const wc=window.webContents;
+  let complete;
+  if(!process.argv.includes('--baseline'))installRendererRecovery({app,window,write:(event,data)=>{events.push({event,...data});if(event==='renderer-recovery-complete')complete?.()},onUnavailable:()=>unavailable++});
+  await window.loadURL('data:text/html,<title>DSH recovery fixture</title><body style="margin:0;background:%23004c2e;color:white;font:24px sans-serif;padding:32px"><h1>Recovery fixture</h1><p>Local static page. No model calls.</p></body>');
+  if(!hidden)window.showInactive();
+  const originalContents=wc.id;
+  const baselinePixels=(await wc.capturePage()).toBitmap();
+  const reference=Array.from(baselinePixels.subarray(0,4));
+  assert.ok(reference[1]>reference[0]&&reference[1]>reference[2]&&reference[3]>0,'baseline fixture must be green');
+  for(let cycle=1;cycle<=2;cycle++){
+   const oldPid=wc.getOSProcessId();
+   const recovered=new Promise(resolve=>{complete=resolve});
+   const gone=waitFor(wc,'render-process-gone');
+   wc.forcefullyCrashRenderer();
+   await gone;
+   if(process.argv.includes('--baseline')){await delay(700);assert.ok(wc.getOSProcessId()>0,'renderer remains dead: persistent blank window after exit');}
+   await recovered;
+   assert.equal(process.pid,nativePid);assert.equal(wc.id,originalContents);
+   assert.ok(wc.getOSProcessId()>0);assert.notEqual(wc.getOSProcessId(),oldPid);
+   assert.equal(await wc.executeJavaScript('document.querySelector("h1").textContent'),'Recovery fixture');
+   const frame=await wc.capturePage();const pixels=frame.toBitmap();
+   let green=0;for(let i=0;i<pixels.length;i+=4)if(reference.every((v,j)=>Math.abs(pixels[i+j]-v)<=3))green++;
+   assert.ok(green>pixels.length/4*.5,'recovered page must paint fixture background instead of white');
+   results.push({hidden,cycle,recovered:true,sameContents:true,painted:true});
+  }
+  const gone=waitFor(wc,'render-process-gone');wc.forcefullyCrashRenderer();await gone;await delay(400);
+  assert.equal(unavailable,1,'third rapid exit must stop auto reload');
+  window.destroy();
+ }
+ console.log(JSON.stringify({electron:process.versions.electron,results,boundedRetry:true}));
+ clearTimeout(deadline);app.exit(0);
+}).catch(error=>{console.error(error.stack);clearTimeout(deadline);app.exit(1)});

package/tools/desktop-shell/renderer-recovery.mjs

@@ -0,0 +1,95 @@
+// Recovery belongs to the desktop window, never to the Host or a plugin session.
+// A zero exit code is still unexpected while the user's window remains open.
+export function installRendererRecovery({
+  app, window, write = () => {}, onUnavailable = () => {},
+  repaint = () => window.webContents.invalidate(),
+  now = Date.now, scheduler = {setTimeout, clearTimeout},
+  retryDelayMs = 250, loadTimeoutMs = 15000, maxAttempts = 2, retryWindowMs = 60000,
+}) {
+  const contents = window.webContents;
+  const listeners = [];
+  let disposed = false, quitting = false, closing = false;
+  let pending = false, reloadTimer = null, deadlineTimer = null, attempts = [];
+  const on = (emitter, event, fn) => {
+    emitter.on(event, fn);
+    listeners.push(() => emitter.removeListener(event, fn));
+  };
+  const live = () => !disposed && !quitting && !closing && !window.isDestroyed() && !contents.isDestroyed();
+  const record = (event, data = {}) => {
+    try { write(event, {contentsId: contents.id, ...data}); } catch {}
+  };
+  const clearTimers = () => {
+    if (reloadTimer !== null) scheduler.clearTimeout(reloadTimer);
+    if (deadlineTimer !== null) scheduler.clearTimeout(deadlineTimer);
+    reloadTimer = deadlineTimer = null;
+  };
+  const unavailable = reason => {
+    record('renderer-recovery-unavailable', {reason});
+    try { Promise.resolve(onUnavailable(reason)).catch(() => {}); } catch {}
+  };
+  const watchLoad = () => {
+    if (deadlineTimer !== null) scheduler.clearTimeout(deadlineTimer);
+    deadlineTimer = scheduler.setTimeout(() => {
+      deadlineTimer = null;
+      if (live() && pending) unavailable('load-timeout');
+    }, loadTimeoutMs);
+  };
+  on(contents, 'render-process-gone', (_event, details) => {
+    if (!live()) return;
+    if (reloadTimer !== null) return;
+    clearTimers();
+    pending = false;
+    const time = now();
+    attempts = attempts.filter(at => time - at < retryWindowMs);
+    if (attempts.length >= maxAttempts) { unavailable('repeated-exit'); return; }
+    attempts.push(time);
+    pending = true;
+    record('renderer-recovery-scheduled', {reason: details.reason, exitCode: details.exitCode, attempt: attempts.length});
+    reloadTimer = scheduler.setTimeout(() => {
+      reloadTimer = null;
+      if (!live() || !pending) return;
+      watchLoad();
+      try {
+        // Preserve the existing navigation controller, auth session and conversation.
+        if (!contents.isLoading()) contents.reload();
+      } catch {
+        clearTimers();
+        pending = false;
+        unavailable('reload-failed');
+      }
+    }, retryDelayMs);
+  });
+  on(contents, 'did-start-loading', () => {
+    if (!live() || !pending) return;
+    // A user's manual Reload can win the race with our queued recovery.
+    if (reloadTimer !== null) scheduler.clearTimeout(reloadTimer);
+    reloadTimer = null;
+    watchLoad();
+  });
+  on(contents, 'did-finish-load', () => {
+    if (!live() || !pending || contents.getOSProcessId() <= 0) return;
+    clearTimers();
+    pending = false;
+    try { repaint(); } catch { record('renderer-repaint-failed'); }
+    record('renderer-recovery-complete', {rendererPid: contents.getOSProcessId()});
+  });
+  on(app, 'before-quit', () => { quitting = true; pending = false; clearTimers(); });
+  on(window, 'close', () => {
+    closing = true;
+    pending = false;
+    clearTimers();
+    // A cancelled close must not disable recovery for the remaining window.
+    queueMicrotask(() => { if (!disposed && !quitting && !window.isDestroyed()) closing = false; });
+  });
+  on(contents, 'will-prevent-unload', () => { quitting = false; closing = false; });
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    clearTimers();
+    for (const remove of listeners) remove();
+  }
+  on(window, 'closed', dispose);
+  on(contents, 'destroyed', dispose);
+  record('renderer-recovery-attached');
+  return dispose;
+}