@ckanner/flywheel 0.33.0 → 0.33.1

package/CHANGELOG.md

@@ -5,6 +5,16 @@ results are recorded separately in the [release runbook](docs/en/releasing.md)
 and [validation index](docs/validation/README.md). Historical entries retain
 their original language.
 
+## 0.33.1 — Strict desktop read codecs
+
+- Fix task discovery and configuration reads rejected by the actual DSH Client
+  Gateway. Supply strict schema factories for session identity, read requests and
+  result envelopes; consume the dynamic namespace through an owned injected
+  scope, use the host Agent registry's `agentId` wire field, and preserve session
+  isolation, teardown and silent reads.
+- Exercise the shipped Client descriptor through the real public Client and Host
+  Gateway on both supported host fixtures instead of mocking Remote mounting.
+
 ## 0.33.0 — One complete npm distribution
 
 - Consolidate the CLI, DSH host/client, workers, embedded skills and four native

package/dist/client.js

@@ -815,6 +815,53 @@ function Feedback({ control, selection, reconcile, t }) {
         !selection.taskDir.trim() && h('p', null, t('taskRequired'))));
 }
 
+// Plain-JS external clients supply real schema factories through the public
+// Typert codec contract; src-json is not a valid generated Client input codec.
+function consoleReadCodec(type, parse) {
+  return { mode: 'strict', typeSymbol: '@ckanner/flywheel#' + type, create: () => ({ parse }) };
+}
+function consoleReadObject(value, keys, label) {
+  if (!record(value) || Object.keys(value).some(key => !keys.includes(key))) throw new Error('Invalid ' + label);
+  return value;
+}
+function consoleReadString(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('Invalid ' + label);
+  return value;
+}
+function consoleReadInput(value) {
+  consoleReadObject(value, ['action', 'taskDir', 'cwd', 'probe', 'editor', 'packet', 'runId', 'sessionKey', 'delivery'], 'console read request');
+  if (!['runs', 'status', 'config', 'config-edit', 'metrics', 'history', 'node', 'delivery', 'doctor'].includes(value.action)) throw new Error('Console Remote accepts reads only');
+  const output = { action: value.action };
+  for (const key of ['taskDir', 'cwd', 'packet', 'runId', 'sessionKey']) {
+    if (value[key] !== undefined) output[key] = consoleReadString(value[key], key);
+  }
+  if (value.probe !== undefined) {
+    if (value.action !== 'doctor' || typeof value.probe !== 'boolean') throw new Error('Invalid doctor probe');
+    output.probe = value.probe;
+  }
+  if (value.action === 'config-edit') {
+    consoleReadObject(value.editor, ['scope'], 'configuration scope');
+    if (!['global', 'project'].includes(value.editor.scope)) throw new Error('Invalid configuration scope');
+    output.editor = { scope: value.editor.scope };
+  } else if (value.editor !== undefined) throw new Error('Editor requires config-edit');
+  if (value.action === 'delivery') {
+    consoleReadObject(value.delivery, ['action', 'headBranch'], 'delivery inspection');
+    if (value.delivery.action !== 'inspect') throw new Error('Delivery Remote accepts inspection only');
+    output.delivery = { action: 'inspect' };
+    if (value.delivery.headBranch !== undefined) output.delivery.headBranch = consoleReadString(value.delivery.headBranch, 'headBranch');
+  } else if (value.delivery !== undefined) throw new Error('Delivery requires inspection');
+  if (value.action === 'node' ? !/^M\d+-T\d+$/.test(output.packet ?? '') : value.packet !== undefined) throw new Error('Invalid node packet');
+  if (value.action === 'history' ? !output.sessionKey : value.sessionKey !== undefined) throw new Error('Invalid history session key');
+  if (value.runId !== undefined && (value.action !== 'metrics' || value.runId.length > 128 || /[\0\r\n]/.test(value.runId))) throw new Error('Invalid metrics run ID');
+  return output;
+}
+function consoleReadResult(value) {
+  consoleReadObject(value, ['result'], 'console read result');
+  const result = consoleReadObject(value.result, ['kind', 'text'], 'console result envelope');
+  if (!['success', 'error'].includes(result.kind) || typeof result.text !== 'string') throw new Error('Invalid console result envelope');
+  return { result: { kind: result.kind, text: result.text } };
+}
+
 exports.inject = ['slots', 'remote', 'remote.commands', 'locale'];
 exports.apply = function apply(ctx) {
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'flywheel: locales');
@@ -833,10 +880,25 @@ exports.apply = function apply(ctx) {
   const readsReady = ctx.remote.$mount({ package: '@ckanner/flywheel', descriptors: [{
     id: '@ckanner/flywheel#flywheelConsole/read', service: 'flywheelConsole', namespace: 'flywheelConsole', method: 'read',
     invocation: { kind: 'direct' }, parameters: [
-      { name: 'agent', wire: 'sessionId', source: 'lookup', lookup: 'agent', codec: { mode: 'src-json' } },
-      { name: 'input', wire: 'input', source: 'json', codec: { mode: 'src-json' } },
-    ], cancellation: { parameter: 'signal' }, result: { mode: 'src-json' },
-  }] });
+      { name: 'agent', wire: 'agentId', source: 'lookup', lookup: 'agent', codec: consoleReadCodec('SessionId', value => consoleReadString(value, 'sessionId')) },
+      { name: 'input', wire: 'input', source: 'json', codec: consoleReadCodec('ConsoleReadRequest', consoleReadInput) },
+    ], cancellation: { parameter: 'signal' }, result: { ...consoleReadCodec('ConsoleReadResult', consoleReadResult), decode: consoleReadResult },
+  }] }).then(async () => {
+    let readConsole;
+    // The namespace is installed asynchronously by $mount. Own its consumer in
+    // an injected child scope; the outer plugin cannot access undeclared services.
+    const consumer = ctx.inject(['remote.flywheelConsole'], scope => {
+      readConsole = (sessionId, request) => scope.remote.flywheelConsole.read(sessionId, request);
+    });
+    try {
+      await consumer;
+      if (disposed || !readConsole) throw new Error('Flywheel read scope is unavailable');
+      return readConsole;
+    } catch (error) {
+      await consumer.dispose();
+      throw error;
+    }
+  });
   // A missing read capability is a visible error, never a noisy command fallback.
   readsReady.catch(() => {});
   ctx.slots.inject('conversation.view', () => ctx.slots.register({
@@ -851,7 +913,7 @@ exports.apply = function apply(ctx) {
         control = createControl(async request => {
           const value = readReply(await (mutates(request.action) || request.action === 'status' && control?.source.getSnapshot().uncertainty
             ? ctx.remote.commands.execute(sessionId, '/flywheel ' + JSON.stringify(request), [])
-            : readsReady.then(() => ctx.remote.flywheelConsole.read(sessionId, request))), request);
+            : readsReady.then(readConsole => readConsole(sessionId, request))), request);
           if (Array.isArray(value.runs)) value.runs = value.runs.filter(item => item.hostSessionId === sessionId);
           return value;
         }, pendingOperations, () => disposed);

package/docs/design.md

@@ -694,7 +694,7 @@ doctor 的状态为 pass/fail/warn/unknown/skipped，必需检查 fail 才使 ok
 
 会话视图不提供任务选择器。只接受当前会话投影和精确匹配 `hostSessionId` 的运行索引；其他会话及无归属记录不可见。显式工具关联优先；没有投影时按开始时间选择最近的本会话任务，再请求 Go 状态。单纯打开页面、刷新或旧版 UI 产生的 `/flywheel status` 日志不能创建新的任务关联。未确认操作始终锁定原目标，fork 不继承关联。无关联时显示空状态，独立终端任务需要在目标会话通过 `flywheel_control status` 显式关联，不能按目录猜测或扫描磁盘。
 
-自动发现、轮询、配置读取、节点与指标读取使用公开 Typert `flywheelConsole/read` Remote，宿主解析实际 Agent／Session，按会话过滤运行并核对任务身份；该入口只允许读取，不能启动或修改任务。读取不执行 slash command，不追加会话事件，不把 JSON 刷进聊天。UI 变更和未知结果的显式 status 核对仍走有持久回执的命令，确保重载后可恢复操作锁；人工命令及模型工具保持原 JSON 协议，不删除历史事件。读取通道不可用时显示错误，不回退到刷屏命令。
+自动发现、轮询、配置读取、节点与指标读取使用公开 Typert `flywheelConsole/read` Remote，宿主解析实际 Agent／Session，按会话过滤运行并核对任务身份；该入口只允许读取，不能启动或修改任务。读取不执行 slash command，不追加会话事件，不把 JSON 刷进聊天。UI 变更和未知结果的显式 status 核对仍走有持久回执的命令，确保重载后可恢复操作锁；人工命令及模型工具保持原 JSON 协议，不删除历史事件。读取通道不可用时显示错误，不回退到刷屏命令。 客户端挂载使用公开 strict codec 工厂校验 Session ID、只读请求和返回 envelope，Agent lookup 的 wire 字段遵循真实宿主的 `agentId`，不以 src-json 充当生成的客户端输入 codec。兼容测试必须让实际打包 descriptor 经过真实 Client `$mount` 和 Host Gateway，不能仅模拟挂载成功。动态挂载完成后，以受父插件拥有的 `ctx.inject` 子作用域消费 `remote.flywheelConsole`，卸载时同时撤销读取 consumer；不得从未声明注入的外层 context 访问它。
 
 项目、任务记录和分支在有值时直接显示。阶段操作、来源、失败证据、会话入口及配置操作使用普通分组，不提供折叠控件；视图导航与画布子图导航仍保留。已有运行只提供适用的继续／停止操作，准备好的新任务才显示 Auto／Quick／Full 启动选项。主工作区只有流程与记录，设置独立进入。设置使用运行方式、模型与会话、预算与重试、JEV、高级与诊断五个分类；重新读取、完整 JSON 和原始回执放在高级与诊断，范围及保存／撤销／恢复默认保持固定位置。窄窗口的设置导航行固定 54px、每项 36px；触控指针下按钮为 44px，并使用 5px 上下留白，不与内容分享最小高度。离开设置、切换范围和重新读取保护未保存草稿。
 

package/docs/en/flow-console.md

@@ -30,7 +30,7 @@ unavailable association tool explicitly. Standalone terminal tasks without a hos
 While the canvas is visible, registered-task discovery refreshes every five seconds.
 An observed running task refreshes status every two seconds, backing off to ten
 seconds after an unsuccessful response. Hidden documents skip those requests.
-Refresh uses a read-only Remote instead of a slash command, so it does not append chat events or JSON. Explicit mutations and uncertain-result reconciliation retain durable command receipts. Old chat records are preserved.
+Refresh uses a read-only Remote instead of a slash command, so it does not append chat events or JSON. Explicit mutations and uncertain-result reconciliation retain durable command receipts. Old chat records are preserved. Session identity and read requests use strict Remote codecs; an unavailable or malformed read remains a visible error rather than falling back to chat commands.
 
 ## This stage versus the full workflow
 

package/docs/validation/2026-11-14-release-0.33.0.md

@@ -0,0 +1,49 @@
+# 0.33.0 单包正式发行与桌面验收
+
+[验证索引](README.md) · [单包工程验证](2026-11-14-single-package.md)
+
+## 正式身份
+
+- PR：[#45](https://github.com/ckanner/flywheel/pull/45)。
+- 标签：`v0.33.0`，源码 `ac1ed320c68f6a8a466005985264e65b5a72fad9`。
+- tree：`7e95a8219705354a3a26146facdd56182a971140`。
+- snapshot SHA-256：`707c11a714e300c62da9bd4d6d5dbf7cad8ea6c90c76a67a642e3aad298bfa78`，dirty=false，candidate format 2。
+- 唯一 npm 包：`@ckanner/flywheel@0.33.0`，tarball `ckanner-flywheel-0.33.0.tgz`，18,623,823 bytes。
+- tarball integrity：`sha512-cvXjIw9LblMJabnEHtPNjj34mbZdJVbwH/R38U+AUkpyxOKxbqzO/7kdV1IStOC+l+/r2mDWd8v1icdYG/ue6g==`。
+- candidate.json SHA-256：`d4bb51bf24f27a5d03cea7e78053d45cc7d265868286b1f0827144b3267edb15`。
+- [正式发布 workflow](https://github.com/ckanner/flywheel/actions/runs/43568347331) 构建一次，双 OS 使用原始产物；本机下载的 Actions ZIP 摘要也已核对。
+
+## 源码与候选验证
+
+PR CI 的 Linux 和 macOS 均通过，包括逐函数 100% Go 覆盖率、插件、桥接、实际 npm 安装和 36 条会话场景。
+PR 首次 macOS job 的 machine 测试包触发默认 10 分钟总超时；当时当前用例仅运行 2 秒。
+该用例本机连续 10 次通过，随后同提交、同候选、原断言和原时限复跑通过。
+保留[首次失败](https://github.com/ckanner/flywheel/actions/runs/43563991853/attempts/1)和[复跑通过](https://github.com/ckanner/flywheel/actions/runs/43563991853/attempts/2)，不声称累计耗时风险已被修复。
+
+正式标签的双平台验证均在首次运行通过：Go 全门禁、插件与兼容宿主、三项跨进程桥接、151 条 npm 检查、打包 Host／Client 10 条、安装 13 条、36 条会话场景；Linux 另通过核心 race。
+本机对下载的同一正式候选另通过 Host／Client 10 条和实际安装 13 条，无跳过。
+
+## 发布与安装回执
+
+正式 workflow 首次通过 OIDC 上传后，版本公开可见性超过 180 秒窗口，publish job 停止，未移动 latest。
+随后从 registry 核对到与候选一致的 SHA-512，仅重跑失败 job，复用原始 artifact；回执包含
+`Verified existing @ckanner/flywheel@0.33.0`，公开 npm 安装通过，OIDC dist-tag 更新及最终 latest 校验通过。
+未使用 npm token 回退或逐包浏览器认证；未重建或覆盖已接受版本。
+
+本机在 DSH 无活动会话后退出桌面并备份配置、安装记录及 profile 清单。CLI 和 desktop profile
+均升级至完整包 0.33.0，官方 CLI 移除旧插件注册；两处各 264 个文件与正式 tarball 一致。
+其他插件依赖、cordis 配置及兼容设置不变；pnpm 的 `minimumReleaseAgeExclude` 自动追加
+新包的精确版本，这是官方安装器产生的包管理元数据。全局配置与最新默认模板语义一致、
+原始字节不变，四项无推理 SDK 探测通过。真实账号推理未测。
+
+## 桌面验收失败与后续修复
+
+重载后视图出现，但任务与配置读取报 `generated Remote flywheelConsole/read field "sessionId" has no strict codec`。
+因此 **0.33.0 的桌面读取验收失败**，不能用源码／候选或 SDK 通过代替。
+
+客户端原来用 src-json 挂载只读 Remote，旧 renderer 测试模拟了 `$mount`，Host 测试则直接调用
+Gateway，遗漏真实 Client 注册。这一 descriptor 在 v0.32.1 源码中已经存在；不能据此次失败
+倒推旧版本曾完成该路径的真实验收。当前 DSH 0.2.2-rc.3 要求 strict 输入 codec。
+
+后续 0.33.1 保留单包结构，补充有实际校验的公开 codec 工厂，并让打包 Client descriptor
+通过真实 Client 和 Host Gateway。0.33.0 产物与标签保持不变；补丁的实际验收另行记录。

package/docs/validation/README.md

@@ -11,6 +11,7 @@ Historical records retain their original language and findings.
 
 | Date | Record |
 | --- | --- |
+| 2026-11-14 | [0.33.0 单包正式发行与桌面读取缺口](2026-11-14-release-0.33.0.md) |
 | 2026-11-14 | [0.33.0 单包分发工程验证](2026-11-14-single-package.md) |
 | 2026-11-13 | [0.32.1：DSH 兼容系列范围与发行（桌面重载待完成）](2026-11-13-release-0.32.1.md) |
 | 2026-11-13 | [0.32.0 正式发行与本机安装（桌面重载待完成）](2026-11-13-release-0.32.0.md) |

package/docs/zh-CN/flow-console.md

@@ -26,7 +26,7 @@ Skill 已加载不代表引擎已经启动。`flywheel-task` 准备适合的契
 无会话 ID 的独立终端任务需要在目标会话显式关联。
 
 画布可见时，每五秒刷新已登记任务；已观察为运行中的任务每两秒刷新状态，失败后
-延长到十秒。页面隐藏时跳过这些请求。刷新使用只读 Remote，不执行对话命令，也不新增聊天事件或 JSON。显式修改与未知结果核对仍保留持久命令回执；既有聊天历史保持原样。
+延长到十秒。页面隐藏时跳过这些请求。刷新使用只读 Remote，不执行对话命令，也不新增聊天事件或 JSON。显式修改与未知结果核对仍保留持久命令回执；既有聊天历史保持原样。会话身份与读取请求使用严格 Remote codec；读取不可用或格式不合法时保留可见错误，不回退到对话命令。
 
 ## 本次阶段与完整流程
 

package/native/manifest.json

@@ -1,22 +1,22 @@
 {
   "protocol": 1,
-  "version": "0.33.0",
+  "version": "0.33.1",
   "platforms": {
     "darwin-arm64": {
       "bytes": 10317010,
-      "sha256": "7e114bb555ff4e5706c71f60b7704d1416b7e3978502df85ab1e97575ffb9735"
+      "sha256": "4efb5efab4fce7b6fd86d15d6fcc21530b4aee169613b5009e2cee452c277c9c"
     },
     "darwin-amd64": {
       "bytes": 11236784,
-      "sha256": "34802d30c3e0bedee9c896779eb93c8d902b4b92af5329e9036f85632afe8d9f"
+      "sha256": "a93e2f8802fb4a1c258dc331546e0a0e56165aec92e90e3eb64e42d88ac49b15"
     },
     "linux-arm64": {
       "bytes": 10092704,
-      "sha256": "985534db0df9baece46e3348d36a98c88e3e608a61f1862ba765230c52438c69"
+      "sha256": "82c611cbada4d1a8b932b619cfe1fb15b30aee2e35ba3fb1da527c000c19cffc"
     },
     "linux-amd64": {
       "bytes": 11014304,
-      "sha256": "7b01b4c280f9dad795a05da3c347e25cdc3e9a1170eb1a40ef89ed9e91aa9d4a"
+      "sha256": "7f49ac00660cf97502d27f150e7969b04cac50c894c5f8b7149a05a19f681316"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckanner/flywheel",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "description": "A deterministic Go orchestrator for coding-agent loops, with task contracts, verification gates, Git worktrees, and DSH desktop integration.",
   "bin": {
     "flywheel": "bin/flywheel.js",
@@ -54,7 +54,7 @@
     "test": "node --test npm/test/*.test.js",
     "test:install": "node scripts/test-packed-host.js && node --test npm/test/install.integration.js",
     "test:registry": "node npm/test/registry-smoke.js",
-    "build:npm": "bash scripts/build-npm.sh 0.33.0 dist-npm",
+    "build:npm": "bash scripts/build-npm.sh 0.33.1 dist-npm",
     "test:sessions": "node scripts/test-session-evaluation.js"
   },
   "dependencies": {

package/plugins/dsh/PROTOCOL.md

@@ -464,6 +464,8 @@ host 在调用 Go 前把任务和仓库目录规范化为真实路径，并校
 
 ### 会话控制台的静默读取
 
+客户端参数与结果使用公开 `strict` codec（`typeSymbol`、`create().parse`）；结果还提供同一校验的 `decode`。Agent lookup 使用宿主规定的 wire 字段 `agentId`，其值仍为当前 Session ID；不能自行改名为 `sessionId`。Session ID 必须为非空字符串，请求只允许具名读取动作及相应字段，返回值保持 `{ result: { kind, text } }`。严格 codec 不替代 Host 的 Session／任务归属检查及 Go 控制验证；客户端仍只导入共享 React。`$mount` 成功后，通过父插件拥有的 `ctx.inject(['remote.flywheelConsole'])` 子作用域访问动态 namespace，随父插件撤销；初始外层 context 不直接访问未注入的服务。
+
 `flywheelConsole/read` 是公开 Typert Remote，参数为宿主解析的 `agent`、控制请求 `input`
 和取消信号 `signal`。客户端显式挂载描述符，只有 React 是运行时共享模块。
 宿主只接受 runs/status/config/config-edit/metrics/history/node/delivery/doctor；其他 action