@karma42/agent 0.1.0-beta.1 → 0.1.0-beta.10

package/src/state.mjs

@@ -1,15 +1,22 @@
-import { constants, lstatSync, realpathSync, fstatSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, renameSync, unlinkSync, readdirSync } from 'node:fs';
-import { join, dirname, basename, resolve } from 'node:path';
-import { homedir } from 'node:os';
+import { constants, lstatSync, realpathSync, fstatSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { join, dirname, basename, resolve, relative, isAbsolute } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
 
-export const defaultHome = () => join(homedir(), '.karma42', 'connections');
 export function canonicalPath(value) {
   let path = resolve(value);
   const tail = [];
   while (!lstatExists(path)) { tail.unshift(basename(path)); path = dirname(path); }
   return join(realpathSync(path), ...tail);
 }
+// Physical paths matter: a symlink spelling must not allow credentials inside a checkout.
+export function assertStateOutsideWorkspace(home, folder) {
+  const state = canonicalPath(home), workspace = canonicalPath(folder);
+  const inside = (root, path) => {
+    const part = relative(root, path);
+    return part === '' || (part !== '..' && !part.startsWith('../') && !isAbsolute(part));
+  };
+  if (inside(workspace, state) || inside(state, workspace)) throw new Error('Private connection state and the project workspace must be separate sibling paths. Choose storage outside the checkout.');
+}
 export const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 export function privateDir(path) {
   try { mkdirSync(path, { mode: 0o700 }); }
@@ -23,14 +30,20 @@ export function ensureHome(home) {
   privateDir(home);
 }
 export function readPrivate(path, json = false) {
-  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
-  try {
-    const stat = fstatSync(fd);
-    if (!stat.isFile() || (stat.mode & 0o077) || stat.nlink !== 1) throw new Error('Connection files must be private regular files.');
-    const value = readFileSync(fd, 'utf8');
-    if (!json) return value;
-    try { return JSON.parse(value); } catch { throw new Error('Invalid private connection record. Restore its backup or reconnect.'); }
-  } finally { closeSync(fd); }
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const stat = fstatSync(fd);
+      if (!stat.isFile() || (stat.mode & 0o077) || stat.nlink > 1) throw new Error('Connection files must be private regular files.');
+      // Atomic replacement can unlink the inode between open and fstat. Reopen
+      // the named record; never read an unlinked inode or relax private-file checks.
+      if (stat.nlink === 0 && attempt < 2) continue;
+      if (stat.nlink !== 1) throw new Error('Connection files must be private regular files.');
+      const value = readFileSync(fd, 'utf8');
+      if (!json) return value;
+      try { return JSON.parse(value); } catch { throw new Error('Invalid private connection record. Restore its backup or reconnect.'); }
+    } finally { closeSync(fd); }
+  }
 }
 export function writePrivate(path, value) {
   try {
@@ -54,9 +67,6 @@ export function connectionDir(home, id) {
 }
 export function save(dir, record) { writePrivate(join(dir, 'connection.json'), record); }
 export function load(dir) { return readPrivate(join(dir, 'connection.json'), true); }
-export function binding(record) {
-  return digest([record.schema, record.id, record.service, record.agentId, record.agentName, record.repo, record.folder, record.provider, record.mode, record.copyVersion, record.runtimePolicy, record.bundleHash]);
-}
 export function withLock(dir, action) {
   const lock = join(dir, 'operation.lock');
   let fd;
@@ -68,26 +78,4 @@ export function withLock(dir, action) {
   writeFileSync(fd, `${process.pid}\n`); closeSync(fd);
   return Promise.resolve().then(action).finally(() => unlinkSync(lock));
 }
-export function list(home) {
-  if (!lstatExists(home)) return [];
-  ensureHome(home);
-  const result = [];
-  for (const project of readdirSync(home)) {
-    if (!/^[a-f0-9]{64}$/.test(project)) continue;
-    privateDir(join(home, project));
-    for (const agent of readdirSync(join(home, project))) {
-      if (!/^[\w-]{1,200}$/.test(agent)) continue;
-      const dir = connectionDir(home, `${project}/${agent}`);
-      if (lstatExists(join(dir, 'connection.json'))) result.push(load(dir));
-      else if (lstatExists(join(dir, 'pending-pair.json'))) {
-        const { token, ...pending } = readPrivate(join(dir, 'pending-pair.json'), true);
-        result.push({ ...pending, phase: 'paired', consent: null });
-      }
-    }
-  }
-  return result;
-}
 export function lstatExists(path) { try { lstatSync(path); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } }
-export function cleanEnvironment(input = process.env) {
-  return Object.fromEntries(Object.entries(input).filter(([key]) => !key.startsWith('PILOT_')));
-}

package/src/system.mjs

@@ -1,17 +1,8 @@
-import { spawnSync, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
-import { doctor } from './doctor.mjs';
-import { cleanEnvironment, privateDir, readPrivate, writePrivate } from './state.mjs';
 
-export function run(command, args, cwd) {
-  const result = spawnSync(command, args, { cwd, shell: false, encoding: 'utf8', timeout: 120_000, maxBuffer: 1024 * 1024, env: cleanEnvironment(), windowsHide: true });
-  // Do not print raw subprocess errors/output: they can contain credentials or terminal escapes.
-  if (result.error || result.status !== 0) return null;
-  return result.stdout.trim();
-}
 export async function request(service, route, body, token) {
   let response;
   try {
@@ -20,9 +11,9 @@ export async function request(service, route, body, token) {
       headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
       body: JSON.stringify(body),
     });
-  } catch { throw new Error(route === 'exchange' ? 'Pairing reply unavailable. The code may have been consumed; generate a fresh code in My agents.' : 'Could not update the readiness check. Retry prepare when the service is available.'); }
+  } catch { throw new Error('Browser pairing reply unavailable. Retry the same pending connection.'); }
   if (!response.ok) {
-    if (response.status === 401 || response.status === 403) throw new Error(route === 'exchange' ? 'The setup code is expired, invalid or no longer authorized. Generate a fresh code in My agents.' : 'This connection is no longer authorized. Check membership and reconnect in My agents.');
+    if (response.status === 401 || response.status === 403) throw new Error('This connection is no longer authorized. Check membership and reconnect in My agents.');
     if (response.status === 429) throw new Error('Too many requests. Wait before retrying.');
     throw new Error('The project service could not complete this request.');
   }
@@ -35,7 +26,7 @@ export function verifyBundle() {
   let manifest;
   try { manifest = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8')); }
   catch { throw new Error('Packaged runtime missing. Build or reinstall this package before preparing an agent.'); }
-  const names = ['runner.mjs', 'control-v2.mjs', 'runtime.mjs', 'launcher.mjs', 'claude-settings.json', 'AGENT_PROMPT_V2.md', 'providers.mjs'];
+  const names = ['control-v2.mjs', 'work-controller.mjs', 'providers.mjs', 'claude-settings.json', 'AGENT_PROMPT_V2.md', 'project-tools.json'];
   if (Object.keys(manifest.files ?? {}).sort().join() !== [...names].sort().join()) throw new Error('Invalid packaged runtime manifest.');
   const files = {};
   for (const name of names) {
@@ -45,31 +36,4 @@ export function verifyBundle() {
   }
   return { files, fingerprint: createHash('sha256').update(JSON.stringify(manifest.files)).digest('hex') };
 }
-export function installBundle(state) {
-  const bundle = verifyBundle();
-  const kit = join(state, 'kit'); privateDir(kit);
-  for (const [name, content] of Object.entries(bundle.files)) writePrivate(join(kit, name), content.toString('utf8'));
-  return bundle.fingerprint;
-}
-export function verifyInstalled(state) {
-  const bundle = verifyBundle();
-  for (const [name, content] of Object.entries(bundle.files)) {
-    if (readPrivate(join(state, 'kit', name)) !== content.toString('utf8')) throw new Error('Prepared runtime files changed. Run prepare before starting.');
-  }
-  return bundle.fingerprint;
-}
-export function launch(dir, record) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [fileURLToPath(new URL('./supervisor.mjs', import.meta.url)), dir], {
-      shell: false, stdio: 'inherit', env: cleanEnvironment(),
-    });
-    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
-    let stopping = false;
-    const handlers = Object.fromEntries(signals.map(signal => [signal, () => { stopping = true; child.kill(signal); }]));
-    for (const [signal, handler] of Object.entries(handlers)) process.on(signal, handler);
-    function cleanup() { for (const [signal, handler] of Object.entries(handlers)) process.off(signal, handler); }
-    child.once('error', () => { cleanup(); reject(new Error('Could not launch the foreground supervisor.')); });
-    child.once('exit', (code, signal) => { cleanup(); resolve(stopping && signal ? 0 : code ?? 1); });
-  });
-}
-export const system = { doctor, run, request, installBundle, verifyBundle, verifyInstalled, launch, now: () => new Date().toISOString() };
+export const system = { request, verifyBundle, now: () => new Date().toISOString() };

package/src/version.mjs

@@ -0,0 +1 @@
+export const VERSION = '0.1.0-beta.10';

package/src/worker-recovery.mjs

@@ -0,0 +1,82 @@
+import { join } from 'node:path';
+import { lstatExists, readPrivate, writePrivate } from './state.mjs';
+import { claimWorkerCheckout } from './checkout-ownership.mjs';
+
+const uuid = value => typeof value === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value);
+const terminal = new Set(['stopped', 'completed', 'startup_failed']);
+const phases = new Set(['starting', 'working', 'waiting', 'paused', 'blocked', 'stopping', 'stopped', 'completed', 'startup_failed']);
+const pathFor = dir => join(dir, 'worker-mission.json');
+const bounded = (value, max) => typeof value === 'string' && value.length > 0 && value.length <= max;
+const ownerAlive = pid => {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code !== 'ESRCH'; } // Unknown/EPERM/reused PID: do not take over.
+};
+
+export function readWorkerMission(dir, record) {
+  const path = pathFor(dir);
+  if (!lstatExists(path)) return null;
+  const value = readPrivate(path, true);
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.schema !== 1 || !uuid(value.id) || value.connectionId !== record.id || value.service !== record.service
+    || value.repo !== record.repo || !uuid(value.workerDir) || !Number.isSafeInteger(value.ownerPid) || value.ownerPid <= 0
+    || !['claude', 'codex'].includes(value.client) || !bounded(value.folder, 4000) || !value.folder.startsWith('/')
+    || !bounded(value.scope, 4000) || !(value.model === null || (typeof value.model === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,149}$/.test(value.model)))
+    || !Number.isSafeInteger(value.startedAt) || !Number.isSafeInteger(value.deadline) || value.deadline <= value.startedAt
+    || value.deadline - value.startedAt < 15 * 60000 || value.deadline - value.startedAt > 240 * 60000
+    || (value.deadline - value.startedAt) % (15 * 60000) !== 0 || !phases.has(value.phase)
+    || !/^[a-f0-9]{64}$/.test(value.instructionsHash ?? '')
+    || !Array.isArray(value.steering) || value.steering.length > 64
+    || value.steering.some(item => !item || typeof item !== 'object' || !Number.isSafeInteger(item.id) || item.id < 1 || !bounded(item.message, 2000) || !['received', 'applied'].includes(item.state))
+    || new Set(value.steering.map(item => item.id)).size !== value.steering.length
+    || !Number.isSafeInteger(value.sequence) || value.sequence < Math.max(0, ...value.steering.map(item => item.id))
+    || typeof value.turnInFlight !== 'boolean' || !Array.isArray(value.inflightSteering)
+    || value.inflightSteering.some(id => !value.steering.some(item => item.id === id))) {
+    throw new Error('Worker recovery record does not match this approved connection or is invalid. Inspect private storage before starting work.');
+  }
+  return value;
+}
+
+export function workerRecoveryStatus(dir, record, now = Date.now()) {
+  const mission = readWorkerMission(dir, record);
+  if (!mission || terminal.has(mission.phase)) return null;
+  return { recovery_ref: mission.id, state: ownerAlive(mission.ownerPid) ? 'supervisor_present' : now >= mission.deadline ? 'expired' : 'approval_required',
+    client: mission.client, model: mission.model, folder: mission.folder, scope: mission.scope,
+    started_at: mission.startedAt, deadline_at: mission.deadline, previous_phase: mission.phase,
+    previous_turn_outcome: mission.turnInFlight ? 'unknown' : 'not_in_flight',
+    steering: mission.steering.map(({ id, state }) => ({ id, state: mission.turnInFlight && mission.inflightSteering.includes(id) ? 'unconfirmed' : state })),
+    note: 'Saved local mission, not live model status. Recovery needs explicit approval, a verified project connection and exclusive checkout ownership. An unfinished turn must reconcile existing changes before repeating actions.' };
+}
+
+export function selectWorkerMission(dir, record, options, now = Date.now()) {
+  const mission = readWorkerMission(dir, record);
+  if (options.recovery_ref !== undefined) {
+    if (!mission || terminal.has(mission.phase) || options.recovery_ref !== mission.id) throw new Error('Worker recovery reference is no longer available. Read worker status again.');
+    if (ownerAlive(mission.ownerPid)) throw new Error('Worker recovery cannot take over a supervisor that may still be running. No process was stopped.');
+    if (now >= mission.deadline) throw new Error('Worker recovery deadline has expired. Approve a new work session instead.');
+    if (options.minutes !== undefined || options.client !== mission.client || (options.model ?? null) !== mission.model
+      || options.scope !== mission.scope || options.folder !== mission.folder) throw new Error('Worker recovery must use the saved client, model, scope and folder, without minutes. The original deadline cannot be extended.');
+    return mission;
+  }
+  if (mission && !terminal.has(mission.phase) && (ownerAlive(mission.ownerPid) || now < mission.deadline)) {
+    throw new Error('Worker recovery is pending for this connection. Read get_project_worker and explicitly recover its saved mission instead of replacing it.');
+  }
+  return null;
+}
+
+export function saveWorkerMission(dir, record, mission, expectedId) {
+  const existing = readWorkerMission(dir, record);
+  if ((existing?.id ?? null) !== expectedId) throw new Error('Worker recovery record changed during startup or work. No replacement mission was overwritten.');
+  writePrivate(pathFor(dir), mission);
+}
+
+export async function cancelWorkerRecovery(dir, record, claimCheckout = claimWorkerCheckout) {
+  const mission = readWorkerMission(dir, record);
+  if (!mission || terminal.has(mission.phase)) return { state: 'not_started', active: false };
+  if (ownerAlive(mission.ownerPid)) throw new Error('Worker recovery cannot cancel a supervisor that may still be running. Stop it in its owning session. No process was stopped.');
+  // Cancellation is a record change, not permission to kill an orphan. The same
+  // checkout arbitration must prove no surviving native process owns these files.
+  const claim = await claimCheckout({ folder: mission.folder, agentId: record.agentId, project: record.service });
+  try {
+    saveWorkerMission(dir, record, { ...mission, phase: 'stopped' }, mission.id);
+    return { state: 'stopped', active: false, mission_ref: mission.id, note: 'Saved mission cancelled. No native process was started or killed; existing contributions remain.' };
+  } finally { claim.release(); }
+}

package/src/worker-runtime.mjs

@@ -0,0 +1,328 @@
+import { spawnSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { createWorkController } from '../runtime/work-controller.mjs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createProvider, CLAUDE_ALLOWED_TOOLS } from '../runtime/providers.mjs';
+import { VERSION } from './version.mjs';
+import { canonicalPath, connectionDir, digest, ensureHome, lstatExists, readPrivate, writePrivate, assertStateOutsideWorkspace } from './state.mjs';
+import { sessionHome } from './session.mjs';
+import { verifyBundle } from './system.mjs';
+import { claimWorkerCheckout } from './checkout-ownership.mjs';
+import { readWorkerMission, selectWorkerMission, saveWorkerMission } from './worker-recovery.mjs';
+import { spawnSupervisedModel } from './model-guard.mjs';
+
+const workerBridges = new WeakMap();
+function workerBridge(bridge) {
+  let listening = workerBridges.get(bridge);
+  if (!listening) {
+    listening = Promise.resolve().then(() => bridge.listen());
+    workerBridges.set(bridge, listening);
+    listening.catch(() => { if (workerBridges.get(bridge) === listening) workerBridges.delete(bridge); });
+  }
+  return listening;
+}
+const bounded = (value, label, max = 2000) => {
+  if (typeof value !== 'string' || !value.trim() || value.length > max || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value)) throw new Error(`Provide a clear ${label}.`);
+  return value.trim();
+};
+const faultCodes = new Set(['rate_limited', 'project_busy', 'internal_error', 'unauthorized', 'forbidden', 'run_superseded', 'runtime_update_required', 'runtime_conflict', 'run_active', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN']);
+const contactIsTransient = failure => failure.fatal === false || failure.name === 'TimeoutError'
+  || (failure instanceof TypeError && failure.message === 'fetch failed')
+  || ['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN'].includes(failure.cause?.code);
+export function validateWorkerWorkspace(folder, record) {
+  if (typeof folder !== 'string' || !folder.startsWith('/')) throw new Error('Choose a separate absolute Git checkout or worktree for the worker.');
+  const cwd = canonicalPath(folder);
+  try { assertStateOutsideWorkspace(record.folder, cwd); } catch { throw new Error('Use separate sibling checkouts or worktrees so the worker and current chat do not edit the same files.'); }
+  const git = args => { const result = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 15000, maxBuffer: 16384, env: { PATH: process.env.PATH, HOME: process.env.HOME, GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_NOSYSTEM: '1' } }); return result.status === 0 ? result.stdout.trim() : null; };
+  const root = git(['rev-parse', '--show-toplevel']), origin = git(['remote', 'get-url', 'origin']);
+  if (!root || canonicalPath(root) !== cwd || !origin || origin.replace(/\.git$/, '').replace(/\/$/, '') !== record.repo.replace(/\/$/, '')) throw new Error('The worker folder must be a Git repository root with the project’s HTTPS GitHub origin. No repository was changed.');
+  return cwd;
+}
+
+export function createLocalWorkerAdapter({ client, model, folder, stateDir, bridge, scope, providerFactory = createProvider, spawnModel = spawnSupervisedModel }) {
+  verifyBundle(); ensureHome(stateDir);
+  const configuredEndpoint = client === 'claude' ? process.env.ANTHROPIC_BASE_URL : process.env.OPENAI_BASE_URL;
+  if (configuredEndpoint && (() => { try { const endpoint = new URL(configuredEndpoint); return endpoint.protocol !== 'https:' || endpoint.origin !== (client === 'claude' ? 'https://api.anthropic.com' : 'https://api.openai.com'); } catch { return true; } })()) throw new Error('This worker adapter cannot preserve your custom API endpoint. Use the current-chat MCP mode rather than silently switching your model backend.');
+  const runtime = fileURLToPath(new URL('../runtime/', import.meta.url));
+  const settings = { claude: 'claude', codex: 'codex', model, repoDir: folder, permissionMode: 'acceptEdits', allowedTools: CLAUDE_ALLOWED_TOOLS, passEnv: '', turnBudgetUsd: 0 };
+  const provider = providerFactory(client, settings);
+  provider.preflight();
+  const instructions = readPrivate(join(stateDir, 'instructions.md'));
+  const promptHash = digest(instructions);
+  const sessionFile = join(stateDir, 'model-session.json');
+  let session = lstatExists(sessionFile) ? readPrivate(sessionFile, true) : null;
+  if (session && (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(session.id ?? '') || session.provider !== client || session.repoDir !== folder || session.promptHash !== promptHash)) throw new Error('Saved worker model session belongs to different approved work. Use a fresh work session.');
+  return {
+    async run({ prompt, signal, deadline, onActivity, onMetadata, onPermission, onModelStarting, onModelStarted, recovering = false }) {
+      if (signal.aborted) return Promise.resolve({ interrupted: true });
+      const resuming = provider.canResume(session);
+      session ??= provider.newSession(promptHash, folder);
+      const save = () => writePrivate(sessionFile, { ...session, provider: client, promptHash, repoDir: folder });
+      save();
+      const invocation = provider.invocation({ prompt, instructionsFile: join(stateDir, 'instructions.md'), settingsFile: join(runtime, 'claude-settings.json'), mcpConfig: join(stateDir, 'mcp.json'), bridge, session, resuming, repoDir: folder, clientVersion: VERSION });
+      onModelStarting?.();
+      const result = await new Promise(resolve => {
+        const child = spawnModel(invocation.command, invocation.args, { cwd: folder, env: provider.environment(invocation.env), stdio: [invocation.rpc ? 'pipe' : 'ignore', 'pipe', 'pipe'], windowsHide: true, deadline });
+        let done = false, interrupted = false, persistenceFault = false, killTimer, forceTimer, stderr = '';
+        child.on('message', value => { if (value?.guardStop === 'deadline') interrupted = true; });
+        if (child.pid) { try { onModelStarted?.(child.pid); } catch { persistenceFault = true; child.kill('SIGTERM'); forceTimer = setTimeout(() => child.kill('SIGKILL'), 8000); } }
+        const stream = provider.collector({ rpc: invocation.rpc, log: () => {}, action: onActivity, metadata: onMetadata, permission: onPermission, session: id => { session.id = id; try { save(); } catch { persistenceFault = true; child.kill('SIGTERM'); } } });
+        // The supervised spawn maps force-stop requests to native group cleanup;
+        // the guard remains alive until that cleanup has completed.
+        const interrupt = () => { interrupted = true; if (invocation.rpc) stream.interrupt(); else child.kill('SIGINT'); killTimer = setTimeout(() => child.kill('SIGTERM'), 3000); forceTimer = setTimeout(() => child.kill('SIGKILL'), 8000); };
+        signal.addEventListener('abort', interrupt, { once: true });
+        const finish = code => {
+          if (done) return; done = true; stream.end(); stream.cleanup?.(); clearTimeout(killTimer); clearTimeout(forceTimer); signal.removeEventListener('abort', interrupt);
+          if (stream.sessionId) session.id = stream.sessionId;
+          if (stream.tokenTotals) session.tokenTotals = stream.tokenTotals;
+          try { save(); } catch { persistenceFault = true; }
+          const diagnostics = `${stderr} ${stream.report?.errors?.join(' ') ?? ''} ${stream.report?.result ?? ''}`;
+          const failureCode = persistenceFault ? 'private_state_failure' : /(?:not logged in|authentication|unauthorized|login required|invalid api key)/i.test(diagnostics) ? 'authentication_required' : /(?:permission denied|not permitted|approval required|tool.*refused)/i.test(diagnostics) ? 'permission_required' : 'local_execution_failure';
+          resolve({ missingSession: !interrupted && !persistenceFault && Boolean(provider.missingSession?.(stderr)), failureCode, retryable: failureCode === 'local_execution_failure', interrupted, failed: !interrupted && (persistenceFault || (invocation.rpc && stream.closed && stream.report ? 0 : code) !== 0 || stream.report?.is_error || !stream.report), text: stream.report?.result ?? stream.finalText ?? '', usage: {
+            ...provider.usage(stream.report, stream.init), toolCalls: stream.toolCalls,
+            toolScope: interrupted || stream.truncated || !stream.report || stream.report.is_error ? 'partial' : 'provider-stream',
+          } });
+        };
+        child.stdout.setEncoding('utf8'); child.stdout.on('data', chunk => { try { stream.feed(chunk); } catch { persistenceFault = true; child.kill('SIGTERM'); } });
+        child.stderr.setEncoding('utf8'); child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-16384); }); child.once('error', () => finish(1)); child.once('close', finish);
+        if (invocation.rpc) { child.stdin.on('error', () => {}); stream.attach(child); }
+        if (signal.aborted) interrupt();
+      });
+      if (result.missingSession && !recovering && !signal.aborted) { session = null; rmSync(sessionFile, { force: true }); return this.run({ prompt, signal, deadline, onActivity, onMetadata, onPermission, onModelStarting, onModelStarted, recovering: true }); }
+      if (result.missingSession) { result.failed = true; result.retryable = false; result.failureCode = 'session_recovery_failed'; }
+      delete result.missingSession; return result;
+    },
+  };
+}
+
+// A lightweight in-process supervisor, owned by the existing MCP transport and run.
+// Waiting never holds a coding model open. Each native turn has a bounded process
+// guard; loss of this controller stops that turn rather than leaving it orphaned.
+export function createProjectWorker({ control, bridge, record, stateDir = connectionDir(sessionHome(), record.id), onState = () => {}, now = Date.now, setTimer = setInterval, clearTimer = clearInterval, adapterFactory = createLocalWorkerAdapter, validateWorkspace = validateWorkerWorkspace, claimCheckout = claimWorkerCheckout, pollMs = 1000, quietIntervalMs = 15 * 60000, random = Math.random, instructionsText } = {}) {
+  let phase = 'idle', deadline = null, startedAt = null, adapter, folder, client, scope, turn, abort, timer, stopRequested = false, scheduler, sendDeferred = false, lastResult = '', error = null, sequence = 0, workerConnection, activity = null;
+  const steering = [];
+  let requestedModel = null, actualModel = null, lastUsage = null, denialCount = 0, lastDenialAt = null;
+  let usageSequence = 0;
+  let ownership;
+  let failureInfo = null, contactRetryAt = null;
+  let mission = null, persistedMission = null, inflightSteering = [];
+  let turnSettled = null;
+  const denialTools = new Set();
+  const snapshot = () => {
+    const scheduling = scheduler?.status() ?? null, news = control.news;
+    return {
+      state: phase, active: phase === 'starting' || Boolean(turn) || (deadline !== null && !stopRequested),
+      checkout_owned: Boolean(ownership), activity, client: client ?? null,
+      requested_model: requestedModel, model: actualModel, last_turn_usage: lastUsage,
+      permission_denials: { count: denialCount, tools: [...denialTools], last_at: lastDenialAt },
+      unread_messages: Number.isSafeInteger(news?.pending) ? news.pending : null,
+      scheduling, delivery: { pending: journal()?.data?.pending?.length ?? 0, notices: journal()?.data?.notices?.length ?? 0 },
+      contact_known: typeof news?.project?.started === 'boolean' && typeof news?.project?.paused === 'boolean',
+      work_available: news?.work?.runnable === true && Number.isSafeInteger(news.work.revision)
+        && news.work.revision > (scheduling?.handledRevision ?? -1),
+      folder: folder ?? null, scope: scope ?? null, started_at: startedAt, deadline_at: deadline,
+      remaining_seconds: deadline ? Math.max(0, Math.ceil((deadline - now()) / 1000)) : 0,
+      current_turn: Boolean(turn), last_result: lastResult, error, failure: failureInfo,
+      mission_ref: mission?.id ?? null, recovered: mission?.recovered === true,
+      steering: steering.map(({ id, state }) => ({ id, state })),
+    };
+  };
+  const notify = () => {
+    if (mission) {
+      const next = { ...mission, phase, turnInFlight: Boolean(turn) || phase === 'working' || phase === 'stopping',
+        inflightSteering, steering: steering.map(item => ({ ...item })), sequence };
+      const serialized = JSON.stringify(next);
+      // Persist lifecycle/steering transitions, not every tool activity or status poll.
+      if (serialized !== persistedMission) { saveWorkerMission(stateDir, record, next, mission.id); mission = next; persistedMission = serialized; }
+    }
+    try { onState(snapshot()); } catch {}
+  };
+  const allowed = () => !control.fatal && !control.closed && control.news?.project?.started === true && control.news.project.paused !== true;
+  const journal = () => bridge.journal;
+  const previousDeferred = bridge.onDeferred;
+  const onDeferred = () => { previousDeferred?.(); if (turn && !stopRequested) sendDeferred = true; };
+  bridge.onDeferred = onDeferred;
+  async function launch() {
+    if (turn || stopRequested || phase === 'paused' || !allowed() || now() >= deadline) return;
+    phase = 'working'; scheduler.beginTurn(control.news); sendDeferred = false; abort = new AbortController();
+    const applied = steering.filter(item => item.state === 'received');
+    inflightSteering = applied.map(item => item.id);
+    const notices = journal()?.notices?.() ?? []; notify();
+    const prompt = `Work only within the human-approved scope: ${scope}.\nRead get_project and get_updates; respect current project state and rules. Reconcile previous work before repeating any external action.\n${mission?.recovered ? 'This mission was recovered after its supervisor ended. The last turn may have completed actions without recording its result. Inspect the checkout, saved work intents and project updates before choosing further work; do not blindly replay edits, commits or messages.\n' : ''}${applied.length ? 'Operator steering for this turn:\n' + applied.map(item => item.message).join('\n') : 'Continue the saved work session.'}\n${notices.length ? 'Runner deferred-send results (already processed; do not republish): ' + JSON.stringify(notices) + '\n' : ''}The work session ends at ${new Date(deadline).toISOString()}. End with WORK_NEXT: runnable when there is concrete work you can do next, otherwise WORK_NEXT: waiting. Do not create another agent or background process.`;
+    const signal = abort.signal;
+    const checkoutClaim = ownership;
+    let finishTurn;
+    turnSettled = new Promise(resolve => { finishTurn = resolve; });
+    let invokedAt;
+    let failureStage = 'runtime_contact';
+    turn = (async () => {
+      try { await control.setPhase?.('turn'); }
+      catch (failure) {
+        const retryable = failure.fatal !== true && contactIsTransient(failure);
+        failureInfo = { stage: 'runtime_contact', code: faultCodes.has(failure.code) ? failure.code : faultCodes.has(failure.cause?.code) ? failure.cause.code : 'unknown', retryable };
+        if (!retryable) throw failure;
+        const retryAfter = Number(failure.retryAfter);
+        contactRetryAt = now() + (Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 3600) * 1000 : 0);
+        return { failed: true, retryable: true, failureCode: 'runtime_contact_failure' };
+      }
+      contactRetryAt = null;
+      if (signal.aborted || stopRequested || !allowed() || now() >= deadline) return { interrupted: true };
+      failureInfo = null; error = null;
+      for (const item of applied) item.state = 'applied';
+      failureStage = 'checkout_ownership';
+      checkoutClaim.beginTurn(); invokedAt = now(); actualModel = null;
+      failureStage = 'native_execution';
+      notify();
+      return adapter.run({ prompt, signal, deadline,
+        onModelStarting: () => checkoutClaim.beginTurn(), onModelStarted: pid => checkoutClaim.modelStarted(pid),
+        onActivity: tool => { if (typeof tool === 'string' && /^[A-Za-z0-9_:.-]{1,150}$/.test(tool)) { activity = { tool, at: now() }; control.activity = activity; notify(); } },
+        onMetadata: value => { if (typeof value?.model === 'string' && /^[A-Za-z0-9_:.-]{1,150}$/.test(value.model)) { actualModel = value.model; notify(); } },
+        onPermission: value => { if (typeof value?.tool === 'string' && /^[A-Za-z0-9_:.-]{1,150}$/.test(value.tool)) { denialCount++; lastDenialAt = now(); if (denialTools.size < 64) denialTools.add(value.tool); notify(); } },
+      });
+    })();
+    try {
+      const result = await turn;
+      failureStage = 'checkout_cleanup';
+      checkoutClaim.endTurn();
+      let lastTurn;
+      if (invokedAt !== undefined) {
+        // Sequence belongs to the fenced service run, not this finite worker mission.
+        // A replacement worker on the same control must not restart at sequence one.
+        usageSequence = Math.max(usageSequence, control.lastTurn?.usage?.sequence ?? 0) + 1;
+        lastUsage = result?.usage ?? null; actualModel = lastUsage?.model ?? null;
+        const endedAt = now();
+        const outcome = result?.interrupted && endedAt >= deadline ? 'timed_out' : result?.interrupted || result?.failed ? 'failed' : 'succeeded';
+        lastTurn = { kind: 'work', outcome, ended_at: endedAt,
+          usage: { provider: client, inputSemantics: client === 'codex' ? 'includes-cache' : 'uncached', model: null, modelSource: 'unknown', tokens: null,
+            ...lastUsage, ...(lastUsage?.tokens ? { tokens: { input: null, output: null, cacheRead: null, cacheWrite: null, modelCalls: null, ...lastUsage.tokens } } : {}),
+            sequence: usageSequence, seconds: Math.max(0, (endedAt - invokedAt) / 1000) } };
+      }
+      if (result?.interrupted) { scheduler.recordOutcome({ kind: sendDeferred ? 'send_deferred' : 'interrupted', news: control.news, now: now() }); if (!stopRequested && phase !== 'paused') phase = 'waiting'; }
+      else if (result?.failed) {
+        if (result.failureCode !== 'runtime_contact_failure') {
+          const codes = ['authentication_required', 'permission_required', 'private_state_failure', 'session_recovery_failed', 'local_execution_failure'];
+          failureInfo = { stage: 'native_execution', code: codes.includes(result.failureCode) ? result.failureCode : 'unknown', retryable: result.retryable !== false };
+        }
+        scheduler.recordOutcome({ kind: 'failed', news: control.news, now: now(), retryable: result.retryable !== false });
+        phase = scheduler.status().blocked ? 'blocked' : 'waiting';
+        const messages = { runtime_contact_failure: 'Project contact failed before model work. Bounded retries wait for fresh contact and stop after three failures.', authentication_required: 'Sign in to the local model client before resuming.', permission_required: 'The model needs an approved permission before this work can continue.', private_state_failure: 'Private worker state could not be saved. Check local storage before resuming.', session_recovery_failed: 'The saved model session could not be recovered. Start a fresh approved work session.' };
+        error = messages[result.failureCode] ?? 'The local model turn failed. Bounded retries stop after three failures.';
+      }
+      else {
+        lastResult = String(result?.text ?? '').slice(0, 2000); error = null; failureInfo = null;
+        scheduler.recordOutcome({ kind: 'ok', news: control.news, now: now(), continuation: sendDeferred || /(?:^|\n)WORK_NEXT: runnable\s*$/.test(result?.text ?? '') });
+        if (notices.length) journal()?.acknowledge?.(notices);
+        if (!stopRequested && phase !== 'paused') phase = 'waiting';
+      }
+      failureStage = 'runtime_report';
+      try { await control.setPhase?.('idle', lastTurn); }
+      catch (failure) {
+        if (failure.fatal) throw failure;
+        // Control keeps the report for its next phase/contact/close request. Retrying
+        // telemetry must neither rerun completed model work nor cancel a model turn.
+        control.log?.('Worker turn report pending; runtime contact will retry.');
+      }
+    } catch (failure) { if (!stopRequested) { failureInfo = { stage: failureStage, code: faultCodes.has(failure.code) ? failure.code : 'unknown', retryable: false }; scheduler.recordOutcome({ kind: 'failed', news: control.news, now: now(), retryable: false }); phase = 'blocked'; error = /^(Worker checkout|Worker ownership)/.test(failure.message ?? '') ? failure.message : 'The worker stopped on a local execution failure.'; } }
+    finally {
+      turn = null; abort = null; inflightSteering = [];
+      try { notify(); } finally { turnSettled = null; finishTurn(); }
+    }
+  }
+  async function tick() {
+    if (stopRequested || deadline === null) return;
+    if (now() >= deadline) { await stop('completed'); return; }
+    if (control.fatal || control.closed) { await stop('stopped'); return; }
+    // Control polling briefly clears news before its HTTP reply. Unknown contact blocks
+    // new turns, but is not evidence that the project was paused or authorization revoked.
+    const observed = control.news?.project;
+    if (!observed || typeof observed.started !== 'boolean' || typeof observed.paused !== 'boolean') return;
+    if (!observed.started || observed.paused) {
+      // Preserve only work that was actually interrupted. A successful waiting result
+      // remains waiting; project resume must not invent a reason to start another turn.
+      if (turn) abort?.abort();
+      if (phase !== 'paused' && phase !== 'blocked') phase = 'waiting';
+      notify(); return;
+    }
+    // Communication never cancels a model turn. The agent can read project updates
+    // during its work; queued steering is supplied at the next natural turn boundary.
+    if (phase === 'paused' || phase === 'blocked' || turn) return;
+    if (contactRetryAt !== null && now() < contactRetryAt) return;
+    if (bridge.fault) { phase = 'blocked'; error = 'Project delivery state requires attention before work can continue.'; notify(); return; }
+    const decision = scheduler.decide({ news: control.news, pendingDeliveries: journal()?.data?.pending?.length ?? 0, notices: journal()?.data?.notices?.length ?? 0, steering: steering.some(item => item.state === 'received'), now: now() });
+    if (decision.action === 'stop') { phase = 'blocked'; error ??= decision.reason === 'unacknowledged_inbox' ? 'Three turns left project updates unacknowledged. Review the worker before resuming.' : 'Repeated local model failures require review before resuming.'; notify(); return; }
+    if (decision.action === 'run') await launch();
+  }
+  async function stop(finalPhase = 'stopped') {
+    stopRequested = true; phase = turn ? 'stopping' : finalPhase; clearTimer(timer); abort?.abort(); notify();
+    if (turnSettled) await turnSettled;
+    try { ownership?.release(); ownership = null; }
+    catch (failure) { phase = 'blocked'; error = failure.message; notify(); throw failure; }
+    phase = finalPhase; if (bridge.onDeferred === onDeferred) bridge.onDeferred = previousDeferred; notify(); return snapshot();
+  }
+  const requestTick = () => { void tick().catch(() => { void stop('stopped').catch(() => { /* stop already exposes the blocked state and retains ownership. */ }); }); };
+  return {
+    status: snapshot,
+    async start(options) {
+      if (options.approved !== true) throw new Error('Explicit human approval is required for the worker client, scope, folder and duration.');
+      if (phase !== 'idle') throw new Error('This work session already started. Pause, resume or stop it; starting cannot extend its deadline.');
+      if (!allowed()) throw new Error('Start the project and resume it before starting a worker. The verified connection must still be authorized and available.');
+      client = options.client;
+      if (options.model !== undefined && (typeof options.model !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,149}$/.test(options.model))) throw new Error('Choose a valid model identifier for the approved client.');
+      requestedModel = options.model ?? null;
+      if (!['claude', 'codex'].includes(client)) throw new Error('Supervised workers currently support local Claude Code or Codex CLI. Other models can use the current-chat MCP mode.');
+      const minutes = options.minutes ?? 60;
+      if (!Number.isInteger(minutes) || minutes < 15 || minutes > 240 || minutes % 15 !== 0) throw new Error('Choose a work duration from 15 to 240 minutes in 15-minute steps.');
+      scope = bounded(options.scope, 'approved work scope', 4000); folder = validateWorkspace(options.folder, record);
+      selectWorkerMission(stateDir, record, { ...options, scope, folder }, now());
+      phase = 'starting'; notify();
+      try {
+      ownership = await claimCheckout({ folder, agentId: record.agentId, project: record.service });
+      if (stopRequested) { ownership.release(); ownership = null; throw new Error('The MCP session closed before the worker could start.'); }
+      assertStateOutsideWorkspace(stateDir, folder); ensureHome(stateDir);
+      const workerHome = join(stateDir, 'worker'); ensureHome(workerHome);
+      const saved = selectWorkerMission(stateDir, record, { ...options, scope, folder }, now());
+      const previousId = readWorkerMission(stateDir, record)?.id ?? null;
+      const workerDirId = saved?.workerDir ?? randomUUID();
+      const workerDir = join(workerHome, workerDirId); ensureHome(workerDir);
+      const source = instructionsText ?? verifyBundle().files['AGENT_PROMPT_V2.md'].toString('utf8');
+      const executionGuide = client === 'claude' ? '\nGuarded execution: project npm scripts (`npm test`, `npm run <script>`) and `node --test`/`node --check` are supported within this approved mission. Git fetch/push use origin or the configured default remote; quiet forms are supported. File edits use native Read/Write/Edit. Arbitrary node scripts, inline code, outside-workspace reads and browser startup may require human permission. A denied operation is local to this worker and does not prove another worker is blocked. Do not disguise or repackage a denied action to evade its decision; report the operation and needed approval, and continue other useful approved work.\n' : '';
+      if (!saved) writePrivate(join(workerDir, 'instructions.md'), `${source}${executionGuide}\n\n## Human-approved local work session\nWork only on: ${scope}. Use only this project's supplied MCP connection. Do not start other agents. Your session has a finite deadline; pauses do not extend it. Stop at the deadline or operator cancellation. Native guarded permissions apply; never enable bypass.\nThis approval covers the mission, not just one issue. After completing one task, choose the next useful task within the approved scope without asking what to do next. The mission is done only when its entire approved scope is complete. If a task is blocked, record its concrete blocker and choose another useful authorized task. Wait when all useful authorized work is blocked or there is no actionable work; do not invent work or repeatedly rediscover it. Notify the human of a concrete blocker when their action is needed. End each turn with exactly one line: WORK_NEXT: runnable when concrete authorized work remains, WORK_NEXT: waiting when no authorized action is available, or WORK_NEXT: done only when the entire approved mission is complete.\nDo not create or change CI/CD, deployment, infrastructure, credentials, repository permissions or branch protection unless the approved work scope explicitly authorizes it. If that prevents a task, record the blocker and choose another authorized task. A failing check does not authorize weakening or bypassing it. These instructions constrain your approved scope; they are not an operating-system sandbox.\n`);
+      const instructionsHash = digest(readPrivate(join(workerDir, 'instructions.md')));
+      if (saved && instructionsHash !== saved.instructionsHash) throw new Error('Worker recovery instructions changed. Inspect the saved mission before resuming.');
+      const connection = {};
+      adapter = adapterFactory({ client, model: options.model, folder, stateDir: workerDir, bridge: connection, scope });
+      workerConnection ??= await workerBridge(bridge);
+      if (stopRequested) throw new Error('The MCP session closed before the worker could start.');
+      Object.assign(connection, workerConnection);
+      writePrivate(join(workerDir, 'mcp.json'), { mcpServers: { pilot: connection } });
+      startedAt = saved?.startedAt ?? now(); deadline = saved?.deadline ?? startedAt + minutes * 60000;
+      if (now() >= deadline) throw new Error('Worker recovery deadline has expired during startup. No model was started.');
+      sequence = saved?.sequence ?? 0;
+      steering.push(...(saved?.steering ?? []).map(item => ({ ...item, state: saved.turnInFlight && saved.inflightSteering.includes(item.id) ? 'received' : item.state })));
+      const nextMission = { schema: 1, id: saved?.id ?? randomUUID(), workerDir: workerDirId, connectionId: record.id, service: record.service, repo: record.repo,
+        ownerPid: process.pid, client, model: requestedModel, scope, folder, startedAt, deadline, instructionsHash, recovered: Boolean(saved),
+        phase: 'waiting', sequence, steering: steering.map(item => ({ ...item })), turnInFlight: false, inflightSteering: [] };
+      // Compare against the exact record observed under exclusive checkout ownership.
+      saveWorkerMission(stateDir, record, nextMission, previousId);
+      mission = nextMission;
+      persistedMission = JSON.stringify(mission);
+      phase = 'waiting'; scheduler = createWorkController({ quietIntervalMs, now, random, deadline }); notify();
+      timer = setTimer(requestTick, pollMs);
+      requestTick(); return snapshot();
+      } catch (failure) {
+        let cleanupFailure;
+        try { ownership?.release(); ownership = null; } catch (cleanup) { cleanupFailure = cleanup; }
+        phase = cleanupFailure ? 'blocked' : stopRequested ? 'stopped' : 'idle'; adapter = null;
+        if (mission && !cleanupFailure) { mission.phase = 'startup_failed'; saveWorkerMission(stateDir, record, mission, mission.id); mission = null; persistedMission = null; }
+        if (cleanupFailure) { error = cleanupFailure.message; failure.cause ??= cleanupFailure; }
+        notify(); throw failure;
+      }
+    },
+    async pause() { if (!deadline || stopRequested) throw new Error('There is no active work session.'); phase = 'paused'; abort?.abort(); notify(); if (turnSettled) await turnSettled; return snapshot(); },
+    async resume() { if (phase !== 'paused' && phase !== 'blocked') throw new Error('Only paused or blocked work can resume.'); if (now() >= deadline) return stop('completed'); error = null; phase = 'waiting'; scheduler.requestContinuation(); notify(); requestTick(); return snapshot(); },
+    steer({ message }) { if (!deadline || stopRequested) throw new Error('There is no active work session.'); if (steering.length >= 64) throw new Error('Too many steering instructions in this work session.'); steering.push({ id: ++sequence, state: 'received', message: bounded(message, 'steering instruction', 2000) }); notify(); return { id: sequence, state: 'received', note: 'Queued for the next natural model turn; current work is not interrupted. Check applied state; the deadline is unchanged.' }; },
+    stop: () => stop('stopped'), close: () => stop('stopped'), tick,
+  };
+}