@foggy-projects/deepseek-harness-plugin 0.4.0-beta.8 → 0.4.0-rc.1

package/lib/client.js

@@ -8,25 +8,47 @@ window.__ModuleLoader__.load({
 
     const NS = 'settings.foggy'
     const passthroughSchema = { parse: (value) => value }
+    const runtimeSettingsInputSchema = {
+      parse: (value) => {
+        const port = value?.port
+        if (!Number.isInteger(port) || port < 1024 || port > 65535 || Object.keys(value || {}).some((key) => key !== 'port')) {
+          throw new Error('Runtime port must be an integer between 1024 and 65535')
+        }
+        return { port }
+      },
+    }
+    const descriptor = (method, parameters = []) => ({
+      id: `@foggy-projects/deepseek-harness-plugin#foggyIntegration/${method}`,
+      service: 'foggyIntegration',
+      namespace: 'foggyIntegration',
+      method,
+      invocation: { kind: 'direct' },
+      parameters,
+      result: {
+        mode: 'strict',
+        typeSymbol: '@foggy-projects/deepseek-harness-plugin#FoggyIntegrationResult',
+        schema: passthroughSchema,
+      },
+      sourceLocation: { file: 'lib/index.js', line: 1, column: 1 },
+    })
     const TYPERT_REMOTE = {
       package: '@foggy-projects/deepseek-harness-plugin',
       descriptors: [
+        ...[
         'status', 'plan', 'initialize', 'repair', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill',
         'migrateProfiles', 'diagnostics', 'runtimeStart', 'runtimeStop',
-      ].map((method) => ({
-        id: `@foggy-projects/deepseek-harness-plugin#foggyIntegration/${method}`,
-        service: 'foggyIntegration',
-        namespace: 'foggyIntegration',
-        method,
-        invocation: { kind: 'direct' },
-        parameters: [],
-        result: {
-          mode: 'strict',
-          typeSymbol: '@foggy-projects/deepseek-harness-plugin#FoggyIntegrationResult',
-          schema: passthroughSchema,
-        },
-        sourceLocation: { file: 'lib/index.js', line: 1, column: 1 },
-      })),
+        ].map((method) => descriptor(method)),
+        descriptor('saveRuntimeSettings', [{
+          name: 'input',
+          wire: 'input',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@foggy-projects/deepseek-harness-plugin#FoggyRuntimeSettingsInput',
+            schema: runtimeSettingsInputSchema,
+          },
+        }]),
+      ],
     }
 
     const zh = {
@@ -73,7 +95,16 @@ window.__ModuleLoader__.load({
       progressSkills: '注册 DSH Skills',
       progressState: '写入安装状态',
       progressComplete: '初始化完成',
+      progressRuntimePreflight: '检查 Runtime 状态',
+      progressRuntimeLauncher: '启动 Java Launcher',
+      progressRuntimeReadiness: '等待 Runtime 就绪',
+      progressRuntimeCapabilities: '验证 Runtime 能力',
+      progressRuntimeState: '保存 Runtime 状态',
+      progressRuntimeComplete: 'Runtime 已就绪',
       progressFiles: '文件',
+      progressElapsed: '已等待',
+      progressTimeout: '最长',
+      progressSeconds: '秒',
       managedPrivate: 'Foggy 私有',
       configuredOverride: '外部指定',
       accepted: '操作已开始；页面会自动刷新状态。',
@@ -90,6 +121,10 @@ window.__ModuleLoader__.load({
       noOnboarding: '尚无数据库引导记录；请在对话中调用 Foggy onboarding Skill。',
       projectRoot: '工作区',
       resumeInChat: '未完成步骤应回到对应工作区，在对话中继续。',
+      queryWarningTitle: '查询输入已自动兼容',
+      queryWarningSummary: 'Runtime 在 WARN 模式下忽略了未知的查询属性，查询仍已执行。请检查告警代码与证据后决定是否修正模型或请求。',
+      queryWarningCodes: '告警代码',
+      queryWarningEvidence: '证据目录',
       stepPlanned: '规划',
       stepDatasourceConfigured: '数据库连接',
       stepDatasourceVerified: '连接验证',
@@ -99,6 +134,21 @@ window.__ModuleLoader__.load({
       stepSemanticPublished: '发布',
       stepSemanticVerified: '首次查询',
       runtimeUrl: 'Runtime 地址',
+      runtimeSettingsTitle: 'Runtime 连接设置',
+      runtimePort: 'Runtime 端口',
+      runtimePortHint: '端口会持久保存，CLI 与 Skill 将使用同一个 Runtime 地址。',
+      configuredRuntimeUrl: '下次启动地址',
+      saveRuntimePort: '保存端口',
+      runtimePortSaved: 'Runtime 端口已保存',
+      stopToChangePort: 'Runtime 运行时不能修改端口，请先停止 Runtime。',
+      errorTitle: 'Foggy 操作失败',
+      portUnavailableTitle: 'Runtime 端口被占用',
+      portUnavailableMessage: '已被其他程序或 Windows 端口代理占用，Runtime 无法启动。',
+      portUnavailableHelp: '请更换端口后保存并重新启动；也可以先释放占用该端口的程序或 Windows 端口代理。',
+      portInvalidTitle: '端口配置无效',
+      portInvalidMessage: '当前值无法保存为 Runtime 端口。',
+      portInvalidHelp: '请输入 1024 到 65535 之间的整数端口。',
+      settingsInvalidTitle: 'Runtime 设置文件异常',
       nextTitle: '后续配置',
       nextCopy: 'Skills 已通过 DeepSeek Harness 原生注册表提供给所有工作区；每个会话直接使用自己的工作目录。Runtime 启动成功后，将继续进入数据库连接与语义层向导。',
       beta: 'Beta',
@@ -148,7 +198,16 @@ window.__ModuleLoader__.load({
       progressSkills: 'Registering DSH Skills',
       progressState: 'Writing install state',
       progressComplete: 'Initialization complete',
+      progressRuntimePreflight: 'Checking Runtime state',
+      progressRuntimeLauncher: 'Starting Java Launcher',
+      progressRuntimeReadiness: 'Waiting for Runtime readiness',
+      progressRuntimeCapabilities: 'Verifying Runtime capabilities',
+      progressRuntimeState: 'Saving Runtime state',
+      progressRuntimeComplete: 'Runtime ready',
       progressFiles: 'files',
+      progressElapsed: 'elapsed',
+      progressTimeout: 'timeout',
+      progressSeconds: 's',
       managedPrivate: 'Foggy private',
       configuredOverride: 'Configured override',
       accepted: 'The operation started; this page will refresh automatically.',
@@ -165,6 +224,10 @@ window.__ModuleLoader__.load({
       noOnboarding: 'No database onboarding record yet. Invoke the Foggy onboarding Skill in a conversation.',
       projectRoot: 'Workspace',
       resumeInChat: 'Resume incomplete steps from a conversation in the matching workspace.',
+      queryWarningTitle: 'Query input was normalized',
+      queryWarningSummary: 'In WARN mode, Runtime ignored unknown query properties and continued. Review the warning codes and evidence before deciding whether to change the model or request.',
+      queryWarningCodes: 'Warning codes',
+      queryWarningEvidence: 'Evidence directory',
       stepPlanned: 'Plan',
       stepDatasourceConfigured: 'Database connection',
       stepDatasourceVerified: 'Connection test',
@@ -174,6 +237,21 @@ window.__ModuleLoader__.load({
       stepSemanticPublished: 'Publish',
       stepSemanticVerified: 'First query',
       runtimeUrl: 'Runtime URL',
+      runtimeSettingsTitle: 'Runtime connection settings',
+      runtimePort: 'Runtime port',
+      runtimePortHint: 'The port is persisted so the CLI and Skills use one stable Runtime URL.',
+      configuredRuntimeUrl: 'Next startup URL',
+      saveRuntimePort: 'Save port',
+      runtimePortSaved: 'Runtime port saved',
+      stopToChangePort: 'Stop Runtime before changing its port.',
+      errorTitle: 'Foggy operation failed',
+      portUnavailableTitle: 'Runtime port is already in use',
+      portUnavailableMessage: 'is already used by another application or Windows port proxy, so Runtime cannot start.',
+      portUnavailableHelp: 'Save a different port and start again, or release the application or Windows port proxy using this port.',
+      portInvalidTitle: 'Invalid port setting',
+      portInvalidMessage: 'The current value cannot be saved as the Runtime port.',
+      portInvalidHelp: 'Enter an integer port between 1024 and 65535.',
+      settingsInvalidTitle: 'Runtime settings file is invalid',
       nextTitle: 'Next configuration',
       nextCopy: 'Skills are provided to every workspace through the native DeepSeek Harness registry, and each session uses its own working directory. After Runtime starts, the database connection and semantic-layer wizard comes next.',
       beta: 'Beta',
@@ -188,8 +266,10 @@ window.__ModuleLoader__.load({
       .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-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-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}
-      @media (width<=680px){.foggy-grid{grid-template-columns:minmax(0,1fr)}}
+      .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-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%}}
     `
 
     if (typeof document !== 'undefined' && !document.querySelector('style[data-foggy-settings]')) {
@@ -247,21 +327,33 @@ window.__ModuleLoader__.load({
         'workspace-skills': 'progressSkills',
         state: 'progressState',
         complete: 'progressComplete',
+        'runtime-preflight': 'progressRuntimePreflight',
+        'runtime-launcher': 'progressRuntimeLauncher',
+        'runtime-readiness': 'progressRuntimeReadiness',
+        'runtime-capabilities': 'progressRuntimeCapabilities',
+        'runtime-state': 'progressRuntimeState',
+        'runtime-complete': 'progressRuntimeComplete',
       }
       const phase = t(phaseKeys[progress.phase] || 'progressWorking')
+      const headline = String(progress.phase || '').startsWith('runtime-') ? phase : progress.message || phase
       const step = progress.step?.index && progress.step?.total
         ? `${progress.step.index}/${progress.step.total}`
         : ''
       const files = progress.files?.total
         ? `${progress.files.completed || 0}/${progress.files.total} ${t('progressFiles')}`
         : ''
+      const elapsed = Number(progress.timing?.elapsedSeconds)
+      const timeout = Number(progress.timing?.timeoutSeconds)
+      const timing = Number.isFinite(elapsed)
+        ? `${t('progressElapsed')} ${elapsed}${t('progressSeconds')}${Number.isFinite(timeout) ? ` / ${t('progressTimeout')} ${timeout}${t('progressSeconds')}` : ''}`
+        : ''
       return jsxs('div', {
         className: 'foggy-progress',
         role: 'status',
         'aria-live': 'polite',
         children: [
           jsxs('div', { className: 'foggy-progress-head', children: [
-            jsx('strong', { children: progress.message || phase }),
+            jsx('strong', { children: headline }),
             jsx('span', { className: 'foggy-progress-percent', children: `${percent}%` }),
           ] }),
           jsx('div', {
@@ -275,7 +367,7 @@ window.__ModuleLoader__.load({
           }),
           jsxs('div', { className: 'foggy-progress-meta', children: [
             jsx('span', { children: phase }),
-            jsx('span', { children: [step, files].filter(Boolean).join(' · ') }),
+            jsx('span', { children: [step, files, timing].filter(Boolean).join(' · ') }),
           ] }),
           progress.currentFile ? jsx('div', { className: 'foggy-progress-meta foggy-progress-file', title: progress.currentFile, children: progress.currentFile }) : null,
         ],
@@ -313,22 +405,54 @@ window.__ModuleLoader__.load({
           title: profile.steps?.[name]?.status || 'pending',
           children: t(label),
         }, name)) }),
+        profile.warningCount > 0 ? jsxs('div', { className: 'foggy-warning foggy-query-warning', role: 'status', children: [
+          jsx('h4', { children: `${t('queryWarningTitle')} · ${profile.warningCount}` }),
+          jsx('p', { children: t('queryWarningSummary') }),
+          profile.warningCodes?.length ? jsxs('p', { children: [`${t('queryWarningCodes')}: `, jsx('code', { children: profile.warningCodes.join(', ') })] }) : null,
+          profile.warningEvidence ? jsxs('p', { children: [`${t('queryWarningEvidence')}: `, jsx('code', { children: profile.warningEvidence })] }) : null,
+        ] }) : null,
         profile.next?.status !== 'completed' ? jsx('p', { style: { marginTop: '9px' }, children: t('resumeInChat') }) : null,
       ] })
     }
 
+    function errorPanel(title, message, help) {
+      if (!message) return null
+      return jsxs('div', {
+        className: 'foggy-error-panel',
+        role: 'alert',
+        'aria-live': 'assertive',
+        children: [
+          jsxs('div', { className: 'foggy-error-panel-head', children: [
+            jsx('span', { className: 'foggy-error-icon', 'aria-hidden': true, children: '!' }),
+            jsx('strong', { children: title }),
+          ] }),
+          jsx('p', { children: message }),
+          help ? jsx('p', { className: 'foggy-error-help', children: help }) : null,
+        ],
+      })
+    }
+
     function FoggySettingsTab({ api, t }) {
-      const [view, setView] = useState({ phase: 'loading', status: null, message: '', error: false })
+      const [view, setView] = useState({ phase: 'loading', status: null, message: '', error: false, errorCode: null })
+      const [portDraft, setPortDraft] = useState('')
+      const [portDirty, setPortDirty] = useState(false)
 
       const refresh = useCallback(async () => {
         setView((current) => ({ ...current, phase: current.status ? 'ready' : 'loading', error: false }))
         try {
           const status = unwrap(await api.status(), 'status')
-          setView((current) => ({ ...current, phase: 'ready', status, error: false }))
+          setView((current) => ({
+            ...current,
+            phase: 'ready',
+            status,
+            error: false,
+            message: current.message === t('accepted') && status.operation?.state !== 'running' ? '' : current.message,
+          }))
+          if (!portDirty) setPortDraft(String(status.runtimeSettings?.port ?? 18166))
         } catch (error) {
           setView((current) => ({ ...current, phase: current.status ? 'ready' : 'error', message: String(error.message || error), error: true }))
         }
-      }, [api])
+      }, [api, portDirty, t])
 
       useEffect(() => { refresh() }, [refresh])
       useEffect(() => {
@@ -338,18 +462,40 @@ window.__ModuleLoader__.load({
       }, [refresh, view.status?.operation?.state])
 
       const run = async (method) => {
-        setView((current) => ({ ...current, message: t('working'), error: false }))
+        setView((current) => ({ ...current, message: t('working'), error: false, errorCode: null }))
         try {
           const result = unwrap(await api[method](), method)
           const message = result.accepted
             ? t('accepted')
             : result.path
               ? `${t('diagnosticsSaved')}: ${result.path}`
-              : ''
-          setView((current) => ({ ...current, message, error: result.success === false }))
+              : result.error?.message || ''
+          setView((current) => ({ ...current, message, error: result.success === false, errorCode: result.error?.code || null }))
           await refresh()
         } catch (error) {
-          setView((current) => ({ ...current, message: `${t('actionFailed')}: ${String(error.message || error)}`, error: true }))
+          setView((current) => ({ ...current, message: `${t('actionFailed')}: ${String(error.message || error)}`, error: true, errorCode: 'REMOTE_ERROR' }))
+        }
+      }
+
+      const saveRuntimePort = async () => {
+        const port = Number(portDraft)
+        if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+          setView((current) => ({ ...current, message: t('portInvalidMessage'), error: true, errorCode: 'RUNTIME_PORT_INVALID' }))
+          return
+        }
+        setView((current) => ({ ...current, message: t('working'), error: false, errorCode: null }))
+        try {
+          const result = unwrap(await api.saveRuntimeSettings({ port }), 'saveRuntimeSettings')
+          if (result.success === false) {
+            setView((current) => ({ ...current, message: result.error?.message || t('actionFailed'), error: true, errorCode: result.error?.code || null }))
+            return
+          }
+          setPortDirty(false)
+          setPortDraft(String(result.settings.port))
+          setView((current) => ({ ...current, message: `${t('runtimePortSaved')}: ${result.settings.runtimeUrl}`, error: false, errorCode: null }))
+          await refresh()
+        } catch (error) {
+          setView((current) => ({ ...current, message: `${t('actionFailed')}: ${String(error.message || error)}`, error: true, errorCode: 'REMOTE_ERROR' }))
         }
       }
 
@@ -361,9 +507,38 @@ window.__ModuleLoader__.load({
 
       const status = view.status
       const busy = status.operation?.state === 'running'
+      const portNumber = Number(portDraft)
+      const portValid = Number.isInteger(portNumber) && portNumber >= 1024 && portNumber <= 65535
       const operationError = status.operation?.state === 'failed'
         ? status.operation.error || status.operation.result?.error?.message || t('actionFailed')
         : ''
+      const operationErrorCode = status.operation?.state === 'failed' ? status.operation.result?.error?.code || null : null
+      const settingsError = status.runtimeSettings?.valid === false
+        ? status.runtimeSettings.error || t('settingsInvalidTitle')
+        : ''
+      const portConflict = status.runtimeSettings?.conflictApplies ? status.runtimeSettings.lastConflict : null
+      const validationError = portDirty && !portValid ? t('portInvalidMessage') : ''
+      const rawAlertMessage = validationError || (view.error ? view.message : '') || operationError || settingsError || portConflict?.message || ''
+      const alertCode = validationError
+        ? 'RUNTIME_PORT_INVALID'
+        : view.error
+          ? view.errorCode
+          : operationErrorCode || (settingsError ? 'RUNTIME_SETTINGS_INVALID' : portConflict ? 'RUNTIME_PORT_UNAVAILABLE' : null)
+      const alertTitle = alertCode === 'RUNTIME_PORT_UNAVAILABLE'
+        ? t('portUnavailableTitle')
+        : alertCode === 'RUNTIME_PORT_INVALID'
+          ? t('portInvalidTitle')
+          : alertCode === 'RUNTIME_SETTINGS_INVALID'
+            ? t('settingsInvalidTitle')
+            : t('errorTitle')
+      const alertMessage = alertCode === 'RUNTIME_PORT_UNAVAILABLE'
+        ? `${t('runtimePort')} ${portConflict?.port ?? status.runtimeSettings?.port ?? portNumber} ${t('portUnavailableMessage')}`
+        : rawAlertMessage
+      const alertHelp = alertCode === 'RUNTIME_PORT_UNAVAILABLE'
+        ? t('portUnavailableHelp')
+        : alertCode === 'RUNTIME_PORT_INVALID'
+          ? t('portInvalidHelp')
+          : ''
       const progress = busy ? progressPanel(status.operation?.progress, t) : null
       const stateLabels = { 'not-installed': 'notInstalled', degraded: 'degraded', ready: 'ready', running: 'running' }
       return jsxs('section', { className: 'foggy-settings', children: [
@@ -382,8 +557,46 @@ window.__ModuleLoader__.load({
             status.running ? jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('runtimeStop'), children: t('stop') }) : null,
           ] }),
         ] }),
+        errorPanel(alertTitle, alertMessage, alertHelp),
         progress,
-        busy || operationError || view.message ? jsx('p', { className: 'foggy-message', 'data-error': operationError || view.error ? 'true' : undefined, children: busy ? t('working') : operationError || view.message }) : null,
+        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,
+        jsxs('div', { className: 'foggy-runtime-settings', children: [
+          jsx('h4', { children: t('runtimeSettingsTitle') }),
+          jsxs('div', { className: 'foggy-runtime-settings-row', children: [
+            jsxs('div', { className: 'foggy-field', children: [
+              jsx('label', { htmlFor: 'foggy-runtime-port', children: t('runtimePort') }),
+              jsx('input', {
+                id: 'foggy-runtime-port',
+                className: 'foggy-input',
+                type: 'number',
+                min: 1024,
+                max: 65535,
+                step: 1,
+                value: portDraft,
+                disabled: busy || status.running,
+                'aria-invalid': portDirty && !portValid ? 'true' : undefined,
+                onChange: (event) => {
+                  setPortDraft(event.target.value)
+                  setPortDirty(true)
+                  setView((current) => ({ ...current, message: '', error: false, errorCode: null }))
+                },
+              }),
+            ] }),
+            jsxs('div', { className: 'foggy-setting-meta', children: [
+              jsx('span', { children: t('runtimePortHint') }),
+              jsx('code', { children: `${t('configuredRuntimeUrl')}: http://127.0.0.1:${portValid ? portNumber : '—'}` }),
+              status.running ? jsx('span', { children: t('stopToChangePort') }) : null,
+            ] }),
+            jsx('button', {
+              className: 'foggy-button foggy-button-primary',
+              type: 'button',
+              disabled: busy || status.running || !portDirty || !portValid,
+              onClick: saveRuntimePort,
+              children: t('saveRuntimePort'),
+            }),
+          ] }),
+        ] }),
         jsxs('div', { className: 'foggy-grid', children: [
           componentCard(t('python'), status.components.python, 'tool', t),
           componentCard(t('java'), status.components.java, 'tool', t),

package/lib/diagnostics.js

@@ -0,0 +1,86 @@
+import { open } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+const DEFAULT_MAX_BYTES = 32 * 1024
+const DEFAULT_MAX_LINES = 120
+const ANSI_ESCAPE = /\u001b(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007]*(?:\u0007|\u001b\\))/g
+const BEARER_SECRET = /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi
+const API_KEY_SECRET = /\bsk-[A-Za-z0-9._-]{12,}/g
+const JDBC_URL = /\bjdbc:[^\s"'<>]+/gi
+const URL_CREDENTIALS = /(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi
+const SENSITIVE_QUERY_VALUE = /([?&](?:password|passwd|pwd|secret|token|api[_-]?key|auth[_-]?code)=)[^&#\s]*/gi
+const SENSITIVE_ASSIGNMENT = /\b([A-Za-z0-9_.-]*(?:password|passwd|pwd|secret|token|api[_-]?key|authorization|auth[_-]?code)[A-Za-z0-9_.-]*)(\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi
+
+export function sanitizeDiagnosticText(value) {
+  return String(value ?? '')
+    .replace(ANSI_ESCAPE, '')
+    .replace(BEARER_SECRET, 'Bearer [REDACTED]')
+    .replace(API_KEY_SECRET, '[REDACTED_API_KEY]')
+    .replace(JDBC_URL, 'jdbc:[REDACTED_CONNECTION_URL]')
+    .replace(URL_CREDENTIALS, '$1[REDACTED]@')
+    .replace(SENSITIVE_QUERY_VALUE, '$1[REDACTED]')
+    .replace(SENSITIVE_ASSIGNMENT, '$1$2[REDACTED]')
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '')
+}
+
+function isInside(root, candidate) {
+  const value = relative(resolve(root), resolve(candidate))
+  return value !== '' && value !== '..' && !value.startsWith(`..${sep}`) && !isAbsolute(value)
+}
+
+export async function readDiagnosticLogTail(path, {
+  allowedRoot,
+  maxBytes = DEFAULT_MAX_BYTES,
+  maxLines = DEFAULT_MAX_LINES,
+} = {}) {
+  if (!path || !allowedRoot || !isInside(allowedRoot, path)) {
+    return { sanitizedTail: '', tailTruncated: false, tailError: 'LOG_PATH_OUTSIDE_RUNTIME_ROOT' }
+  }
+
+  let handle
+  try {
+    handle = await open(path, 'r')
+    const details = await handle.stat()
+    const bytesToRead = Math.min(details.size, maxBytes)
+    const buffer = Buffer.alloc(bytesToRead)
+    if (bytesToRead > 0) await handle.read(buffer, 0, bytesToRead, details.size - bytesToRead)
+    let text = buffer.toString('utf8')
+    let truncated = details.size > bytesToRead
+    if (truncated) {
+      const firstLineEnd = text.indexOf('\n')
+      if (firstLineEnd >= 0) text = text.slice(firstLineEnd + 1)
+    }
+    const lines = text.split(/\r?\n/)
+    if (lines.length > maxLines) {
+      text = lines.slice(-maxLines).join('\n')
+      truncated = true
+    }
+    return {
+      sanitizedTail: sanitizeDiagnosticText(text).trim(),
+      tailTruncated: truncated,
+      tailBytesRead: bytesToRead,
+    }
+  } catch (error) {
+    return {
+      sanitizedTail: '',
+      tailTruncated: false,
+      tailError: error?.code || 'LOG_READ_FAILED',
+    }
+  } finally {
+    await handle?.close()
+  }
+}
+
+export async function enrichRuntimeStartFailure(failure, dataRoot) {
+  if (!failure || typeof failure !== 'object') return failure
+  const runtimeRoot = join(dataRoot, 'runtime')
+  const logs = Array.isArray(failure.logs)
+    ? await Promise.all(failure.logs.map(async (entry) => ({
+        ...entry,
+        ...(entry?.exists && entry?.path
+          ? await readDiagnosticLogTail(entry.path, { allowedRoot: runtimeRoot })
+          : {}),
+      })))
+    : []
+  return { ...failure, logs }
+}