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

package/dist/runtime/subagents/deliveries.d.ts

@@ -3,6 +3,7 @@ import type { EventPayload } from "../../conversations/events.js";
 import { KernelDb } from "../../infra/database/kernel-db.js";
 import { TransactionHost } from "../../infra/database/transaction-host.js";
 import { KernelEvents } from "../../infra/events/kernel-events.js";
+import { OutboxService } from "../../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../../log.js";
 import { type DispatchRow } from "./child.js";
 /** What a caller of {@link SubagentDeliveries.deliverIn} gives; the rest comes from the dispatch. */
@@ -17,7 +18,7 @@ export declare const finishedDeliveryIdemKey: (childRunId: string) => string;
  *
  * A background child's run reaching a terminal state ({@link childFinished}) writes the
  * display-only `subagent_finished` and a `finished` delivery in one transaction, both idempotent by
- * the child run, so of two finishers (the worker and a stop, the orphan sweep) exactly one writes
+ * the child run, so of two finishers (the worker, a stop, the `deliver-to-parent` job, the `run-orphan-check`) exactly one writes
  * them. A run that handed back a report and then completed writes no delivery (acceptance
  * 2026-11-07): the report already told the parent everything, and a content-free "completed" line
  * only woke an idle parent for nothing and pushed the report away from the end of its request. Fork invocations (phase D, `for_skill`) do not deliver: their parent run waits on the child
@@ -29,7 +30,8 @@ export declare class SubagentDeliveries {
     private readonly events;
     private readonly log;
     readonly txHost: TransactionHost;
-    constructor(kdb: KernelDb, eventLog: EventLog, events: KernelEvents, log: Pick<KernelLogger, "warn">, txHost: TransactionHost);
+    private readonly outbox;
+    constructor(kdb: KernelDb, eventLog: EventLog, events: KernelEvents, log: Pick<KernelLogger, "warn">, txHost: TransactionHost, outbox: Pick<OutboxService, "add">);
     /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
     private get db();
     /**
@@ -38,7 +40,8 @@ export declare class SubagentDeliveries {
      * the child run's (a wake runs as that person, §7). Idempotent by `opts.idemKey` (a finish's
      * default is {@link finishedDeliveryIdemKey}; a report or a note must name its own): under the
      * parent conversation's row lock, an existing delivery returns null and writes nothing. After
-     * the commit: the log's notify and `subagent.delivered`. Returns the new event's seq.
+     * the commit: the log's notify and `subagent.delivered`; the parent's ensure-run backstop is
+     * owed in the transaction. Returns the new event's seq.
      */
     deliverIn(row: DispatchRow, d: DeliveryInput, opts?: {
         idemKey?: string;

package/dist/runtime/subagents/deliveries.js

@@ -15,8 +15,9 @@ 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 { KernelEvents } from "../../infra/events/kernel-events.js";
+import { OutboxService } from "../../infra/outbox/outbox.service.js";
 import { KERNEL_LOGGER } from "../../infra/tokens.js";
-import { TERMINAL_STATUSES } from "../run-finish.js";
+import { oweEnsureRun, TERMINAL_STATUSES } from "../run-jobs.js";
 import { childResult, deliveryRowOfChildRun, finishedEvent } from "./child.js";
 import { dispatchedIdemKey } from "./dispatch.js";
 /** Idempotency key of a child run's finished delivery (one per child run). */
@@ -31,7 +32,7 @@ const DELIVERY_TEXT_MAX = 200_000;
  *
  * A background child's run reaching a terminal state ({@link childFinished}) writes the
  * display-only `subagent_finished` and a `finished` delivery in one transaction, both idempotent by
- * the child run, so of two finishers (the worker and a stop, the orphan sweep) exactly one writes
+ * the child run, so of two finishers (the worker, a stop, the `deliver-to-parent` job, the `run-orphan-check`) exactly one writes
  * them. A run that handed back a report and then completed writes no delivery (acceptance
  * 2026-11-07): the report already told the parent everything, and a content-free "completed" line
  * only woke an idle parent for nothing and pushed the report away from the end of its request. Fork invocations (phase D, `for_skill`) do not deliver: their parent run waits on the child
@@ -43,12 +44,14 @@ let SubagentDeliveries = class SubagentDeliveries {
     events;
     log;
     txHost;
-    constructor(kdb, eventLog, events, log, txHost) {
+    outbox;
+    constructor(kdb, eventLog, events, log, txHost, outbox) {
         this.kdb = kdb;
         this.eventLog = eventLog;
         this.events = events;
         this.log = log;
         this.txHost = txHost;
+        this.outbox = outbox;
     }
     /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
     get db() {
@@ -60,7 +63,8 @@ let SubagentDeliveries = class SubagentDeliveries {
      * the child run's (a wake runs as that person, §7). Idempotent by `opts.idemKey` (a finish's
      * default is {@link finishedDeliveryIdemKey}; a report or a note must name its own): under the
      * parent conversation's row lock, an existing delivery returns null and writes nothing. After
-     * the commit: the log's notify and `subagent.delivered`. Returns the new event's seq.
+     * the commit: the log's notify and `subagent.delivered`; the parent's ensure-run backstop is
+     * owed in the transaction. Returns the new event's seq.
      */
     async deliverIn(row, d, opts = {}) {
         const idemKey = opts.idemKey ?? (d.kind === "finished" ? finishedDeliveryIdemKey(row.childRunId) : undefined);
@@ -68,9 +72,9 @@ let SubagentDeliveries = class SubagentDeliveries {
             throw new Error(`a ${d.kind} delivery needs its idempotency key`);
         const t = this.db;
         const parent = row.parentConversationId;
-        await t
+        const conv = await t
             .selectFrom("conversations")
-            .select("id")
+            .select("org_id")
             .where("id", "=", parent)
             .forUpdate()
             .executeTakeFirst();
@@ -103,6 +107,10 @@ let SubagentDeliveries = class SubagentDeliveries {
         ]);
         if (!event)
             return null;
+        // the parent's wake is owed with the delivery: the wake after the commit (`BackgroundWake`)
+        // may never happen (transactional outbox spec §6)
+        if (conv)
+            await oweEnsureRun(this.outbox, parent, event.seq, conv.org_id);
         afterCommit(async () => {
             await this.eventLog.notify(parent, event.seq);
             await this.events.emit("subagent.delivered", { conversationId: parent });
@@ -223,6 +231,7 @@ SubagentDeliveries = __decorate([
     __param(1, Inject(EventLog)),
     __param(2, Inject(KernelEvents)),
     __param(3, Inject(KERNEL_LOGGER)),
-    __param(4, Inject(TransactionHost))
+    __param(4, Inject(TransactionHost)),
+    __param(5, Inject(OutboxService))
 ], SubagentDeliveries);
 export { SubagentDeliveries };

package/dist/runtime/subagents/dispatch.d.ts

@@ -18,8 +18,11 @@ export interface DispatchDeps {
     purposes: Pick<ModelPurposesService, "resolve">;
     registry: Pick<ProviderRegistry, "resolve">;
     config: Pick<KernelConfigService, "get">;
-    /** Enqueues a child run (on the sub-agent run queue: `kind` is always `subagent`). */
-    enqueue: (data: RunJobData, jobId: string, kind: ConversationKind) => Promise<void>;
+    /**
+     * Owes a child run's job in the dispatch's transaction (`RunJobs.owe`: on the sub-agent run
+     * queue, `kind` is always `subagent`); false when the job id is already owed.
+     */
+    owe: (data: RunJobData, jobId: string, kind: ConversationKind, orgId: string) => Promise<boolean>;
     log: Pick<Logger, "error" | "warn">;
     /**
      * Runs {@link commitDispatchIn} in a transaction of its own (`SubagentsService.commitDispatch`,
@@ -121,9 +124,9 @@ export interface DispatchPlan {
  * dispatches of one run serialize) inserts the child conversation, appends `subagent_started` and
  * the task message, inserts the child run (`queued`) and the `subagent_dispatches` row, appends
  * `subagent_dispatched` and the call's `tool_result` ({@link agentStartedText}: the sub-agent runs
- * in the background) to the parent and audits `subagent.dispatched` and `tool.called`. After
- * commit the child run is enqueued; a failed enqueue only logs (the dispatch is durable, the wait
- * sweep re-enqueues it). A fork invocation (`forSkill`) writes no `tool_result`: its run waits on
+ * in the background) to the parent and audits `subagent.dispatched` and `tool.called`. The child
+ * run's job is owed in the same transaction (transactional outbox spec §6), so the committed
+ * dispatch always starts its child. A fork invocation (`forSkill`) writes no `tool_result`: its run waits on
  * the child (`advanceSkillForks`).
  *
  * Refusals (§4.5) start nothing: a call from a run at `subagents.maxDepth` (agent map spec §4.1:
@@ -188,7 +191,8 @@ export declare const sentMessageIdemKey: (runId: string, callId: string) => stri
  * row, then the parent run row (the order every terminal path uses),
  * runs `child` (writes the child conversation's first events and returns the task message, or
  * null to refuse), then inserts the child run and the dispatch row, appends `subagent_dispatched`
- * and the audit row. After commit: notifies both conversations and enqueues the child run.
+ * and the audit row, and owes the child run's job (transactional outbox spec §6). After commit:
+ * notifies both conversations.
  * Returns null when `child` refused.
  *
  * Under the parent run's row lock it first re-checks what the pipeline checked without it: a call
@@ -205,10 +209,6 @@ export type DispatchCommit = {
     kind: "existing";
     childRunId: string;
     childConversationId: string;
-    requeue: {
-        conversationId: string;
-        seq: number;
-    } | null;
     /** The call's logged result (null for a fork dispatch) and its seq, to notify. */
     result: {
         content: string;
@@ -233,7 +233,7 @@ export type DispatchCommit = {
  * {@link commit}'s transaction (run by `SubagentsService.commitDispatch`, `d.db` its handle).
  * Null when `child` refused.
  */
-export declare function commitDispatchIn(d: Pick<DispatchDeps, "db" | "eventLog" | "config">, a: DispatchArgs, plan: DispatchPlan, child: ChildWriter): Promise<DispatchCommit | null>;
-export declare function commit(d: Pick<DispatchDeps, "commitDispatch" | "enqueue" | "log" | "eventLog">, a: DispatchArgs, plan: DispatchPlan, 
+export declare function commitDispatchIn(d: Pick<DispatchDeps, "db" | "eventLog" | "config" | "owe">, a: DispatchArgs, plan: DispatchPlan, child: ChildWriter): Promise<DispatchCommit | null>;
+export declare function commit(d: Pick<DispatchDeps, "commitDispatch" | "eventLog">, a: DispatchArgs, plan: DispatchPlan, 
 /** Writes the child's events; `checked` is the org agent version the in-lock gates passed. */
 child: ChildWriter): Promise<DispatchOutcome | null>;

package/dist/runtime/subagents/dispatch.js

@@ -31,9 +31,9 @@ export const dispatchedIdemKey = (runId, callId) => `subagent_dispatched:${runId
  * dispatches of one run serialize) inserts the child conversation, appends `subagent_started` and
  * the task message, inserts the child run (`queued`) and the `subagent_dispatches` row, appends
  * `subagent_dispatched` and the call's `tool_result` ({@link agentStartedText}: the sub-agent runs
- * in the background) to the parent and audits `subagent.dispatched` and `tool.called`. After
- * commit the child run is enqueued; a failed enqueue only logs (the dispatch is durable, the wait
- * sweep re-enqueues it). A fork invocation (`forSkill`) writes no `tool_result`: its run waits on
+ * in the background) to the parent and audits `subagent.dispatched` and `tool.called`. The child
+ * run's job is owed in the same transaction (transactional outbox spec §6), so the committed
+ * dispatch always starts its child. A fork invocation (`forSkill`) writes no `tool_result`: its run waits on
  * the child (`advanceSkillForks`).
  *
  * Refusals (§4.5) start nothing: a call from a run at `subagents.maxDepth` (agent map spec §4.1:
@@ -226,7 +226,7 @@ const isActiveStatus = (status) => ACTIVE_RUN_STATUSES.includes(status);
  * delivered (agent map spec, rc upgrade: a foreground-era dispatch whose rc finisher wrote
  * `subagent_finished` and resumed the parent): the child's report (`childResult`), with the
  * parent's `subagent_finished` appended in this transaction when it is missing (idempotent by its
- * key), so the undelivered sweep never delivers it a second time. Null when the parent already
+ * key), so the `deliver-to-parent` job never delivers it a second time. Null when the parent already
  * has a delivery for the run (it carries the result) or the run has no terminal event yet.
  */
 async function rcFinishedResult(d, row) {
@@ -272,7 +272,7 @@ export async function commitDispatchIn(d, a, plan, child) {
     const existing = await t
         .selectFrom("subagent_dispatches as sd")
         .leftJoin("runs as cr", "cr.id", "sd.child_run_id")
-        .select(["sd.child_run_id", "sd.child_conversation_id", "cr.status", "cr.trigger_seq"])
+        .select(["sd.child_run_id", "sd.child_conversation_id", "cr.status"])
         .where("sd.parent_run_id", "=", ctx.runId)
         .where("sd.parent_call_id", "=", callId)
         .executeTakeFirst();
@@ -284,10 +284,10 @@ export async function commitDispatchIn(d, a, plan, child) {
         let result = null;
         if (a.forSkill === undefined) {
             // an rc child that already ended under the foreground wait, whose rc finisher wrote
-            // `subagent_finished` and resumed this run (no delivery; the sweep never delivers a run with
-            // `subagent_finished`): its report is this call's result, as the rc gave it, or it is lost.
+            // `subagent_finished` and resumed this run (no delivery; a run with `subagent_finished` is
+            // never delivered): its report is this call's result, as the rc gave it, or it is lost.
             // Only while the call has no result: a call that has one (a background dispatch's second
-            // holder) keeps it, and its child's finish stays to its delivery or the undelivered sweep.
+            // holder) keeps it, and its child's finish stays to its delivery (or its `deliver-to-parent` job).
             const resultKey = resultEvent(ctx, callId, AGENT_TOOL, "").idemKey;
             const finished = a.sent === undefined &&
                 existing.status !== null &&
@@ -312,13 +312,6 @@ export async function commitDispatchIn(d, a, plan, child) {
             childRunId: existing.child_run_id,
             childConversationId: existing.child_conversation_id,
             result,
-            // still queued: the first holder may have died before its enqueue (review M4)
-            requeue: existing.status === "queued" && existing.trigger_seq !== null
-                ? {
-                    conversationId: existing.child_conversation_id,
-                    seq: Number(existing.trigger_seq),
-                }
-                : null,
         };
     }
     if (parent?.status !== "running")
@@ -384,6 +377,9 @@ export async function commitDispatchIn(d, a, plan, child) {
         for_skill: a.forSkill !== undefined,
     })
         .execute();
+    // the child run's job is owed with its row (transactional outbox spec §6): a queued child
+    // always has its job, whatever happens after the commit
+    await d.owe({ runId: childRunId, conversationId: plan.childConversationId }, runJobId(plan.childConversationId, task.seq), "subagent", ctx.orgId);
     // an org agent runs on its own model (§5.4): a `model` on the call was ignored
     const ownModel = plan.source === "agent" && input.model !== undefined;
     const content = a.sent?.content ?? agentStartedText(plan.childConversationId, { ownModel });
@@ -475,19 +471,7 @@ child) {
     if (out === null)
         return null;
     if (out.kind === "existing") {
-        // a child still queued is enqueued again under the first dispatch's job id (BullMQ dedupes
-        // it while that job exists), so a holder that died before its enqueue does not leave the
-        // child to the wait sweep
-        if (out.requeue !== null) {
-            const jobId = runJobId(out.requeue.conversationId, out.requeue.seq);
-            await d
-                .enqueue({ runId: out.childRunId, conversationId: out.requeue.conversationId }, jobId, "subagent")
-                .catch((err) => d.log.error("cannot enqueue sub-agent run; the sweep retries", {
-                childRunId: out.childRunId,
-                jobId,
-                err,
-            }));
-        }
+        // the child's job was owed with the first dispatch (a still queued child has it)
         if (out.result !== null)
             await d.eventLog.notify(ctx.conversationId, out.result.seq);
         return {
@@ -507,18 +491,9 @@ child) {
         return out.outcome;
     await d.eventLog.notify(plan.childConversationId, out.childSeq);
     await d.eventLog.notify(ctx.conversationId, out.parentSeq);
-    const childRunId = out.childRunId;
-    const jobId = runJobId(plan.childConversationId, out.childSeq);
-    try {
-        await d.enqueue({ runId: childRunId, conversationId: plan.childConversationId }, jobId, "subagent");
-    }
-    catch (err) {
-        // the dispatch is committed: the wait sweep re-enqueues the queued child run
-        d.log.error("cannot enqueue sub-agent run; the sweep retries", { childRunId, jobId, err });
-    }
     return {
         kind: "dispatched",
-        childRunId,
+        childRunId: out.childRunId,
         childConversationId: plan.childConversationId,
         content: out.content,
     };

package/dist/runtime/subagents/messages.d.ts

@@ -50,12 +50,16 @@ export declare class SubagentMessages {
     private readonly kdb;
     private readonly eventLog;
     private readonly config;
+    /** Owes a restarted sub-agent's run job in the dispatch's transaction. */
+    private readonly jobs;
     private readonly deliveries;
     readonly txHost: TransactionHost;
     private readonly hooks?;
     /** What the dispatch transaction of a restart needs (`commit`). */
     private readonly deps;
-    constructor(kdb: KernelDb, eventLog: EventLog, config: KernelConfigService, jobs: RunJobs, log: KernelLogger, deliveries: SubagentDeliveries, txHost: TransactionHost, hooks?: SubagentMessagesHooks | undefined);
+    constructor(kdb: KernelDb, eventLog: EventLog, config: KernelConfigService, 
+    /** Owes a restarted sub-agent's run job in the dispatch's transaction. */
+    jobs: Pick<RunJobs, "owe">, log: KernelLogger, deliveries: SubagentDeliveries, txHost: TransactionHost, hooks?: SubagentMessagesHooks | undefined);
     /** The restart's dispatch writes in a transaction of their own (see `commitDispatchIn`). */
     private commitDispatch;
     /** The context's handle (the transaction of a `@Transactional` method, else the pool). */

package/dist/runtime/subagents/messages.js

@@ -56,28 +56,36 @@ let SubagentMessages = class SubagentMessages {
     kdb;
     eventLog;
     config;
+    jobs;
     deliveries;
     txHost;
     hooks;
     /** What the dispatch transaction of a restart needs (`commit`). */
     deps;
-    constructor(kdb, eventLog, config, jobs, log, deliveries, txHost, hooks) {
+    constructor(kdb, eventLog, config, 
+    /** Owes a restarted sub-agent's run job in the dispatch's transaction. */
+    jobs, log, deliveries, txHost, hooks) {
         this.kdb = kdb;
         this.eventLog = eventLog;
         this.config = config;
+        this.jobs = jobs;
         this.deliveries = deliveries;
         this.txHost = txHost;
         this.hooks = hooks;
         this.deps = {
             eventLog,
-            enqueue: (data, jobId, kind) => jobs.enqueue(data, jobId, kind),
             log,
             commitDispatch: (a, plan, child) => this.commitDispatch(a, plan, child),
         };
     }
     /** The restart's dispatch writes in a transaction of their own (see `commitDispatchIn`). */
     commitDispatch(a, plan, child) {
-        return commitDispatchIn({ db: this.db, eventLog: this.eventLog, config: this.config }, a, plan, child);
+        return commitDispatchIn({
+            db: this.db,
+            eventLog: this.eventLog,
+            config: this.config,
+            owe: (data, jobId, kind, orgId) => this.jobs.owe(data, jobId, kind, orgId),
+        }, a, plan, child);
     }
     /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
     get db() {

package/dist/runtime/subagents/skill-fork.d.ts

@@ -11,8 +11,8 @@ import { type DispatchDeps } from "./dispatch.js";
  * through phase C's `dispatchSubagent` before any model call and waits on it (`subagents` wait
  * `sa-<runId>-0`; the dispatch row has `for_skill`, agent map spec §5.4: a fork stays in the
  * foreground while `Agent` calls run in the background). When the child has ended, `prepare` appends the model-visible
- * `skill_fork_result` and the parent's model answers. Every terminal path of the run (and the wait
- * sweep) pairs a fork invocation without a report ({@link pairStoppedForks}), so the log never holds
+ * `skill_fork_result` and the parent's model answers. Every terminal path of the run
+ * (`RunFinish.finishIn`) pairs a fork invocation without a report ({@link pairStoppedForks}), so the log never holds
  * a fork lead whose report is missing before the next model call.
  */
 /** The dispatch's parent call id (no `:`; there is no tool call). */
@@ -108,7 +108,7 @@ export declare const recordedSkillForks: (eventLog: Pick<EventLog, "append" | "f
     payload: unknown;
 }[]) => SkillForks;
 /**
- * In the transaction of a run's terminal path (or the wait sweep): the run's fork invocation
+ * In the transaction of a run's terminal path (`RunFinish.finishIn`): the run's fork invocation
  * (its trigger message, by the run boundary) without a report gets one now: the ended child's
  * result (and the parent's missing `subagent_finished`), {@link AGENT_STOPPED_WITH_RUN_TEXT} for a
  * child still active (the caller stops it after its commit, as for `Agent` calls), or

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

@@ -1,7 +1,7 @@
 import { ApiError } from "../../errors.js";
 import { AGENT_STOPPED_WITH_RUN_TEXT } from "../../tools/builtins/agent.js";
 import { subagentsWait } from "../loop.js";
-import { TERMINAL_STATUSES } from "../run-finish.js";
+import { TERMINAL_STATUSES } from "../run-jobs.js";
 import { childResult, dispatchOfCall, finishedEvent } from "./child.js";
 import { dispatchSubagent } from "./dispatch.js";
 /**
@@ -10,8 +10,8 @@ import { dispatchSubagent } from "./dispatch.js";
  * through phase C's `dispatchSubagent` before any model call and waits on it (`subagents` wait
  * `sa-<runId>-0`; the dispatch row has `for_skill`, agent map spec §5.4: a fork stays in the
  * foreground while `Agent` calls run in the background). When the child has ended, `prepare` appends the model-visible
- * `skill_fork_result` and the parent's model answers. Every terminal path of the run (and the wait
- * sweep) pairs a fork invocation without a report ({@link pairStoppedForks}), so the log never holds
+ * `skill_fork_result` and the parent's model answers. Every terminal path of the run
+ * (`RunFinish.finishIn`) pairs a fork invocation without a report ({@link pairStoppedForks}), so the log never holds
  * a fork lead whose report is missing before the next model call.
  */
 /** The dispatch's parent call id (no `:`; there is no tool call). */
@@ -126,7 +126,7 @@ export async function advanceSkillForks(d, a) {
             agent: ctx.agent,
             accountId: ctx.triggerAccountId,
             signal: ctx.signal,
-            deadline: ctx.limits.deadline,
+            ...(ctx.limits.deadline !== undefined && { deadline: ctx.limits.deadline }),
             ...(ctx.conversationKind !== undefined &&
                 ctx.conversationKind !== "eval" && { conversationKind: ctx.conversationKind }),
         },
@@ -188,7 +188,7 @@ export const recordedSkillForks = (eventLog, recorded) => ({
     },
 });
 /**
- * In the transaction of a run's terminal path (or the wait sweep): the run's fork invocation
+ * In the transaction of a run's terminal path (`RunFinish.finishIn`): the run's fork invocation
  * (its trigger message, by the run boundary) without a report gets one now: the ended child's
  * result (and the parent's missing `subagent_finished`), {@link AGENT_STOPPED_WITH_RUN_TEXT} for a
  * child still active (the caller stops it after its commit, as for `Agent` calls), or

package/dist/runtime/subagents/subagents.service.js

@@ -53,7 +53,7 @@ let SubagentsService = class SubagentsService {
             purposes,
             registry,
             config,
-            enqueue: (data, jobId, kind) => jobs.enqueue(data, jobId, kind),
+            owe: (data, jobId, kind, orgId) => jobs.owe(data, jobId, kind, orgId),
             log,
             invoker,
             commitDispatch: (a, plan, child) => this.commitDispatch(a, plan, child),

package/dist/runtime/subagents/tree-jobs.d.ts

@@ -0,0 +1,61 @@
+import type { OutboxService } from "../../infra/outbox/outbox.service.js";
+import type { Waits } from "../waits.js";
+/**
+ * The stops a transaction owes a sub-agent tree (transactional outbox spec §6 "Sub-agents"), on
+ * the maintenance queue. Two shapes:
+ * - `{ runId }`: what a run's terminal transaction owes its children: its active fork invocation
+ *   child stops (`Waits.stopChildren`, sub-agents spec §12), and a sub-agent run a person stopped
+ *   stops its descendants (`Waits.stopDescendantsOfStopped`, agent map spec §6);
+ * - `{ conversationId, byAccountId }`: a deleted root's whole tree below it stops
+ *   (`Waits.stopTree` without the root, agent map spec §10).
+ *
+ * The caller still stops them right after its commit; the job is the backstop for a process that
+ * died in between, {@link TREE_JOB_BACKSTOP_MS} later.
+ */
+export declare const STOP_TREE_JOB = "stop-tree";
+/**
+ * A finished sub-agent run's delivery to its parent (`Waits.childFinished`: a background child's
+ * `subagent_finished` and `finished` delivery, a fork child's `subagent_finished` and its parent
+ * run's resume), owed by the child run's terminal transaction. The delivery is not written in that
+ * transaction: it holds the child's conversation and run rows, and the parent's conversation row
+ * comes before the child's in the dispatch's lock order (parent conversation, parent run, budget
+ * run, child conversation), so taking it there could deadlock with a follow-up dispatch. The
+ * caller delivers right after its commit; the job is the backstop, {@link TREE_JOB_BACKSTOP_MS}
+ * later.
+ */
+export declare const DELIVER_TO_PARENT_JOB = "deliver-to-parent";
+/** How long after its transaction a tree job fires (a backstop of the direct call, not a second). */
+export declare const TREE_JOB_BACKSTOP_MS = 30000;
+/** The `stop-tree` job's data. */
+export type StopTreeJobData = {
+    runId: string;
+} | {
+    conversationId: string;
+    byAccountId: string | null;
+};
+/** The `deliver-to-parent` job's data. */
+export interface DeliverToParentJobData {
+    childRunId: string;
+}
+/** The `stop-tree` job id of a finished run's children (no `:`). */
+export declare const stopChildrenJobId: (runId: string) => string;
+/** The `stop-tree` job id of a deleted root's tree (a conversation is deleted once; no `:`). */
+export declare const stopDeletedTreeJobId: (conversationId: string) => string;
+/** The `deliver-to-parent` job id: one per child run (no `:`). */
+export declare const deliverToParentJobId: (childRunId: string) => string;
+/** Owes the stops of `runId`'s children in the caller's transaction (throws outside one). */
+export declare function oweStopChildren(outbox: Pick<OutboxService, "add">, runId: string, orgId: string): Promise<boolean>;
+/** Owes the stop of a deleted root's tree in the caller's transaction (throws outside one). */
+export declare function oweStopDeletedTree(outbox: Pick<OutboxService, "add">, conversationId: string, byAccountId: string | null, orgId: string): Promise<boolean>;
+/** Owes a finished child run's delivery to its parent in the caller's transaction. */
+export declare function oweDeliverToParent(outbox: Pick<OutboxService, "add">, childRunId: string, orgId: string): Promise<boolean>;
+/**
+ * The `stop-tree` job (`MaintenanceProcessor`): every stop reads the active runs and stops only
+ * those, so a run the direct call already stopped is not stopped again.
+ */
+export declare function processStopTree(waits: Pick<Waits, "stopChildren" | "stopDescendantsOfStopped" | "stopTree">, data: StopTreeJobData): Promise<void>;
+/**
+ * The `deliver-to-parent` job (`MaintenanceProcessor`): `Waits.childFinished` writes the delivery
+ * once by the child run (idempotency keys under the parent conversation's row lock).
+ */
+export declare function processDeliverToParent(waits: Pick<Waits, "childFinished">, data: DeliverToParentJobData): Promise<void>;

package/dist/runtime/subagents/tree-jobs.js

@@ -0,0 +1,86 @@
+import { MAINTENANCE_QUEUE_NAME } from "../maintenance-queue.js";
+/**
+ * The stops a transaction owes a sub-agent tree (transactional outbox spec §6 "Sub-agents"), on
+ * the maintenance queue. Two shapes:
+ * - `{ runId }`: what a run's terminal transaction owes its children: its active fork invocation
+ *   child stops (`Waits.stopChildren`, sub-agents spec §12), and a sub-agent run a person stopped
+ *   stops its descendants (`Waits.stopDescendantsOfStopped`, agent map spec §6);
+ * - `{ conversationId, byAccountId }`: a deleted root's whole tree below it stops
+ *   (`Waits.stopTree` without the root, agent map spec §10).
+ *
+ * The caller still stops them right after its commit; the job is the backstop for a process that
+ * died in between, {@link TREE_JOB_BACKSTOP_MS} later.
+ */
+export const STOP_TREE_JOB = "stop-tree";
+/**
+ * A finished sub-agent run's delivery to its parent (`Waits.childFinished`: a background child's
+ * `subagent_finished` and `finished` delivery, a fork child's `subagent_finished` and its parent
+ * run's resume), owed by the child run's terminal transaction. The delivery is not written in that
+ * transaction: it holds the child's conversation and run rows, and the parent's conversation row
+ * comes before the child's in the dispatch's lock order (parent conversation, parent run, budget
+ * run, child conversation), so taking it there could deadlock with a follow-up dispatch. The
+ * caller delivers right after its commit; the job is the backstop, {@link TREE_JOB_BACKSTOP_MS}
+ * later.
+ */
+export const DELIVER_TO_PARENT_JOB = "deliver-to-parent";
+/** How long after its transaction a tree job fires (a backstop of the direct call, not a second). */
+export const TREE_JOB_BACKSTOP_MS = 30_000;
+/** The `stop-tree` job id of a finished run's children (no `:`). */
+export const stopChildrenJobId = (runId) => `stop-tree-run-${runId}`;
+/** The `stop-tree` job id of a deleted root's tree (a conversation is deleted once; no `:`). */
+export const stopDeletedTreeJobId = (conversationId) => `stop-tree-deleted-${conversationId}`;
+/** The `deliver-to-parent` job id: one per child run (no `:`). */
+export const deliverToParentJobId = (childRunId) => `deliver-to-parent-${childRunId}`;
+const backstopAt = () => new Date(Date.now() + TREE_JOB_BACKSTOP_MS);
+/** Owes the stops of `runId`'s children in the caller's transaction (throws outside one). */
+export function oweStopChildren(outbox, runId, orgId) {
+    return outbox.add({
+        queue: MAINTENANCE_QUEUE_NAME,
+        name: STOP_TREE_JOB,
+        jobId: stopChildrenJobId(runId),
+        data: { runId },
+        runAt: backstopAt(),
+        orgId,
+    });
+}
+/** Owes the stop of a deleted root's tree in the caller's transaction (throws outside one). */
+export function oweStopDeletedTree(outbox, conversationId, byAccountId, orgId) {
+    return outbox.add({
+        queue: MAINTENANCE_QUEUE_NAME,
+        name: STOP_TREE_JOB,
+        jobId: stopDeletedTreeJobId(conversationId),
+        data: { conversationId, byAccountId },
+        runAt: backstopAt(),
+        orgId,
+    });
+}
+/** Owes a finished child run's delivery to its parent in the caller's transaction. */
+export function oweDeliverToParent(outbox, childRunId, orgId) {
+    return outbox.add({
+        queue: MAINTENANCE_QUEUE_NAME,
+        name: DELIVER_TO_PARENT_JOB,
+        jobId: deliverToParentJobId(childRunId),
+        data: { childRunId },
+        runAt: backstopAt(),
+        orgId,
+    });
+}
+/**
+ * The `stop-tree` job (`MaintenanceProcessor`): every stop reads the active runs and stops only
+ * those, so a run the direct call already stopped is not stopped again.
+ */
+export async function processStopTree(waits, data) {
+    if ("runId" in data) {
+        await waits.stopChildren(data.runId, null);
+        await waits.stopDescendantsOfStopped(data.runId);
+        return;
+    }
+    await waits.stopTree(data.conversationId, data.byAccountId, { includeSelf: false });
+}
+/**
+ * The `deliver-to-parent` job (`MaintenanceProcessor`): `Waits.childFinished` writes the delivery
+ * once by the child run (idempotency keys under the parent conversation's row lock).
+ */
+export async function processDeliverToParent(waits, data) {
+    await waits.childFinished(data.childRunId);
+}