@yeaft/webchat-agent 1.0.649 → 1.0.650

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.649",
+  "version": "1.0.650",
   "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/sessions/scheduled-task-definition.js

@@ -0,0 +1,74 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { initialOccurrence, nextOccurrence, normalizeRecurrence, validateScheduleTimestamp } from '../work-center/recurrence.js';
+
+const FIELDS = ['prompt', 'enabled', 'notify', 'trigger'];
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+  }
+  return value;
+}
+
+function configKey(task) {
+  return JSON.stringify(canonical({ prompt: task.prompt, enabled: task.enabled,
+    notify: task.notify !== false, trigger: task.trigger }));
+}
+
+/** Legacy definitions get a stable config-only revision without a read-time disk write. */
+export function scheduledTaskRevision(task) {
+  if (typeof task._revision === 'string' && task._revision) return task._revision;
+  return `legacy:${createHash('sha256').update(configKey(task)).digest('hex')}`;
+}
+
+/** Validate external task definitions only; runtime fields are never writable over the wire. */
+export function normalizeScheduledTask(value, previous = null) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('task must be an object');
+  if (Object.keys(value).some(key => !FIELDS.includes(key))) throw new Error('Unknown or read-only task field');
+  const input = previous ? { ...publicScheduledTask(previous), ...value } : value;
+  if (typeof input.prompt !== 'string' || !input.prompt.trim() || input.prompt.length > 65536) {
+    throw new Error('task.prompt must be non-empty text of at most 65536 characters');
+  }
+  if (typeof input.enabled !== 'boolean') throw new Error('task.enabled must be a boolean');
+  if (input.notify !== undefined && typeof input.notify !== 'boolean') throw new Error('task.notify must be a boolean');
+  const trigger = input.trigger;
+  if (!trigger || typeof trigger !== 'object' || Array.isArray(trigger)) throw new Error('Invalid task.trigger');
+  let normalizedTrigger;
+  if (trigger.type === 'manual') {
+    if (Object.keys(trigger).some(key => key !== 'type')) throw new Error('Unknown manual trigger field');
+    normalizedTrigger = { type: 'manual' };
+  } else if (trigger.type === 'schedule') {
+    if (Object.keys(trigger).some(key => !['type', 'scheduledFor', 'recurrence'].includes(key))) throw new Error('Unknown schedule trigger field');
+    normalizedTrigger = { type: 'schedule', scheduledFor: validateScheduleTimestamp(trigger.scheduledFor),
+      recurrence: normalizeRecurrence(trigger.recurrence) };
+  } else throw new Error('Invalid task.trigger type');
+  const next = { prompt: input.prompt.trim(), enabled: input.enabled, notify: input.notify ?? true,
+    trigger: normalizedTrigger, nextRunAt: null, lastRun: previous?.lastRun ?? null };
+  const sameTrigger = previous && JSON.stringify(previous.trigger) === JSON.stringify(next.trigger);
+  if (sameTrigger) {
+    next._scheduledRuns = previous._scheduledRuns || 0;
+    next.nextRunAt = previous.nextRunAt;
+  } else {
+    next.nextRunAt = next.trigger.type === 'schedule'
+      ? initialOccurrence(next.trigger.recurrence, next.trigger.scheduledFor) : null;
+  }
+  if (next.trigger.recurrence?.endsAt != null && next.nextRunAt > next.trigger.recurrence.endsAt) next.nextRunAt = null;
+  next._revision = previous && configKey(previous) === configKey(next) ? scheduledTaskRevision(previous) : randomUUID();
+  return next;
+}
+
+/** Explicit, idempotent projection keeps durable scheduler bookkeeping out of Session snapshots. */
+export function publicScheduledTask(task) {
+  return { prompt: task.prompt, enabled: task.enabled, notify: task.notify !== false,
+    trigger: structuredClone(task.trigger), nextRunAt: task.nextRunAt ?? null,
+    lastRun: task.lastRun ? structuredClone(task.lastRun) : null,
+    revision: typeof task.revision === 'string' && !task._revision ? task.revision : scheduledTaskRevision(task) };
+}
+
+export function advanceScheduledTask(task, after) {
+  const recurrence = task.trigger.recurrence;
+  if (!recurrence || (recurrence.maxRuns != null && (task._scheduledRuns || 0) >= recurrence.maxRuns)) return null;
+  const next = nextOccurrence(recurrence, after);
+  return next != null && (recurrence.endsAt == null || next <= recurrence.endsAt) ? next : null;
+}

package/yeaft/sessions/scheduled-task-scheduler.js

@@ -0,0 +1,257 @@
+import { lstatSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { validateSessionId } from './ids.js';
+import { loadSessionMeta, SESSION_META_FILE } from './session-store.js';
+import { writeAtomic } from '../storage/atomic.js';
+import { advanceScheduledTask, normalizeScheduledTask, publicScheduledTask } from './scheduled-task-definition.js';
+
+// Internal-only ingress fence. Browser JSON cannot supply or bypass this hook.
+export const SCHEDULED_TASK_DISPATCH_GUARD = Symbol('scheduled-task-dispatch-guard');
+const POLL_MS = 1000;
+
+/** Instance-owned scheduler. All metadata transitions are synchronous, fresh-read,
+ * atomic replacements; no openSession handle can create a deleted directory.
+ * dispatch only accepts/routes input. isActive owns the full Session lifecycle,
+ * including fanout, route-forward, pending classifications and model task reentry.
+ */
+export class ScheduledTaskScheduler {
+  constructor({ yeaftDir, dispatch, isActive, canDispatch = () => true, onChange = () => {}, notify = () => {}, now = Date.now,
+    warn = error => console.warn('[ScheduledTasks]', error?.message || error) }) {
+    this.yeaftDir = resolve(yeaftDir);
+    this.dispatch = dispatch;
+    this.isActive = isActive;
+    this.canDispatch = canDispatch;
+    this.waitingForContext = new Set();
+    this.onChange = onChange;
+    this.notify = notify;
+    this.now = now;
+    this.warn = warn;
+    this.runs = new Map();
+    this.retryAfter = new Map();
+    this.timer = null;
+  }
+
+  read(sessionId) {
+    if (!validateSessionId(sessionId).ok) throw new Error('Invalid Session id');
+    const root = join(this.yeaftDir, 'sessions');
+    const dir = join(root, sessionId);
+    const path = join(dir, SESSION_META_FILE);
+    try {
+      const rootStat = lstatSync(root), stat = lstatSync(dir), fileStat = lstatSync(path);
+      if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || !stat.isDirectory()
+        || stat.isSymbolicLink() || !fileStat.isFile() || fileStat.isSymbolicLink()) throw new Error('Invalid Session path');
+      const meta = loadSessionMeta(dir);
+      if (!meta || meta.id !== sessionId) throw new Error('Session not found');
+      return { meta, path, identity: `${stat.dev}:${stat.ino}:${meta.createdAt}` };
+    } catch { throw new Error('Session not found or unsafe Session path'); }
+  }
+
+  ids() {
+    const root = join(this.yeaftDir, 'sessions');
+    try {
+      const stat = lstatSync(root);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) return [];
+      return readdirSync(root).filter(id => validateSessionId(id).ok);
+    } catch (error) {
+      if (error.code !== 'ENOENT') this.warn(error);
+      return [];
+    }
+  }
+
+  save(row) {
+    // Recheck identity rather than creating directories if deletion/recreation won.
+    if (this.read(row.meta.id).identity !== row.identity) throw new Error('Session changed');
+    row.meta.metadataUpdatedAt = new Date(this.now()).toISOString();
+    writeAtomic(row.path, `${JSON.stringify(row.meta, null, 2)}\n`);
+  }
+
+  changed() {
+    try { this.onChange(); } catch (error) { this.warn(error); }
+  }
+
+  snapshot(meta) {
+    return { ...meta, ...(meta.task ? { task: publicScheduledTask(meta.task) } : {}) };
+  }
+
+  /** Compare the caller's config revision against fresh metadata, never runtime state. */
+  update(sessionId, patch, expectedRevision) {
+    const row = this.read(sessionId);
+    if (!row.meta.task) throw new Error('Session has no task');
+    if (typeof expectedRevision !== 'string' || expectedRevision !== row.meta.task._revision) {
+      throw Object.assign(new Error('Task changed; refresh before editing'), { code: 'task_conflict' });
+    }
+    row.meta.task = normalizeScheduledTask(patch, row.meta.task);
+    this.save(row);
+    this.changed();
+    return this.snapshot(row.meta);
+  }
+
+  start() {
+    if (this.timer) return this;
+    for (const id of this.ids()) {
+      try { this.recover(this.read(id), true); } catch (error) { this.backoff(id, error); }
+    }
+    this.timer = setInterval(() => { this.tick().catch(error => this.warn(error)); }, POLL_MS);
+    this.timer.unref?.();
+    return this;
+  }
+
+  recover(row, skipMissed = false) {
+    const task = row.meta.task;
+    if (!task) return;
+    let dirty = false, interrupted = false;
+    // Never replay a persisted running attempt: effects may already have occurred.
+    if (task.lastRun?.status === 'running') {
+      // A newer edited trigger or a manual run must not consume a future one-shot.
+      if (task.lastRun.trigger === 'schedule' && task.trigger.type === 'schedule'
+        && !task.trigger.recurrence && task.nextRunAt != null && task.nextRunAt <= task.lastRun.startedAt) task.nextRunAt = null;
+      task.lastRun = { ...task.lastRun, status: 'interrupted', finishedAt: this.now(), error: 'Agent restarted during execution' };
+      interrupted = true;
+      dirty = true;
+    }
+    // Recurring downtime is skipped, including an occurrence exactly at boot.
+    if (skipMissed && this.canDispatch(row.meta.id) && task.trigger.type === 'schedule' && task.trigger.recurrence
+      && task.nextRunAt != null && task.nextRunAt <= this.now()) {
+      task.nextRunAt = advanceScheduledTask(task, this.now());
+      dirty = true;
+    }
+    if (dirty) { this.save(row); this.changed(); }
+    if (interrupted && task.notify !== false) {
+      try { this.notify({ type: 'scheduled_task_notification', sessionId: row.meta.id, runId: task.lastRun.id,
+        status: 'interrupted', taskName: row.meta.name, error: task.lastRun.error }); } catch (error) { this.warn(error); }
+    }
+  }
+
+  stop() {
+    clearInterval(this.timer);
+    this.timer = null;
+    this.runs.clear();
+    this.waitingForContext.clear();
+  }
+
+  backoff(id, error) {
+    this.retryAfter.set(id, this.now() + 30_000);
+    this.warn(error);
+  }
+
+  assertReady(sessionId) {
+    if (!this.canDispatch(sessionId)) {
+      throw Object.assign(new Error('Waiting for authoritative Project context from Server; retry after synchronization'),
+        { code: 'project_context_unavailable' });
+    }
+  }
+
+  run(sessionId, trigger = 'manual') {
+    const row = this.read(sessionId), task = row.meta.task;
+    if (!task) throw new Error('Session has no task');
+    this.assertReady(sessionId);
+    if (this.runs.has(sessionId) || task.lastRun?.status === 'running' || this.isActive(sessionId)) throw new Error('Session is busy or task is already running');
+    if (trigger === 'schedule' && (!task.enabled || task.trigger.type !== 'schedule'
+      || task.nextRunAt == null || task.nextRunAt > this.now())) throw new Error('Task is no longer due');
+    // Validate persisted definitions without trusting externally edited runtime fields.
+    normalizeScheduledTask({ prompt: task.prompt, enabled: task.enabled, notify: task.notify, trigger: task.trigger });
+    const run = { id: randomUUID(), status: 'running', trigger, startedAt: this.now(), finishedAt: null };
+    task.lastRun = run;
+    if (trigger === 'schedule') {
+      task._scheduledRuns = (task._scheduledRuns || 0) + 1;
+      task.nextRunAt = advanceScheduledTask(task, this.now());
+    }
+    this.save(row); // A durable claim must precede any execution side effect.
+    const active = { id: run.id, identity: row.identity, revision: task._revision, routed: false, terminal: false, error: null, interrupted: false };
+    this.runs.set(sessionId, active);
+    const guard = () => {
+      this.assertReady(sessionId);
+      const fresh = this.read(sessionId);
+      if (fresh.identity !== active.identity || fresh.meta.task?.lastRun?.id !== active.id
+        || fresh.meta.task?._revision !== active.revision) throw new Error('Task changed before dispatch');
+    };
+    try {
+      guard();
+      const result = this.dispatch({ type: 'yeaft_session_send', sessionId, id: run.id, text: task.prompt,
+        [SCHEDULED_TASK_DISPATCH_GUARD]: guard });
+      Promise.resolve(result).then(() => { active.routed = true; }, error => {
+        active.error = error?.message || String(error); active.routed = true;
+      });
+    } catch (error) {
+      active.error = error?.message || String(error); active.routed = true;
+    }
+    this.changed();
+    return this.snapshot(row.meta);
+  }
+
+  observe(sessionId, event) {
+    const active = this.runs.get(sessionId);
+    if (!active) return;
+    if (event.type === 'error') active.error = event.message || event.error?.message || String(event.error || 'Execution failed');
+    if (event.type === 'vp_turn_end') {
+      active.terminal = true;
+      if (event.reason === 'errored') active.error = event.detail?.message || active.error || 'Execution failed';
+      if (event.reason === 'aborted') active.interrupted = true;
+    }
+  }
+
+  finish(id, active) {
+    let row;
+    try { row = this.read(id); } catch { this.runs.delete(id); return; }
+    const task = row.meta.task;
+    if (row.identity !== active.identity || task?.lastRun?.id !== active.id) { this.runs.delete(id); return; }
+    const status = active.error ? 'failed' : active.interrupted ? 'interrupted' : active.terminal ? 'completed' : 'failed';
+    const error = active.error || (status === 'failed' ? 'Session produced no terminal execution' : null);
+    task.lastRun = { ...task.lastRun, status, finishedAt: this.now(), ...(error ? { error } : {}) };
+    // Completion never consumes or moves a schedule, especially for manual runs.
+    // Missed recurring occurrences belong to tick's explicit busy-Session policy.
+    this.save(row);
+    this.runs.delete(id);
+    this.changed();
+    if (task.notify !== false) {
+      try { this.notify({ type: 'scheduled_task_notification', sessionId: id, runId: active.id, status,
+        taskName: row.meta.name, ...(error ? { error } : {}) }); } catch (error) { this.warn(error); }
+    }
+  }
+
+  async tick() {
+    // Inspect due occurrences before retiring tracked runs: an occurrence elapsed
+    // during a manual run is busy/missed, even if its runtime just became idle.
+    // Manual run/finish themselves never change nextRunAt or _scheduledRuns.
+    for (const id of this.ids()) {
+      if ((this.retryAfter.get(id) || 0) > this.now()) continue;
+      try {
+        const row = this.read(id), task = row.meta.task;
+        const tracked = this.runs.get(id);
+        if (tracked && (row.identity !== tracked.identity || task?.lastRun?.id !== tracked.id)) this.runs.delete(id);
+        // Retry boot recovery after a transient atomic-write failure.
+        if (task?.lastRun?.status === 'running' && !this.runs.has(id)) { this.recover(row, true); continue; }
+        if (task?.enabled && task.trigger.type === 'schedule' && task.nextRunAt != null && task.nextRunAt <= this.now()) {
+          if (!this.canDispatch(id)) {
+            if (!this.waitingForContext.has(id)) {
+              this.waitingForContext.add(id);
+              this.warn(new Error(`Session ${id}: waiting for authoritative Project context from Server`));
+            }
+            continue; // Unknown is not 'no Project': do not claim, fail or consume the occurrence.
+          }
+          this.waitingForContext.delete(id);
+          const busy = this.runs.has(id) || this.isActive(id);
+          // One minute of grace tolerates timer jitter. Older recurring
+          // occurrences (or ones blocked by an active Session) are missed, not queued.
+          if (task.trigger.recurrence && (busy || this.now() - task.nextRunAt > 60_000)) {
+            task.nextRunAt = advanceScheduledTask(task, this.now());
+            this.save(row);
+            this.changed();
+          } else if (!busy) this.run(id, 'schedule');
+        }
+      } catch (error) { this.backoff(id, error); }
+    }
+    for (const [id, active] of this.runs) {
+      if ((this.retryAfter.get(id) || 0) > this.now()) continue;
+      try {
+        // Drop removed/archived/replaced Sessions even if an old engine stays alive.
+        const fresh = this.read(id);
+        if (fresh.identity !== active.identity || fresh.meta.task?.lastRun?.id !== active.id) { this.runs.delete(id); continue; }
+        if (active.routed && !this.isActive(id)) this.finish(id, active);
+      } catch (error) {
+        try { this.read(id); this.backoff(id, error); } catch { this.runs.delete(id); }
+      }
+    }
+  }
+}

package/yeaft/sessions/session-crud.js

@@ -52,6 +52,7 @@ import { isAbsolute, join, resolve } from 'path';
 import {
   openSession, createSession, loadSessionMeta,
 } from './session-store.js';
+import { normalizeScheduledTask, publicScheduledTask } from './scheduled-task-definition.js';
 import { addVp as rosterAdd, removeVp as rosterRemove, setDefaultVp } from './roster.js';
 import { seedDefaultSession, DEFAULT_SESSION_ID } from './seed-default.js';
 import { nextSessionId, validateVpId, isReservedVpId } from './ids.js';
@@ -511,6 +512,8 @@ export function ensureDefaultSessionIfEmpty(yeaftDir, options = {}) {
  */
 export function createSessionFromSpec(yeaftDir, spec, options = {}) {
   const input = spec || {};
+  // Task validation precedes discovery repair and every filesystem mutation.
+  if (input.task !== undefined) normalizeScheduledTask(input.task);
   const normalizedWorkDir = normalizeWorkDir(input.workDir);
   const workspaceKey = canonicalWorkspaceKey(normalizedWorkDir);
   ensureSessionManifestReady(yeaftDir);
@@ -553,6 +556,7 @@ export function createSessionFromSpec(yeaftDir, spec, options = {}) {
 
   const handle = createSession(root, {
     id, name, roster, defaultVpId, workDir: normalizedWorkDir, workspaceKey,
+    ...(input.task !== undefined ? { task: input.task } : {}),
   });
   const meta = handle.getMeta();
   handle.close();
@@ -998,6 +1002,7 @@ export function snapshotSessions(yeaftDir) {
   // render the effective model without re-querying.
   for (const meta of byId.values()) {
     meta.config = loadSessionConfig(yeaftDir, meta.id);
+    if (meta.task) meta.task = publicScheduledTask(meta.task);
   }
   return Array.from(byId.values()).sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')));
 }

package/yeaft/sessions/session-store.js

@@ -30,6 +30,8 @@ import { join } from 'path';
 import { writeAtomic, openLog } from '../storage/index.js';
 import { nextMsgId, isReservedVpId, ReservedVpIdError, validateVpId, InvalidVpIdError } from './ids.js';
 
+import { normalizeScheduledTask, scheduledTaskRevision } from './scheduled-task-definition.js';
+
 export const SESSION_META_FILE = 'session.json';
 export const LEGACY_GROUP_META_FILE = 'group.json';
 const MESSAGES_DIR = 'messages';
@@ -48,12 +50,6 @@ export function openSession(sessionsRoot, sessionId) {
   const dir = join(sessionsRoot, sessionId);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
-  let meta = loadSessionMeta(dir);
-  if (!meta) {
-    // Fresh session — caller must call createSession() next; we return a handle
-    // with meta=null so createSession() can write the initial file.
-  }
-
   const messagesDir = join(dir, MESSAGES_DIR);
   if (!existsSync(messagesDir)) mkdirSync(messagesDir, { recursive: true });
   const log = openLog(messagesDir);
@@ -61,12 +57,21 @@ export function openSession(sessionsRoot, sessionId) {
   return {
     dir,
     id: sessionId,
-    /** Return current meta (reads fresh from memory after last save). */
-    getMeta() { return meta ? structuredClone(meta) : null; },
-    /** Overwrite session.json atomically. */
+    /** Read fresh: coordinators may retain this handle across external CRUD. */
+    getMeta() { return loadSessionMeta(dir); },
+    /**
+     * Save Session metadata atomically. After creation, the scheduler exclusively
+     * owns task definitions/runtime. Preserve its fresh on-disk value even when
+     * a caller retained an older metadata snapshot across a run or task edit.
+     */
     saveMeta(next) {
       validateMeta(next);
-      meta = next;
+      const current = loadSessionMeta(dir);
+      const meta = structuredClone(next);
+      if (current) {
+        if (Object.hasOwn(current, 'task')) meta.task = current.task;
+        else delete meta.task;
+      }
       writeAtomic(join(dir, SESSION_META_FILE), JSON.stringify(meta, null, 2));
     },
     /**
@@ -121,6 +126,7 @@ export function openSession(sessionsRoot, sessionId) {
  */
 export function createSession(sessionsRoot, spec) {
   if (!spec || !spec.id) throw new Error('createSession: spec.id required');
+  const task = spec.task === undefined ? undefined : normalizeScheduledTask(spec.task);
   const h = openSession(sessionsRoot, spec.id);
   if (h.getMeta()) {
     throw new Error(`session ${spec.id} already exists`);
@@ -138,6 +144,7 @@ export function createSession(sessionsRoot, spec) {
   }
   const meta = {
     id: spec.id,
+    ...(task ? { task } : {}),
     name: spec.name || spec.id,
     roster,
     defaultVpId: spec.defaultVpId || null,
@@ -168,6 +175,7 @@ export function loadSessionMeta(dir) {
     if (typeof parsed.announcement !== 'string') parsed.announcement = '';
     if (typeof parsed.workDir !== 'string') parsed.workDir = '';
     if (typeof parsed.workspaceKey !== 'string') parsed.workspaceKey = '';
+    if (parsed.task) parsed.task._revision = scheduledTaskRevision(parsed.task);
     return parsed;
   } catch {
     return null;

package/yeaft/web-bridge.js

@@ -15,7 +15,7 @@
  *      style strips on incoming/outgoing message bodies.
  */
 
-import { delimiter, join } from 'node:path';
+import { delimiter, join, resolve } from 'node:path';
 import { COLLAB_TOOL_POLICY } from './tools/registry.js';
 import { createFullRegistry } from './tools/index.js';
 import { existsSync, lstatSync } from 'node:fs';
@@ -102,6 +102,8 @@ import {
 } from './sessions/session-crud.js';
 import { openSession, loadSessionMeta, SESSION_META_FILE } from './sessions/session-store.js';
 import { validateSessionId } from './sessions/ids.js';
+import { publicScheduledTask } from './sessions/scheduled-task-definition.js';
+import { ScheduledTaskScheduler, SCHEDULED_TASK_DISPATCH_GUARD } from './sessions/scheduled-task-scheduler.js';
 import { loadSessionConfig, normalizeSessionConfig, resolveSessionConfig, SessionConfigError } from './sessions/session-config.js';
 import { updateSessionConfig } from './sessions/session-crud.js';
 import { createCoordinator } from './sessions/coordinator.js';
@@ -2693,6 +2695,7 @@ function resolveGroupDefaultVpId(sessionId) {
 }
 
 function sendSessionOutputFrame(data, { sessionId, chatId, vpId, turnId, threadId, perfTraceId } = {}) {
+  scheduledTaskScheduler?.observe(sessionId, data);
   const resolvedVpId = vpId || (sessionId ? resolveGroupDefaultVpId(sessionId) : null);
   sendToServer({
     type: 'yeaft_output',
@@ -3156,6 +3159,7 @@ function mergedStatusForProjectRuntime(runtime, ownerSession = session) {
 
 /** Send a Yeaft Session metadata event over the legacy-compatible envelope. */
 function sendSessionEvent(event, { sessionId, chatId, vpId, turnId, threadId, requestId, requestClientId, perfTraceId, conversationId = yeaftConversationId } = {}) {
+  scheduledTaskScheduler?.observe(sessionId || event?.sessionId, event);
   sendToServer({
     type: 'yeaft_output',
     conversationId,
@@ -3498,11 +3502,12 @@ async function sharedProjectContext(yeaftDir, sessionId, options = {}) {
   return context;
 }
 
-function sendSessionCrudResult(payload) {
+function sendSessionCrudResult(payload, envelope) {
   const next = payload && payload.ok && Array.isArray(payload.sessions)
     ? { ...payload, sessions: decorateSessionsWithRuntimeState(payload.sessions) }
     : payload;
-  sendSessionEvent({ type: 'session_crud_result', ...next });
+  const projected = next?.session?.task ? { ...next, session: { ...next.session, task: publicScheduledTask(next.session.task) } } : next;
+  sendSessionEvent({ type: 'session_crud_result', ...projected }, envelope);
 }
 
 function isMcpServerEnabled(name, plugins = session?.config?.plugins) {
@@ -3708,6 +3713,72 @@ function sendSessionSnapshotBroadcast() {
  */
 export { sendSessionSnapshotBroadcast as broadcastYeaftSessionSnapshotEager };
 
+let scheduledTaskScheduler = null;
+
+/** Server authority is connection-scoped; cached context must not survive reconnect. */
+export function invalidateYeaftProjectContexts() {
+  projectContextBySession.clear();
+}
+
+function scheduledSessionReady(sessionId) {
+  return ctx.ws?.readyState === 1 && projectContextBySession.has(sessionId);
+}
+
+/** Start once per Agent data root, not per browser subscription or reconnect. */
+export function startYeaftScheduledTasks() {
+  const yeaftDir = ctx.CONFIG?.yeaftDir;
+  if (!yeaftDir) return null;
+  if (scheduledTaskScheduler?.yeaftDir !== resolve(yeaftDir)) {
+    scheduledTaskScheduler?.stop();
+    scheduledTaskScheduler = new ScheduledTaskScheduler({
+      yeaftDir,
+      canDispatch: scheduledSessionReady,
+      dispatch: msg => {
+        const guard = msg[SCHEDULED_TASK_DISPATCH_GUARD];
+        const input = { ...msg, projectContext: projectContextBySession.get(msg.sessionId) };
+        input[SCHEDULED_TASK_DISPATCH_GUARD] = () => {
+          guard(); // Includes readiness plus the persisted claim/config/identity checks.
+          // Runtime boot may have spanned a Project edit or reconnect. Use the
+          // latest authority at ingress, never the pre-boot context or legacy cache.
+          input.projectContext = projectContextBySession.get(msg.sessionId);
+        };
+        return handleYeaftSessionSend(input);
+      },
+      isActive: sessionHasActiveWork,
+      onChange: sendSessionSnapshotBroadcast,
+      notify: event => sendSessionEvent(event, { sessionId: event.sessionId }),
+    });
+  }
+  return scheduledTaskScheduler.start();
+}
+
+export function stopYeaftScheduledTasks() {
+  scheduledTaskScheduler?.stop();
+  scheduledTaskScheduler = null;
+}
+
+export function handleYeaftScheduledTask(msg = {}) {
+  const op = msg.op === 'update' ? 'update_task' : 'run_task';
+  const requestId = msg.requestId || null;
+  const respond = payload => sendSessionEvent({ type: 'session_crud_result', op, requestId, ...payload },
+    { requestId, requestClientId: msg._requestClientId });
+  try {
+    if (!['update', 'run'].includes(msg.op)) throw new Error('Invalid scheduled task operation');
+    if (msg.op === 'run' && msg.task !== undefined) throw new Error('task is only accepted for update');
+    if (!validateSessionId(msg.sessionId).ok) throw new Error('Invalid Session id');
+    if (msg.op === 'run' && Object.hasOwn(msg, 'projectContext')) {
+      handleYeaftProjectContextSync({ contexts: [{ sessionId: msg.sessionId, projectContext: msg.projectContext }] });
+    }
+    const scheduler = startYeaftScheduledTasks();
+    if (!scheduler) throw new Error('No Yeaft directory configured');
+    const result = msg.op === 'update' ? scheduler.update(msg.sessionId, msg.task, msg.expectedRevision) : scheduler.run(msg.sessionId);
+    result.config = loadSessionConfig(scheduler.yeaftDir, msg.sessionId);
+    respond({ ok: true, session: result });
+  } catch (error) {
+    respond({ ok: false, error: { code: error?.code || 'scheduled_task_error', sessionId: msg.sessionId, message: error?.message || String(error) } });
+  }
+}
+
 function sendSessionRosterChanged(session) {
   if (!session) return;
   const payload = {
@@ -3749,6 +3820,7 @@ export function handleYeaftProjectContextSync(msg) {
     const sessionId = typeof row?.sessionId === 'string' ? row.sessionId.trim() : '';
     if (!sessionId) continue;
     const projectContext = normalizeProjectContext(row.projectContext, sessionId);
+    if (!projectContext && row.projectContext !== null) continue;
     projectContextBySession.set(sessionId, projectContext || {
       projectId: null,
       projectName: null,
@@ -3801,15 +3873,18 @@ export function handleYeaftProjectMutation(msg) {
 export function handleYeaftCreateSession(msg) {
   const requestId = msg && msg.requestId;
   const payload = (msg && msg.payload) || {};
+  // Server authenticates/overwrites the requester identity. Task create results
+  // (including validation failures) must be routed back to that browser only.
+  const envelope = payload.task !== undefined ? { requestId, requestClientId: msg?._requestClientId } : undefined;
   try {
     const yeaftDir = ctx.CONFIG?.yeaftDir;
     const group = createSessionFromSpec(yeaftDir, payload, configuredVpPaths());
     recordAgentSessionCreated();
     group.config = loadSessionConfig(yeaftDir, group.id);
-    sendSessionCrudResult({ op: 'create', requestId, ok: true, session: group });
+    sendSessionCrudResult({ op: 'create', requestId, ok: true, session: group }, envelope);
     sendSessionSnapshotBroadcast();
   } catch (err) {
-    sendSessionCrudResult({ op: 'create', requestId, ok: false, error: sessionErrorPayload(err) });
+    sendSessionCrudResult({ op: 'create', requestId, ok: false, error: sessionErrorPayload(err) }, envelope);
   }
 }
 
@@ -5028,6 +5103,23 @@ async function runYeaftSessionSend(msg) {
   const sessionId = (typeof msg.sessionId === 'string' && msg.sessionId.trim())
     ? msg.sessionId.trim()
     : 'grp_default';
+  // Cache authority before the first await: an accepted send from the previous
+  // transport must not repopulate stale context after disconnect invalidation.
+  const hasInboundProjectContext = Object.prototype.hasOwnProperty.call(msg, 'projectContext');
+  const inboundProjectContext = normalizeProjectContext(msg.projectContext, sessionId);
+  if (hasInboundProjectContext) {
+    projectContextBySession.set(sessionId, inboundProjectContext || {
+      projectId: null,
+      projectName: null,
+      projectInstruction: '',
+      sessionIds: [],
+    });
+  } else {
+    // An old Server does not know this field. Drop any context cached from a
+    // newer Server before falling back to this Agent's legacy projects.json.
+    projectContextBySession.delete(sessionId);
+  }
+
   const perfTraceId = typeof msg.perfTraceId === 'string' && msg.perfTraceId.trim()
     ? msg.perfTraceId.trim()
     : null;
@@ -5128,6 +5220,9 @@ async function dispatchAcceptedSessionSend({
 }) {
   const ensureSessionStart = perfNowMs();
   await ensureSessionLoaded({ sessionMeta: sessionMetaForRuntime, perfTraceId });
+  // Runtime boot may await I/O. Re-read the claim immediately before ingress
+  // so edits, disable, archive or deletion during boot cannot execute stale work.
+  msg[SCHEDULED_TASK_DISPATCH_GUARD]?.();
   if (!sessionHandle) {
     try {
       const dir = join(sessionRoot, sessionId);
@@ -5244,21 +5339,6 @@ async function dispatchAcceptedSessionSend({
     },
   });
 
-  const hasInboundProjectContext = Object.prototype.hasOwnProperty.call(msg, 'projectContext');
-  const inboundProjectContext = normalizeProjectContext(msg.projectContext, sessionId);
-  if (hasInboundProjectContext) {
-    projectContextBySession.set(sessionId, inboundProjectContext || {
-      projectId: null,
-      projectName: null,
-      projectInstruction: '',
-      sessionIds: [],
-    });
-  } else {
-    // An old Server does not know this field. Drop any context cached from a
-    // newer Server before falling back to this Agent's legacy projects.json.
-    projectContextBySession.delete(sessionId);
-  }
-
   // Ingest user text. The coordinator persists, applies mention/fanout
   // rules, and calls deliver() (== enqueueForVp) for each chosen VP —
   // which both (a) emits vp_typing_start and (b) ensures a driver runs.