@ixo/oracle-runtime-workers 0.12.0 → 0.15.0

package/src/tasks/scheduler.ts

@@ -15,7 +15,10 @@
  * Task records live in the USER'S OWN SQLite database (`host.db`) so they are
  * part of the owner file the user controls — pausing, exporting or deleting
  * the file carries the tasks with it. A Durable Object is single-threaded, so
- * there are no run locks: `onAlarm` executes due runs serially.
+ * there are no run locks: `onAlarm` executes due runs up to
+ * `MAX_CONCURRENT_TASK_RUNS` at a time, and in-memory ownership (a task
+ * taken up by a tick, a run executing, a turn being recovered) keeps any
+ * task from firing twice.
  *
  * A run re-enters the SAME agent through `host.runTurn` — the exact entry the
  * HTTP shell and Matrix gateway use — on a synthetic per-task session
@@ -23,9 +26,16 @@
  * and the result is delivered to the user's oracle room via the Matrix
  * gateway. `before-action` tasks do not execute on fire: the scheduler posts
  * an approval request to the room and waits; `surface.resolveApproval`
- * (driven by the `resolve_task_approval` tool) triggers or drops the actual
- * run.
+ * (driven by the `resolve_task_approval` tool) drops the run or persists
+ * the approval, and the next alarm — armed for right away — executes it.
  */
+import {
+  deliverableIntent,
+  markdownDigest,
+  type TopicDeliverableRequest,
+  type TopicDeliverableResult,
+  type TopicDeliverableSnapshot,
+} from './topic-deliverables';
 import type {
   Logger,
   OracleTaskInput,
@@ -53,11 +63,18 @@ import {
   type TaskRecord,
   type TaskRunState,
 } from './store';
+import { taskExecutionProfile } from '../core/execution-profile';
 import { retryGateway } from '../do/gateway-retry';
 
 /** Session-id prefix for the synthetic sessions task runs execute on. */
 export const TASK_SESSION_PREFIX = 'task:';
 
+function taskIdOfSession(sessionId: string): string | undefined {
+  return sessionId.startsWith(TASK_SESSION_PREFIX)
+    ? sessionId.slice(TASK_SESSION_PREFIX.length)
+    : undefined;
+}
+
 /**
  * The slice of the Matrix gateway the scheduler needs. Structural, so the
  * host passes its `DurableObjectStub<MatrixGatewayObject>` unchanged while
@@ -101,8 +118,9 @@ export interface TaskSchedulerHost {
   gateway: TaskGateway;
   /** Run one agent turn in this user's object (same entry the HTTP shell uses). */
   runTurn: (req: TurnRequest) => Promise<TurnResult>;
+  abortTurn?: (sessionId: string) => Promise<boolean>;
   /** Ask the object to re-arm its alarm no later than `at` (ms epoch). */
-  requestAlarm: (at: number) => void;
+  requestAlarm: (at: number) => void | Promise<void>;
   /**
    * Whether the durable turn run of a task run (`TurnRequest.taskRunId`) is
    * still live in the object — recovering or executing — so an open
@@ -125,10 +143,40 @@ export interface TaskSchedulerHost {
 export interface TaskScheduler {
   /** Plugin-facing surface, exposed as `ctx.tasks`. */
   surface: OracleTasksSurface;
-  /** Earliest pending deadline (ms epoch), or null when nothing is scheduled. */
+  /**
+   * Refuse a turn that does not match the persisted task run it claims (or
+   * that targets a restricted task's session without being its run). Throws.
+   */
+  assertTurnProfile(req: TurnRequest): Promise<void>;
+  /**
+   * Whether `sessionId` is the synthetic session of a task with an execution
+   * profile — or of a task row this runtime cannot load, which is treated as
+   * restricted. Derived from the task row, never from a request.
+   */
+  isRestrictedSession(sessionId: string): Promise<boolean>;
+  startTopicDeliverable(
+    operationId: string,
+    request: TopicDeliverableRequest,
+  ): Promise<TopicDeliverableResult>;
+  readTopicDeliverable(operationId: string): Promise<TopicDeliverableResult>;
+  cancelTopicDeliverable(
+    operationId: string,
+    request: TopicDeliverableRequest,
+  ): Promise<TopicDeliverableResult>;
+  /**
+   * Earliest pending deadline (ms epoch), or null when nothing is scheduled.
+   * A task whose run is executing or being recovered contributes nothing:
+   * the end of that run re-arms the alarm for its next occurrence.
+   */
   nextWakeAt(): Promise<number | null>;
-  /** Run everything that is due. Must be safe to call spuriously. */
-  onAlarm(now: number): Promise<void>;
+  /**
+   * Run everything that is due — up to `MAX_CONCURRENT_TASK_RUNS` runs at a
+   * time — and resolve to the `nextWakeAt()` computed afterwards. The caller
+   * arms the alarm for it (no earlier than a second from now, so a deadline
+   * left in the past cannot spin the alarm). Must be safe to call
+   * spuriously.
+   */
+  onAlarm(now: number): Promise<number | null>;
   /** Runs no incarnation has finished (operator/debug). */
   openRuns(): Promise<OpenTaskRun[]>;
   /** A run this instance is executing or delivering right now. */
@@ -143,6 +191,15 @@ export interface TaskScheduler {
   failRecoveredRun(runId: string, detail: string): Promise<void>;
 }
 
+/**
+ * Due runs one alarm tick executes at the same time. Each is an agent turn
+ * of up to `TURN_TIMEOUT_MS`; run one after another, a single slow turn held
+ * back every task due with it, and a long queue outlived the alarm
+ * invocation. The runs share the object's tool lanes (one write slot), so
+ * the cap stays small.
+ */
+export const MAX_CONCURRENT_TASK_RUNS = 3;
+
 /** How much of a run's output is kept as `lastResult.summary`. */
 const RESULT_SUMMARY_MAX = 500;
 /** How much of an error message is kept in bookkeeping / notices. */
@@ -192,7 +249,14 @@ export function shouldCreateDedicatedRoom(args: {
   if (args.explicit !== 'auto') return args.explicit === 'yes';
   const { schedule } = args;
   if (schedule.kind === 'cron') {
-    const interval = cronIntervalMs(schedule.cron, schedule.timezone);
+    // The clock cadence, without the timezone: a daily task is daily even
+    // on the day the clocks change (its real gap is then 23 or 25 hours).
+    const interval = cronIntervalMs(
+      schedule.cron,
+      undefined,
+      Date.now(),
+      DAY_MS,
+    );
     if (interval !== null && interval < DAY_MS) return true;
   } else if (schedule.kind === 'interval') {
     if (schedule.everySeconds * 1000 < DAY_MS) return true;
@@ -227,6 +291,22 @@ function approvalRequestMessage(task: TaskRecord): string {
   ].join('\n');
 }
 
+/**
+ * A restricted task is one immutable attempt: it can run once or be
+ * cancelled, never paused and later resumed (a resume would re-arm it from
+ * a recomputed schedule rather than the authorized one).
+ */
+function assertLifecycleMutable(task: TaskRecord): void {
+  if (task.executionProfile) {
+    throw new Error(
+      'Supplied-context tasks cannot be paused or resumed; cancel it and create a new attempt',
+    );
+  }
+}
+
+const TOPIC_TASK_CANCEL_ERROR =
+  "This task is a Topic deliverable; cancel it through its owner's Topic deliverable cancel route (POST /topic-deliverables/:operationId/cancel).";
+
 function errorMessage(err: unknown): string {
   return (err instanceof Error ? err.message : String(err)).slice(0, ERROR_MAX);
 }
@@ -249,12 +329,45 @@ class AlarmTaskScheduler implements TaskScheduler {
   /** Tasks whose open run is being recovered by the object (rebuilt per alarm). */
   private readonly recoveringTasks = new Set<string>();
 
+  /**
+   * Tasks an alarm tick has taken up (approval request or run) and not yet
+   * finished. Claimed synchronously before the first await, so a second
+   * tick — or a second worker of the same tick — never fires them again.
+   */
+  private readonly firingTasks = new Set<string>();
+
   private hasActiveRun(taskId: string): boolean {
     for (const owner of this.activeRuns.values())
       if (owner === taskId) return true;
     return false;
   }
 
+  /** The task has a run (or approval request) in flight, or a turn being recovered. */
+  private isBusy(taskId: string): boolean {
+    return (
+      this.firingTasks.has(taskId) ||
+      this.recoveringTasks.has(taskId) ||
+      this.hasActiveRun(taskId)
+    );
+  }
+
+  private busyTaskIds(): string[] {
+    return [
+      ...new Set([
+        ...this.firingTasks,
+        ...this.recoveringTasks,
+        ...this.activeRuns.values(),
+      ]),
+    ];
+  }
+
+  /** Re-arm the alarm for the next deadline (after a run ended outside a tick). */
+  private async rearm(): Promise<void> {
+    const next = await this.nextWakeAt();
+    if (next !== null)
+      await this.host.requestAlarm(Math.max(next, Date.now() + 1000));
+  }
+
   constructor(
     private readonly host: TaskSchedulerHost,
     private readonly store: TasksStore,
@@ -265,25 +378,203 @@ class AlarmTaskScheduler implements TaskScheduler {
     this.deliveryRetryDelaysMs = host.deliveryRetryDelaysMs;
     this.deliveryRoundBackoffMs =
       host.deliveryRoundBackoffMs ?? DEFAULT_DELIVERY_ROUND_BACKOFF_MS;
+    // Topic deliverables live in the same table but belong to their owner's
+    // signed API: the plugin surface neither lists nor shows them, and its
+    // cancel refuses them (the dedicated cancel also aborts a running turn
+    // and keeps the operation's binding). Pause/resume/update are refused
+    // for every task with an execution profile, Topic ones included.
     this.surface = {
       preview: (input) => this.preview(input),
       create: (input) => this.create(input),
-      list: () => this.store.list(),
-      get: (id) => this.store.get(id),
+      list: async () =>
+        (await this.store.list()).filter((task) => !task.topicOperationId),
+      get: async (id) => {
+        const task = await this.store.get(id);
+        return task?.topicOperationId ? null : task;
+      },
       update: (id, patch) => this.update(id, patch),
       pause: (id) => this.pause(id),
       resume: (id) => this.resume(id),
-      cancel: (id) => this.cancel(id),
+      cancel: async (id) => {
+        if ((await this.load(id)).topicOperationId)
+          throw new Error(TOPIC_TASK_CANCEL_ERROR);
+        return this.cancel(id);
+      },
       resolveApproval: (taskId, decision, note) =>
         this.resolveApproval(taskId, decision, note),
     };
   }
 
+  private newTopicTask(
+    operationId: string,
+    request: TopicDeliverableRequest,
+    status: 'active' | 'cancelled',
+  ): TaskRecord {
+    const now = new Date().toISOString();
+    return {
+      id: newTaskId(request.title),
+      title: request.title,
+      intent: deliverableIntent(request),
+      executionProfile: 'supplied-context-markdown',
+      schedule: { kind: 'once', at: now },
+      approval: 'never',
+      status,
+      createdAt: now,
+      updatedAt: now,
+      ...(status === 'active' ? { nextRunAt: now } : {}),
+      consecutiveFailures: 0,
+      topicOperationId: operationId,
+      topicRequest: request,
+    };
+  }
+
+  async startTopicDeliverable(
+    operationId: string,
+    request: TopicDeliverableRequest,
+  ): Promise<TopicDeliverableResult> {
+    const created = await this.host.db.transaction(async () => {
+      const existing = await this.store.getTopicOperation(operationId);
+      if (existing) {
+        if (JSON.stringify(existing.topicRequest) !== JSON.stringify(request)) {
+          return {
+            ok: false,
+            status: 409,
+            message: 'This operation is already bound to different input.',
+          } as const;
+        }
+        return { ok: true, task: existing } as const;
+      }
+      if ((await this.store.countLive()) >= this.maxTasksPerUser) {
+        return {
+          ok: false,
+          status: 429,
+          message: 'Too many active tasks.',
+        } as const;
+      }
+      const task = this.newTopicTask(operationId, request, 'active');
+      await this.store.insert(task);
+      return { ok: true, task } as const;
+    });
+    if (!created.ok) return created;
+    if (created.task.nextRunAt)
+      await this.host.requestAlarm(Date.parse(created.task.nextRunAt));
+    return this.readTopicDeliverable(operationId);
+  }
+
+  async readTopicDeliverable(
+    operationId: string,
+  ): Promise<TopicDeliverableResult> {
+    const { task, run } = await this.host.db.transaction(async () => {
+      const task = await this.store.getTopicOperation(operationId);
+      return {
+        task,
+        run: task ? await this.store.topicRun(task.id) : undefined,
+      };
+    });
+    if (
+      !task?.topicRequest ||
+      task.executionProfile !== 'supplied-context-markdown'
+    ) {
+      return { ok: false, status: 404, message: 'Deliverable not found.' };
+    }
+    const snapshot: TopicDeliverableSnapshot = {
+      operationId,
+      taskId: task.id,
+      topic: task.topicRequest.topic,
+      status: 'queued',
+      ...(run ? { runId: run.run_id } : {}),
+    };
+    if (
+      run?.result_text &&
+      run.completed_at &&
+      ['delivering', 'delivered', 'failed'].includes(run.state ?? '')
+    ) {
+      snapshot.status = 'ready';
+      snapshot.output = {
+        markdown: run.result_text,
+        sha256: await markdownDigest(run.result_text),
+        completedAt: run.completed_at,
+      };
+      snapshot.delivery =
+        run.state === 'delivered'
+          ? 'delivered'
+          : run.state === 'failed'
+            ? 'failed'
+            : 'pending';
+    } else if (run?.state === 'running') {
+      snapshot.status = 'working';
+    } else if (run?.state === 'interrupted') {
+      snapshot.status = 'interrupted';
+    } else if (run) {
+      // The attempt ended without a result (turn error, empty output).
+      snapshot.status = 'failed';
+    } else if (task.status === 'paused') {
+      // Not reachable through any API (pause is refused for Topic tasks),
+      // but a row written that way is reported as it is, not as a failure.
+      snapshot.status = 'paused';
+    } else if (task.status !== 'active') {
+      // `failed` (bookkeeping stopped it) or a `completed` row without its
+      // delivered run: either way there is no result to return.
+      snapshot.status = 'failed';
+    }
+    if (task.status === 'cancelled') {
+      snapshot.status =
+        run?.state === 'running' &&
+        (this.hasActiveRun(task.id) || this.host.turnRunLive?.(run.run_id))
+          ? 'stopping'
+          : 'cancelled';
+    }
+    return { ok: true, snapshot };
+  }
+
+  async cancelTopicDeliverable(
+    operationId: string,
+    request: TopicDeliverableRequest,
+  ): Promise<TopicDeliverableResult> {
+    const cancelled = await this.host.db.transaction(async () => {
+      const existing = await this.store.getTopicOperation(operationId);
+      if (!existing) {
+        const task = this.newTopicTask(operationId, request, 'cancelled');
+        await this.store.insert(task);
+        return { ok: true, task } as const;
+      }
+      if (JSON.stringify(existing.topicRequest) !== JSON.stringify(request)) {
+        return {
+          ok: false,
+          status: 409,
+          message: 'This operation is already bound to different input.',
+        } as const;
+      }
+      // Execution finished (its result is stored, even while delivery is
+      // still being retried): the result is final, cancel has nothing left
+      // to stop and delivery continues. A repeated cancel stays idempotent.
+      if (
+        existing.status === 'completed' ||
+        (existing.status !== 'cancelled' &&
+          (await this.store.topicRun(existing.id))?.completed_at)
+      ) {
+        return {
+          ok: false,
+          status: 409,
+          message: 'Execution already finished; its result is final.',
+        } as const;
+      }
+      await this.cancel(existing.id);
+      return { ok: true, task: existing } as const;
+    });
+    if (!cancelled.ok) return cancelled;
+    await this.host.abortTurn?.(`${TASK_SESSION_PREFIX}${cancelled.task.id}`);
+    return this.readTopicDeliverable(operationId);
+  }
+
   // ── alarm client ─────────────────────────────────────────────────────────
 
   async nextWakeAt(): Promise<number | null> {
+    // A busy task's `nextRunAt` stays in the past until its run (or the
+    // recovered turn) ends — counting it would re-arm the alarm every
+    // second for the length of a turn.
     const [nextRun, nextRetry] = await Promise.all([
-      this.store.minNextRunAt(),
+      this.store.minNextRunAt(this.busyTaskIds()),
       this.store.minRetryAt(),
     ]);
     if (nextRun === null) return nextRetry;
@@ -302,6 +593,20 @@ class AlarmTaskScheduler implements TaskScheduler {
   async completeRecoveredRun(runId: string, text: string): Promise<void> {
     const run = await this.store.getOpenRun(runId);
     if (!run || run.state !== 'running') return;
+    try {
+      await this.finishRecoveredRun(run, text);
+    } finally {
+      // The task waited on this turn (no wake was armed for it).
+      this.recoveringTasks.delete(run.taskId);
+      await this.rearm();
+    }
+  }
+
+  private async finishRecoveredRun(
+    run: OpenTaskRun,
+    text: string,
+  ): Promise<void> {
+    const runId = run.runId;
     const nowMs = Date.now();
     const loaded = await this.store.get(run.taskId);
     if (!loaded || loaded.status !== 'active') {
@@ -345,6 +650,7 @@ class AlarmTaskScheduler implements TaskScheduler {
         state: 'delivering',
         ...(roomId ? { roomId } : {}),
         resultText: trimmed,
+        completedAt: new Date().toISOString(),
       });
     });
     const refreshed = (await this.store.get(task.id)) ?? task;
@@ -369,64 +675,93 @@ class AlarmTaskScheduler implements TaskScheduler {
   async failRecoveredRun(runId: string, detail: string): Promise<void> {
     const run = await this.store.getOpenRun(runId);
     if (!run || run.state !== 'running') return;
-    const task = await this.store.get(run.taskId);
-    if (!task) {
-      await this.store.updateRun(runId, {
-        state: 'interrupted',
-        ok: false,
-        finishedAt: new Date().toISOString(),
-        detail,
-      });
-      return;
+    try {
+      const task = await this.store.get(run.taskId);
+      if (!task) {
+        await this.store.updateRun(runId, {
+          state: 'interrupted',
+          ok: false,
+          finishedAt: new Date().toISOString(),
+          detail,
+        });
+        return;
+      }
+      await this.recordFailure(
+        task,
+        Date.now(),
+        run.startedAt,
+        new Error(detail),
+        {
+          runId,
+          state: 'interrupted',
+        },
+      );
+    } finally {
+      this.recoveringTasks.delete(run.taskId);
+      await this.rearm();
     }
-    await this.recordFailure(
-      task,
-      Date.now(),
-      run.startedAt,
-      new Error(detail),
-      {
-        runId,
-        state: 'interrupted',
-      },
-    );
   }
 
-  async onAlarm(now: number): Promise<void> {
+  async onAlarm(now: number): Promise<number | null> {
     // Unfinished runs first: what a previous incarnation left behind decides
     // the fate of its task before the due scan can fire the task again.
     await this.reconcileOpenRuns(now);
     const due = await this.store.due(now);
-    for (const stale of due) {
-      // Re-load: a tool call awaited between iterations may have paused,
-      // cancelled or rescheduled the task since the due scan.
-      const task = await this.store.get(stale.id);
-      if (!task || task.status !== 'active' || task.nextRunAt === undefined) {
-        continue;
-      }
-      if (Date.parse(task.nextRunAt) > now) continue;
-      // A run of this task is executing in this instance right now (a long
-      // turn while the object's alarm fires for something else), or its
-      // turn is being recovered by the object after a reset: its schedule
-      // advances when the turn ends, never start a second one.
-      if (this.hasActiveRun(task.id) || this.recoveringTasks.has(task.id))
-        continue;
-      try {
-        if (task.approval === 'before-action') {
-          await this.requestApproval(task, now);
-        } else {
-          await this.executeRun(task, now);
+    let cursor = 0;
+    // The due scan's rows are current for the runs started before anything
+    // yields; a task taken up later (after a slot freed) is re-read, since a
+    // tool call may have paused, cancelled or rescheduled it meanwhile.
+    let reload = false;
+    const worker = async (): Promise<void> => {
+      while (cursor < due.length) {
+        const listed = due[cursor++]!;
+        // A run of this task is executing in this instance right now (a
+        // long turn while the object's alarm fires for something else), or
+        // its turn is being recovered by the object after a reset: its
+        // schedule advances when the turn ends, never start a second one.
+        if (this.isBusy(listed.id)) continue;
+        this.firingTasks.add(listed.id);
+        try {
+          const task = reload ? await this.store.get(listed.id) : listed;
+          if (task) await this.fire(task, now);
+        } catch (err) {
+          // `executeRun`/`requestApproval` do their own failure bookkeeping —
+          // reaching here means the BOOKKEEPING failed (storage trouble).
+          // Log and move on; the caller's 1s re-arm floor prevents a hot loop.
+          this.host.log.error(
+            `[tasks] run bookkeeping crashed for ${listed.id}: ${errorMessage(err)}`,
+          );
+        } finally {
+          this.firingTasks.delete(listed.id);
         }
-      } catch (err) {
-        // `executeRun`/`requestApproval` do their own failure bookkeeping —
-        // reaching here means the BOOKKEEPING failed (storage trouble). Log
-        // and move on; the 1s re-arm floor below prevents a hot loop.
-        this.host.log.error(
-          `[tasks] run bookkeeping crashed for ${task.id}: ${errorMessage(err)}`,
-        );
       }
+    };
+    const workers = Array.from(
+      { length: Math.min(MAX_CONCURRENT_TASK_RUNS, due.length) },
+      () => worker(),
+    );
+    reload = true;
+    await Promise.all(workers);
+    return this.nextWakeAt();
+  }
+
+  /** One due task: its approved run, else its scheduled fire. */
+  private async fire(task: TaskRecord, now: number): Promise<void> {
+    if (task.status !== 'active') return;
+    if (task.approvedAt !== undefined && Date.parse(task.approvedAt) <= now) {
+      await this.executeRun(task, now, {
+        approved: true,
+        ...(task.approvalNote ? { approvalNote: task.approvalNote } : {}),
+      });
+      return;
+    }
+    if (task.nextRunAt === undefined || Date.parse(task.nextRunAt) > now)
+      return;
+    if (task.approval === 'before-action') {
+      await this.requestApproval(task, now);
+    } else {
+      await this.executeRun(task, now);
     }
-    const next = await this.nextWakeAt();
-    if (next !== null) this.host.requestAlarm(Math.max(next, now + 1000));
   }
 
   /**
@@ -441,9 +776,9 @@ class AlarmTaskScheduler implements TaskScheduler {
     this.recoveringTasks.clear();
     for (const run of open) {
       if (this.activeRuns.has(run.runId)) continue; // alive in this instance
-      const task = await this.store.get(run.taskId);
       if (run.state === 'delivering') {
         if (run.retryAt !== undefined && run.retryAt > now) continue;
+        const task = await this.store.get(run.taskId);
         if (!task || task.status === 'cancelled') {
           await this.store.updateRun(run.runId, {
             state: 'failed',
@@ -469,6 +804,7 @@ class AlarmTaskScheduler implements TaskScheduler {
         this.host.log.warn(
           `[tasks] run ${run.runId} of ${run.taskId} started ${run.startedAt} never finished (the object was reset while it ran); closing it as interrupted, not re-running`,
         );
+        const task = await this.store.get(run.taskId);
         if (!task) {
           await this.store.updateRun(run.runId, {
             state: 'interrupted',
@@ -524,7 +860,88 @@ class AlarmTaskScheduler implements TaskScheduler {
     return { ok: problems.length === 0, nextRuns, problems };
   }
 
+  /**
+   * Every turn that names a task run (original or recovered) must still own
+   * an open ledger row on that task's session — for ordinary tasks too: a
+   * closed row means the run was already reported as interrupted or
+   * dropped, its result would be discarded (`completeRecoveredRun`), and
+   * re-running the turn would only repeat its tool calls. A restricted turn
+   * must additionally match the persisted task exactly: profile, owner,
+   * message, one-shot schedule, no approval conversation, no attachments
+   * or metadata. Anything the stored task cannot vouch for is refused.
+   */
+  async assertTurnProfile(req: TurnRequest): Promise<void> {
+    const requested = taskExecutionProfile(req.executionProfile);
+    const run = req.taskRunId
+      ? await this.store.getOpenRun(req.taskRunId)
+      : undefined;
+    if (
+      req.taskRunId &&
+      (!run || req.sessionId !== `${TASK_SESSION_PREFIX}${run.taskId}`)
+    ) {
+      throw new Error(
+        'Task execution profile does not match its persisted run',
+      );
+    }
+    const taskId = run?.taskId ?? taskIdOfSession(req.sessionId);
+    if (
+      taskId !== undefined &&
+      (await this.store.unsupportedProfileOf(taskId)) !== undefined
+    ) {
+      throw new Error(
+        'Task has an execution profile this runtime does not support',
+      );
+    }
+    const task = taskId !== undefined ? await this.store.get(taskId) : null;
+    if (!requested && !task?.executionProfile) return;
+    if (
+      !task ||
+      task.executionProfile !== requested ||
+      !run ||
+      run.taskId !== task.id ||
+      run.state !== 'running'
+    ) {
+      throw new Error(
+        'Task execution profile does not match its persisted run',
+      );
+    }
+    if (task.schedule.kind !== 'once' || task.approval !== 'never') {
+      throw new Error(
+        'Supplied-context tasks must be one-shot without an approval conversation',
+      );
+    }
+    if (
+      req.identity.userDid !== this.host.userDid ||
+      req.message !== buildRunMessage(task)
+    ) {
+      throw new Error(
+        'Supplied-context task does not match its authorized input',
+      );
+    }
+    if (task.status !== 'active') throw new Error('Task is no longer active');
+    if (req.attachments?.length || req.metadata)
+      throw new Error('Supplied-context task accepts plain text only');
+  }
+
+  async isRestrictedSession(sessionId: string): Promise<boolean> {
+    const taskId = taskIdOfSession(sessionId);
+    if (taskId === undefined) return false;
+    if ((await this.store.unsupportedProfileOf(taskId)) !== undefined)
+      return true;
+    return Boolean((await this.store.get(taskId))?.executionProfile);
+  }
+
   private async create(input: OracleTaskInput): Promise<OracleTaskRecord> {
+    const executionProfile = taskExecutionProfile(input.executionProfile);
+    if (
+      executionProfile &&
+      (input.schedule.kind !== 'once' ||
+        (input.approval && input.approval !== 'never'))
+    ) {
+      throw new Error(
+        'Supplied-context tasks must be one-shot without an approval conversation',
+      );
+    }
     const problems = await this.problemsFor(input);
     if (problems.length > 0) throw new Error(problems.join(' '));
     const nowMs = Date.now();
@@ -534,6 +951,7 @@ class AlarmTaskScheduler implements TaskScheduler {
     const nowIso = new Date(nowMs).toISOString();
     const record: TaskRecord = {
       id: newTaskId(title),
+      executionProfile,
       title,
       intent: input.intent.trim(),
       schedule: input.schedule,
@@ -566,7 +984,7 @@ class AlarmTaskScheduler implements TaskScheduler {
       if (roomId) record.deliveryRoomId = roomId;
     }
     await this.store.insert(record);
-    this.host.requestAlarm(nextMs);
+    await this.host.requestAlarm(nextMs);
     this.host.log.log(
       `[tasks] created ${record.id} — ${summarizeSchedule(record.schedule)}; next run ${record.nextRunAt}`,
     );
@@ -586,6 +1004,20 @@ class AlarmTaskScheduler implements TaskScheduler {
     patch: Partial<OracleTaskInput>,
   ): Promise<OracleTaskRecord> {
     const task = await this.load(id);
+    if (
+      'executionProfile' in patch &&
+      patch.executionProfile !== task.executionProfile
+    ) {
+      throw new Error('Task execution profile is immutable');
+    }
+    if (
+      task.executionProfile &&
+      Object.keys(patch).some((key) => key !== 'executionProfile')
+    ) {
+      throw new Error(
+        'Supplied-context tasks are immutable; create a new attempt',
+      );
+    }
     if (task.status === 'completed' || task.status === 'cancelled') {
       throw new Error(
         `A ${task.status} task cannot be updated — create a new one.`,
@@ -631,12 +1063,13 @@ class AlarmTaskScheduler implements TaskScheduler {
     }
     task.updatedAt = new Date().toISOString();
     await this.store.save(task);
-    if (nextMs !== null) this.host.requestAlarm(nextMs);
+    if (nextMs !== null) await this.host.requestAlarm(nextMs);
     return task;
   }
 
   private async pause(id: string): Promise<OracleTaskRecord> {
     const task = await this.load(id);
+    assertLifecycleMutable(task);
     if (task.status === 'paused') return task;
     if (task.status !== 'active') {
       throw new Error(`A ${task.status} task cannot be paused.`);
@@ -652,6 +1085,7 @@ class AlarmTaskScheduler implements TaskScheduler {
 
   private async resume(id: string): Promise<OracleTaskRecord> {
     const task = await this.load(id);
+    assertLifecycleMutable(task);
     if (task.status === 'active') return task;
     if (task.status !== 'paused' && task.status !== 'failed') {
       throw new Error(
@@ -671,7 +1105,7 @@ class AlarmTaskScheduler implements TaskScheduler {
     delete task.pendingApprovalAt;
     task.updatedAt = new Date().toISOString();
     await this.store.save(task);
-    this.host.requestAlarm(nextMs);
+    await this.host.requestAlarm(nextMs);
     return task;
   }
 
@@ -710,7 +1144,26 @@ class AlarmTaskScheduler implements TaskScheduler {
           'Could not resolve a delivery room for the approval request',
         );
       }
-      await this.host.gateway.sendText(roomId, approvalRequestMessage(task));
+      // Retried across a gateway restart under an id fixed per occurrence:
+      // a send whose response was lost — or that went out just before a
+      // reset, so the next tick asks again — is deduplicated by the
+      // homeserver instead of reaching the user twice.
+      await retryGateway(
+        () =>
+          this.host.gateway.sendText(roomId, approvalRequestMessage(task), {
+            txnId: `task-approval-${task.id}-${task.nextRunAt ?? task.createdAt}`,
+            priority: 'interactive',
+          }),
+        {
+          ...(this.deliveryRetryDelaysMs
+            ? { delaysMs: this.deliveryRetryDelaysMs }
+            : {}),
+          onRetry: (err, attempt, delayMs) =>
+            this.host.log.warn(
+              `[tasks] approval request for ${task.id} failed on attempt ${attempt}, retrying in ${delayMs} ms: ${errorMessage(err)}`,
+            ),
+        },
+      );
       task.pendingApprovalAt = startedAt;
       if (task.schedule.kind === 'once') {
         delete task.nextRunAt;
@@ -777,9 +1230,20 @@ class AlarmTaskScheduler implements TaskScheduler {
       return { resolved: true };
     }
 
-    await this.store.save(task);
-    this.host.log.log(`[tasks] approval granted for ${task.id} — running now`);
-    await this.executeRun(task, Date.now(), { approvalNote: note });
+    // The run itself executes on the alarm, never inside this call: the
+    // approval arrives as a tool call that holds the object's only write
+    // slot, which the run's own write tools would wait on until the turn
+    // timed out. The approval is persisted with the cleared request, so a
+    // reset before the alarm still runs it — once.
+    const approvedAt = Date.now();
+    await this.host.db.transaction(async () => {
+      await this.store.save(task);
+      await this.store.approve(task.id, approvedAt, note?.trim() || undefined);
+    });
+    this.host.log.log(
+      `[tasks] approval granted for ${task.id} — running on the alarm`,
+    );
+    await this.host.requestAlarm(approvedAt);
     return { resolved: true };
   }
 
@@ -843,27 +1307,46 @@ class AlarmTaskScheduler implements TaskScheduler {
    * Two extra single-row writes per run against the dozens of checkpoint
    * writes the turn itself makes; task runs are rare next to chat turns.
    *
-   * `opts.approvalNote` marks an approval-triggered run: the schedule was
-   * already advanced when the request was posted, so only a one-shot's
-   * completion is recorded here.
+   * `opts.approved` marks the approved run of a `before-action` task: the
+   * approval marker is taken in the transaction that opens the ledger row
+   * (no marker, no run), and the schedule was already advanced when the
+   * request was posted, so only a one-shot's completion is recorded here.
    */
   private async executeRun(
     taskAtFire: TaskRecord,
     nowMs: number,
-    opts: { approvalNote?: string } = {},
+    opts: { approved?: boolean; approvalNote?: string } = {},
   ): Promise<void> {
     let task = taskAtFire;
-    const approvalRun = task.approval === 'before-action';
+    const approvalRun =
+      opts.approved === true || task.approval === 'before-action';
+    // A Topic deliverable's turn never uses a room (the restricted turn
+    // leaves no room trail) and its product is the stored result, read
+    // through the owner API: run first, deliver afterwards, best-effort
+    // (`deliverOrDefer` resolves the room and retries in rounds). An
+    // ordinary task's turn runs in its delivery room, so that comes first.
+    const topic = task.topicOperationId !== undefined;
     const startedAt = new Date(nowMs).toISOString();
     const runId = crypto.randomUUID();
     const txnId = `task-${runId}`;
     const ledger = { runId, state: 'failed' as const };
     let open: OpenTaskRun | undefined;
+    // Owned from here on: a concurrent tick sees the task as busy.
+    this.activeRuns.set(runId, task.id);
     try {
-      await this.store.startRun({ runId, taskId: task.id, startedAt, txnId });
-      this.activeRuns.set(runId, task.id);
-      const roomId = await this.resolveDeliveryRoom(task);
-      if (!roomId) throw new Error('Could not resolve a delivery room');
+      const started = await this.host.db.transaction(async () => {
+        if (opts.approved && !(await this.store.claimApproval(task.id)))
+          return false;
+        await this.store.startRun({ runId, taskId: task.id, startedAt, txnId });
+        return true;
+      });
+      if (!started) {
+        this.activeRuns.delete(runId);
+        return;
+      }
+      const roomId = topic ? undefined : await this.resolveDeliveryRoom(task);
+      if (!topic && !roomId)
+        throw new Error('Could not resolve a delivery room');
       const result = await this.host.runTurn({
         identity: {
           userDid: this.host.userDid,
@@ -874,11 +1357,12 @@ class AlarmTaskScheduler implements TaskScheduler {
         sessionId: `${TASK_SESSION_PREFIX}${task.id}`,
         message: buildRunMessage(task, opts.approvalNote),
         client: 'matrix',
-        roomId,
+        ...(roomId ? { roomId } : {}),
         requestId: crypto.randomUUID(),
         // Links the durable turn run to this task run: a reset mid-turn is
         // recovered and delivered by the object instead of closed.
         taskRunId: runId,
+        executionProfile: task.executionProfile,
       });
       const text = result.text.trim();
       if (text.length === 0) throw new Error('Agent returned no output');
@@ -922,8 +1406,9 @@ class AlarmTaskScheduler implements TaskScheduler {
         await this.store.save(task);
         await this.store.updateRun(runId, {
           state: 'delivering',
-          roomId,
+          ...(roomId ? { roomId } : {}),
           resultText: text,
+          completedAt: new Date().toISOString(),
         });
       });
       open = {
@@ -932,7 +1417,7 @@ class AlarmTaskScheduler implements TaskScheduler {
         startedAt,
         state: 'delivering',
         txnId,
-        roomId,
+        ...(roomId ? { roomId } : {}),
         resultText: text,
         attempts: 0,
       };
@@ -1008,7 +1493,7 @@ class AlarmTaskScheduler implements TaskScheduler {
         ] ?? 60_000;
       const retryAt = Math.max(nowMs, Date.now()) + pause;
       await this.store.updateRun(run.runId, { attempts, retryAt });
-      this.host.requestAlarm(retryAt);
+      await this.host.requestAlarm(retryAt);
       this.host.log.warn(
         `[tasks] run ${run.runId} of ${task.id}: delivery round ${attempts} failed (${errorMessage(err)}); next round at ${new Date(retryAt).toISOString()}`,
       );
@@ -1016,26 +1501,23 @@ class AlarmTaskScheduler implements TaskScheduler {
     }
 
     const finishedAt = new Date().toISOString();
+    const summary = text.slice(0, RESULT_SUMMARY_MAX);
     // Delivered. Bookkeeping goes onto the task as it is NOW (a pause or
     // cancel during the send must stand); only an active one-shot completes.
-    const current = (await this.store.get(task.id)) ?? task;
-    current.lastRunAt = run.startedAt;
-    current.lastResult = {
-      ok: true,
-      summary: text.slice(0, RESULT_SUMMARY_MAX),
-      at: finishedAt,
-    };
-    current.consecutiveFailures = 0;
-    if (current.schedule.kind === 'once' && current.status === 'active')
-      current.status = 'completed';
-    current.updatedAt = finishedAt;
     await this.host.db.transaction(async () => {
+      const current = (await this.store.get(task.id)) ?? task;
+      current.lastRunAt = run.startedAt;
+      current.lastResult = { ok: true, summary, at: finishedAt };
+      current.consecutiveFailures = 0;
+      if (current.schedule.kind === 'once' && current.status === 'active')
+        current.status = 'completed';
+      current.updatedAt = finishedAt;
       await this.store.save(current);
       await this.store.updateRun(run.runId, {
         state: 'delivered',
         ok: true,
         finishedAt,
-        detail: task.lastResult?.summary,
+        detail: summary,
         retryAt: null,
       });
     });
@@ -1145,14 +1627,20 @@ class AlarmTaskScheduler implements TaskScheduler {
     this.host.log.warn(
       `[tasks] run failed for ${task.id} (${task.consecutiveFailures} consecutive${stopped ? ', stopped' : ''}): ${message}`,
     );
-    if (stopped) {
+    // A Topic deliverable's product is its stored result, read through the
+    // owner's API (which reports the failed delivery): no room notice.
+    if (stopped && task.topicOperationId === undefined) {
       // Best-effort notice — the failure bookkeeping above is already saved.
       // Retried across a gateway restart under a fixed id: never two copies.
       const roomId = await this.resolveDeliveryRoom(task);
       if (roomId) {
-        const text = oneShot
-          ? `🛑 **${task.title}** could not be completed. Ask me to run it again or to reschedule it.`
-          : `🛑 **${task.title}** has been stopped after ${task.consecutiveFailures} unsuccessful runs in a row. Ask me to look into it or to reschedule it when you're ready.`;
+        // A run whose result exists but could not be delivered is not a
+        // failed run: asking for a re-run would pay for the work twice.
+        const text = !oneShot
+          ? `🛑 **${task.title}** has been stopped after ${task.consecutiveFailures} unsuccessful runs in a row. Ask me to look into it or to reschedule it when you're ready.`
+          : ledger?.undelivered
+            ? `🛑 **${task.title}** ran, but its result could not be delivered here.`
+            : `🛑 **${task.title}** could not be completed. Ask me to run it again or to reschedule it.`;
         await retryGateway(
           () =>
             this.host.gateway.sendText(roomId, text, {
@@ -1175,7 +1663,7 @@ class AlarmTaskScheduler implements TaskScheduler {
 export async function createTaskScheduler(
   host: TaskSchedulerHost,
 ): Promise<TaskScheduler> {
-  const store = new TasksStore(host.db);
+  const store = new TasksStore(host.db, host.log);
   await store.setup();
   return new AlarmTaskScheduler(host, store);
 }