@ckanner/flywheel 0.33.1 → 0.34.0

package/node_modules/dsh-preset-generator/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## 0.4.0
+
+Export a pure ESM SDK composition API alongside the existing desktop CLI.
+`createSdkPtcComposition` shares daily/heavy policy and returns an isolated PTC
+overlay with canonical base/bundle provenance. `inspectPtcBundle` distinguishes
+same-version source bundles without inferring runtime support, and
+`validateSdkPtcAdmission` checks correlated executor/output/image observations.
+The API neither writes the desktop profile nor mounts a named preset or grants
+GUI/delegation access. Existing profile-preservation tests now use portable ASAR
+fixtures and run in CI without the Mac application.
+
+The CLI now creates an absent output file in an existing parent directory,
+including a profile's first `cordis.patch.yml`. Existing files retain the same
+merge behavior; only `ENOENT` is treated as an empty patch. Other read errors
+still stop before writing, and missing parent directories are not created.
+Exclusive first creation also preserves a patch written concurrently.
+
+## 0.3.0
+
+Both generated presets now use PTC.
+
+**LCU moves to a PTC bridge.** The `heavy` preset no longer swaps in
+`tool-executor-native`; LCU's Computer/Browser runtime is exposed as the PTC
+`cua` object instead of a directly-callable `js` tool. A profile regenerated
+against 0.3.0 therefore has `tool-executor-ptc` in both `daily` and `heavy`.
+
+
+## 0.2.0
+
+Track DSH Desktop 0.2.2 and stop generating the deprecated presentation selector.
+
+**The generated presets mount the executor directly.** DSH 0.2.2 deprecates
+`@deepseek-ai/dsh-agent-tool-presentation`; the base preset now carries
+`@deepseek-ai/dsh-tool-executor-ptc`. The generator replaces that row with
+`tool-executor-ptc` (daily) or `tool-executor-native` (heavy) instead of writing a
+`mode:` field, and still accepts a pre-0.2.2 base that has the old selector.
+
+**Re-run after upgrading DSH.** The 0.2.2 base adds `tool-office`, the
+`tool-fs.applyPatch` option, and `tool-subagent-control.interrupt`; a re-run picks
+them up. The `--dry-run` output now matches the current profile block except for
+these base changes.
+
+## 0.1.1
+
+Track DSH Desktop 0.2.1.
+
+**`heavy` uses `native` presentation.** DSH 0.2.1 removed the `both` tool-presentation mode; a preset declares
+one presentation and only `native` and `ptc` exist. `heavy` now asks for `native`, which keeps computer-use tools
+directly callable and gives up the PTC `run_code` surface for that preset. A profile regenerated against the new
+app no longer fails the `heavy` mount.
+
+**Re-run after upgrading DSH.** The shipped base changed again: `persona.suffix` with `{{cwd}}` is gone (the
+variable no longer exists and prompt assembly rejects it), `time-context` and `tool-schedule` rows were added,
+`backgroundMode` was removed from `tool-subagent`, and the per-preset `tool-subagent-codex` /
+`tool-subagent-claude-code` / `tool-ralph` rows were dropped. The generator reads the installed base, so a re-run
+picks all of it up; the tests now pin the current surface instead of the old Codex-row expectation.
+
+## 0.1.0
+
+First release, as a project of its own.
+
+**Moved out of `dsh-plugin-lcu`.** It generates presets that serve more than one plugin, and the region it writes
+is also written by DSH's settings UI, so it does not belong to any one plugin — least of all one whose script was
+rewriting a profile region shared with settings it does not own. The move is behaviour-preserving: generating
+from the same profile with both produced byte-identical output.
+
+**The marker still names the old path.** `BEGIN` contains `scripts/gen-presets.mjs` on purpose: a profile
+generated before the move already has that exact string, and a different one would make the script append a
+second block instead of replacing the first.
+
+**Replaces only its own entry.** The region between the markers is not exclusively this script's — the settings
+UI appends `agent-preset-registry` and `subagent-model-selection-settings` there. Splicing the whole region
+deleted them; re-emitting them after the block left another copy behind on every later settings write. A run now
+replaces the single `- insert:` entry it wrote and leaves everything else byte for byte where it is, so there is
+nothing to move and nothing to accumulate.

package/node_modules/dsh-preset-generator/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kanner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/dsh-preset-generator/README.md

@@ -0,0 +1,149 @@
+# dsh-preset-generator
+
+English | [中文](docs/README.zh.md)
+
+Materialize [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) agent presets from the base preset
+that ships inside the application.
+
+```sh
+node src/gen-presets.mjs              # write into ~/.dsh/profiles/desktop
+node src/gen-presets.mjs --dry-run    # print the block, write nothing
+node src/gen-presets.mjs --out FILE   # write somewhere else
+node src/gen-presets.mjs --daily-only # refuse if the file already defines heavy
+```
+
+An absent output file is created in its existing parent directory. This also
+supports a profile that does not yet have `cordis.patch.yml`. Existing files are
+updated in place, preserving other settings. The parent directory must already
+exist; unreadable files, directory targets and other filesystem errors stop the
+run without treating existing content as empty.
+New-file creation is exclusive: a patch created by another writer during the
+run is not overwritten.
+
+## Why this exists
+
+DSH agent presets have **no inheritance**. A preset's `plugins` list is its complete composition, and a patch
+replaces a whole entry rather than merging into it. So a custom preset has to restate the base preset — and the
+base ships inside the application and changes when DSH is upgraded, which makes hand-copying it a losing game.
+
+This writes that restatement: it reads the base from the installed `app.asar`, applies a policy, and writes the
+marked region of a profile's `cordis.patch.yml`.
+
+It is deliberately **not part of a plugin**. The presets it generates serve more than one plugin, and the region
+it writes is also written by DSH's own settings UI. A tool that belongs to one plugin ends up rewriting a file
+that several parties own; this one belongs to nobody in particular, which is the honest description.
+
+## The marker is load-bearing
+
+The `BEGIN` marker contains the path this file lived at when the first profiles were generated. It has to keep
+containing that path: a profile generated before the move already has the exact string, and a different one would
+make this script **append a second block** instead of replacing the first.
+
+## What it writes
+
+| Preset | Base | Policy |
+|---|---|---|
+| `daily` (日常) | the shipped `ptc` preset | PTC executor; daily coding label |
+| `heavy` (重活) | the same `ptc` preset | the same executor policy; heavy work label |
+
+Both presets use PTC. LCU exposes its ChatGPT-app Computer/Browser runtime through the PTC `cua`
+bridge: `cua.getApp`, `cua.getTab`, screenshots and handle methods all run through `run_code`, so
+`heavy` no longer opts out of PTC for a directly-callable native `js` tool.
+The generated plugin lists currently have the same policy. GUI availability and
+Codex delegation depend on separately mounted providers and their allowlists;
+the name `heavy` does not itself grant either capability.
+
+The official Codex tool is no longer a per-preset row: as of DSH 0.2.1 the `@deepseek-ai/dsh-subagent-codex`
+bundle contributes a **global** `subagent_codex` tool, and a separate provider (`dsh-subagent-codex-pro`)
+registers its own same-named tool per Agent for these presets, shadowing the global one. Two registrations in
+*one* scope still collide, so nothing may enable a same-name `tool-subagent` row beside that provider.
+
+## What it must not touch
+
+The region between the markers is **not exclusively this script's**. DSH's settings UI appends its own entries
+there — `agent-preset-registry` and `subagent-model-selection-settings` have both landed between the markers —
+and so may anything else that writes a profile patch.
+
+So a run replaces **only its own entry**: the `- insert:` shell carrying the preset rows. Everything else in the
+region is left exactly where it is, byte for byte.
+
+That is a stronger property than handling them carefully. An earlier version replaced the whole region, then
+re-emitted the entries it had not written after the block, then de-duplicated them against copies already
+outside it — three mechanisms, each fixing a failure of the one before:
+
+| Approach | What went wrong |
+|---|---|
+| Replace the region | Deleted the settings entries silently |
+| Re-emit them after the block | The next settings write landed inside again, and the run left another copy each time |
+| De-duplicate by id | Correct, but ~60 lines that exist only to undo a move that should not happen |
+
+Replacing one entry has none of those failure modes, because nothing is ever moved: there is no copy to
+de-duplicate and nothing to accumulate. Entries that are not ours are not read, not rewritten, and not
+relocated — including values this script would not have chosen.
+
+## Development
+
+```sh
+npm test    # portable CLI/ASAR fixtures and SDK composition contracts
+```
+
+The tests use a synthetic ASAR and profile patch, so preservation, idempotency,
+legacy selectors and direct executor rows run on CI without a desktop app. They
+do not certify a user's installed application or call a model.
+
+## SDK composition API
+
+The package also exports a pure ESM API. Importing it performs no file access,
+runtime launch, model call, or desktop-profile write. Desktop generation and SDK
+composition share `src/policy.mjs`; SDK callers apply a separate profile patch.
+
+```js
+import {
+  inspectPtcBundle, createSdkPtcComposition, validateSdkPtcAdmission,
+} from 'dsh-preset-generator'
+
+// Values read by the caller from the exact installed bundle, not a version guess.
+const evidence = inspectPtcBundle({ packageJson, files, sourceRevision })
+const composition = createSdkPtcComposition({
+  runtimeProfile: 'flywheel-sdk', preset: 'heavy', baseRows, ptcEvidence: evidence,
+})
+// Apply composition.overlay via the SDK host's profile loader, then run a probe.
+const admission = validateSdkPtcAdmission(composition, observed, { requireImages: true })
+```
+
+`baseRows` are effective JSON plugin rows with unique ids, after the host has
+resolved its configuration; nested patch `insert` directives are rejected. The
+overlay disables the native executor, enables PTC, and sets
+`tool-fs.applyPatch: false`, preserving supplied fs/PTC configuration. A known
+legacy `tool-presentation` row is disabled too. `desktop` is refused as an SDK
+profile. Absent `baseRows`, the result is the official minimal SDK PTC patch; it
+does not claim to have inspected custom configuration.
+
+The returned `digest` binds the profile, policy, base, overlay and bundle
+evidence. `compositionDigest(value)` hashes canonical JSON; files are supplied as
+relative paths mapped to their exact text. `inspectPtcBundle` returns per-file
+hashes, actual manifest exports and descriptive source clues. It always leaves
+`outputContract: 'unknown'`: release rc.3 and later master can share
+`0.2.2-rc.3` while changing exports and image/output semantics. Source identity
+must accompany the version. See the [release PTC manifest](https://github.com/deepseek-ai/deepseek-harness/blob/38a6a5c965aa99ab525161efb7cc5cf1fe62fced/packages/core/tool-executor-ptc/package.json)
+and [later manifest](https://github.com/deepseek-ai/deepseek-harness/blob/39163dd30f703a79079e2d2446545cff3c453738/packages/core/tool-executor-ptc/package.json).
+
+Admission requires observed `compositionDigest`, `runtimeProfile`,
+`executor: 'ptc'`, `activeExecutors: ['ptc']`, `tools` containing `run_code`,
+`probeStatus: 'passed'`, and a verified `outputContract` of
+`deferred-context-v1` or `inspect-image-v1`. Supplied bundle evidence requires a
+matching observed `bundleDigest`. `requireImages` additionally requires
+`imageProbeStatus: 'passed'`; an absent image probe never advertises image
+support. The worker obtains these facts from its actual runtime. This library
+only checks the receipt, hashes all JSON observations, and rejects a composition
+modified after generation. It does not authenticate the receipt transport.
+
+`provenance.kind` is `sdk-global-composition` and `namedPresetMounted` is always
+false: sharing daily/heavy policy is not a named-preset SDK RPC. GUI and
+delegation remain separate grants. A consumer adding permission or provider
+overlays must also bind the complete final configuration in its own digest.
+Executor image probing and delivery through the provider are separate checks.
+
+## License
+
+MIT.

package/node_modules/dsh-preset-generator/docs/README.zh.md

@@ -0,0 +1,95 @@
+# dsh-preset-generator
+
+[English](../README.md) | 中文
+
+从**应用内自带的基底 preset** 生成 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 agent preset。
+
+```sh
+node src/gen-presets.mjs              # 写进 ~/.dsh/profiles/desktop
+node src/gen-presets.mjs --dry-run    # 只打印块，不写文件
+node src/gen-presets.mjs --out FILE   # 写到别处
+node src/gen-presets.mjs --daily-only # 文件里已有 heavy 时拒绝
+```
+
+目标文件不存在时，会在已有的父目录中创建文件；首次使用、profile 里尚无
+`cordis.patch.yml` 时也可以直接生成。已有文件则原地更新并保留其他设置。
+父目录必须已经存在；无法读取的文件、目录类型的目标及其他文件系统错误会终止
+操作，不会把已有内容当作空文件处理。
+新文件以独占方式创建，运行期间其他程序抢先写入的补丁不会被覆盖。
+
+## 为什么需要它
+
+DSH 的 agent preset **没有继承**。一个 preset 的 `plugins` 列表就是它完整的组合，而 patch 是**整体替换**一个条目而不是合并进去。所以自定义 preset 必须把基底 preset 重述一遍 —— 而基底随应用一起发布、会随 DSH 升级变化，手抄注定跟不上。
+
+本工具做的就是这份"重述"：从已安装的 `app.asar` 里读出基底，套用一份策略，写进某个 profile 的 `cordis.patch.yml` 的**标记区间**。
+
+它**刻意不属于任何插件**。它生成的 preset 服务于不止一个插件，而它写入的那个区间**DSH 自己的设置 UI 也会写**。一个属于某个插件的工具，最后就在改写一个多方共有的文件；这个工具不属于任何一方，这才是诚实的描述。
+
+## 标记是承重的
+
+`BEGIN` 标记里写着这个文件**曾经所在的路径**。它必须继续写着那个路径：在本次搬迁之前生成的 profile 里已经含有那串确切文本，换一串会让本脚本**追加第二个块**而不是替换第一个。
+
+## 它写什么
+
+| preset | 基底 | 策略 |
+|---|---|---|
+| `daily`（日常） | 自带的 `ptc` preset | PTC executor；标记为日常编码 |
+| `heavy`（重活） | 同一个 `ptc` preset | 相同的 executor 策略；标记为重活 |
+
+两个 preset 都使用 PTC。LCU 通过 PTC 的 `cua` 桥暴露 ChatGPT 应用的 Computer/Browser runtime；`cua.getApp`、`cua.getTab`、截图和 handle 方法都经 `run_code` 运行，重活不再切换到 native executor 的直接 `js` 工具。目前生成的插件列表使用相同策略；GUI 与 Codex 委派是否可用取决于另外挂载的 provider 和各自 allowlist，`heavy` 这个名字本身不授予这些能力。
+
+官方的 Codex 工具不再是 per-preset 行：从 DSH 0.2.1 起，`@deepseek-ai/dsh-subagent-codex` bundle 提供的是**全局**的 `subagent_codex` 工具；独立 provider（`dsh-subagent-codex-pro`）在这些 preset 里按 Agent 注册同名工具，遮蔽全局那个。而**同一个** scope 内的两次注册仍会冲突，所以不能在这个 provider 之外再启用同名的 `tool-subagent` 行。
+
+## 它绝不能碰的东西
+
+标记之间的区间**不是本脚本独占的**。DSH 的设置 UI 会把它的条目追加在那里 —— `agent-preset-registry` 和 `subagent-model-selection-settings` 都曾落在标记之间 —— 别的往 profile patch 里写东西的组件也可能如此。
+
+所以一次运行**只替换它自己那一个条目**：那个携带 preset 行的 `- insert:` 外壳。区间内其他一切**逐字节留在原位**。
+
+这比"小心处理它们"是更强的性质。早先的实现替换整个区间，然后把不是自己写的条目重新发到块后面，再对区间外的副本做去重 —— 三个机制，每一个都在补前一个的失败：
+
+| 做法 | 出了什么问题 |
+|---|---|
+| 替换整个区间 | 静默删掉了设置项 |
+| 把它们重新发到块后 | 下一次设置写入又落进区间，每次运行多留一份 |
+| 按 id 去重 | 对了，但那是约 60 行只为撤销一次**本不该发生的搬动** |
+
+只替换一个条目就不存在这些失败模式，因为**什么都不搬动**：没有副本要去重，也没有东西会累积。不属于我们的条目**连读都不读、不重写、不搬移** —— 包括我们不会选的值。
+
+## 开发
+
+```sh
+npm test    # 跨平台 CLI/ASAR 夹具及 SDK composition 契约
+```
+
+测试使用合成 ASAR 与 profile patch，配置保留、幂等、旧 selector 和新 executor 行都会在没有桌面应用的 CI 上实际执行。它们不认证用户已安装的应用，也不调用模型。
+
+## SDK composition API
+
+本包还导出纯 ESM API。导入不会读取文件、启动 runtime、调用模型或改写桌面 profile。桌面生成器与 SDK composition 共用 `src/policy.mjs`，SDK 调用方将 patch 应用于独立 profile。
+
+```js
+import {
+  inspectPtcBundle, createSdkPtcComposition, validateSdkPtcAdmission,
+} from 'dsh-preset-generator'
+
+// 调用方从确切的已安装 bundle 读取这些值，不能只猜版本号。
+const evidence = inspectPtcBundle({ packageJson, files, sourceRevision })
+const composition = createSdkPtcComposition({
+  runtimeProfile: 'flywheel-sdk', preset: 'heavy', baseRows, ptcEvidence: evidence,
+})
+// 经 SDK 宿主的 profile loader 应用 composition.overlay，然后执行探针。
+const admission = validateSdkPtcAdmission(composition, observed, { requireImages: true })
+```
+
+`baseRows` 是宿主解析完配置后的有效 JSON 插件行，id 必须唯一，不能传未展开的 `insert` 指令。overlay 禁用 native executor、启用 PTC、设置 `tool-fs.applyPatch: false`，同时保留已提供的 fs/PTC 配置。已知的旧 `tool-presentation` 行也会被禁用。SDK profile 拒绝 `desktop`；不提供 `baseRows` 时，只产生官方最小 SDK PTC patch，不声称检查过自定义配置。
+
+返回的 `digest` 绑定 profile、策略、基底、overlay 和 bundle 证据。`compositionDigest(value)` 对规范化 JSON 求哈希；`files` 是相对路径到确切文本的映射。`inspectPtcBundle` 返回各文件哈希、实际 manifest exports 和描述性的源码线索，始终保留 `outputContract: 'unknown'`：rc.3 release 与后续 master 可能同为 `0.2.2-rc.3`，但 exports 与图片/输出语义不同，因此版本必须附带源码身份。参见 [release PTC manifest](https://github.com/deepseek-ai/deepseek-harness/blob/38a6a5c965aa99ab525161efb7cc5cf1fe62fced/packages/core/tool-executor-ptc/package.json) 与[后续 manifest](https://github.com/deepseek-ai/deepseek-harness/blob/39163dd30f703a79079e2d2446545cff3c453738/packages/core/tool-executor-ptc/package.json)。
+
+准入要求实际观测到匹配的 `compositionDigest`、`runtimeProfile`、`executor: 'ptc'`、`activeExecutors: ['ptc']`、包含 `run_code` 的 `tools`、`probeStatus: 'passed'`，以及已验证的 `outputContract`（`deferred-context-v1` 或 `inspect-image-v1`）。若 composition 提供了 bundle 证据，观测的 `bundleDigest` 也必须匹配。`requireImages` 还要求 `imageProbeStatus: 'passed'`，缺少图片探针永远不能声明已支持图片。worker 应从真实 runtime 获取这些事实；本库只校验回执、哈希 JSON 观测，并拒绝生成后被修改的 composition，不认证回执的传输通道。
+
+`provenance.kind` 为 `sdk-global-composition`，`namedPresetMounted` 恒为 false：共享日常/重活策略不代表存在 named-preset SDK RPC。GUI 与委派必须分别授权。消费方另外增加权限或 provider overlay 后，仍需在自己的总摘要中绑定完整最终配置。executor 图片探针与 provider 向模型传图是不同的验证。
+
+## 许可
+
+MIT。

package/node_modules/dsh-preset-generator/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "dsh-preset-generator",
+  "version": "0.4.0",
+  "description": "Materialize DeepSeek Harness agent presets from the base preset shipped inside the application.",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/composition.mjs",
+    "./composition": "./src/composition.mjs",
+    "./policy": "./src/policy.mjs",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "bin": {
+    "dsh-preset-generator": "./src/gen-presets.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "docs/README.zh.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "presets": "node src/gen-presets.mjs",
+    "test": "node --test \"tests/*.spec.mjs\""
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "homepage": "https://github.com/ckanner/dsh-preset-generator#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ckanner/dsh-preset-generator.git"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "cordis",
+    "presets",
+    "configuration"
+  ]
+}

package/node_modules/dsh-preset-generator/src/composition.mjs

@@ -0,0 +1,150 @@
+/** Pure SDK composition and observation checks; importing this module performs no I/O. */
+import { createHash } from 'node:crypto'
+import { presetPolicy } from './policy.mjs'
+
+export { PRESETS, presetPolicy } from './policy.mjs'
+export const COMPOSITION_PROTOCOL = 1
+const CONTRACTS = new Set(['deferred-context-v1', 'inspect-image-v1'])
+const record = value => typeof value === 'object' && value !== null && !Array.isArray(value)
+
+function canonical(value) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return value
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (Array.isArray(value)) return value.map(canonical)
+  if (!record(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new TypeError('Composition inputs must contain only JSON values')
+  }
+  return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]))
+}
+
+/** Stable content identity, independent of object property insertion order. */
+export function compositionDigest(value) {
+  return createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex')
+}
+
+function identityOf(composition) {
+  return { version: composition.version, runtimeProfile: composition.runtimeProfile,
+    presetPolicy: composition.presetPolicy, overlay: composition.overlay,
+    provenance: composition.provenance, requirements: composition.requirements }
+}
+
+/**
+ * Inspect caller-supplied, actually read bundle files. This is static provenance,
+ * never proof that an executor ran or that a model received an image.
+ * Versions alone deliberately cannot select the output protocol.
+ */
+export function inspectPtcBundle({ packageJson, files, sourceRevision } = {}) {
+  if (!record(packageJson) || packageJson.name !== '@deepseek-ai/dsh-tool-executor-ptc'
+    || typeof packageJson.version !== 'string' || !packageJson.version) {
+    throw new TypeError('Expected the actual dsh-tool-executor-ptc package manifest')
+  }
+  if (!record(files) || !Object.keys(files).length || Object.entries(files).some(([name, value]) =>
+    !name || name.startsWith('/') || name.split('/').includes('..') || typeof value !== 'string')) {
+    throw new TypeError('Supply nonempty relative bundle filenames and their exact text')
+  }
+  if (sourceRevision !== undefined && (typeof sourceRevision !== 'string' || !sourceRevision)) {
+    throw new TypeError('sourceRevision must be a nonempty source identity')
+  }
+  const exports = record(packageJson.exports) ? structuredClone(packageJson.exports) : {}
+  const joined = Object.values(files).join('\n')
+  const inspectImage = /\binspect\b/.test(joined) && /\bPtcImage\b|\bImage\b/.test(joined)
+  const deferred = /deferredContext|deferred context/i.test(joined)
+  const clues = {
+    privateProgramExport: Object.hasOwn(exports, './run-code'),
+    inspectImage: inspectImage,
+    deferredContext: deferred,
+  }
+  return {
+    version: COMPOSITION_PROTOCOL, kind: 'static-bundle',
+    package: packageJson.name, packageVersion: packageJson.version,
+    bundleDigest: compositionDigest({ packageJson, files }),
+    files: Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b))
+      .map(([name, content]) => [name, createHash('sha256').update(content).digest('hex')])),
+    exports, clues,
+    // Clues are descriptive: an unknown or misleading README cannot certify behavior.
+    outputContract: 'unknown',
+    ...(sourceRevision === undefined ? {} : { sourceRevision }),
+  }
+}
+
+/**
+ * Produce an SDK-only patch. baseRows, when supplied, are the effective rows
+ * obtained through the host loader, not raw nested insert directives. Cordis
+ * replaces config values, so preserve unrelated fs/executor config explicitly.
+ * This does not mount a named Agent Preset, enable children, or grant GUI access.
+ */
+export function createSdkPtcComposition({ runtimeProfile = 'sdk', preset = 'heavy', baseRows = [], ptcEvidence } = {}) {
+  if (typeof runtimeProfile !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(runtimeProfile)
+    || runtimeProfile === 'desktop') throw new TypeError('A non-desktop SDK runtime profile is required')
+  const policy = presetPolicy(preset)
+  if (!Array.isArray(baseRows)) throw new TypeError('baseRows must be effective plugin rows')
+  const rows = new Map()
+  for (const row of baseRows) {
+    canonical(row)
+    if (!record(row) || typeof row.id !== 'string' || !row.id || rows.has(row.id)
+      || Object.hasOwn(row, 'insert')) throw new TypeError('baseRows require unique plugin ids, not patch directives')
+    rows.set(row.id, row)
+  }
+  if (ptcEvidence !== undefined && (!record(ptcEvidence) || ptcEvidence.version !== COMPOSITION_PROTOCOL
+    || ptcEvidence.kind !== 'static-bundle' || !/^[a-f0-9]{64}$/.test(ptcEvidence.bundleDigest))) {
+    throw new TypeError('ptcEvidence must be an inspectPtcBundle result')
+  }
+  const configFor = id => {
+    const config = rows.get(id)?.config
+    if (config !== undefined && !record(config)) throw new TypeError(`${id}.config must be an object`)
+    return structuredClone(config ?? {})
+  }
+  const overlay = [
+    ...(rows.has('tool-presentation') ? [{ id: 'tool-presentation', disabled: true }] : []),
+    { id: 'tool-executor-native', disabled: true },
+    { id: 'tool-executor-ptc', disabled: false, ...(rows.has('tool-executor-ptc') ? { config: configFor('tool-executor-ptc') } : {}) },
+    { id: 'tool-fs', config: { ...configFor('tool-fs'), applyPatch: false } },
+  ]
+  const composition = {
+    version: COMPOSITION_PROTOCOL, runtimeProfile, presetPolicy: policy.id,
+    overlay,
+    provenance: {
+      kind: 'sdk-global-composition', baseDigest: compositionDigest(baseRows),
+      bundleDigest: ptcEvidence?.bundleDigest ?? null,
+      staticEvidence: ptcEvidence === undefined ? null : structuredClone(ptcEvidence),
+      namedPresetMounted: false,
+    },
+    requirements: {
+      executor: 'ptc', tools: ['run_code'], outputContract: 'observed-runtime',
+      guiGranted: false, delegationGranted: false,
+    },
+  }
+  return { ...composition, digest: compositionDigest(identityOf(composition)) }
+}
+
+/**
+ * Validate facts supplied by the owning worker after its real runtime probe.
+ * No subprocess, model, tool or GUI action is performed here. This validator is
+ * not an attestation transport: its caller must authenticate/correlate the probe.
+ */
+export function validateSdkPtcAdmission(composition, observed, { requireImages = false } = {}) {
+  const failures = []
+  if (!record(composition) || composition.version !== COMPOSITION_PROTOCOL
+    || !/^[a-f0-9]{64}$/.test(composition.digest ?? '')) throw new TypeError('Invalid composition')
+  if (compositionDigest(identityOf(composition)) !== composition.digest) throw new TypeError('Composition changed after generation')
+  if (!record(observed)) observed = {}
+  if (observed.compositionDigest !== composition.digest) failures.push('composition-digest-mismatch')
+  if (observed.runtimeProfile !== composition.runtimeProfile) failures.push('runtime-profile-mismatch')
+  if (observed.executor !== 'ptc' || !Array.isArray(observed.activeExecutors)
+    || observed.activeExecutors.length !== 1 || observed.activeExecutors[0] !== 'ptc') failures.push('executor-not-exclusive-ptc')
+  if (!Array.isArray(observed.tools) || !observed.tools.includes('run_code')) failures.push('run-code-not-registered')
+  if (!CONTRACTS.has(observed.outputContract)) failures.push('output-contract-unverified')
+  if (observed.probeStatus !== 'passed') failures.push('runtime-probe-not-passed')
+  if (composition.provenance.bundleDigest !== null && observed.bundleDigest !== composition.provenance.bundleDigest) {
+    failures.push('bundle-digest-mismatch')
+  }
+  if (requireImages && observed.imageProbeStatus !== 'passed') failures.push('image-contract-unverified')
+  return {
+    version: COMPOSITION_PROTOCOL, eligible: failures.length === 0, failures,
+    compositionDigest: composition.digest,
+    observedDigest: compositionDigest(observed),
+    // Absent optional image evidence never turns into a positive capability.
+    imagesVerified: failures.length === 0 && observed.imageProbeStatus === 'passed',
+    namedPresetMounted: false,
+  }
+}