@foggy-projects/deepseek-harness-plugin 0.4.0-rc.2 → 0.4.0-rc.3

package/README.md

@@ -3,7 +3,9 @@
 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 private Python runtime, Launcher, and isolated CLI environment
-are downloaded only when the user selects **Initialize Foggy**.
+are downloaded only when the user selects **Initialize and start** (or the
+equivalent component action). Existing installations are not silently changed
+when the plugin package is upgraded.
 
 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
@@ -14,7 +16,7 @@ modify `PATH`, or register Python globally. Advanced users may explicitly set
 ## Local beta installation
 
 ```powershell
-dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.0-rc.2.tgz
+dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.0-rc.3.tgz
 ```
 
 Restart `dsh web`, use the browser it opens (or the complete printed URL,
@@ -27,6 +29,13 @@ After npm beta publication, the corresponding one-line install is:
 dsh plugin --profile web add --workspace-root @foggy-projects/deepseek-harness-plugin@beta
 ```
 
+After updating the plugin package, open **Settings → Plugins → Foggy Data
+Analysis** and use **Update components** (or **Update and start**) to download
+the pinned CLI, Launcher, and Skills. The settings page shows current and target
+versions. Updates are blocked while Runtime is running so the active Java
+process and the next-launcher state cannot diverge. Component-specific repair
+actions remain available under **Advanced repair**.
+
 DeepSeek Harness 0.1.2-rc.1 applies pnpm's minimum-release-age policy to its
 profile lockfile. An upgrade performed shortly after publication can therefore
 fail while naming either the new plugin or the previously installed Beta. This

package/docs/RELEASE-CANDIDATE-0.4.0-RC.3.md

@@ -0,0 +1,18 @@
+# Foggy DeepSeek Harness plugin 0.4.0-rc.3 release candidate
+
+Assessment date: 2026-09-06
+
+## Delta from rc.2
+
+- Add a single **Initialize and start** action for first use.
+- Add **Update components** and **Update and start** actions for managed CLI,
+  Launcher, and Skill assets after a plugin-package upgrade.
+- Show current versus target component versions and an explicit update banner.
+- Block component update/repair while Runtime is running; the active Launcher
+  process must not diverge from the persisted next-launcher version.
+- Keep Refresh, diagnostics, and component-specific repair actions in the
+  secondary/advanced action areas.
+- Add public documentation, plugin repository, release, and Runtime project
+  links to the settings page.
+
+No Java engine or `foggy-runtime-cli` source was changed.

package/lib/client.js

@@ -35,7 +35,7 @@ window.__ModuleLoader__.load({
       package: '@foggy-projects/deepseek-harness-plugin',
       descriptors: [
         ...[
-        'status', 'plan', 'initialize', 'repair', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill', 'repairSemanticQuerySkill',
+        'status', 'plan', 'initialize', 'initializeAndStart', 'repair', 'updateComponents', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill', 'repairSemanticQuerySkill',
         'migrateProfiles', 'diagnostics', 'runtimeStart', 'runtimeStop',
         ].map((method) => descriptor(method)),
         descriptor('saveRuntimeSettings', [{
@@ -54,7 +54,7 @@ window.__ModuleLoader__.load({
     const zh = {
       tab: 'Foggy 数据分析',
       title: 'Foggy Java 数据分析引擎',
-      intro: '在 DeepSeek Harness 内管理 Foggy 私有 Python、CLI、Launcher、Skills 和本地 Runtime。大型组件在首次初始化时按需下载。',
+      intro: '在 DeepSeek Harness 内管理 Foggy 私有 Python、CLI、Launcher、Skills 和本地 Runtime。大型组件按需下载，插件升级后可在此处一键更新。',
       refresh: '刷新状态',
       loading: '正在读取 Foggy 状态…',
       failed: '暂时无法读取 Foggy 状态。',
@@ -73,11 +73,20 @@ window.__ModuleLoader__.load({
       java: 'Java',
       installed: '已安装',
       missing: '未安装',
+      upToDate: '最新',
+      updateAvailable: '有更新',
+      installedVersion: '当前版本',
+      targetVersion: '目标版本',
       available: '可用',
       unavailable: '不可用',
       initialize: '初始化 Foggy',
-      repair: '重新下载 / 修复',
-      repairTitle: '分组件检查与修复',
+      initializeAndStart: '初始化并启动',
+      initializeAndStartDone: 'Foggy 已初始化，Runtime 已启动。',
+      updateComponents: '更新组件',
+      updateAndStart: '更新并启动',
+      updateAndStartDone: '组件已更新，Runtime 已启动。',
+      repair: '修复组件',
+      repairTitle: '高级修复',
       repairPython: '检查 / 修复私有 Python',
       repairCli: '检查 / 修复 CLI',
       repairLauncher: '检查 / 修复 Launcher',
@@ -87,6 +96,16 @@ window.__ModuleLoader__.load({
       diagnosticsSaved: '诊断报告已保存',
       start: '启动 Runtime',
       stop: '停止 Runtime',
+      updateBlockedRunning: 'Runtime 运行中，停止后才能更新组件。',
+      updateReady: '检测到组件更新；可点击“更新并启动”一次完成更新。',
+      updateNone: '所有托管组件均为当前版本。',
+      operationTimeout: '操作等待超时，请刷新状态或导出诊断报告。',
+      resourceTitle: '文档与项目',
+      docs: '使用文档',
+      project: '插件项目',
+      releases: '版本记录',
+      runtimeProject: 'Runtime 项目',
+      openExternal: '在新标签页打开',
       working: '操作进行中…',
       progressWorking: '正在初始化 Foggy…',
       progressPreflight: '检查运行环境',
@@ -160,7 +179,7 @@ window.__ModuleLoader__.load({
     const en = {
       tab: 'Foggy Data Analysis',
       title: 'Foggy Java Data Analysis Engine',
-      intro: 'Manage Foggy private Python, CLI, Launcher, Skills, and the 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 download on demand, and plugin upgrades can be applied here in one step.',
       refresh: 'Refresh status',
       loading: 'Reading Foggy status…',
       failed: 'Foggy status is temporarily unavailable.',
@@ -179,11 +198,20 @@ window.__ModuleLoader__.load({
       java: 'Java',
       installed: 'Installed',
       missing: 'Missing',
+      upToDate: 'Up to date',
+      updateAvailable: 'Update available',
+      installedVersion: 'Current',
+      targetVersion: 'Target',
       available: 'Available',
       unavailable: 'Unavailable',
       initialize: 'Initialize Foggy',
-      repair: 'Re-download / Repair',
-      repairTitle: 'Component checks and repair',
+      initializeAndStart: 'Initialize and start',
+      initializeAndStartDone: 'Foggy was initialized and Runtime started.',
+      updateComponents: 'Update components',
+      updateAndStart: 'Update and start',
+      updateAndStartDone: 'Components were updated and Runtime started.',
+      repair: 'Repair components',
+      repairTitle: 'Advanced repair',
       repairPython: 'Check / repair private Python',
       repairCli: 'Check / repair CLI',
       repairLauncher: 'Check / repair Launcher',
@@ -193,6 +221,16 @@ window.__ModuleLoader__.load({
       diagnosticsSaved: 'Diagnostics saved',
       start: 'Start Runtime',
       stop: 'Stop Runtime',
+      updateBlockedRunning: 'Runtime is running. Stop it before updating components.',
+      updateReady: 'Component updates are available. Use “Update and start” to finish in one step.',
+      updateNone: 'All managed components are up to date.',
+      operationTimeout: 'The operation timed out. Refresh the status or export diagnostics.',
+      resourceTitle: 'Documentation and project',
+      docs: 'User documentation',
+      project: 'Plugin project',
+      releases: 'Releases',
+      runtimeProject: 'Runtime project',
+      openExternal: 'Opens in a new tab',
       working: 'Operation in progress…',
       progressWorking: 'Initializing Foggy…',
       progressPreflight: 'Checking prerequisites',
@@ -267,15 +305,17 @@ window.__ModuleLoader__.load({
       .foggy-settings{width:100%;max-width:820px;color:var(--dsw-alias-label-primary);display:flex;flex-direction:column;gap:16px}
       .foggy-hero{border:1px solid var(--dsw-alias-border-l2);background:linear-gradient(135deg,color-mix(in srgb,var(--dsw-alias-state-business-primary) 10%,var(--dsw-alias-bg-layer-3)),var(--dsw-alias-bg-layer-3));border-radius:12px;padding:18px}
       .foggy-title-row{display:flex;align-items:center;gap:10px}.foggy-title-row h3{margin:0;font-size:18px;line-height:26px}.foggy-beta{font-size:11px;padding:2px 7px;border-radius:999px;background:color-mix(in srgb,var(--dsw-alias-state-business-primary) 14%,transparent);color:var(--dsw-alias-state-business-primary)}
-      .foggy-intro{margin:8px 0 0;color:var(--dsw-alias-label-secondary);font-size:13px;line-height:20px}.foggy-toolbar{display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap}
+      .foggy-intro{margin:8px 0 0;color:var(--dsw-alias-label-secondary);font-size:13px;line-height:20px}.foggy-toolbar{display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap}.foggy-toolbar-main,.foggy-toolbar-secondary{display:flex;gap:8px;flex-wrap:wrap;align-items:center}.foggy-toolbar-secondary{width:100%;padding-top:2px;border-top:1px solid var(--dsw-alias-border-l2)}
       .foggy-state{display:flex;align-items:center;gap:8px;font-size:14px;font-weight:600}.foggy-dot{width:9px;height:9px;border-radius:50%;background:var(--dsw-alias-label-tertiary)}.foggy-dot[data-state=ready],.foggy-dot[data-state=running]{background:var(--dsw-alias-state-success-primary)}.foggy-dot[data-state=degraded]{background:var(--dsw-alias-state-error-primary)}
-      .foggy-actions{display:flex;gap:8px;flex-wrap:wrap}.foggy-button{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:inherit;border-radius:8px;padding:7px 12px;cursor:pointer}.foggy-button:hover{background:var(--dsw-alias-interactive-bg-hover)}.foggy-button:disabled{opacity:.55;cursor:not-allowed}.foggy-button-primary{border-color:var(--dsw-alias-state-business-primary);background:var(--dsw-alias-state-business-primary);color:white}
+      .foggy-actions{display:flex;gap:8px;flex-wrap:wrap}.foggy-button{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:inherit;border-radius:8px;padding:7px 12px;cursor:pointer;transition:background-color .15s ease,box-shadow .15s ease,transform .15s ease}.foggy-button:hover{background:var(--dsw-alias-interactive-bg-hover)}.foggy-button:active{transform:translateY(1px)}.foggy-button:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:2px}.foggy-button:disabled{opacity:.55;cursor:not-allowed}.foggy-button-primary{border-color:var(--dsw-alias-state-business-primary);background:var(--dsw-alias-state-business-primary);color:white}
       .foggy-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:10px}.foggy-card{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);border-radius:10px;padding:13px 14px}.foggy-card-head{display:flex;justify-content:space-between;gap:8px}.foggy-card strong{font-size:13px}.foggy-badge{font-size:11px;color:var(--dsw-alias-label-secondary)}.foggy-card code{display:block;margin-top:8px;color:var(--dsw-alias-label-tertiary);font-size:11px;overflow-wrap:anywhere}
       .foggy-progress{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);border-radius:10px;padding:13px 14px}.foggy-progress-head{display:flex;align-items:center;justify-content:space-between;gap:12px;font-size:13px}.foggy-progress-head strong{font-weight:600}.foggy-progress-percent{color:var(--dsw-alias-label-secondary);font-variant-numeric:tabular-nums}.foggy-progress-track{height:8px;margin-top:10px;border-radius:999px;background:var(--dsw-alias-bg-layer-1);overflow:hidden}.foggy-progress-fill{height:100%;border-radius:inherit;background:var(--dsw-alias-state-business-primary);transition:width .25s ease}.foggy-progress-meta{display:flex;justify-content:space-between;gap:12px;margin-top:8px;color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px}.foggy-progress-file{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
       .foggy-runtime-settings{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);border-radius:10px;padding:14px}.foggy-runtime-settings h4{margin:0;font-size:13px}.foggy-runtime-settings-row{display:grid;grid-template-columns:minmax(150px,220px) minmax(0,1fr) auto;align-items:end;gap:10px;margin-top:10px}.foggy-field{display:flex;flex-direction:column;gap:6px}.foggy-field label{font-size:12px;font-weight:600}.foggy-input{width:100%;box-sizing:border-box;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:inherit;font-variant-numeric:tabular-nums;padding:8px 10px;outline:none}.foggy-input:focus{border-color:var(--dsw-alias-state-business-primary);box-shadow:0 0 0 3px color-mix(in srgb,var(--dsw-alias-state-business-primary) 18%,transparent)}.foggy-input[aria-invalid=true]{border-color:var(--dsw-alias-state-error-primary);box-shadow:0 0 0 3px color-mix(in srgb,var(--dsw-alias-state-error-primary) 14%,transparent)}.foggy-setting-meta{display:flex;flex-direction:column;gap:4px;min-width:0;color:var(--dsw-alias-label-tertiary);font-size:11px}.foggy-setting-meta code{overflow-wrap:anywhere;color:var(--dsw-alias-label-secondary)}
+      .foggy-update-banner{border:1px solid color-mix(in srgb,var(--dsw-alias-state-warning-primary) 55%,var(--dsw-alias-border-l2));background:color-mix(in srgb,var(--dsw-alias-state-warning-primary) 9%,transparent);border-radius:10px;padding:11px 13px;color:var(--dsw-alias-label-primary);font-size:12px;line-height:18px}.foggy-update-banner strong{color:var(--dsw-alias-state-warning-primary)}.foggy-update-list{margin:6px 0 0;padding-left:18px;color:var(--dsw-alias-label-secondary)}
+      .foggy-resources{border-top:1px solid var(--dsw-alias-border-l2);padding-top:14px}.foggy-resources h4{margin:0 0 9px;font-size:13px}.foggy-resource-links{display:flex;gap:8px;flex-wrap:wrap}.foggy-resource-link{display:inline-flex;align-items:center;gap:5px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:7px 10px;color:var(--dsw-alias-label-secondary);font-size:12px;text-decoration:none}.foggy-resource-link:hover{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}.foggy-resource-link:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:2px}
       .foggy-error-panel{border:2px solid var(--dsw-alias-state-error-primary);background:color-mix(in srgb,var(--dsw-alias-state-error-primary) 10%,var(--dsw-alias-bg-layer-3));border-radius:10px;padding:13px 14px;box-shadow:0 6px 18px color-mix(in srgb,var(--dsw-alias-state-error-primary) 13%,transparent)}.foggy-error-panel-head{display:flex;align-items:center;gap:8px;color:var(--dsw-alias-state-error-primary);font-size:14px;font-weight:700}.foggy-error-icon{display:grid;place-items:center;width:22px;height:22px;border-radius:50%;background:var(--dsw-alias-state-error-primary);color:white;font-size:14px}.foggy-error-panel p{margin:7px 0 0;color:var(--dsw-alias-label-primary);font-size:13px;line-height:20px;overflow-wrap:anywhere}.foggy-error-help{color:var(--dsw-alias-state-error-primary)!important;font-weight:600}
       .foggy-message{margin:0;font-size:13px;line-height:20px;color:var(--dsw-alias-label-secondary)}.foggy-message[data-error=true]{color:var(--dsw-alias-state-error-primary)}.foggy-paths,.foggy-next,.foggy-section{border-top:1px solid var(--dsw-alias-border-l2);padding-top:14px}.foggy-paths h4,.foggy-next h4,.foggy-section h4{margin:0 0 8px;font-size:13px}.foggy-paths dl{display:grid;grid-template-columns:100px minmax(0,1fr);gap:6px 10px;margin:0}.foggy-paths dt{color:var(--dsw-alias-label-tertiary);font-size:12px}.foggy-paths dd{margin:0;min-width:0;overflow-wrap:anywhere;font-family:var(--ds-font-family-code);font-size:11px}.foggy-next p,.foggy-section p{margin:0;color:var(--dsw-alias-label-secondary);font-size:13px;line-height:20px}.foggy-section-actions{display:flex;gap:8px;flex-wrap:wrap;margin-top:10px}.foggy-onboarding-head{display:flex;justify-content:space-between;gap:12px;align-items:start}.foggy-onboarding-head code{font-size:11px;color:var(--dsw-alias-label-tertiary);overflow-wrap:anywhere}.foggy-step-list{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:7px;margin-top:10px}.foggy-step{border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:8px;font-size:11px;color:var(--dsw-alias-label-tertiary)}.foggy-step[data-state=completed]{border-color:color-mix(in srgb,var(--dsw-alias-state-success-primary) 45%,var(--dsw-alias-border-l2));color:var(--dsw-alias-state-success-primary)}.foggy-step[data-state=failed],.foggy-step[data-state=invalid]{border-color:var(--dsw-alias-state-error-primary);color:var(--dsw-alias-state-error-primary)}.foggy-warning{border:1px solid color-mix(in srgb,var(--dsw-alias-state-warning-primary) 55%,var(--dsw-alias-border-l2));background:color-mix(in srgb,var(--dsw-alias-state-warning-primary) 8%,transparent);border-radius:10px;padding:12px}.foggy-query-warning{margin-top:10px}.foggy-query-warning p+p{margin-top:5px}.foggy-query-warning code{overflow-wrap:anywhere}
-      @media (width<=680px){.foggy-grid{grid-template-columns:minmax(0,1fr)}.foggy-runtime-settings-row{grid-template-columns:minmax(0,1fr)}.foggy-runtime-settings-row .foggy-button{width:100%}}
+      @media (width<=680px){.foggy-grid{grid-template-columns:minmax(0,1fr)}.foggy-runtime-settings-row{grid-template-columns:minmax(0,1fr)}.foggy-runtime-settings-row .foggy-button{width:100%}.foggy-toolbar-main{width:100%}.foggy-toolbar-main .foggy-button{flex:1}.foggy-resource-link{min-height:36px}}
     `
 
     if (typeof document !== 'undefined' && !document.querySelector('style[data-foggy-settings]')) {
@@ -295,16 +335,23 @@ window.__ModuleLoader__.load({
 
     function componentCard(label, component, kind, t) {
       const available = kind === 'runtime' ? component?.installed : component?.available
-      const stateText = kind === 'runtime'
-        ? t(available ? 'installed' : 'missing')
-        : t(available ? 'available' : 'unavailable')
+      const stateText = component?.updateAvailable
+        ? t('updateAvailable')
+        : 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?.installedVersion
+          ? `${t('installedVersion')} ${component.installedVersion}`
+          : component?.version || component?.output || '—',
+        component?.targetVersion && component?.targetVersion !== component?.installedVersion
+          ? `${t('targetVersion')} ${component.targetVersion}`
+          : null,
         component?.minimum ? `≥${component.minimum}` : null,
         source,
       ].filter(Boolean).join(' · ')
@@ -321,6 +368,19 @@ window.__ModuleLoader__.load({
       })
     }
 
+    const componentLabels = {
+      cli: 'cli',
+      launcher: 'launcher',
+      analysisSkill: 'analysisSkill',
+      semanticQuerySkill: 'semanticQuerySkill',
+    }
+
+    function updateSummary(status, t) {
+      return Object.entries(status?.components || {})
+        .filter(([key, component]) => componentLabels[key] && component?.updateAvailable)
+        .map(([key, component]) => `${t(componentLabels[key])}: ${component.installedVersion || '—'} → ${component.targetVersion}`)
+    }
+
     function progressPanel(progress, t) {
       if (!progress) return null
       const percent = Math.max(0, Math.min(100, Number(progress.percent) || 0))
@@ -443,6 +503,7 @@ window.__ModuleLoader__.load({
       const [view, setView] = useState({ phase: 'loading', status: null, message: '', error: false, errorCode: null })
       const [portDraft, setPortDraft] = useState('')
       const [portDirty, setPortDirty] = useState(false)
+      const [sequenceBusy, setSequenceBusy] = useState(false)
 
       const refresh = useCallback(async () => {
         setView((current) => ({ ...current, phase: current.status ? 'ready' : 'loading', error: false }))
@@ -469,6 +530,7 @@ window.__ModuleLoader__.load({
       }, [refresh, view.status?.operation?.state])
 
       const run = async (method) => {
+        setSequenceBusy(true)
         setView((current) => ({ ...current, message: t('working'), error: false, errorCode: null }))
         try {
           const result = unwrap(await api[method](), method)
@@ -481,6 +543,44 @@ window.__ModuleLoader__.load({
           await refresh()
         } catch (error) {
           setView((current) => ({ ...current, message: `${t('actionFailed')}: ${String(error.message || error)}`, error: true, errorCode: 'REMOTE_ERROR' }))
+        } finally {
+          setSequenceBusy(false)
+        }
+      }
+
+      const waitForOperation = async (operationId) => {
+        for (let attempt = 0; attempt < 900; attempt += 1) {
+          const status = unwrap(await api.status(), 'status')
+          const operation = status.operation
+          if (operation?.id === operationId && operation.state !== 'running') return status
+          await new Promise((resolve) => setTimeout(resolve, 1000))
+        }
+        throw new Error(t('operationTimeout'))
+      }
+
+      const runSequence = async (methods, successMessage) => {
+        setSequenceBusy(true)
+        setView((current) => ({ ...current, message: t('working'), error: false, errorCode: null }))
+        try {
+          for (const method of methods) {
+            const result = unwrap(await api[method](), method)
+            if (result.success === false) {
+              setView((current) => ({ ...current, message: result.error?.message || t('actionFailed'), error: true, errorCode: result.error?.code || null }))
+              return
+            }
+            if (result.accepted && result.operation?.id) {
+              const completed = await waitForOperation(result.operation.id)
+              if (completed.operation?.state === 'failed') {
+                throw new Error(completed.operation.error || completed.operation.result?.error?.message || t('actionFailed'))
+              }
+            }
+          }
+          setView((current) => ({ ...current, message: successMessage, error: false, errorCode: null }))
+        } catch (error) {
+          setView((current) => ({ ...current, message: `${t('actionFailed')}: ${String(error.message || error)}`, error: true, errorCode: 'REMOTE_ERROR' }))
+        } finally {
+          setSequenceBusy(false)
+          await refresh()
         }
       }
 
@@ -513,7 +613,7 @@ window.__ModuleLoader__.load({
       ] })
 
       const status = view.status
-      const busy = status.operation?.state === 'running'
+      const busy = sequenceBusy || status.operation?.state === 'running'
       const portNumber = Number(portDraft)
       const portValid = Number.isInteger(portNumber) && portNumber >= 1024 && portNumber <= 65535
       const operationError = status.operation?.state === 'failed'
@@ -545,29 +645,57 @@ window.__ModuleLoader__.load({
         ? t('portUnavailableHelp')
         : alertCode === 'RUNTIME_PORT_INVALID'
           ? t('portInvalidHelp')
+          : alertCode === 'RUNTIME_RUNNING_UPDATE_REQUIRES_STOP'
+            ? t('updateBlockedRunning')
           : ''
       const progress = busy ? progressPanel(status.operation?.progress, t) : null
+      const pendingUpdates = updateSummary(status, t)
+      const hasPendingUpdates = pendingUpdates.length > 0
       const stateLabels = { 'not-installed': 'notInstalled', degraded: 'degraded', ready: 'ready', running: 'running' }
       return jsxs('section', { className: 'foggy-settings', children: [
         jsxs('div', { className: 'foggy-hero', children: [
           jsxs('div', { className: 'foggy-title-row', children: [jsx('h3', { children: t('title') }), jsx('span', { className: 'foggy-beta', children: t('beta') })] }),
           jsx('p', { className: 'foggy-intro', children: t('intro') }),
         ] }),
+        jsxs('div', { className: 'foggy-resources', children: [
+          jsx('h4', { children: t('resourceTitle') }),
+          jsxs('div', { className: 'foggy-resource-links', children: [
+            jsx('a', { className: 'foggy-resource-link', href: 'https://github.com/foggy-projects/foggy-deepseek-harness-plugin#readme', target: '_blank', rel: 'noreferrer noopener', title: t('openExternal'), children: t('docs') }),
+            jsx('a', { className: 'foggy-resource-link', href: 'https://github.com/foggy-projects/foggy-deepseek-harness-plugin', target: '_blank', rel: 'noreferrer noopener', title: t('openExternal'), children: t('project') }),
+            jsx('a', { className: 'foggy-resource-link', href: 'https://github.com/foggy-projects/foggy-deepseek-harness-plugin/releases', target: '_blank', rel: 'noreferrer noopener', title: t('openExternal'), children: t('releases') }),
+            jsx('a', { className: 'foggy-resource-link', href: 'https://github.com/f-projects/foggy-data-mcp-bridge', target: '_blank', rel: 'noreferrer noopener', title: t('openExternal'), children: t('runtimeProject') }),
+          ] }),
+        ] }),
         jsxs('div', { className: 'foggy-toolbar', children: [
-          jsxs('div', { className: 'foggy-state', children: [jsx('span', { className: 'foggy-dot', 'data-state': status.state }), jsx('span', { children: t(stateLabels[status.state] || 'notInstalled') })] }),
-          jsxs('div', { className: 'foggy-actions', children: [
+          jsxs('div', { className: 'foggy-state', children: [jsx('span', { className: 'foggy-dot', 'data-state': status.state }), jsx('span', { children: `${t(stateLabels[status.state] || 'notInstalled')}${hasPendingUpdates ? ` · ${t('updateAvailable')}` : ''}` })] }),
+          jsxs('div', { className: 'foggy-toolbar-main', children: [
+            status.state === 'not-installed'
+              ? jsx('button', { className: 'foggy-button foggy-button-primary', type: 'button', disabled: busy, onClick: () => runSequence(['initializeAndStart'], t('initializeAndStartDone')), children: t('initializeAndStart') })
+              : status.running
+                ? jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('runtimeStop'), children: t('stop') })
+                : hasPendingUpdates && status.components.java.available
+                  ? jsx('button', { className: 'foggy-button foggy-button-primary', type: 'button', disabled: busy, onClick: () => runSequence(['updateComponents', 'runtimeStart'], t('updateAndStartDone')), children: t('updateAndStart') })
+                  : status.installed && status.components.java.available
+                    ? jsx('button', { className: 'foggy-button foggy-button-primary', type: 'button', disabled: busy, onClick: () => run('runtimeStart'), children: t('start') })
+                    : jsx('button', { className: 'foggy-button foggy-button-primary', type: 'button', disabled: busy, onClick: () => run('updateComponents'), children: t('updateComponents') }),
+          ] }),
+          jsxs('div', { className: 'foggy-toolbar-secondary', children: [
             jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: refresh, children: t('refresh') }),
             jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('diagnostics'), children: t('diagnostics') }),
-            status.state === 'not-installed' ? jsx('button', { className: 'foggy-button foggy-button-primary', type: 'button', disabled: busy, onClick: () => run('initialize'), children: t('initialize') }) : null,
-            status.state !== 'not-installed' ? jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('repair'), children: t('repair') }) : null,
-            status.installed && !status.running && status.components.java.available ? jsx('button', { className: 'foggy-button foggy-button-primary', type: 'button', disabled: busy, onClick: () => run('runtimeStart'), children: t('start') }) : null,
-            status.running ? jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('runtimeStop'), children: t('stop') }) : null,
+            status.state !== 'not-installed' && !status.running && hasPendingUpdates
+              ? jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('updateComponents'), children: t('updateComponents') })
+              : null,
           ] }),
         ] }),
         errorPanel(alertTitle, alertMessage, alertHelp),
         progress,
         busy ? jsx('p', { className: 'foggy-message', children: t('working') }) : null,
         !busy && view.message && !view.error && !operationError ? jsx('p', { className: 'foggy-message', children: view.message }) : null,
+        !busy && hasPendingUpdates ? jsxs('div', { className: 'foggy-update-banner', role: 'status', children: [
+          jsx('strong', { children: t('updateAvailable') }),
+          jsx('span', { children: ` · ${status.running ? t('updateBlockedRunning') : t('updateReady')}` }),
+          jsx('ul', { className: 'foggy-update-list', children: pendingUpdates.map((item) => jsx('li', { children: item }, item)) }),
+        ] }) : null,
         jsxs('div', { className: 'foggy-runtime-settings', children: [
           jsx('h4', { children: t('runtimeSettingsTitle') }),
           jsxs('div', { className: 'foggy-runtime-settings-row', children: [
@@ -617,11 +745,11 @@ 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') }),
-            jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('repairSemanticQuerySkill'), children: t('repairSemanticQuerySkill') }),
+            jsx('button', { className: 'foggy-button', type: 'button', disabled: busy || status.running, title: status.running ? t('updateBlockedRunning') : undefined, onClick: () => run('repairPython'), children: t('repairPython') }),
+            jsx('button', { className: 'foggy-button', type: 'button', disabled: busy || status.running, title: status.running ? t('updateBlockedRunning') : undefined, onClick: () => run('repairCli'), children: t('repairCli') }),
+            jsx('button', { className: 'foggy-button', type: 'button', disabled: busy || status.running, title: status.running ? t('updateBlockedRunning') : undefined, onClick: () => run('repairLauncher'), children: t('repairLauncher') }),
+            jsx('button', { className: 'foggy-button', type: 'button', disabled: busy || status.running, title: status.running ? t('updateBlockedRunning') : undefined, onClick: () => run('repairAnalysisSkill'), children: t('repairAnalysisSkill') }),
+            jsx('button', { className: 'foggy-button', type: 'button', disabled: busy || status.running, title: status.running ? t('updateBlockedRunning') : undefined, onClick: () => run('repairSemanticQuerySkill'), children: t('repairSemanticQuerySkill') }),
           ] }),
         ] }),
         status.profileMigration?.pendingCount || status.profileMigration?.conflictCount ? jsxs('div', { className: 'foggy-warning', children: [

package/lib/index.js

@@ -45,6 +45,18 @@ function defaultRoots() {
   }
 }
 
+function componentReleaseState({ installed, installedVersion, targetVersion }) {
+  const normalizedInstalled = installedVersion || null
+  const normalizedTarget = targetVersion || null
+  const updateAvailable = Boolean(installed && normalizedInstalled && normalizedTarget && normalizedInstalled !== normalizedTarget)
+  return {
+    installed: Boolean(installed && !updateAvailable),
+    installedVersion: normalizedInstalled,
+    targetVersion: normalizedTarget,
+    updateAvailable,
+  }
+}
+
 async function exists(path) {
   try {
     await access(path, fsConstants.F_OK)
@@ -66,6 +78,22 @@ async function readOptionalJson(path) {
   }
 }
 
+async function runtimeRunningUpdateGuard() {
+  const roots = defaultRoots()
+  const runtime = await readOptionalJson(join(roots.dataRoot, 'runtime-state.json'))
+  if (runtime && processRunning(Number(runtime.pid))) {
+    return {
+      success: false,
+      accepted: false,
+      error: {
+        code: 'RUNTIME_RUNNING_UPDATE_REQUIRES_STOP',
+        message: 'Stop Foggy Runtime before updating or repairing managed components.',
+      },
+    }
+  }
+  return null
+}
+
 async function commandVersion(command, args) {
   try {
     const { stdout, stderr } = await execFileAsync(command, args, {
@@ -232,32 +260,50 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     const onboardingSkillPath = join(packageRoot, 'skills', 'foggy-deepseek-onboarding')
     const analysisMarker = await readOptionalJson(join(analysisSkillPath, '.foggy-managed-skill.json'))
     const semanticQueryMarker = await readOptionalJson(join(semanticQuerySkillPath, '.foggy-managed-skill.json'))
+    const cliPresent = Boolean(cliPath && await exists(cliPath))
+    const launcherPresent = Boolean(launcherPath && await exists(launcherPath))
+    const analysisSkillPresent = await exists(join(analysisSkillPath, 'SKILL.md'))
+      && analysisMarker?.schemaVersion === 'foggy-managed-skill/v1'
+    const semanticQuerySkillPresent = await exists(join(semanticQuerySkillPath, 'SKILL.md'))
+      && semanticQueryMarker?.schemaVersion === 'foggy-managed-skill/v1'
+    const cliRelease = componentReleaseState({
+      installed: cliPresent,
+      installedVersion: state?.cli?.version,
+      targetVersion: manifest.components.cli.version,
+    })
+    const launcherRelease = componentReleaseState({
+      installed: launcherPresent,
+      installedVersion: state?.launcher?.version,
+      targetVersion: manifest.components.launcher.version,
+    })
+    const analysisRelease = componentReleaseState({
+      installed: analysisSkillPresent,
+      installedVersion: analysisMarker?.componentVersion || state?.skills?.analysis?.version,
+      targetVersion: manifest.components.analysisSkill.version,
+    })
+    const semanticQueryRelease = componentReleaseState({
+      installed: semanticQuerySkillPresent,
+      installedVersion: semanticQueryMarker?.componentVersion || state?.skills?.semanticQuery?.version,
+      targetVersion: manifest.components.semanticQuerySkill.version,
+    })
     const components = {
       python,
       java,
       cli: {
-        installed: Boolean(cliPath && await exists(cliPath)),
-        version: state?.cli?.version ?? manifest.components.cli.version,
+        ...cliRelease,
+        version: cliRelease.installedVersion ?? manifest.components.cli.version,
       },
       launcher: {
-        installed: Boolean(launcherPath && await exists(launcherPath)),
-        version: state?.launcher?.version ?? manifest.components.launcher.version,
+        ...launcherRelease,
+        version: launcherRelease.installedVersion ?? manifest.components.launcher.version,
       },
       analysisSkill: {
-        installed: Boolean(
-          await exists(join(analysisSkillPath, 'SKILL.md'))
-          && analysisMarker?.schemaVersion === 'foggy-managed-skill/v1'
-          && analysisMarker?.componentVersion === manifest.components.analysisSkill.version
-        ),
-        version: state?.skills?.analysis?.version ?? manifest.components.analysisSkill.version,
+        ...analysisRelease,
+        version: analysisRelease.installedVersion ?? manifest.components.analysisSkill.version,
       },
       semanticQuerySkill: {
-        installed: Boolean(
-          await exists(join(semanticQuerySkillPath, 'SKILL.md'))
-          && semanticQueryMarker?.schemaVersion === 'foggy-managed-skill/v1'
-          && semanticQueryMarker?.componentVersion === manifest.components.semanticQuerySkill.version
-        ),
-        version: state?.skills?.semanticQuery?.version ?? manifest.components.semanticQuerySkill.version,
+        ...semanticQueryRelease,
+        version: semanticQueryRelease.installedVersion ?? manifest.components.semanticQuerySkill.version,
       },
       onboardingSkill: {
         installed: await exists(join(onboardingSkillPath, 'SKILL.md')),
@@ -271,6 +317,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       && components.analysisSkill.installed
       && components.semanticQuerySkill.installed
       && components.onboardingSkill.installed
+    const updateAvailable = Object.values(components).some((component) => component?.updateAvailable)
     const running = Boolean(runtime && processRunning(Number(runtime.pid)))
     const activePort = running && Number.isInteger(Number(runtime?.port)) ? Number(runtime.port) : null
     const progress = await readOptionalJson(progressPath)
@@ -294,6 +341,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       packageVersion: manifest.packageVersion,
       state: running ? 'running' : installed ? 'ready' : state ? 'degraded' : 'not-installed',
       installed,
+      updateAvailable,
       running,
       runtimeUrl: running ? runtime.runtimeUrl ?? null : null,
       runtimeSettings: {
@@ -309,7 +357,13 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       operation,
       onboarding,
       profileMigration,
-      next: installed ? (running ? 'configure-database' : 'start-runtime') : 'initialize',
+      next: !state
+        ? 'initialize'
+        : updateAvailable
+          ? 'update-components'
+          : installed
+            ? (running ? 'configure-database' : 'start-runtime')
+            : 'repair',
     }
   }
 
@@ -337,27 +391,96 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     return this.startOperation('initialize', false)
   }
 
+  async initializeAndStart() {
+    const status = await this.status()
+    if (status.state !== 'not-installed') {
+      return {
+        success: false,
+        accepted: false,
+        error: { code: 'FOGGY_ALREADY_INITIALIZED', message: 'Foggy is already initialized; use Start Runtime or Update components.' },
+      }
+    }
+    return this.startOperation('initialize-and-start', false, undefined, async ({ operation, progressPath, pythonProgress }) => {
+      await assertSystemPrerequisites('initialize')
+      const cacheArgs = (process.env.FOGGY_ASSET_CACHE_DIRS || '').split(delimiter).filter(Boolean)
+        .flatMap((cacheDir) => ['--asset-cache-dir', cacheDir])
+      const install = await runOnboarding([
+        'install', '--progress-file', progressPath, '--operation-id', operation.id, '--operation-kind', 'initialize',
+        ...cacheArgs,
+      ], 15 * 60_000, {
+        ensurePython: true,
+        onPythonProgress: (detail) => pythonProgress?.update(detail),
+        flushPythonProgress: () => pythonProgress?.flush(),
+      })
+      if (install.success === false) return install
+
+      await assertSystemPrerequisites('runtime-start')
+      const roots = defaultRoots()
+      const manifest = await readJson(versionsFile)
+      const settings = await readRuntimeSettings(roots.dataRoot, {
+        defaultPort: manifest.defaults?.port ?? DEFAULT_RUNTIME_PORT,
+      })
+      if (!settings.valid) {
+        return {
+          success: false,
+          error: { code: 'RUNTIME_SETTINGS_INVALID', message: `Runtime settings are invalid: ${settings.error}` },
+        }
+      }
+      return runOnboarding([
+        'runtime-start', '--install-root', roots.installRoot, '--data-root', roots.dataRoot,
+        '--port', String(settings.port), '--progress-file', progressPath, '--operation-id', operation.id,
+        '--operation-kind', 'runtime-start',
+      ], 15 * 60_000, { ensurePython: false })
+    })
+  }
+
   async repair() {
+    const blocked = await runtimeRunningUpdateGuard()
+    if (blocked) return blocked
     return this.startOperation('repair', true)
   }
 
+  async updateComponents() {
+    const blocked = await runtimeRunningUpdateGuard()
+    if (blocked) return blocked
+    const status = await this.status()
+    if (status.state === 'not-installed') {
+      return {
+        success: false,
+        accepted: false,
+        error: { code: 'FOGGY_NOT_INITIALIZED', message: 'Initialize Foggy before updating managed components.' },
+      }
+    }
+    return this.startOperation('update-components', true)
+  }
+
   async repairCli() {
+    const blocked = await runtimeRunningUpdateGuard()
+    if (blocked) return blocked
     return this.startOperation('repair-cli', false, ['install', '--repair-component', 'cli'])
   }
 
   async repairPython() {
+    const blocked = await runtimeRunningUpdateGuard()
+    if (blocked) return blocked
     return this.startOperation('repair-python', false, ['install'])
   }
 
   async repairLauncher() {
+    const blocked = await runtimeRunningUpdateGuard()
+    if (blocked) return blocked
     return this.startOperation('repair-launcher', false, ['install', '--repair-component', 'launcher'])
   }
 
   async repairAnalysisSkill() {
+    const blocked = await runtimeRunningUpdateGuard()
+    if (blocked) return blocked
     return this.startOperation('repair-analysis-skill', true, ['install', '--repair-component', 'analysis-skill'])
   }
 
   async repairSemanticQuerySkill() {
+    const blocked = await runtimeRunningUpdateGuard()
+    if (blocked) return blocked
     return this.startOperation('repair-semantic-query-skill', true, ['install', '--repair-component', 'semantic-query-skill'])
   }
 
@@ -459,22 +582,22 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     }
   }
 
-  startOperation(kind, replaceSkill, explicitArgs) {
+  startOperation(kind, replaceSkill, explicitArgs, runner = null) {
     if (this.operation?.state === 'running') {
       return { success: false, accepted: false, operation: operationView(this.operation), error: 'another Foggy operation is running' }
     }
     const id = `${Date.now()}-${Math.random().toString(16).slice(2, 10)}`
     const args = explicitArgs ?? ['install']
-    const reportsProgress = args[0] === 'install' || args[0] === 'runtime-start'
+    const reportsProgress = args[0] === 'install' || args[0] === 'runtime-start' || runner !== null
+    const progressPath = reportsProgress ? join(defaultRoots().dataRoot, 'operation-progress.json') : null
     if (reportsProgress) {
-      const roots = defaultRoots()
-      args.push('--progress-file', join(roots.dataRoot, 'operation-progress.json'), '--operation-id', id, '--operation-kind', kind)
+      args.push('--progress-file', progressPath, '--operation-id', id, '--operation-kind', kind)
     }
     if (replaceSkill) args.push('--replace-skill')
     for (const cacheDir of (process.env.FOGGY_ASSET_CACHE_DIRS || '').split(delimiter).filter(Boolean)) {
       args.push('--asset-cache-dir', cacheDir)
     }
-    const runtimeStart = kind === 'runtime-start'
+    const runtimeStart = kind === 'runtime-start' || kind.endsWith('-and-start')
     const operation = {
       id,
       kind,
@@ -497,10 +620,11 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       promise: null,
     }
     const pythonProgress = reportsProgress
-      ? createPythonProgressReporter(operation, join(defaultRoots().dataRoot, 'operation-progress.json'))
+      ? createPythonProgressReporter(operation, progressPath)
       : null
     operation.promise = (async () => {
       await assertSystemPrerequisites(kind)
+      if (runner) return runner({ operation, progressPath, pythonProgress })
       return runOnboarding(args, 15 * 60_000, {
         ensurePython: true,
         forcePython: kind === 'repair-python',
@@ -545,7 +669,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
 
 const markerInitializers = []
 for (const method of [
-  'status', 'plan', 'initialize', 'repair', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill', 'repairSemanticQuerySkill',
+  'status', 'plan', 'initialize', 'initializeAndStart', 'repair', 'updateComponents', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill', 'repairSemanticQuerySkill',
   'migrateProfiles', 'diagnostics', 'runtimeStart', 'runtimeStop',
   'saveRuntimeSettings',
 ]) {

package/lib/remote-descriptor.js

@@ -26,7 +26,9 @@ export const descriptors = [
   descriptor('status'),
   descriptor('plan'),
   descriptor('initialize'),
+  descriptor('initializeAndStart'),
   descriptor('repair'),
+  descriptor('updateComponents'),
   descriptor('repairPython'),
   descriptor('repairSemanticQuerySkill'),
   descriptor('runtimeStart'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foggy-projects/deepseek-harness-plugin",
-  "version": "0.4.0-rc.2",
+  "version": "0.4.0-rc.3",
   "description": "Foggy Java data analysis engine integration for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
@@ -21,6 +21,7 @@
     "experience/linux/**",
     "docs/PUBLIC-BETA-READINESS.md",
     "docs/RELEASE-CANDIDATE-0.4.0-RC.2.md",
+    "docs/RELEASE-CANDIDATE-0.4.0-RC.3.md",
     "docs/WINDOWS-BETA-ACCEPTANCE.md",
     "THIRD-PARTY-RUNTIME-NOTICES.md",
     "README.md"

package/skills/foggy-deepseek-onboarding/assets/versions.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "foggy-deepseek-onboarding-versions/v1",
-  "packageVersion": "0.4.0-rc.2",
+  "packageVersion": "0.4.0-rc.3",
   "validatedAt": "2026-09-06",
   "components": {
     "deepseekHarness": {