@ckanner/flywheel 0.32.1 → 0.33.0

package/CHANGELOG.md

@@ -5,7 +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.
 
-## Unreleased
+## 0.33.0 — One complete npm distribution
+
+- Consolidate the CLI, DSH host/client, workers, embedded skills and four native
+  engines into one `@ckanner/flywheel` npm tarball. Resolve and verify bundled
+  native files locally; do not download or borrow platform packages at runtime.
+- Migrate the old desktop package through the official DSH CLI, verifying the
+  replacement before removal and retaining explicit rollback/cancellation state.
+  Keep user configuration, modified skills and task histories intact.
+- Publish one immutable candidate through OIDC, test its registry installation,
+  then promote its single latest tag. Historical split packages remain unchanged.
 
 ## 0.32.1 — DSH compatible-series upgrades
 

package/README.md

@@ -32,6 +32,13 @@ retries, budgets, workspaces, and delivery. Use it from the DeepSeek Harness
 - **Makes failures visible.** Unknown execution, usage, or cleanup stays
   unknown. The engine preserves work and stops when it cannot safely proceed.
 
+From 0.33, `@ckanner/flywheel` is one complete package: CLI, DSH view/workers,
+embedded skills and four platform engines. No separate platform package or first-run
+engine download is needed. When upgrading from 0.32.x, quit DSH before running the
+installer; it replaces the old desktop package registration and preserves your
+configuration and histories. Reload DSH after setup. Existing old npm versions
+remain available for historical installations.
+
 ## Install
 
 For the desktop path, install Node.js **22.18.0 or later**, npm, Git, and a

package/README.zh-CN.md

@@ -8,6 +8,11 @@ Flywheel 是面向 coding agent 的确定性 Go 编排器。模型负责规划
 
 [快速开始](docs/zh-CN/getting-started.md) · [文档](docs/README.zh-CN.md) · [参与贡献](docs/zh-CN/contributing.md) · [MIT 许可证](LICENSE)
 
+从 0.33 起，`@ckanner/flywheel` 一个包包含 CLI、DSH 界面／worker、内嵌技能和
+四个平台引擎，不再需要独立平台包或首次运行下载引擎。从 0.32.x 升级前先退出 DSH，
+再运行原来的安装命令；安装器替换旧桌面包登记，保留配置和任务历史，完成后重载 DSH。
+历史 npm 版本继续保留。
+
 ## Flywheel 能做什么
 
 - **根据任务选择流程。** Auto 为满足条件、边界明确的任务选择 Quick，需要规划或更广泛验收时选择 Full。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,42 @@
+# Third-party notices
+
+## DeepSeek Harness UI patterns
+
+Flywheel's plugin-owned Button, Input, and ongoing StateDot treatments are
+adapted from DeepSeek Harness at commit
+`b830ec950faba0a46dda564be3e2d854afed94f1`:
+
+- `packages/client/ui-primitives/src/Button.tsx` and its stylesheet
+- `packages/client/ui-primitives/src/Input.tsx` and its stylesheet
+- `packages/client/ui-primitives/src/StateDot.tsx` and its stylesheet
+
+[Upstream source](https://github.com/deepseek-ai/deepseek-harness/tree/b830ec950faba0a46dda564be3e2d854afed94f1/packages/client/ui-primitives/src)
+
+These adapted portions retain the upstream MIT license below. Flywheel's own
+source is also licensed under MIT; see [LICENSE](LICENSE).
+
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.
+
+## Bundled Codex Pro public package
+
+This distribution bundles `dsh-subagent-codex-pro@0.9.0`, Copyright (c) 2026 ckanner, under the MIT License. Its complete license is retained at `node_modules/dsh-subagent-codex-pro/LICENSE` inside the complete package. Source identity and tarball integrity are recorded in `plugins/dsh/vendor/README.md` and `plugins/dsh/vendor/codex-pro.json` in the source repository. The bundled package is the upstream public machine API implementation, including its compiled supervisor; it contains no native Codex executable or user credentials.

package/bin/runtime.js

@@ -8,26 +8,16 @@ const platforms = { darwin: "darwin", linux: "linux" };
 const architectures = { arm64: "arm64", x64: "amd64" };
 const forwardedSignals = ["SIGTERM", "SIGINT", "SIGHUP"];
 const ownPackage = require("../package.json");
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
 
-function packageEntry(name, entry, expectedVersion, missingMessage) {
-  let installed;
-  let entryPath;
-  try {
-    installed = require(`${name}/package.json`);
-    entryPath = require.resolve(`${name}/${entry}`);
-  } catch {
-    throw new Error(missingMessage);
-  }
-  // npm may legitimately hoist dependencies. Check the resolved package's
-  // identity, rather than assuming a particular machine's node_modules path.
-  // A partial installation must not pick up an incompatible parent package.
-  if (installed.name !== name) {
-    throw new Error(`package identity mismatch for ${name}: found ${installed.name}; reinstall @ckanner/flywheel`);
-  }
-  if (typeof expectedVersion !== "string" || installed.version !== expectedVersion) {
-    throw new Error(`version mismatch for ${name}: expected ${expectedVersion}, found ${installed.version}; reinstall @ckanner/flywheel`);
-  }
-  return entryPath;
+function packageFile(relative) {
+  if (ownPackage.name !== '@ckanner/flywheel') throw new Error('Flywheel package identity mismatch');
+  const filename = path.resolve(__dirname, '..', relative);
+  const stat = fs.lstatSync(filename, { throwIfNoEntry: false });
+  if (!stat?.isFile() || stat.isSymbolicLink()) throw new Error(`Bundled ${relative} is missing or invalid; reinstall @ckanner/flywheel`);
+  return filename;
 }
 
 function loadNativePath() {
@@ -36,27 +26,31 @@ function loadNativePath() {
   if (!platform || !arch) {
     throw new Error(`unsupported platform ${process.platform}/${process.arch} (supported: darwin/linux × amd64/arm64)`);
   }
-  const name = `@ckanner/flywheel-${platform}-${arch}`;
-  return packageEntry(name, "flywheel", ownPackage.optionalDependencies?.[name],
-    `platform package ${name} is missing; reinstall @ckanner/flywheel with optional dependencies enabled`);
+  const key = `${platform}-${arch}`;
+  const manifest = JSON.parse(fs.readFileSync(packageFile('native/manifest.json'), 'utf8'));
+  if (manifest.protocol !== 1 || manifest.version !== ownPackage.version) {
+    throw new Error('Bundled engine version mismatch; reinstall @ckanner/flywheel');
+  }
+  const entry = manifest.platforms?.[key];
+  const filename = packageFile(`native/${key}/flywheel`);
+  const bytes = fs.readFileSync(filename);
+  if (!entry || entry.bytes !== bytes.length || !/^[a-f0-9]{64}$/.test(entry.sha256 ?? '') ||
+      crypto.createHash('sha256').update(bytes).digest('hex') !== entry.sha256) {
+    throw new Error(`Bundled engine integrity mismatch for ${key}; reinstall @ckanner/flywheel`);
+  }
+  return filename;
 }
 
 function loadWorkerPath() {
-  const name = "@ckanner/dsh-plugin-flywheel";
-  return packageEntry(name, "worker", ownPackage.dependencies?.[name],
-    "the matching @ckanner/dsh-plugin-flywheel worker is missing; reinstall @ckanner/flywheel");
+  return packageFile('dist/worker.mjs');
 }
 
 function loadCodexProWorkerPath() {
-  const name = "@ckanner/dsh-plugin-flywheel";
-  return packageEntry(name, "codex-pro-worker", ownPackage.dependencies?.[name],
-    "the matching @ckanner/dsh-plugin-flywheel Codex Pro worker is missing; reinstall @ckanner/flywheel");
+  return packageFile('dist/codex-pro-worker.mjs');
 }
 
 function loadClaudeCodeProWorkerPath() {
-  const name = "@ckanner/dsh-plugin-flywheel";
-  return packageEntry(name, "claude-code-pro-worker", ownPackage.dependencies?.[name],
-    "the matching @ckanner/dsh-plugin-flywheel Claude Code Pro worker is missing; reinstall @ckanner/flywheel");
+  return packageFile('dist/claude-code-pro-worker.mjs');
 }
 
 function assertSupportedNode(version = process.versions.node) {

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    - id: flywheel
+      name: '@ckanner/flywheel'
+      config:
+        controlTimeoutMs: 60000

package/dist/bridge.mjs

@@ -0,0 +1,421 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validatePrepare, matchWarmStart, writeWarmReceipt } from './prewarm.mjs';
+import { BridgeError, MAX_FRAME_BYTES, normalizedError, readPolicyReceipt, record, SESSION_PROTOCOL, SessionFold, validateStart } from './protocol.mjs';
+
+export function makeOverlay(request, policyPath = fileURLToPath(new URL('./policy.mjs', import.meta.url)), admission = {}, historyRoot) {
+  // Each patch replaces an entire config row. Pin the checked rc.5/rc.1 enforcement
+  // implementations, not the user's mutable permission dropdown defaults.
+  const disable = ['permission', 'tool-plugin-manager', 'tool-working-directory',
+    'tool-subagent', 'tool-subagent-fork', 'tool-subagent-control', 'tool-subagent-list-agents',
+    'subagent-spawn-in-process', 'subagent-fork-in-process', 'tool-workflow',
+    'tool-goal', 'goal-round-driver', 'schedule', 'tool-schedule',
+    'session-title-llm', 'tool-web', 'compaction-basic', 'command-compact', 'hmr'];
+  return [
+    ...disable.map(id => ({ id, disabled: true })),
+    ...(historyRoot ? [{ id: 'session-persistence-jsonl', config: { root: historyRoot } }] : []),
+    { id: 'sandbox', name: '@deepseek-ai/dsh-sandbox-local', disabled: false, config: {} },
+    { id: 'sandbox-policy', name: '@deepseek-ai/dsh-sandbox-policy', disabled: false,
+      config: { mode: request.permissionMode, workspaceRoot: request.cwd } },
+    { id: 'bash-sandbox', name: '@deepseek-ai/dsh-bash-sandbox', disabled: false,
+      config: { timeoutMs: 60000, graceMs: 100 } },
+    { id: 'fs-sandbox', name: '@deepseek-ai/dsh-fs-sandbox', disabled: false, config: {} },
+    { id: 'approval', name: '@deepseek-ai/dsh-user-approval', disabled: false, config: { policy: 'never' } },
+    { id: 'sdk-jsonrpc-server', config: { maxTokensAsSuccess: false } },
+    { insert: [{ id: 'flywheel-worker-policy', name: policyPath,
+      config: { permissionMode: request.permissionMode, cwd: request.cwd,
+        ...(request.workspaceCwd ? { workspaceCwd: request.workspaceCwd } : {}),
+        ...(!request.sessionId && request.sessionTitle ? { sessionTitle: request.sessionTitle } : {}), ...admission } }] },
+  ];
+}
+
+async function bounded(promise, ms) {
+  let timer;
+  try {
+    return await Promise.race([promise, new Promise(resolve => { timer = setTimeout(resolve, ms); })]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function abortable(promise, signal) {
+  signal.throwIfAborted();
+  let listener;
+  try {
+    return await Promise.race([promise, new Promise((_, reject) => {
+      listener = () => reject(signal.reason);
+      signal.addEventListener('abort', listener, { once: true });
+    })]);
+  } finally {
+    signal.removeEventListener('abort', listener);
+  }
+}
+
+/** A bounded JSON-RPC transport. It does not own a new process group. */
+export class Runtime {
+  constructor(bin, args, options, notify) {
+    this.nextId = 0;
+    this.pending = new Map();
+    this.buffer = Buffer.alloc(0);
+    this.failed = null;
+    this.protocolFailure = null;
+    this.shutdownAcknowledged = false;
+    this.exit = null;
+    this.closed = false;
+    this.child = spawn(bin, args, { ...options, detached: false, stdio: ['pipe', 'pipe', 'pipe'] });
+    this.exited = new Promise(resolve => { this.resolveExit = resolve; });
+    this.child.on('error', error => {
+      this.fail(new BridgeError('TRANSPORT', `cannot start DSH: ${error.message}`));
+      if (this.child.pid === undefined) {
+        this.exit = { code: null, signal: null };
+        this.resolveExit(this.exit);
+      }
+    });
+    this.child.on('exit', (code, signal) => {
+      this.exit = { code, signal };
+    });
+    this.child.on('close', (code, signal) => {
+      this.closed = true;
+      if (this.buffer.length) {
+        this.protocolFailure ??= new BridgeError('TRANSPORT', 'DSH stdout ended in an incomplete frame');
+        this.fail(this.protocolFailure);
+      }
+      this.fail(new BridgeError('TRANSPORT', `DSH transport closed (exit=${code}, signal=${signal ?? 'none'})`));
+      this.resolveExit(this.exit ?? { code, signal });
+    });
+    this.child.stdin.on('error', error => this.fail(new BridgeError('TRANSPORT', `DSH stdin: ${error.message}`)));
+    this.child.stderr.on('data', chunk => {
+      // Logs stay separate from the engine's protocol. No prompt/credential dump.
+      options.stderr?.(chunk);
+    });
+    this.child.stdout.on('data', chunk => {
+      try {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        let newline;
+        while ((newline = this.buffer.indexOf(10)) !== -1) {
+          if (newline > MAX_FRAME_BYTES) throw new BridgeError('TRANSPORT', 'DSH frame exceeds 8 MiB');
+          const line = this.buffer.subarray(0, newline).toString('utf8');
+          this.buffer = this.buffer.subarray(newline + 1);
+          if (line.trim() === '') continue;
+          const message = JSON.parse(line);
+          if (!record(message) || message.jsonrpc !== '2.0') {
+            throw new BridgeError('TRANSPORT', 'DSH stdout is not JSON-RPC 2.0');
+          }
+          if (Object.hasOwn(message, 'id')) {
+            if (message.id === 'flywheel-shutdown') {
+              this.shutdownAcknowledged = !message.error && Object.hasOwn(message, 'result');
+            }
+            const waiting = this.pending.get(message.id);
+            if (!waiting) continue; // Includes the best-effort shutdown acknowledgement.
+            this.pending.delete(message.id);
+            if (message.error) {
+              waiting.reject(new BridgeError('TRANSPORT', `${waiting.method}: ${message.error.message ?? 'JSON-RPC error'}`));
+            } else if (Object.hasOwn(message, 'result')) waiting.resolve(message.result);
+            else waiting.reject(new BridgeError('TRANSPORT', 'DSH response has no result or error'));
+          } else if (typeof message.method === 'string') notify(message.method, message.params);
+          else throw new BridgeError('TRANSPORT', 'malformed DSH notification');
+        }
+        if (this.buffer.length > MAX_FRAME_BYTES) throw new BridgeError('TRANSPORT', 'DSH frame exceeds 8 MiB');
+      } catch (error) {
+        this.protocolFailure = error instanceof BridgeError ? error : new BridgeError('TRANSPORT', `invalid DSH frame: ${error.message}`);
+        this.buffer = Buffer.alloc(0);
+        this.fail(this.protocolFailure);
+      }
+    });
+  }
+
+  fail(error) {
+    this.failed ??= error;
+    for (const waiter of this.pending.values()) waiter.reject(this.failed);
+    this.pending.clear();
+  }
+
+  request(method, params) {
+    if (this.failed) return Promise.reject(this.failed);
+    if (this.exit) return Promise.reject(new BridgeError('TRANSPORT', 'DSH already exited'));
+    const id = ++this.nextId;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject, method });
+      this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+    });
+  }
+
+  async close() {
+    // The Go watchdog owns the whole inherited process group. We request the
+    // SDK's child-first drain and bound the leader wait; Go performs the final
+    // group sweep even on normal exit. A child must not detach/setsid.
+    let forced = false;
+    if (!this.exit && !this.child.stdin.destroyed) {
+      this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 'flywheel-shutdown', method: 'shutdown', params: {} }) + '\n');
+      // SDK shutdown includes persistent history flush and plugin disposal.
+      // Keep this bounded below Go's default 5s cancellation grace, while
+      // allowing a normal fsync to complete under concurrent local workloads.
+      await bounded(this.exited, 2000);
+    }
+    if (!this.exit) {
+      forced = true;
+      this.child.stdin.end();
+      this.child.kill('SIGTERM');
+      await bounded(this.exited, 250);
+    }
+    if (!this.exit) {
+      this.child.kill('SIGKILL');
+      await bounded(this.exited, 350);
+    }
+    if (!this.exit) throw new BridgeError('TRANSPORT', 'DSH leader did not exit during bounded shutdown');
+    if (!this.closed && this.child.pid !== undefined) {
+      await bounded(this.exited, 350);
+      if (!this.closed) throw new BridgeError('TRANSPORT', 'DSH exited but its protocol streams did not reach quiescence');
+    }
+    return { ...this.exit, forced, graceful: this.shutdownAcknowledged, spawned: this.child.pid !== undefined };
+  }
+}
+
+export async function runWorker(input, { emit, env = process.env, signal, doctor = false, stderr, prewarm } = {}) {
+  let request;
+  let prepared;
+  let formalStarted = false;
+  let warmClosed = false;
+  let runtime;
+  let temp;
+  let sessionId;
+  let fold;
+  let outcome;
+  let failure;
+  let cancelled = false;
+  let settled = true;
+  let readySent = false;
+  let resumeAccepted = false;
+  let resumeUnconfirmed = false;
+  let dispatch = 'not-dispatched';
+  let promptId = '';
+  let waited = false;
+  const beforeReady = [];
+  let deadline;
+  let started = Date.now();
+  const controller = new AbortController();
+  const cancel = () => {
+    cancelled = true;
+    controller.abort(new BridgeError('TRANSPORT', 'worker cancelled'));
+  };
+  const abort = () => runtime?.fail(controller.signal.reason);
+  controller.signal.addEventListener('abort', abort);
+  signal?.addEventListener('abort', cancel, { once: true });
+  const frame = value => emit({ protocol: request?.protocol ?? (input?.protocol === 2 ? 2 : 1), requestId: request?.requestId ?? input?.requestId ?? 'invalid-request', ...value });
+  try {
+    const budget = Number.isSafeInteger(input?.timeoutMs) && input.timeoutMs > 0 && input.timeoutMs <= 86400000
+      ? input.timeoutMs : 30 * 60 * 1000;
+    deadline = setTimeout(() => controller.abort(new BridgeError('TIMEOUT', 'DSH worker lifecycle deadline exceeded')), budget);
+    if (signal?.aborted) cancel();
+    // Validate owned cleanup metadata even if an early close cancelled startup.
+    // This never creates a Session and lets EOF/close publish no-dispatch proof.
+    request = prewarm ? await validatePrepare(input) : await abortable(validateStart(input), controller.signal);
+    if (prewarm) {
+      prepared = request;
+      clearTimeout(deadline);
+      deadline = setTimeout(() => controller.abort(new BridgeError('TIMEOUT', 'SDK prewarm expired before dispatch')), request.ttlMs);
+    }
+    if (doctor && request.protocol === 2) throw new BridgeError('INVALID_REQUEST', 'doctor does not create or resume persistent histories');
+    controller.signal.throwIfAborted();
+    const bin = env.FLYWHEEL_DSH_BIN || 'dsh';
+    if (bin.includes('\0') || bin.startsWith('-')) throw new BridgeError('INVALID_REQUEST', 'invalid FLYWHEEL_DSH_BIN');
+    const profile = env.FLYWHEEL_DSH_PROFILE || 'sdk';
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(profile) || profile === 'desktop') {
+      throw new BridgeError('INVALID_REQUEST', 'FLYWHEEL_DSH_PROFILE must name an SDK profile, not desktop');
+    }
+    temp = await realpath(await mkdtemp(join(tmpdir(), 'flywheel-dsh-')));
+    const patch = join(temp, 'worker.patch.json');
+    sessionId = prepared ? undefined : request.sessionId ?? `flywheel-${randomUUID()}`;
+    const admission = { receiptPath: join(temp, 'policy.json'), requestId: prepared ? prepared.warmId : request.requestId,
+      ...(prepared ? { deferredAdmissionPath: join(temp, 'admission.json') } : { sessionId }), nonce: randomUUID() };
+    await writeFile(patch, JSON.stringify(makeOverlay(request, undefined, admission, doctor ? join(temp, 'probe-history') : undefined)), { mode: 0o600 });
+    controller.signal.throwIfAborted();
+    if (!prepared) fold = new SessionFold(sessionId, { strict: request.protocol === 2 });
+    runtime = new Runtime(bin, ['--profile', profile, '--patch', patch], {
+      cwd: request.cwd,
+      env: { ...env, DSH_PERMISSION_MODE: request.permissionMode,
+        DSH_MAX_TOKENS_AS_SUCCESS: 'false', DSH_TELEMETRY_DISABLED: '1', FLYWHEEL_DSH_NATIVE_WORKER: '1' },
+      stderr,
+    }, (method, params) => {
+      if (prepared && !formalStarted && method === 'session.event') {
+        throw new BridgeError('TRANSPORT', 'SDK emitted a Session event before formal prewarm dispatch');
+      }
+      if (method === 'session.event' && fold.accept(params)) {
+        const eventFrame = { type: 'event', sessionId, event: params.event };
+        if (readySent) frame(eventFrame);
+        else {
+          beforeReady.push(eventFrame);
+          if (beforeReady.length > 256) throw new BridgeError('TRANSPORT', 'excessive SDK events before readiness');
+        }
+      }
+      if (method === 'subagent.started' && params?.parentSessionId === sessionId) {
+        throw new BridgeError('INVALID_REQUEST', 'DSH child delegation is disabled: the Go engine owns workers');
+      }
+    });
+    if (controller.signal.aborted) runtime.fail(controller.signal.reason);
+    const initialized = await runtime.request('initialize', {
+      cwd: request.workspaceCwd ?? request.cwd, provider: request.provider, model: request.model,
+      ...(request.reasoningEffort === undefined ? {} : { reasoningEffort: request.reasoningEffort }),
+      ...(request.maxTokens === undefined ? {} : { maxTokens: request.maxTokens }),
+    });
+    if (initialized?.serverInfo?.name !== 'deepseek-harness-sdk-runtime') {
+      throw new BridgeError('TRANSPORT', 'unexpected SDK runtime identity');
+    }
+    if (prepared) {
+      prewarm.ready();
+      emit({ protocol: 1, type: 'warm-ready', warmId: prepared.warmId, binding: prepared.binding,
+        level: 'sdk-initialized', dispatched: false });
+      const next = await abortable(prewarm.dispatch, controller.signal);
+      if (next === null) { warmClosed = true; throw new BridgeError('TRANSPORT', 'unused prewarm closed'); }
+      // Once a full request arrives its lifecycle belongs to the already durable
+      // invocation, even if validation fails before any model input is sent.
+      formalStarted = true;
+      request = next;
+      // Receiving the owned start retires the prepare deadline before filesystem
+      // validation yields. The formal deadline covers that validation as well.
+      started = Date.now();
+      clearTimeout(deadline);
+      const formalBudget = Number.isSafeInteger(next?.timeoutMs) && next.timeoutMs > 0 && next.timeoutMs <= 86400000
+        ? next.timeoutMs : 30 * 60 * 1000;
+      deadline = setTimeout(() => controller.abort(new BridgeError('TIMEOUT', 'DSH worker lifecycle deadline exceeded')), formalBudget);
+      request = await abortable(validateStart(next), controller.signal);
+      matchWarmStart(prepared, request);
+      sessionId = request.sessionId ?? `flywheel-${randomUUID()}`;
+      fold = new SessionFold(sessionId, { strict: request.protocol === 2 });
+      await writeFile(admission.deferredAdmissionPath, JSON.stringify({ requestId: admission.requestId,
+        nonce: admission.nonce, sessionId, ...(!request.sessionId && request.sessionTitle ? { sessionTitle: request.sessionTitle } : {}) }),
+      { mode: 0o600, flag: 'wx' });
+    }
+    if (request.sessionId !== undefined) {
+      // Public SDK resume restores exactly this identity, without a new input
+      // and without a replacement on failure. A generic RPC error cannot tell
+      // missing history from another live owner; never silently cold-start it.
+      resumeUnconfirmed = true;
+      const restored = await runtime.request('session/resume', { sessionId });
+      if (!record(restored) || Object.keys(restored).length !== 0) {
+        throw new BridgeError('TRANSPORT', 'SDK resume did not confirm restoration');
+      }
+      resumeAccepted = true;
+      resumeUnconfirmed = false;
+    }
+    // This creates the fresh Session and its permission facts without an LLM turn.
+    let working = await runtime.request('session/working-directory/get', { sessionId });
+    if (request.workspaceCwd !== undefined && working?.cwd !== request.cwd) {
+      working = await runtime.request('session/working-directory/set', { sessionId, path: request.cwd });
+    }
+    if (working?.cwd !== request.cwd) throw new BridgeError('INVALID_REQUEST', 'DSH effective cwd differs from the requested workspace');
+    fold.policy = await abortable(readPolicyReceipt(admission.receiptPath,
+      { requestId: admission.requestId, sessionId, nonce: admission.nonce }), controller.signal);
+    if (request.workspaceCwd !== undefined && fold.policy.workspaceCwd !== request.workspaceCwd) {
+      throw new BridgeError('INVALID_REQUEST', 'DSH session project workspace differs from the requested project');
+    }
+    fold.verifiedPolicy(request);
+    frame({ type: 'ready', sessionId, cwd: request.cwd, ...(request.workspaceCwd ? { workspaceCwd: request.workspaceCwd } : {}), provider: request.provider, model: request.model,
+      ...(request.reasoningEffort === undefined ? {} : { reasoningEffort: request.reasoningEffort }),
+      permissionMode: request.permissionMode, approvalPolicy: 'never',
+      policy: { protocol: fold.policy.protocol, cwd: fold.policy.cwd, permissionMode: fold.policy.permissionMode,
+        approvalPolicy: fold.policy.approvalPolicy, confinedShell: fold.policy.confinedShell,
+        ...(fold.policy.enforcement === undefined ? {} : { enforcement: fold.policy.enforcement }) },
+      ...(request.protocol === 2 ? { persistent: true, resumed: resumeAccepted } : {}) });
+    readySent = true;
+    // v2 publishes only this invocation's events. Restoration/configuration
+    // records are reflected in the checked ready receipt, never as new output.
+    if (request.protocol === 1) for (const eventFrame of beforeReady) frame(eventFrame);
+    beforeReady.length = 0;
+    if (doctor) {
+      outcome = { text: 'SDK route, cwd and permission handshake verified; no model prompt sent.', usage: null };
+    } else {
+      // The next prompt is the only invocation owned by this worker. Reset any
+      // restoration facts before dispatch; historical usage must never be added.
+      fold.beginCall();
+      dispatch = 'unknown';
+      const receipt = await runtime.request('session/prompt', {
+        sessionId, contentBlocks: [{ type: 'text', text: request.prompt }],
+      });
+      if (typeof receipt?.messageId !== 'string' || receipt.messageId === '') {
+        throw new BridgeError('TRANSPORT', 'SDK prompt returned no messageId');
+      }
+      promptId = receipt.messageId;
+      dispatch = 'dispatched';
+      const completed = await runtime.request('session/wait', { sessionId });
+      if (!record(completed) || Object.keys(completed).length !== 0) {
+        throw new BridgeError('TRANSPORT', 'SDK wait did not confirm a quiescent session');
+      }
+      waited = true;
+      outcome = fold.finish(receipt.messageId);
+    }
+  } catch (error) {
+    if (!warmClosed) failure = normalizedError(error);
+  } finally {
+    if (runtime) {
+      try {
+        const exit = await runtime.close();
+        if (exit.spawned && (exit.forced || exit.code !== 0 || exit.signal || !exit.graceful)) {
+          settled = false;
+          failure ??= { code: 'TRANSPORT', message: 'DSH runtime did not prove graceful shutdown of its managed processes' };
+        }
+        if (runtime.protocolFailure) {
+          // A provider result cannot attest a damaged SDK stream. Keep its
+          // diagnosis as context, while protocol and cleanup facts stay independent.
+          const protocolFailure = normalizedError(runtime.protocolFailure);
+          failure = failure && failure.message !== protocolFailure.message
+            ? { ...protocolFailure, message: `${protocolFailure.message}; preceding failure: ${failure.message}` }
+            : protocolFailure;
+        }
+      } catch (error) {
+        settled = false;
+        failure = normalizedError(error);
+      }
+    }
+    clearTimeout(deadline);
+    if (controller.signal.aborted) failure ??= normalizedError(controller.signal.reason);
+    if (request && Date.now() - started > request.timeoutMs && !cancelled) {
+      failure = { code: 'TIMEOUT', message: 'DSH worker lifecycle deadline exceeded (including cleanup)' };
+    }
+    if (temp) await rm(temp, { recursive: true, force: true }).catch(error => {
+      failure ??= { code: 'TRANSPORT', message: `could not remove worker overlay: ${error.message}` };
+    });
+    signal?.removeEventListener('abort', cancel);
+    controller.signal.removeEventListener('abort', abort);
+    if (prepared && !formalStarted) {
+      const confirmed = settled && !runtime?.protocolFailure;
+      try { await writeWarmReceipt(prepared, confirmed, failure); }
+      catch (error) { settled = false; failure = normalizedError(error); }
+      emit({ protocol: 1, type: 'warm-result', warmId: prepared.warmId, binding: prepared.binding,
+        dispatched: false, cleanupConfirmed: confirmed && settled, status: warmClosed && settled && !failure ? 'closed' : cancelled ? 'cancelled' : 'error',
+        ...(failure ? { error: failure } : {}) });
+    }
+  }
+  if (prepared && !formalStarted) return { status: warmClosed && settled && !failure ? 'closed' : cancelled ? 'cancelled' : 'error', settled };
+  const result = {
+    type: 'result', status: cancelled ? 'cancelled' : failure ? 'error' : 'ok', settled,
+    ...(sessionId ? { sessionId } : {}),
+    text: outcome?.text ?? fold?.text ?? '',
+    usage: outcome?.usage ?? null, costUsd: null,
+    ...(failure ? { error: failure } : {}),
+  };
+  if ((formalStarted ? request.protocol : input?.protocol) === 2) {
+    // Cleanup, result certainty and output validity are independent. A complete
+    // native turn with empty/model-invalid output can still be repaired in its
+    // own context. Disconnects, damaged frames and ambiguous restore failures
+    // never become a confirmed failure merely because the process has exited.
+    const terminalKnown = waited && fold?.receipts.has(promptId) && fold?.terminal && !runtime?.protocolFailure;
+    const terminal = terminalKnown ? fold.terminal.kind === 'completed' ? 'completed'
+      : fold.terminal.kind === 'aborted' ? 'cancelled' : 'failed'
+      : dispatch === 'not-dispatched' && !resumeUnconfirmed ? 'failed' : 'unknown';
+    result.lifecycle = {
+      protocol: SESSION_PROTOCOL, requestId: request?.requestId ?? input.requestId,
+      sessionId: sessionId ?? '', dispatch, outcome: terminal,
+      cleanupConfirmed: settled,
+      resumeCandidate: Boolean(terminal === 'completed' && settled && readySent && !cancelled && !controller.signal.aborted),
+      resumeAccepted, turnId: terminalKnown ? fold.turnId : '',
+      usageStatus: result.usage === null ? 'unknown' : 'complete',
+    };
+  }
+  frame(result);
+  return result;
+}