@capybara-hq/kernel 0.1.0-rc.24 → 0.1.0-rc.25

package/dist/runtime/run-worker.js

@@ -25,11 +25,13 @@ import { KernelEvents } from "../infra/events/kernel-events.js";
 import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { SkillsCatalogService } from "../skills/catalog.js";
 import { normalizeStoredDefinitionIn } from "../tools/legacy-data.js";
+import { ToolRegistry } from "../tools/registry.js";
 import { RunAbort } from "./abort.js";
 import { KyselyCheckpointSaver } from "./checkpointer.js";
 import { ConversationLock } from "./conversation-lock.js";
 import { runDeadline, tightestLimit } from "./limits.js";
 import { RunError } from "./model-call.js";
+import { PluginContextService } from "./plugin-context.service.js";
 import { ProviderListError, ProviderRegistry } from "./providers.js";
 import { ORG_QUOTA_LEASE_MS, orgRunLimit, RUN_QUOTA } from "./quota.js";
 import { RunContextService } from "./run-context.service.js";
@@ -64,6 +66,15 @@ async function requeue(job, token, delayMs) {
     await job.moveToDelayed(Date.now() + delayMs, token);
     throw new DelayedError();
 }
+/** An account's display name ("" when it is gone). */
+async function accountName(db, accountId) {
+    const row = await db
+        .selectFrom("accounts")
+        .select("display_name")
+        .where("id", "=", accountId)
+        .executeTakeFirst();
+    return row?.display_name ?? "";
+}
 /**
  * 运行 worker（只在含 `worker` 角色的进程消费）：领取 `cap-kernel-runs` 与 `cap-kernel-subagent-runs` 的任务
  * （两个 `@Processor`，见 run-processors.ts），取会话锁与组织配额，调用 AgentLoop，按结果写终态事件并推进
@@ -87,6 +98,8 @@ let RunWorker = class RunWorker {
     models;
     skillsCatalog;
     runContext;
+    pluginContext;
+    tools;
     finisher;
     txHost;
     drafts;
@@ -114,7 +127,11 @@ let RunWorker = class RunWorker {
     /** Run start's skills catalog snapshot (reads the pinned skills' bodies, phase B). */
     skillsCatalog, 
     /** Run start's run context (run context spec §5): who the agent is, the day, the person. */
-    runContext, finisher, txHost, 
+    runContext, 
+    /** Run start's plugin context (memory plugin spec §6.1): the `context@1` providers' text. */
+    pluginContext, 
+    /** The run's resolved tools, for the plugin context's `tools` (chat runs with providers). */
+    tools, finisher, txHost, 
     /** The steps' live drafts this process writes for the runs it executes. */
     drafts, hooks) {
         this.kdb = kdb;
@@ -134,6 +151,8 @@ let RunWorker = class RunWorker {
         this.models = models;
         this.skillsCatalog = skillsCatalog;
         this.runContext = runContext;
+        this.pluginContext = pluginContext;
+        this.tools = tools;
         this.finisher = finisher;
         this.txHost = txHost;
         this.drafts = drafts;
@@ -379,9 +398,10 @@ let RunWorker = class RunWorker {
         // 运行在等人处理（例如暂停后本任务被 stalled 机制重新投递）：不执行，续跑由处理 / 超时发起的新任务负责。
         if (run.status === "waiting")
             return;
+        await this.hooks?.afterRunRead?.(runId, conversationId);
         const conv = await this.db
             .selectFrom("conversations")
-            .select(["org_id", "agent_id", "kind", "subagent_depth"])
+            .select(["org_id", "agent_id", "kind", "subagent_depth", "source", "account_id"])
             .where("id", "=", conversationId)
             .executeTakeFirst();
         if (!conv)
@@ -448,8 +468,6 @@ let RunWorker = class RunWorker {
                 delayMs = QUOTA_FULL_DELAY_MS;
             }
             else {
-                // 运行开始执行（含续跑、stalled 后接手）：通知旁路（渠道出站投递据此把输出投到 IM），失败不影响运行
-                void this.events.emit("run.started", { conversationId, runId });
                 const r = await this.execute(run, { id: conversationId, ...conv }, state).catch(async (err) => {
                     if (state.abandoned)
                         return "abandoned";
@@ -574,6 +592,14 @@ let RunWorker = class RunWorker {
             saved = await normalizeStoredDefinitionIn(this.db, conv.org_id, version.definition);
             agent = saved;
         }
+        // the trigger account's role, read once per run for the plugin context and plugin tool
+        // handlers (memory plugin spec §6.2); an account no longer in the org counts as a guest
+        const role = (await this.db
+            .selectFrom("memberships")
+            .select("role")
+            .where("org_id", "=", conv.org_id)
+            .where("account_id", "=", run.trigger_account_id)
+            .executeTakeFirst())?.role ?? "guest";
         let startedAt = run.started_at;
         // The model / effort switch in effect (UI refresh B): the latest `model_switched` before this
         // run's `run_started`, read under the conversation lock when the run starts, so a replay
@@ -585,9 +611,14 @@ let RunWorker = class RunWorker {
         }
         if (run.status === "queued" || startedAt === null) {
             if (!existingStart) {
+                await this.hooks?.beforeRunStarted?.(runId, conversationId);
                 if (saved !== undefined)
                     await this.fallBackIfUnavailable(conv.org_id, conversationId, runId, saved);
                 const started = await this.appendRunStarted(conversationId, run, agent, saved);
+                // the status was read before the conversation lock: a stop that ended the run meanwhile
+                // (a queued run's direct abort, an orphan abort) wins, and the run never starts
+                if (started.terminal)
+                    return "finished";
                 agent = started.agent;
                 const toSeq = started.toSeq;
                 if (toSeq !== undefined)
@@ -617,14 +648,42 @@ let RunWorker = class RunWorker {
                     },
                 }),
             });
+            // plugin context (memory plugin spec §6.1): after the run context, still before the run is
+            // running; the providers are asked outside any transaction, a chat run only
+            await this.pluginContext.record({
+                orgId: conv.org_id,
+                conversationId,
+                runId,
+                agentId: conv.agent_id,
+                agentName: agent.name,
+                ownerAccountId: conv.account_id,
+                // only a chat run asks the providers
+                ownerName: conv.kind === "chat" ? await accountName(this.db, conv.account_id) : "",
+                triggerAccountId: run.trigger_account_id,
+                source: conv.source,
+                role,
+                kind: conv.kind,
+                toolKeysByPlugin: () => this.pluginToolKeys(conv, agent),
+                // the run's own abort watch starts with its execution below: until then, the shutdown
+                signal: state.shutdown.signal,
+            });
+            await this.hooks?.beforeRunning?.(runId, conversationId);
+            // never over a terminal status: a run finished meanwhile stays finished
             const updated = await this.db
                 .updateTable("runs")
                 .set({ status: "running", started_at: sql `COALESCE(started_at, now())` })
                 .where("id", "=", runId)
+                .where("status", "in", ["queued", "running"])
                 .returning("started_at")
-                .executeTakeFirstOrThrow();
+                .executeTakeFirst();
+            if (updated === undefined)
+                return "finished";
             startedAt = updated.started_at;
         }
+        // the run executes (a first start, a resume, a stalled takeover): a hint to the side paths (the
+        // channel outbound delivers its output to IM), after the start went through, never for a run a
+        // stop ended first; a failure does not affect the run
+        void this.events.emit("run.started", { conversationId, runId });
         // 截止时间以首次开始为准：停机后在其他 worker 续跑也不重新计时；等人处理的时长（waited_ms）不计入。
         // `runtime.maxRunSeconds` 0: no deadline, no timer (the run ends when the model stops or is stopped)
         const deadline = runDeadline(startedAt.getTime() + Number(run.waited_ms), runtime.maxRunSeconds);
@@ -688,6 +747,9 @@ let RunWorker = class RunWorker {
                     runId,
                     agentId: conv.agent_id,
                     triggerAccountId: run.trigger_account_id,
+                    source: conv.source,
+                    ownerAccountId: conv.account_id,
+                    role,
                     agent,
                     agentVersion: run.agent_version,
                     signal: ac.signal,
@@ -788,6 +850,28 @@ let RunWorker = class RunWorker {
         // a completed run enqueues the conversation's title job (never throws)
         void this.titles.maybeEnqueue(conversationId);
     }
+    /**
+     * The run's extension tool keys by plugin, resolved as a chat run's first step lists them
+     * (disabled tools, org switches, the conversation's source): a provider's `tools`.
+     */
+    async pluginToolKeys(conv, agent) {
+        const { tools } = await this.tools.forAgent(conv.org_id, {
+            disabledTools: agent.disabledTools,
+            subagentTools: agent.subagentTools,
+            subagents: agent.subagents,
+            sandboxConversationId: conv.id,
+            source: conv.source,
+        });
+        const out = new Map();
+        for (const t of tools) {
+            if (t.source.kind !== "plugin")
+                continue;
+            const keys = out.get(t.source.plugin) ?? [];
+            keys.push(t.key);
+            out.set(t.source.plugin, keys);
+        }
+        return out;
+    }
     /**
      * When the conversation was switched to a model that no longer resolves (provider disabled,
      * model removed), writes `model_switched { model: null, effort: null, reason: "unavailable" }`
@@ -834,6 +918,17 @@ let RunWorker = class RunWorker {
             .where("id", "=", conversationId)
             .forUpdate()
             .execute();
+        // the run's status again under the locks (conversation, then run, as `RunFinish.finishIn`):
+        // the job read it before taking the conversation lock, and a stop may have ended it since
+        const row = await t
+            .selectFrom("runs")
+            .select("status")
+            .where("id", "=", run.id)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!row || TERMINAL_STATUSES.has(row.status)) {
+            return { toSeq: undefined, agent: current, terminal: true };
+        }
         const agent = saved !== undefined
             ? effectiveDefinition(saved, await readSelection(t, conversationId))
             : current;
@@ -951,10 +1046,12 @@ RunWorker = __decorate([
     __param(16, Inject(ProviderRegistry)),
     __param(17, Inject(SkillsCatalogService)),
     __param(18, Inject(RunContextService)),
-    __param(19, Inject(RunFinish)),
-    __param(20, Inject(TransactionHost)),
-    __param(21, Inject(RunDrafts)),
-    __param(22, Optional()),
-    __param(22, Inject(RUN_HOOKS))
+    __param(19, Inject(PluginContextService)),
+    __param(20, Inject(ToolRegistry)),
+    __param(21, Inject(RunFinish)),
+    __param(22, Inject(TransactionHost)),
+    __param(23, Inject(RunDrafts)),
+    __param(24, Optional()),
+    __param(24, Inject(RUN_HOOKS))
 ], RunWorker);
 export { RunWorker };

package/dist/runtime/runtime.module.js

@@ -23,6 +23,7 @@ import { RunAbort } from "./abort.js";
 import { KyselyCheckpointSaver } from "./checkpointer.js";
 import { ConversationLock } from "./conversation-lock.js";
 import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
+import { PluginContextService } from "./plugin-context.service.js";
 import { ProvidersModule } from "./providers.js";
 import { EVAL_QUOTA, EVAL_QUOTA_PREFIX, OrgQuota, RUN_QUOTA, RUN_QUOTA_PREFIX } from "./quota.js";
 import { RunContextService } from "./run-context.service.js";
@@ -83,6 +84,7 @@ RuntimeModule = __decorate([
             AgentLoops,
             RunSteps,
             RunContextService,
+            PluginContextService,
             RunWorker,
             // a finished background task wakes an idle conversation (background Bash spec §3)
             BackgroundWake,

package/dist/runtime/subagents/dispatch.js

@@ -121,6 +121,7 @@ export async function dispatchSubagent(d, a) {
             parent_conversation_id: ctx.conversationId,
             subagent_type: entry.type,
             subagent_depth: childDepth,
+            source: "subagent",
         })
             .execute();
         const [, task] = await d.eventLog.appendIn(childId, [

package/dist/runtime/subagents/skill-fork.js

@@ -125,6 +125,9 @@ export async function advanceSkillForks(d, a) {
             agentVersion: ctx.agentVersion,
             agent: ctx.agent,
             accountId: ctx.triggerAccountId,
+            source: ctx.source,
+            ownerAccountId: ctx.ownerAccountId,
+            role: ctx.role,
             signal: ctx.signal,
             ...(ctx.limits.deadline !== undefined && { deadline: ctx.limits.deadline }),
             ...(ctx.conversationKind !== undefined &&

package/dist/sandbox/jobs.d.ts

@@ -1,5 +1,6 @@
 import type { Job, Queue } from "bullmq";
 import { LockService } from "../infra/lock/lock.service.js";
+import type { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 import { SandboxService } from "./sandbox.service.js";
 /** The idle suspension sweep (every minute, once per tick across replicas). */
@@ -7,10 +8,25 @@ export declare const SANDBOX_SUSPEND_JOB = "sandbox-suspend-idle";
 /** The inactivity destruction sweep (hourly, once per tick across replicas). */
 export declare const SANDBOX_DESTROY_JOB = "sandbox-destroy-inactive";
 /**
- * One-off job: destroy a batch of devices now, instance and file system (device
- * deletion, offboarding; data `{ deviceIds }`).
+ * One-off job: destroy devices now, instance and file system (data `{ deviceIds }`). Owed through
+ * the outbox by the transaction that soft-deletes the device (a device's deletion, offboarding),
+ * one device per job under {@link deviceDestroyJobId} ({@link oweDeviceDestroy}).
  */
 export declare const SANDBOX_DESTROY_FOR_JOB = "sandbox-destroy-for";
+/** The data of a {@link SANDBOX_DESTROY_FOR_JOB} job. */
+export interface SandboxDestroyForData {
+    deviceIds: string[];
+}
+/**
+ * The deterministic id of a deleted device's destroy job (no `:`): a device is deleted once, so
+ * its destruction is owed once.
+ */
+export declare const deviceDestroyJobId: (deviceId: string) => string;
+/**
+ * Owes the destruction of a device in the caller's transaction, the one that soft-deleted it
+ * (transactional outbox spec §8.1; throws outside a transaction).
+ */
+export declare function oweDeviceDestroy(outbox: Pick<OutboxService, "add">, deviceId: string, orgId: string): Promise<boolean>;
 /**
  * One-off job: start a device over with empty files (`resetFileSystem`; data
  * `{ deviceId }`, job id {@link resetFilesJobId}).
@@ -22,18 +38,12 @@ export declare const SANDBOX_RESET_FILES_JOB = "sandbox-reset-files";
  */
 export declare const resetFilesJobId: (deviceId: string) => string;
 /**
- * The producer of the sandbox maintenance jobs: {@link SANDBOX_DESTROY_FOR_JOB} (BullMQ's own job
- * ids, as before: every enqueue is a new job, also after a batch failed all its attempts) and
- * {@link SANDBOX_RESET_FILES_JOB}; `MaintenanceProcessor` consumes them.
+ * The producer of {@link SANDBOX_RESET_FILES_JOB} (destroys are owed through the outbox,
+ * {@link oweDeviceDestroy}); `MaintenanceProcessor` consumes both.
  */
 export declare class SandboxJobs {
     private readonly queue;
     constructor(queue: Pick<Queue, "add">);
-    /**
-     * Enqueues the destruction of these devices: a failed batch is retried whole (destroying
-     * one already destroyed does nothing).
-     */
-    destroy(deviceIds: string[]): Promise<void>;
     /**
      * Enqueues the reset of a device's files (see {@link resetFilesJobId}): retried on failure
      * (the exclusive lease not obtained in time, the provider failing); a job that failed all its

package/dist/sandbox/jobs.js

@@ -19,10 +19,29 @@ export const SANDBOX_SUSPEND_JOB = "sandbox-suspend-idle";
 /** The inactivity destruction sweep (hourly, once per tick across replicas). */
 export const SANDBOX_DESTROY_JOB = "sandbox-destroy-inactive";
 /**
- * One-off job: destroy a batch of devices now, instance and file system (device
- * deletion, offboarding; data `{ deviceIds }`).
+ * One-off job: destroy devices now, instance and file system (data `{ deviceIds }`). Owed through
+ * the outbox by the transaction that soft-deletes the device (a device's deletion, offboarding),
+ * one device per job under {@link deviceDestroyJobId} ({@link oweDeviceDestroy}).
  */
 export const SANDBOX_DESTROY_FOR_JOB = "sandbox-destroy-for";
+/**
+ * The deterministic id of a deleted device's destroy job (no `:`): a device is deleted once, so
+ * its destruction is owed once.
+ */
+export const deviceDestroyJobId = (deviceId) => `device-destroy-${deviceId}`;
+/**
+ * Owes the destruction of a device in the caller's transaction, the one that soft-deleted it
+ * (transactional outbox spec §8.1; throws outside a transaction).
+ */
+export function oweDeviceDestroy(outbox, deviceId, orgId) {
+    return outbox.add({
+        queue: MAINTENANCE_QUEUE_NAME,
+        name: SANDBOX_DESTROY_FOR_JOB,
+        jobId: deviceDestroyJobId(deviceId),
+        data: { deviceIds: [deviceId] },
+        orgId,
+    });
+}
 /**
  * One-off job: start a device over with empty files (`resetFileSystem`; data
  * `{ deviceId }`, job id {@link resetFilesJobId}).
@@ -34,27 +53,14 @@ export const SANDBOX_RESET_FILES_JOB = "sandbox-reset-files";
  */
 export const resetFilesJobId = (deviceId) => `${SANDBOX_RESET_FILES_JOB}-${deviceId}`;
 /**
- * The producer of the sandbox maintenance jobs: {@link SANDBOX_DESTROY_FOR_JOB} (BullMQ's own job
- * ids, as before: every enqueue is a new job, also after a batch failed all its attempts) and
- * {@link SANDBOX_RESET_FILES_JOB}; `MaintenanceProcessor` consumes them.
+ * The producer of {@link SANDBOX_RESET_FILES_JOB} (destroys are owed through the outbox,
+ * {@link oweDeviceDestroy}); `MaintenanceProcessor` consumes both.
  */
 let SandboxJobs = class SandboxJobs {
     queue;
     constructor(queue) {
         this.queue = queue;
     }
-    /**
-     * Enqueues the destruction of these devices: a failed batch is retried whole (destroying
-     * one already destroyed does nothing).
-     */
-    async destroy(deviceIds) {
-        await this.queue.add(SANDBOX_DESTROY_FOR_JOB, { deviceIds }, {
-            attempts: 5,
-            backoff: { type: "exponential", delay: 30_000 },
-            removeOnComplete: true,
-            removeOnFail: 100,
-        });
-    }
     /**
      * Enqueues the reset of a device's files (see {@link resetFilesJobId}): retried on failure
      * (the exclusive lease not obtained in time, the provider failing); a job that failed all its

package/dist/schedules/fire.d.ts

@@ -7,8 +7,10 @@ import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { LockService } from "../infra/lock/lock.service.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
+import { type SchedSettleJobData } from "./job-ids.js";
 import { ScheduledTaskRunTracker } from "./run-tracker.js";
 import { ScheduledTaskStore } from "./store.js";
 /** A task run's message client id in a conversation's queue (never read back as "the task's"). */
@@ -21,10 +23,12 @@ export declare function localTimeOf(at: Date, timeZone: string): string;
  *
  * 1. The claim, one transaction under the org row lock (which serializes the org's rate limit
  *    count), then the task run and the task rows: the checks in order (task paused since the
- *    scan, unless a person's "run now"; org disabled, creator
- *    inactive or not a member, agent gone or not visible, conversation gone, connection inactive,
+ *    scan, unless a person's "run now"; a tick fired more than 10 minutes past the org's catch-up
+ *    window, `missed`, unless a "run now"; org disabled, creator inactive or not a member, agent
+ *    gone or not visible, conversation gone, connection inactive,
  *    overlap, rate limit, device offline, queue paused), each a `skipped` run with its reason, the
- *    lasting ones also pausing the task; then `fired_at` is written, after the rate limit count.
+ *    lasting ones also pausing the task; then `fired_at` is written, after the rate limit count,
+ *    with the run's delayed settle check owed (`sched-settle`, {@link settle}).
  *    A run whose claim committed before (a retried job) goes straight to the start.
  * 2. The start, idempotent: `new` creates the conversation with its first message keyed by the
  *    task run id (`create_request_id`); `conversation` queues the prompt in the target
@@ -51,12 +55,29 @@ export declare class ScheduledTaskFirer {
     /** Reads a local device's connection lease (online or not). */
     private readonly locks;
     private readonly log;
+    /** The claim owes the run's settle check (ruling R26). */
+    private readonly outbox;
     constructor(kdb: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, store: ScheduledTaskStore, tracker: Pick<ScheduledTaskRunTracker, "inFlightIn" | "failStartIn">, orgLock: Pick<OrgLock, "tryLock">, agents: Pick<AgentLookup, "get">, access: Pick<ConversationAccess, "isAccessible">, conversations: Pick<ConversationsService, "createWithMessage" | "create">, queue: Pick<ConversationQueue, "add">, connections: Pick<ChannelConnections, "row" | "channel">, 
     /** Reads a local device's connection lease (online or not). */
-    locks: Pick<LockService, "holderOf">, log: Pick<KernelLogger, "warn" | "info">);
+    locks: Pick<LockService, "holderOf">, log: Pick<KernelLogger, "warn" | "info">, 
+    /** The claim owes the run's settle check (ruling R26). */
+    outbox: Pick<OutboxService, "add">);
     private get db();
     /** Fires task run `taskRunId` (see the class); a run not `pending` is left as it is. */
     fire(taskRunId: string): Promise<void>;
+    /**
+     * The `sched-settle` job (ruling R26; `job-ids.ts`). The claimed check: a task run claimed
+     * (`fired_at`) and still `pending` goes through the run tracker's check, which links it to its
+     * run, settles it, or releases a run that left no trace (`skipped`, `removed`), so a `once`
+     * task's last run never stays pending; one still in flight (its item queued, its message posted)
+     * owes the next check an hour on. The unfired check: a run still `pending` that no claim took
+     * (its fire job failed for good before the claim) is skipped, `missed` for a tick, `removed` for
+     * a "run now", so the overlap check never waits on it. A run claimed, started, ended or skipped
+     * since is left as it is (the claimed check follows a claimed run).
+     */
+    settle(data: SchedSettleJobData): Promise<void>;
+    /** The unfired check (see {@link settle}), task row first (the one lock order). */
+    private settleUnfired;
     /** Step 1 (see the class): a skip, the plan, or null when there is nothing to fire. */
     private claim;
     /** Step 2 (see the class). */

package/dist/schedules/fire.js

@@ -16,19 +16,20 @@ import { ConversationAccess, ConversationAccessModule } from "../conversations/a
 import { ConversationsModule } from "../conversations/conversations.module.js";
 import { ConversationsService } from "../conversations/conversations.service.js";
 import { ConversationQueue } from "../conversations/queue.service.js";
+import { channelSource } from "../conversations/source.js";
 import { ApiError } from "../errors.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { LockService } from "../infra/lock/lock.service.js";
-import { QueueModule } from "../infra/queue/queue.module.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { deviceLeaseKey } from "../local-devices/keys.js";
 import { OrgLock, OrgLockModule } from "../orgs/org-lock.js";
-import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
 import { RuntimeModule } from "../runtime/runtime.module.js";
 import { readScheduleSettings } from "./effective-settings.js";
+import { oweSchedSettle, SCHED_LATE_FIRE_SLACK_MS, SCHED_SETTLE_AFTER_MS, SCHED_SETTLE_LONG_CHECKS, SCHED_SETTLE_RECHECK_MS, } from "./job-ids.js";
 import { pauseTaskIn } from "./pause.js";
 import { lockTaskRow, ScheduledTaskRunTracker, ScheduledTaskTrackerModule } from "./run-tracker.js";
 import { ScheduledTaskScanJob } from "./scan.job.js";
@@ -69,10 +70,12 @@ const DEVICE_GONE = new Set(["device.not_found", "device.unavailable", "sandbox.
  *
  * 1. The claim, one transaction under the org row lock (which serializes the org's rate limit
  *    count), then the task run and the task rows: the checks in order (task paused since the
- *    scan, unless a person's "run now"; org disabled, creator
- *    inactive or not a member, agent gone or not visible, conversation gone, connection inactive,
+ *    scan, unless a person's "run now"; a tick fired more than 10 minutes past the org's catch-up
+ *    window, `missed`, unless a "run now"; org disabled, creator inactive or not a member, agent
+ *    gone or not visible, conversation gone, connection inactive,
  *    overlap, rate limit, device offline, queue paused), each a `skipped` run with its reason, the
- *    lasting ones also pausing the task; then `fired_at` is written, after the rate limit count.
+ *    lasting ones also pausing the task; then `fired_at` is written, after the rate limit count,
+ *    with the run's delayed settle check owed (`sched-settle`, {@link settle}).
  *    A run whose claim committed before (a retried job) goes straight to the start.
  * 2. The start, idempotent: `new` creates the conversation with its first message keyed by the
  *    task run id (`create_request_id`); `conversation` queues the prompt in the target
@@ -98,9 +101,12 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
     connections;
     locks;
     log;
+    outbox;
     constructor(kdb, txHost, config, store, tracker, orgLock, agents, access, conversations, queue, connections, 
     /** Reads a local device's connection lease (online or not). */
-    locks, log) {
+    locks, log, 
+    /** The claim owes the run's settle check (ruling R26). */
+    outbox) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.config = config;
@@ -114,6 +120,7 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
         this.connections = connections;
         this.locks = locks;
         this.log = log;
+        this.outbox = outbox;
     }
     get db() {
         return this.kdb.db;
@@ -137,6 +144,61 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
             return;
         await this.start(claimed.plan);
     }
+    /**
+     * The `sched-settle` job (ruling R26; `job-ids.ts`). The claimed check: a task run claimed
+     * (`fired_at`) and still `pending` goes through the run tracker's check, which links it to its
+     * run, settles it, or releases a run that left no trace (`skipped`, `removed`), so a `once`
+     * task's last run never stays pending; one still in flight (its item queued, its message posted)
+     * owes the next check an hour on. The unfired check: a run still `pending` that no claim took
+     * (its fire job failed for good before the claim) is skipped, `missed` for a tick, `removed` for
+     * a "run now", so the overlap check never waits on it. A run claimed, started, ended or skipped
+     * since is left as it is (the claimed check follows a claimed run).
+     */
+    async settle(data) {
+        const { taskRunId } = data;
+        if ("unfired" in data) {
+            await this.settleUnfired(taskRunId);
+            return;
+        }
+        const run = await this.store.updateRun(this.db, taskRunId, {});
+        if (run?.status !== "pending" || run.firedAt === null)
+            return;
+        // inFlightIn takes the task row before the run (the one lock order)
+        if (!(await this.tracker.inFlightIn(run)))
+            return;
+        const now = await this.store.updateRun(this.db, taskRunId, {});
+        if (now?.status !== "pending" || now.firedAt === null)
+            return;
+        const next = data.check + 1;
+        if (next === SCHED_SETTLE_LONG_CHECKS) {
+            this.log.warn("scheduled task run still in flight a week after its claim", {
+                taskId: run.taskId,
+                taskRunId,
+            });
+        }
+        await oweSchedSettle(this.outbox, taskRunId, run.orgId, next, SCHED_SETTLE_RECHECK_MS);
+    }
+    /** The unfired check (see {@link settle}), task row first (the one lock order). */
+    async settleUnfired(taskRunId) {
+        const t = this.db;
+        const owner = await t
+            .selectFrom("scheduled_task_runs")
+            .select("task_id")
+            .where("id", "=", taskRunId)
+            .executeTakeFirst();
+        if (!owner)
+            return;
+        await lockTaskRow(t, owner.task_id);
+        const run = await t
+            .selectFrom("scheduled_task_runs")
+            .select(["status", "fired_at", "manual"])
+            .where("id", "=", taskRunId)
+            .forUpdate()
+            .executeTakeFirst();
+        if (run?.status !== "pending" || run.fired_at !== null)
+            return;
+        await this.skipIn(t, taskRunId, owner.task_id, run.manual ? "removed" : "missed");
+    }
     /** Step 1 (see the class): a skip, the plan, or null when there is nothing to fire. */
     async claim(taskRunId, orgId, deviceOffline) {
         const t = this.db;
@@ -179,6 +241,12 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
         if (!resumed && !run.manual && task.status === "paused")
             return skip("task_paused");
         const settings = await readScheduleSettings(t, this.config, orgId);
+        // a tick whose fire comes this late (workers down for long) is missed, as the scan records a
+        // tick it finds outside the window; a person's "run now" still runs
+        const lateAfter = settings.catchUpWindowMinutes * 60_000 + SCHED_LATE_FIRE_SLACK_MS;
+        if (!resumed && !run.manual && Date.now() - run.scheduledFor.getTime() > lateAfter) {
+            return skip("missed");
+        }
         if (!resumed && !settings.enabled)
             return skip("org_disabled");
         if (!resumed && !(await this.creatorActive(orgId, task.accountId))) {
@@ -260,6 +328,8 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
             firedAt: new Date(),
             ...(plan.mode === "conversation" && { conversationId: plan.conversationId }),
         });
+        // a start that fails for good leaves the run claimed: its settle check releases or ends it
+        await oweSchedSettle(this.outbox, run.id, orgId, 0, SCHED_SETTLE_AFTER_MS);
         return { plan: { ...plan, run: claimed ?? run } };
     }
     /** Step 2 (see the class). */
@@ -282,7 +352,7 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
                     ...(task.model !== null && { model: task.model }),
                     ...(task.effort !== null && { effort: task.effort }),
                 };
-                const out = await this.conversations.createWithMessage(task.orgId, task.accountId, task.agentId, { text: task.prompt, clientMessageId: run.id, ...pick }, task.deviceId === null ? {} : { deviceId: task.deviceId }, internal);
+                const out = await this.conversations.createWithMessage(task.orgId, task.accountId, task.agentId, { text: task.prompt, clientMessageId: run.id, ...pick }, task.deviceId === null ? {} : { deviceId: task.deviceId }, { ...internal, source: "web" });
                 // a retried start found the conversation made before: `createWithMessage` already asked
                 // for its run (and the first start's message owes the ensure-run backstop)
                 await this.setConversation(run.id, out.conversation.id);
@@ -345,7 +415,7 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
         const { conversationId, created } = await findOrBindThread(t, plan.thread, plan.target, async () => {
             const conv = await this.conversations.create(task.orgId, task.accountId, task.agentId, 
             // a chat task takes no device (new mode only): an IM conversation's default
-            { im: true });
+            { im: true }, { source: channelSource(plan.target.chatType) });
             await t
                 .updateTable("conversations")
                 .set({ scheduled_task_id: task.id })
@@ -382,15 +452,17 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
             return null;
         if (locked.conversation_id !== null)
             return locked.conversation_id;
+        const target = { chatId: plan.chatId, chatType: "group" };
         const conv = await this.conversations.create(task.orgId, task.accountId, task.agentId, 
         // a chat task takes no device (new mode only): an IM conversation's default
-        { im: true });
+        { im: true }, 
+        // stored now: the thread to derive it from binds only at the run's first post
+        { source: channelSource(target.chatType) });
         await t
             .updateTable("conversations")
             .set({ scheduled_task_id: task.id })
             .where("id", "=", conv.id)
             .execute();
-        const target = { chatId: plan.chatId, chatType: "group" };
         await t
             .insertInto("channel_deliveries")
             .values({
@@ -558,6 +630,9 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
         return (await this.locks.holderOf(deviceLeaseKey(deviceId))) === null;
     }
 };
+__decorate([
+    Transactional()
+], ScheduledTaskFirer.prototype, "settle", null);
 __decorate([
     Transactional()
 ], ScheduledTaskFirer.prototype, "claim", null);
@@ -590,7 +665,8 @@ ScheduledTaskFirer = __decorate([
     __param(9, Inject(ConversationQueue)),
     __param(10, Inject(ChannelConnections)),
     __param(11, Inject(LockService)),
-    __param(12, Inject(KERNEL_LOGGER))
+    __param(12, Inject(KERNEL_LOGGER)),
+    __param(13, Inject(OutboxService))
 ], ScheduledTaskFirer);
 export { ScheduledTaskFirer };
 /**
@@ -610,8 +686,6 @@ ScheduledTaskFireModule = __decorate([
             OrgLockModule,
             ScheduledTaskStoreModule,
             ScheduledTaskTrackerModule,
-            // the scanner enqueues the fire jobs
-            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
         ],
         providers: [ScheduledTaskFirer, ScheduledTaskScanJob],
         exports: [ScheduledTaskFirer],