接入 INI 面板只读 session readiness handoff

PROJECT_COMPLETION_TRACKER.md

@@ -9,7 +9,7 @@ turn-by-turn continuation notes and next-batch execution records.
 ## Current Status
 
 - Active continuation file: `text14.txt`
-- Latest completed batch: INI panel session readiness workflow
+- Latest completed batch: INI panel readonly session readiness handoff
 - Latest relevant commit: use `git log -1 --oneline` after each committed batch
 - Working tree at tracker creation: clean
 - Required policy: LinuxCNC remains the only CNC semantic source
@@ -44,7 +44,7 @@ The project is complete for the current scope when all of the following are true
 | Native sim configs baseline | Stable | Last recorded Layer 2: `total 159`, `pass 151`, `expected_fail 8`, `unexpected_fail 0`. |
 | OPFS/session persistence | Stable for current scope | Browser smoke passes, SDK re-exports OPFS/session helpers including `readMachineSessionReadiness()`, and `docs/opfs-session-persistence.md` defines the project-level release gate. |
 | SDK/API surface | Stable for current scope | SDK re-exports core, OPFS/session readiness/load helpers, sim-config staging, and INI panel shell/workflow overview helpers with a Node surface smoke. |
-| Browser/UI workflow | Stable for current scope | Workflow overview embedding mount DOM closure is complete, and INI panel session workflows expose OPFS/session readiness before loading WASM session state. |
+| Browser/UI workflow | Stable for current scope | Workflow overview embedding mount DOM closure is complete, and INI panel session workflows plus read-only control/shell handoff expose OPFS/session readiness before loading or reading WASM session state. |
 | Workflow overview embedding | Stable for current scope | Report/display/render, DOM contract/readiness/renderer, mount result/display/render, mount DOM contract/readiness/renderer/wrapper exist. |
 | Host/runtime boundary proof | Stable blocked state | Host smoke passes; runtime families remain blocked and `docs/host-runtime-boundary-handoff.md` records host readiness, promotion blockers, dispatch, and evidence gates. |
 | Documentation/release gate | Stable for current scope | `docs/project-release-handoff.md` links README, panel entry, SDK, OPFS/session, sim-config, host/runtime, source reuse, drift, and tracker acceptance paths. |

text14.txt

@@ -1776,3 +1776,71 @@ browser_ini_shell_integration_workflow_smoke=ok
 继续做实质能力推进。下一批建议把 session readiness report 纳入 read-only control page status 或
 shell handoff package/display view-model，让外部 shell 不进入 editor 页面也能读取 session
 ready/blocked 原因；仍保持只读，不新增控制按钮，不解析 G-code，不扩大 LinuxCNC 语义边界。
+
+二十二、2026-06-16 继续执行记录：INI panel readonly session readiness handoff
+
+本轮继续以功能实质性推进为主，把上一批 session readiness report 纳入只读 control page status
+和 external shell handoff contract。现在外部 shell 不进入 editor 页面，也能通过 read-only status
+读取 machine-session ready/blocked 原因。
+
+完成内容：
+
+- `wasm-port/runtime/ui/ini-panel/panel-state-summary.js` 将 `sessionReadiness` 纳入：
+  - `createIniPanelStateSummary()`；
+  - `createMachineSessionStateSnapshot()`；
+  - `createMachineSessionStateReport()`；
+  - `createMachineSessionWorkflowStatus()`；
+- `wasm-port/runtime/ui/ini-panel/readonly-status-api.js` 新增只读 `sessionReadiness` 字段；
+- readonly status API manifest 的 `statusFields` 新增 `sessionReadiness`；
+- `wasm-port/runtime/ui/ini-panel/control-page-session-workflow.js` 在 waiting/ready session load state
+  中透出 `sessionReadiness`；
+- `wasm-port/docs/panel-entry.md` 记录外部 shell 可通过 read-only status 和 control-page session
+  workflow 获取 machine-session ready/blocked 状态；
+- Node 测试覆盖 state summary、readonly status API、control-page session workflow、control-page
+  controller、shell control-page contract、shell integration manifest、entry docs、ui shell；
+- Browser smoke 覆盖真实 control page readonly status 和 shell handoff readonly status 中的
+  `sessionReadiness`；
+- 未新增控制按钮；
+- 未执行 action-plan；
+- 未解析 G-code；
+- 未解释 canonical events；
+- 未新增 JS CNC 语义；
+- 未运行 opt-in runtime probes；
+- 未 promotion blocked runtime family；
+- 未改变 LinuxCNC interpreter、tool、parameter、planner、kinematics、remap 或 LinuxCNC-owned
+  runtime semantics。
+
+验证已通过：
+
+```bash
+git diff --check
+wasm-port/tools/verify_vendor_sync.sh
+wasm-port/tools/verify_no_standalone_cnc_semantics.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh
+SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
+wasm-port/tests/ui/node/verify_ui_node_smokes.sh
+SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
+wasm-port/tests/host/verify_host_smokes.sh
+```
+
+关键输出：
+
+```text
+vendor sync up to date
+standalone CNC semantics guard complete
+interp_wasm_node_smoke=ok
+sim_configs_wasm_node_inventory_unexpected_fail=0
+ui_node_smokes=ok
+browser_ini_opfs_smoke=ok
+browser_ini_control_page_smoke=ok
+browser_ini_launch_smoke=ok
+browser_ini_workflow_overview_smoke=ok
+browser_ini_shell_integration_workflow_smoke=ok
+host_wasm_opfs_browser_smokes=ok
+```
+
+下一步工作计划：
+
+继续以实质能力推进为主。下一批可把 `sessionReadiness` 纳入 shell handoff workflow display/render rows，
+让外部 shell 的已挂载 handoff 面板直接展示 ready/blocked 原因；仍保持只读，不新增控制按钮，不解析
+G-code，不扩大 LinuxCNC 语义边界。

wasm-port/docs/panel-entry.md

@@ -126,7 +126,8 @@ read-only model with `pages`, `launcherLinks`, and `controlPage` helpers for
 mounting the existing control-page controller, refresh workflow, and renderer.
 Use `controlPage.readStatus` or `readMachineSessionReadonlyStatus()` when an
 outer shell needs one stable read of `stateBundle`, `workflowStatus`,
-`overview`, `controlView`, `session`, `runReadiness`, and `run`.
+`overview`, `controlView`, `sessionReadiness`, `session`, `runReadiness`, and
+`run`.
 Use `createMachineSessionReadonlyStatusApiManifest()` or
 `controlPage.readonlyStatusApiManifest` when you only need the API shape and
 method names.
@@ -433,7 +434,8 @@ state-shape helper used by the workflow.
 The control-page session workflow lives in
 `runtime/ui/ini-panel/control-page-session-workflow.js`. Use
 `loadMachineSessionForControlPageWorkflow()` when an outer shell needs a
-read-only readiness snapshot for the embedded panel API and first control view.
+read-only readiness snapshot for the embedded panel API, machine-session
+ready/blocked state, and first control view.
 `createControlPageSessionLoadState()` is the stable state-shape helper for
 `waiting-panel`, `waiting-api`, `waiting-session`, `ready`, and `error` phases.
 

wasm-port/runtime/ui/ini-panel/control-page-session-workflow.js

@@ -5,6 +5,7 @@ export function createControlPageSessionLoadState({
   controlViewReady = false,
   stateBundle = null,
   workflowStatus = null,
+  sessionReadiness = null,
   controlView = null,
   error = null,
 } = {}) {
@@ -15,11 +16,19 @@ export function createControlPageSessionLoadState({
     controlViewReady,
     stateBundle,
     workflowStatus,
+    sessionReadiness,
     controlView,
     error,
   };
 }
 
+function getSessionReadiness(stateBundle, workflowStatus) {
+  return workflowStatus?.sessionReadiness
+    ?? stateBundle?.workflowStatus?.sessionReadiness
+    ?? stateBundle?.report?.sessionReadiness
+    ?? null;
+}
+
 export function loadMachineSessionForControlPageWorkflow({
   getPanelWindow,
   getPanelApi,
@@ -63,22 +72,28 @@ export function loadMachineSessionForControlPageWorkflow({
   }
 
   if (!controlView) {
+    const stateBundle = panelApi.getMachineSessionStateBundle?.() ?? null;
+    const workflowStatus = panelApi.getMachineSessionWorkflowStatus?.() ?? null;
     return createControlPageSessionLoadState({
       phase: "waiting-session",
       panelReady: true,
       apiReady: true,
-      stateBundle: panelApi.getMachineSessionStateBundle?.() ?? null,
+      stateBundle,
-      workflowStatus: panelApi.getMachineSessionWorkflowStatus?.() ?? null,
+      workflowStatus,
+      sessionReadiness: getSessionReadiness(stateBundle, workflowStatus),
     });
   }
 
+  const stateBundle = panelApi.getMachineSessionStateBundle?.() ?? null;
+  const workflowStatus = panelApi.getMachineSessionWorkflowStatus?.() ?? null;
   return createControlPageSessionLoadState({
     phase: "ready",
     panelReady: true,
     apiReady: true,
     controlViewReady: true,
-    stateBundle: panelApi.getMachineSessionStateBundle?.() ?? null,
+    stateBundle,
-    workflowStatus: panelApi.getMachineSessionWorkflowStatus?.() ?? null,
+    workflowStatus,
+    sessionReadiness: getSessionReadiness(stateBundle, workflowStatus),
     controlView,
   });
 }

wasm-port/runtime/ui/ini-panel/panel-state-summary.js

@@ -3,6 +3,7 @@ export function createIniPanelStateSummary({
   machine = null,
   machineFiles = null,
   sessionSnapshot = null,
+  sessionReadiness = null,
   sessionLoad = null,
   runReadiness = null,
   run = null,
@@ -17,6 +18,7 @@ export function createIniPanelStateSummary({
     machine,
     machineFiles,
     sessionSnapshot,
+    sessionReadiness,
     sessionLoad,
     runReadiness,
     run,
@@ -29,6 +31,7 @@ export function createMachineSessionStateSnapshot({
   machine = null,
   machineFiles = null,
   sessionSnapshot = null,
+  sessionReadiness = null,
   sessionLoad = null,
   runReadiness = null,
   selectedProgram = null,
@@ -44,6 +47,7 @@ export function createMachineSessionStateSnapshot({
       machine,
       machineFiles,
       sessionSnapshot,
+      sessionReadiness,
       sessionLoad,
       runReadiness,
       run,
@@ -72,6 +76,7 @@ export function createMachineSessionStateReport(state = {}) {
   const badges = state.badges ?? {};
   const fields = state.fields ?? {};
   const sessionSnapshot = state.sessionSnapshot ?? {};
+  const sessionReadiness = state.sessionReadiness ?? null;
   const sessionLoad = state.sessionLoad ?? {};
   const runReadiness = state.runReadiness ?? {};
   const selectedProgram = state.selectedProgram ?? {};
@@ -90,6 +95,7 @@ export function createMachineSessionStateReport(state = {}) {
       toolTable: fields.sessionToolTable ?? sessionSnapshot.toolTableOpfsPath ?? sessionLoad.toolTableWasmPath ?? null,
       gcode: fields.sessionGcode ?? sessionSnapshot.gcodeOpfsPath ?? null,
     },
+    sessionReadiness,
     loaded: {
       iniWasmPath: sessionLoad.iniWasmPath ?? null,
       parameterWasmPath: sessionLoad.parameterWasmPath ?? null,
@@ -141,6 +147,7 @@ export function createMachineSessionWorkflowStatus(state = {}) {
   return {
     readiness: report.readiness,
     overview,
+    sessionReadiness: report.sessionReadiness ?? null,
     runReadiness: report.runReadiness,
     lastAction: report.status.lastAction,
     error: report.status.error,

wasm-port/runtime/ui/ini-panel/readonly-status-api.js

@@ -4,12 +4,17 @@ export function createMachineSessionReadonlyStatus({
   controlView = null,
 } = {}) {
   const overview = stateBundle?.overview ?? workflowStatus?.overview ?? null;
+  const sessionReadiness = workflowStatus?.sessionReadiness
+    ?? stateBundle?.workflowStatus?.sessionReadiness
+    ?? stateBundle?.report?.sessionReadiness
+    ?? null;
   return {
     stateBundle,
     workflowStatus,
     overview,
     controlView,
     report: stateBundle?.report ?? null,
+    sessionReadiness,
     runReadiness: workflowStatus?.runReadiness ?? stateBundle?.report?.runReadiness ?? null,
     run: workflowStatus?.run ?? stateBundle?.report?.run ?? null,
     session: workflowStatus?.session ?? stateBundle?.report?.session ?? null,
@@ -42,6 +47,7 @@ export function createMachineSessionReadonlyStatusApiManifest() {
       "overview",
       "controlView",
       "report",
+      "sessionReadiness",
       "runReadiness",
       "run",
       "session",

wasm-port/tests/browser/ini_panel_control_page_smoke.html

@@ -218,6 +218,11 @@ TOOL_TABLE = browser-tool.tbl
         "load-session",
         "control page readonly status workflow last action after load",
       );
+      assertEqual(
+        loadedStatus.sessionReadiness.ready,
+        true,
+        "control page readonly status session readiness",
+      );
       assertEqual(
         loadedStatus.controlView.status.lastAction,
         "load-session",

wasm-port/tests/browser/ini_panel_shell_integration_workflow_smoke.html

@@ -268,6 +268,11 @@ TOOL_TABLE = browser-shell-tool.tbl
       assertEqual(handoffSummary.handoffMethods.loadSessionState, "loadControlPageSessionState", "shell handoff load method");
       assertEqual(handoffSummary.handoffMethods.readStatus, "readControlPageStatus", "shell handoff status method");
       assertEqual(handoffSummary.readonlyStatusFields.includes("session"), true, "shell handoff readonly session field");
+      assertEqual(
+        handoffSummary.readonlyStatusFields.includes("sessionReadiness"),
+        true,
+        "shell handoff readonly session readiness field",
+      );
       assertEqual(handoffSummary.persistenceCapabilities.length, 3, "shell handoff persistence capabilities");
       assertEqual(readiness.apiNames.launch, "ini-panel-launch", "shell integration launch API name");
       assertEqual(
@@ -531,6 +536,11 @@ TOOL_TABLE = browser-shell-tool.tbl
       });
       assertEqual(readonlyStatusResult.phase, "ready", "shell handoff readonly status result phase");
       assertEqual(readonlyStatusResult.ready, true, "shell handoff readonly status result readiness");
+      assertEqual(
+        readonlyStatus.sessionReadiness.ready,
+        true,
+        "shell handoff readonly status session readiness",
+      );
       assertEqual(
         readonlyStatusResult.missingStatusFields.join(","),
         "",

wasm-port/tests/ui/node/verify_ini_panel_control_page_controller.mjs

@@ -93,6 +93,7 @@ assert.deepEqual(controller.readStatus(), {
   overview: null,
   controlView: expectedView,
   report: expectedStateBundle.report,
+  sessionReadiness: null,
   runReadiness: null,
   run: null,
   session: null,
@@ -109,6 +110,7 @@ assert.deepEqual(controller.loadSessionState(), {
   controlViewReady: true,
   stateBundle: expectedStateBundle,
   workflowStatus: expectedWorkflowStatus,
+  sessionReadiness: null,
   controlView: expectedView,
   error: null,
 });

wasm-port/tests/ui/node/verify_ini_panel_control_page_session_workflow.mjs

@@ -21,6 +21,11 @@ const workflowStatus = {
   overview: {
     phase: "ready",
   },
+  sessionReadiness: {
+    phase: "ready",
+    ready: true,
+    missing: [],
+  },
   lastAction: "load-session",
   error: null,
 };
@@ -40,6 +45,7 @@ assert.deepEqual(createControlPageSessionLoadState({ phase: "waiting-panel" }),
   controlViewReady: false,
   stateBundle: null,
   workflowStatus: null,
+  sessionReadiness: null,
   controlView: null,
   error: null,
 });
@@ -81,6 +87,7 @@ assert.deepEqual(
     apiReady: true,
     stateBundle,
     workflowStatus,
+    sessionReadiness: workflowStatus.sessionReadiness,
   }),
 );
 
@@ -101,6 +108,7 @@ assert.deepEqual(
     controlViewReady: true,
     stateBundle,
     workflowStatus,
+    sessionReadiness: workflowStatus.sessionReadiness,
     controlView,
   }),
 );

wasm-port/tests/ui/node/verify_ini_panel_entry_docs.mjs

@@ -430,6 +430,7 @@ assert.deepEqual(createControlPageSessionLoadState({ phase: "waiting-panel" }),
   controlViewReady: false,
   stateBundle: null,
   workflowStatus: null,
+  sessionReadiness: null,
   controlView: null,
   error: null,
 });

wasm-port/tests/ui/node/verify_ini_panel_readonly_status_api.mjs

@@ -30,6 +30,11 @@ const stateBundle = {
 };
 const workflowStatus = {
   overview: stateBundle.overview,
+  sessionReadiness: {
+    phase: "ready",
+    ready: true,
+    missing: [],
+  },
   runReadiness: stateBundle.report.runReadiness,
   session: stateBundle.report.session,
   run: stateBundle.report.run,
@@ -56,6 +61,7 @@ assert.deepEqual(
     overview: stateBundle.overview,
     controlView,
     report: stateBundle.report,
+    sessionReadiness: workflowStatus.sessionReadiness,
     runReadiness: stateBundle.report.runReadiness,
     run: stateBundle.report.run,
     session: stateBundle.report.session,
@@ -73,6 +79,7 @@ assert.deepEqual(createMachineSessionReadonlyStatus(), {
   overview: null,
   controlView: null,
   report: null,
+  sessionReadiness: null,
   runReadiness: null,
   run: null,
   session: null,
@@ -103,6 +110,7 @@ assert.deepEqual(createMachineSessionReadonlyStatusApiManifest(), {
     "overview",
     "controlView",
     "report",
+    "sessionReadiness",
     "runReadiness",
     "run",
     "session",

wasm-port/tests/ui/node/verify_ini_panel_shell_control_page_contract.mjs

@@ -59,6 +59,7 @@ assert.deepEqual(contract, {
     "overview",
     "controlView",
     "report",
+    "sessionReadiness",
     "runReadiness",
     "run",
     "session",

wasm-port/tests/ui/node/verify_ini_panel_shell_integration_manifest.mjs

@@ -217,6 +217,7 @@ assert.deepEqual(workflowPlan, {
       "overview",
       "controlView",
       "report",
+      "sessionReadiness",
       "runReadiness",
       "run",
       "session",
@@ -272,6 +273,7 @@ assert.deepEqual(handoffSummary, {
     "overview",
     "controlView",
     "report",
+    "sessionReadiness",
     "runReadiness",
     "run",
     "session",

wasm-port/tests/ui/node/verify_ini_panel_state_summary.mjs

@@ -68,6 +68,12 @@ const expectedEmptyRunReadinessReport = {
   iniWasmPath: null,
 };
 
+const sessionReadinessFixture = {
+  phase: "ready",
+  ready: true,
+  missing: [],
+};
+
 const expectedWorkflowOverview = {
   phase: "ran",
   missing: [],
@@ -120,6 +126,7 @@ const summary = createIniPanelStateSummary({
     snapshotLabel: "ui-machine-session/ui-machine-session.json",
     workflow: "save-session-snapshot",
   },
+  sessionReadiness: sessionReadinessFixture,
   sessionLoad: {
     iniOpfsPath: "linuxcnc/machines/xyzab-tdr/machine.ini",
     iniWasmPath: "/work/session-machine.ini",
@@ -152,6 +159,7 @@ assert.deepEqual(summary, {
     snapshotLabel: "ui-machine-session/ui-machine-session.json",
     workflow: "save-session-snapshot",
   },
+  sessionReadiness: sessionReadinessFixture,
   sessionLoad: {
     iniOpfsPath: "linuxcnc/machines/xyzab-tdr/machine.ini",
     iniWasmPath: "/work/session-machine.ini",
@@ -175,6 +183,7 @@ assert.deepEqual(
     machine: null,
     machineFiles: null,
     sessionSnapshot: null,
+    sessionReadiness: null,
     sessionLoad: null,
     runReadiness: null,
     run: null,
@@ -195,6 +204,7 @@ assert.deepEqual(
     sessionSnapshot: {
       snapshotLabel: "ui-machine-session/ui-machine-session.json",
     },
+    sessionReadiness: sessionReadinessFixture,
     sessionLoad: {
       iniWasmPath: "/work/session-machine.ini",
     },
@@ -237,6 +247,7 @@ assert.deepEqual(
     sessionSnapshot: {
       snapshotLabel: "ui-machine-session/ui-machine-session.json",
     },
+    sessionReadiness: sessionReadinessFixture,
     sessionLoad: {
       iniWasmPath: "/work/session-machine.ini",
     },
@@ -311,6 +322,7 @@ assert.deepEqual(
       parameterWasmPath: "/work/session-linuxcnc.var",
       toolTableWasmPath: "/work/session-tool.tbl",
     },
+    sessionReadiness: sessionReadinessFixture,
     runReadiness: runReadinessFixture,
     selectedProgram: {
       source: "snapshot",
@@ -344,6 +356,7 @@ assert.deepEqual(
       toolTable: "/work/session-tool.tbl",
       gcode: "linuxcnc/gcode/ui-session.ngc",
     },
+    sessionReadiness: sessionReadinessFixture,
     loaded: {
       iniWasmPath: "/work/session-machine.ini",
       parameterWasmPath: "/work/session-linuxcnc.var",
@@ -383,6 +396,7 @@ const expectedExportReport = {
     toolTable: null,
     gcode: null,
   },
+  sessionReadiness: null,
   loaded: {
     iniWasmPath: "/work/session-machine.ini",
     parameterWasmPath: null,
@@ -446,6 +460,7 @@ assert.deepEqual(
       runWorkflow: "save-session-snapshot",
     },
     runReadiness: runReadinessFixture,
+    sessionReadiness: sessionReadinessFixture,
     run: {
       runStatus: "ok",
       canonicalEventCount: 2,
@@ -492,6 +507,7 @@ assert.deepEqual(
       },
     },
     runReadiness: expectedRunReadinessReport,
+    sessionReadiness: sessionReadinessFixture,
     lastAction: "run-gcode",
     error: null,
     session: {
@@ -525,6 +541,7 @@ const expectedBundleReport = {
     toolTable: null,
     gcode: "linuxcnc/gcode/ui-session.ngc",
   },
+  sessionReadiness: sessionReadinessFixture,
   loaded: {
     iniWasmPath: null,
     parameterWasmPath: null,
@@ -569,6 +586,7 @@ assert.deepEqual(
       runWorkflow: "save-session-snapshot",
     },
     runReadiness: runReadinessFixture,
+    sessionReadiness: sessionReadinessFixture,
     run: {
       runStatus: "ok",
       canonicalEventCount: 2,
@@ -593,6 +611,7 @@ assert.deepEqual(
         opfs: "OPFS: ready",
       },
       overview: expectedWorkflowOverview,
+      sessionReadiness: sessionReadinessFixture,
       lastAction: "run-gcode",
       error: null,
       runReadiness: expectedRunReadinessReport,

wasm-port/tests/ui/node/verify_ini_panel_ui_shell.mjs

@@ -96,6 +96,7 @@ assert.deepEqual(createControlPageSessionLoadState({ phase: "waiting-panel" }),
   controlViewReady: false,
   stateBundle: null,
   workflowStatus: null,
+  sessionReadiness: null,
   controlView: null,
   error: null,
 });
@@ -1078,6 +1079,7 @@ assert.deepEqual(missingStatusResult.missingStatusFields, [
   "overview",
   "controlView",
   "report",
+  "sessionReadiness",
   "runReadiness",
   "run",
   "session",