@ckanner/flywheel 0.33.0 → 0.34.0

package/dist/kimi-native-runtime.mjs

@@ -0,0 +1,233 @@
+import { createHash } from 'node:crypto';
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const execute = promisify(execFile);
+export const digest = value => createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex');
+export const error = (code, message) => Object.assign(new Error(message), { code });
+export const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
+export const checkAbort = signal => { if (signal?.aborted) throw typeof signal.reason?.code === 'string' ? signal.reason : error('CANCELLED', 'The owned Kimi invocation was cancelled'); };
+
+async function processTable() {
+  const { stdout } = await execute('ps', ['-axo', 'pid=,ppid=,lstart=,stat='], {
+    encoding: 'utf8', maxBuffer: 4 * 1024 * 1024, timeout: 2000, env: { ...process.env, LC_ALL: 'C' },
+  });
+  return stdout.trim().split('\n').map(line => {
+    const fields = line.trim().split(/\s+/);
+    return { pid: Number(fields[0]), parent: Number(fields[1]), birth: fields.slice(2, 7).join(' '), state: fields[7] };
+  }).filter(row => Number.isSafeInteger(row.pid) && row.birth && row.state);
+}
+
+/** One foreground local server, sharing only the user's existing credential home. */
+export class OwnedKimiRuntime {
+  constructor(env, mode) {
+    this.env = { ...env, KIMI_CODE_EXPERIMENTAL_TOWER: mode === 'tower' ? '1' : '0' };
+    this.home = env.KIMI_CODE_HOME || join(env.HOME || homedir(), '.kimi-code');
+    this.processes = new Map();
+    this.processInspection = false;
+    this.closed = false;
+  }
+  async sampleProcesses() {
+    const table = await processTable();
+    let changed = true;
+    const root = table.find(row => row.pid === this.child.pid);
+    // Never adopt a reused PID after the owned process has exited.
+    const owned = new Set();
+    if (root && (!this.closed || this.processes.get(root.pid)?.birth === root.birth)) {
+      owned.add(root.pid); this.observedRoot = true;
+    }
+    for (const row of table) if (this.processes.get(row.pid)?.birth === row.birth) owned.add(row.pid);
+    while (changed) {
+      changed = false;
+      for (const row of table) if (!owned.has(row.pid) && owned.has(row.parent)) { owned.add(row.pid); changed = true; }
+    }
+    for (const row of table) if (owned.has(row.pid)) this.processes.set(row.pid, row);
+    this.processInspection = true;
+    return table.filter(row => this.processes.get(row.pid)?.birth === row.birth && !row.state.startsWith('Z'));
+  }
+  async start(signal) {
+    checkAbort(signal);
+    const started = Date.now();
+    this.child = spawn(this.env.FLYWHEEL_KIMI_BIN || 'kimi', ['web', '--no-open', '--host', '127.0.0.1', '--port', '0'], {
+      env: this.env, stdio: ['ignore', 'pipe', 'pipe'], detached: false,
+    });
+    // The CLI banner includes the bearer token. Neither stdout nor stderr is a
+    // machine protocol, and no raw startup bytes are forwarded or persisted.
+    this.child.stdout.on('data', () => {});
+    this.child.stderr.on('data', () => {});
+    this.exit = new Promise(resolve => {
+      this.child.once('error', cause => { this.spawnError = cause; this.closed = true; resolve(); });
+      this.child.once('exit', (code, signalName) => { this.closed = true; this.exitCode = code; this.exitSignal = signalName; resolve(); });
+    });
+    this.sampler = setInterval(() => { this.sampleProcesses().catch(() => { this.processInspection = false; }); }, 500);
+    this.sampler.unref();
+    await this.sampleProcesses();
+    const directory = join(this.home, 'server', 'instances');
+    while (Date.now() - started < 20_000) {
+      checkAbort(signal);
+      if (this.closed) throw error('RUNTIME_START', this.spawnError ? 'Cannot start the configured Kimi CLI' : 'Kimi web exited before registering its owned server');
+      let names = [];
+      try { names = await readdir(directory); } catch (cause) { if (cause.code !== 'ENOENT') throw error('RUNTIME_REGISTRY', 'Cannot read the Kimi server instance registry'); }
+      for (const name of names.filter(name => name.endsWith('.json'))) {
+        let entry;
+        try { entry = JSON.parse(await readFile(join(directory, name), 'utf8')); } catch { continue; }
+        if (entry.pid !== this.child.pid || entry.host !== '127.0.0.1' || !Number.isSafeInteger(entry.port) || entry.port < 1 || entry.port > 65535
+            || typeof entry.server_id !== 'string' || entry.started_at < started - 2000) continue;
+        const token = (await readFile(join(this.home, 'server.token'), 'utf8')).trim();
+        if (!token || /[\s,]/.test(token) || token.length > 4096) throw error('RUNTIME_AUTH', 'The existing Kimi server token is missing or invalid');
+        this.token = token;
+        this.base = `http://127.0.0.1:${entry.port}`;
+        const meta = await this.request('/api/v1/meta', undefined, { signal });
+        if (meta.server_id !== entry.server_id || meta.dangerous_bypass_auth !== false || meta.backend !== 'v2' || meta.capabilities?.websocket !== true) {
+          throw error('RUNTIME_IDENTITY', 'The authenticated server does not match the newly owned local runtime');
+        }
+        this.meta = meta;
+        await this.sampleProcesses();
+        return;
+      }
+      await pause(40);
+    }
+    throw error('RUNTIME_START', 'Kimi web did not register an authenticated local server in time');
+  }
+  async request(path, body, { signal, raw = false, timeout = 5000 } = {}) {
+    const bounded = AbortSignal.timeout(timeout);
+    const response = await fetch(this.base + path, {
+      method: body === undefined ? 'GET' : 'POST', headers: { Authorization: `Bearer ${this.token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: signal ? AbortSignal.any([signal, bounded]) : bounded,
+    });
+    const reader = response.body.getReader();
+    const chunks = []; let bytes = 0;
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        bytes += value.byteLength;
+        if (bytes > 8 * 1024 * 1024) { await reader.cancel(); throw error('RESPONSE_LIMIT', 'Kimi response exceeds the bounded adapter limit'); }
+        chunks.push(Buffer.from(value));
+      }
+    } finally { reader.releaseLock(); }
+    const text = Buffer.concat(chunks).toString('utf8');
+    let json;
+    try { json = JSON.parse(text); } catch { throw error('RUNTIME_PROTOCOL', 'Kimi returned a non-JSON response'); }
+    if (!response.ok || (!raw && json.code !== 0)) {
+      // Server errors can include prompts, account details and attachment paths.
+      // Stable machine code is sufficient for the receipt; do not echo bodies.
+      throw error('KIMI_API_' + (json.code ?? response.status), `Kimi rejected ${path.split('?')[0]} (code ${json.code ?? response.status})`);
+    }
+    return raw ? json : json.data;
+  }
+  async stop() {
+    if (this.sampler) clearInterval(this.sampler);
+    if (!this.child) return { exited: true, processesConfirmed: true, forced: false };
+    let inspected = this.processInspection, forced = false;
+    try { await this.sampleProcesses(); inspected = true; } catch { inspected = false; }
+    if (!this.closed && this.base) {
+      try { await this.request('/api/v1/shutdown', {}, { timeout: 2000 }); } catch { /* Exit below remains authoritative. */ }
+    }
+    let deadline = Date.now() + 3500;
+    while (!this.closed && Date.now() < deadline) await pause(30);
+    if (!this.closed) { forced = true; this.child.kill('SIGTERM'); }
+    deadline = Date.now() + 1500;
+    while (!this.closed && Date.now() < deadline) await pause(30);
+    if (!this.closed) { forced = true; this.child.kill('SIGKILL'); await Promise.race([this.exit, pause(1000)]); }
+    let live = [];
+    try { live = await this.sampleProcesses(); } catch { inspected = false; }
+    for (const row of live) {
+      forced = true;
+      try { process.kill(row.pid, 'SIGTERM'); } catch { /* Recheck by birth before escalation. */ }
+    }
+    if (live.length) await pause(200);
+    try { live = await this.sampleProcesses(); } catch { inspected = false; }
+    for (const row of live) { try { process.kill(row.pid, 'SIGKILL'); } catch { /* Final table determines certainty. */ } }
+    if (live.length) await pause(100);
+    try { live = await this.sampleProcesses(); } catch { inspected = false; }
+    return { exited: this.closed, processesConfirmed: inspected && (!this.child.pid || Boolean(this.spawnError) || this.observedRoot === true) && live.length === 0, forced,
+      observedProcesses: this.processes.size, exitCode: this.exitCode ?? null, signal: this.exitSignal ?? null };
+  }
+}
+
+function dereference(document, schema, seen = new Set()) {
+  if (!schema || typeof schema !== 'object') return {};
+  if (schema.$ref?.startsWith('#/') && !seen.has(schema.$ref)) {
+    seen.add(schema.$ref);
+    return dereference(document, schema.$ref.slice(2).split('/').reduce((node, key) => node?.[key], document), seen);
+  }
+  const properties = { ...(schema.properties || {}) };
+  for (const item of [...(schema.allOf || []), ...(schema.anyOf || []), ...(schema.oneOf || [])]) Object.assign(properties, dereference(document, item, new Set(seen)).properties);
+  return { ...schema, properties };
+}
+
+/** Match actual runtime contracts; no semantic-version inference is used. */
+export function inspectKimiSchemas(openapi, asyncapi, mode) {
+  const paths = ['/api/v1/meta', '/api/v1/sessions', '/api/v1/sessions/{session_id}', '/api/v1/sessions/{session_id}/profile',
+    '/api/v1/sessions/{session_id}/environment', '/api/v1/sessions/{session_id}/prompts',
+    '/api/v1/sessions/{session_id}/agents/{agent_id}/turns', '/api/v1/shutdown', '/api/v1/remote-control'];
+  if (!String(openapi.openapi).startsWith('3.') || paths.some(path => !openapi.paths?.[path])) throw error('UNSUPPORTED_SCHEMA', 'Kimi OpenAPI is missing a required local lifecycle route');
+  const properties = (path, method = 'post') => dereference(openapi, openapi.paths[path]?.[method]?.requestBody?.content?.['application/json']?.schema).properties || {};
+  const creation = properties('/api/v1/sessions');
+  const config = dereference(openapi, creation.agent_config).properties || {};
+  const prompt = properties('/api/v1/sessions/{session_id}/prompts');
+  const profile = dereference(openapi, properties('/api/v1/sessions/{session_id}/profile').agent_config).properties || {};
+  if (['model', 'thinking', 'permission_mode', 'swarm_mode', 'profile'].some(key => !config[key])
+      || ['content', 'prompt_id', 'disabled_tools'].some(key => !prompt[key])
+      || (mode === 'tower' && ['tower_mode', 'tower_base'].some(key => !profile[key]))) {
+    throw error('UNSUPPORTED_SCHEMA', 'Kimi request schemas do not describe the selected native profile');
+  }
+  const messages = new Set(Object.values(asyncapi.components?.messages || {}).map(item => item.name));
+  const required = ['subscribe', 'response', 'agent', 'task', 'task.list', 'task.stop', 'turns', 'turn.started', 'turn.ended', 'interaction', 'ping', 'pong'];
+  if (asyncapi.channels?.kimiCodeWebSocket?.address !== '/api/v1/ws' || required.some(name => !messages.has(name))) {
+    throw error('UNSUPPORTED_SCHEMA', 'Kimi AsyncAPI does not describe the required task and conversation lifecycle');
+  }
+  return { protocol: 'kimi-server/v1', openapiDigest: digest(openapi), asyncapiDigest: digest(asyncapi), inspectedRoutes: paths, inspectedMessages: required };
+}
+
+export class KimiSocket {
+  constructor(runtime, receive) { this.runtime = runtime; this.receive = receive; this.pending = new Map(); this.sequence = 0; this.lastMessage = Date.now(); }
+  async open(signal) {
+    this.socket = new WebSocket(this.runtime.base.replace('http:', 'ws:') + '/api/v1/ws', ['kimi-code.bearer.' + this.runtime.token]);
+    this.socket.addEventListener('message', event => {
+      this.lastMessage = Date.now();
+      try {
+        if (typeof event.data !== 'string' || Buffer.byteLength(event.data) > 2 * 1024 * 1024) throw error('WS_PROTOCOL', 'Kimi sent an invalid or oversized WebSocket frame');
+        const frame = JSON.parse(event.data);
+        if (frame.type === 'ping') { this.socket.send(JSON.stringify({ type: 'pong' })); return; }
+        if (frame.type === 'response') {
+          const waiter = this.pending.get(frame.request_id);
+          if (waiter) { clearTimeout(waiter.timer); this.pending.delete(frame.request_id); frame.code === 0 ? waiter.resolve(frame) : waiter.reject(error('KIMI_WS_' + frame.code, 'Kimi WebSocket command was rejected')); }
+          return;
+        }
+        this.receive(frame);
+      } catch (cause) { this.failure = cause; }
+    });
+    this.socket.addEventListener('close', () => {
+      this.closed = true;
+      for (const waiter of this.pending.values()) { clearTimeout(waiter.timer); waiter.reject(error('WS_CLOSED', 'The owned Kimi socket closed')); }
+      this.pending.clear();
+    });
+    this.socket.addEventListener('error', () => { this.failure = error('WS_ERROR', 'The authenticated Kimi socket failed'); });
+    const deadline = Date.now() + 5000;
+    while (this.socket.readyState !== WebSocket.OPEN) {
+      checkAbort(signal);
+      if (this.failure || this.closed) throw this.failure || error('WS_CLOSED', 'Kimi socket closed before admission');
+      if (Date.now() > deadline) throw error('WS_TIMEOUT', 'The authenticated Kimi socket did not open');
+      await pause(20);
+    }
+  }
+  command(type, fields = {}, timeout = 3000) {
+    if (this.socket?.readyState !== WebSocket.OPEN) return Promise.reject(error('WS_CLOSED', 'Kimi socket is unavailable'));
+    const request_id = `flywheel-${++this.sequence}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(request_id); reject(error('WS_TIMEOUT', 'Kimi did not acknowledge ' + type)); }, timeout);
+      this.pending.set(request_id, { resolve, reject, timer });
+      this.socket.send(JSON.stringify({ type, request_id, ...fields }));
+    });
+  }
+  check() {
+    if (this.failure) throw this.failure;
+    if (this.closed || Date.now() - this.lastMessage > 25_000) throw error('WS_LOST', 'Kimi conversation continuity was lost; the prompt will not be retried');
+  }
+  close() { this.socket?.close(); }
+}

package/dist/kimi-native-worker.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { runKimiWorker } from './kimi-native-bridge.mjs';
+
+const controller = new AbortController();
+let finished = false, inputError, request = { requestId: 'invalid-request' }, outputError;
+const cancel = () => { if (!finished) controller.abort(); };
+for (const name of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(name, cancel);
+process.stdout.on('error', () => { outputError = true; cancel(); });
+
+function write(frame) {
+  const line = JSON.stringify(frame) + '\n';
+  if (Buffer.byteLength(line) > 2 * 1024 * 1024) throw new Error('Kimi native receipt exceeds the output frame limit');
+  if (!outputError) process.stdout.write(line);
+}
+
+async function doctor() {
+  const child = spawn(process.env.FLYWHEEL_KIMI_BIN || 'kimi', ['--version'], { stdio: ['ignore', 'pipe', 'pipe'], detached: false });
+  let output = '', bytes = 0;
+  child.stdout.on('data', chunk => { bytes += chunk.length; if (bytes < 4096) output += chunk; });
+  child.stderr.on('data', () => {});
+  const timer = setTimeout(() => child.kill('SIGKILL'), 5000);
+  const ok = await new Promise(resolve => { child.once('error', () => resolve(false)); child.once('exit', code => resolve(code === 0)); });
+  clearTimeout(timer);
+  const version = output.match(/\b\d+\.\d+\.\d+(?:[-+][\w.-]+)?\b/)?.[0] || null;
+  write({ type: 'doctor', protocol: 1, available: ok && version !== null, cliVersion: version,
+    backendProtocol: 'kimi-server/v1', inferenceTested: false, nativeAdmission: 'requires-actual-server-schema-and-effective-session-probe', recoverySupported: false });
+  process.exitCode = ok && version ? 0 : 1;
+}
+
+async function input() {
+  return new Promise((resolve, reject) => {
+    let buffer = Buffer.alloc(0), admitted = false;
+    const fail = message => { inputError ||= message; clearTimeout(timer); controller.abort(); reject(new Error(message)); };
+    const timer = setTimeout(() => fail('No complete Kimi native request arrived within 10 seconds'), 10_000);
+    process.stdin.on('data', chunk => {
+      if (finished) return;
+      if (admitted) { if (chunk.toString('utf8').trim()) fail('Only one start request is accepted'); return; }
+      buffer = Buffer.concat([buffer, chunk]);
+      if (buffer.length > 1024 * 1024) { fail('Kimi native request exceeds the 1 MiB limit'); return; }
+      const end = buffer.indexOf(10);
+      if (end < 0) return;
+      try {
+        request = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, end)));
+        if (buffer.subarray(end + 1).toString('utf8').trim()) throw new Error();
+        admitted = true; clearTimeout(timer); resolve(request);
+      } catch { fail('Expected one valid UTF-8 JSON start request'); }
+    });
+    process.stdin.on('end', () => { if (!admitted) fail('Parent input closed before a start request'); else cancel(); });
+    process.stdin.on('error', () => fail('Parent input failed'));
+  });
+}
+
+try {
+  if (process.argv.includes('--doctor')) await doctor();
+  else {
+    let value;
+    try { value = await input(); } catch { value = request; }
+    const result = await runKimiWorker(value, { emit: write, signal: controller.signal,
+      stderr: message => process.stderr.write('[Kimi native] ' + message) });
+    if (inputError) {
+      result.status = 'error'; result.error = { code: 'INPUT_ERROR', message: inputError };
+      result.lifecycle.resumeCandidate = false;
+    }
+    finished = true;
+    write(result);
+    process.exitCode = result.status === 'ok' ? 0 : result.status === 'cancelled' ? 130 : 1;
+  }
+} catch {
+  // A broken consumer/oversized receipt must fail the outer transport gate;
+  // never emit a second plausible final after partial output.
+  process.exitCode = 1;
+} finally {
+  finished = true;
+  process.stdin.pause();
+  for (const name of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.removeListener(name, cancel);
+}

package/dist/kimi-tower-candidate.mjs

@@ -0,0 +1,227 @@
+// Trusted workspace transport. Tower receives a separate .git; Go still owns
+// validation, protected-path decisions, final commits and task acceptance.
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdtemp, mkdir, lstat, readFile, writeFile, readlink, symlink, chmod, readdir, realpath } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+const execute = promisify(execFile);
+const sha = value => createHash('sha256').update(value).digest('hex');
+const MAX_BYTES = 256 * 1024 * 1024;
+
+function fail(message) { return Object.assign(new Error(message), { code: 'INVALID_REQUEST' }); }
+
+export async function towerGit(cwd, args) {
+  // A host shell may itself be inside a temporary index/worktree operation.
+  // Those variables must not redirect the trusted copy or transfer commands.
+  const inherited = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  const { stdout } = await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.autocrlf=false', ...args], {
+    cwd, encoding: 'buffer', maxBuffer: MAX_BYTES,
+    env: { ...inherited, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null',
+      GIT_AUTHOR_NAME: 'Flywheel', GIT_AUTHOR_EMAIL: 'flywheel@localhost',
+      GIT_COMMITTER_NAME: 'Flywheel', GIT_COMMITTER_EMAIL: 'flywheel@localhost' },
+  });
+  return stdout;
+}
+
+/** Only the actual task's changing engine records are outside the candidate. */
+function runtimeTaskPath(name) {
+  if (['.sessions/', '.control/', 'reports/native/'].some(prefix => name.startsWith(prefix))) return true;
+  return /^(?:metrics\.jsonl|orchestrator\.(?:log|pid)|\.state\.lock|\.run\.lock|\.stop-request)$/.test(name)
+    || /^state\.json(?:\.tmp(?:[.-].*)?)?$/.test(name);
+}
+
+export function towerExcluded(path, cwd, taskDir) {
+  const parts = path.split('/');
+  if (parts.includes('.git') || parts[0] === '.tower') return true;
+  const ledger = relative(cwd, taskDir).split(sep).join('/');
+  if (ledger === '..' || ledger.startsWith('../') || isAbsolute(ledger) || (ledger && !path.startsWith(ledger + '/'))) return false;
+  return runtimeTaskPath(ledger ? path.slice(ledger.length + 1) : path);
+}
+
+async function externalTaskSnapshot(taskDir, byteLimit) {
+  const entries = []; let total = 0;
+  const walk = async (directory, prefix = '') => {
+    for (const name of (await readdir(directory)).sort()) {
+      const path = prefix + name, absolute = join(directory, name);
+      // Skip known runtime names before lstat: an atomic state/session rename
+      // may remove a temporary entry between readdir and metadata inspection.
+      if (runtimeTaskPath(path) || runtimeTaskPath(path + '/')) continue;
+      const stat = await lstat(absolute);
+      if (stat.isDirectory()) await walk(absolute, path + '/');
+      else if (stat.isFile()) {
+        total += stat.size;
+        if (total > byteLimit) throw fail('Tower source and external contract exceed the 256 MiB snapshot limit');
+        entries.push({ path, kind: 'file', executable: Boolean(stat.mode & 0o111), digest: sha(await readFile(absolute)) });
+      } else {
+        // A frozen external contract cannot be faithfully snapshotted by
+        // following an unconstrained symlink tree or a special-file stream.
+        throw fail('Tower external task contracts must contain regular files and directories');
+      }
+    }
+  };
+  await walk(taskDir);
+  return { path: resolve(taskDir), entries, digest: sha(JSON.stringify(entries)) };
+}
+
+async function noSymlinkAncestor(cwd, path) {
+  let cursor = cwd;
+  for (const segment of path.split('/').slice(0, -1)) {
+    cursor = join(cursor, segment);
+    try { if ((await lstat(cursor)).isSymbolicLink()) throw fail('Tower input traverses a symlink directory'); }
+    catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  }
+}
+
+/** HEAD plus exact tracked/unignored bytes, deletions, executable bits and links. */
+export async function towerSnapshot(cwd, taskDir, { externalContract = true } = {}) {
+  cwd = resolve(cwd);
+  const head = (await towerGit(cwd, ['rev-parse', '--verify', 'HEAD'])).toString().trim();
+  const top = (await towerGit(cwd, ['rev-parse', '--show-toplevel'])).toString().trim();
+  if (resolve(top) !== cwd) throw fail('Tower requires the repository root as its execution directory');
+  const paths = [...new Set((await towerGit(cwd, ['ls-files', '-c', '-o', '--exclude-standard', '-z'])).toString().split('\0').filter(Boolean))].sort();
+  const entries = [];
+  let total = 0;
+  for (const path of paths) {
+    if (isAbsolute(path) || path.split('/').some(part => part === '..' || part === '')) throw fail('Invalid Tower source path');
+    if (towerExcluded(path, cwd, taskDir)) continue;
+    await noSymlinkAncestor(cwd, path);
+    let stat;
+    try { stat = await lstat(join(cwd, path)); }
+    catch (error) { if (error.code === 'ENOENT') { entries.push({ path, kind: 'missing' }); continue; } throw error; }
+    if (stat.isSymbolicLink()) {
+      entries.push({ path, kind: 'link', target: await readlink(join(cwd, path)) });
+    } else if (stat.isFile()) {
+      total += stat.size;
+      if (total > MAX_BYTES) throw fail('Tower source exceeds the 256 MiB tracked/unignored snapshot limit');
+      entries.push({ path, kind: 'file', executable: Boolean(stat.mode & 0o111), digest: sha(await readFile(join(cwd, path))) });
+    } else {
+      throw fail('Tower input contains a submodule, directory entry or unsupported special file');
+    }
+  }
+  const location = relative(cwd, taskDir);
+  const outside = location === '..' || location.startsWith('..' + sep) || isAbsolute(location);
+  const contract = externalContract && outside ? await externalTaskSnapshot(taskDir, MAX_BYTES - total) : undefined;
+  return { version: 1, head, entries, ...(contract ? { externalContract: contract } : {}), digest: sha(JSON.stringify({ head, entries, externalContract: contract })) };
+}
+
+export async function createTowerCandidate(input) {
+  const source = await towerSnapshot(input.cwd, input.managed.taskDir);
+  const directory = await realpath(await mkdtemp(join(tmpdir(), 'flywheel-kimi-tower-')));
+  await chmod(directory, 0o700);
+  const path = join(directory, 'repository');
+  const branch = input.native.tower?.branch ?? `flywheel-tower-${sha(input.requestId).slice(0, 16)}`;
+  await towerGit(input.cwd, ['check-ref-format', '--branch', branch]);
+  // --no-local and --no-hardlinks avoid shared objects/admin data even when the
+  // source itself is a linked worktree. Nothing writes the source's .git.
+  await towerGit(input.cwd, ['clone', '--quiet', '--no-local', '--no-hardlinks', '--no-checkout', '--', input.cwd, path]);
+  await towerGit(path, ['remote', 'remove', 'origin']);
+  await towerGit(path, ['reset', '--mixed', source.head]);
+  for (const entry of source.entries) {
+    if (entry.kind === 'missing') continue;
+    const target = join(path, entry.path);
+    await mkdir(dirname(target), { recursive: true });
+    if (entry.kind === 'link') await symlink(entry.target, target);
+    else {
+      await writeFile(target, await readFile(join(input.cwd, entry.path)));
+      await chmod(target, entry.executable ? 0o755 : 0o644);
+    }
+  }
+  if ((await towerSnapshot(input.cwd, input.managed.taskDir)).digest !== source.digest) {
+    throw fail(`Tower source changed while copying; partial candidate retained at ${path}`);
+  }
+  await towerGit(path, ['add', '-A', '--', '.']);
+  await towerGit(path, ['commit', '--quiet', '--allow-empty', '-m', 'Snapshot Flywheel candidate for isolated Tower execution']);
+  const baseHead = (await towerGit(path, ['rev-parse', 'HEAD'])).toString().trim();
+  await towerGit(path, ['checkout', '-B', branch]);
+  const candidate = { kind: 'tower-repository', path, branch, baseHead, sourceHead: source.head,
+    sourceSnapshotDigest: source.digest, patchPath: join(directory, 'candidate.patch'), source };
+  await writeFile(join(directory, 'source-snapshot.json'), JSON.stringify(source), { mode: 0o600 });
+  return candidate;
+}
+
+/** Freeze the candidate only after the owned runtime is quiescent. */
+export async function freezeTowerCandidate(candidate, input) {
+  // Exclude Tower's administrative worktrees/comms, while retaining ordinary
+  // contract edits so Go's existing boundary guard can reject them explicitly.
+  const paths = (await towerGit(candidate.path, ['ls-files', '-c', '-o', '--exclude-standard', '-z'])).toString().split('\0').filter(Boolean);
+  const excluded = [...new Set(paths.filter(path => towerExcluded(path, input.cwd, input.managed.taskDir)))];
+  await towerGit(candidate.path, ['add', '-A', '--', '.', ':(exclude).tower', ...excluded.map(path => `:(exclude,literal)${path}`)]);
+  const patch = await towerGit(candidate.path, ['diff', '--cached', '--binary', '--full-index', candidate.baseHead, '--', '.', ':(exclude).tower', ...excluded.map(path => `:(exclude,literal)${path}`)]);
+  await writeFile(candidate.patchPath, patch, { mode: 0o600 });
+  const tree = (await towerGit(candidate.path, ['write-tree'])).toString().trim();
+  const snapshot = await towerSnapshot(candidate.path, join(candidate.path, relative(input.cwd, input.managed.taskDir)), { externalContract: false });
+  return { ...candidate, tree, patchDigest: sha(patch), snapshot };
+}
+
+/** Apply no candidate after uncertainty, to another role, or to a changed source. */
+export async function transferTowerCandidate(candidate, input, cleanupConfirmed) {
+  if (!cleanupConfirmed) throw fail('Tower candidate transfer requires confirmed runtime cleanup');
+  if (input.managed.role !== 'execute') return { applied: false, reason: 'role-does-not-own-workspace-transfer' };
+  const current = await towerSnapshot(input.cwd, input.managed.taskDir);
+  if (current.digest !== candidate.sourceSnapshotDigest) throw fail('Tower source or contract changed; candidate retained without transfer');
+  const patch = await readFile(candidate.patchPath);
+  if (sha(patch) !== candidate.patchDigest) throw fail('Tower candidate patch changed after freezing');
+  if (patch.length === 0) return { applied: true, empty: true, sourceSnapshotDigest: current.digest, afterDigest: current.digest };
+  await towerGit(input.cwd, ['apply', '--check', '--binary', '--', candidate.patchPath]);
+  // A second read catches edits made while checking the patch. There is no
+  // claim of an OS-wide lock over unrelated editors; the postcondition below
+  // also rejects a concurrent write instead of reporting a matching candidate.
+  if ((await towerSnapshot(input.cwd, input.managed.taskDir)).digest !== current.digest) throw fail('Tower source changed during transfer admission');
+  await towerGit(input.cwd, ['apply', '--binary', '--', candidate.patchPath]);
+  const after = await towerSnapshot(input.cwd, input.managed.taskDir);
+  const existing = entries => entries.filter(entry => entry.kind !== 'missing');
+  if (after.head !== current.head || after.externalContract?.digest !== candidate.source.externalContract?.digest
+      || JSON.stringify(existing(after.entries)) !== JSON.stringify(existing(candidate.snapshot.entries))) {
+    throw fail('Tower transfer postcondition differs from the frozen candidate; artifacts retained');
+  }
+  return { applied: true, empty: false, sourceSnapshotDigest: current.digest, afterDigest: after.digest };
+}
+
+export function towerCandidateReceipt(candidate, transfer) {
+  const { kind, path, branch, baseHead, sourceHead, sourceSnapshotDigest, patchPath, patchDigest, tree } = candidate;
+  return { kind, path, branch, baseHead, sourceHead, sourceSnapshotDigest, patchPath,
+    ...(candidate.source.externalContract ? { externalContractDigest: candidate.source.externalContract.digest } : {}),
+    ...(patchDigest ? { patchDigest, tree } : {}), ...(transfer ? { transfer } : {}) };
+}
+
+/** Remap exact project path references, never substrings in another path/URL. */
+export function towerPrompt(input, candidate, declaredCwd = input.cwd) {
+  const source = input.cwd, target = candidate.path;
+  // Admission has already resolved the declared directory to source. Match
+  // either spelling in the original prompt, preferring a longer prefix at the
+  // same position; never re-scan text inserted from the candidate path.
+  // Removing trailing separators/dot components is equivalent for a directory;
+  // do not collapse '..', whose meaning can change across a symlink.
+  const prefixes = [...new Set([source, declaredCwd, declaredCwd.replace(/(?:\/+\.?)+$/, '') || '/'])].sort((a, b) => b.length - a.length);
+  const urls = [...input.prompt.matchAll(/(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\/[^\s"'`<>]+/g)]
+    .map(match => ({ start: match.index, end: match.index + match[0].length }));
+  let cursor = 0, urlIndex = 0, mapped = '', replacements = 0;
+  for (;;) {
+    let index = -1;
+    for (const value of prefixes) {
+      const position = input.prompt.indexOf(value, cursor);
+      if (position >= 0 && (index < 0 || position < index)) index = position;
+    }
+    if (index < 0) { mapped += input.prompt.slice(cursor); break; }
+    while (urls[urlIndex]?.end <= index) urlIndex++;
+    const inUrl = urls[urlIndex] && index >= urls[urlIndex].start && index < urls[urlIndex].end;
+    const before = index === 0 ? '' : input.prompt[index - 1];
+    const startsPath = !inUrl && (before === '' || /[\s"'`([{=:]/.test(before));
+    const prefix = startsPath && prefixes.find(value => {
+      const after = input.prompt[index + value.length] || '';
+      return input.prompt.startsWith(value, index) && (after === '' || /[\/\s"'`)\]},;:#?]/.test(after));
+    });
+    if (!prefix) { mapped += input.prompt.slice(cursor, index + 1); cursor = index + 1; continue; }
+    mapped += input.prompt.slice(cursor, index) + target;
+    replacements++;
+    cursor = index + prefix.length;
+  }
+  const prompt = `Flywheel Tower candidate directory: ${target}\n` +
+    'Run project edits and Git operations in this independent repository. External task contract files are read-only evidence at their supplied paths. ' +
+    'Flywheel transfers this candidate after cleanup and owns validation, review and final commits.\n\n' + mapped;
+  return { prompt, mapping: { sourceCwd: source, declaredSourceCwd: declaredCwd, candidateCwd: target, replacements,
+    rule: 'bounded-literal-absolute-path-prefix', originalPromptDigest: sha(input.prompt), effectivePromptDigest: sha(prompt), filesystemSandbox: false } };
+}

package/dist/machine-worker.mjs

@@ -8,10 +8,24 @@ function identifier(value) {
   return typeof value === 'string' && value.trim() !== '' && value.length <= 256 && !value.includes('\0');
 }
 
+/** Host-owned attribution, not provider arguments. External callers cannot supply leases. */
+export function validateNativeAdmission(value, requestId, WorkerError) {
+  if (value === undefined) return;
+  const fields = ['version', 'runId', 'invocationId', 'role', 'scope', 'candidateId', 'channel', 'taskDir'];
+  const text = value => typeof value === 'string' && value.trim() !== '' && value.length <= 4096 && !value.includes('\0');
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.version !== 1 ||
+      Object.keys(value).some(key => !fields.includes(key)) || value.invocationId !== requestId ||
+      !['invocationId', 'role', 'scope', 'channel', 'taskDir'].every(key => text(value[key])) ||
+      typeof value.runId !== 'string' || value.runId.length > 4096 || value.runId.includes('\0') ||
+      (value.candidateId !== undefined && !text(value.candidateId)) || !isAbsolute(value.taskDir)) {
+    throw new WorkerError('INVALID_REQUEST', 'The managed native identity must match this request and contain only host attribution fields');
+  }
+}
+
 /** Recovery carries only the old non-secret binding, never a prompt. */
 export function recoveryRequest(value, WorkerError) {
   const keys = new Set(['type', 'protocol', 'requestId', 'runId', 'recoveryDirectory', 'original']);
-  const originalKeys = new Set(['cwd', 'model', 'reasoningEffort', 'permissionMode', 'threadMode', 'threadId']);
+  const originalKeys = new Set(['cwd', 'model', 'reasoningEffort', 'permissionMode', 'threadMode', 'threadId', 'native', 'nativeOperation', 'managed']);
   const o = value?.original;
   if (!value || typeof value !== 'object' || Array.isArray(value) || value.type !== 'recover' || value.protocol !== 3 ||
       Object.keys(value).some(key => !keys.has(key)) || !identifier(value.requestId) || !identifier(value.runId) ||
@@ -23,13 +37,16 @@ export function recoveryRequest(value, WorkerError) {
       (o.threadId !== undefined && (o.threadMode !== 'persistent' || !identifier(o.threadId)))) {
     throw new WorkerError('INVALID_REQUEST', 'Expected a protocol 3 read-only recovery request with the original non-secret binding');
   }
+  validateNativeAdmission(o.managed, value.requestId, WorkerError);
   // No cwd resolution, login, runMachine, thread/resume or model request here.
   return { protocol: 1, requestId: value.requestId, runId: value.runId, recoveryDirectory: value.recoveryDirectory };
 }
 
 // Parent lifeline and bounded transport; adapters own backend semantics.
 export async function runMachineWorker({ ADAPTER, LIMITS, WorkerError, loadAdapter, machineRequest, doctorResult,
-  label, commandName, attestAdmission = false, runtimeOptions = () => ({}) }) {
+  label, commandName, attestAdmission = false, runtimeOptions = () => ({}),
+  invokeAdapter = (api, request, options) => api.runMachine(request, options),
+  recoverAdapter = (api, request) => api.recoverMachine(request) }) {
   const controller = new AbortController();
   let cancelledBy, inputFailure, outputFailure, requestId = 'invalid-request', protocol = 1, finished = false, adapterInvoked = false;
   let recovery = false, pendingAck, lifecycleSequence = 0, lifecycleRunId, lifecycleBytes = 0;
@@ -190,7 +207,7 @@ export async function runMachineWorker({ ADAPTER, LIMITS, WorkerError, loadAdapt
       }
       if (recovery) {
         const query = recoveryRequest(value, WorkerError);
-        const evidence = await api.recoverMachine(query);
+        const evidence = await recoverAdapter(api, query, value.original);
         finished = true;
         lifeline.stop();
         const error = inputFailure || outputFailure;
@@ -211,13 +228,30 @@ export async function runMachineWorker({ ADAPTER, LIMITS, WorkerError, loadAdapt
               outputFailure ??= new WorkerError('OUTPUT_LIMIT', label + ' progress exceeded the 1 MiB stream limit');
               controller.abort();
             } else write(frame);
+          },
+          onNativeEvent(event) {
+            if (controller.signal.aborted) return;
+            if (!event || typeof event !== 'object' || Array.isArray(event) || event.version !== 1 ||
+                !Number.isSafeInteger(event.sequence) || event.sequence < 1 || !identifier(event.id) ||
+                !identifier(event.kind) || typeof event.state !== 'string' ||
+                (event.parentId !== null && !identifier(event.parentId))) {
+              outputFailure ??= new WorkerError('INVALID_NATIVE_EVENT', 'The adapter emitted invalid native child metadata');
+              controller.abort(); return;
+            }
+            const frame = { protocol, type: 'native-event', requestId, adapter: ADAPTER, native: event,
+              ...(value.managed === undefined ? {} : { managed: value.managed }) };
+            progressBytes += Buffer.byteLength(JSON.stringify(frame) + '\n');
+            if (progressBytes > LIMITS.progressBytes) {
+              outputFailure ??= new WorkerError('OUTPUT_LIMIT', label + ' native evidence exceeded the 1 MiB stream limit');
+              controller.abort();
+            } else write(frame);
           } };
         adapterInvoked = true;
-        const receipt = await api.runMachine(request, options);
+        const receipt = await invokeAdapter(api, request, options);
         finished = true;
         lifeline.stop();
         const error = inputFailure || outputFailure;
-        if (outputFailure?.code === 'OUTPUT_LIMIT') outputFailure = undefined;
+        if (['OUTPUT_LIMIT', 'INVALID_NATIVE_EVENT'].includes(outputFailure?.code)) outputFailure = undefined;
         write({ protocol, type: 'result', requestId, adapter: ADAPTER, receipt,
           error: error ? { code: error.code, message: error.message } : null });
         process.exitCode = receipt.ok && !error && !controller.signal.aborted ? 0 : 1;