@yeaft/webchat-agent 1.0.295 → 1.0.298

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.295",
+  "version": "1.0.298",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/engine.js

@@ -1838,7 +1838,7 @@ export class Engine {
    *   string-prompt shape (no regression for existing callers).
    * @yields {EngineEvent}
    */
-  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, sessionTopics = null, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, askUser = null, threadId = MAIN_THREAD_ID, vpTurnId = null, drainPendingUserMessages = null, closePendingUserInput = null, collabToolPolicy = null } = {}) {
+  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, sessionTopics = null, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, askUser = null, threadId = MAIN_THREAD_ID, vpTurnId = null, drainPendingUserMessages = null, prepareProviderRequest = null, startProviderRequest = null, finishProviderRequest = null, failProviderRequest = null, closePendingUserInput = null, collabToolPolicy = null } = {}) {
     if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
       yield {
         type: 'error',
@@ -1915,7 +1915,7 @@ export class Engine {
     };
     try {
       this.#currentThreadId = threadId || MAIN_THREAD_ID;
-      yield* this.#runQuery({ prompt: effectivePrompt, promptParts: effectivePromptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, sessionTopics, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted, getCurrentTodos, setCurrentTodos, askUser, threadId: this.#currentThreadId, vpTurnId, drainPendingUserMessages, closePendingUserInput, collabToolPolicy: effectiveCollabToolPolicy, explicitSkillName: parsedSkill.skillName, retryLifecycle });
+      yield* this.#runQuery({ prompt: effectivePrompt, promptParts: effectivePromptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, sessionTopics, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted, getCurrentTodos, setCurrentTodos, askUser, threadId: this.#currentThreadId, vpTurnId, drainPendingUserMessages, prepareProviderRequest, startProviderRequest, finishProviderRequest, failProviderRequest, closePendingUserInput, collabToolPolicy: effectiveCollabToolPolicy, explicitSkillName: parsedSkill.skillName, retryLifecycle });
     } finally {
       // Closing the async generator at a visible retry boundary means the
       // continuation never reached a provider. Keep it out of history and
@@ -1963,7 +1963,7 @@ export class Engine {
    * in a try/finally without indenting the whole loop.
    * @private
    */
-  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, sessionTopics = null, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, askUser = null, threadId = MAIN_THREAD_ID, vpTurnId = null, drainPendingUserMessages = null, closePendingUserInput = null, collabToolPolicy = null, explicitSkillName = null, retryLifecycle }) {
+  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, sessionTopics = null, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, askUser = null, threadId = MAIN_THREAD_ID, vpTurnId = null, drainPendingUserMessages = null, prepareProviderRequest = null, startProviderRequest = null, finishProviderRequest = null, failProviderRequest = null, closePendingUserInput = null, collabToolPolicy = null, explicitSkillName = null, retryLifecycle }) {
 
     const effectiveCollabToolPolicy = collabToolPolicy === COLLAB_TOOL_POLICY.SINGLE_VP || collabToolPolicy === COLLAB_TOOL_POLICY.MULTI_VP
       ? collabToolPolicy
@@ -2367,6 +2367,7 @@ export class Engine {
     let currentModel = this.#config.model;
     let cumulativeInputTokens = 0;
     let cumulativeOutputTokens = 0;
+    let activeProviderRequest = null;
     // task-707: tool-callable end-turn signal. Tools (currently only
     // `route_forward`) can set this via toolCtx.requestEndTurn(reason)
     // to break out of the tool-loop after the current batch finishes
@@ -2645,6 +2646,16 @@ export class Engine {
           retryLifecycle.pendingContinuation = null;
         }
 
+        activeProviderRequest = typeof prepareProviderRequest === 'function'
+          ? prepareProviderRequest({
+              turnNumber,
+              entries: appendedBeforeStream,
+              system: systemPrompt,
+              messages: wireMessages.map(mapDebugMessage),
+              model: currentModel,
+            }) || null
+          : null;
+
         // Snapshot task results carried by this exact request. Request start
         // is not delivery: fetch may remain pending and then be aborted before
         // the provider processes anything. Ack only after a normal stream end
@@ -2661,6 +2672,7 @@ export class Engine {
           effortSource: userEffort ? 'user' : 'auto',
           signal,
           onRawExchange: captureRawExchange,
+          onRequestStart: () => startProviderRequest?.(activeProviderRequest),
         })) {
           // task-325a (abort-stop fix): per-event abort short-circuit.
           // The adapter is expected to throw AbortError when fetch's
@@ -2768,6 +2780,14 @@ export class Engine {
         // escrow so retry or final rescue can deliver the payload.
         if (sawProviderStop) {
           this.#confirmAsyncTaskResults(requestAsyncTaskIds);
+          const completedProviderRequest = activeProviderRequest;
+          activeProviderRequest = null;
+          finishProviderRequest?.(completedProviderRequest, {
+            responseText,
+            stopReason,
+            toolCalls: toolCalls.map(tc => ({ id: tc.id, name: tc.name, input: tc.input })),
+            thinkingBlocks,
+          });
         }
         traceRequest('llm.request_complete', {
           durationMs: perfNowMs() - requestPerfStart,
@@ -2785,6 +2805,10 @@ export class Engine {
         consecutiveRetryableErrors = 0;
       } catch (err) {
         const latencyMs = Date.now() - startTime;
+        if (activeProviderRequest) {
+          failProviderRequest?.(activeProviderRequest, err);
+          activeProviderRequest = null;
+        }
 
         const endAttemptTrace = (attemptStopReason) => {
           this.#trace.endTurn(turnId, {
@@ -3571,6 +3595,7 @@ export class Engine {
         let displayImages = [];
         let isError = false;
         let toolErrorOutput = null;
+        let fatalToolError = null;
         currentToolCallForAsyncTask = {
           id: tc.id,
           name: tc.name,
@@ -3644,6 +3669,7 @@ export class Engine {
             output = `Error: ${err.message}`;
             isError = true;
             yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: true, threadId: this.currentThreadId };
+            if (err?.fatalToolTimeout === true) fatalToolError = err;
           }
         }
 
@@ -3732,6 +3758,7 @@ export class Engine {
           isError,
         }));
         queryToolCount += 1;
+        if (fatalToolError) throw fatalToolError;
       }
 
       // PR-L: flush any duplicate-call reminders queued during the batch.

package/yeaft/sessions/session-crud.js

@@ -541,7 +541,7 @@ export function renameSession(yeaftDir, sessionId, newName) {
   if (!name) throw new SessionCrudError('invalid_name', sessionId);
   const handle = requireSession(yeaftDir, sessionId);
   const meta = handle.getMeta();
-  handle.saveMeta({ ...meta, name });
+  handle.saveMeta({ ...meta, name, metadataUpdatedAt: new Date().toISOString() });
   const next = handle.getMeta();
   handle.close();
   return next;
@@ -561,7 +561,7 @@ export function updateSessionAnnouncement(yeaftDir, sessionId, text) {
   const announcement = text.trim();
   const handle = requireSession(yeaftDir, sessionId);
   const meta = handle.getMeta();
-  handle.saveMeta({ ...meta, announcement });
+  handle.saveMeta({ ...meta, announcement, metadataUpdatedAt: new Date().toISOString() });
   const next = handle.getMeta();
   handle.close();
   return next;
@@ -577,7 +577,10 @@ export function updateSessionAnnouncement(yeaftDir, sessionId, text) {
 export function updateSessionConfig(yeaftDir, sessionId, partial) {
   const handle = requireSession(yeaftDir, sessionId);
   try {
-    return saveSessionConfig(yeaftDir, sessionId, partial || {});
+    const saved = saveSessionConfig(yeaftDir, sessionId, partial || {});
+    const meta = handle.getMeta();
+    handle.saveMeta({ ...meta, metadataUpdatedAt: new Date().toISOString() });
+    return saved;
   } finally {
     handle.close();
   }
@@ -708,7 +711,7 @@ export function addMember(yeaftDir, sessionId, vpId) {
   try {
     const meta = handle.getMeta();
     const next = rosterAdd(meta, vpId);
-    handle.saveMeta(next);
+    handle.saveMeta({ ...next, metadataUpdatedAt: new Date().toISOString() });
     return handle.getMeta();
   } finally {
     handle.close();
@@ -728,7 +731,7 @@ export function removeMember(yeaftDir, sessionId, vpId) {
       return meta;
     }
     const next = rosterRemove(meta, vpId);
-    handle.saveMeta(next);
+    handle.saveMeta({ ...next, metadataUpdatedAt: new Date().toISOString() });
     return handle.getMeta();
   } finally {
     handle.close();
@@ -741,7 +744,7 @@ export function setSessionDefaultVp(yeaftDir, sessionId, vpId) {
   try {
     const meta = handle.getMeta();
     const next = setDefaultVp(meta, vpId);
-    handle.saveMeta(next);
+    handle.saveMeta({ ...next, metadataUpdatedAt: new Date().toISOString() });
     return handle.getMeta();
   } finally {
     handle.close();

package/yeaft/sessions/session-store.js

@@ -145,6 +145,7 @@ export function createSession(sessionsRoot, spec) {
     workDir: typeof spec.workDir === 'string' ? spec.workDir.trim() : '',
     workspaceKey: typeof spec.workspaceKey === 'string' ? spec.workspaceKey.trim() : '',
     createdAt: spec.createdAt || new Date().toISOString(),
+    metadataUpdatedAt: spec.metadataUpdatedAt || spec.createdAt || new Date().toISOString(),
   };
   h.saveMeta(meta);
   return h;

package/yeaft/tools/file-edit.js

@@ -75,16 +75,16 @@ Guidelines:
   isDestructive: () => false,
   async execute(input, ctx) {
     const { file_path, old_string, new_string, replace_all = false } = input;
-    if (!file_path) return JSON.stringify({ error: 'file_path is required' });
-    if (old_string === undefined) return JSON.stringify({ error: 'old_string is required' });
-    if (new_string === undefined) return JSON.stringify({ error: 'new_string is required' });
-    if (old_string === new_string) return JSON.stringify({ error: 'old_string and new_string are identical' });
+    if (!file_path) return JSON.stringify({ errorEffect: 'none', error: 'file_path is required' });
+    if (old_string === undefined) return JSON.stringify({ errorEffect: 'none', error: 'old_string is required' });
+    if (new_string === undefined) return JSON.stringify({ errorEffect: 'none', error: 'new_string is required' });
+    if (old_string === new_string) return JSON.stringify({ errorEffect: 'none', error: 'old_string and new_string are identical' });
 
     const cwd = ctx?.cwd || process.cwd();
     const absPath = resolve(cwd, file_path);
 
     if (!existsSync(absPath)) {
-      return JSON.stringify({ error: `File not found: ${absPath}` });
+      return JSON.stringify({ errorEffect: 'none', error: `File not found: ${absPath}` });
     }
 
     try {
@@ -106,6 +106,7 @@ Guidelines:
           ? old_string.slice(0, 100) + '...'
           : old_string;
         return JSON.stringify({
+          errorEffect: 'none',
           error: `old_string not found in file`,
           hint: `The exact text "${preview}" was not found in ${absPath}. Check whitespace and indentation.`,
         });
@@ -113,6 +114,7 @@ Guidelines:
 
       if (count > 1 && !replace_all) {
         return JSON.stringify({
+          errorEffect: 'none',
           error: `old_string found ${count} times — not unique. Use replace_all: true to replace all occurrences, or provide more context to make it unique.`,
           occurrences: count,
         });
@@ -137,7 +139,7 @@ Guidelines:
         message: `Replaced ${replace_all ? count : 1} occurrence(s) in ${absPath}`,
       });
     } catch (err) {
-      return JSON.stringify({ error: `Failed to edit file: ${err.message}` });
+      return JSON.stringify({ errorEffect: 'unknown', error: `Failed to edit file: ${err.message}` });
     }
   },
 });

package/yeaft/tools/file-write.js

@@ -56,9 +56,9 @@ Guidelines:
   isDestructive: () => false,
   async execute(input, ctx) {
     const { file_path, content } = input;
-    if (!file_path) return JSON.stringify({ error: 'file_path is required' });
+    if (!file_path) return JSON.stringify({ errorEffect: 'none', error: 'file_path is required' });
     if (content === undefined || content === null) {
-      return JSON.stringify({ error: 'content is required' });
+      return JSON.stringify({ errorEffect: 'none', error: 'content is required' });
     }
 
     const cwd = ctx?.cwd || process.cwd();

package/yeaft/tools/registry.js

@@ -194,23 +194,31 @@ export function normalizeToolOutput(output) {
   return text;
 }
 
-export function isToolErrorOutput(output) {
+function parseToolErrorOutput(output) {
   const text = normalizeToolOutput(output).trim();
-  if (!text.startsWith('{')) return false;
+  if (!text.startsWith('{')) return null;
   try {
     const parsed = JSON.parse(text);
-    return Boolean(
-      parsed
+    return parsed
       && typeof parsed === 'object'
       && !Array.isArray(parsed)
       && typeof parsed.error === 'string'
-      && parsed.error.trim(),
-    );
+      && parsed.error.trim()
+      ? parsed
+      : null;
   } catch {
-    return false;
+    return null;
   }
 }
 
+export function isToolErrorOutput(output) {
+  return parseToolErrorOutput(output) !== null;
+}
+
+export function toolErrorEffect(output) {
+  return parseToolErrorOutput(output)?.errorEffect === 'none' ? 'none' : 'unknown';
+}
+
 function truncateUtf8(text, maxBytes) {
   if (maxBytes <= 0) return '';
   const buffer = Buffer.from(String(text), 'utf8');
@@ -435,9 +443,19 @@ export class ToolRegistry {
     const rawTimeout = Number.isFinite(tool.timeoutMs) ? tool.timeoutMs : DEFAULT_TOOL_TIMEOUT_MS;
     const useTimeout = rawTimeout > 0;
 
-    const output = useTimeout
-      ? await runWithTimeout(tool.execute(input, ctx), rawTimeout, name)
-      : await tool.execute(input, ctx);
+    let output;
+    try {
+      output = useTimeout
+        ? await runWithTimeout(tool.execute(input, ctx), rawTimeout, name)
+        : await tool.execute(input, ctx);
+    } catch (error) {
+      if (error instanceof ToolExecutionTimeoutError
+          && tool.sideEffectScope !== 'run'
+          && tool.isReadOnly?.(input) !== true) {
+        error.fatalToolTimeout = true;
+      }
+      throw error;
+    }
 
     return normalizeToolOutput(output);
   }

package/yeaft/tools/types.js

@@ -63,6 +63,7 @@
  * @property {(input?: object) => boolean} [isReadOnly] — read-only operation?
  * @property {(input?: object) => boolean} [isDestructive] — destructive operation?
  * @property {'json-error-envelope' | null} [errorOutput] — explicit returned-output error contract; null means only thrown errors fail
+ * @property {'external' | 'run'} [sideEffectScope] — whether mutations escape the current Run collector
  */
 
 /**
@@ -77,6 +78,7 @@
  *   isReadOnly?: (input?: object) => boolean,
  *   isDestructive?: (input?: object) => boolean,
  *   errorOutput?: 'json-error-envelope' | null,
+ *   sideEffectScope?: 'external' | 'run',
  *   timeoutMs?: number,
  * }} def
  * @returns {ToolDef}
@@ -91,6 +93,7 @@ export function defineTool({
   isReadOnly = () => false,
   isDestructive = () => false,
   errorOutput = 'json-error-envelope',
+  sideEffectScope = 'external',
   timeoutMs,
 }) {
   if (!name) throw new Error('Tool must have a name');
@@ -105,6 +108,7 @@ export function defineTool({
     isReadOnly,
     isDestructive,
     errorOutput,
+    sideEffectScope,
   };
   // Legacy tool-name aliases. Registered as extra lookup keys so old
   // jsonl tool_calls (e.g. `SendMessage` → `PromptAgent`) keep resolving,

package/yeaft/web-bridge.js

@@ -1098,6 +1098,10 @@ const ESCALATE_AFTER_ABORT_MS = 15_000;
 /** Virtual conversationId for the Yeaft session */
 let yeaftConversationId = null;
 
+function createYeaftConversationId() {
+  return `yeaft-${randomUUID()}`;
+}
+
 /** Last agent-level Yeaft slash command payload. Replayed after the web side
  *  creates/replaces the virtual Yeaft conversation id so `/` autocomplete never
  *  falls back to built-ins while full Session metadata is still loading. */
@@ -1316,7 +1320,7 @@ function loadVisibleGroupHistoryPage(store, sessionId, limit, beforeSeq = null)
 
 function ensureYeaftConversationId() {
   if (!yeaftConversationId) {
-    yeaftConversationId = `yeaft-${Date.now()}`;
+    yeaftConversationId = createYeaftConversationId();
     replayCachedSkillSlashCommandsToYeaftConversation();
   }
   return yeaftConversationId;
@@ -3110,6 +3114,7 @@ function sendSessionRosterChanged(session) {
     roster: session.roster,
     defaultVpId: session.defaultVpId,
     workDir: session.workDir || '',
+    metadataUpdatedAt: session.metadataUpdatedAt || session.createdAt || null,
   };
   sendSessionEvent({ type: 'session_roster_changed', ...payload });
 }
@@ -7029,7 +7034,7 @@ export async function resetYeaftSession() {
     claimRuntimeOwnership(session);
     installYeaftRuntimeBridge(session);
 
-    yeaftConversationId = `yeaft-${Date.now()}`;
+    yeaftConversationId = createYeaftConversationId();
     scheduleBaseRuntimeLoad();
     hydrateYeaftStatusFromSession(session, { reason: 'reset', emitEvent: true });
     broadcastSkillSlashCommands(session);
@@ -7346,6 +7351,9 @@ export const __testHooks = {
   ensureYeaftConversationIdForTest() {
     return ensureYeaftConversationId();
   },
+  setYeaftConversationIdForTest(value) {
+    yeaftConversationId = value || null;
+  },
   preloadYeaftSkillSlashCommandsForTest() {
     return broadcastSkillSlashCommands(session);
   },

package/yeaft/work-center/bridge.js

@@ -20,7 +20,7 @@ let shutdownPromise = null;
 let serviceFactory = null;
 
 const BROWSER_DETAIL_OPS = new Set([
-  'get', 'create', 'update', 'start', 'cancel', 'resume', 'action_input', 'retry_action', 'guide', 'retry',
+  'get', 'create', 'update', 'start', 'cancel', 'resume', 'post_work_item_message', 'action_input', 'retry_action', 'guide', 'retry',
 ]);
 const BROWSER_ACTION_DEBUG_OPS = new Set(['get_action_messages', 'get_action_requests', 'get_action_request']);
 // `files` is an internal server-to-Agent field. The browser relay rejects any
@@ -29,6 +29,10 @@ const BROWSER_FILE_FIELDS = Object.freeze({
   create: [
     'title', 'goal', 'acceptanceCriteria', 'workItemType', 'workDir', 'reuseMemory', 'files', 'start',
   ],
+  post_work_item_message: [
+    'id', 'clientMessageId', 'text', 'target', 'revision', 'planRevision', 'ledgerRevision',
+    'coordinatorRevision', 'files',
+  ],
   work_item_message: [
     'id', 'text', 'revision', 'planRevision', 'ledgerRevision', 'coordinatorRevision', 'files',
   ],

package/yeaft/work-center/controller.js

@@ -227,6 +227,8 @@ export class WorkflowController {
   }
 
   input(id, input = {}) {
+    const existingClientMessage = this.store.hasActionInputClientMessage(id, input.actionId, input.clientMessageId);
+    if (existingClientMessage) return this.store.getWorkItemDetail(id);
     const text = typeof input.text === 'string' ? input.text.trim().slice(0, 8_000) : '';
     const addedAttachmentCount = Math.max(0, Number(input.addedAttachmentCount) || 0);
     if (!text && addedAttachmentCount === 0) throw new Error('Action input or attachments are required');
@@ -253,7 +255,7 @@ export class WorkflowController {
         actionId: input.actionId,
         generation: expectedGeneration,
         revision: input.revision,
-      }, input.attachments, input.addedAttachments);
+      }, input.attachments, input.addedAttachments, input.clientMessageId);
     }
     if (!['waiting', 'failed'].includes(targetAction.status)) {
       throw new Error(`Action in ${targetAction.status} cannot accept input`);
@@ -264,7 +266,9 @@ export class WorkflowController {
       expected: { actionId: input.actionId, generation: input.generation, revision: input.revision },
       attachments: input.attachments,
       inputEvent: {
-        inputId: randomUUID(),
+        inputId: input.clientMessageId || randomUUID(),
+        clientMessageId: input.clientMessageId || null,
+        targetActionId: input.actionId,
         text: text || `The user added ${addedAttachmentCount} attachment(s) as additional context for this Action.`,
         attachments: input.addedAttachments,
       },

package/yeaft/work-center/coordinator.js

@@ -1,4 +1,4 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { resolveMaxOutputTokens } from '../models.js';
 import {
   LLMAuthError,
@@ -531,6 +531,8 @@ export class WorkItemCoordinator {
     this.runtimeProvider = options.runtimeProvider;
     this.policyProvider = typeof options.policyProvider === 'function' ? options.policyProvider : async () => ({});
     this.registry = options.registry;
+    this.ownerBootId = options.ownerBootId || randomUUID();
+    this.claimLeaseMs = Math.max(5_000, Number(options.claimLeaseMs) || 60_000);
     this.attachmentRoot = options.attachmentRoot || null;
     this.languageProvider = typeof options.languageProvider === 'function'
       ? options.languageProvider
@@ -550,7 +552,7 @@ export class WorkItemCoordinator {
       throw new Error('Work Center Coordinator message or attachments are required');
     }
     const promptText = text || `The user added ${addedAttachments.length} attachment(s) for this WorkItem.`;
-    const started = this.store.beginCoordinatorTurn(id, text, {
+    let started = this.store.beginCoordinatorTurn(id, text, {
       revision: Number(input.revision),
       planRevision: Number(input.planRevision),
       ledgerRevision: Number(input.ledgerRevision),
@@ -558,8 +560,15 @@ export class WorkItemCoordinator {
     }, {
       attachments: input.attachments,
       addedAttachments,
+      clientMessageId: input.clientMessageId,
     });
     if (!started) throw new Error(`WorkItem not found: ${id}`);
+    if (started.duplicate) {
+      return { detail: started.detail, task: Promise.resolve(started.detail), duplicate: true };
+    }
+    const claimed = this.store.claimStartedCoordinatorTurn(started, this.ownerBootId, this.claimLeaseMs);
+    if (!claimed) return { detail: started.detail, task: Promise.resolve(started.detail), duplicate: true };
+    started = claimed;
     options.onUpdate?.('coordinator.turn_started', started.detail);
     return this.#scheduleTurn(started, {
       text: promptText,
@@ -569,6 +578,18 @@ export class WorkItemCoordinator {
     });
   }
 
+  resume(started, options = {}) {
+    if (!started?.turnId || !started?.detail || !started?.fence) {
+      throw new Error('Coordinator provider recovery target is invalid');
+    }
+    return this.#scheduleTurn(started, {
+      text: typeof options.text === 'string' ? options.text : '',
+      recovery: options.recovery === true,
+      addedAttachments: Array.isArray(options.addedAttachments) ? options.addedAttachments : [],
+      options,
+    });
+  }
+
   recover(id, options = {}) {
     if (this.shuttingDown) throw new Error('Work Center Coordinator is shutting down');
     const detail = this.store.getWorkItemDetail(id);
@@ -595,11 +616,13 @@ export class WorkItemCoordinator {
       },
     });
     if (!started) return null;
-    options.onUpdate?.('coordinator.recovery_started', started.detail);
+    const claimed = this.store.claimStartedCoordinatorTurn(started, this.ownerBootId, this.claimLeaseMs);
+    if (!claimed) return null;
+    options.onUpdate?.('coordinator.recovery_started', claimed.detail);
     const text = `Action stage "${action.stageId}" failed. Decide the next safe control transition. `
       + 'Failure is not a terminal WorkItem state: guide or replan executable work whenever possible. '
       + 'Request human input only when the snapshot lacks information required for a safe decision.';
-    return this.#scheduleTurn(started, { text, recovery: true, options });
+    return this.#scheduleTurn(claimed, { text, recovery: true, options });
   }
 
   #scheduleTurn(started, {
@@ -607,11 +630,19 @@ export class WorkItemCoordinator {
   }) {
     const abortController = new AbortController();
     this.activeTurns.set(started.turnId, abortController);
+    const claim = started.fence?.claim;
+    const renewalTimer = claim ? setInterval(() => {
+      if (!this.store.renewCoordinatorMailbox(
+        claim.mailboxId, claim.ownerBootId, claim.claimEpoch, this.claimLeaseMs,
+      )) abortController.abort('work_center_coordinator_claim_lost');
+    }, Math.max(1_000, Math.floor(this.claimLeaseMs / 3))) : null;
+    renewalTimer?.unref?.();
     const task = new Promise(resolve => setTimeout(resolve, 0))
       .then(() => this.#executeTurn(started, {
         text, recovery, addedAttachments, options, abortController,
       }))
       .finally(() => {
+        if (renewalTimer) clearInterval(renewalTimer);
         this.activeTurns.delete(started.turnId);
         this.activeTasks.delete(started.turnId);
       });
@@ -622,6 +653,7 @@ export class WorkItemCoordinator {
   async #executeTurn(started, {
     text, recovery, addedAttachments, options, abortController,
   }) {
+    let providerTurn = null;
     try {
       let normalized = null;
       let mutation = null;
@@ -682,6 +714,7 @@ export class WorkItemCoordinator {
           const correction = lastError
             ? `\n\nYour previous decision was rejected by the deterministic validator:\n${String(lastError.message || lastError).slice(0, 2_000)}\nReturn a corrected complete JSON decision.`
             : '';
+          providerTurn = null;
           try {
             let result;
             try {
@@ -689,19 +722,46 @@ export class WorkItemCoordinator {
               const content = attachmentContext.promptParts.length > 0
                 ? [{ type: 'text', text: latestMessage }, ...attachmentContext.promptParts]
                 : latestMessage;
-              result = await Promise.race([
+              const requestBody = {
+                model: resolved.model,
+                system: coordinatorSystemPrompt(language),
+                messages: [{ role: 'user', content }],
+                maxTokens: Math.min(
+                  resolveMaxOutputTokens(resolved.model, runtime.config),
+                  COORDINATOR_MAX_OUTPUT_TOKENS,
+                ),
+                effort: resolved.effort,
+                effortSource: resolved.source,
+                effortContext: { scenario: 'work-center-coordinator' },
+              };
+              const claim = started.fence.claim;
+              providerTurn = this.store.prepareCoordinatorProviderTurn(
+                started.detail.id, started.turnId, attemptCount, requestBody, claim,
+              );
+              if (!providerTurn) return started.detail;
+              if (providerTurn.status === 'unknown') {
+                throw new Error('Coordinator provider dispatch outcome is unknown and requires review');
+              }
+              if (providerTurn.status === 'responded') {
+                result = providerTurn.response;
+              } else {
+                result = await Promise.race([
                 runtime.adapter.call({
-                  model: resolved.model,
-                  system: coordinatorSystemPrompt(language),
-                  messages: [{ role: 'user', content }],
-                  maxTokens: Math.min(
-                    resolveMaxOutputTokens(resolved.model, runtime.config),
-                    COORDINATOR_MAX_OUTPUT_TOKENS,
-                  ),
-                  effort: resolved.effort,
-                  effortSource: resolved.source,
-                  effortContext: { scenario: 'work-center-coordinator' },
+                  ...requestBody,
                   signal: abortController.signal,
+                  onRequestStart: () => {
+                    if (!this.store.dispatchCoordinatorProviderTurn(providerTurn.id, claim)) {
+                      abortController.abort('work_center_coordinator_dispatch_fence_lost');
+                      throw new Error('Coordinator provider turn lost its dispatch fence');
+                    }
+                  },
+                }).then(response => {
+                  const persisted = this.store.respondCoordinatorProviderTurn(
+                    providerTurn.id, providerTurn.requestHash, response, claim,
+                  );
+                  if (!persisted) throw new Error('Coordinator provider response lost its CAS fence');
+                  providerTurn = persisted;
+                  return response;
                 }),
                 new Promise((_, reject) => {
                   abortController.signal.addEventListener('abort', () => {
@@ -709,6 +769,7 @@ export class WorkItemCoordinator {
                   }, { once: true });
                 }),
               ]);
+              }
             } catch (error) {
               if (abortController.signal.aborted || this.shuttingDown) throw error;
               throw coordinatorExecutionError(error, 'provider', language);
@@ -738,6 +799,9 @@ export class WorkItemCoordinator {
             break;
           } catch (error) {
             normalized = null;
+            if (providerTurn?.status === 'responded') {
+              this.store.rejectCoordinatorProviderTurn(providerTurn.id, error, started.fence.claim);
+            }
             if (abortController.signal.aborted || this.shuttingDown || error?.coordinatorClassified) {
               throw error;
             }
@@ -784,16 +848,19 @@ export class WorkItemCoordinator {
         mutation,
         attemptCount,
       }, started.fence);
-      if (!detail) throw new Error('Work Center Coordinator turn is stale or already completed');
+      if (!detail) return this.store.getWorkItemDetail(started.detail.id);
       options.onUpdate?.(recovery ? 'coordinator.recovery_completed' : 'coordinator.turn_completed', detail);
       return detail;
     } catch (error) {
+      if (providerTurn?.status === 'responded') {
+        this.store.rejectCoordinatorProviderTurn(providerTurn.id, error, started.fence.claim);
+      }
       const detail = this.store.failCoordinatorTurn(started.turnId, error, started.fence);
       if (detail) {
         options.onUpdate?.('coordinator.turn_failed', detail);
         return detail;
       }
-      throw error;
+      return this.store.getWorkItemDetail(started.detail.id);
     }
   }