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

package/dist/schedules/schedule-math.js

@@ -104,6 +104,13 @@ export function validateTrigger(t, now) {
 export function nextTick(t, after) {
     return ticker(t)(after);
 }
+/**
+ * The scanner's ticker for one trigger ({@link nextTick} without rebuilding its `CronTime`s per
+ * call), for callers that walk the same trigger many times ({@link ticksIn}).
+ */
+export function tickerOf(t) {
+    return ticker(t);
+}
 /** How far back a DST transition can move a tick: longer than any gap (spec §5). */
 const TRANSITION_LOOKBACK_MS = 6 * 3600_000;
 /**
@@ -138,6 +145,51 @@ function ticker(t) {
         return null;
     };
 }
+/**
+ * The ticks in `(after, until]` (before jitter), at most `max`, from the same ticker
+ * {@link nextTick} and {@link dueTicks} use, so a list of planned runs equals what the scanner
+ * fires (calendar spec §5.2). `exhausted`: `max` ticks were taken before a tick past `until` was
+ * seen, so more may follow. A `once` trigger yields its one tick when it lies in the window.
+ * Costs one tick evaluation per tick returned, plus one when the walk reaches `until`. A caller
+ * that walks one trigger in many windows passes a {@link tickerOf} it built once.
+ */
+export function ticksIn(t, after, until, max) {
+    const ticks = [];
+    if (after.getTime() >= until.getTime())
+        return { ticks, exhausted: false };
+    const next = typeof t === "function" ? t : ticker(t);
+    let cursor = after;
+    while (ticks.length < max) {
+        const tick = next(cursor);
+        if (!tick || tick.getTime() > until.getTime())
+            return { ticks, exhausted: false };
+        ticks.push(tick);
+        cursor = tick;
+    }
+    return { ticks, exhausted: true };
+}
+/**
+ * One scan of a due task (`next_run_at <= now`) as of `now`, the schedule math alone: the ticks
+ * are before jitter, so the due tick is `nextRunAt - jitter` and a tick is due once
+ * `tick + jitter <= now`. The scanner applies the result; the calendar's parity test drives it.
+ * Throws when the trigger cannot be evaluated.
+ */
+export function scanStep(task, now, catchUpWindowMinutes) {
+    const jitterMs = task.jitterSeconds * 1000;
+    const dueTick = new Date(task.nextRunAt.getTime() - jitterMs);
+    const until = new Date(now.getTime() - jitterMs);
+    const ticks = dueTicks(task.trigger, new Date(dueTick.getTime() - 1), until, catchUpWindowMinutes);
+    const next = nextTick(task.trigger, until);
+    const expires = task.expiresAt?.getTime() ?? Number.POSITIVE_INFINITY;
+    const fire = ticks.fire !== null && ticks.fire.getTime() <= expires ? ticks.fire : null;
+    const first = ticks.firstMissed;
+    const missed = first !== null && first.getTime() <= expires ? first : null;
+    if (next === null)
+        return { missed, fire, nextRunAt: null, end: "done" };
+    if (next.getTime() > expires)
+        return { missed, fire, nextRunAt: null, end: "expired" };
+    return { missed, fire, nextRunAt: new Date(next.getTime() + jitterMs), end: null };
+}
 /** The wall clock of `at` in `timeZone`, read as if it were UTC (epoch ms, seconds dropped). */
 function localWallClock(at, timeZone) {
     return Math.floor(wallOf(at.getTime(), timeZone) / 60000) * 60000;

package/dist/schedules/scheduled-tasks.service.d.ts

@@ -13,6 +13,7 @@ import { OrgLock } from "../orgs/org-lock.js";
 import { ProviderRegistry } from "../runtime/providers.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { ToolRegistry } from "../tools/registry.js";
+import { type CalendarAnswer, type CalendarLimits } from "./calendar.js";
 import { type GrantContext, type GrantRefusalCode, grantRefusal, grantRefusalOf, networkGrantRefusal } from "./grant-rules.js";
 import { ScheduledTaskStore } from "./store.js";
 import type { ScheduleChat, ScheduledTask, ScheduledTaskGrant, ScheduleMode, SchedulePauseReason, TaskRun } from "./types.js";
@@ -231,6 +232,21 @@ export declare class ScheduledTasksService {
         all?: boolean;
         conversationId?: string;
     }): Promise<ScheduledTaskListItem[]>;
+    /**
+     * The calendar between two instants (calendar spec §5): the runs and planned occurrences of the
+     * actor's own tasks, or with `all` (org admins only, else `forbidden`) every task of the org; with
+     * `taskId` only that task (one the actor may see, else `schedule.not_found`), never collapsed.
+     * Another creator's runs come without `conversationId`, `error` and `missingGrants` (§15 Q3).
+     * A range longer than 43 days (2 with `taskId`), or not forward, is `validation_failed`. `now`
+     * is for tests.
+     */
+    calendar(orgId: string, actor: ScheduleActor, q: {
+        from: Date;
+        to: Date;
+        timeZone: string;
+        all?: boolean;
+        taskId?: string;
+    }, now?: Date, limits?: CalendarLimits): Promise<CalendarAnswer>;
     /**
      * The tasks of `tasks` that post into the conversation: a `conversation` task naming it, or a
      * `chat` task whose chat the conversation is a thread of (spec §10 side panel).

package/dist/schedules/scheduled-tasks.service.js

@@ -32,6 +32,7 @@ import { ProviderRegistry } from "../runtime/providers.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { isTimeZone } from "../time-zone.js";
 import { ToolRegistry } from "../tools/registry.js";
+import { assembleCalendar, CALENDAR_LIMITS, CALENDAR_RANGE_DAYS, CALENDAR_TASK_RANGE_DAYS, calendarRunReadLimit, } from "./calendar.js";
 import { readScheduleSettings } from "./effective-settings.js";
 import { grantNotAllowed, scheduleDisabled, scheduleForbidden, scheduleNotFound, targetInvalid, } from "./errors.js";
 import { grantRefusal, grantRefusalOf, isNetworkGrantKey, isPolicyGrantKey, isTierGrantKey, NETWORK_GRANT_PREFIX, NETWORK_GRANT_SPEC_HASH, networkGrantHost, networkGrantRefusal, TIER_GRANT_SPEC_HASH, tierGrantRefusal, } from "./grant-rules.js";
@@ -363,6 +364,58 @@ let ScheduledTasksService = class ScheduledTasksService {
         }
         return this.withLastRuns(tasks);
     }
+    /**
+     * The calendar between two instants (calendar spec §5): the runs and planned occurrences of the
+     * actor's own tasks, or with `all` (org admins only, else `forbidden`) every task of the org; with
+     * `taskId` only that task (one the actor may see, else `schedule.not_found`), never collapsed.
+     * Another creator's runs come without `conversationId`, `error` and `missingGrants` (§15 Q3).
+     * A range longer than 43 days (2 with `taskId`), or not forward, is `validation_failed`. `now`
+     * is for tests.
+     */
+    async calendar(orgId, actor, q, now = new Date(), limits = CALENDAR_LIMITS) {
+        const role = await this.liveRole(orgId, actor.accountId);
+        const manage = can(role, "schedules.manage");
+        if (q.all === true && !manage) {
+            throw new ApiError("forbidden", "Only org admins can read every scheduled task");
+        }
+        const span = q.to.getTime() - q.from.getTime();
+        const maxDays = q.taskId === undefined ? CALENDAR_RANGE_DAYS : CALENDAR_TASK_RANGE_DAYS;
+        if (!(span > 0))
+            throw new ApiError("validation_failed", "from must be before to");
+        if (span > maxDays * DAY_MS) {
+            throw new ApiError("validation_failed", `The range is at most ${maxDays} days${q.taskId === undefined ? "" : " with taskId"}`);
+        }
+        const t = this.db.db;
+        let tasks;
+        if (q.taskId !== undefined) {
+            const task = await this.store.getTask(t, orgId, q.taskId);
+            if (!task || (task.accountId !== actor.accountId && !manage))
+                throw scheduleNotFound();
+            tasks = [task];
+        }
+        else {
+            tasks =
+                q.all === true
+                    ? await this.store.listForOrg(t, orgId)
+                    : await this.store.listForAccount(t, orgId, actor.accountId);
+        }
+        const runs = await this.store.listRunsBetween(t, orgId, tasks.map((x) => x.id), q.from, q.to, 
+        // one row past the caps tells the assembly where to cut
+        calendarRunReadLimit(limits));
+        const settings = await readScheduleSettings(t, this.config, orgId);
+        return assembleCalendar({
+            tasks,
+            runs,
+            viewerAccountId: actor.accountId,
+            from: q.from,
+            to: q.to,
+            timeZone: q.timeZone,
+            now,
+            plan: settings.enabled,
+            catchUpWindowMinutes: settings.catchUpWindowMinutes,
+            collapse: q.taskId === undefined,
+        }, limits);
+    }
     /**
      * The tasks of `tasks` that post into the conversation: a `conversation` task naming it, or a
      * `chat` task whose chat the conversation is a thread of (spec §10 side panel).

package/dist/schedules/schedules.controller.d.ts

@@ -1,8 +1,9 @@
 import type { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
+import type { CalendarAnswer } from "./calendar.js";
 import { type ChatTarget, type GrantableTool, type ScheduledTaskGrantView, type ScheduledTaskListItem, ScheduledTasksService } from "./scheduled-tasks.service.js";
-import { type ScheduleChatTargetsQuery, type ScheduleCreateBody, type ScheduleGrantableQuery, type ScheduleGrantParams, type ScheduleGrantsBody, type ScheduleListQuery, type ScheduleParams, type ScheduleRunBody, type ScheduleRunsQuery, type ScheduleUpdateBody } from "./schedules.schemas.js";
+import { type ScheduleCalendarQuery, type ScheduleChatTargetsQuery, type ScheduleCreateBody, type ScheduleGrantableQuery, type ScheduleGrantParams, type ScheduleGrantsBody, type ScheduleListQuery, type ScheduleParams, type ScheduleRunBody, type ScheduleRunsQuery, type ScheduleUpdateBody } from "./schedules.schemas.js";
 import type { ScheduledTask, ScheduledTaskGrant, TaskRun } from "./types.js";
 /**
  * Scheduled tasks (`/api/v1/orgs/:orgId/schedules`, spec 2026-11-11-scheduled-tasks §10); human
@@ -10,6 +11,8 @@ import type { ScheduledTask, ScheduledTaskGrant, TaskRun } from "./types.js";
  * - `GET /` → `{ items }`: the caller's own tasks, each with its `lastRun`; `?all=true` every task
  *   of the org (org admins, `schedules.manage`, enforced by the service: 403 `forbidden`
  *   otherwise); `?conversationId=` only those posting into that conversation;
+ * - `GET /calendar?from&to&timeZone[&all][&taskId]` → the calendar (runs, planned occurrences,
+ *   collapsed task-days; calendar spec §5.1), `org.read` like the list, `all` as the list's;
  * - `GET /chat-targets` → `{ items }`: the chats the caller can point a `chat` task at;
  * - `GET /grantable-tools?agentId=` → `{ items }`: the agent's tools, each grantable or why not;
  * - `POST /` → 201 `{ task }` (`timeZone` is the browser zone, a fallback only);
@@ -30,6 +33,7 @@ export declare class SchedulesController {
     list(principal: Principal, org: OrgContext, q: z.infer<typeof ScheduleListQuery>): Promise<{
         items: ScheduledTaskListItem[];
     }>;
+    calendar(principal: Principal, org: OrgContext, q: z.infer<typeof ScheduleCalendarQuery>): Promise<CalendarAnswer>;
     chatTargets(principal: Principal, org: OrgContext, _q: z.infer<typeof ScheduleChatTargetsQuery>): Promise<{
         items: ChatTarget[];
     }>;

package/dist/schedules/schedules.controller.js

@@ -12,13 +12,15 @@ import { CurrentPrincipal, requireUser } from "../identity/principal.js";
 import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { ScheduledTasksService, } from "./scheduled-tasks.service.js";
-import { createInputOf, grantsOf, ScheduleChatTargetsQueryDto, ScheduleCreateBodyDto, ScheduleGrantableQueryDto, ScheduleGrantParamsDto, ScheduleGrantsBodyDto, ScheduleListQueryDto, ScheduleParamsDto, ScheduleRunBodyDto, ScheduleRunsQueryDto, ScheduleUpdateBodyDto, updateInputOf, } from "./schedules.schemas.js";
+import { calendarInputOf, createInputOf, grantsOf, ScheduleCalendarQueryDto, ScheduleChatTargetsQueryDto, ScheduleCreateBodyDto, ScheduleGrantableQueryDto, ScheduleGrantParamsDto, ScheduleGrantsBodyDto, ScheduleListQueryDto, ScheduleParamsDto, ScheduleRunBodyDto, ScheduleRunsQueryDto, ScheduleUpdateBodyDto, updateInputOf, } from "./schedules.schemas.js";
 /**
  * Scheduled tasks (`/api/v1/orgs/:orgId/schedules`, spec 2026-11-11-scheduled-tasks §10); human
  * users only (a service token gets 403).
  * - `GET /` → `{ items }`: the caller's own tasks, each with its `lastRun`; `?all=true` every task
  *   of the org (org admins, `schedules.manage`, enforced by the service: 403 `forbidden`
  *   otherwise); `?conversationId=` only those posting into that conversation;
+ * - `GET /calendar?from&to&timeZone[&all][&taskId]` → the calendar (runs, planned occurrences,
+ *   collapsed task-days; calendar spec §5.1), `org.read` like the list, `all` as the list's;
  * - `GET /chat-targets` → `{ items }`: the chats the caller can point a `chat` task at;
  * - `GET /grantable-tools?agentId=` → `{ items }`: the agent's tools, each grantable or why not;
  * - `POST /` → 201 `{ task }` (`timeZone` is the browser zone, a fallback only);
@@ -48,6 +50,11 @@ let SchedulesController = class SchedulesController {
         });
         return { items };
     }
+    // declared before `:id`; org.read like the list (a creator demoted to guest still reads their own)
+    async calendar(principal, org, q) {
+        const p = requireUser(principal);
+        return this.tasks.calendar(org.orgId, { accountId: p.account.id }, calendarInputOf(q));
+    }
     async chatTargets(principal, org, _q) {
         const p = requireUser(principal);
         return { items: await this.tasks.chatTargets(org.orgId, p.account.id) };
@@ -134,6 +141,13 @@ __decorate([
     __param(1, CurrentOrg()),
     __param(2, ZQuery(ScheduleListQueryDto))
 ], SchedulesController.prototype, "list", null);
+__decorate([
+    Get("calendar"),
+    OrgAction("org.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZQuery(ScheduleCalendarQueryDto))
+], SchedulesController.prototype, "calendar", null);
 __decorate([
     Get("chat-targets"),
     OrgAction("schedules.use"),

package/dist/schedules/schedules.schemas.d.ts

@@ -138,6 +138,21 @@ export declare const ScheduleListQuery: z.ZodObject<{
     }>>;
     conversationId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/**
+ * The calendar's range (`from < to`, at most 43 days, 2 with `taskId`: checked by the service),
+ * the viewer's zone (local days for the collapse and the cut), `all` (org admins) and `taskId`
+ * (one task, never collapsed).
+ */
+export declare const ScheduleCalendarQuery: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    timeZone: z.ZodString;
+    all: z.ZodOptional<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>>;
+    taskId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 export declare const ScheduleChatTargetsQuery: z.ZodObject<{}, z.core.$strict>;
 export declare const ScheduleGrantableQuery: z.ZodObject<{
     agentId: z.ZodString;
@@ -258,6 +273,18 @@ declare const ScheduleListQueryDto_base: import("../infra/validation/create-zod-
 }, z.core.$strict>>;
 export declare class ScheduleListQueryDto extends ScheduleListQueryDto_base {
 }
+declare const ScheduleCalendarQueryDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    timeZone: z.ZodString;
+    all: z.ZodOptional<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>>;
+    taskId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare class ScheduleCalendarQueryDto extends ScheduleCalendarQueryDto_base {
+}
 declare const ScheduleChatTargetsQueryDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{}, z.core.$strict>>;
 export declare class ScheduleChatTargetsQueryDto extends ScheduleChatTargetsQueryDto_base {
 }
@@ -313,4 +340,12 @@ export declare function createInputOf(body: z.infer<typeof ScheduleCreateBody>):
 };
 /** A patch body as the service's input (an explicit `timeZone` changes the task's zone). */
 export declare function updateInputOf(body: z.infer<typeof ScheduleUpdateBody>): UpdateTaskInput;
+/** A calendar query as the service's input. */
+export declare const calendarInputOf: (q: z.infer<typeof ScheduleCalendarQuery>) => {
+    from: Date;
+    to: Date;
+    timeZone: string;
+    all: boolean;
+    taskId?: string;
+};
 export {};

package/dist/schedules/schedules.schemas.js

@@ -86,6 +86,22 @@ export const ScheduleListQuery = z
     conversationId: Id.optional(),
 })
     .strict();
+/** An instant with an offset (`2026-11-09T00:00:00+08:00`). */
+const Instant = z.string().datetime({ offset: true });
+/**
+ * The calendar's range (`from < to`, at most 43 days, 2 with `taskId`: checked by the service),
+ * the viewer's zone (local days for the collapse and the cut), `all` (org admins) and `taskId`
+ * (one task, never collapsed).
+ */
+export const ScheduleCalendarQuery = z
+    .object({
+    from: Instant,
+    to: Instant,
+    timeZone: IanaTimeZone,
+    all: z.enum(["true", "false"]).optional(),
+    taskId: Id.optional(),
+})
+    .strict();
 export const ScheduleChatTargetsQuery = z.object({}).strict();
 export const ScheduleGrantableQuery = z.object({ agentId: Id }).strict();
 export const ScheduleParams = z.object({ id: Id });
@@ -103,6 +119,8 @@ export class ScheduleUpdateBodyDto extends createZodDto(ScheduleUpdateBody, "Sch
 }
 export class ScheduleListQueryDto extends createZodDto(ScheduleListQuery, "ScheduleListQuery") {
 }
+export class ScheduleCalendarQueryDto extends createZodDto(ScheduleCalendarQuery, "ScheduleCalendarQuery") {
+}
 export class ScheduleChatTargetsQueryDto extends createZodDto(ScheduleChatTargetsQuery, "ScheduleChatTargetsQuery") {
 }
 export class ScheduleGrantableQueryDto extends createZodDto(ScheduleGrantableQuery, "ScheduleGrantableQuery") {
@@ -120,6 +138,7 @@ export class ScheduleGrantParamsDto extends createZodDto(ScheduleGrantParams, "S
 /** The schedule routes the Platform operations mirror (`check:platform-ops` keys). */
 export const SCHEDULE_ROUTES = [
     { route: "GET /api/v1/orgs/:orgId/schedules", query: ScheduleListQuery },
+    { route: "GET /api/v1/orgs/:orgId/schedules/calendar", query: ScheduleCalendarQuery },
     { route: "GET /api/v1/orgs/:orgId/schedules/chat-targets", query: ScheduleChatTargetsQuery },
     { route: "GET /api/v1/orgs/:orgId/schedules/grantable-tools", query: ScheduleGrantableQuery },
     { route: "POST /api/v1/orgs/:orgId/schedules", body: ScheduleCreateBody },
@@ -184,3 +203,11 @@ export function updateInputOf(body) {
         ...(expiresAt !== undefined && { expiresAt: expiresAt === null ? null : new Date(expiresAt) }),
     };
 }
+/** A calendar query as the service's input. */
+export const calendarInputOf = (q) => ({
+    from: new Date(q.from),
+    to: new Date(q.to),
+    timeZone: q.timeZone,
+    all: q.all === "true",
+    ...(q.taskId !== undefined && { taskId: q.taskId }),
+});

package/dist/schedules/store.d.ts

@@ -68,6 +68,11 @@ export declare class ScheduledTaskStore {
     countFiredSince(t: KernelSchemaDb, orgId: string, since: Date): Promise<number>;
     /** A task's runs, latest tick first. */
     listRuns(t: KernelSchemaDb, taskId: string, limit: number): Promise<TaskRun[]>;
+    /**
+     * The runs of these tasks of the org with `scheduled_for` in `[from, to)`, trial included, by tick, at most
+     * `limit` (the calendar; `scheduled_task_runs_task_idx` per task).
+     */
+    listRunsBetween(t: KernelSchemaDb, orgId: string, taskIds: readonly string[], from: Date, to: Date, limit: number): Promise<TaskRun[]>;
     listGrants(t: KernelSchemaDb, taskId: string): Promise<ScheduledTaskGrant[]>;
     /** Adds a grant, replacing the task's grant of the same tool key. */
     addGrant(t: KernelSchemaDb, taskId: string, grant: ScheduledTaskGrant): Promise<void>;

package/dist/schedules/store.js

@@ -329,6 +329,26 @@ let ScheduledTaskStore = class ScheduledTaskStore {
             .execute();
         return rows.map(toRun);
     }
+    /**
+     * The runs of these tasks of the org with `scheduled_for` in `[from, to)`, trial included, by tick, at most
+     * `limit` (the calendar; `scheduled_task_runs_task_idx` per task).
+     */
+    async listRunsBetween(t, orgId, taskIds, from, to, limit) {
+        if (taskIds.length === 0)
+            return [];
+        const rows = await t
+            .selectFrom("scheduled_task_runs")
+            .selectAll()
+            .where("org_id", "=", orgId)
+            .where("task_id", "in", [...taskIds])
+            .where("scheduled_for", ">=", from)
+            .where("scheduled_for", "<", to)
+            .orderBy("scheduled_for")
+            .orderBy("id")
+            .limit(limit)
+            .execute();
+        return rows.map(toRun);
+    }
     async listGrants(t, taskId) {
         const rows = await t
             .selectFrom("scheduled_task_grants")

package/dist/tools/approvals.service.d.ts

@@ -8,6 +8,7 @@ import { KernelEvents } from "../infra/events/kernel-events.js";
 import { LockService } from "../infra/lock/lock.service.js";
 import { DevicePolicyService } from "../local-devices/device-policy.service.js";
 import { type OrgRole } from "../orgs/roles.js";
+import { RunResume } from "../runtime/run-jobs.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { ScheduledTaskStore } from "../schedules/store.js";
 import type { ApprovalPolicySource } from "./pipeline.js";
@@ -206,10 +207,12 @@ export interface ToolGrantView {
  * 工具调用审批：新建（loop 调用）、列出 / 查看 / 处理（HTTP），以及「以后都允许」授权的查看与撤销。
  * 状态全部在 PG：处理决定在事务里 `SELECT … FOR UPDATE` 审批行，多副本并发处理同一审批时恰好一个生效。
  *
- * A decision is announced after the commit as the domain event `approval.decided` (exactly once:
- * only the decision that changed the row from pending), which the run's waits follow to resume it
- * (spec §3b; the wait sweep resumes a run whose resume was lost). Events are appended in the
- * context's transaction (`EventLog.appendIn`) and published after the commit.
+ * A decision resumes its waiting run in the decision's transaction (`RunResume.resumeIn`, after the
+ * decided row: lock order approval, then run; transactional outbox spec §6). It is announced after
+ * the commit as the domain event `approval.decided` (exactly once: only the decision that changed
+ * the row from pending; no kernel subscriber: the IM card update is owed by the `approval_decided`
+ * append, transactional outbox spec §8.1). Events are appended in the context's transaction
+ * (`EventLog.appendIn`) and published after the commit.
  */
 export declare class ApprovalsService {
     private readonly db;
@@ -226,6 +229,8 @@ export declare class ApprovalsService {
     readonly lockService: LockService;
     /** A trial run's 「这次允许」 becomes a task grant only within the org's egress. */
     private readonly sandbox;
+    /** A decision resumes its waiting run in the decision's transaction. */
+    private readonly resumes;
     constructor(db: KernelDb, config: Pick<KernelConfigService, "get">, eventLog: Pick<EventLog, "appendIn" | "notify">, events: Pick<KernelEvents, "emit">, txHost: TransactionHost, schedules: Pick<ScheduledTaskStore, "addGrant">, 
     /** A trial approval is kept only for a tool the task may hold as a grant (its agent's tools). */
     registry: Pick<ToolRegistry, "forAgent">, 
@@ -234,7 +239,9 @@ export declare class ApprovalsService {
     /** One decision of a network ask at a time, across replicas (the op is sent before the transaction). */
     lockService: LockService, 
     /** A trial run's 「这次允许」 becomes a task grant only within the org's egress. */
-    sandbox: Pick<SandboxService, "ceilingLimits">);
+    sandbox: Pick<SandboxService, "ceilingLimits">, 
+    /** A decision resumes its waiting run in the decision's transaction. */
+    resumes: Pick<RunResume, "resumeIn">);
     /**
      * 新建 pending 审批（`expires_at` = 现在 + `tools.approvalTimeoutHours`）并写 `approval_requested`，同一事务。
      * 按 (run_id, call_id, attempt) 幂等：已存在则返回已有记录（不覆盖），事件按 `approval_requested:<approvalId>` 幂等。
@@ -346,13 +353,25 @@ export declare class ApprovalsService {
      * active runs `authorAccountId` started, in the conversation and in its sub-agents'
      * conversations at any depth (their asks are shown in the root). Each becomes `skipped` with
      * `approval_decided{skipped}` by the author; access stays blocked. Returns the skipped records and
-     * the highest seq written per conversation; the caller notifies and emits
-     * `approval.decided{skipped}` after the commit, so the runs resume.
+     * the highest seq written per conversation; the caller resumes their waiting runs in this
+     * transaction once every skipped row is locked (`ConversationsService.skipWaitsIn`), and notifies
+     * and emits the domain event `approval.decided{skipped}` after the commit (its IM card update is
+     * owed by the append, transactional outbox spec §8.1).
      */
     skipNetworkIn(conversationId: string, authorAccountId: string): Promise<{
         records: ApprovalRecord[];
         seqs: Map<string, number>;
     }>;
+    /**
+     * Locks the conversation row of approval `id` (`SELECT … FOR UPDATE`; re-entrant with the lock
+     * `EventLog.appendIn` takes later). Every write to an approval row takes its conversation's lock
+     * first, then the approval row, then the run row, as the stop of a waiting run
+     * (`Waits.abortWaitingIn`) and the questions do, so no two of them can deadlock. False: no such
+     * approval (in `orgId`).
+     */
+    private lockConversationOf;
+    /** Locks, in id order, the conversations `ids` selects; returns their ids. */
+    private lockConversations;
     /** `conversationId` and its sub-agents' conversations at any depth (at most 16 levels). */
     private subtreeOf;
     /**