@karma42/agent 0.0.0-stage → 0.1.0-beta.10

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,
+  };
+}