@linxin666/dsh-remote-web-ui 0.1.13 → 0.1.15

package/src/client/settings-form.ts

@@ -1,10 +1,11 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
  * Staged form model behind the plugin settings card. A card stages what the
  * user types and writes it only when they save — the settings write is a
  * durable, revision-fenced document mutation, so staging keeps what is on
- * screen exactly what a save would store. Mirrors the official
- * ui-plugin-config card-store pattern in a self-contained slice: this
- * package must not depend on a sibling UI package.
+ * screen exactly what a save would store. Family-shared slice inlined into
+ * each plugin's client bundle; mirrors the official ui-plugin-config
+ * card-store pattern.
  */
 
 import type { SettingsScope, SettingsScopeSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
@@ -90,8 +91,17 @@ interface PlannedWrite {
   run: (() => Promise<boolean>) | undefined
 }
 
-/** A whole-number field. An empty draft clears the field; any other draft that is not a finite number blocks the save. */
-export function numberField(field: string): FieldSpec {
+/** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
+export interface NumberConstraints {
+  /** The accepted value must be a whole number. */
+  integer?: boolean
+  /** The accepted value must be at least this. */
+  min?: number
+}
+
+/** A whole- or decimal-number field. An empty draft clears the field; any other draft that is not a finite number within the constraints blocks the save. */
+export function numberField(field: string, constraints: NumberConstraints = {}): FieldSpec {
+  const { integer = false, min } = constraints
   return {
     field,
     format: value => typeof value === 'number' ? String(value) : '',
@@ -99,7 +109,10 @@ export function numberField(field: string): FieldSpec {
       const trimmed = text.trim()
       if (trimmed === '') return { kind: 'clear' }
       const parsed = Number(trimmed)
-      return Number.isFinite(parsed) ? { kind: 'set', value: parsed } : undefined
+      if (!Number.isFinite(parsed)) return undefined
+      if (integer && !Number.isInteger(parsed)) return undefined
+      if (min !== undefined && parsed < min) return undefined
+      return { kind: 'set', value: parsed }
     },
   }
 }
@@ -122,13 +135,27 @@ export function booleanField(field: string): FieldSpec {
     field,
     format: value => typeof value === 'boolean' ? String(value) : '',
     parse: (text) => {
-      if (text === 'true') return { kind: 'set', value: true }
-      if (text === 'false') return { kind: 'set', value: false }
+      const trimmed = text.trim()
+      if (trimmed === '') return { kind: 'clear' }
+      if (trimmed === 'true') return { kind: 'set', value: true }
+      if (trimmed === 'false') return { kind: 'set', value: false }
       return undefined
     },
   }
 }
 
+/** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */
+export function choiceField(field: string, choices: readonly string[]): FieldSpec {
+  return {
+    field,
+    format: value => typeof value === 'string' && choices.includes(value) ? value : '',
+    parse: (text) => {
+      if (text === '') return { kind: 'clear' }
+      return choices.includes(text) ? { kind: 'set', value: text } : undefined
+    },
+  }
+}
+
 /**
  * Stages one card's edits over one settings namespace and writes them on save.
  *
@@ -215,6 +242,9 @@ export class CardForm<T> {
     const plan = this.plan()
     const writes = plan.flatMap(item => item.run === undefined ? [] : [item.run])
     if (plan.length === 0 || this.saving || writes.length !== plan.length) return
+    // Snapshot the fields this save writes, so edits staged while it is in
+    // flight survive: only the staged keys this save actually wrote are cleared.
+    const fields = new Set(plan.map(item => item.field))
     this.saving = true
     this.failed = false
     this.publish()
@@ -222,7 +252,9 @@ export class CardForm<T> {
     for (const write of writes) {
       landed = await write() && landed
     }
-    if (landed) this.staged.clear()
+    if (landed) {
+      for (const field of fields) this.staged.delete(field)
+    }
     this.saving = false
     this.failed = !landed
     this.publish()

package/src/mobile/mux.test.ts

@@ -80,8 +80,9 @@ describe('MuxClient polling fallback', () => {
     await vi.advanceTimersByTimeAsync(400)
     expect(pollLatest).not.toHaveBeenCalled()
 
-    // Past the stall threshold the first poll runs and emits seq 0.
-    await vi.advanceTimersByTimeAsync(700) // 1100ms total -> first stall-checker tick
+    // The single tick (400 ms) crosses the 800 ms stall threshold at 1200 ms:
+    // the same tick then runs the first poll and emits seq 0.
+    await vi.advanceTimersByTimeAsync(800) // 1200ms total -> first stall crossing tick
     expect(pollLatest).toHaveBeenCalledWith('s1')
     expect(frames).toHaveLength(1)
     expect(frames[0]).toMatchObject({ type: 'session/event', sessionId: 's1' })
@@ -104,7 +105,7 @@ describe('MuxClient polling fallback', () => {
     client.start()
     client.observe('s1')
 
-    await vi.advanceTimersByTimeAsync(1100) // first poll -> 3 events
+    await vi.advanceTimersByTimeAsync(1200) // first poll -> 3 events
     expect(frames).toHaveLength(3)
 
     await vi.advanceTimersByTimeAsync(400) // second poll -> same page, nothing new
@@ -119,7 +120,7 @@ describe('MuxClient polling fallback', () => {
     client.start()
     client.observe('s1')
 
-    await vi.advanceTimersByTimeAsync(1100)
+    await vi.advanceTimersByTimeAsync(1200)
     expect(pollLatest).toHaveBeenCalled()
 
     client.observe(undefined)
@@ -136,7 +137,7 @@ describe('MuxClient polling fallback', () => {
     client.start()
     client.observe('s1')
 
-    await vi.advanceTimersByTimeAsync(1100)
+    await vi.advanceTimersByTimeAsync(1200)
     expect(pollLatest).toHaveBeenCalled()
 
     client.stop()
@@ -156,7 +157,7 @@ describe('MuxClient polling fallback', () => {
     client.observe('s1')
 
     // Stall into polling.
-    await vi.advanceTimersByTimeAsync(1100)
+    await vi.advanceTimersByTimeAsync(1200)
     expect(pollLatest).toHaveBeenCalledTimes(1)
 
     // A live mux frame proves SSE delivers again -> fallback stops.
@@ -169,4 +170,81 @@ describe('MuxClient polling fallback', () => {
     expect(live[0]).toMatchObject({ type: 'session/subscribed', sessionId: 's1' })
     client.stop()
   })
+
+  it('drives the whole lifecycle on a single scheduler tick (one interval)', async () => {
+    const { factory } = makeSources()
+    const setIntervalSpy = vi.spyOn(globalThis, 'setInterval')
+    try {
+      const pages = [pageOf([0]), pageOf([0, 1])]
+      const pollLatest = vi.fn(async (_sessionId: string) => pages.shift() ?? pageOf([]))
+      const client = new MuxClient('/m/api/events.mux', {
+        sourceFactory: factory,
+        pollLatest,
+        stallThresholdMs: 1500,
+        pollIntervalMs: 2000,
+      })
+      client.start()
+      client.observe('s1')
+
+      // Exactly one interval is ever created: the single tick scheduler.
+      expect(setIntervalSpy).toHaveBeenCalledTimes(1)
+
+      // The tick fires below the stall threshold without polling.
+      await vi.advanceTimersByTimeAsync(1000)
+      expect(pollLatest).not.toHaveBeenCalled()
+
+      // The same interval arms the fallback once silence passes the threshold
+      // (tick at 2000 crosses 1500) and runs the first poll immediately.
+      await vi.advanceTimersByTimeAsync(1100) // 2100ms total
+      expect(pollLatest).toHaveBeenCalledTimes(1)
+      expect(setIntervalSpy).toHaveBeenCalledTimes(1) // still one timer
+
+      // Subsequent polls ride the same tick at the poll cadence (2000 ms).
+      await vi.advanceTimersByTimeAsync(2000)
+      expect(pollLatest).toHaveBeenCalledTimes(2)
+      client.stop()
+    } finally {
+      setIntervalSpy.mockRestore()
+    }
+  })
+
+  it('paces polls on the tick only after the stall phase ends', async () => {
+    const { factory } = makeSources()
+    const pages = [pageOf([0]), pageOf([0, 1]), pageOf([0, 1, 2]), pageOf([0, 1, 2, 3])]
+    const pollLatest = vi.fn(async (_sessionId: string) => pages.shift() ?? pageOf([]))
+    const client = new MuxClient('/m/api/events.mux', {
+      sourceFactory: factory,
+      pollLatest,
+      stallThresholdMs: 800,
+      pollIntervalMs: 400,
+    })
+    client.start()
+    client.observe('s1')
+
+    // At 1200 ms the stall threshold is crossed on this single 400 ms tick.
+    await vi.advanceTimersByTimeAsync(1200)
+    expect(pollLatest).toHaveBeenCalledTimes(1)
+
+    // Each subsequent 400 ms tick is a poll, matching the poll cadence.
+    await vi.advanceTimersByTimeAsync(400)
+    await vi.advanceTimersByTimeAsync(400)
+    await vi.advanceTimersByTimeAsync(400)
+    expect(pollLatest).toHaveBeenCalledTimes(4)
+    client.stop()
+  })
+
+  it('observe() already in the stall window starts the single-tick poller immediately', async () => {
+    const { factory } = makeSources()
+    const pollLatest = vi.fn(async (_sessionId: string) => pageOf([0]))
+    const client = new MuxClient('/m/api/events.mux', baseOptions(pollLatest, factory))
+    client.start()
+    // Advance well past the stall threshold while nothing is observed.
+    await vi.advanceTimersByTimeAsync(2000)
+    expect(pollLatest).not.toHaveBeenCalled()
+
+    // Observing a session now is already in the stall window: poll right away.
+    client.observe('s1')
+    expect(pollLatest).toHaveBeenCalledTimes(1)
+    client.stop()
+  })
 })

package/src/mobile/mux.ts

@@ -66,6 +66,12 @@ type SessionEventFrame = Extract<MuxFrame, { type: 'session/event' }>
 
 const DEFAULT_POLL_INTERVAL_MS = 3000
 const DEFAULT_STALL_THRESHOLD_MS = 12000
+/**
+ * Stall-check granularity: the single scheduler tick runs at least this
+ * often so fallback arms within a second of the stall threshold passing,
+ * while the poll cadence itself stays {@link MuxClientOptions.pollIntervalMs}.
+ */
+const STALL_CHECK_MS = 1000
 /** Poll window: enough recent events to cover a few seconds of agent output. */
 const DEFAULT_POLL_PAGE_SIZE = 50
 
@@ -98,9 +104,11 @@ export class MuxClient {
   private sseAlive = false
   /** Per-session highest event seq already emitted, for poll dedup. */
   private readonly pollWatermark = new Map<string, number>()
-  private stallTimer: ReturnType<typeof setInterval> | undefined
-  private pollTimer: ReturnType<typeof setInterval> | undefined
+  /** Single scheduler tick: both the stall check and the poll cadence ride this one interval. */
+  private tickTimer: ReturnType<typeof setInterval> | undefined
   private polling = false
+  /** Epoch ms of the next due poll while polling (kept on the same tick timer). */
+  private nextPollAt = 0
 
   /**
    * @param url - the mobile events endpoint (browser-relative).
@@ -120,16 +128,17 @@ export class MuxClient {
     this.stopped = false
     this.lastDataAt = this.now()
     if (this.source === undefined) this.connect()
-    this.startStallChecker()
+    this.startTick()
   }
 
   /** Close for good. */
   stop(): void {
     this.stopped = true
-    this.stopStallChecker()
+    this.stopTick()
     this.stopPolling()
     this.closeSource()
     this.observeSessionId = undefined
+    this.nextPollAt = 0
   }
 
   /** Subscribe to validated frames; returns an unsubscribe function. */
@@ -176,40 +185,52 @@ export class MuxClient {
     }
   }
 
-  private startStallChecker(): void {
-    this.stopStallChecker()
-    this.stallTimer = setInterval(() => {
-      if (this.stopped) return
-      if (this.observeSessionId === undefined) return
-      if (this.polling) return
-      // A live SSE channel only goes silent while the agent idles; never
-      // poll against it. Fallback arms again only via onerror or a stream
-      // that has never delivered.
-      if (this.sseAlive) return
-      if ((this.now() - this.lastDataAt) > this.stallThresholdMs) this.startPolling()
-    }, 1000)
+  /**
+   * The single scheduler tick is the only interval this client owns. One
+   * timer (at the finer of the stall-check and poll cadences) both arms the
+   * polling fallback once the stall threshold passes and drives each poll at
+   * {@link MuxClientOptions.pollIntervalMs} — one timer instead of two.
+   */
+  private startTick(): void {
+    if (this.tickTimer !== undefined) return
+    const cadence = Math.min(this.pollIntervalMs, STALL_CHECK_MS)
+    this.tickTimer = setInterval(() => { this.tick() }, cadence)
+  }
+
+  private stopTick(): void {
+    if (this.tickTimer !== undefined) {
+      clearInterval(this.tickTimer)
+      this.tickTimer = undefined
+    }
   }
 
-  private stopStallChecker(): void {
-    if (this.stallTimer !== undefined) {
-      clearInterval(this.stallTimer)
-      this.stallTimer = undefined
+  private tick(): void {
+    if (this.stopped) return
+    if (this.observeSessionId === undefined) return
+    if (this.polling) {
+      // The stall phase has ended; the same tick now paces the polls.
+      if (this.now() >= this.nextPollAt) {
+        this.nextPollAt = this.now() + this.pollIntervalMs
+        void this.pollTick()
+      }
+      return
     }
+    // A live SSE channel only goes silent while the agent idles; never poll
+    // against it. Fallback arms again only via onerror or a stream that has
+    // never delivered.
+    if (this.sseAlive) return
+    if ((this.now() - this.lastDataAt) > this.stallThresholdMs) this.startPolling()
   }
 
   private startPolling(): void {
     if (this.polling || this.stopped) return
     this.polling = true
+    this.nextPollAt = this.now() + this.pollIntervalMs
     void this.pollTick()
-    this.pollTimer = setInterval(() => { void this.pollTick() }, this.pollIntervalMs)
   }
 
   private stopPolling(): void {
     this.polling = false
-    if (this.pollTimer !== undefined) {
-      clearInterval(this.pollTimer)
-      this.pollTimer = undefined
-    }
   }
 
   /**

package/src/mobile-api.ts

@@ -49,6 +49,8 @@ const MOBILE_PREFERENCES_METHOD = 'mobile.preferences'
 
 /** One session.list page (thin phones load incrementally). */
 const SESSION_PAGE_SIZE = 20
+/** SSE keep-alive ping cadence for the live mux stream (single connection). */
+const DEFAULT_EVENTS_HEARTBEAT_MS = 15_000
 
 /** Encode one list position as an opaque continuation cursor. */
 function sessionListCursor(updatedAt: number, sessionId: string): string {
@@ -78,6 +80,8 @@ export interface MobileApiDeps {
   apiProxy: ApiProxy
   /** The resolved mobile composer preference (live per request). */
   mobileEnterToSend: () => boolean
+  /** SSE keep-alive ping cadence for the mux stream (default 15000 ms; test seam). */
+  eventsHeartbeatMs?: number
 }
 
 /** Mobile API route paths. */
@@ -97,6 +101,7 @@ const MOBILE_API_METHOD_PREFIX = `${MOBILE_API_PREFIX}/`
  */
 export function makeMobileApiRoutes(deps: MobileApiDeps): WebRoute[] {
   const { service, apiProxy, mobileEnterToSend } = deps
+  const eventsHeartbeatMs = deps.eventsHeartbeatMs ?? DEFAULT_EVENTS_HEARTBEAT_MS
 
   /** The phone gate: a live paired-device cookie, or nothing else proceeds. */
   const gateOk = (req: IncomingMessage): boolean => {
@@ -190,7 +195,7 @@ export function makeMobileApiRoutes(deps: MobileApiDeps): WebRoute[] {
       } catch {
         // The write failed; the close handler tears the subscription down.
       }
-    }, 15_000)
+    }, eventsHeartbeatMs)
     const onClose = (): void => {
       if (closed) return
       closed = true

package/src/routes.ts

@@ -10,6 +10,7 @@
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import { z, type ZodType } from 'zod'
 import { UnknownLanAddressError, type PairingService, type PairingSnapshot } from './pairing.ts'
 import { isLoopbackClient, readCookie } from './gate.ts'
 
@@ -91,6 +92,34 @@ export const PAIR_PATHS = {
   events: '/api/pair/events',
 } as const
 
+/**
+ * /api/pair request payload contracts. Each POST endpoint validates its body
+ * against one of these instead of reaching into a hand-parsed object: the
+ * control-plane endpoints that carry no meaningful payload use the permissive
+ * pairActionPayloadSchema so their smoke calls keep working unchanged, while
+ * issue/accept enforce their optional/required fields. Unknown (extra) keys
+ * are tolerated exactly as the previous manual reads ignored them.
+ */
+export const issuePayloadSchema = z.object({
+  workspaceId: z.string().min(1).optional(),
+  address: z.string().min(1).optional(),
+})
+export const acceptPayloadSchema = z.object({
+  token: z.string().default(''),
+})
+export const pairActionPayloadSchema = z.object({}).passthrough()
+
+/**
+ * Parse a pair request body through schema. A missing/empty or non-object
+ * body is treated as an empty object (the same way the previous manual reads
+ * yielded absent fields), and a value that fails the schema returns
+ * `undefined` so the caller can answer with the existing error shape.
+ */
+function parsePairPayload<T>(schema: ZodType<T>, body: Record<string, unknown> | undefined): T | undefined {
+  const result = schema.safeParse(body ?? {})
+  return result.success ? result.data : undefined
+}
+
 /** One JSON response. */
 function writeJson(res: ServerResponse, status: number, body: unknown): void {
   const payload = JSON.stringify(body)
@@ -225,12 +254,12 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
       return
     }
     const body = await readJsonBody(req)
-    const workspaceId = body === undefined || typeof body.workspaceId !== 'string' || body.workspaceId === ''
-      ? undefined
-      : body.workspaceId
-    const address = body === undefined || typeof body.address !== 'string' || body.address === ''
-      ? undefined
-      : body.address
+    const payload = parsePairPayload(issuePayloadSchema, body)
+    if (payload === undefined) {
+      writeJson(res, 400, { ok: false, code: 'bad-payload' })
+      return
+    }
+    const { workspaceId, address } = payload
     try {
       const { token, expiresAt } = service.issue(workspaceId, address)
       // The default base is the public (tunneled) URL when configured — a
@@ -273,8 +302,12 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
       return
     }
     const body = await readJsonBody(req)
-    const token = typeof body?.token === 'string' ? body.token : ''
-    const result = service.accept(token)
+    const payload = parsePairPayload(acceptPayloadSchema, body)
+    if (payload === undefined) {
+      writeJson(res, 400, { ok: false, code: 'bad-payload' })
+      return
+    }
+    const result = service.accept(payload.token)
     if (!result.ok) {
       writeJson(res, result.code === 'used' ? 409 : 404, { ok: false, code: result.code })
       return
@@ -294,7 +327,11 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
       writeJson(res, 403, { ok: false, code: 'forbidden' })
       return
     }
-    await readJsonBody(req)
+    const body = await readJsonBody(req)
+    if (parsePairPayload(pairActionPayloadSchema, body) === undefined) {
+      writeJson(res, 400, { ok: false, code: 'bad-payload' })
+      return
+    }
     service.stop()
     writeJson(res, 200, { ok: true })
   }
@@ -305,7 +342,11 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
       writeJson(res, 403, { ok: false, code: 'forbidden' })
       return
     }
-    await readJsonBody(req)
+    const body = await readJsonBody(req)
+    if (parsePairPayload(pairActionPayloadSchema, body) === undefined) {
+      writeJson(res, 400, { ok: false, code: 'bad-payload' })
+      return
+    }
     const deviceId = readCookie(req.headers.cookie, service.config.cookieName)
     if (deviceId === undefined || !service.heartbeat(deviceId)) {
       writeJson(res, 401, { ok: false, code: 'unpaired' })

package/src/update.ts

@@ -383,53 +383,143 @@ export interface UpdateRunDeps {
   spawnImpl?: typeof spawn
   /** Hard timeout; the child is killed on expiry. */
   timeoutMs?: number
+  /** Platform override (defaults to process.platform; test seam). */
+  platform?: NodeJS.Platform
 }
 
 /** Cap on captured pnpm output (keeps error payloads bounded). */
 const OUTPUT_CAP = 16 * 1024
 
 /**
- * Run the update: `pnpm update <packages>` inside the profile directory.
+ * Windows cmd command-not-found stderr. With shell:true a missing shim
+ * exits with code 1 (cmd cannot report ENOENT), so the fallback chain
+ * detects this message instead of the spawn error event.
+ */
+const WIN_CMD_MISSING_RE = /not recognized as an internal or external command/i
+
+/**
+ * Run the update inside the profile directory. Tries pnpm first, falls back
+ * to corepack and then npx when the previous command is missing (ENOENT);
+ * all candidates share one hard timeout and keep accumulating output.
  * @param deps - profile dir, package list, and spawn/timeout seams.
  * @returns the outcome with captured output.
  */
 export function runUpdate(deps: UpdateRunDeps): Promise<UpdateRunResult> {
   return new Promise((resolve) => {
-    const child = (deps.spawnImpl ?? spawn)('pnpm', ['update', ...deps.packages], {
+    const spawnImpl = deps.spawnImpl ?? spawn
+    const packages = deps.packages
+    const platform = deps.platform ?? process.platform
+    // Windows ships pnpm/corepack/npx as .cmd shims; Node's spawn cannot
+    // start .cmd files directly (ENOENT even when installed), so route
+    // them through cmd.exe there. POSIX spawns stay shell-free.
+    const spawnOptions: Record<string, unknown> = {
       cwd: deps.profileDir,
       stdio: ['ignore', 'pipe', 'pipe'],
-    })
+      ...(platform === 'win32' ? { shell: true } : {}),
+    }
+    // Ordered fallback chain: each is tried only when the previous one is
+    // missing on PATH (ENOENT on the spawn error event, never on close).
+    const candidates: ReadonlyArray<{ command: string; args: string[] }> = [
+      { command: 'pnpm', args: ['update', ...packages] },
+      { command: 'corepack', args: ['pnpm', 'update', ...packages] },
+      { command: 'npx', args: ['--yes', 'pnpm', 'update', ...packages] },
+    ]
+    // `output` accumulates across candidates for UI display; `currentOutput`
+    // is reset per candidate and carries only that candidate's own diagnostics
+    // (its tail is subject to OUTPUT_CAP). The win32 missing-command test must
+    // run against `currentOutput` so a previous candidate's 'not recognized'
+    // stderr cannot misclassify a real failure in the next one.
     let output = ''
+    let currentOutput = ''
     const append = (chunk: Buffer): void => {
       output += chunk.toString('utf8')
       if (output.length > OUTPUT_CAP) output = output.slice(output.length - OUTPUT_CAP)
+      currentOutput += chunk.toString('utf8')
+      if (currentOutput.length > OUTPUT_CAP) currentOutput = currentOutput.slice(currentOutput.length - OUTPUT_CAP)
+    }
+    let currentChild: ReturnType<typeof spawnImpl> | undefined
+    // Terminal guard: once a result is produced the promise is settled and no
+    // further candidate is started (a killed child's late close must not
+    // respawn anything after a timeout resolution).
+    let finished = false
+    const finish = (result: UpdateRunResult): void => {
+      if (finished) return
+      finished = true
+      clearTimeout(timer)
+      resolve(result)
     }
-    child.stdout?.on('data', append)
-    child.stderr?.on('data', append)
     const timer = setTimeout(() => {
-      child.kill('SIGTERM')
-      resolve({ ok: false, exitCode: null, output, error: 'update timed out; install process killed', errorCode: 'timeout' })
+      if (finished) return
+      if (platform === 'win32') {
+        // cmd.exe under shell:true only kills the shell wrapper; kill the whole
+        // process tree best-effort so pnpm/npx do not keep running.
+        const pid = (currentChild as { pid?: number } | undefined)?.pid
+        if (pid !== undefined && pid > 0) {
+          try {
+            spawnImpl('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore' })
+          } catch {
+            // Best-effort kill; fall through to the timeout result.
+          }
+        }
+      } else {
+        currentChild?.kill('SIGTERM')
+      }
+      finish({ ok: false, exitCode: null, output, error: 'update timed out; install process killed', errorCode: 'timeout' })
     }, deps.timeoutMs ?? 10 * 60_000)
-    child.on('error', (error: Error) => {
-      clearTimeout(timer)
-      const missing = (error as NodeJS.ErrnoException).code === 'ENOENT'
-      resolve({
-        ok: false,
-        exitCode: null,
-        output,
-        error: missing ? 'pnpm not found on PATH' : error.message,
-        errorCode: missing ? 'pnpm-missing' : undefined,
+    const runCandidate = (index: number): void => {
+      if (finished) return
+      if (index >= candidates.length) {
+        finish({
+          ok: false,
+          exitCode: null,
+          output,
+          error: 'pnpm not found on PATH (tried pnpm, corepack, npx); install pnpm and restart the app',
+          errorCode: 'pnpm-missing',
+        })
+        return
+      }
+      const candidate = candidates[index]
+      currentOutput = ''
+      const child = spawnImpl(candidate.command, candidate.args, spawnOptions)
+      currentChild = child
+      let settled = false
+      const once = (fn: () => void): void => {
+        if (settled) return
+        settled = true
+        fn()
+      }
+      child.stdout?.on('data', append)
+      child.stderr?.on('data', append)
+      child.on('error', (error: Error) => {
+        once(() => {
+          if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            // Command missing: try the next candidate in the chain.
+            runCandidate(index + 1)
+          } else {
+            finish({ ok: false, exitCode: null, output, error: error.message, errorCode: undefined })
+          }
+        })
       })
-    })
-    child.on('close', (code) => {
-      clearTimeout(timer)
-      resolve({
-        ok: code === 0,
-        exitCode: code,
-        output,
-        error: code === 0 ? undefined : 'pnpm exited with code ' + String(code),
-        ...(code === 0 ? {} : { errorCode: 'pnpm-failed' as const }),
+      child.on('close', (code: number | null) => {
+        if (settled || finished) return
+        // Windows + shell: a missing command reports exit 1 with
+        // 'not recognized' instead of ENOENT — keep the chain going. Checked
+        // against this candidate's own output so a prior fallback's stderr
+        // cannot misclassify a real failure here.
+        if (platform === 'win32' && code !== 0 && WIN_CMD_MISSING_RE.test(currentOutput)) {
+          runCandidate(index + 1)
+          return
+        }
+        settled = true
+        finish({
+          ok: code === 0,
+          exitCode: code,
+          output,
+          error: code === 0 ? undefined : 'pnpm exited with code ' + String(code),
+          ...(code === 0 ? {} : { errorCode: 'pnpm-failed' as const }),
+        })
       })
-    })
+    }
+    runCandidate(0)
   })
 }