feat(kv260): wire preflight panel to live serial probe

docs/EDITOR_BRIDGE_CONTRACT.md

@@ -332,3 +332,10 @@ xsim path, and text surface sketches is documented in
 - No MCP server implementation in this repo today.
 - No pccx-llm-launcher runtime call yet; future integration requires an
   explicit reviewed contract.
+- The KV260 status surface is a read-only local display over launcher NPU
+  status data and pccx-lab trace manifest JSON. The VS Code prototype command
+  `pccxSystemVerilog.showKv260StatusPanel` and CLI command `sv-ide
+  kv260-status` render fixture or explicitly supplied local JSON data only;
+  they do not invoke the launcher, invoke pccx-lab, run shell commands, open
+  SSH, control KV260 hardware, or write back status. The surface is documented
+  in [`KV260_READ_ONLY_STATUS_SURFACE.md`](./KV260_READ_ONLY_STATUS_SURFACE.md).

docs/KV260_READ_ONLY_STATUS_SURFACE.md

@@ -0,0 +1,49 @@
+# KV260 Read-Only Status Surface
+
+This page documents the local IDE status surface for KV260 data. The surface
+parses existing JSON data and renders a checklist before a future run path is
+considered. It does not open SSH, run board commands, invoke the launcher,
+invoke pccx-lab, load a bitstream, access AXI, scan networks, mutate files, or
+write back status.
+
+## Inputs
+
+- `LauncherStatusReader` consumes the launcher `NPUStatus` shape from
+  `pccxai/pccx-llm-launcher#70`: `bitstream_loaded`, `bitstream_uuid`,
+  `axi_base_addr`, `axi_stat_register_value`, and `last_error`.
+- The same reader accepts the launcher serial preflight snapshot from
+  `pccxai/pccx-llm-launcher#72`: selected tty port, login result, truncated
+  kernel uname display, XRT presence, and last preflight timestamp. When the
+  snapshot is absent, blocked, or has no tty/login data, the panel reports
+  `preflight not run` instead of reading environment variables or opening a
+  port.
+- `LabTraceReader` parses the lab `TraceManifest` JSON shape from
+  `pccxai/pccx-lab#160` for file-replay trace manifests.
+
+The launcher type is mirrored locally because this repository does not import
+the launcher contract package.
+
+## Rendered Surface
+
+`Kv260StatusPanel` renders launcher status, lab manifest metadata, and a
+`PreflightProposal` checklist:
+
+- serial tty port
+- serial login
+- XRT present
+- serial preflight timestamp
+
+The checklist is display-only. A blocked item is evidence that the IDE should
+keep any future KV260 run path gated until lower layers provide reviewed data.
+The IDE surface does not run the launcher serial backend, SSH, shell commands,
+or board commands; it only renders JSON already produced by the launcher side.
+
+## CLI
+
+```bash
+sv-ide kv260-status
+```
+
+The command reads the bundled tiny fixtures by default and prints the same
+status panel as text. Optional local JSON paths can be supplied with
+`--launcher-status` and `--trace-manifest`.

docs/examples/kv260-status/lab-trace-manifest.example.json

@@ -0,0 +1,25 @@
+{
+  "schema_version": "pccx.lab.kv260.trace-manifest.v0",
+  "bitstream_uuid": "00000000-0000-0000-0000-000000000160",
+  "axi_base": "0x00000000a0000000",
+  "isa_version": "pccx_v002",
+  "frame_count": 1,
+  "checksums": [
+    {
+      "algorithm": "sha256",
+      "value": "fixture-only-not-a-hardware-capture",
+      "frame_idx": null
+    }
+  ],
+  "runbook_ref": "pccxai/pccx-lab#160",
+  "source_kind": "file_replay",
+  "frames": [
+    {
+      "frame_idx": 0,
+      "axi_stat_register_value": 1,
+      "engine_completion_mask": 3,
+      "cycle_count": 128,
+      "result_payload": "a55a0001"
+    }
+  ]
+}

docs/examples/kv260-status/launcher-npu-status.example.json

@@ -0,0 +1,16 @@
+{
+  "bitstream_loaded": false,
+  "bitstream_uuid": null,
+  "axi_base_addr": null,
+  "axi_stat_register_value": null,
+  "last_error": "fixture only; lower-layer evidence not supplied",
+  "serial_probe": {
+    "schema_version": "pccx.launcher.kv260-serial-preflight.v0",
+    "status": "not_run",
+    "tty_port": null,
+    "login_ok": null,
+    "kernel_uname": null,
+    "xrt_present": null,
+    "last_preflight_at": null
+  }
+}

editors/vscode-prototype/README.md

@@ -147,6 +147,7 @@ The contributed commands are:
 - `pccxSystemVerilog.showContextBundleAudit`
 - `pccxSystemVerilog.showPccxLabBackendStatus`
 - `pccxSystemVerilog.showDiagnosticsHandoffSummary`
+- `pccxSystemVerilog.showKv260StatusPanel`
 
 The prototype-only settings are:
 
@@ -559,6 +560,7 @@ node editors/vscode-prototype/test/runtime-readiness-consumer.test.mjs
 node editors/vscode-prototype/test/runtime-readiness-status-surface.test.mjs
 node editors/vscode-prototype/test/device-session-status-consumer.test.mjs
 node editors/vscode-prototype/test/device-session-status-surface.test.mjs
+node editors/vscode-prototype/test/kv260-status-panel.test.mjs
 node editors/vscode-prototype/test/local-workflow-status.test.mjs
 node editors/vscode-prototype/test/context-bundle-audit.test.mjs
 node editors/vscode-prototype/test/validation-result-summary.test.mjs
@@ -597,3 +599,8 @@ node editors/vscode-prototype/src/adapter.mjs diagnostics \
 node editors/vscode-prototype/src/adapter.mjs navigation \
   docs/examples/editor-bridge/declarations.example.json
 ```
+
+The KV260 status surface is a read-only panel over local launcher NPU status
+and pccx-lab trace manifest data. `pccxSystemVerilog.showKv260StatusPanel`
+renders the bundled tiny fixture data and does not invoke the launcher,
+pccx-lab, shell, SSH, or hardware paths.

editors/vscode-prototype/package.json

@@ -34,7 +34,8 @@
     "onCommand:pccxSystemVerilog.showLocalWorkflowStatus",
     "onCommand:pccxSystemVerilog.showContextBundleAudit",
     "onCommand:pccxSystemVerilog.showPccxLabBackendStatus",
-    "onCommand:pccxSystemVerilog.showDiagnosticsHandoffSummary"
+    "onCommand:pccxSystemVerilog.showDiagnosticsHandoffSummary",
+    "onCommand:pccxSystemVerilog.showKv260StatusPanel"
   ],
   "contributes": {
     "commands": [
@@ -125,6 +126,10 @@
       {
         "command": "pccxSystemVerilog.showDiagnosticsHandoffSummary",
         "title": "PCCX SystemVerilog: Show Diagnostics Handoff Summary (Experimental)"
+      },
+      {
+        "command": "pccxSystemVerilog.showKv260StatusPanel",
+        "title": "PCCX SystemVerilog: Show KV260 Status Panel (Experimental)"
       }
     ],
     "configuration": {

editors/vscode-prototype/src/config.mjs

@@ -56,11 +56,16 @@ export const DIAGNOSTICS_HANDOFF_COMMAND_IDS = Object.freeze([
   "pccxSystemVerilog.showDiagnosticsHandoffSummary",
 ]);
 
+export const KV260_STATUS_COMMAND_IDS = Object.freeze([
+  "pccxSystemVerilog.showKv260StatusPanel",
+]);
+
 export const COMMAND_IDS = Object.freeze([
   ...FACADE_COMMAND_IDS,
   ...WORKFLOW_COMMAND_IDS,
   ...PCCX_LAB_COMMAND_IDS,
   ...DIAGNOSTICS_HANDOFF_COMMAND_IDS,
+  ...KV260_STATUS_COMMAND_IDS,
 ]);
 
 export const MODES = Object.freeze(["checkedExample", "liveWorkspace"]);

editors/vscode-prototype/src/extension.mjs

@@ -72,6 +72,10 @@ import {
   createDiagnosticsHandoffStatusSurface,
   formatDiagnosticsHandoffStatusSurface,
 } from "./diagnostics-handoff-status-surface.mjs";
+import {
+  createKv260StatusPanel,
+  formatKv260StatusPanel,
+} from "./kv260-status-panel.mjs";
 
 const EXTENSION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const DEFAULT_DIAGNOSTIC_FILE_ROOT = resolve(EXTENSION_ROOT, "../..");
@@ -113,6 +117,8 @@ export const PCCX_LAB_BACKEND_STATUS_COMMAND =
   "pccxSystemVerilog.showPccxLabBackendStatus";
 export const SHOW_DIAGNOSTICS_HANDOFF_SUMMARY_COMMAND =
   "pccxSystemVerilog.showDiagnosticsHandoffSummary";
+export const SHOW_KV260_STATUS_PANEL_COMMAND =
+  "pccxSystemVerilog.showKv260StatusPanel";
 
 const NAVIGATION_LOCATION_COMMAND_IDS = Object.freeze([
   CHECKED_EXAMPLE_NAVIGATION_COMMAND,
@@ -428,6 +434,9 @@ function appendCommandOutput(outputChannel, commandId, result) {
   if (result.kind === "diagnostics-handoff-status") {
     outputChannel.appendLine(formatDiagnosticsHandoffStatusSurface(result.surface));
   }
+  if (result.kind === "kv260-status-panel") {
+    outputChannel.appendLine(formatKv260StatusPanel(result.panel));
+  }
   if (result.status?.kind === "pccx-lab-backend-status") {
     outputChannel.appendLine(JSON.stringify(result.status, null, 2));
   }
@@ -1106,6 +1115,28 @@ export function createCommandHandler(commandId, vscodeApi, runtime = {}) {
       return result;
     }
 
+    if (commandId === SHOW_KV260_STATUS_PANEL_COMMAND) {
+      let result;
+      try {
+        const panel = createKv260StatusPanel(runtime.kv260StatusInputs);
+        result = {
+          ok: true,
+          commandId,
+          kind: "kv260-status-panel",
+          panel,
+        };
+        vscodeApi?.window?.showInformationMessage?.(
+          `KV260 status surface: ${panel.lab.frameCount} trace frame(s).`,
+          result,
+        );
+      } catch (error) {
+        result = { ok: false, commandId, error: error.message };
+        vscodeApi?.window?.showWarningMessage?.(result.error, result);
+      }
+      appendCommandOutput(runtime.outputChannel, commandId, result);
+      return result;
+    }
+
     if (commandId === APPROVED_VALIDATION_RUNNER_COMMAND) {
       let result;
       try {