@foggy-projects/deepseek-harness-plugin 0.4.0-beta.10 → 0.4.0-beta.12

package/README.md

@@ -14,7 +14,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-beta.10.tgz
+dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.0-beta.12.tgz
 ```
 
 Restart `dsh web`, use the browser it opens (or the complete printed URL,

package/docs/PUBLIC-BETA-READINESS.md

@@ -1,10 +1,10 @@
-# Public beta readiness: 0.4.0-beta.10
+# Public beta readiness: 0.4.0-beta.12
 
 Assessment date: 2026-09-04
 
 ## Verdict
 
-`0.4.0-beta.10` is suitable for a scoped public beta on Windows 10/11 x64 and
+`0.4.0-beta.12` 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
@@ -21,13 +21,18 @@ system PATH, registry, or a user's existing Python installation.
 - The component installer code is unchanged from beta.9, whose Windows x64 run
   completed a cold Python download, checksum verification, extraction,
   initialization, forced Python repair, and doctor run.
-- DeepSeek Harness `0.1.2-rc.1` loaded the beta.10 candidate Bundle, web client,
+- DeepSeek Harness `0.1.2-rc.1` loaded the beta.12 candidate Bundle, web client,
   remote status service, and native Skill provider on both Windows and WSL2.
 - WSL2 reported the existing managed Python, CLI, Launcher, and analysis Skill
   as ready; an isolated Windows profile correctly reported its fresh component
   state and rejected the host's Java 12 as below the Java 17 prerequisite.
 - 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.10 as installed.
+  0.1.18, analysis Skill 0.1.17, and onboarding Skill 0.4.0-beta.12 as installed.
+- Runtime startup now reports the current phase, elapsed/timeout seconds, and a
+  bounded progress value. A real WSL2 launch reached readiness in 13.4 seconds;
+  a forced timeout recorded failure evidence and cleaned up the Java process.
+- Diagnostic export success remains visible alongside a prior Runtime startup
+  error, including the generated local JSON path.
 - 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

package/docs/WINDOWS-BETA-ACCEPTANCE.md

@@ -1,7 +1,7 @@
 # Native Windows Beta acceptance
 
 This runbook validates DeepSeek Harness `0.1.2-rc.1` with Foggy plugin
-`0.4.0-beta.10` on a clean 64-bit Windows 10 or Windows 11 machine. Use a local
+`0.4.0-beta.12` on a clean 64-bit Windows 10 or Windows 11 machine. Use a local
 directory that is not synchronized by OneDrive.
 
 ## Prerequisites
@@ -49,10 +49,16 @@ Expected component state:
 - CLI 0.1.23;
 - Launcher 0.1.18;
 - analysis Skill 0.1.17;
-- onboarding Skill 0.4.0-beta.10;
+- onboarding Skill 0.4.0-beta.12;
 - Java 17+ available;
 - native DSH Skill registration available.
 
+Runtime startup shows its current phase, elapsed time, and the 180-second
+readiness deadline. Typical startup is 15–30 seconds on the validated WSL2 host
+and may take up to 60 seconds on Windows with cold JVM or antivirus scanning.
+On timeout, export diagnostics before retrying; the report includes the startup
+phase, PID state, evidence directory, and Runtime log locations.
+
 ## Database and semantic-layer acceptance
 
 Keep database credentials out of this public repository. Create a private CLI

package/experience/linux/prepare.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 DSH_VERSION="0.1.2-rc.1"
 PNPM_VERSION="11.7.0"
-PLUGIN_VERSION="0.4.0-beta.10"
+PLUGIN_VERSION="0.4.0-beta.12"
 PLUGIN_REF="v${PLUGIN_VERSION}"
 PLUGIN_REPOSITORY="https://github.com/foggy-projects/foggy-deepseek-harness-plugin.git"
 

package/lib/client.js

@@ -73,7 +73,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: '操作已开始；页面会自动刷新状态。',
@@ -148,7 +157,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.',
@@ -247,21 +265,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 +305,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,
         ],
@@ -383,7 +413,9 @@ window.__ModuleLoader__.load({
           ] }),
         ] }),
         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,
+        operationError ? jsx('p', { className: 'foggy-message', 'data-error': 'true', children: operationError }) : null,
+        !busy && view.message ? jsx('p', { className: 'foggy-message', 'data-error': view.error ? 'true' : undefined, children: view.message }) : null,
         jsxs('div', { className: 'foggy-grid', children: [
           componentCard(t('python'), status.components.python, 'tool', t),
           componentCard(t('java'), status.components.java, 'tool', t),

package/lib/index.js

@@ -131,6 +131,8 @@ async function assertSystemPrerequisites(kind) {
 
 function createPythonProgressReporter(operation, path) {
   let pending = Promise.resolve()
+  const runtimeStart = operation.kind === 'runtime-start'
+  const totalSteps = runtimeStart ? 6 : 7
   return {
     update(detail) {
       const fraction = Math.max(0, Math.min(1, Number(detail.fraction) || 0))
@@ -139,11 +141,11 @@ function createPythonProgressReporter(operation, path) {
         operationId: operation.id,
         kind: operation.kind,
         state: 'running',
-        phase: 'python',
-        message: detail.message || 'Preparing managed Python',
+        phase: runtimeStart ? 'runtime-preflight' : 'python',
+        message: runtimeStart ? 'Preparing the Foggy Runtime controller' : detail.message || 'Preparing managed Python',
         currentFile: detail.currentFile || null,
-        percent: Math.round(((1 + fraction) / 7) * 100),
-        step: { index: 2, total: 7 },
+        percent: runtimeStart ? Math.round(fraction * 3) : Math.round(((1 + fraction) / totalSteps) * 100),
+        step: { index: runtimeStart ? 1 : 2, total: totalSteps },
         startedAt: operation.startedAt,
         updatedAt: new Date().toISOString(),
       }
@@ -348,6 +350,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       components: status.components,
       onboarding: status.onboarding,
       profileMigration: status.profileMigration,
+      lastRuntimeStartFailure: await readOptionalJson(join(roots.dataRoot, 'last-runtime-start-failure.json')),
       doctor,
     }
     const directory = join(roots.dataRoot, 'diagnostics')
@@ -358,11 +361,17 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
   }
 
   async runtimeStart() {
-    return this.startOperation('runtime-start', false, ['runtime-start'])
+    const roots = defaultRoots()
+    return this.startOperation('runtime-start', false, [
+      'runtime-start', '--install-root', roots.installRoot, '--data-root', roots.dataRoot,
+    ])
   }
 
   async runtimeStop() {
-    return this.startOperation('runtime-stop', false, ['runtime-stop'])
+    const roots = defaultRoots()
+    return this.startOperation('runtime-stop', false, [
+      'runtime-stop', '--install-root', roots.installRoot, '--data-root', roots.dataRoot,
+    ])
   }
 
   startOperation(kind, replaceSkill, explicitArgs) {
@@ -371,7 +380,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     }
     const id = `${Date.now()}-${Math.random().toString(16).slice(2, 10)}`
     const args = explicitArgs ?? ['install']
-    const reportsProgress = args[0] === 'install'
+    const reportsProgress = args[0] === 'install' || args[0] === 'runtime-start'
     if (reportsProgress) {
       const roots = defaultRoots()
       args.push('--progress-file', join(roots.dataRoot, 'operation-progress.json'), '--operation-id', id, '--operation-kind', kind)
@@ -380,6 +389,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     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 operation = {
       id,
       kind,
@@ -394,10 +404,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         kind,
         state: 'running',
         phase: 'preflight',
-        message: 'Starting Foggy initialization',
+        message: runtimeStart ? 'Starting Foggy Runtime' : 'Starting Foggy initialization',
         currentFile: null,
         percent: 0,
-        step: { index: 1, total: 7 },
+        step: { index: 1, total: runtimeStart ? 6 : 7 },
       } : null,
       promise: null,
     }
@@ -422,8 +432,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
           operation.progress = {
             ...operation.progress,
             state: operation.state,
-            phase: operation.state === 'succeeded' ? 'complete' : operation.progress.phase,
-            message: operation.state === 'succeeded' ? 'Foggy initialization completed' : 'Foggy initialization failed',
+            phase: operation.state === 'succeeded' ? (runtimeStart ? 'runtime-complete' : 'complete') : operation.progress.phase,
+            message: operation.state === 'succeeded'
+              ? (runtimeStart ? 'Foggy Runtime is ready' : 'Foggy initialization completed')
+              : (runtimeStart ? 'Foggy Runtime startup failed' : 'Foggy initialization failed'),
             percent: operation.state === 'succeeded' ? 100 : operation.progress.percent,
           }
         }
@@ -437,7 +449,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
           operation.progress = {
             ...operation.progress,
             state: 'failed',
-            message: 'Foggy initialization failed',
+            message: runtimeStart ? 'Foggy Runtime startup failed' : 'Foggy initialization failed',
           }
         }
       })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foggy-projects/deepseek-harness-plugin",
-  "version": "0.4.0-beta.10",
+  "version": "0.4.0-beta.12",
   "description": "Foggy Java data analysis engine integration for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "foggy-deepseek-onboarding-versions/v1",
-  "packageVersion": "0.4.0-beta.10",
+  "packageVersion": "0.4.0-beta.12",
   "validatedAt": "2026-09-04",
   "components": {
     "deepseekHarness": {

package/skills/foggy-deepseek-onboarding/scripts/onboarding.py

@@ -48,20 +48,35 @@ ACTIVE_PROGRESS: "ProgressReporter | None" = None
 
 
 class ProgressReporter:
-    total_steps = 7
-
-    def __init__(self, path: str | None, operation_id: str | None, kind: str) -> None:
+    def __init__(
+        self,
+        path: str | None,
+        operation_id: str | None,
+        kind: str,
+        *,
+        total_steps: int = 7,
+        completion_phase: str = "complete",
+        completion_message: str = "Foggy initialization completed",
+        failure_message: str = "Foggy initialization failed",
+    ) -> None:
         self.path = Path(path).expanduser() if path else None
         self.operation_id = operation_id
         self.kind = kind
+        self.total_steps = total_steps
+        self.completion_phase = completion_phase
+        self.completion_message = completion_message
+        self.failure_message = failure_message
         self.started_at = now_utc()
         self.phase = "preflight"
         self.step_index = 0
         self.fraction = 0.0
+        self.percent_override: int | None = None
         self.message = ""
         self.current_file: str | None = None
         self.completed_files: int | None = None
         self.total_files: int | None = None
+        self.elapsed_seconds: int | None = None
+        self.timeout_seconds: int | None = None
 
     @property
     def enabled(self) -> bool:
@@ -72,7 +87,11 @@ class ProgressReporter:
             return
         bounded_step = max(0, min(self.step_index, self.total_steps))
         bounded_fraction = max(0.0, min(float(self.fraction), 1.0))
-        percent = 100 if state == "succeeded" else round(((bounded_step + bounded_fraction) / self.total_steps) * 100)
+        percent = 100 if state == "succeeded" else (
+            max(0, min(self.percent_override, 99))
+            if self.percent_override is not None
+            else round(((bounded_step + bounded_fraction) / self.total_steps) * 100)
+        )
         payload = {
             "schemaVersion": PROGRESS_SCHEMA,
             "operationId": self.operation_id,
@@ -88,6 +107,10 @@ class ProgressReporter:
         }
         if self.completed_files is not None and self.total_files is not None:
             payload["files"] = {"completed": self.completed_files, "total": self.total_files}
+        if self.elapsed_seconds is not None:
+            payload["timing"] = {"elapsedSeconds": self.elapsed_seconds}
+            if self.timeout_seconds is not None:
+                payload["timing"]["timeoutSeconds"] = self.timeout_seconds
         if finished_at:
             payload["finishedAt"] = finished_at
         if error:
@@ -105,28 +128,37 @@ class ProgressReporter:
         current_file: str | None = None,
         completed_files: int | None = None,
         total_files: int | None = None,
+        percent: int | None = None,
+        elapsed_seconds: int | None = None,
+        timeout_seconds: int | None = None,
     ) -> None:
         self.phase = phase
         self.step_index = step_index
         self.fraction = fraction
+        self.percent_override = percent
         self.message = message
         self.current_file = current_file
         self.completed_files = completed_files
         self.total_files = total_files
+        self.elapsed_seconds = elapsed_seconds
+        self.timeout_seconds = timeout_seconds
         self._write("running")
 
     def finish(self) -> None:
-        self.phase = "complete"
+        self.phase = self.completion_phase
         self.step_index = self.total_steps
         self.fraction = 0.0
-        self.message = "Foggy initialization completed"
+        self.percent_override = 100
+        self.message = self.completion_message
         self.current_file = None
         self.completed_files = None
         self.total_files = None
+        self.elapsed_seconds = None
+        self.timeout_seconds = None
         self._write("succeeded", finished_at=now_utc())
 
     def fail(self, error: object) -> None:
-        self.message = "Foggy initialization failed"
+        self.message = self.failure_message
         self._write("failed", finished_at=now_utc(), error=str(error))
 
 
@@ -245,6 +277,79 @@ def command_result(command: list[str], timeout: int = 30, check: bool = False) -
     return payload
 
 
+def command_result_with_progress(
+    command: list[str],
+    timeout: int,
+    progress: ProgressReporter,
+    *,
+    phase: str,
+    step_index: int,
+    message: str,
+    readiness_timeout: int,
+    start_percent: int,
+    end_percent: int,
+    poll_interval: float = 1.0,
+) -> dict:
+    started = time.monotonic()
+    try:
+        process = subprocess.Popen(
+            command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except FileNotFoundError:
+        return {
+            "command": command[0],
+            "available": False,
+            "exitCode": None,
+            "stdout": "",
+            "stderr": "command not found",
+            "durationMs": round((time.monotonic() - started) * 1000),
+        }
+
+    stdout = ""
+    stderr = ""
+    while True:
+        try:
+            stdout, stderr = process.communicate(timeout=poll_interval)
+            break
+        except subprocess.TimeoutExpired:
+            elapsed = time.monotonic() - started
+            readiness_fraction = min(elapsed / max(readiness_timeout, 1), 1.0)
+            percent = round(start_percent + (end_percent - start_percent) * readiness_fraction)
+            progress.update(
+                phase,
+                step_index,
+                message,
+                percent=percent,
+                elapsed_seconds=max(1, round(elapsed)),
+                timeout_seconds=readiness_timeout,
+            )
+            if elapsed >= timeout:
+                process.kill()
+                stdout, stderr = process.communicate()
+                return {
+                    "command": command[0],
+                    "available": True,
+                    "exitCode": None,
+                    "stdout": stdout.strip(),
+                    "stderr": f"timed out after {timeout} seconds",
+                    "durationMs": round((time.monotonic() - started) * 1000),
+                }
+
+    return {
+        "command": command[0],
+        "available": True,
+        "exitCode": process.returncode,
+        "stdout": stdout.strip(),
+        "stderr": stderr.strip(),
+        "durationMs": round((time.monotonic() - started) * 1000),
+    }
+
+
 def sha256(path: Path) -> str:
     digest = hashlib.sha256()
     with path.open("rb") as stream:
@@ -1276,8 +1381,57 @@ def parse_json_output(result: dict, label: str) -> dict:
         raise OnboardingError(f"{label} did not return JSON") from exc
 
 
+def write_runtime_start_failure(
+    data_root: Path,
+    evidence_dir: Path,
+    launch: dict,
+    phase: str,
+    error: object,
+    elapsed_ms: int,
+) -> dict:
+    logs = []
+    for name in ("stdoutLog", "stderrLog"):
+        value = launch.get(name)
+        path = normalized(value) if isinstance(value, str) and value else None
+        item = {"name": name, "path": str(path) if path else None, "exists": bool(path and path.is_file())}
+        if path and path.is_file():
+            stat = path.stat()
+            item.update({"sizeBytes": stat.st_size, "modifiedAt": dt.datetime.fromtimestamp(stat.st_mtime, dt.timezone.utc).isoformat()})
+        logs.append(item)
+    pid = int(launch.get("pid", 0))
+    failure = {
+        "schemaVersion": "foggy-deepseek-runtime-start-failure/v1",
+        "failedAt": now_utc(),
+        "phase": phase,
+        "message": str(error),
+        "elapsedMs": elapsed_ms,
+        "pid": pid or None,
+        "processRunningBeforeCleanup": process_info(pid)["running"] if pid else False,
+        "runtimeUrl": launch.get("runtimeUrl"),
+        "workDir": launch.get("workDir"),
+        "evidenceDir": str(evidence_dir),
+        "logs": logs,
+    }
+    atomic_json(evidence_dir / "failure.json", failure)
+    atomic_json(data_root / "last-runtime-start-failure.json", failure)
+    return failure
+
+
 def runtime_start_command(args: argparse.Namespace) -> dict:
+    global ACTIVE_PROGRESS
     versions = load_versions()
+    readiness_timeout = args.timeout or int(versions["defaults"]["readinessTimeoutSeconds"])
+    progress = ProgressReporter(
+        getattr(args, "progress_file", None),
+        getattr(args, "operation_id", None),
+        getattr(args, "operation_kind", "runtime-start"),
+        total_steps=6,
+        completion_phase="runtime-complete",
+        completion_message="Foggy Runtime is ready",
+        failure_message="Foggy Runtime startup failed",
+    )
+    ACTIVE_PROGRESS = progress
+    progress.update("runtime-preflight", 0, "Checking Runtime state and prerequisites", percent=3)
     install_root = normalized(args.install_root or default_install_root())
     state = read_install_state(install_root)
     data_root = normalized(args.data_root or state["dataRoot"])
@@ -1296,15 +1450,24 @@ def runtime_start_command(args: argparse.Namespace) -> dict:
             base_url = prior.get("runtimeUrl")
             if not isinstance(base_url, str) or not base_url:
                 raise OnboardingError("Recorded Runtime does not contain runtimeUrl")
-            wait_result = command_result(
+            progress.update("runtime-readiness", 3, "Revalidating the recorded Runtime", percent=30, elapsed_seconds=0, timeout_seconds=readiness_timeout)
+            wait_result = command_result_with_progress(
                 [cli, "--base-url", base_url, "--namespace", namespace, "--output", "json", "wait-ready",
-                 "--timeout-seconds", str(args.timeout or versions["defaults"]["readinessTimeoutSeconds"]),
+                 "--timeout-seconds", str(readiness_timeout),
                  "--interval-seconds", "1"],
-                timeout=(args.timeout or versions["defaults"]["readinessTimeoutSeconds"]) + 30,
+                readiness_timeout + 30,
+                progress,
+                phase="runtime-readiness",
+                step_index=3,
+                message="Revalidating the recorded Runtime",
+                readiness_timeout=readiness_timeout,
+                start_percent=30,
+                end_percent=85,
             )
             wait_payload = parse_json_output(wait_result, "wait-ready")
             if wait_payload.get("success") is not True:
                 raise OnboardingError("wait-ready returned success=false for recorded Runtime")
+            progress.update("runtime-capabilities", 4, "Verifying Runtime API capabilities", percent=90)
             capabilities = parse_json_output(
                 command_result(
                     [cli, "--base-url", base_url, "--namespace", namespace, "--output", "json", "capabilities"],
@@ -1324,6 +1487,8 @@ def runtime_start_command(args: argparse.Namespace) -> dict:
                 "schemaVersion": capabilities.get("data", {}).get("schemaVersion"),
                 "securityMode": capabilities.get("data", {}).get("securityMode"),
             }
+            progress.finish()
+            ACTIVE_PROGRESS = None
             return {
                 "success": True,
                 **prior,
@@ -1340,6 +1505,7 @@ def runtime_start_command(args: argparse.Namespace) -> dict:
                 "productionReady": False,
             }
         existing.unlink()
+    progress.update("runtime-preflight", 1, "Checking port and Runtime workspace", percent=10)
     port = args.port or int(versions["defaults"]["port"])
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
         try:
@@ -1350,6 +1516,7 @@ def runtime_start_command(args: argparse.Namespace) -> dict:
     work_dir.mkdir(parents=True, exist_ok=True)
     launcher_dir = normalized(state["launcher"]["path"])
     java_exe = args.java or os.environ.get("JAVA_EXE", "java")
+    progress.update("runtime-launcher", 2, "Starting the Java Runtime through Launcher", percent=20)
     if os.name == "nt":
         shell = shutil.which("pwsh") or shutil.which("powershell")
         if not shell:
@@ -1397,12 +1564,25 @@ def runtime_start_command(args: argparse.Namespace) -> dict:
     evidence_dir = data_root / "evidence" / f"runtime-start-{dt.datetime.now().strftime('%Y%m%d-%H%M%S')}"
     evidence_dir.mkdir(parents=True, exist_ok=True)
     atomic_json(evidence_dir / "launch.json", launch)
+    startup_started = time.monotonic()
     try:
-        wait_result = command_result([cli, "--base-url", base_url, "--namespace", namespace, "--output", "json", "wait-ready", "--timeout-seconds", str(args.timeout or versions["defaults"]["readinessTimeoutSeconds"]), "--interval-seconds", "1"], timeout=(args.timeout or versions["defaults"]["readinessTimeoutSeconds"]) + 30)
+        progress.update("runtime-readiness", 3, "Waiting for Java Runtime readiness", percent=30, elapsed_seconds=0, timeout_seconds=readiness_timeout)
+        wait_result = command_result_with_progress(
+            [cli, "--base-url", base_url, "--namespace", namespace, "--output", "json", "wait-ready", "--timeout-seconds", str(readiness_timeout), "--interval-seconds", "1"],
+            readiness_timeout + 30,
+            progress,
+            phase="runtime-readiness",
+            step_index=3,
+            message="Waiting for Java Runtime readiness",
+            readiness_timeout=readiness_timeout,
+            start_percent=30,
+            end_percent=85,
+        )
         wait_payload = parse_json_output(wait_result, "wait-ready")
         if wait_payload.get("success") is not True:
             raise OnboardingError("wait-ready returned success=false")
         atomic_json(evidence_dir / "wait-ready.json", wait_payload)
+        progress.update("runtime-capabilities", 4, "Verifying Runtime API capabilities", percent=90)
         capabilities_result = command_result([cli, "--base-url", base_url, "--namespace", namespace, "--output", "json", "capabilities"], timeout=30)
         capabilities = parse_json_output(capabilities_result, "capabilities")
         expected_contract = versions["components"]["launcher"]["runtimeApiContract"]
@@ -1411,12 +1591,21 @@ def runtime_start_command(args: argparse.Namespace) -> dict:
         if capabilities.get("data", {}).get("securityMode") != versions["defaults"]["securityMode"]:
             raise OnboardingError("Packaged Launcher did not report the expected dev/test security mode")
         atomic_json(evidence_dir / "capabilities.json", capabilities)
-    except Exception:
+    except Exception as exc:
+        failure = write_runtime_start_failure(
+            data_root,
+            evidence_dir,
+            launch,
+            progress.phase,
+            exc,
+            round((time.monotonic() - startup_started) * 1000),
+        )
         try:
             os.kill(pid, signal.SIGTERM)
         except OSError:
             pass
-        raise
+        raise OnboardingError(f"{exc}; startup diagnostics: {failure['evidenceDir']}") from exc
+    progress.update("runtime-state", 5, "Saving verified Runtime state", percent=96, current_file="runtime-state.json")
     runtime_state = {
         "schemaVersion": RUNTIME_STATE_SCHEMA,
         "startedAt": now_utc(),
@@ -1435,6 +1624,9 @@ def runtime_start_command(args: argparse.Namespace) -> dict:
         },
     }
     atomic_json(data_root / "runtime-state.json", runtime_state)
+    (data_root / "last-runtime-start-failure.json").unlink(missing_ok=True)
+    progress.finish()
+    ACTIVE_PROGRESS = None
     return {"success": True, **runtime_state, "productionReady": False}
 
 
@@ -2855,6 +3047,9 @@ def build_parser() -> argparse.ArgumentParser:
     start.add_argument("--namespace")
     start.add_argument("--timeout", type=int)
     start.add_argument("--java")
+    start.add_argument("--progress-file")
+    start.add_argument("--operation-id")
+    start.add_argument("--operation-kind", default="runtime-start")
     start.set_defaults(handler=runtime_start_command)
 
     stop = sub.add_parser("runtime-stop")