@foggy-projects/deepseek-harness-plugin 0.4.0-beta.7 → 0.4.0-beta.9

package/README.md

@@ -2,13 +2,19 @@
 
 This package is the lightweight DeepSeek Harness Bundle for Foggy's Java data
 analysis engine. Installing the Bundle adds a native Foggy tab under **Settings
-→ Plugins**. The large Launcher and the isolated CLI environment are downloaded
-only when the user selects **Initialize Foggy**.
+→ Plugins**. The private Python runtime, Launcher, and isolated CLI environment
+are downloaded only when the user selects **Initialize Foggy**.
+
+DeepSeek Harness uses a system Node.js (`^22.19.0 || >=24.0.0`) and Foggy's Java
+Launcher uses a system Java 17+. Foggy manages its own pinned Python 3.12 runtime
+inside the per-user component directory; it does not require a system Python,
+modify `PATH`, or register Python globally. Advanced users may explicitly set
+`FOGGY_PYTHON` to a compatible Python 3.11+ executable.
 
 ## Local beta installation
 
 ```powershell
-dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.0-beta.7.tgz
+dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.0-beta.9.tgz
 ```
 
 Restart `dsh web`, open Settings → Plugins → Foggy Data Analysis, and initialize
@@ -44,8 +50,8 @@ persistent store. A completed profile can also be bound non-destructively to an
 additional DSH workspace when its reviewed connection contract and published
 semantic digest are unchanged.
 
-CLI, Launcher, the analysis Skill, install state, and Runtime state live in the
-user-level Foggy component directories. The managed CLI is intentionally isolated
+Private Python, CLI, Launcher, the analysis Skill, install state, and Runtime
+state live in the user-level Foggy component directories. The managed CLI is intentionally isolated
 and does not need to be on `PATH`. **Re-download / Repair** verifies the global
 analysis Skill, backs up modified or outdated managed content, restores it, and
 invalidates DSH's Skill catalog. The onboarding Skill is bundled with the plugin
@@ -53,7 +59,7 @@ and is restored by reinstalling or upgrading the plugin package.
 
 The Foggy settings tab shows the persisted database/semantic onboarding stages,
 offers pinned checks and repair for CLI, Launcher, and the managed analysis
-Skill, and exports a private redacted diagnostics report. Runtime start is
+Skill, private Python, and exports a private redacted diagnostics report. Runtime start is
 idempotent: an already-recorded process is verified with `wait-ready` and
 `capabilities` instead of being treated as a failed second start.
 
@@ -63,6 +69,9 @@ a production service.
 
 See [`docs/PUBLIC-BETA-READINESS.md`](./docs/PUBLIC-BETA-READINESS.md) for the
 tested public Beta scope, release gates, and stable-release blockers.
+Native Windows acceptance instructions are in
+[`docs/WINDOWS-BETA-ACCEPTANCE.md`](./docs/WINDOWS-BETA-ACCEPTANCE.md); database
+credentials intentionally remain outside the public repository.
 
 ## Linux and WSL2 experience
 

package/THIRD-PARTY-RUNTIME-NOTICES.md

@@ -0,0 +1,16 @@
+# Third-party runtime notices
+
+Foggy for DeepSeek Harness downloads a pinned CPython runtime on first
+initialization. The runtime is not included in the npm package and is installed
+only inside Foggy's per-user component directory.
+
+- CPython is provided under the Python Software Foundation License Version 2.
+- Portable distributions are produced by
+  [astral-sh/python-build-standalone](https://github.com/astral-sh/python-build-standalone),
+  whose build tooling is provided under MPL-2.0.
+- The downloaded distribution contains its own license and attribution files.
+
+The exact build release, platform assets, sizes, URLs, and SHA256 digests are
+recorded in `skills/foggy-deepseek-onboarding/assets/versions.json`. Foggy
+verifies the selected digest before extraction and does not add the interpreter
+to `PATH` or register it as a system Python installation.

package/docs/PUBLIC-BETA-READINESS.md

@@ -0,0 +1,53 @@
+# Public beta readiness: 0.4.0-beta.9
+
+Assessment date: 2026-09-04
+
+## Verdict
+
+`0.4.0-beta.9` is suitable for a scoped public beta on Windows 10/11 x64 and
+Linux/WSL2 x64. It is not a general-availability release.
+
+The plugin package stays small and downloads large components only during
+initialization. Node.js and Java remain system prerequisites. Python 3.12.13 is
+installed privately below Foggy's component directory and does not change the
+system PATH, registry, or a user's existing Python installation.
+
+## Verified behavior
+
+- The npm tarball is about 67 KB compressed and contains no Python or Java
+  runtime binary.
+- Managed CPython assets are pinned by URL, byte size, and SHA256 for Windows,
+  Linux, and macOS on x64 and arm64.
+- Windows x64 completed a cold Python download, checksum verification,
+  extraction, initialization, forced Python repair, and doctor run.
+- Linux/WSL2 x64 completed managed Python extraction, initialization, and a live
+  DeepSeek Harness `0.1.1-rc.2` UI status check.
+- The UI reported Python 3.12.13 as `Foggy private`, and CLI 0.1.23, Launcher
+  0.1.18, analysis Skill 0.1.17, and onboarding Skill 0.4.0-beta.9 as installed.
+- Interrupted downloads resume with HTTP Range when the server supports it;
+  downloaded artifacts are not trusted until the complete SHA256 matches.
+- Windows progress writes tolerate transient sharing violations without losing
+  the previous valid progress document or leaving temporary files behind.
+- Automated regression passed under Node 22.23.2: 17 Node tests and 10 Python
+  tests, plus shell and PowerShell syntax checks.
+
+## Beta boundaries
+
+- Supported public-beta targets: Windows 10/11 x64 and Linux/WSL2 x64.
+- Windows users must install a supported system Node.js line (`^22.19.0` or
+  `>=24.0.0`) and Java 17 or later. They do not need to install Python.
+- macOS and arm64 assets are pinned and integrity-checked but have not received
+  the same end-to-end host validation; treat those targets as experimental.
+- DeepSeek Harness itself is still consumed at `0.1.1-rc.2`, so its plugin
+  installation and supply-chain policy behavior may change before a stable
+  Harness release.
+- Runtime production authentication is outside this beta's default local
+  onboarding mode. The UI and doctor continue to report `productionReady=false`
+  for the development-only no-auth mode.
+
+## Release gate after publication
+
+Before broad announcement, complete the native Windows fresh-machine checklist
+in [WINDOWS-BETA-ACCEPTANCE.md](./WINDOWS-BETA-ACCEPTANCE.md). Record the exact
+Node, Java, DeepSeek Harness, and plugin versions and confirm that initialization
+works without a system Python executable.

package/docs/WINDOWS-BETA-ACCEPTANCE.md

@@ -0,0 +1,70 @@
+# Native Windows Beta acceptance
+
+This runbook validates DeepSeek Harness `0.1.1-rc.2` with Foggy plugin
+`0.4.0-beta.9` on a clean 64-bit Windows 10 or Windows 11 machine. Use a local
+directory that is not synchronized by OneDrive.
+
+## Prerequisites
+
+Install a system Node.js matching `^22.19.0 || >=24.0.0` and a system Java 17+
+JRE/JDK. Windows must also provide `tar` (included in supported Windows 10/11
+versions). A system Python is neither required nor used by default.
+
+```powershell
+node --version
+npm --version
+java -version
+tar --version
+```
+
+Foggy downloads a pinned private CPython 3.12.13 runtime during initialization.
+It remains below `%LOCALAPPDATA%\Foggy\DeepSeekHarness`, is not added to `PATH`,
+and is not registered as a system Python.
+
+## Install and start
+
+```powershell
+New-Item -ItemType Directory -Force C:\FoggyAcceptance | Out-Null
+Set-Location C:\FoggyAcceptance
+
+npx --yes --package=@deepseek-ai/dsh@0.1.1-rc.2 --package=pnpm@11.7.0 `
+  dsh plugin --profile web add --workspace-root `
+  "@foggy-projects/deepseek-harness-plugin@beta"
+
+npx --yes --package=@deepseek-ai/dsh@0.1.1-rc.2 --package=pnpm@11.7.0 dsh web
+```
+
+Open `http://127.0.0.1:3080/`, configure an LLM provider, select the
+`C:\FoggyAcceptance` workspace, then open **Settings → Plugins → Foggy Data
+Analysis** and choose **Initialize Foggy**.
+
+Expected component state:
+
+- Python 3.12.13, source `Foggy private`;
+- CLI 0.1.23;
+- Launcher 0.1.18;
+- analysis Skill 0.1.17;
+- onboarding Skill 0.4.0-beta.9;
+- Java 17+ available;
+- native DSH Skill registration available.
+
+## Database and semantic-layer acceptance
+
+Keep database credentials out of this public repository. Create a private CLI
+profile outside the DSH conversation, pass only its opaque profile ID and
+revision to the onboarding workflow, and use a test-only database account with
+read-only permissions.
+
+Use a natural prompt such as:
+
+```text
+请帮我用 Foggy 分析这个测试数据库。我已经按验收手册创建了私有连接
+profile。请先确认连接和表结构，再围绕订单数据创建一个简单的语义层，
+包含订单数量、状态和开单时间，最后执行一个不超过 20 行的只读查询。
+不要修改数据库，也不要在对话或验收文件中输出密码。
+```
+
+Pass only when Runtime readiness and capabilities succeed, datasource metadata
+can be discovered, TM/QM models validate and publish, the bounded read-only
+query succeeds, diagnostics contain no credentials, and stopping Runtime frees
+port 18066.

package/experience/linux/README.md

@@ -5,14 +5,13 @@ It has been designed for Ubuntu 22.04/24.04 x86_64 and WSL2.
 
 ## Prerequisites
 
-- Node.js 22.19 or newer
-- Python 3.11 or newer with `venv`
+- Node.js `^22.19.0` or `>=24.0.0`
 - Java 17 or newer
-- Git and npm
+- Git, npm, and `tar`
 - At least 4 GiB free disk space and 2 GiB available memory; 4 GiB memory is recommended
 
 Keep the experience root on the Linux-native filesystem, such as under `$HOME`. In WSL2, do not
-put DSH, `node_modules`, the Python virtual environment, or Foggy data under `/mnt/c` or `/mnt/d`.
+put DSH, `node_modules`, Foggy's private Python environment, or Foggy data under `/mnt/c` or `/mnt/d`.
 
 ## Prepare
 
@@ -35,8 +34,8 @@ Start the prepared profile with:
 ```
 
 Open the URL printed by DSH, then choose **Settings → Plugins → Foggy Data Analysis** and select
-**Initialize Foggy**. The CLI, Launcher, and analysis Skill are downloaded from their pinned public
-Releases and verified before installation.
+**Initialize Foggy**. Private Python, the CLI, Launcher, and analysis Skill are downloaded from their
+pinned public Releases and verified before installation. A system Python is not required.
 
 Provider configuration remains a separate DSH setup step. Store API keys in a private environment
 file or secret manager; do not add them to the DSH settings document or the project repository.

package/experience/linux/prepare.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 DSH_VERSION="0.1.1-rc.2"
 PNPM_VERSION="11.7.0"
-PLUGIN_VERSION="0.4.0-beta.4"
+PLUGIN_VERSION="0.4.0-beta.9"
 PLUGIN_REF="v${PLUGIN_VERSION}"
 PLUGIN_REPOSITORY="https://github.com/foggy-projects/foggy-deepseek-harness-plugin.git"
 
@@ -62,22 +62,19 @@ require_command() {
 
 [[ "$(uname -s)" == "Linux" ]] || fail "this entry supports Linux and WSL2 only"
 case "$(uname -m)" in
-  x86_64|amd64) ;;
-  *) fail "validated architecture is x86_64; detected $(uname -m)" ;;
+  x86_64|amd64|aarch64|arm64) ;;
+  *) fail "supported architectures are x86_64 and arm64; detected $(uname -m)" ;;
 esac
 
 require_command node
 require_command npm
-require_command python3
 require_command java
 require_command git
 require_command df
+require_command tar
 
-node -e 'const [major, minor] = process.versions.node.split(".").map(Number); if (major < 22 || (major === 22 && minor < 19)) process.exit(1)' \
-  || fail "Node 22.19+ required; detected $(node --version 2>/dev/null || echo unknown)"
-python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)' \
-  || fail "Python 3.11+ required; detected $(python3 --version 2>/dev/null || echo unknown)"
-python3 -m venv --help >/dev/null 2>&1 || fail "Python venv support is required"
+node -e 'const [major, minor] = process.versions.node.split(".").map(Number); if (!((major === 22 && minor >= 19) || major >= 24)) process.exit(1)' \
+  || fail "Node ^22.19.0 or >=24 required; detected $(node --version 2>/dev/null || echo unknown)"
 
 java_major="$(java -version 2>&1 | awk -F'[\".]' '/version/ { print $2; exit }')"
 [[ "$java_major" =~ ^[0-9]+$ ]] || fail "could not detect Java version"
@@ -121,6 +118,7 @@ Foggy Linux experience plan
   DSH:              $DSH_VERSION
   pnpm:             $PNPM_VERSION
   Foggy Bundle:     $PLUGIN_VERSION
+  Python:           private managed 3.12.13 (downloaded during Foggy initialization)
   Experience root:  $experience_root
   Project root:     $project_root
   Filesystem:       Linux-native

package/lib/atomic-json.js

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+const TRANSIENT_REPLACE_CODES = new Set(['EACCES', 'EBUSY', 'EPERM'])
+const TRANSIENT_WINERRORS = new Set([5, 32, 33])
+
+function wait(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+function transientReplaceError(error) {
+  return TRANSIENT_REPLACE_CODES.has(error?.code) || TRANSIENT_WINERRORS.has(error?.winerror)
+}
+
+export async function replaceWithRetry(source, destination, {
+  replace = rename,
+  sleep = wait,
+  attempts = 12,
+} = {}) {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      await replace(source, destination)
+      return
+    } catch (error) {
+      if (!transientReplaceError(error) || attempt === attempts - 1) throw error
+      await sleep(Math.min(25 * (2 ** attempt), 400))
+    }
+  }
+}
+
+export async function writeJsonAtomic(path, payload, options = {}) {
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`
+  try {
+    await writeFile(temporary, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+    await replaceWithRetry(temporary, path, options)
+  } finally {
+    await rm(temporary, { force: true })
+  }
+}

package/lib/client.js

@@ -11,7 +11,7 @@ window.__ModuleLoader__.load({
     const TYPERT_REMOTE = {
       package: '@foggy-projects/deepseek-harness-plugin',
       descriptors: [
-        'status', 'plan', 'initialize', 'repair', 'repairCli', 'repairLauncher', 'repairAnalysisSkill',
+        'status', 'plan', 'initialize', 'repair', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill',
         'migrateProfiles', 'diagnostics', 'runtimeStart', 'runtimeStop',
       ].map((method) => ({
         id: `@foggy-projects/deepseek-harness-plugin#foggyIntegration/${method}`,
@@ -32,7 +32,7 @@ window.__ModuleLoader__.load({
     const zh = {
       tab: 'Foggy 数据分析',
       title: 'Foggy Java 数据分析引擎',
-      intro: '在 DeepSeek Harness 内管理 Foggy CLI、Launcher、Skills 和本地 Runtime。大型组件在首次初始化时按需下载。',
+      intro: '在 DeepSeek Harness 内管理 Foggy 私有 Python、CLI、Launcher、Skills 和本地 Runtime。大型组件在首次初始化时按需下载。',
       refresh: '刷新状态',
       loading: '正在读取 Foggy 状态…',
       failed: '暂时无法读取 Foggy 状态。',
@@ -55,6 +55,7 @@ window.__ModuleLoader__.load({
       initialize: '初始化 Foggy',
       repair: '重新下载 / 修复',
       repairTitle: '分组件检查与修复',
+      repairPython: '检查 / 修复私有 Python',
       repairCli: '检查 / 修复 CLI',
       repairLauncher: '检查 / 修复 Launcher',
       repairAnalysisSkill: '检查 / 修复分析 Skill',
@@ -65,6 +66,7 @@ window.__ModuleLoader__.load({
       working: '操作进行中…',
       progressWorking: '正在初始化 Foggy…',
       progressPreflight: '检查运行环境',
+      progressPython: '准备私有 Python',
       progressCli: '准备 CLI',
       progressLauncher: '准备 Launcher',
       progressAnalysis: '准备分析 Skill',
@@ -72,6 +74,8 @@ window.__ModuleLoader__.load({
       progressState: '写入安装状态',
       progressComplete: '初始化完成',
       progressFiles: '文件',
+      managedPrivate: 'Foggy 私有',
+      configuredOverride: '外部指定',
       accepted: '操作已开始；页面会自动刷新状态。',
       actionFailed: '操作失败',
       roots: '本地目录',
@@ -103,7 +107,7 @@ window.__ModuleLoader__.load({
     const en = {
       tab: 'Foggy Data Analysis',
       title: 'Foggy Java Data Analysis Engine',
-      intro: 'Manage the Foggy CLI, Launcher, Skills, and local Runtime inside DeepSeek Harness. Large components are downloaded on first initialization.',
+      intro: 'Manage Foggy private Python, CLI, Launcher, Skills, and the local Runtime inside DeepSeek Harness. Large components are downloaded on first initialization.',
       refresh: 'Refresh status',
       loading: 'Reading Foggy status…',
       failed: 'Foggy status is temporarily unavailable.',
@@ -126,6 +130,7 @@ window.__ModuleLoader__.load({
       initialize: 'Initialize Foggy',
       repair: 'Re-download / Repair',
       repairTitle: 'Component checks and repair',
+      repairPython: 'Check / repair private Python',
       repairCli: 'Check / repair CLI',
       repairLauncher: 'Check / repair Launcher',
       repairAnalysisSkill: 'Check / repair analysis Skill',
@@ -136,6 +141,7 @@ window.__ModuleLoader__.load({
       working: 'Operation in progress…',
       progressWorking: 'Initializing Foggy…',
       progressPreflight: 'Checking prerequisites',
+      progressPython: 'Preparing private Python',
       progressCli: 'Preparing CLI',
       progressLauncher: 'Preparing Launcher',
       progressAnalysis: 'Preparing analysis Skill',
@@ -143,6 +149,8 @@ window.__ModuleLoader__.load({
       progressState: 'Writing install state',
       progressComplete: 'Initialization complete',
       progressFiles: 'files',
+      managedPrivate: 'Foggy private',
+      configuredOverride: 'Configured override',
       accepted: 'The operation started; this page will refresh automatically.',
       actionFailed: 'Operation failed',
       roots: 'Local directories',
@@ -204,6 +212,16 @@ window.__ModuleLoader__.load({
       const stateText = kind === 'runtime'
         ? t(available ? 'installed' : 'missing')
         : t(available ? 'available' : 'unavailable')
+      const source = component?.source === 'managed'
+        ? t('managedPrivate')
+        : component?.source === 'override'
+          ? t('configuredOverride')
+          : null
+      const detail = [
+        component?.version || component?.output || '—',
+        component?.minimum ? `≥${component.minimum}` : null,
+        source,
+      ].filter(Boolean).join(' · ')
       return jsxs('div', {
         className: 'foggy-card',
         children: [
@@ -211,7 +229,8 @@ window.__ModuleLoader__.load({
             jsx('strong', { children: label }),
             jsx('span', { className: 'foggy-badge', children: stateText }),
           ] }),
-          jsx('code', { children: `${component?.version || component?.output || '—'}${component?.minimum ? ` · ≥${component.minimum}` : ''}` }),
+          jsx('code', { children: detail }),
+          component?.path ? jsx('code', { title: component.path, children: component.path }) : null,
         ],
       })
     }
@@ -221,6 +240,7 @@ window.__ModuleLoader__.load({
       const percent = Math.max(0, Math.min(100, Number(progress.percent) || 0))
       const phaseKeys = {
         preflight: 'progressPreflight',
+        python: 'progressPython',
         cli: 'progressCli',
         launcher: 'progressLauncher',
         'analysis-skill': 'progressAnalysis',
@@ -376,6 +396,7 @@ window.__ModuleLoader__.load({
         jsxs('div', { className: 'foggy-section', children: [
           jsx('h4', { children: t('repairTitle') }),
           jsx('div', { className: 'foggy-section-actions', children: [
+            jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('repairPython'), children: t('repairPython') }),
             jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('repairCli'), children: t('repairCli') }),
             jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('repairLauncher'), children: t('repairLauncher') }),
             jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('repairAnalysisSkill'), children: t('repairAnalysisSkill') }),

package/lib/index.js

@@ -6,7 +6,9 @@ import { fileURLToPath } from 'node:url'
 import { promisify } from 'node:util'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import { createFoggySkillProvider } from './skill-provider.js'
-import { compatible } from './version.js'
+import { writeJsonAtomic } from './atomic-json.js'
+import { ensurePythonRuntime, probePythonRuntime } from './python-runtime.js'
+import { compatible, compatibleNode } from './version.js'
 
 const execFileAsync = promisify(execFile)
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
@@ -71,16 +73,6 @@ async function commandVersion(command, args) {
   }
 }
 
-async function pythonCommand() {
-  const configured = process.env.FOGGY_PYTHON
-  const candidates = configured ? [configured] : process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python']
-  for (const command of candidates) {
-    const probe = await commandVersion(command, ['--version'])
-    if (probe.available) return command
-  }
-  throw new Error('Python 3.11+ was not found; set FOGGY_PYTHON to its executable')
-}
-
 function parseOutput(stdout, stderr) {
   const text = String(stdout ?? '').trim()
   if (!text) throw new Error(String(stderr ?? '').trim() || 'Foggy onboarding returned no JSON')
@@ -91,14 +83,34 @@ function parseOutput(stdout, stderr) {
   }
 }
 
-async function runOnboarding(args, timeout = 15 * 60_000) {
-  const python = await pythonCommand()
+async function runOnboarding(args, timeout = 15 * 60_000, options = {}) {
+  const roots = defaultRoots()
+  const manifest = await readJson(versionsFile)
+  const cacheDirs = (process.env.FOGGY_ASSET_CACHE_DIRS || '').split(delimiter).filter(Boolean)
+  const python = options.ensurePython
+    ? await ensurePythonRuntime({
+        installRoot: roots.installRoot,
+        manifest,
+        cacheDirs,
+        force: options.forcePython,
+        onProgress: options.onPythonProgress,
+      })
+    : await probePythonRuntime({ installRoot: roots.installRoot, manifest })
+  if (!python.available) {
+    throw new Error('Foggy managed Python is unavailable; initialize or repair the Python component')
+  }
+  await options.flushPythonProgress?.()
   try {
-    const { stdout, stderr } = await execFileAsync(python, [onboardingScript, ...args], {
+    const { stdout, stderr } = await execFileAsync(python.path, [onboardingScript, ...args], {
       windowsHide: true,
       timeout,
       maxBuffer: 4 * 1024 * 1024,
       cwd: process.env.FOGGY_PROJECT_ROOT || process.cwd(),
+      env: {
+        ...process.env,
+        FOGGY_ONBOARDING_PYTHON: python.path,
+        FOGGY_ONBOARDING_PYTHON_SOURCE: python.source,
+      },
     })
     return parseOutput(stdout, stderr)
   } catch (error) {
@@ -107,6 +119,44 @@ async function runOnboarding(args, timeout = 15 * 60_000) {
   }
 }
 
+async function assertSystemPrerequisites(kind) {
+  if (kind === 'initialize' && !compatibleNode(process.versions.node)) {
+    throw new Error(`DeepSeek Harness requires Node.js ^22.19.0 or >=24.0.0; detected ${process.versions.node}`)
+  }
+  if (kind === 'initialize' || kind === 'runtime-start') {
+    const java = compatible(await commandVersion(process.env.JAVA_EXE || 'java', ['-version']), '17.0')
+    if (!java.available) throw new Error('Java 17+ is required; install a system JRE/JDK or set JAVA_EXE')
+  }
+}
+
+function createPythonProgressReporter(operation, path) {
+  let pending = Promise.resolve()
+  return {
+    update(detail) {
+      const fraction = Math.max(0, Math.min(1, Number(detail.fraction) || 0))
+      const payload = {
+        schemaVersion: 'foggy-deepseek-onboarding-progress/v1',
+        operationId: operation.id,
+        kind: operation.kind,
+        state: 'running',
+        phase: 'python',
+        message: detail.message || 'Preparing managed Python',
+        currentFile: detail.currentFile || null,
+        percent: Math.round(((1 + fraction) / 7) * 100),
+        step: { index: 2, total: 7 },
+        startedAt: operation.startedAt,
+        updatedAt: new Date().toISOString(),
+      }
+      if (detail.bytes) payload.bytes = detail.bytes
+      operation.progress = payload
+      pending = pending.then(() => writeJsonAtomic(path, payload))
+    },
+    flush() {
+      return pending
+    },
+  }
+}
+
 function processRunning(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false
   try {
@@ -145,13 +195,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     const runtimeStatePath = join(roots.dataRoot, 'runtime-state.json')
     const progressPath = join(roots.dataRoot, 'operation-progress.json')
     const manifest = await readJson(versionsFile)
-    let pythonProbe
-    try {
-      pythonProbe = await commandVersion(await pythonCommand(), ['--version'])
-    } catch (error) {
-      pythonProbe = { available: false, output: '', error: String(error.message ?? error) }
-    }
-    const python = compatible(pythonProbe, '3.11')
+    const python = await probePythonRuntime({ installRoot: roots.installRoot, manifest })
     const java = compatible(await commandVersion(process.env.JAVA_EXE || 'java', ['-version']), '17.0')
     let state = null
     let runtime = null
@@ -197,7 +241,8 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         provider: 'foggy-managed-skills',
       },
     }
-    const installed = components.cli.installed
+    const installed = components.python.available
+      && components.cli.installed
       && components.launcher.installed
       && components.analysisSkill.installed
       && components.onboardingSkill.installed
@@ -243,6 +288,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       workspaceMode: 'dsh-session-cwd',
       versions: Object.fromEntries(Object.entries(manifest.components).map(([name, value]) => [name, value.version])),
       operations: [
+        'download and verify a pinned private Python runtime',
         'create isolated Python environment',
         'download and verify pinned CLI and Launcher assets',
         'install the Foggy analysis Skill into the global managed component directory',
@@ -265,6 +311,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     return this.startOperation('repair-cli', false, ['install', '--repair-component', 'cli'])
   }
 
+  async repairPython() {
+    return this.startOperation('repair-python', false, ['install'])
+  }
+
   async repairLauncher() {
     return this.startOperation('repair-launcher', false, ['install', '--repair-component', 'launcher'])
   }
@@ -279,10 +329,13 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
 
   async diagnostics() {
     const roots = defaultRoots()
-    const [status, doctor] = await Promise.all([
-      this.status(),
-      runOnboarding(['doctor', '--no-fail']),
-    ])
+    const status = await this.status()
+    let doctor
+    try {
+      doctor = await runOnboarding(['doctor', '--no-fail'])
+    } catch (error) {
+      doctor = { success: false, error: String(error.message ?? error), bootstrapOnly: true }
+    }
     const report = {
       schemaVersion: 'foggy-deepseek-diagnostics/v1',
       generatedAt: new Date().toISOString(),
@@ -344,11 +397,22 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         message: 'Starting Foggy initialization',
         currentFile: null,
         percent: 0,
-        step: { index: 1, total: 6 },
+        step: { index: 1, total: 7 },
       } : null,
       promise: null,
     }
-    operation.promise = runOnboarding(args)
+    const pythonProgress = reportsProgress
+      ? createPythonProgressReporter(operation, join(defaultRoots().dataRoot, 'operation-progress.json'))
+      : null
+    operation.promise = (async () => {
+      await assertSystemPrerequisites(kind)
+      return runOnboarding(args, 15 * 60_000, {
+        ensurePython: true,
+        forcePython: kind === 'repair-python',
+        onPythonProgress: (detail) => pythonProgress?.update(detail),
+        flushPythonProgress: () => pythonProgress?.flush(),
+      })
+    })()
       .then((result) => {
         operation.state = result.success === false ? 'failed' : 'succeeded'
         operation.result = result
@@ -384,7 +448,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
 
 const markerInitializers = []
 for (const method of [
-  'status', 'plan', 'initialize', 'repair', 'repairCli', 'repairLauncher', 'repairAnalysisSkill',
+  'status', 'plan', 'initialize', 'repair', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill',
   'migrateProfiles', 'diagnostics', 'runtimeStart', 'runtimeStop',
 ]) {
   Remote(method)(FoggyIntegrationGateway.prototype[method], {