martty 0.2.34 → 0.2.35

package/lib/acp-session-config.js

@@ -64,6 +64,7 @@ class AcpSessionConfigService extends Service {
 /** Install the `ctx.acpSessionConfig` standard ACP state service. */
 export function installAcpSessionConfig(ctx) {
   let sessionId
+  let sessionGeneration = 0
   let selectionKnown = false
   const optionsBySession = new Map()
   let requestTui
@@ -142,6 +143,15 @@ export function installAcpSessionConfig(ctx) {
 
   function observeClient(message) {
     if (!isObject(message) || message.id === undefined || typeof message.method !== 'string') return
+    if (message.method === 'initialize') {
+      sessionGeneration++
+      pending.clear()
+      sessionId = undefined
+      selectionKnown = false
+      optionsBySession.clear()
+      publish()
+      return
+    }
     if (SETUP_METHODS.has(message.method)) {
       const requested = message.method !== 'session/new'
         ? readString(message.params, 'sessionId', 'session_id')
@@ -209,12 +219,15 @@ export function installAcpSessionConfig(ctx) {
       throw new Error(`acpSessionConfig.set: option "${id}" is not advertised by the current Session`)
     }
     validateValue(option, value)
+    const requestedSession = targetSessionId
+    const requestedGeneration = sessionGeneration
     const result = await requestTui(CORDIS_METHODS.sessionConfigSet, {
       protocol: CORDIS_PROTOCOL,
       sessionId: targetSessionId,
       configId: id,
       value,
     })
+    assertSession(requestedSession, requestedGeneration)
     if (!isObject(result)) {
       throw new Error('acpSessionConfig.set: native ACP client returned an invalid response')
     }
@@ -227,6 +240,12 @@ export function installAcpSessionConfig(ctx) {
     return setForSession(sessionId, id, value)
   }
 
+  function assertSession(expectedSession, expectedGeneration) {
+    if (sessionGeneration !== expectedGeneration || !optionsBySession.has(expectedSession)) {
+      throw new Error('acpSessionConfig: Session changed while configuring options')
+    }
+  }
+
   function transaction(selector) {
     const transactionSessionId = sessionId
     if (transactionSessionId === undefined) {
@@ -234,6 +253,8 @@ export function installAcpSessionConfig(ctx) {
     }
     const transactionOptions = optionsBySession.get(transactionSessionId) ?? []
     const option = resolveTransactionOption(selector, transactionOptions)
+    const originalSession = transactionSessionId
+    const originalGeneration = sessionGeneration
     const original = cloneJson(option.currentValue ?? option.current_value)
     if (original === undefined) {
       throw new Error(
@@ -248,6 +269,7 @@ export function installAcpSessionConfig(ctx) {
     let settled = false
 
     const write = async (value) => {
+      assertSession(originalSession, originalGeneration)
       const result = await setForSession(transactionSessionId, option.id, value)
       applied = cloneJson(value)
       return result
@@ -269,6 +291,7 @@ export function installAcpSessionConfig(ctx) {
       if (finalizing) return finalizing
       desired = cloneJson(value)
       const settle = async () => {
+        assertSession(originalSession, originalGeneration)
         if (!Object.is(applied, desired)) await write(desired)
         settled = true
         return listFor(transactionSessionId)

package/lib/acp-session-plan.js

@@ -101,7 +101,16 @@ export function installAcpSessionPlan(ctx) {
   }
 
   function observeClient(message) {
-    if (!isObject(message) || message.id === undefined || !SETUP_METHODS.has(message.method)) return
+    if (!isObject(message) || message.id === undefined) return
+    if (message.method === 'initialize') {
+      pending.clear()
+      plansBySession.clear()
+      sessionId = undefined
+      selectionKnown = false
+      publish()
+      return
+    }
+    if (!SETUP_METHODS.has(message.method)) return
     pending.set(message.id, {
       sessionId: message.method !== 'session/new'
         ? readString(message.params, 'sessionId', 'session_id')

package/lib/acp-session-stats.js

@@ -114,6 +114,17 @@ export function installAcpSessionStats(ctx, options = {}) {
 
   function observeClient(message) {
     if (!object(message) || message.id === undefined || typeof message.method !== 'string') return
+    if (message.method === 'initialize') {
+      pendingSetup.clear()
+      pendingPrompts.clear()
+      activePrompts.clear()
+      toolStarts.clear()
+      values.clear()
+      sessionId = undefined
+      selectionKnown = false
+      publish()
+      return
+    }
     if (SETUP_METHODS.has(message.method)) {
       pendingSetup.set(message.id, {
         sessionId: message.method !== 'session/new'

package/lib/acp-session-status.js

@@ -2,7 +2,7 @@
  * Standard-ACP-backed run-state projection for the Client tree.
  *
  * Folds the non-statistics facts `/status` needs — connection, server,
- * authenticate state, session binding, model, effort, permission, plan,
+ * authenticate state, session binding/use, model, effort, permission, plan,
  * agent preset, and the running/idle state — from messages the mux already
  * observes. Statistics stay in `acpSessionStats`; this service never
  * counts tokens or timings, so there is exactly one stats source.
@@ -43,7 +43,7 @@ class AcpSessionStatusService extends Service {
 function zeroSession(sessionId, bound = sessionId !== undefined) {
   return {
     state: 'idle',
-    session: { sessionId, bound },
+    session: { sessionId, bound, started: false },
     model: undefined,
     effort: undefined,
     permission: undefined,
@@ -68,6 +68,8 @@ export function installAcpSessionStatus(ctx, options = {}) {
   let server
   const auth = { status: undefined, method: undefined }
   let initializeId
+  let authMethods = []
+  const pendingRequests = new Set()
   const pendingAuthenticate = new Set()
   const pendingSetup = new Map()
   const pendingPrompts = new Map()
@@ -131,22 +133,43 @@ export function installAcpSessionStatus(ctx, options = {}) {
   function observeClient(message) {
     if (!object(message) || typeof message.method !== 'string') return
     if (message.method === 'initialize' && message.id !== undefined) {
+      pendingRequests.clear()
+      sessions.clear()
+      Object.assign(fallback, zeroSession(undefined, false))
+      delete fallback.error
+      sessionId = undefined
+      selectionKnown = false
+      connection = 'connecting'
+      server = undefined
+      auth.status = undefined
+      auth.method = undefined
+      delete auth.message
+      authMethods = []
+      pendingAuthenticate.clear()
+      pendingSetup.clear()
+      pendingPrompts.clear()
       initializeId = message.id
+      publish()
       return
     }
+    if (message.id !== undefined) pendingRequests.add(message.id)
     if (message.method === 'authenticate' && message.id !== undefined) {
       pendingAuthenticate.add(message.id)
+      const methodId = readString(message.params, 'methodId')
+      const method = authMethods.find((candidate) => candidate?.id === methodId)
+      if (methodId !== undefined) auth.method = readString(method, 'name', 'label') ?? methodId
+      delete auth.message
       auth.status = 'signing in'
       publish()
       return
     }
     if (SETUP_METHODS.has(message.method) && message.id !== undefined) {
-      pendingSetup.set(
-        message.id,
-        message.method !== 'session/new'
+      pendingSetup.set(message.id, {
+        sessionId: message.method !== 'session/new'
           ? readString(message.params, 'sessionId', 'session_id')
           : undefined,
-      )
+        started: message.method !== 'session/new',
+      })
       return
     }
     if (message.method === 'session/prompt' && message.id !== undefined) {
@@ -155,6 +178,7 @@ export function installAcpSessionStatus(ctx, options = {}) {
       if (!selectionKnown && sessionId === undefined) sessionId = promptSessionId
       pendingPrompts.set(message.id, promptSessionId)
       const value = stateFor(promptSessionId)
+      value.session.started = true
       if (value.state === 'idle') {
         value.state = 'starting'
         publishIf(promptSessionId)
@@ -166,42 +190,61 @@ export function installAcpSessionStatus(ctx, options = {}) {
     if (!object(message)) return
     if (message.id !== undefined && message.id === initializeId) {
       initializeId = undefined
-      connection = 'attached'
+      connection = message.error === undefined ? 'attached' : 'failed'
+      fallback.error = message.error?.message
       const result = object(message.result) ? message.result : undefined
       server = readString(result?.agentInfo, 'name')
       const methods = Array.isArray(result?.authMethods) ? result.authMethods : []
-      const method = methods.find((candidate) => object(candidate)
-        && typeof candidate.id === 'string' && candidate.id.length > 0)
-      if (method !== undefined && auth.status === undefined) {
-        auth.method = readString(method, 'name', 'label') ?? method.id
-      }
+      authMethods = methods
+      // initialize advertises choices, not the credential used by this process.
       publish()
       return
     }
+    // Unknown replies can belong to a replaced Agent. Never let them restore
+    // its authentication or run state in the new connection.
+    if (response(message) && !pendingRequests.delete(message.id)) return
     if (message.id !== undefined && pendingAuthenticate.has(message.id)) {
       pendingAuthenticate.delete(message.id)
       if (message.error === undefined) {
         auth.status = 'configured'
-      } else if (isAuthRequired(message.error)) {
-        auth.status = 'needs sign-in'
+        delete auth.message
       } else {
-        auth.status = undefined
+        auth.status = 'sign-in failed'
+        auth.message = readString(message.error?.data, 'details', 'message')
+          ?? readString(message.error, 'message') ?? 'Authentication failed'
       }
       publish()
       return
     }
     if (message.id !== undefined && pendingSetup.has(message.id)) {
-      const requested = pendingSetup.get(message.id)
+      const setup = pendingSetup.get(message.id)
       pendingSetup.delete(message.id)
       if (message.error !== undefined) {
         if (isAuthRequired(message.error)) auth.status = 'needs sign-in'
-        if (requested !== undefined) {
-          stateFor(requested, false).session.bound = false
+        else {
+          connection = 'failed'
+          const value = stateFor(setup.sessionId, false)
+          value.error = readString(message.error, 'message') ?? 'Session setup failed'
+          value.state = 'idle'
+          value.model = undefined
+          value.effort = undefined
         }
-        if (!selectionKnown) sessionId = requested
+        stateFor(setup.sessionId, false).session = {
+          sessionId: setup.sessionId, bound: false, started: false,
+        }
+        if (!selectionKnown) sessionId = setup.sessionId
       } else {
-        const bound = readString(message.result, 'sessionId', 'session_id') ?? requested
-        if (bound !== undefined) stateFor(bound).session = { sessionId: bound, bound: true }
+        connection = 'attached'
+        delete fallback.error
+        const bound = readString(message.result, 'sessionId', 'session_id') ?? setup.sessionId
+        if (bound !== undefined) {
+          stateFor(bound).session = { sessionId: bound, bound: true, started: setup.started }
+          delete stateFor(bound).error
+          if (authMethods.length > 0) {
+            auth.status = 'configured'
+            delete auth.message
+          }
+        }
         if (!selectionKnown) sessionId = bound
       }
       publish()
@@ -304,14 +347,16 @@ export function installAcpSessionStatus(ctx, options = {}) {
       ? snapshot.sessionId
       : sessionId
     const value = stateFor(configSessionId)
-    value.model = optionValue(snapshot.options, 'model') ?? value.model
-    value.effort = optionValue(snapshot.options, 'effort') ?? value.effort
+    if (!selectionKnown && sessionId === undefined) sessionId = configSessionId
+    value.model = optionValue(snapshot.options, 'model', 'model')
+    value.effort = optionValue(snapshot.options, 'thought_level', 'effort')
     publishIf(configSessionId)
   }
 
-  function optionValue(options, id) {
+  function optionValue(options, category, id) {
     if (!Array.isArray(options)) return undefined
-    const option = options.find((candidate) => candidate?.id === id)
+    const option = options.find((candidate) => candidate?.category === category)
+      ?? options.find((candidate) => candidate?.id === id)
     if (option === undefined) return undefined
     const raw = option.currentValue ?? option.current_value
     return typeof raw === 'string' ? raw : undefined

package/lib/agent.js

@@ -6,11 +6,12 @@ import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { selectedHarness } from './harnesses.js'
+import { tokenizeCommandArgs } from './command-args.js'
 
 /**
  * Resolve the ACP package and TUI's internal Creator overlay bundle.
  * @param {string | URL} [anchor]
- * @returns {{ command: string, args: string[] }}
+ * @returns {{ command: string, args: string[], env?: Record<string, string> }}
  */
 export function resolveDependencyStack(anchor = import.meta.url) {
   const req = createRequire(anchor)
@@ -31,20 +32,39 @@ export function resolveDependencyStack(anchor = import.meta.url) {
 
 /**
  * Resolve the standalone ACP command without affecting the profile path.
+ * `forcedHarness` is an internal product initialization value, not a CLI
+ * argument; null/omitted means that no product Harness is forced.
  * @param {string | URL} [anchor]
- * @param {{ settingsPath?: string }} [options]
+ * @param {{ settingsPath?: string, forcedHarness?: { id: string, label: string, command: string, args?: string[] } | null }} [options]
  * @returns {{ command: string, args: string[] }}
  */
 export function resolveStackedAgent(anchor = import.meta.url, options = {}) {
   const envCmd = process.env.DSH_TUI_AGENT
   if (typeof envCmd === 'string' && envCmd.trim().length > 0) {
-    const tokens = envCmd.trim().split(/\s+/)
+    const tokens = tokenizeCommandArgs(envCmd)
+    if (!tokens[0]) throw new Error('DSH_TUI_AGENT needs a non-empty command')
     return { command: tokens[0], args: tokens.slice(1) }
   }
+  if (options.forcedHarness !== undefined && options.forcedHarness !== null) {
+    const configured = options.forcedHarness
+    if (typeof configured !== 'object' || Array.isArray(configured)
+      || typeof configured.command !== 'string' || configured.command.trim().length === 0) {
+      throw new Error('forcedHarness must declare a non-empty command')
+    }
+    return {
+      command: configured.command,
+      args: Array.isArray(configured.args) ? configured.args.map(String) : [],
+      ...(configured.env !== undefined ? { env: { ...configured.env } } : {}),
+    }
+  }
   if (typeof options.settingsPath === 'string') {
     const selected = selectedHarness(options.settingsPath)
     if (selected !== undefined) {
-      return { command: selected.command, args: selected.args }
+      return {
+        command: selected.command,
+        args: selected.args,
+        ...(selected.env !== undefined ? { env: { ...selected.env } } : {}),
+      }
     }
   }
   try {

package/lib/boot.js

@@ -67,6 +67,8 @@ import { installTuiLocalPlugins } from './tui-local-plugins.js'
  * @param {{ stdin: import('node:stream').Writable, stdout: import('node:stream').Readable, child?: import('node:child_process').ChildProcess }} [options.stream]
  * @param {{ stdin: number | 'inherit', stdout: number | 'inherit' }} [options.tty]
  * @param {string} [options.settingsPath]
+ * Internal product-only forced Harness; null means no pinned Harness.
+ * @param {{ id: string, label: string, command: string, args?: string[] } | null} [options.forcedHarness]
  * @param {string} [options.artifactRoot]
  * @param {Array<{ id: string, label: string, command: string, args?: string[], source?: string }>} [options.harnessDefaults]
  * @param {string} [options.harnessPathValue]
@@ -75,10 +77,16 @@ import { installTuiLocalPlugins } from './tui-local-plugins.js'
 export async function bootClient(options = {}) {
   const { Context } = await import('@deepseek-ai/cordis')
   const ctx = new Context()
+  const settingsPath = options.settingsPath ?? uiSettingsPath(options.extraArgs ?? [])
+  const forcedHarness = options.forcedHarness ?? null
   const acpConfig = options.stream !== undefined
     ? { stream: options.stream }
-    : { agent: options.agent ?? resolveStackedAgent() }
-  const settingsPath = options.settingsPath ?? uiSettingsPath(options.extraArgs ?? [])
+    : {
+        agent: options.agent ?? resolveStackedAgent(import.meta.url, {
+          settingsPath,
+          forcedHarness,
+        }),
+      }
   if (options.settingsPath === undefined) {
     migrateLegacyUiSettings(settingsPath, legacyUiSettingsPaths(options.extraArgs ?? []))
   }
@@ -96,9 +104,16 @@ export async function bootClient(options = {}) {
       harnessDefaults = []
     }
   }
+  if (forcedHarness !== null) {
+    const forcedEntry = { ...forcedHarness, source: 'forced' }
+    const forcedIndex = harnessDefaults.findIndex(({ id }) => id === forcedHarness.id)
+    if (forcedIndex === -1) harnessDefaults = [forcedEntry, ...harnessDefaults]
+    else harnessDefaults = harnessDefaults.map((entry, index) => index === forcedIndex ? forcedEntry : entry)
+  }
   const harnessConfig = {
     settingsPath,
     defaults: harnessDefaults,
+    forcedHarness,
     pathValue: options.harnessPathValue,
     hostOwned: options.stream !== undefined,
   }
@@ -292,10 +307,12 @@ export function migrateLegacyUiSettings(settingsPath, legacyPaths) {
 
 /**
  * Parse `--agent` / `--agent-arg` from argv. Remaining flags pass through to Rust.
+ * `forcedHarness` is an internal product initialization value, not a CLI
+ * argument; null/omitted means that no product Harness is forced.
  * `--agent` is also forwarded via {@link painterArgs} so Terminal Auth can
  * re-exec the same command.
  * @param {string[]} argv
- * @param {{ settingsPath?: string }} [options]
+ * @param {{ settingsPath?: string, forcedHarness?: { id: string, label: string, command: string, args?: string[] } | null }} [options]
  * @returns {{ agent: { command: string, args: string[] }, rustArgs: string[] }}
  */
 export function parseClientArgv(argv, options = {}) {
@@ -305,12 +322,16 @@ export function parseClientArgv(argv, options = {}) {
   for (let i = 0; i < argv.length; i += 1) {
     const token = argv[i]
     if (token === '--agent') {
+      if (!argv[i + 1]?.trim() || argv[i + 1].startsWith('--')) {
+        throw Object.assign(new Error('--agent needs a value'), { exitCode: 2 })
+      }
       command = argv[i + 1]
       i += 1
       continue
     }
     if (token === '--agent-arg') {
-      args.push(argv[i + 1] ?? '')
+      if (argv[i + 1] === undefined) throw Object.assign(new Error('--agent-arg needs a value'), { exitCode: 2 })
+      args.push(argv[i + 1])
       i += 1
       continue
     }
@@ -319,7 +340,10 @@ export function parseClientArgv(argv, options = {}) {
   if (command === undefined) {
     const settingsPath = options.settingsPath ?? uiSettingsPath(rustArgs)
     return {
-      agent: resolveStackedAgent(import.meta.url, { settingsPath }),
+      agent: resolveStackedAgent(import.meta.url, {
+        settingsPath,
+        forcedHarness: options.forcedHarness,
+      }),
       rustArgs,
     }
   }

package/lib/command-args.js

@@ -0,0 +1,28 @@
+/** Split an argv string without shell execution, expansion, or substitution. */
+export function tokenizeCommandArgs(value) {
+  const tokens = []
+  let token = '', quote
+  let escaped = false, started = false
+  for (const char of String(value ?? '')) {
+    if (escaped) {
+      if (quote === '"' && !['\\', '"', '$', '`', '\n'].includes(char)) token += '\\'
+      token += char
+      escaped = false
+    } else if (char === '\\' && quote !== "'") {
+      escaped = true; started = true
+    } else if (quote !== undefined) {
+      if (char === quote) quote = undefined
+      else token += char
+    } else if (char === '"' || char === "'") {
+      quote = char; started = true
+    } else if (/\s/.test(char)) {
+      if (started) { tokens.push(token); token = ''; started = false }
+    } else {
+      token += char; started = true
+    }
+  }
+  if (escaped) token += '\\'
+  if (quote !== undefined) throw Object.assign(new Error(`Unclosed ${quote} quote in command`), { exitCode: 2 })
+  if (started) tokens.push(token)
+  return tokens
+}

package/lib/download.js

@@ -0,0 +1,165 @@
+import { DownloaderHelper } from 'node-downloader-helper'
+import { lstatSync, statSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import path from 'node:path'
+
+function httpUrl(value, base) {
+  const parsed = new URL(value, base)
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error('download requires an HTTP or HTTPS URL')
+  }
+  return parsed.href
+}
+
+// Compatibility boundary for the pinned SDK 2.1.11: its response callback can
+// throw outside start()'s promise, and resolves relative redirects against the
+// initial URL. Wrap that callback, not the transport or global HTTP modules.
+// Re-run the redirect regressions when upgrading the SDK's private hook.
+class ArchiveDownloader extends DownloaderHelper {
+  __downloadRequest(resolve, reject) {
+    const requestUrl = this.requestURL
+    const request = super.__downloadRequest(resolve, reject)
+    const [onResponse] = request.listeners('response')
+    request.removeListener('response', onResponse)
+    request.once('response', (response) => {
+      try {
+        if (response.statusCode >= 300 && response.statusCode < 400) {
+          if (![301, 302, 303, 307, 308].includes(response.statusCode) || !response.headers.location) {
+            throw new Error(`download returned HTTP ${response.statusCode} without a usable redirect`)
+          }
+          response.headers.location = httpUrl(response.headers.location, requestUrl)
+        }
+        onResponse.call(request, response)
+      } catch (error) {
+        response.destroy()
+        request.destroy()
+        this.emit('error', error)
+        reject(error)
+      }
+    })
+    return request
+  }
+}
+
+/** Download into a caller-owned staging directory, without a total-time limit. */
+export async function downloadFile(url, destination, options = {}) {
+  const label = options.label ?? 'binary download'
+  const cancelled = () => Object.assign(new Error(`${label} cancelled`), { name: 'AbortError' })
+  if (options.signal?.aborted) throw cancelled()
+  url = httpUrl(url)
+  const filePath = path.resolve(destination)
+  // This adapter owns only a new staging file, never a pre-existing user file.
+  try {
+    lstatSync(filePath)
+    throw new Error(`download destination already exists: ${filePath}`)
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+  }
+  const connectTimeoutMs = options.connectTimeoutMs ?? 30_000
+  const idleTimeoutMs = options.idleTimeoutMs ?? 60_000
+  const maxBytes = options.maxBytes ?? 512 * 1024 * 1024
+  const request = new AbortController()
+  const downloader = new ArchiveDownloader(url, path.dirname(filePath), {
+    fileName: path.basename(filePath),
+    override: true,
+    // The panel owns retry. SDK retry/resume can otherwise outlive cancellation.
+    retry: false,
+    resumeOnIncomplete: false,
+    resumeIfFileExists: false,
+    forceResume: false,
+    removeOnStop: false,
+    removeOnFail: false,
+    httpRequestOptions: { signal: request.signal },
+    httpsRequestOptions: { signal: request.signal },
+  })
+
+  return new Promise((resolve, reject) => {
+    let state = 'running'
+    let phase = 'connecting'
+    let receivedBytes = 0
+    let totalBytes
+    let timer
+    const cleanListeners = () => {
+      clearTimeout(timer)
+      options.signal?.removeEventListener('abort', onAbort)
+    }
+    const fail = (error) => {
+      if (state !== 'running') return
+      state = 'stopping'
+      cleanListeners()
+      request.abort(error)
+      // SDK emits "download" before finishing stream setup. Let that setup
+      // finish, then await closed handles before removing a partial file (Windows).
+      void Promise.resolve().then(async () => {
+        try {
+          await downloader.stop()
+          await rm(filePath, { force: true })
+        } catch (cleanupError) {
+          reject(new Error(`${error.message}; download cleanup failed: ${cleanupError.message}`, { cause: error }))
+          return
+        }
+        reject(error)
+      })
+    }
+    const onAbort = () => fail(cancelled())
+    const resetTimer = () => {
+      clearTimeout(timer)
+      if (state !== 'running') return
+      const duration = phase === 'connecting' ? connectTimeoutMs : idleTimeoutMs
+      timer = setTimeout(() => fail(new Error(
+        `${label} timed out (${phase} for ${duration}ms; received ${receivedBytes} bytes)`,
+      )), duration)
+    }
+    const progress = (detail) => {
+      if (state !== 'running') return
+      try {
+        options.onProgress?.({ phase: 'download', receivedBytes,
+          ...(totalBytes === undefined ? {} : { totalBytes }),
+          ...(detail === undefined ? {} : { detail }) })
+      } catch (error) { fail(error) }
+    }
+    const tooLarge = () => fail(new Error(`${label} is larger than ${maxBytes} bytes`))
+    downloader.on('download', (info) => {
+      if (state !== 'running') return
+      if (info.totalSize > maxBytes) { tooLarge(); return }
+      totalBytes = info.totalSize > 0 ? info.totalSize : undefined
+      phase = 'idle'
+      resetTimer()
+      progress('Connected; receiving archive data…')
+    })
+    downloader.on('progress', (info) => {
+      if (state !== 'running') return
+      if (info.downloaded > receivedBytes) {
+        receivedBytes = info.downloaded
+        resetTimer()
+      }
+      if (receivedBytes > maxBytes) { tooLarge(); return }
+      progress()
+    })
+    downloader.on('end', (info) => {
+      if (state !== 'running') return
+      try {
+        if (info.incomplete || path.resolve(info.filePath) !== filePath) {
+          throw new Error(`${label} is incomplete or has an unexpected destination`)
+        }
+        const size = statSync(filePath).size
+        if (size > maxBytes) { tooLarge(); return }
+        if (totalBytes !== undefined && size !== totalBytes) {
+          throw new Error(`${label} is incomplete: expected ${totalBytes} bytes, received ${size}`)
+        }
+        state = 'complete'
+        cleanListeners()
+        resolve({ filePath, receivedBytes: size })
+      } catch (error) { fail(error) }
+    })
+    // Keep an error listener through stop/cleanup; native abort can emit late.
+    downloader.on('error', (error) => fail(new Error(`${label} failed: ${error.message}`, { cause: error })))
+    downloader.on('stop', () => fail(new Error(`${label} stopped before completion`)))
+    options.signal?.addEventListener('abort', onAbort, { once: true })
+    resetTimer()
+    progress('Connecting to download server…')
+    if (state !== 'running') return
+    // start() resolves true on STOP as well as completion. Only "end" is success.
+    downloader.start().catch((error) => fail(new Error(`${label} failed: ${error.message}`, { cause: error })))
+  })
+}

package/lib/harness-discovery.js

@@ -0,0 +1,41 @@
+/** Run filesystem probes off the Client event loop; never launch an agent. */
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
+import { discoverHarnessCandidates } from './harnesses.js'
+
+export async function scanHarnessCandidates(settingsPath, options = {}, query = '') {
+  const { signal } = options
+  signal?.throwIfAborted()
+  // Pass only discovery data, not transport callbacks or unrelated plugin options.
+  const scoped = Object.fromEntries([
+    'registry', 'defaults', 'pathValue', 'pathExt', 'platform', 'arch', 'installRoot',
+  ].filter((key) => options[key] !== undefined).map((key) => [key, options[key]]))
+  scoped.settingsPath = settingsPath
+  const worker = new Worker(new URL(import.meta.url), {
+    workerData: { harnessDiscovery: true, settingsPath, options: scoped, query },
+    // No CLI/test-runner flags apply to this plain filesystem worker.
+    execArgv: [],
+  })
+  return new Promise((resolve, reject) => {
+    let settled = false
+    const finish = (error, entries) => {
+      if (settled) return
+      settled = true
+      signal?.removeEventListener('abort', cancel)
+      void worker.terminate()
+      if (error) reject(error)
+      else resolve(entries)
+    }
+    const cancel = () => finish(signal.reason)
+    signal?.addEventListener('abort', cancel, { once: true })
+    worker.once('message', (entries) => finish(undefined, entries))
+    worker.once('error', (error) => finish(error))
+    worker.once('exit', (code) => {
+      if (!settled) finish(new Error(`Harness discovery worker exited before returning results (${code})`))
+    })
+    if (signal?.aborted) cancel()
+  })
+}
+
+if (!isMainThread && workerData?.harnessDiscovery === true) {
+  parentPort.postMessage(discoverHarnessCandidates(workerData.settingsPath, workerData.options, workerData.query))
+}