@ckanner/flywheel 0.32.1 → 0.33.1

package/dist/codex-pro-bridge.mjs

@@ -0,0 +1,75 @@
+// Public machine API consumer. Go remains the owner of scheduling and acceptance.
+import { createRequire } from 'node:module';
+import { isAbsolute } from 'node:path';
+
+export const ADAPTER = Object.freeze({ package: 'dsh-subagent-codex-pro', version: '0.9.0', protocol: 1 });
+export const LIMITS = Object.freeze({ requestBytes: 1024 * 1024, machineOutputBytes: 1024 * 1024,
+  progressBytes: 1024 * 1024, receiptFrameBytes: 8 * 1024 * 1024, admissionMs: 10000 });
+const require = createRequire(import.meta.url);
+
+export class WorkerError extends Error {
+  constructor(code, message) { super(message); this.name = 'WorkerError'; this.code = code; }
+}
+
+/** The doctor executes this same import, but never calls runMachine. */
+export async function loadAdapter() {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (major < 22 || (major === 22 && minor < 18)) throw new WorkerError('UNSUPPORTED_RUNTIME', 'Codex Pro requires Node.js 22.18.0 or newer');
+  if (!['darwin', 'linux'].includes(process.platform)) throw new WorkerError('UNSUPPORTED_RUNTIME', 'Codex Pro requires a supported POSIX platform');
+  let manifest, api;
+  try {
+    manifest = require('dsh-subagent-codex-pro/package.json');
+  } catch {
+    throw new WorkerError('ADAPTER_UNAVAILABLE', 'Install the exact dsh-subagent-codex-pro@0.9.0 dependency with Flywheel');
+  }
+  if (manifest.name !== ADAPTER.package || manifest.version !== ADAPTER.version) {
+    throw new WorkerError('ADAPTER_MISMATCH', 'Codex Pro package identity or version does not match the pinned contract');
+  }
+  try { api = await import('dsh-subagent-codex-pro/machine'); }
+  catch { throw new WorkerError('ADAPTER_UNAVAILABLE', 'The pinned Codex Pro public machine API could not be imported'); }
+  if (api.MACHINE_PROTOCOL_VERSION !== ADAPTER.protocol ||
+      typeof api.parseMachineRequest !== 'function' || typeof api.runMachine !== 'function' || typeof api.MachineInputError !== 'function' ||
+      api.MACHINE_LIFECYCLE_VERSION !== 1 || typeof api.recoverMachine !== 'function' ||
+      api.MACHINE_LIFECYCLE_CAPABILITIES?.durableJournal !== true || api.MACHINE_LIFECYCLE_CAPABILITIES?.readOnlyRecovery !== true ||
+      api.MACHINE_LIFECYCLE_CAPABILITIES?.threadReadyBeforeDispatch !== true) {
+    throw new WorkerError('ADAPTER_MISMATCH', 'Codex Pro package identity, version or public machine API does not match the pinned contract');
+  }
+  return api;
+}
+
+/** Reject unsupported fields and permissions before any process or prompt starts. */
+export function machineRequest(value, api, env) {
+  const lifecycle = value?.protocol === 3;
+  const persistent = value?.protocol === 2 || (lifecycle && value.threadMode === 'persistent');
+  const keys = new Set(['type', 'protocol', 'requestId', 'cwd', 'model', 'reasoningEffort', 'permissionMode', 'prompt', 'timeoutMs',
+    ...(persistent || lifecycle ? ['threadMode', 'threadId'] : []), ...(lifecycle ? ['recoveryDirectory'] : [])]);
+  if (value === null || typeof value !== 'object' || Array.isArray(value) || value.type !== 'start' || ![1, 2, 3].includes(value.protocol) ||
+      Object.keys(value).some(key => !keys.has(key)) || typeof value.requestId !== 'string' || value.requestId.length > 256 ||
+      (lifecycle && (!['ephemeral', 'persistent'].includes(value.threadMode) ||
+        typeof value.recoveryDirectory !== 'string' || !isAbsolute(value.recoveryDirectory) ||
+        value.recoveryDirectory.length > 4096 || value.recoveryDirectory.includes('\0') || (!persistent && value.threadId !== undefined))) ||
+      (persistent && (value.threadMode !== 'persistent' || (value.threadId !== undefined &&
+        (typeof value.threadId !== 'string' || !value.threadId.trim() || value.threadId.includes('\0'))))) ||
+      !['read-only', 'workspace-write', 'danger-full-access'].includes(value.permissionMode)) {
+    throw new WorkerError('INVALID_REQUEST', 'Expected one versioned start request with explicit supported permissions and history; protocol 3 requires an absolute recovery directory');
+  }
+  if (value.timeoutMs !== undefined && (!Number.isSafeInteger(value.timeoutMs) || value.timeoutMs < 1 || value.timeoutMs > 2147483647)) {
+    throw new WorkerError('INVALID_REQUEST', 'timeoutMs must be a positive safe integer no greater than 2147483647');
+  }
+  try {
+    return api.parseMachineRequest({ protocol: 1, requestId: value.requestId, cwd: value.cwd, model: value.model,
+      effort: value.reasoningEffort,
+      permissionMode: value.permissionMode === 'danger-full-access' ? 'dangerously-bypass-approvals-and-sandbox' : value.permissionMode,
+      prompt: value.prompt,
+      ...(value.timeoutMs === undefined ? {} : { timeoutMs: value.timeoutMs }),
+      command: env.FLYWHEEL_CODEX_BIN || 'codex', threadMode: persistent ? 'persistent' : 'ephemeral',
+      ...(persistent && value.threadId !== undefined ? { threadId: value.threadId } : {}), maxOutputBytes: LIMITS.machineOutputBytes });
+  } catch (error) {
+    throw new WorkerError('INVALID_REQUEST', error instanceof api.MachineInputError ? error.message : 'Invalid Codex Pro machine request');
+  }
+}
+
+export function doctorResult() {
+  return { protocol: 1, type: 'doctor', package: ADAPTER.package, version: ADAPTER.version,
+    machineProtocol: ADAPTER.protocol, available: true, inferenceTested: false };
+}

package/dist/codex-pro-worker.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import * as adapter from './codex-pro-bridge.mjs';
+import { runMachineWorker } from './machine-worker.mjs';
+
+await runMachineWorker({ ...adapter, label: 'Codex Pro', commandName: 'flywheel-codex-pro-worker' });

package/dist/console-read.mjs

@@ -0,0 +1,51 @@
+import { Service } from '@deepseek-ai/cordis';
+import { Remote, bindTypertRemote } from '@deepseek-ai/dsh-typert-protocol';
+import { realpath } from 'node:fs/promises';
+import { ControlNotDispatchedError } from './control.mjs';
+import { taskProjectionKey } from './task-association.mjs';
+
+// A read-only Remote, separate from logged human commands. Never add mutations
+// here: their durable command/tool receipts own replay and uncertain outcomes.
+export const consoleReadActions = new Set(['runs', 'status', 'config', 'config-edit', 'metrics', 'history', 'node', 'delivery', 'doctor']);
+const initializers = [];
+export class ConsoleReadService extends Service {
+  constructor(ctx, control, failure) {
+    super(ctx, 'flywheelConsole');
+    this.typertRemote = bindTypertRemote(this, 'flywheelConsole');
+    this.control = control;
+    this.failure = failure;
+    for (const initialize of initializers) initialize.call(this);
+  }
+  async read(agent, input, signal) {
+    try {
+      if (!agent?.session || !consoleReadActions.has(input?.action)) throw new ControlNotDispatchedError('Only session-scoped console reads are supported');
+      // Taskless configuration uses the real session directory. The client may
+      // not turn a read endpoint into arbitrary cross-session task discovery.
+      const projection = this.ctx.sessionProjections.stateOf(agent.session, taskProjectionKey);
+      const catalog = async () => {
+        const value = await this.control({ action: 'runs' }, agent, signal);
+        return { ...value, runs: (value.runs ?? []).filter(run => run.hostSessionId === agent.session.id) };
+      };
+      let value;
+      if (input.action === 'runs') {
+        value = await catalog();
+      } else {
+        if (input.taskDir) {
+          const taskDir = await realpath(input.taskDir);
+          const cwd = await realpath(input.cwd ?? this.ctx.workingDirectory.get(agent.session));
+          const matches = task => task?.taskDir === taskDir && task.cwd === cwd;
+          if (!matches(projection?.view) && !(await catalog()).runs.some(matches)) throw new ControlNotDispatchedError('This task is not associated with the current conversation');
+        } else if (input.cwd != null && await realpath(input.cwd) !== await realpath(this.ctx.workingDirectory.get(agent.session))) {
+          throw new ControlNotDispatchedError('Configuration must belong to the current conversation workspace');
+        }
+        value = await this.control(input, agent, signal);
+      }
+      return { result: { kind: 'success', text: JSON.stringify(value) } };
+    } catch (error) {
+      return { result: { kind: 'error', text: JSON.stringify(this.failure(input, error)) } };
+    }
+  }
+}
+// Invoke the public standard decorator in plain JS (no compiler/private symbols).
+Remote(ConsoleReadService.prototype.read, { kind: 'method', name: 'read', static: false, private: false,
+  addInitializer: initialize => initializers.push(initialize) });

package/dist/control.mjs

@@ -0,0 +1,218 @@
+import { spawn } from 'node:child_process';
+import { directory, nonempty, record, validInvestigationCommand } from './protocol.mjs';
+
+const actions = ['investigate', 'launch', 'start', 'status', 'stop', 'config', 'doctor', 'step', 'config-edit', 'config-save', 'runs', 'metrics', 'session', 'history', 'delivery', 'deliver', 'node'];
+const checkStatuses = ['pass', 'fail', 'warn', 'unknown', 'skipped'];
+
+// This marker is issued only where the host can prove that no control process
+// started. An engine/transport error after spawn must never acquire it.
+export class ControlNotDispatchedError extends Error {
+  constructor(cause) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.name = 'ControlNotDispatchedError';
+  }
+}
+
+export async function validateControl(input, defaultCwd) {
+  if (!record(input) || !actions.includes(input.action)) {
+    throw new Error('action must be launch, start, step, status, stop, config, config-edit, config-save, or doctor');
+  }
+  if (Object.keys(input).some(key => !['action', 'taskDir', 'cwd', 'probe', 'mode', 'only', 'packet', 'revision', 'retryReason', 'editor', 'session', 'sessionKey', 'delivery', 'runId', 'investigation'].includes(key))) {
+    throw new Error('unknown Flywheel control argument');
+  }
+  if (input.action === 'investigate' ? !validInvestigationCommand(input.investigation) : 'investigation' in input) throw new Error('investigate requires a typed, revision-bound preparation command');
+  if (input.investigation && Buffer.byteLength(JSON.stringify(input.investigation)) > 131072) throw new Error('investigation input exceeds 128 KiB');
+  if ('probe' in input && (input.action !== 'doctor' || typeof input.probe !== 'boolean')) {
+    throw new Error('probe must be a boolean and is only supported by doctor');
+  }
+  if ('mode' in input && (!['launch', 'start'].includes(input.action) || !['auto', 'quick', 'full'].includes(input.mode))) {
+    throw new Error('mode must be auto, quick, or full and is only supported by launch/start');
+  }
+  if (input.action === 'session' ? !record(input.session) || !['claim', 'send', 'return', 'reconcile', 'release'].includes(input.session.action) || typeof input.session.key !== 'string' || !Number.isSafeInteger(input.session.revision) || input.session.revision < 1 : 'session' in input) throw new Error('session requires a typed revision-bound command');
+  if (input.action === 'history' ? typeof input.sessionKey !== 'string' || !input.sessionKey : 'sessionKey' in input) throw new Error('history requires an exact session key');
+  if (input.session && Buffer.byteLength(JSON.stringify(input.session)) > 131072) throw new Error('session command too large');
+  if (['delivery','deliver'].includes(input.action) ? !record(input.delivery) || (input.action === 'delivery' ? input.delivery.action !== 'inspect' : !['create','merge'].includes(input.delivery.action) || input.delivery.confirmed !== true) : 'delivery' in input) throw new Error('delivery writes require explicit confirmation');
+  if (input.delivery && Buffer.byteLength(JSON.stringify(input.delivery)) > 131072) throw new Error('delivery request too large');
+  if ('runId' in input && (input.action !== 'metrics' || typeof input.runId !== 'string' || !input.runId || input.runId.length > 128 || /[\0\r\n]/.test(input.runId))) throw new Error('runId requires metrics and an exact engine ID');
+  const editing = ['config-edit', 'config-save'].includes(input.action);
+  if (editing ? !record(input.editor) || !['global', 'project'].includes(input.editor.scope) : 'editor' in input) {
+    throw new Error('editor requires config-edit/config-save and an explicit global/project scope');
+  }
+  if (input.action === 'step') {
+    if (!['plan', 'execute', 'review', 'verify', 'integrate', 'final'].includes(input.only) || !Number.isSafeInteger(input.revision) || input.revision < 1 ||
+        (input.packet !== undefined && (typeof input.packet !== 'string' || !/^M\d+-T\d+$/.test(input.packet)))) {
+      throw new Error('step requires a valid stage, state revision and optional packet id');
+    }
+  } else if (input.action === 'node') {
+    if (typeof input.packet !== 'string' || !/^M\d+-T\d+$/.test(input.packet) || 'only' in input || 'revision' in input) throw new Error('node requires an exact packet ID');
+  } else if (['only', 'packet', 'revision'].some(key => key in input)) {
+    throw new Error('stage arguments require step');
+  }
+  if ('retryReason' in input && (input.action !== 'step' || input.only !== 'execute' || typeof input.retryReason !== 'string' || !input.retryReason.trim() || Buffer.byteLength(input.retryReason) > 1000)) throw new Error('retryReason requires Execute and a bounded explanation');
+  if (editing && Buffer.byteLength(JSON.stringify(input.editor)) > 1024 * 1024) throw new Error('configuration exceeds 1 MiB');
+  const needsTask = !['config', 'doctor', 'config-edit', 'config-save', 'runs'].includes(input.action);
+  return {
+    action: input.action,
+    ...(input.investigation ? { investigation: input.investigation } : {}),
+    ...(input.action === 'node' ? { packet: input.packet } : {}),
+    ...(input.runId ? { runId: input.runId } : {}),
+    ...(input.delivery ? { delivery: input.delivery } : {}),
+    ...(input.session ? { session: input.session } : {}),
+    ...(input.sessionKey ? { sessionKey: input.sessionKey } : {}),
+    taskDir: needsTask || 'taskDir' in input ? await directory(input.taskDir, 'taskDir') : '',
+    cwd: await directory(input.cwd ?? defaultCwd, 'cwd'),
+    ...(input.action === 'doctor' ? { probe: input.probe ?? false } : {}),
+    ...(input.action === 'launch' || 'mode' in input ? { mode: input.mode ?? 'auto' } : {}),
+    ...(input.action === 'step' ? { only: input.only, packet: input.packet, revision: input.revision, ...(input.retryReason ? { retryReason: input.retryReason } : {}) } : {}),
+    ...(editing ? { editor: input.editor } : {}),
+  };
+}
+
+function validConfiguration(value) {
+  return record(value) && typeof value.source === 'string' && typeof value.scope === 'string' &&
+    Array.isArray(value.bindings) && value.bindings.every(binding => record(binding) &&
+      ['id', 'role', 'harness'].every(key =>
+        typeof binding[key] === 'string' && binding[key].trim() !== '') &&
+      ['route', 'profile', 'provider', 'channel', 'model', 'thinking', 'permissionMode'].every(key =>
+        binding[key] === undefined || typeof binding[key] === 'string') &&
+      ['residentSession', 'inScope'].every(key => binding[key] === undefined || typeof binding[key] === 'boolean'));
+}
+
+function validDiagnostic(value, request) {
+  return record(value) && value.kind === 'doctor' && typeof value.ok === 'boolean' &&
+    typeof value.cwd === 'string' && value.cwd.trim() !== '' && value.taskDir === request.taskDir &&
+    value.probeRequested === request.probe && value.inferenceTested === false &&
+    (value.configuration === undefined || validConfiguration(value.configuration)) &&
+    Array.isArray(value.checks) && value.checks.every(check => record(check) &&
+      typeof check.id === 'string' && check.id.trim() !== '' && checkStatuses.includes(check.status) &&
+      typeof check.summary === 'string' && check.summary.trim() !== '' &&
+      ['code', 'remedy'].every(key => check[key] === undefined || typeof check[key] === 'string'));
+}
+
+/** Only the engine executable can mutate engine state. No shell interpolation. */
+export async function runControl(input, { binary = 'flywheel', defaultCwd, hostSessionID, signal, timeoutMs = 60000 } = {}) {
+  let request;
+  try {
+    nonempty(binary, 'flywheelBinary', 4096);
+    if (binary.startsWith('-')) throw new Error('flywheelBinary must name an executable');
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 120000) {
+      throw new Error('controlTimeoutMs must be between 100 and 120000');
+    }
+    request = await validateControl(input, defaultCwd);
+    if (signal?.aborted) throw new Error('Flywheel control request cancelled');
+  } catch (error) {
+    throw new ControlNotDispatchedError(error);
+  }
+  // Diagnostic commands own watchdog child groups. Its TERM grace, pipe
+  // WaitDelay, and quiescence confirmation may each take 5s; keep the Go owner
+  // alive long enough to finish all three instead of orphaning its workers.
+  const killGraceMs = ['config', 'doctor', 'config-edit', 'config-save', 'delivery', 'deliver'].includes(request.action) ? 20000 : 500;
+  const args = ['control', request.action, '--cwd', request.cwd, '--compact'];
+  if (request.taskDir) args.push('--task-dir', request.taskDir);
+  if (request.probe) args.push('--probe');
+  if (request.mode) args.push('--mode', request.mode);
+  if (request.only) args.push('--only', request.only, '--expect-revision', String(request.revision));
+  if (request.packet) args.push('--packet', request.packet);
+  if (request.runId) args.push('--run-id', request.runId);
+  if (request.sessionKey) args.push('--session-key', request.sessionKey);
+  if (request.retryReason) args.push('--retry-reason', request.retryReason);
+  const env = { ...process.env };
+  delete env.DSH_SESSION_ID;
+  if (typeof hostSessionID === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(hostSessionID)) env.DSH_SESSION_ID = hostSessionID;
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(binary, args, {
+        cwd: request.cwd, env, detached: false, stdio: [request.editor || request.session || request.delivery || request.investigation ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      reject(new ControlNotDispatchedError(error));
+      return;
+    }
+    let spawned = false;
+    child.once('spawn', () => { spawned = true; });
+    let stdout = '';
+    let stderr = '';
+    let failure;
+    let killTimer;
+    const stop = error => {
+      if (failure) return;
+      failure = error;
+      clearTimeout(timer);
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), killGraceMs);
+    };
+    const cancel = () => stop(new Error('Flywheel control request cancelled'));
+    const timer = setTimeout(() => stop(new Error('Flywheel control request timed out')), timeoutMs);
+    if (request.editor || request.session || request.delivery || request.investigation) {
+      child.stdin.on('error', error => stop(error));
+      child.stdin.end(JSON.stringify(request.editor ?? request.session ?? request.delivery ?? request.investigation));
+    }
+    signal?.addEventListener('abort', cancel, { once: true });
+    // Decode across chunks so a split UTF-8 code point is not replaced in a
+    // Chinese diagnostic, model name, or path.
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', chunk => {
+      if (failure) return;
+      stdout += chunk;
+      if (Buffer.byteLength(stdout) > 1024 * 1024) stop(new Error('Flywheel control response exceeds 1 MiB'));
+    });
+    child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-8192); });
+    child.on('error', error => {
+      // Node emits spawn before other events after successful process creation.
+      // Require both the missing spawn event and missing PID for positive proof.
+      failure = !spawned && child.pid === undefined ? new ControlNotDispatchedError(error) : error;
+    });
+    child.on('close', (code, childSignal) => {
+      clearTimeout(timer);
+      clearTimeout(killTimer);
+      signal?.removeEventListener('abort', cancel);
+      if (failure) return reject(failure);
+      let response;
+      try { response = JSON.parse(stdout); } catch {
+        return reject(new Error(`Flywheel returned invalid JSON (exit ${code}): ${stderr.trim()}`));
+      }
+      if (!record(response) || response.protocol !== 1 || response.taskDir !== request.taskDir ||
+          (response.cwd !== undefined && response.cwd !== request.cwd) ||
+          typeof response.ok !== 'boolean') {
+        return reject(new Error('Flywheel control response has incompatible protocol, taskDir, or cwd'));
+      }
+      if ((response.configuration !== undefined && !validConfiguration(response.configuration)) ||
+          (response.diagnostic !== undefined && !validDiagnostic(response.diagnostic, request))) {
+        return reject(new Error('Flywheel control returned a malformed configuration or diagnostic'));
+      }
+      if (request.action === 'doctor' && response.diagnostic !== undefined &&
+          response.diagnostic.ok !== response.ok) {
+        return reject(new Error('Flywheel doctor result disagrees with its control envelope'));
+      }
+      // A failed preflight is a usable report, unlike transport/protocol errors.
+      // Only the documented failure exit is allowed through this exception.
+      if (request.action === 'doctor' && code === 1 && !childSignal && response.ok === false &&
+          response.diagnostic?.ok === false) return resolve(response);
+      if (code !== 0 || childSignal || response.ok !== true) {
+        return reject(new Error(typeof response.error === 'string' ? response.error :
+          `Flywheel control failed (exit ${code}): ${stderr.trim()}`));
+      }
+      // After a repair handoff the implementation ledger owns status. This
+      // read-only subcommand may return that ledger; mutations still require
+      // their preparation receipt and cannot be confirmed by unrelated state.
+      const investigationStatusAfterHandoff = request.investigation?.action === 'status' && response.preparation === undefined &&
+        record(response.state) && Number.isSafeInteger(response.state.revision) && response.state.revision > 0 &&
+        typeof response.state.status === 'string' && response.state.status !== '' && record(response.state.packets);
+      if ((request.action === 'investigate' && !investigationStatusAfterHandoff && (!record(response.preparation) || response.preparation.version !== 1 || !Number.isSafeInteger(response.preparation.revision) || response.preparation.revision < 1 || !record(response.preparation.contract) || !Array.isArray(response.preparation.observations))) ||
+          (request.action === 'node' && (!record(response.node) || response.node.id !== request.packet || !record(response.node.packet))) ||
+          (['delivery','deliver'].includes(request.action) && (!record(response.delivery) || !Array.isArray(response.delivery.pulls))) ||
+          (request.action === 'history' && (!record(response.history) || response.history.key !== request.sessionKey)) ||
+          (request.action === 'runs' && !Array.isArray(response.runs)) ||
+          (request.action === 'metrics' && (!record(response.metrics) || !Array.isArray(response.metrics.groups))) ||
+          (request.action === 'config' && !response.configuration) ||
+          (request.action === 'doctor' && !response.diagnostic) ||
+          (request.editor && (!record(response.editor) || response.editor.scope !== request.editor.scope ||
+            typeof response.editor.revision !== 'string' || !record(response.editor.values) || !record(response.editor.defaults)))) {
+        return reject(new Error('Flywheel control response is missing its requested report'));
+      }
+      resolve(response);
+    });
+  });
+}

package/dist/index.mjs

@@ -0,0 +1,185 @@
+import { reconcileWorkspaces, watchWorkspaces } from './workspaces.mjs';
+import { ControlNotDispatchedError, runControl } from './control.mjs';
+import { resolveFlywheelBinary } from './installation.mjs';
+import { mutatesTask, taskAssociationProjection, taskProjectionKey } from './task-association.mjs';
+
+export const inject = ['commands', 'tools', 'workingDirectory', 'sessionProjections'];
+
+export function apply(ctx, config = {}) {
+  // Loading the desktop package accidentally into the SDK profile must not
+  // give a worker a tool that launches another orchestrator.
+  if (process.env.FLYWHEEL_DSH_NATIVE_WORKER === '1') return;
+  ctx.sessionProjections.register(taskAssociationProjection);
+  watchWorkspaces(ctx);
+  const binary = resolveFlywheelBinary(config);
+  const active = new Set();
+  const sessionMutations = new WeakMap();
+  const failure = (input, error) => ({
+    protocol: 1, type: 'flywheel-control-error',
+    action: typeof input?.action === 'string' ? input.action : null,
+    dispatch: error instanceof ControlNotDispatchedError ? 'not-dispatched' : 'unknown',
+    message: error instanceof Error ? error.message : String(error),
+  });
+  const control = async (input, agent, signal, operationId) => {
+    const session = agent?.session;
+    const mutation = mutatesTask(input?.action);
+    if (session && (mutation || input?.action === 'status')) {
+      try {
+        const projection = ctx.sessionProjections.stateOf(session, taskProjectionKey);
+        if (!projection) throw new Error('Flywheel task association is unavailable for this session');
+        const unresolved = projection.view;
+        if (sessionMutations.has(session) || (mutation && unresolved &&
+            unresolved.outcome !== 'confirmed' && unresolved.operationId !== operationId)) {
+          throw new Error('A Flywheel mutation is still unconfirmed. Wait for it to finish, then query status for its original task before another launch/start/stop.');
+        }
+        // The projection can recover an omitted cwd only from the immutable
+        // header or a logged directory change. An external getter fallback
+        // cannot bind a missing response to the original project after reload.
+        if (mutation && input?.cwd == null && (typeof projection.cwd !== 'string' ||
+            !projection.cwd.startsWith('/') || /[\0\r\n]/.test(projection.cwd))) {
+          throw new Error('This session has no recorded project directory. Supply an explicit absolute cwd for launch/start/stop so the original task can be associated and reconciled.');
+        }
+      } catch (error) {
+        throw new ControlNotDispatchedError(error);
+      }
+    }
+    const controller = new AbortController();
+    if (session && mutation) sessionMutations.set(session, controller);
+    const cancel = () => controller.abort();
+    signal?.addEventListener('abort', cancel, { once: true });
+    if (signal?.aborted) cancel();
+    active.add(controller);
+    try {
+      let defaultCwd;
+      try {
+        // The immutable session header records its original project. Read the
+        // public current-directory projection without ensure() recovery effects.
+        if (input?.cwd == null && agent?.session) {
+          defaultCwd = ctx.workingDirectory.get(agent.session);
+        }
+      } catch (error) {
+        // No control process has been launched if resolving the default fails.
+        throw new ControlNotDispatchedError(error);
+      }
+      const response = await runControl(input, {
+        binary,
+        defaultCwd,
+        hostSessionID: session?.id,
+        timeoutMs: config.controlTimeoutMs ?? 60000,
+        signal: controller.signal,
+      });
+      try { await reconcileWorkspaces(ctx, response); }
+      catch (error) {
+        // Association failure does not undo a successful engine mutation.
+        response.workspaceWarnings = ['工作区归属未同步：' + error.message];
+      }
+      return response;
+    } finally {
+      if (session && sessionMutations.get(session) === controller) sessionMutations.delete(session);
+      active.delete(controller);
+      signal?.removeEventListener('abort', cancel);
+    }
+  };
+  ctx.on('dispose', () => { for (const controller of active) controller.abort(); });
+  // Optional injection keeps command-only SDK/legacy fixtures independent.
+  ctx.inject?.(['typert'], async scope => {
+    // Host peers remain optional for CLI-only imports and native workers.
+    const { ConsoleReadService } = await import('./console-read.mjs');
+    new ConsoleReadService(scope, control, failure);
+  });
+  ctx.commands.register({
+    name: 'flywheel',
+    description: '通过 Go 引擎控制 Flywheel 任务、查看实际模型配置或执行无推理环境检查。',
+    input: { hint: '{"action":"launch","taskDir":"/absolute/docs/task","mode":"auto"} 或 {"action":"status","taskDir":"/absolute/docs/task"}' },
+    async handler({ rawInput, agent, signal, commandId }) {
+      let input;
+      try {
+        try {
+          input = JSON.parse(rawInput);
+        } catch (error) {
+          throw new ControlNotDispatchedError(error);
+        }
+        const value = await control(input, agent, signal, 'command:' + commandId);
+        return { kind: 'success', text: JSON.stringify(value, null, 2) };
+      } catch (error) {
+        // CommandResult preserves only kind/text. Wrap every failure, including
+        // unknown outcomes, so a child error's text cannot impersonate host proof.
+        return { kind: 'error', text: JSON.stringify(failure(input, error), null, 2) };
+      }
+    },
+  });
+  const toolFailures = new WeakMap();
+  const executeTool = async (args, execution) => {
+    try {
+      return JSON.stringify(await control(args, execution.agent, execution.signal, 'tool:' + execution.callId));
+    } catch (error) {
+      toolFailures.set(execution, failure(args, error));
+      throw error;
+    }
+  };
+  // finalizeContent is the public last-mile ToolDefinition hook. Framework
+  // failures remain isError outcomes, with host-owned dispatch proof available
+  // to the durable projection instead of brittle matching of error prose.
+  const finalizeContent = (execution, result) => {
+    const known = toolFailures.get(execution);
+    toolFailures.delete(execution);
+    if (!result.isError) return;
+    const action = execution.name === 'flywheel_launch' ? 'launch' : execution.arguments?.action;
+    const value = known ?? failure({ action }, new Error(result.error?.message ?? 'Flywheel tool did not confirm its result'));
+    if (result.error?.info?.code === 'ABORTED_BEFORE_DISPATCH') value.dispatch = 'not-dispatched';
+    return [{ type: 'text', text: JSON.stringify(value) }];
+  };
+  const taskProperties = {
+    taskDir: { type: 'string', description: 'Absolute existing prepared task ledger directory; never infer a task by scanning directories' },
+    cwd: { type: 'string', description: 'Absolute target repository directory; defaults to the current working directory of this DSH session. Launch/start/stop require it explicitly if the session has no recorded directory.' },
+    mode: { type: 'string', enum: ['auto', 'quick', 'full'], description: 'Launch/start only. Launch defaults to auto; omitted on legacy start preserves its existing behavior. The Go engine persists and explains the effective mode.' },
+  };
+  ctx.tools.register({
+    name: 'flywheel_launch',
+    description: 'Launch one prepared Flywheel task with its deterministic Go engine and associate its exact directory with this DSH conversation’s Flywheel view. ' +
+      'Prepare and validate the frozen contract first; this tool does not invent requirements or write state.json. ' +
+      'Default mode auto lets the engine choose Quick or Full and explain why. Explicit quick/full selects that request. ' +
+      'If the result is unconfirmed, query flywheel_control status for the same task before repeating any mutation. Do not launch recursively from a Flywheel worker.',
+    parameters: { type: 'object', additionalProperties: false, properties: taskProperties, required: ['taskDir'] },
+    output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
+    timeoutMs: config.controlTimeoutMs ?? 60000,
+    isConcurrencySafe: () => false,
+    execute: (args, execution) => executeTool({ ...args, action: 'launch' }, execution),
+    finalizeContent,
+  });
+  // ToolDefinition is the public raw registry format. The same boundary
+  // validates both this entry and the human slash command before spawning.
+  ctx.tools.register({
+    name: 'flywheel_control',
+    description: 'Control an existing Flywheel task via its deterministic Go engine. ' +
+      'Use investigate with a versioned preparation contract to gather bounded evidence; run starts the Go investigation owner in the background. Report-only investigation never authorizes implementation. Use launch for a prepared implementation task (Auto by default), status to inspect progress, start to resume, stop to await cancellation. ' +
+      'Launch/start associates the exact task with the current conversation’s Flywheel view. After an unconfirmed mutation, query the same task before another mutation. ' +
+      'Use config to inspect effective model bindings or doctor for a local preflight; these may omit taskDir. ' +
+      'Only doctor accepts probe=true to check the SDK without sending an inference prompt. ' +
+      'A successful doctor does not prove account authorization, quota, or model inference. ' +
+      'This tool never writes state.json. Do not use it to create a recursive Flywheel run.',
+    parameters: {
+      type: 'object', additionalProperties: false,
+      properties: {
+        action: { type: 'string', enum: ['investigate', 'launch', 'start', 'status', 'stop', 'config', 'doctor'] },
+        ...taskProperties,
+        investigation: { type: 'object', additionalProperties: false, properties: {
+          action: { type: 'string', enum: ['start', 'run', 'status', 'report', 'cancel'] },
+          revision: { type: 'integer', minimum: 1 },
+          contract: { type: 'object', description: 'Exact version-1 preparation.schema.json contract; use flywheel template to read the installed schema. Store no credentials.' },
+          report: { type: 'object', description: 'Evidence-cited investigation report; references must name recorded invocation IDs. This never marks code completed.' },
+        }, required: ['action'] },
+        probe: { type: 'boolean', description: 'Doctor only: explicitly enable SDK checks without inference; defaults to false' },
+      },
+      required: ['action'],
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    timeoutMs: config.controlTimeoutMs ?? 60000,
+    isConcurrencySafe: args => ['status', 'config', 'doctor'].includes(args.action),
+    execute: executeTool,
+    finalizeContent,
+  });
+}

package/dist/installation.mjs

@@ -0,0 +1,56 @@
+import { accessSync, constants, lstatSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ownPackage = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
+
+function bundledLauncher() {
+  // The private source harness has no complete distribution. Installed packages
+  // own their CLI and must never silently borrow a different global version.
+  const root = new URL('../', import.meta.url);
+  if (ownPackage.private === true) return 'flywheel';
+  const launcher = fileURLToPath(new URL('bin/flywheel.js', root));
+  if (ownPackage.name !== '@ckanner/flywheel') throw new Error('Invalid bundled Flywheel package identity');
+  const stat = lstatSync(launcher);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('Bundled Flywheel launcher is missing or invalid; reinstall the package');
+  accessSync(launcher, constants.X_OK);
+  return launcher;
+}
+
+// The npm installer owns this small receipt. A desktop host can find the exact
+// launcher without relying on the login shell's PATH or editing a user patch.
+export function resolveFlywheelBinary(config = {}, environment = process.env) {
+  if (config.flywheelBinary !== undefined) {
+    if (typeof config.flywheelBinary !== 'string' || !config.flywheelBinary.trim()) throw new Error('flywheelBinary must be a nonempty command or path');
+    return config.flywheelBinary;
+  }
+  const filename = join(environment.HOME || homedir(), '.config', 'flywheel', 'installation.json');
+  let receipt;
+  try {
+    const stat = lstatSync(filename);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384) throw new Error('invalid installation record');
+    receipt = JSON.parse(readFileSync(filename, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return bundledLauncher();
+    throw new Error('Flywheel installation record is invalid; rerun flywheel setup or set flywheelBinary explicitly');
+  }
+  const launcher = receipt?.launcher;
+  if (receipt?.protocol !== 1 || receipt?.owner !== '@ckanner/flywheel' || typeof launcher?.path !== 'string'
+    || !isAbsolute(launcher.path) || !/^[a-f0-9]{64}$/.test(launcher.sha256)) {
+    throw new Error('Flywheel installation record has an unsupported contract; rerun flywheel setup');
+  }
+  try {
+    const stat = lstatSync(launcher.path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65536) throw new Error('invalid launcher');
+    accessSync(launcher.path, constants.X_OK);
+    if (createHash('sha256').update(readFileSync(launcher.path)).digest('hex') !== launcher.sha256) throw new Error('launcher was modified');
+  } catch {
+    throw new Error('Flywheel launcher is missing or changed; preserve custom edits and rerun setup or set flywheelBinary explicitly');
+  }
+  if (ownPackage.private !== true && receipt.version !== ownPackage.version) {
+    throw new Error('Flywheel launcher version does not match this package; rerun flywheel setup for this version');
+  }
+  return launcher.path;
+}