@ckanner/flywheel 0.33.1 → 0.34.0

package/dist/native.mjs

@@ -0,0 +1,251 @@
+import { createHash } from 'node:crypto';
+import { BridgeError, record, nonempty, SessionFold } from './protocol.mjs';
+
+export function nativeDigest(value) {
+  const canonical = v => Array.isArray(v) ? v.map(canonical) : record(v)
+    ? Object.fromEntries(Object.keys(v).sort().map(k => [k, canonical(v[k])])) : v;
+  return createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex');
+}
+
+export function validateNative(value, harness = 'dsh') {
+  if (value === undefined) return;
+  if (!record(value) || value.version !== 1) throw new BridgeError('INVALID_REQUEST', 'native requires version 1');
+  if (harness !== 'dsh') return; // Public machine adapters own their native vocabularies.
+  const keys = ['version', 'preset', 'agents', 'team', 'workflows', 'web', 'lcu'];
+  if (Object.keys(value).some(k => !keys.includes(k)) || !['heavy', 'daily'].includes(value.preset)) {
+    throw new BridgeError('INVALID_REQUEST', 'DSH native requires a daily/heavy PTC composition');
+  }
+  for (const [name, fields] of Object.entries({ agents: ['maxConcurrent', 'maxDepth'], team: [], workflows: [], lcu: ['config'] })) {
+    const option = value[name];
+    if (option === undefined) continue;
+    if (!record(option) || typeof option.enabled !== 'boolean' || Object.keys(option).some(k => !['enabled', ...fields].includes(k))) {
+      throw new BridgeError('INVALID_REQUEST', `invalid native.${name}`);
+    }
+  }
+  for (const [key, limit] of [['maxConcurrent', 64], ['maxDepth', 16]]) {
+    const limitValue = value.agents?.[key];
+    if (limitValue !== undefined && (!Number.isSafeInteger(limitValue) || limitValue < 1 || limitValue > limit)) {
+      throw new BridgeError('INVALID_REQUEST', `invalid native.agents.${key}`);
+    }
+  }
+  if ((value.team?.enabled || value.workflows?.enabled) && value.agents?.enabled !== true) {
+    throw new BridgeError('INVALID_REQUEST', 'Team and Workflows require enabled native agents');
+  }
+  if (value.web !== undefined && (!record(value.web) || Object.entries(value.web).some(([k, v]) => !['search', 'fetch'].includes(k) || typeof v !== 'boolean'))) {
+    throw new BridgeError('INVALID_REQUEST', 'invalid native.web');
+  }
+  if (value.lcu?.config !== undefined && (!record(value.lcu.config) || Object.entries(value.lcu.config).some(([k, v]) =>
+    ['app', 'command'].includes(k) ? typeof v !== 'string' || !v.trim() || v.includes('\0') :
+      ['chrome', 'audio'].includes(k) ? typeof v !== 'boolean' :
+        ['allowedApps', 'allowedOrigins'].includes(k) ? !Array.isArray(v) || v.some(s => typeof s !== 'string' || !s.trim()) : true))) {
+    throw new BridgeError('INVALID_REQUEST', 'invalid native.lcu.config');
+  }
+}
+
+export function validateManaged(value, requestId) {
+  if (value === undefined) return;
+  if (!record(value) || value.version !== 1 || value.invocationId !== requestId ||
+      Object.keys(value).some(k => !['version', 'runId', 'invocationId', 'role', 'scope', 'candidateId', 'channel', 'taskDir'].includes(k))) {
+    throw new BridgeError('INVALID_REQUEST', 'native admission identity does not match its invocation');
+  }
+  for (const key of ['invocationId', 'role', 'scope', 'channel', 'taskDir']) nonempty(value[key], `managed.${key}`, 4096);
+  if (typeof value.runId !== 'string' || (value.candidateId !== undefined && typeof value.candidateId !== 'string')) {
+    throw new BridgeError('INVALID_REQUEST', 'invalid native run/candidate identity');
+  }
+}
+
+const MAX_NATIVE_EVENTS = 4096;
+const MAX_NATIVE_EVENT_BYTES = 2 * 1024 * 1024;
+const usageKeys = ['input_tokens', 'output_tokens', 'reasoning_tokens', 'cache_read_tokens', 'cache_write_tokens', 'total_tokens'];
+const validUsage = usage => record(usage) && usageKeys.every(key => Number.isSafeInteger(usage[key]) && usage[key] >= 0);
+const identityString = value => typeof value === 'string' && value.length > 0 && value.length <= 4096 && !value.includes('\0');
+
+/** Native child histories contribute usage, never the root's answer or verdict. */
+export class NativeTree {
+  constructor(rootSessionId, request, emit = () => {}) {
+    this.rootSessionId = rootSessionId;
+    this.request = request;
+    this.emit = emit;
+    this.children = new Map();
+    this.activations = new Map();
+    this.runtimeSeen = new Map();
+    this.events = [];
+    this.sequence = 0;
+    this.eventBytes = 0;
+    this.observationError = null;
+  }
+  fail(message) {
+    this.observationError ??= message;
+    throw new BridgeError('TRANSPORT', message);
+  }
+  event(kind, facts) {
+    const event = { version: 1, sequence: this.sequence + 1, kind, ...facts };
+    const bytes = Buffer.byteLength(JSON.stringify(event));
+    if (this.events.length >= MAX_NATIVE_EVENTS || this.eventBytes + bytes > MAX_NATIVE_EVENT_BYTES) {
+      this.fail('Native observation journal exceeded its bounded event budget');
+    }
+    this.sequence += 1;
+    this.eventBytes += bytes;
+    this.events.push(event);
+    this.emit(event);
+  }
+  ownsParent(id) { return id === this.rootSessionId || this.children.has(id); }
+  child(id, parentId, local = true) {
+    if (!this.request.agents?.enabled || !identityString(id) || id === this.rootSessionId || !this.ownsParent(parentId)) {
+      this.fail('Native child dispatch has no admitted parent lineage');
+    }
+    const existing = this.children.get(id);
+    if (existing && (existing.parentId !== parentId || existing.local !== local)) this.fail('Native child changed parent or ownership kind');
+    if (existing) return existing;
+    const child = { id, parentId, kind: 'agent', local, state: 'created', terminal: false,
+      fold: local ? new SessionFold(id, { strict: true }) : null, fingerprints: new Map(), lastEventSequence: -1, currentTurn: -1 };
+    this.children.set(id, child);
+    this.event('child.created', { id, parentId, local, state: 'created' });
+    return child;
+  }
+  notify(method, params) {
+    if (method === 'subagent.started') {
+      if (!record(params)) this.fail('Malformed native child publication');
+      this.child(params.childSessionId, params.parentSessionId);
+      return;
+    }
+    const child = this.children.get(params?.sessionId ?? params?.childSessionId);
+    if (method === 'session.event' && child?.local) {
+      const event = params.event;
+      if (!record(event) || !Number.isSafeInteger(event.seq)) this.fail('Malformed native child event');
+      const digest = nativeDigest(event);
+      if (child.fingerprints.has(event.seq)) {
+        if (child.fingerprints.get(event.seq) !== digest) this.fail('Native child replay changed a committed event');
+        return;
+      }
+      if (event.seq < child.lastEventSequence) this.fail('Native child events arrived out of order');
+      if (child.fold.accept(params)) {
+        child.fingerprints.set(event.seq, digest);
+        child.lastEventSequence = event.seq;
+        const turn = event.data.turn;
+        if (event.type === 'turn/start') {
+          if (!Number.isSafeInteger(turn) || turn < 0 || turn < child.currentTurn) this.fail('Native child turn identity regressed');
+          child.currentTurn = turn;
+          child.terminal = false;
+          child.state = 'active';
+          child.fold.terminal = null;
+        } else if (event.type === 'turn/end') {
+          if (turn < child.currentTurn) this.fail('A late native terminal belongs to an earlier turn');
+          child.currentTurn = turn;
+          child.state = event.data.reason.kind;
+          // A committed turn ending does not establish residency-epoch settlement.
+          // subagent.finished / public subagent/end owns that separate fact.
+        }
+        this.event('child.event', { id: child.id, parentId: child.parentId, state: child.state,
+          eventType: event.type, eventSequence: event.seq, turnId: Number.isSafeInteger(turn) ? String(turn) : child.fold.turnId || null });
+      }
+    }
+    if (method === 'subagent.finished') {
+      if (!child) {
+        if (this.ownsParent(params?.parentSessionId)) this.fail('Native child settled without a published start');
+        return;
+      }
+      if (params.parentSessionId !== child.parentId || !identityString(params.stopReason)) this.fail('Native child terminal changed parent or lacks a stop reason');
+      if (child.terminal && child.state === params.stopReason) return;
+      child.state = params.stopReason;
+      child.terminal = true;
+      this.event('child.finished', { id: child.id, parentId: child.parentId, state: child.state });
+    }
+  }
+  /** Fold the SDK policy's durable public lifecycle observations, idempotently. */
+  observeRuntime(events) {
+    if (!Array.isArray(events) || events.length > MAX_NATIVE_EVENTS) this.fail('Malformed native runtime journal');
+    for (const event of events) {
+      if (!['subagent.started', 'subagent.finished', 'agent.admission-rejected'].includes(event?.type)) continue;
+      if (event.version !== 1 || !Number.isSafeInteger(event.journalSequence) || event.journalSequence < 1 ||
+          event.rootSessionId !== this.rootSessionId) this.fail('Unowned native runtime lifecycle observation');
+      const fingerprint = nativeDigest(event);
+      if (this.runtimeSeen.has(event.journalSequence)) {
+        if (this.runtimeSeen.get(event.journalSequence) !== fingerprint) this.fail('Native runtime journal changed an observed event');
+        continue;
+      }
+      if (this.runtimeSeen.size >= MAX_NATIVE_EVENTS) this.fail('Native runtime journal exceeded its bounded event budget');
+      if (event.type === 'agent.admission-rejected') {
+        const child = this.children.get(event.id);
+        if (!child || event.id === this.rootSessionId) continue;
+        if (!child.local || child.parentId !== event.parentId || event.matched !== false) this.fail('Native child rejection changed its owned identity');
+        const active = [...this.activations.values()].some(value => value.id === child.id && !value.terminal);
+        const proven = event.beforeModelDispatch === true && event.parentLive === true && !active;
+        child.rejectedAdmissions ??= [];
+        child.rejectedAdmissions.push({ journalSequence: event.journalSequence, beforeModelDispatch: proven });
+        // Rejecting a new attempt never resets previous paid turns. Only a
+        // fresh, wholly undispatched child can acquire a proved-zero usage.
+        if (proven && child.fold.assistantCount === 0 && child.fold.terminal === null) {
+          child.state = 'admission-rejected';
+          child.terminal = true;
+          child.admissionRejected = true;
+        } else if (!proven) child.terminal = false;
+        this.runtimeSeen.set(event.journalSequence, fingerprint);
+        this.event('child.admission-rejected', { id: child.id, parentId: child.parentId, beforeModelDispatch: proven });
+        continue;
+      }
+      const info = event.child;
+      if (!record(info) || !identityString(info.runId) || !identityString(info.provider) || typeof info.local !== 'boolean') {
+        this.fail('Malformed native runtime child identity');
+      }
+      const child = this.child(info.id, info.parentSessionId, info.local);
+      let activation = this.activations.get(info.runId);
+      if (activation && (activation.id !== info.id || activation.parentId !== info.parentSessionId ||
+          activation.provider !== info.provider || activation.local !== info.local)) this.fail('Native runtime activation changed identity');
+      if (event.type === 'subagent.started') {
+        if (!activation) {
+          activation = { runId: info.runId, id: info.id, parentId: info.parentSessionId, provider: info.provider,
+            local: info.local, state: 'active', terminal: false };
+          this.activations.set(info.runId, activation);
+          child.admissionRejected = false;
+          // Local wire events may already have reported settlement before this
+          // journal is read. An active epoch still appears in completion().
+          if (!info.local) { child.state = 'active'; child.terminal = false; }
+        }
+      } else {
+        if (!activation || !identityString(info.stopReason)) this.fail('Native runtime terminal has no attributable start');
+        if (activation.terminal && activation.state !== info.stopReason) this.fail('Native runtime terminal outcome changed');
+        activation.state = info.stopReason;
+        activation.terminal = true;
+        child.state = info.stopReason;
+        child.terminal = ![...this.activations.values()].some(value => value.id === child.id && !value.terminal);
+      }
+      this.runtimeSeen.set(event.journalSequence, fingerprint);
+      this.event(event.type, { id: child.id, parentId: child.parentId, runId: info.runId,
+        provider: info.provider, local: info.local, state: activation.state });
+    }
+  }
+  /** Capture this at root completion, before shutdown can cancel pending work. */
+  completion() {
+    const pending = new Set([...this.children.values()].filter(child => !child.terminal).map(child => child.id));
+    for (const activation of this.activations.values()) if (!activation.terminal) pending.add(activation.id);
+    const pendingIds = [...pending].sort();
+    return { confirmed: this.observationError === null && pendingIds.length === 0, pendingIds };
+  }
+  receipt(effective, cleanup) {
+    return { version: 1, requested: this.request, effective,
+      observed: { events: this.events, truncated: false, complete: this.observationError === null,
+        ...(this.observationError ? { error: this.observationError } : {}) },
+      children: [...this.children.values()].map(({ fold, fingerprints, lastEventSequence, currentTurn, ...child }) => ({ ...child,
+        turnId: fold?.turnId || null, usage: this.knownUsage(child, fold) ? { ...fold.usage } : null })),
+      activations: [...this.activations.values()].map(value => ({ ...value })), cleanup,
+      usage: { strategy: 'exclusive-committed-session-events', status: this.usageComplete() ? 'complete' : 'partial' } };
+  }
+  knownUsage(child, fold = child.fold) {
+    return child.local && child.terminal && fold?.usageComplete && validUsage(fold.usage) &&
+      (fold.assistantCount > 0 && fold.terminal !== null || child.admissionRejected === true && fold.assistantCount === 0);
+  }
+  usageComplete() {
+    return this.observationError === null && this.completion().confirmed && [...this.children.values()].every(child => this.knownUsage(child));
+  }
+  addUsage(rootUsage) {
+    if (!validUsage(rootUsage) || !this.usageComplete()) return null;
+    const result = { ...rootUsage };
+    for (const { fold } of this.children.values()) for (const key of usageKeys) {
+      const sum = result[key] + fold.usage[key];
+      if (!Number.isSafeInteger(sum)) return null;
+      result[key] = sum;
+    }
+    return result;
+  }
+}

package/dist/policy.mjs

@@ -3,12 +3,14 @@
 import { link, realpath, stat, unlink, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute } from 'node:path';
 import { readPolicyReceipt, nonempty } from './protocol.mjs';
+import { createNativePolicy } from './native-policy.mjs';
 
 export const inject = ['sandboxPolicy', 'approval', 'shell', 'workingDirectory'];
 
 export async function apply(ctx, config) {
   const { permissionMode, cwd, workspaceCwd, receiptPath, requestId, nonce, deferredAdmissionPath } = config;
   let { sessionTitle, sessionId } = config;
+  let nativePolicy;
   const fullAccess = permissionMode === 'danger-full-access';
   if (!['read-only', 'workspace-write', 'danger-full-access'].includes(permissionMode) || typeof cwd !== 'string' ||
       ctx.shell.sandboxMode === undefined) {
@@ -45,13 +47,18 @@ export async function apply(ctx, config) {
     const session = agent.session;
     if (deferredAdmissionPath !== undefined) {
       const identity = await readPolicyReceipt(deferredAdmissionPath, { requestId, nonce });
-      if (Object.keys(identity).some(key => !['requestId', 'nonce', 'sessionId', 'sessionTitle'].includes(key))) {
+      if (Object.keys(identity).some(key => !['requestId', 'nonce', 'sessionId', 'sessionTitle', 'managed', 'resuming'].includes(key))) {
         throw new Error('Flywheel deferred admission has unsupported fields');
       }
       sessionId = nonempty(identity.sessionId, 'sessionId', 512);
       sessionTitle = identity.sessionTitle === undefined ? undefined : nonempty(identity.sessionTitle, 'sessionTitle', 512);
+      config.managed = identity.managed;
+      config.resuming = identity.resuming;
     }
-    if (String(session.id) !== sessionId) throw new Error('Flywheel policy refuses an unrelated SDK session');
+    config.sessionId = sessionId;
+    nativePolicy ??= await createNativePolicy(ctx, config);
+    const root = String(session.id) === sessionId;
+    if (!root && !nativePolicy?.isChild(agent)) throw new Error('Flywheel policy refuses an unrelated SDK session');
     if (workspaceCwd !== undefined && session.header.cwd !== workspaceCwd) {
       throw new Error('Flywheel refuses to relabel a session from a different project workspace');
     }
@@ -61,17 +68,20 @@ export async function apply(ctx, config) {
       // unsupported split workspace-write requests are rejected at admission.
       await ctx.workingDirectory.set(agent, cwd);
     }
-    if (sessionTitle && ctx.get('sessionTitle')) {
+    if (root && sessionTitle && ctx.get('sessionTitle')) {
       ctx.get('sessionTitle').rename(session, [...sessionTitle].slice(0, 35).join(''));
     }
     // Official events remain readable by a later SDK. An ad-hoc Session event
     // would make rc.1 reject the entire persisted log on resume.
     session.append('sandbox/mode', { mode: permissionMode });
     session.append('approval/policy', { policy: 'never' });
+    const native = await nativePolicy?.admit(agent, root);
+    if (!root) return;
     const policy = ctx.sandboxPolicy.resolve({ session });
     const receipt = {
       protocol: 1,
       requestId, sessionId, nonce,
+      ...(native ? { native } : {}),
       ...(workspaceCwd === undefined ? {} : { workspaceCwd: session.header.cwd }),
       cwd: policy.workspaceRoot,
       permissionMode: policy.mode,

package/dist/prewarm.mjs

@@ -2,6 +2,7 @@
 import { open, realpath, stat, link, unlink, readdir } from 'node:fs/promises';
 import { join, isAbsolute } from 'node:path';
 import { BridgeError, MAX_FRAME_BYTES, directory, nonempty, record } from './protocol.mjs';
+import { validateNative, nativeDigest } from './native.mjs';
 
 export const PREWARM_MS = 60000;
 const MAX_RECEIPT_BYTES = 8192;
@@ -9,7 +10,7 @@ const TRUNCATED_DIAGNOSTIC = ' [truncated]';
 const BINDING_FIELDS = ['cwd', 'workspaceCwd', 'provider', 'model', 'reasoningEffort', 'permissionMode'];
 
 export async function validatePrepare(value) {
-  const keys = new Set(['type', 'protocol', 'warmId', 'binding', 'receiptDirectory', 'ttlMs', ...BINDING_FIELDS]);
+  const keys = new Set(['type', 'protocol', 'warmId', 'binding', 'receiptDirectory', 'ttlMs', 'native', ...BINDING_FIELDS]);
   if (!record(value) || value.type !== 'prepare' || value.protocol !== 1 ||
       Object.keys(value).some(key => !keys.has(key)) || typeof value.warmId !== 'string' || typeof value.binding !== 'string' ||
       !/^[a-zA-Z0-9_-]{8,128}$/.test(value.warmId) ||
@@ -19,6 +20,7 @@ export async function validatePrepare(value) {
   }
   const request = { ...value, cwd: await directory(value.cwd, 'cwd'),
     ...(value.workspaceCwd === undefined ? {} : { workspaceCwd: await directory(value.workspaceCwd, 'workspaceCwd') }) };
+  validateNative(value.native);
   for (const key of ['provider', 'model', 'reasoningEffort']) nonempty(value[key], key);
   if (request.workspaceCwd && request.workspaceCwd !== request.cwd && request.permissionMode === 'workspace-write') {
     throw new BridgeError('INVALID_REQUEST', 'separate execution roots require an explicitly compatible permission mode');
@@ -38,6 +40,7 @@ export function matchWarmStart(prepared, request) {
   if (BINDING_FIELDS.some(key => (prepared[key] ?? '') !== (request[key] ?? ''))) {
     throw new BridgeError('INVALID_REQUEST', 'formal request differs from the initialized SDK binding');
   }
+  if (nativeDigest(prepared.native ?? null) !== nativeDigest(request.native ?? null)) throw new BridgeError('INVALID_REQUEST', 'native composition changed after prewarm initialization');
 }
 
 export async function writeWarmReceipt(prepared, settled, error) {

package/dist/protocol.mjs

@@ -1,6 +1,7 @@
 import { constants } from 'node:fs';
 import { open, realpath, stat } from 'node:fs/promises';
 import { dirname, isAbsolute } from 'node:path';
+import { validateNative, validateManaged } from './native.mjs';
 
 export const PROTOCOL = 1;
 export const SESSION_PROTOCOL = 'dsh-sdk/session-resume/worker-v2';
@@ -55,7 +56,7 @@ export async function validateStart(value) {
     throw new BridgeError('INVALID_REQUEST', 'expected one protocol 1 or 2 start request');
   }
   const allowed = new Set(['type', 'protocol', 'requestId', 'cwd', 'provider', 'model',
-    'reasoningEffort', 'permissionMode', 'prompt', 'maxTokens', 'timeoutMs', 'workspaceCwd', 'sessionTitle']);
+    'reasoningEffort', 'permissionMode', 'prompt', 'maxTokens', 'timeoutMs', 'workspaceCwd', 'sessionTitle', 'native', 'managed']);
   if (value.protocol === 2) {
     allowed.add('sessionId');
     allowed.add('persistent');
@@ -66,6 +67,12 @@ export async function validateStart(value) {
     if (!allowed.has(key)) throw new BridgeError('INVALID_REQUEST', `unsupported start field: ${key}`);
   }
   const requestId = nonempty(value.requestId, 'requestId', 128);
+  validateNative(value.native);
+  validateManaged(value.managed, requestId);
+  if (value.managed !== undefined && value.native === undefined) throw new BridgeError('INVALID_REQUEST', 'managed identity requires native options');
+  if (value.native?.lcu?.enabled && (!value.managed || value.permissionMode !== 'danger-full-access')) {
+    throw new BridgeError('INVALID_REQUEST', 'LCU requires managed identity and explicitly selected full access');
+  }
   const provider = nonempty(value.provider, 'provider');
   const model = nonempty(value.model, 'model');
   const prompt = nonempty(value.prompt, 'prompt', MAX_FRAME_BYTES);

package/dist/worker.mjs

@@ -2,6 +2,7 @@
 import { runWorker } from './bridge.mjs';
 import { prewarmInput } from './prewarm.mjs';
 import { BridgeError, MAX_FRAME_BYTES, normalizedError } from './protocol.mjs';
+import { nativeDoctor } from './native-doctor.mjs';
 
 const controller = new AbortController();
 process.once('SIGTERM', () => controller.abort());
@@ -33,16 +34,22 @@ async function readInput() {
 const emit = value => process.stdout.write(JSON.stringify(value) + '\n');
 let warmInput;
 try {
-  if (process.argv.slice(2).some(arg => !['--doctor', '--prewarm'].includes(arg)) || process.argv.length > 3) {
-    throw new BridgeError('INVALID_REQUEST', 'worker accepts only optional --doctor or --prewarm');
+  if (process.argv.slice(2).some(arg => !['--doctor', '--native-doctor', '--prewarm'].includes(arg)) || process.argv.length > 3) {
+    throw new BridgeError('INVALID_REQUEST', 'worker accepts only optional --doctor, --native-doctor or --prewarm');
+  }
+  if (process.argv.includes('--native-doctor')) {
+    const result = await nativeDoctor();
+    emit(result);
+    process.exitCode = result.available ? 0 : 1;
+  } else {
+    warmInput = process.argv.includes('--prewarm') ? prewarmInput(controller) : undefined;
+    const request = warmInput ? await warmInput.admission : await readInput();
+    const result = await runWorker(request, {
+      emit, signal: controller.signal, doctor: process.argv.includes('--doctor'),
+      stderr: chunk => process.stderr.write(chunk), prewarm: warmInput,
+    });
+    process.exitCode = !result || ['ok', 'closed'].includes(result.status) ? 0 : result.status === 'cancelled' ? 143 : 1;
   }
-  warmInput = process.argv.includes('--prewarm') ? prewarmInput(controller) : undefined;
-  const request = warmInput ? await warmInput.admission : await readInput();
-  const result = await runWorker(request, {
-    emit, signal: controller.signal, doctor: process.argv.includes('--doctor'),
-    stderr: chunk => process.stderr.write(chunk), prewarm: warmInput,
-  });
-  process.exitCode = !result || ['ok', 'closed'].includes(result.status) ? 0 : result.status === 'cancelled' ? 143 : 1;
 } catch (error) {
   emit({ protocol: 1, requestId: 'invalid-request', type: 'result', status: 'error', settled: true,
     text: '', usage: null, costUsd: null, error: normalizedError(error) });

package/docs/README.md

@@ -16,6 +16,7 @@ guides are maintained in English and Simplified Chinese.
 | Use the canvas, stage controls, sessions, and run history | [Workbench](en/flow-console.md) | [流程工作台](zh-CN/flow-console.md) |
 | Resolve configuration, profiles, permissions, and scheduling | [Configuration](en/configuration.md) | [配置参考](zh-CN/configuration.md) |
 | Understand the default models and reasoning settings | [Model policy](en/model-policy.md) | [模型策略](zh-CN/model-policy.md) |
+| Use native Agents, Teams, Swarm, Tower and LCU | [Native capabilities](en/native-capabilities.md) | [原生能力](zh-CN/native-capabilities.md) |
 | Enable the optional Claude machine backend | [Claude Code Pro](en/claude-code-pro.md) | [Claude Code Pro](zh-CN/claude-code-pro.md) |
 | Resume roles and reconcile interrupted calls | [Recovery and context quality](en/session-recovery.md) | [恢复与上下文质量](zh-CN/session-recovery.md) |
 | Compare session policies with fixed tasks and evidence | [Session evaluation](en/session-evaluation.md) | [会话评估](zh-CN/session-evaluation.md) |
@@ -54,6 +55,14 @@ The [P5 implementation plan](plans/2026-11-13-p5-ready-queue-prewarm.md) (Chines
 records optional scheduling and runtime preparation; live performance and any
 default adoption require separate evidence.
 
+The [native harness, PTC and LCU implementation design](plans/2026-11-13-native-harness-capabilities.en.md)
+([中文](plans/2026-11-13-native-harness-capabilities.md)), revised on 2026-11-14,
+describes the six-repository implementation: shared SDK/PTC composition, native
+Agents/Teams/Swarm/Workflows, Tower candidates, GUI leases, media, accounting and
+recovery. Use the [native guide](en/native-capabilities.md) for configuration and
+the [validation record](validation/2026-11-14-native-harness-implementation.md)
+for the tested source and installation boundaries.
+
 | Collection | Contents |
 | --- | --- |
 | [Plans](plans/README.md) | Dated design proposals and implementation decisions |

package/docs/README.zh-CN.md

@@ -14,6 +14,7 @@
 | 使用画布、阶段操作、会话和运行记录 | [流程工作台](zh-CN/flow-console.md) | [Workbench](en/flow-console.md) |
 | 配置优先级、profiles、权限和调度 | [配置参考](zh-CN/configuration.md) | [Configuration](en/configuration.md) |
 | 默认模型与推理等级的依据 | [模型策略](zh-CN/model-policy.md) | [Model policy](en/model-policy.md) |
+| 使用原生 Agent、Team、Swarm、Tower 与 LCU | [原生能力](zh-CN/native-capabilities.md) | [Native capabilities](en/native-capabilities.md) |
 | 接入可选 Claude machine 后端 | [Claude Code Pro](zh-CN/claude-code-pro.md) | [Claude Code Pro](en/claude-code-pro.md) |
 | 角色续接、调用中断与对账 | [恢复与上下文质量](zh-CN/session-recovery.md) | [Recovery and context quality](en/session-recovery.md) |
 | 使用固定任务和证据比较会话策略 | [会话评估](zh-CN/session-evaluation.md) | [Session evaluation](en/session-evaluation.md) |
@@ -38,6 +39,8 @@
 
 [反馈驱动工作流与 JEV 方案](plans/2026-11-12-feedback-driven-workflows.md)（中文，历史提案）系统讨论 Auto／Quick／Full、故障调查、短反馈闭环、模型策略和有界语义决策；当前支持的行为见[调查指南](zh-CN/investigation.md)与 [JEV 指南](zh-CN/jev.md)。[P5 实施计划](plans/2026-11-13-p5-ready-queue-prewarm.md)记录可选调度与运行时准备，真实性能和默认采用策略另需证据。
 
+[原生 Harness、PTC 与 LCU 完整设计](plans/2026-11-13-native-harness-capabilities.md)（[English](plans/2026-11-13-native-harness-capabilities.en.md)）于 2026-11-14 修订为六仓库实现设计，涵盖共享 SDK/PTC 组合、原生 Agent/Team/Swarm/Workflow、Tower 候选、GUI lease、媒体、用量和恢复。配置方法见[原生能力指南](zh-CN/native-capabilities.md)，已测源码和安装边界见[验收记录](validation/2026-11-14-native-harness-implementation.md)。
+
 | 分类 | 内容 |
 | --- | --- |
 | [方案](plans/README.md) | 按日期保存的设计提案与实施决策 |

package/docs/design.md

@@ -32,7 +32,7 @@ Flywheel 把明确需求变为一组有边界、有验收、有失败出口的 c
 
 默认以 DSH Mac 桌面为入口，支持 Kimi、ChatGPT 订阅和 DSH 已登录并充值的 DeepSeek 账号。DeepSeek 只使用 Flash，默认 provider 为 `deepseek-account`；`deepseek-official` API Key 仍是显式可选配置，不自动回退。Kimi 通过原生 CLI 调用，不使用 ACP。GPT 可以在 DSH 原生 agent 中执行，也可以通过 Codex Pro 插件的 machine API 使用完整 Codex harness；这两个后端的工具、权限和会话语义不同。
 
-具名模型 profiles、provider 与账号渠道的独立配置、有效配置查看和无推理安装预检已具备。`codex-pro` harness 直接消费 `dsh-subagent-codex-pro@0.9.0` 公开 machine API，作为默认 hard 路由；原 `codex` CLI driver 仅保留为用户明确选择的兼容路径，不作自动后备。统一准备启动入口、Auto／Quick／Full 和 DSH 会话任务关联减少已明确小任务的重复规划与终验。有界并行按冻结依赖和写入范围调度；桌面控制台提供受管阶段操作、配置编辑、会话接管和明确授权的远端交付。开放式自动模型选型与 DSH 原生 Teams 不属于现有实现；显式允许集合内的有界执行升级见 §13.1。
+具名模型 profiles、provider 与账号渠道的独立配置、有效配置查看和无推理安装预检已具备。`codex-pro` harness 直接消费 `dsh-subagent-codex-pro@0.10.0` 公开 machine API，作为默认 hard 路由；原 `codex` CLI driver 仅保留为用户明确选择的兼容路径，不作自动后备。统一准备启动入口、Auto／Quick／Full 和 DSH 会话任务关联减少已明确小任务的重复规划与终验。有界并行按冻结依赖和写入范围调度；桌面控制台提供受管阶段操作、配置编辑、会话接管和明确授权的远端交付。原生能力通过 native-profiles 接入各 loop，支持 DSH Team、Kimi Agent/Swarm/Tower、Codex agents 与 Claude Workflow；各后端实际边界见 §3.3。开放式自动模型选型仍不属于现有实现；显式允许集合内的执行升级见 §13。
 
 ## 2. 设计不变量
 
@@ -82,7 +82,7 @@ DSH 使用原仓库作为 Session header 的 cwd，再通过公开工作目录
 
 ### 3.2 Worker 与进程所有权
 
-DSH worker 是独立进程，通过正式 SDK 的 stdio JSON-RPC 驱动原生会话。每次调用创建一个 SDK 进程，worker 和 SDK 继承 Go 管理的进程组，不另行 detached。SDK 自己创建的托管命令还须经 SDK 关闭协议排空；正常关闭保留 2 秒用于历史落盘与插件释放，再进行有界 TERM/KILL 收尾。无法证明正常关闭就不能报告成功。不依赖 Teams、OAR、Forge，也不把 external subagent 名称当成原生 LLM provider。
+DSH worker 是独立进程，通过正式 SDK 的 stdio JSON-RPC 驱动原生会话。每次调用创建一个 SDK 进程，worker 和 SDK 继承 Go 管理的进程组，不另行 detached。SDK 自己创建的托管命令还须经 SDK 关闭协议排空；普通路径关闭保留 2 秒用于历史落盘与插件释放；启用 native 时为 15 秒，LCU 路径为 135 秒，Go 外层分别至少 20／145 秒。之后才进行有界 TERM/KILL 收尾。无法证明正常关闭就不能报告成功。可显式启用 SDK 内的 Team，但不能把 external subagent 名称当成原生 LLM provider。
 
 可选 `scheduler.prewarm:true` 提前启动一次性 DSH Review 运行环境：在串行 packet 的 Execute 已确认收尾后，与 L1／适用 Quick 检查重叠执行 SDK 启动与 `initialize`。准备阶段不创建或恢复 Session，不发送 prompt，不使用占位推理。新协议以 `--prewarm` 明确选择，与原 v1／v2 的一次性请求保持兼容；最多一个待用 SDK，60 秒 TTL，stdin EOF 始终触发有界清理。正式 Review 仍先通过全部适用验证、预算和角色调用准入，持久化实际 invocation intent 后才能消费同一运行环境。
 
@@ -95,6 +95,18 @@ IPC lifeline，再由 guardian 派发 Claude CLI 并拥有其进程组；worker
 收束原生工作。正常结果等待 native 与 guardian 退出。清理与任务结果独立：外层被
 强杀导致回执丢失时，不能因为 guardian 清理了进程就推断任务成功或安全重放。
 
+### 3.3 原生能力、任务树和独立任务
+
+`native-profile` 在模型／阶段／路由绑定中引用版本化 `native-profiles`；能力跟随实际 harness，不改变 provider、账号或模型的既有绑定。DSH 复用 `dsh-preset-generator@0.4.0` 的 SDK global PTC overlay，明确不是挂载 named Agent Preset。首个 prompt 前实际执行 canonical JSON、handle、多图、TypeScript 和输出协议 probe；同版本号不代替行为验证。各后代在公开 Agent 生命周期中按真实 registry 和 lineage 准入。
+
+每次 invocation 记录 requested／effective／observed、owned children、usage、completion 和 cleanup；默认值写入 effective，不改写原始 requested。native-event 只是观察，不充当 Pro durable lifecycle ACK。completion 在 root 结束、开始 cleanup 之前冻结；取消残留 child 不能倒推原任务已完成。SDK policy 的 bounded journal 按 requestId／nonce／rootSessionId／连续序号核对，最终 complete/events/bytes 不一致时保持失败与未知清理。
+
+LCU 通过公开 managed API 挂载，root 与真实后代共享一个跨进程 `local-desktop` lease并顺序操作 GUI；每次操作核对 caller 与 epoch，未知 owner 不被自动接管。PTC tool 名为 `lcu_cua`，程序对象仍是 `cua`。取消必须区分 MCP 请求、turn cleanup 和 native 物理退出。图片从实际 AttachmentStore 读取并归档至 task 的 reports/native/invocation；capture 与 archive hash 分开，模型送达未验证时如实标注。
+
+Kimi native 路径调用独立 worker，拥有 `kimi web` 的本地 server、registry、PID 与订阅，实际核对模型／effort／mode／permission后再派发。普通 CLI 路径保留。Agent/Swarm 使用角色账本；Tower 创建独立 `.git` 候选，只有 Execute 在完成和清理确认、source HEAD／bytes／modes／外部契约复核及 patch check 后导回。该副本不构成 OS 文件系统沙箱，Server 仅接受显式 full access；未知调用不重放。
+
+Codex 0.10.0 使用 config/read核对原生 agents controls与当前child turn；Claude 0.5.0支持Agent定义／Workflow／Advisor，并区分init工具事实与无法验证的hard cap。Codex原生review不消费角色prompt，因此通过 `flywheel native codex-review`独立入口；Claude `claude-review`、`claude-team`、`claude-recover`和`claude-control`保留远端job／tmux所有权与恢复回执。它们不写Flywheel state、不自动产生Review或Judge verdict，远端本地超时不证明云任务已结束。使用与协议见[原生能力指南](zh-CN/native-capabilities.md)及[完整设计](plans/2026-11-13-native-harness-capabilities.md)。
+
 ## 4. 执行闭环
 
 ### 4.0 Auto、Quick 与 Full
@@ -133,8 +145,10 @@ Plan 不得直接修改实现、任务目录外的冻结 oracle，或 `flywheel.
 规划检查点提交前后核对候选内容，并检查新 HEAD 的路径范围与已提交契约。Git hook 修改已加载契约、仅修改 index、或混入实现变更时拒绝继续同步；保留工作区，要求重新加载并验证。
 
 scoped 下 Plan 按任务／里程碑保存自己的历史，显式 `resident-session:false` 继续关闭
-Plan 复用；省略该字段不等于关闭。fresh 保留既有 Kimi Plan resident 选项，但不把它
-记录为通用作用域可复用句柄。实际绑定、工作目录、权限和运行配置不匹配时不续用旧
+Plan 复用；省略该字段不等于关闭。fresh 仅在未配置 `native-profile` 的旧 Kimi CLI
+路径保留旧 Plan resident 行为，但不把它记录为通用作用域可复用句柄。原生 Agent/Swarm
+将全局 `fresh` 下的显式 `resident-session:true` 意图映射为 scoped 角色账本，显式 `sessions.roles.plan:"fresh"`
+仍优先关闭复用；不导入旧 CLI Session，Tower 始终 fresh。实际绑定、工作目录、权限和运行配置不匹配时不续用旧
 历史；未知调用先阻断，不能以冷启动覆盖。会话不是状态真相。
 
 ### 4.1.1 可信 Plan 检查点
@@ -289,8 +303,9 @@ Node 发布的预热终态回执与 Go 读取端共用 8192 字节上限，按
 
 调用安全记录与历史复用分别控制。Codex Pro、Claude Code Pro、DSH、Kimi 的主任务调用在 fresh/scoped
 下都先保存 intent 再派发。`last.persistent` 表示是否参与通用角色历史；只有它为 true
-的可信结果才保存可复用句柄。fresh 的原始后端会话标识仍可保留在回执中，既有 Kimi
-Plan resident 行为不冒充跨里程碑的通用会话。其他适配器、mock 与 Intake／Garden
+的可信结果才保存可复用句柄。fresh 的原始后端会话标识仍可保留在回执中；仅未配置
+`native-profile` 的旧 Kimi CLI Plan 保留 resident 行为，不冒充跨里程碑的通用会话。
+其他适配器、mock 与 Intake／Garden
 保留原路径。模式或后端变化不能绕过已保存的未知调用。
 
 每个作用域有一个 `.sessions` 原子回执槽，使用私有目录／文件、限定大小与禁止符号
@@ -452,9 +467,9 @@ SIGKILL 后的进程组探测必须确认 `ESRCH` 才算清理成功。探测的
 
 ### 7.1 Codex Pro 接入契约
 
-`codex-pro` 不是 DSH LLM provider ID。使用 `harness: "codex-pro"`、显式模型、thinking 和账号 channel 选择该路径；不接受被忽略的 provider 或旧 resident-session 选项。主任务 fresh/scoped 均使用外层 worker v3，分别显式选择 ephemeral/persistent；低层兼容 v1/v2。内部仍为插件 0.9.0 的 machine request/receipt protocol 1，另有 lifecycle version 1。权限由显式 `permissions.mode` 决定，不能从桌面全访问设置隐式继承。
+`codex-pro` 不是 DSH LLM provider ID。使用 `harness: "codex-pro"`、显式模型、thinking 和账号 channel 选择该路径；不接受被忽略的 provider 或旧 resident-session 选项。主任务 fresh/scoped 均使用外层 worker v3，分别显式选择 ephemeral/persistent；低层兼容 v1/v2。内部仍为插件 0.10.0 的 machine request/receipt protocol 1，另有 lifecycle version 1。权限由显式 `permissions.mode` 决定，不能从桌面全访问设置隐式继承。
 
-worker 精确依赖插件 `0.9.0` 的公开 `runMachine` API，使用其协议 1 请求、进度回调和终态回执。模型／cwd／sandbox／approval 回执不符合请求时失败；接受 `workspace-write`、`read-only` 或明确选择的 `danger-full-access`，审批策略为 `never`。完全权限在公开 machine API 边界映射为 `dangerously-bypass-approvals-and-sandbox`，回执中的 Codex sandbox 为 `danger-full-access`、policy 类型为 `dangerFullAccess`，不能要求不存在的受限模式字段。插件仅能证明 effort 已被配置接受时，保留 `accepted` 与 `effectiveEffort: null`，不得改写成已证明实际推理强度。
+worker 精确依赖插件 `0.10.0` 的公开 `runMachine` API，使用其协议 1 请求、进度回调和终态回执。模型／cwd／sandbox／approval 回执不符合请求时失败；接受 `workspace-write`、`read-only` 或明确选择的 `danger-full-access`，审批策略为 `never`。完全权限在公开 machine API 边界映射为 `dangerously-bypass-approvals-and-sandbox`，回执中的 Codex sandbox 为 `danger-full-access`、policy 类型为 `dangerFullAccess`，不能要求不存在的受限模式字段。插件仅能证明 effort 已被配置接受时，保留 `accepted` 与 `effectiveEffort: null`，不得改写成已证明实际推理强度。
 
 权限检查分两个时点：插件检查实际配置，主任务 v3 的 thread-ready 再把完整 sandboxPolicy 送交 Go，在 ACK 前完成完整检查，阻止不符合策略的 turn/start。终态还须重新核对。受限模式不得有工作区外额外 writable roots 或 networkAccess；完全权限明确记录 dangerFullAccess，不宣称 OS 隔离。旧 v1/v2 以及未请求 lifecycle 的辅助调用仍只有终态完整策略检查，不能外推为预执行 guard。doctor 报告静态接口能力，不证明具体账号、历史或实际沙箱可用。
 
@@ -470,7 +485,7 @@ worker 精确依赖插件 `0.9.0` 的公开 `runMachine` API，使用其协议 1
 `thinking` 缺省 high，支持插件允许的 low/medium/high/xhigh/max；CLI、模型与账号仍
 可能拒绝某档位，不能把传参成功宣称为实际推理强度已验证。
 
-Flywheel 分发 worker，把插件 0.4.0 声明为精确的 optional peer。未选择它时不用安装
+Flywheel 分发 worker，把插件 0.5.0 声明为精确的 optional peer。未选择它时不用安装
 该 peer；选中时 `doctor` 与 worker 核验包名／版本／公开导出，并检查本地 `claude`
 命令。桌面安装目录不一定是 worker 的 Node 解析树；必须安装在该 worker 能解析的
 同一依赖树或全局 prefix。依赖缺失、接口不符和无效请求在 machine 调用前证明未派发；
@@ -508,6 +523,8 @@ unknown。身份错配的结果可以保留原始回执作审计，但其 usage/
 预算限制新的派发；消费已完成的可信回执不额外发请求或计费，不应因预算已满丢掉该
 结果。回执消费后需要的新阶段或重试仍受预算门禁控制。
 
+原生树的用量只有在exclusive归属、去重和本次调用完整性都成立时汇总。DSH本地子Session committed events与Codex子thread delta可在完整时加到root；Claude task snapshots不可直接相加；Kimi从实际step统计，compaction、恢复旧child、Tower或缺失计量保持unknown。scheduler的provider配额限制根调用，不是各harness内部的统一whole-tree硬上限；Claude observed guard明确hard=false，Kimi显式请求不可执行的hard cap时拒绝该组合。hard budget保留对未知调用的阻断，不用root-only数字伪装完整总量。
+
 ### 8.1 运行索引与指标比较
 
 运行索引在全局配置旁的 `runs/` 为每次明确的 CLI／控制接口启动独立保存，可用绝对 `FLYWHEEL_RUNS_DIR` 覆盖。索引记录 run ID、契约／配置摘要、启动和结束回执，以及可用的 DSH 会话 ID；只读取最近 100 条登记，不扫描项目或磁盘，也不作为进程仍存活或任务已完成的证明。
@@ -628,6 +645,7 @@ Go 的 `make quality-gate` 执行 vet、gofmt 和 **逐函数 100% statement cov
 | P5 就绪队列与一次性 DSH 预热 | [实施计划](plans/2026-11-13-p5-ready-queue-prewarm.md) | [工程验证与收益边界](validation/2026-11-13-p5-ready-queue-prewarm.md) |
 | 历史影子评估（已退役） | [原 JEV 方案](plans/2026-11-10-jev-shadow.md) | [历史验收](validation/2026-11-10-jev-shadow.md) |
 | 0.30.2 发行与安装 | [发行流程](zh-CN/releasing.md) | [发行记录](validation/2026-11-11-release-0.30.2.md) |
+| 0.33.1 桌面读取与发行 | [发行流程](zh-CN/releasing.md) | [发行与验收记录](validation/2026-11-14-release-0.33.1.md) |
 | 0.33.0 单包分发 | [发行流程](zh-CN/releasing.md) | [工程验证](validation/2026-11-14-single-package.md) |
 | 0.31.0 发行与安装 | [发行流程](zh-CN/releasing.md) | [发行记录](validation/2026-11-11-release-0.31.0.md) |
 
@@ -732,7 +750,9 @@ JEV 关闭对既有任务的影响在内容区说明，固定保存栏用简短
 
 原生 UI 接入和独立 worker 是不同边界。SDK worker 的临时 `--patch` 仅用于该子进程，不修改桌面 profile，也不卸载桌面的插件、skills、工具或 UI。桌面已加载插件、已登录账号、已选模型，不代表 SDK profile 或其他 harness 已配置相同能力；控制面显示引擎实际配置，不静默继承或迁移桌面设置。
 
-现有 worker 策略固定每次调用的目录、权限和审批，限制自主委派及 workflow／goal 驱动，禁用 `schedule`／`tool-schedule` 的自主提醒输入，并关闭模型标题和自动模型压缩以免脱离 Go 的计量和生命周期管理。临时覆盖不修改用户提醒存储。当前也保守禁用整个 `tool-web`，包括搜索与抓取；这不表示所有网页工具都需要辅助模型。官方 [web 工具](https://github.com/deepseek-ai/deepseek-harness/blob/fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159/packages/web/tool-web/README.md)可分别配置两者，模型辅助调用与普通检索需分别核对。完全权限改变宿主访问策略，仍保留这些工具与辅助模型调用限制；恢复检索、压缩或其他扩展属于后续能力工作，须同时验证计量、预算、取消与工作目录边界。
+未选择 native-profile 的 worker 保留原有工具组合与关闭自主 goal／schedule、辅助标题和自动压缩的策略。显式 native-profile 可启用同一受管调用内的 agents、Team、Workflow、Web 与 LCU；能力必须实际准入，不能只改提示词。完整权限仍不自动启用任何原生能力。临时 overlay不修改用户的 desktop preset、profile 或提醒存储。
+
+桌面 heavy/daily 与 SDK composition 复用生成器策略，但用户桌面历史不继承到独立 loop。工作台的模型与会话表可选择同 harness 的 native-profile，高级 JSON 编辑定义，配置查看和 doctor 展示实际引用。doctor的本地 manifest通过不等于运行 admission；native DSH不以legacy probe冒充实际PTC/LCU准入。完整设计与验证见[原生能力设计](plans/2026-11-13-native-harness-capabilities.md)和[验收记录](validation/2026-11-14-native-harness-implementation.md)。
 
 ### 12.3 受管阶段与远端交付
 
@@ -756,6 +776,8 @@ min-applicability、min-choice 和 allowed-data 限定请求。开启配置校
 
 可选的顶层 profiles 定义 harness/model/channel/thinking/provider；loops、routes 和顶层 judge-panel 通过 profile 引用，加载时展开为完整实际绑定。当前 binding 显式出现的字段覆盖 profile，省略才继承；不支持 profile 继承。必需字符串的 null、空白、错拼字段及未知引用在模型启动前失败。thinking 显式空字符串表示当前 harness 的既有默认，不重新继承；resident-session 仍属于阶段，显式 false 保留。judge-panel:null 继续关闭第二意见。旧 inline 配置保留已有缺省语义。
 
+可选 `native-profiles` 的字段信源为 `templates/native-profiles.schema.json`，每个定义明确harness与version 1 options。loops/routes/model profiles/judge-panel/execution-policy bindings的native-profile引用在LOAD时校验存在且harness一致。实际options进入session/history/prewarm和被引用execution-policy冻结身份，durable session configuration与state schema同时保存nativeProfile/nativeOptions；恢复按原请求核对。无关profile不改变已冻结身份，显式空字符串关闭模型profile继承。静态native配置与JEV唯一开关独立。
+
 可选 `execution-policy` 的字段信源为 `templates/execution-policy.schema.json`，
 版本 1 接受完整受管绑定、逐 route 允许集合和有界切换，缺省保留原绑定。packet
 派发前冻结策略身份。质量升级只在可信重复 L1 空转、剩余尝试与任务预算允许时
@@ -796,7 +818,7 @@ skills 继续从同一 Go 二进制内嵌资源安装。每个受管快照保存
 
 发布以精确 HEAD 标签与干净候选为依据。构建一次完整单包候选（candidate format 2），Linux/macOS 安装测试消费同一个 tarball；候选验证同时核对四个平台二进制、公开入口、MIT 许可和内置 adapter。已存在版本必须核对 integrity；先发 candidate 标签，精确版本从 registry 安装验证后才推进 latest，防止倒退。源码 PR CI 通过、npm pack 成功、registry 安装通过与用户 Mac 实机验收是不同证据，分别记录。
 
-历史 0.28.2 使用 DeepSeek API Key 默认，账号默认修复从 0.28.3 开始提供；这些版本差异保留在 changelog 和发行记录，升级仍须显式迁移已有配置，不重写已发布的包。DSH 插件精确依赖上游 `dsh-subagent-codex-pro@0.9.0`；该已审查源码候选以真实 npm tarball 锁定并 bundle 到完整包，来源、许可证和摘要见 [vendor 记录](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/vendor/README.md)。Claude 0.4.0 维持可选 peer。旧发行失败与重试记录保留在 [npm 验证记录](validation/2026-11-01-npm-installation.md)；源码、候选、CI、registry 和 Mac 实机证据分别记录，不混为一个“测试通过”。
+历史 0.28.2 使用 DeepSeek API Key 默认，账号默认修复从 0.28.3 开始提供；这些版本差异保留在 changelog 和发行记录，升级仍须显式迁移已有配置，不重写已发布的包。DSH 插件精确依赖上游 `dsh-subagent-codex-pro@0.10.0`；该正式发行包按 registry 的真实 npm tarball 与 integrity 锁定并 bundle 到完整包，来源、许可证和摘要见 [vendor 记录](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/vendor/README.md)。generator 0.4.0的共享PTC composition同样固定并bundle；Claude 0.5.0与LCU 0.5.0维持可选peer。旧发行失败与重试记录保留在 [npm 验证记录](validation/2026-11-01-npm-installation.md)；源码、候选、CI、registry 和 Mac 实机证据分别记录，不混为一个“测试通过”。
 
 CI、候选构建、双平台验证和发布统一固定为 Node 24.22.1／npm 12.2.1，预检只需同版 Node。发行协议测试通过隔离的本地 registry 调用真实 `npm view`，覆盖 latest、integrity、缺失字段与错误响应。存在的字段必须返回字符串，兼容用单元素数组包裹；多结果拒绝，缺失 latest 单独处理，缺失 integrity 不能当成版本不存在。只有结构化 E404 表示版本不存在，取消、认证或网络错误仍阻止发布。npm 11／12 的 `pack --json` 兼容保持严格包身份检查。
 

package/docs/en/claude-code-pro.md

@@ -8,7 +8,7 @@ The plugin runs the user's installed Claude Code CLI, with its native tool loop
 and login environment. Go retains scheduling, role sessions, verification,
 budgets, and delivery.
 
-The adapter requires **`dsh-subagent-claude-code-pro@0.4.0`**, machine protocol
+The adapter requires **`dsh-subagent-claude-code-pro@0.5.0`**, machine protocol
 1 and the public lifecycle/recovery interfaces. The older desktop-tool interface
 and older machine contracts are not substitutes. No default stage or route
 selects Claude. Package availability must be checked separately from source
@@ -22,7 +22,7 @@ Flywheel does not copy credentials or sign in on the user's behalf.
 
 Flywheel ships `flywheel-claude-code-pro-worker` and declares the exact plugin as
 an **optional peer**. Other backends work without it. To select Claude, install
-`dsh-subagent-claude-code-pro@0.4.0` in the same Node dependency tree or global npm
+`dsh-subagent-claude-code-pro@0.5.0` in the same Node dependency tree or global npm
 prefix as Flywheel. Installing it only in a DSH desktop profile does not establish
 that the independent worker can resolve it.