@yeaft/webchat-agent 1.0.567 → 1.0.569

package/yeaft/tools/registry.js

@@ -242,6 +242,35 @@ export function truncateToolResultIfNeeded(output, { toolName, language } = {})
   const originalBytes = Buffer.byteLength(text, 'utf8');
   if (originalBytes <= TOOL_RESULT_MAX_BYTES) return text;
 
+  // Preserve the error contract in the model projection; raw tool output
+  // remains available to tracing/persistence before this budget is applied.
+  if (toolName === 'Bash') {
+    const failure = parseToolErrorOutput(text);
+    if (failure && failure.code?.startsWith('bash_')) {
+      const projected = { ...failure, truncated: true, originalBytes };
+      for (const [key, value] of Object.entries(projected)) {
+        if (key !== 'output' && typeof value === 'string') projected[key] = truncateUtf8(value, 1024);
+      }
+      const source = typeof failure.output === 'string' ? failure.output : '';
+      const buffer = Buffer.from(source, 'utf8');
+      const sample = bytes => {
+        const half = Math.floor(bytes / 2);
+        let start = Math.max(0, buffer.length - half);
+        while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) start += 1;
+        return truncateUtf8(source, half) + '\n[Middle omitted by tool result budget]\n' + buffer.subarray(start).toString('utf8');
+      };
+      let low = 0, high = Math.min(buffer.length, TOOL_RESULT_MAX_BYTES);
+      while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        projected.output = sample(mid);
+        if (Buffer.byteLength(JSON.stringify(projected), 'utf8') <= TOOL_RESULT_MAX_BYTES) low = mid;
+        else high = mid - 1;
+      }
+      projected.output = sample(low);
+      return JSON.stringify(projected);
+    }
+  }
+
   const markerFor = name => normalizeLanguage(language) === 'zh'
     ? `\n\n[已截断：${name} 返回 ${formatSize(originalBytes)}，上限为 ${formatSize(TOOL_RESULT_MAX_BYTES)}；原因：单个 tool result 超过 ${formatSize(TOOL_RESULT_MAX_BYTES)}，模型消息历史不会看到剩余内容]`
     : `\n\n[truncated: ${name} returned ${formatSize(originalBytes)}, capped at ${formatSize(TOOL_RESULT_MAX_BYTES)}; reason: single tool result exceeded ${formatSize(TOOL_RESULT_MAX_BYTES)}, the model message history will not see the rest]`;

package/yeaft/tools/update-agent.js

@@ -9,8 +9,8 @@ import { diagnoseAgentLiveness } from '../sub-agent/liveness.js';
 export default defineTool({
   name: 'UpdateAgent',
   description: {
-    en: 'Adjust a live child in place after inspecting its progress: absolute lifetime time/tool/LLM budgets and explicit extra tool grants. Does not queue a prompt, reset usage, or revive a terminal/reporting child. Give evidence and the remaining task in reason; do not extend stalled or repeating work blindly. Bash permits arbitrary shell and writes, not a read-only sandbox; grant only necessary parent tools and isolate writable workspaces. Already dispatched work is not undone by revocation.',
-    zh: '检查进展后原地调整活跃子 Agent：累计时间/工具/LLM 上限及额外工具授权。不排队提示、不清零用量、不复活终止或收尾中的任务。reason 说明已有证据和剩余工作，勿盲目给停滞/重复任务扩额。Bash 可执行任意 Shell 和写入，并非只读沙箱；只授予必要的父级工具，写任务隔离 workspace。撤销不撤回已执行操作。',
+    en: 'Adjust a live child in place after inspecting its progress: absolute lifetime budgets, extra tool grants, or request a cooperative evidence-only final report. Finalization is control, not a prompt containing reason. Does not reset usage or revive a terminal/reporting child. Already dispatched work is not undone.',
+    zh: '检查进展后原地调整活跃子 Agent：累计预算、额外工具授权，或请求基于现有证据协作收尾。收尾是控制信号，不会把 reason 冒充提示词。不清零用量、不复活终止/报告中的任务，也不撤回已派发操作。',
   },
   parameters: {
     type: 'object',
@@ -32,6 +32,10 @@ export default defineTool({
         type: 'array', items: { type: 'string' }, maxItems: 32,
         description: { en: 'Replace extra persona grants with these canonical parent tool names (e.g. Bash, FileEdit); [] revokes extras, omission leaves grants unchanged', zh: '替换 persona 额外授权（如 Bash、FileEdit）；[] 撤销额外授权，省略则不变' },
       },
+      request_finalize: {
+        type: 'boolean',
+        description: { en: 'Request one tool-free final report from existing evidence, then end the child lifecycle normally', zh: '请求仅基于现有证据生成一次无工具最终报告，然后正常结束子任务生命周期' },
+      },
     },
     required: ['agent_id', 'reason'],
   },
@@ -42,10 +46,10 @@ export default defineTool({
     const fail = error => JSON.stringify({ error, next_steps: 'Inspect the current agent state and correct the request; do not respawn or repeat blindly.' });
     const agent = getAgentRegistry().get(input.agent_id);
     if (!agent || !agentBelongsToCaller(agent, ctx)) return fail(`Agent not found: ${input.agent_id}`);
-    if (isTerminalAgentStatus(agent.status) || agent.budgetReportStarted || agent.budgetStopReason
+    if (isTerminalAgentStatus(agent.status) || agent.budgetReportStarted || agent.finalizationRequested || agent.budgetStopReason
         || agent.abortController?.signal.aborted) return fail('Agent is terminal, stopping or already reporting; it cannot be extended');
     if (typeof input.reason !== 'string' || !input.reason.trim() || input.reason.length > 2000) return fail('reason must contain 1..2000 characters of evidence and remaining work');
-    if (input.budget === undefined && input.allow_tools === undefined) return fail('budget or allow_tools is required');
+    if (input.budget === undefined && input.allow_tools === undefined && input.request_finalize !== true) return fail('budget, allow_tools, or request_finalize=true is required');
     if (input.budget !== undefined) {
       const error = validateBudget(input.budget);
       if (error) return fail(error);
@@ -58,6 +62,7 @@ export default defineTool({
     // All validation precedes mutation. Original usage/deadline origin are retained.
     agent.budget = { ...agent.budget, ...input.budget };
     if (grants) agent.allowTools = grants.tools;
+    if (input.request_finalize === true) agent.finalizationRequested = true;
     agent.controlRevision = (agent.controlRevision || 0) + 1;
     if (agent.execution && (agent.budget.max_tool_calls === undefined
         || agent.execution.toolCalls < agent.budget.max_tool_calls * 0.75)) agent.execution.warning = null;
@@ -68,6 +73,7 @@ export default defineTool({
     agent.refreshToolPolicy?.();
     agent.rearmWallTimeWatchdog?.();
     const event = { type: 'sub_agent_control_updated', at: Date.now(), reason: input.reason.trim(),
+      requestFinalize: input.request_finalize === true,
       previousBudget, budget: { ...agent.budget }, previousTools, allowTools: [...(agent.allowTools || [])] };
     agent.diagnostics ||= [];
     agent.diagnostics.push(event);
@@ -75,6 +81,9 @@ export default defineTool({
     try { agent.outputLog?.write(event); } catch { /* diagnostics must not fail the applied update */ }
     return JSON.stringify({ success: true, agentId: agent.id, status: agent.status,
       budget: agent.budget, allow_tools: agent.allowTools || [], liveness: diagnoseAgentLiveness(agent),
-      next_steps: 'Adjustment applied without restarting work. Continue the parent task; use PromptAgent only if new guidance is needed, then collect its reply. Revocation does not cancel already dispatched work.' });
+      finalizationRequested: agent.finalizationRequested === true,
+      next_steps: input.request_finalize === true
+        ? 'Cooperative wrap-up requested without turning reason into a child prompt. Use WaitAgent to collect the evidence-only final report; already dispatched work may finish first.'
+        : 'Adjustment applied without restarting work. Continue the parent task; use PromptAgent only if new guidance is needed, then collect its reply. Revocation does not cancel already dispatched work.' });
   },
 });

package/yeaft/tools/wait-agent.js

@@ -35,6 +35,7 @@ import { agentBelongsToCaller, getAgentRegistry } from './agent.js';
 import { isTerminalAgentStatus, STATUS } from '../sub-agent/status.js';
 import { diagnoseAgentLiveness } from '../sub-agent/liveness.js';
 import { consumeNotificationForAgent } from '../sub-agent/notifications.js';
+import { describeAgentLifecycle, describeAgentOutcome } from '../sub-agent/outcome.js';
 
 /**
  * Build the status-specific next-step guidance the LLM reads after a wait.
@@ -55,6 +56,9 @@ function nextStepsFor(status, opts = {}) {
       'as an ordinary successful completion.'
     );
   }
+  if (opts.incomplete) {
+    return 'Sub-agent lifecycle ended with incomplete evidence. Inspect outcome and final_report; do not present partial verdict text as a completed review.';
+  }
   if (opts.timedOut && opts.stale) {
     return (
       'No observable event arrived within the diagnostic threshold. This does ' +
@@ -157,12 +161,15 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
     next_steps: nextStepsFor(status, {
       timedOut,
       budgetExceeded: !!budgetResult,
+      incomplete: isTerminalAgentStatus(status) && !describeAgentOutcome(agent).complete,
       stale: liveness.stale,
       mustCollectReply: mustCollectReply && !liveness.stale,
     }),
     agentId: agent.id,
     name: agent.name,
     status,
+    lifecycle: describeAgentLifecycle(agent),
+    outcome: describeAgentOutcome(agent),
     error: agent.error || null,
     outputFile: agent.outputFile || null,
     liveness,
@@ -185,8 +192,17 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
     env.budget_status = budgetResult.status;
     env.budget_reason = budgetResult.reason || null;
     env.partial_output = budgetResult.partial_output || '';
+    env.incomplete = true;
+    env.truncated = Boolean(budgetResult.truncated || budgetResult.final_report?.truncated);
+    env.final_report = budgetResult.final_report || null;
     env.budget_usage = budgetResult.usage || null;
   }
+  if (agent.finalizationRequested) {
+    env.incomplete = true;
+    env.final_report = agent.finalReport || null;
+    env.truncated = Boolean(agent.finalReport?.truncated);
+    env.partial_output = resultText;
+  }
   env.result = resultText;
   return env;
 }

package/yeaft/tools/wait-task.js

@@ -0,0 +1,73 @@
+/**
+ * wait-task.js — Bounded wait for one Session background task.
+ */
+
+import { defineTool } from './types.js';
+import { isTerminalTaskStatus } from '../tasks/store.js';
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_TIMEOUT_MS = 600_000;
+
+export function taskWaitResult(result) {
+  if (!result?.ok) return { error: result?.error || 'Unable to wait for task' };
+  const task = result.task;
+  if (!task) return { error: 'Task state unavailable' };
+  const log = task.log && typeof task.log === 'object' ? task.log : {};
+  const taskResult = task.result && typeof task.result === 'object' ? task.result : {};
+  return {
+    taskId: task.id,
+    status: task.status,
+    terminal: isTerminalTaskStatus(task.status),
+    timedOut: result.timedOut === true,
+    exitCode: Number.isInteger(taskResult.exitCode) ? taskResult.exitCode : null,
+    signal: taskResult.signal || null,
+    resultDelivery: task.resultDelivery,
+    resultConsumed: false,
+    ...(task.runtime?.subAgentId ? { agentId: task.runtime.subAgentId } : {}),
+    ...(task.runtime?.cancelRequestedAt ? { cancelPending: !isTerminalTaskStatus(task.status) } : {}),
+    next_steps: 'Status only; no output was consumed. ReadTaskLog with your last read offset (or tail) for evidence; use WaitAgent for a child result. Do not use log.endOffset as an already-read cursor.',
+    error: taskResult.error || null,
+    log: {
+      ...(log.path ? { path: log.path } : {}),
+      bytes: Number.isFinite(log.bytes) ? log.bytes : 0,
+      endOffset: Number.isFinite(log.bytes) ? log.bytes : 0,
+    },
+  };
+}
+
+export default defineTool({
+  name: 'WaitTask',
+  description: {
+    en: 'Wait for one background task by taskId, up to a bounded timeout. Returns terminal status and a log cursor/reference, never the whole log. This does not cancel or retry the task.',
+    zh: '按 taskId 有界等待一个后台任务。仅返回终态和日志游标/引用，不返回完整日志；不会取消或重试任务。',
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      taskId: { type: 'string', description: { en: 'Task id', zh: '任务 ID' } },
+      sessionId: { type: 'string', description: { en: 'Session id (defaults to current Session)', zh: 'Session ID（默认当前 Session）' } },
+      timeout_ms: { type: 'number', description: { en: `Wait timeout in milliseconds (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS})`, zh: `等待超时毫秒数（默认 ${DEFAULT_TIMEOUT_MS}，最大 ${MAX_TIMEOUT_MS}）` } },
+    },
+    required: ['taskId'],
+  },
+  timeoutMs: 0,
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  cacheWithinQuery: false,
+  duplicateCallPolicy: () => 'allow',
+  async execute(input = {}, ctx = {}) {
+    if (!ctx.taskManager) return JSON.stringify({ error: 'task manager unavailable' });
+    if (ctx.sessionId && input.sessionId && input.sessionId !== ctx.sessionId) {
+      return JSON.stringify({ error: 'Task access is limited to the current Session', errorEffect: 'none' });
+    }
+    if (!input.taskId) return JSON.stringify({ error: 'taskId is required' });
+    const sessionId = input.sessionId || ctx.sessionId || 'default';
+    const timeoutMs = Math.min(Math.max(Number.isFinite(input.timeout_ms) ? input.timeout_ms : DEFAULT_TIMEOUT_MS, 0), MAX_TIMEOUT_MS);
+    const result = await ctx.taskManager.waitForTask(sessionId, input.taskId, {
+      timeoutMs,
+      signal: ctx.signal || null,
+      ownerVpId: ctx.currentVpId || null,
+    });
+    return JSON.stringify(taskWaitResult(result), null, 2);
+  },
+});

package/yeaft/work-center/attachments.js

@@ -392,6 +392,34 @@ function resolveAttachmentPath(root, workItemId, attachment) {
   return { filePath: actualPath, size: stat.size, itemDirectory: itemRoot };
 }
 
+/** Copy verified bytes into a new owner directory; never share source paths. */
+export function cloneWorkItemAttachments(workItem, workItemId, options = {}) {
+  if (!workItem.attachments?.length) return [];
+  const state = openAttachmentDirectory(options.root, workItem.id);
+  try {
+    const files = workItem.attachments.map(attachment => {
+      const storageName = attachment.storageName;
+      if (typeof storageName !== 'string' || !/^[A-Za-z0-9_-]+(?:\.[a-z0-9]{1,10})?$/.test(storageName)) {
+        throw new Error('WorkItem attachment metadata is invalid');
+      }
+      assertDescriptorMatchesPath(state.rootDescriptor, state.attachmentRoot, 'WorkItem attachment root');
+      assertDescriptorMatchesPath(state.itemDescriptor, state.itemDirectory, 'WorkItem attachment owner directory');
+      const fd = openSync(`/proc/self/fd/${state.itemDescriptor}/${storageName}`, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+      try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile()) throw new Error('WorkItem attachment is not a regular file');
+        assertWorkItemAttachmentSize(stat.size);
+        const buffer = readFileSync(fd);
+        if (buffer.length !== Number(attachment.size) || digest(buffer) !== attachment.sha256) {
+          throw new Error('WorkItem attachment changed after creation');
+        }
+        return { name: attachment.name, mimeType: attachment.mimeType, data: buffer.toString('base64') };
+      } finally { closeSync(fd); }
+    });
+    return persistWorkItemAttachments(files, { root: options.root, workItemId });
+  } finally { closeDirectoryState(state); }
+}
+
 export function readWorkItemAttachment(workItem, attachmentId, options = {}) {
   const attachment = Array.isArray(workItem?.attachments)
     ? workItem.attachments.find(item => item?.id === attachmentId)

package/yeaft/work-center/bridge.js

@@ -21,7 +21,7 @@ let serviceFactory = null;
 let featureEnabled = false;
 
 const BROWSER_DETAIL_OPS = new Set([
-  'get', 'create', 'update', 'start', 'cancel', 'resume', 'extend_budget', 'post_work_item_message', 'action_input', 'retry_action', 'guide', 'retry',
+  'get', 'create', 'update', 'update_schedule', 'start', 'cancel', 'resume', 'extend_budget', '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,7 +29,7 @@ const BROWSER_ACTION_DEBUG_OPS = new Set(['get_action_messages', 'get_action_req
 const BROWSER_FILE_FIELDS = Object.freeze({
   create: [
     'title', 'titleSource', 'goal', 'acceptanceCriteria', 'workItemType', 'workDir', 'deliveryTarget', 'deliveryInstructions',
-    'reuseMemory', 'files', 'start',
+    'reuseMemory', 'files', 'start', 'scheduledFor', 'scheduleEnabled', 'recurrence',
   ],
   post_work_item_message: [
     'id', 'clientMessageId', 'text', 'target', 'revision', 'planRevision', 'ledgerRevision',
@@ -96,6 +96,7 @@ async function getSettingsRuntime() {
     defaultWorkDir: ctx.CONFIG?.workDir || process.cwd(),
     workItemAttachments: Array.isArray(ctx.agentCapabilities)
       && ctx.agentCapabilities.includes('work_item_attachments'),
+    recurringSchedules: true,
     defaultStageInstructions: defaultWorkCenterStageInstructions(),
   };
 }

package/yeaft/work-center/controller.js

@@ -164,8 +164,8 @@ export class WorkflowController {
     return detail;
   }
 
-  startScheduled(id, scheduledAt) {
-    return this.store.startWorkItemAtomic(id, workItem => {
+  startScheduled(id, scheduledAt, cloneAttachments = null) {
+    return this.store.dispatchScheduledWorkItem(id, scheduledAt, workItem => {
       const action = initialActionFor(workItem);
       if (workItem.reuseMemory === false) return action;
       const context = this.store.getReusableContext(workItem.workDir, workItem.id);
@@ -174,7 +174,7 @@ export class WorkflowController {
         context,
         instruction: actionInstruction(action, workItem, context, renderSessionContextSnapshot(workItem.sessionContext)),
       };
-    }, { scheduledAt });
+    }, cloneAttachments);
   }
 
   update(id, patch) {

package/yeaft/work-center/durable-model.js

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from 'node:crypto';
+import { withTransaction } from './transaction.js';
 
-export const WORK_CENTER_SCHEMA_VERSION = 41;
+export const WORK_CENTER_SCHEMA_VERSION = 42;
 
 const MIGRATIONS = [
   ['23-conversation-stream', migrateConversationStream],
@@ -22,6 +23,7 @@ const MIGRATIONS = [
   ['39-action-creation-source', migrateActionCreationSource],
   ['40-work-item-schedules', migrateWorkItemSchedules],
   ['41-delivery-instructions', migrateDeliveryInstructions],
+  ['42-recurring-schedules', migrateRecurringSchedules],
 ];
 
 const MIGRATION_ALIASES = new Map([
@@ -83,15 +85,7 @@ function runMigration(db, now, name, migration) {
     db.prepare(`INSERT INTO schema_migrations(name, checksum, applied_at)
       VALUES (?, ?, ?)`).run(name, checksum, now);
   };
-  if (db.isTransaction) return apply();
-  db.exec('BEGIN IMMEDIATE');
-  try {
-    apply();
-    db.exec('COMMIT');
-  } catch (error) {
-    try { db.exec('ROLLBACK'); } catch {}
-    throw error;
-  }
+  return withTransaction(db, apply);
 }
 
 export function migrateDurableWorkCenterModel(db, now = Date.now(), sourceSchemaVersion = 22) {
@@ -568,6 +562,20 @@ function migrateActionClosureAndOutputs(db) {
   `);
 }
 
+function migrateRecurringSchedules(db) {
+  for (const [column, definition] of [
+    ['schedule_recurrence', 'TEXT'],
+    ['schedule_run_count', 'INTEGER NOT NULL DEFAULT 0'],
+    ['schedule_last_work_item_id', 'TEXT'],
+    ['source_schedule_id', 'TEXT'],
+    ['scheduled_occurrence_at', 'INTEGER'],
+  ]) {
+    if (!hasColumn(db, 'work_items', column)) db.exec(`ALTER TABLE work_items ADD COLUMN ${column} ${definition}`);
+  }
+  db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_work_items_schedule_occurrence
+    ON work_items(source_schedule_id, scheduled_occurrence_at) WHERE source_schedule_id IS NOT NULL`);
+}
+
 function migrateWorkItemSchedules(db) {
   for (const [column, definition] of [
     ['schedule_status', 'TEXT'],

package/yeaft/work-center/projection.js

@@ -27,6 +27,24 @@ const MAX_HISTORICAL_BRIEF_CHARS = 256;
 const MAX_CURRENT_BRIEF_BYTES = 8 * 1024;
 export const MAX_WORK_ITEM_BROWSER_DTO_BYTES = 512 * 1024;
 
+function projectSchedule(schedule) {
+  if (!schedule) return null;
+  return {
+    status: schedule.status,
+    scheduledFor: schedule.scheduledFor ?? null,
+    triggeredAt: schedule.triggeredAt ?? null,
+    recurrence: schedule.recurrence || null,
+    runCount: count(schedule.runCount),
+    lastWorkItemId: schedule.lastWorkItemId || null,
+    // Do not forward caller-provided diagnostic text, stack, paths or metadata.
+    lastError: schedule.lastError ? {
+      code: 'schedule_dispatch_failed',
+      message: 'Scheduled execution could not start. The plan will retry automatically; check its configuration and attachments.',
+      at: count(schedule.lastError.at),
+    } : null,
+  };
+}
+
 function jsonByteLength(value) {
   return Buffer.byteLength(JSON.stringify(value), 'utf8');
 }
@@ -1094,7 +1112,9 @@ export function projectWorkItemDetail(detail, options = {}) {
     executionControl: detail.executionControl,
     executionStats: combinedExecutionStats(detail),
     reuseMemory: detail.reuseMemory !== false,
-    schedule: detail.schedule || null,
+    schedule: projectSchedule(detail.schedule),
+    sourceScheduleId: detail.sourceScheduleId || null,
+    scheduledOccurrenceAt: detail.scheduledOccurrenceAt ?? null,
     deliveryTarget: ['response', 'workspace_files', 'pull_request', 'merge'].includes(detail.deliveryTarget)
       ? detail.deliveryTarget : null,
     deliveryInstructions: truncateUtf8(detail.deliveryInstructions || '', 2 * 1024),
@@ -1206,7 +1226,9 @@ export function projectWorkItemSummary(detail) {
       executionStats: combinedExecutionStats(detail),
       executionControl: detail.executionControl,
       origin: detail.origin?.sessionId ? { sessionId: detail.origin.sessionId } : null,
-      schedule: detail.schedule || null,
+      schedule: projectSchedule(detail.schedule),
+      sourceScheduleId: detail.sourceScheduleId || null,
+      scheduledOccurrenceAt: detail.scheduledOccurrenceAt ?? null,
       linkedSessionIds: Array.isArray(detail.linkedSessionIds) ? detail.linkedSessionIds : [],
       attachmentCount: Array.isArray(detail.attachments) ? detail.attachments.length : 0,
       createdAt: detail.createdAt,
@@ -1247,7 +1269,9 @@ export function projectWorkItemSummary(detail) {
     currentAction: projectCurrentActionSummary(action, projectedAction),
     actionStats: projectActionStats(detail, null),
     origin: detail.origin?.sessionId ? { sessionId: detail.origin.sessionId } : null,
-    schedule: detail.schedule || null,
+    schedule: projectSchedule(detail.schedule),
+    sourceScheduleId: detail.sourceScheduleId || null,
+    scheduledOccurrenceAt: detail.scheduledOccurrenceAt ?? null,
     linkedSessionIds: Array.isArray(detail.linkedSessionIds) ? detail.linkedSessionIds : [],
     attachmentCount: Array.isArray(detail.attachments) ? detail.attachments.length : 0,
     createdAt: detail.createdAt,

package/yeaft/work-center/recurrence.js

@@ -0,0 +1,103 @@
+// Calendar computation is pure and independent of dispatch / Agent local timezone.
+// Keep arithmetic and Intl in a bounded, supported date range (1970–2099).
+export const MAX_SCHEDULE_TIMESTAMP = Date.UTC(2100, 0, 1) - 1;
+const DAY = 86_400_000;
+
+export function validateScheduleTimestamp(value, name = 'scheduledFor') {
+  if (!Number.isSafeInteger(value) || value < 0 || value > MAX_SCHEDULE_TIMESTAMP) {
+    throw new Error(`${name} must be epoch milliseconds between 1970 and 2099`);
+  }
+  return value;
+}
+
+export function normalizeRecurrence(value) {
+  if (value == null) return null;
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid recurrence');
+  const allowed = ['frequency', 'timeZone', 'time', 'weekdays', 'dayOfMonth', 'endsAt', 'maxRuns'];
+  if (Object.keys(value).some(key => !allowed.includes(key))) throw new Error('Unknown recurrence field');
+  if (!['daily', 'weekdays', 'weekly', 'monthly'].includes(value.frequency)) throw new Error('Invalid recurrence frequency');
+  if (typeof value.timeZone !== 'string' || value.timeZone.length > 100 || /^[+-]/.test(value.timeZone)) throw new Error('Invalid recurrence timeZone');
+  try { new Intl.DateTimeFormat('en', { timeZone: value.timeZone }); } catch { throw new Error('Invalid recurrence timeZone'); }
+  if (typeof value.time !== 'string' || !/^([01]\d|2[0-3]):[0-5]\d$/.test(value.time)) throw new Error('Invalid recurrence time');
+  if (value.weekdays !== undefined && (!Array.isArray(value.weekdays) || value.weekdays.length > 7
+      || value.weekdays.some(day => !Number.isInteger(day) || day < 0 || day > 6)
+      || new Set(value.weekdays).size !== value.weekdays.length)) throw new Error('Invalid recurrence weekdays');
+  if (value.frequency === 'weekly' && !value.weekdays?.length) throw new Error('Weekly recurrence requires weekdays');
+  if (value.dayOfMonth !== undefined && (!Number.isInteger(value.dayOfMonth) || value.dayOfMonth < 1 || value.dayOfMonth > 31)) throw new Error('Invalid recurrence dayOfMonth');
+  if (value.frequency === 'monthly' && value.dayOfMonth === undefined) throw new Error('Monthly recurrence requires dayOfMonth');
+  if (value.endsAt != null) validateScheduleTimestamp(value.endsAt, 'endsAt');
+  if (value.maxRuns != null && (!Number.isInteger(value.maxRuns) || value.maxRuns < 1 || value.maxRuns > 1000)) throw new Error('Invalid recurrence maxRuns');
+  return { frequency: value.frequency, timeZone: value.timeZone, time: value.time,
+    ...(value.weekdays !== undefined ? { weekdays: [...value.weekdays].sort() } : {}),
+    ...(value.dayOfMonth !== undefined ? { dayOfMonth: value.dayOfMonth } : {}),
+    endsAt: value.endsAt ?? null, maxRuns: value.maxRuns ?? null };
+}
+
+function calendar(recurrence) {
+  const formatter = new Intl.DateTimeFormat('en-GB', { timeZone: recurrence.timeZone,
+    year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23' });
+  const parts = timestamp => Object.fromEntries(formatter.formatToParts(timestamp)
+    .filter(part => part.type !== 'literal').map(part => [part.type, Number(part.value)]));
+  const localEpoch = timestamp => {
+    const p = parts(timestamp);
+    return Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
+  };
+  return { parts, localEpoch };
+}
+
+// Resolve a wall time by trying nearby UTC offsets. Gaps have no matching instant;
+// folds select the earlier instant, so a local date can never execute twice.
+function wallInstant(date, recurrence, localEpoch) {
+  const [hour, minute] = recurrence.time.split(':').map(Number);
+  const wall = date + hour * 3_600_000 + minute * 60_000;
+  const candidates = new Set();
+  for (let hours = -36; hours <= 36; hours += 6) {
+    const probe = wall + hours * 3_600_000;
+    const candidate = wall - (localEpoch(probe) - probe);
+    if (localEpoch(candidate) === wall) candidates.add(candidate);
+  }
+  return candidates.size ? Math.min(...candidates) : null;
+}
+
+function matchesDate(date, recurrence) {
+  const d = new Date(date);
+  const weekday = d.getUTCDay();
+  if (recurrence.frequency === 'weekdays') return weekday > 0 && weekday < 6;
+  if (recurrence.frequency === 'weekly') return recurrence.weekdays.includes(weekday);
+  if (recurrence.frequency === 'monthly') {
+    const last = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate();
+    return d.getUTCDate() === Math.min(recurrence.dayOfMonth, last);
+  }
+  return true;
+}
+
+function findOccurrence(recurrence, timestamp, direction) {
+  validateScheduleTimestamp(timestamp);
+  const { parts, localEpoch } = calendar(recurrence);
+  const p = parts(timestamp);
+  const date = Date.UTC(p.year, p.month - 1, p.day);
+  // Monthly schedules need at most 62 days even around a skipped civil date.
+  // A hard bound also protects dispatch from malformed persisted data.
+  for (let day = 0; day < 370; day++) {
+    const candidateDate = date + day * direction * DAY;
+    if (!matchesDate(candidateDate, recurrence)) continue;
+    const candidate = wallInstant(candidateDate, recurrence, localEpoch);
+    if (candidate == null || candidate < 0 || candidate > MAX_SCHEDULE_TIMESTAMP) continue;
+    if (direction > 0 ? candidate > timestamp : candidate <= timestamp) return candidate;
+  }
+  return null;
+}
+
+export function nextOccurrence(recurrence, after) {
+  return findOccurrence(recurrence, after, 1);
+}
+
+export function latestOccurrence(recurrence, at) {
+  return findOccurrence(recurrence, at, -1);
+}
+
+export function initialOccurrence(recurrence, scheduledFor) {
+  validateScheduleTimestamp(scheduledFor);
+  if (!recurrence || latestOccurrence(recurrence, scheduledFor) === scheduledFor) return scheduledFor;
+  return nextOccurrence(recurrence, scheduledFor);
+}

package/yeaft/work-center/resource-control.js

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
+import { withTransaction } from './transaction.js';
 import { LLMAdapter } from '../llm/adapter.js';
 import { normalizeTokenUsage } from '../llm/usage-accounting.js';
 
@@ -88,10 +89,7 @@ export class WorkCenterResourceControl {
   }
 
   atomic(fn) {
-    if (this.db.isTransaction) return fn();
-    this.db.exec('BEGIN IMMEDIATE');
-    try { const result = fn(); this.db.exec('COMMIT'); return result; }
-    catch (error) { this.db.exec('ROLLBACK'); throw error; }
+    return withTransaction(this.db, fn);
   }
 
   ensure(id) {

package/yeaft/work-center/service.js

@@ -1,3 +1,4 @@
+import { normalizeRecurrence, validateScheduleTimestamp } from './recurrence.js';
 import { realpathSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -6,6 +7,7 @@ import { WorkflowController } from './controller.js';
 import { WorkItemWatcher } from './watcher.js';
 import {
   appendWorkItemAttachments,
+  cloneWorkItemAttachments,
   persistWorkItemAttachments,
   readWorkItemAttachment,
   removeWorkItemAttachmentFiles,
@@ -114,6 +116,7 @@ export class WorkCenterService {
         ...(await this.runtimeInfoProvider()),
         defaultStageInstructions: defaultWorkCenterStageInstructions(),
         workItemTypes: listWorkItemTypeTemplates(settings),
+        recurringSchedules: true,
       };
     };
     this.ownerBootId = options.ownerBootId || randomUUID();
@@ -255,10 +258,14 @@ export class WorkCenterService {
             workItemId,
           });
           const scheduledFor = payload.scheduledFor == null || payload.scheduledFor === ''
-            ? null : Number(payload.scheduledFor);
+            ? null : payload.scheduledFor;
           if (scheduledFor != null && (!Number.isSafeInteger(scheduledFor) || scheduledFor <= this.now())) {
             throw new Error('scheduledFor must be in the future');
           }
+          if (scheduledFor != null) validateScheduleTimestamp(scheduledFor);
+          if (payload.scheduleEnabled !== undefined && typeof payload.scheduleEnabled !== 'boolean') throw new Error('scheduleEnabled must be a boolean');
+          const recurrence = normalizeRecurrence(payload.recurrence);
+          if (recurrence && scheduledFor == null) throw new Error('recurrence requires scheduledFor');
           const shouldStart = scheduledFor == null
             && (payload.start === undefined ? settings.startImmediately : payload.start !== false);
           const goal = requiredString(payload.goal, 'goal');
@@ -308,6 +315,7 @@ export class WorkCenterService {
             schedule: scheduledFor == null ? null : {
               status: payload.scheduleEnabled === false ? 'paused' : 'scheduled',
               scheduledFor,
+              recurrence,
             },
             start: false,
           });
@@ -745,8 +753,27 @@ export class WorkCenterService {
   #scanSchedules() {
     const now = this.now();
     for (const id of this.store.listDueScheduledWorkItemIds(now)) {
-      const detail = this.controller.startScheduled(id, now);
-      if (detail) this.#emit({ type: 'work_item.schedule_triggered', workItem: detail });
+      const createdAttachmentOwners = [];
+      try {
+        const before = this.store.getWorkItem(id);
+        const detail = this.controller.startScheduled(id, now, (source, occurrenceId) => {
+          const attachments = cloneWorkItemAttachments(source, occurrenceId, { root: this.attachmentRoot });
+          createdAttachmentOwners.push(occurrenceId);
+          return attachments;
+        });
+        const source = this.store.getWorkItemDetail(id);
+        if (detail) this.#emit({ type: 'work_item.schedule_triggered', workItem: source });
+        else if (source && source.revision !== before?.revision) {
+          this.#emit({ type: 'work_item.schedule_advanced', workItem: source });
+        }
+        if (detail && detail.id !== id) this.#emit({ type: 'work_item.created', workItem: detail });
+      } catch {
+        for (const owner of createdAttachmentOwners) {
+          if (!this.store.getWorkItem(owner)) removeWorkItemAttachments(this.attachmentRoot, owner);
+        }
+        const workItem = this.store.recordScheduleFailure(id);
+        if (workItem) this.#emit({ type: 'work_item.schedule_failed', workItem });
+      }
     }
   }