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

package/dist/channels/deliver-job.d.ts

@@ -4,15 +4,22 @@ import type { OutboxService } from "../infra/outbox/outbox.service.js";
  * with no BullMQ and no Nest class, so the event log can owe it without importing the channels
  * domain. `jobs.ts` (the producer) re-exports these names.
  */
-/** 渠道队列（出站投递与入站任务，不含 `:`），只在 worker 角色上消费。 */
+/** The channel queue (outbound deliveries and inbound jobs; no `:`), consumed only by workers. */
 export declare const CHANNEL_QUEUE_NAME = "cap-kernel-channels";
-/** 投递任务名。 */
+/** The delivery job's name. */
 export declare const DELIVER_JOB = "deliver";
-/** 投递任务 id（不含 `:`）：同一会话、同一日志位置只排一个任务。 */
+/** The delivery job id (no `:`): one job per conversation and log position. */
 export declare const deliverJobId: (conversationId: string, seq: number) => string;
 export interface DeliverJobData {
     conversationId: string;
 }
+/** The catch-up job of a connection that can deliver again (re-enabled, credentials rotated). */
+export declare const RESUME_JOB = "channel-resume";
+/** Its job id: one per connection and update (`updated_at` in ms; no `:`). */
+export declare const resumeJobId: (connectionId: string, at: Date) => string;
+export interface ResumeJobData {
+    connectionId: string;
+}
 /**
  * Owes the conversation's delivery job for the log position `seq` in the transaction in context:
  * the caller knows the conversation has a channel target. Shares the job id of

package/dist/channels/deliver-job.js

@@ -3,12 +3,16 @@
  * with no BullMQ and no Nest class, so the event log can owe it without importing the channels
  * domain. `jobs.ts` (the producer) re-exports these names.
  */
-/** 渠道队列（出站投递与入站任务，不含 `:`），只在 worker 角色上消费。 */
+/** The channel queue (outbound deliveries and inbound jobs; no `:`), consumed only by workers. */
 export const CHANNEL_QUEUE_NAME = "cap-kernel-channels";
-/** 投递任务名。 */
+/** The delivery job's name. */
 export const DELIVER_JOB = "deliver";
-/** 投递任务 id（不含 `:`）：同一会话、同一日志位置只排一个任务。 */
+/** The delivery job id (no `:`): one job per conversation and log position. */
 export const deliverJobId = (conversationId, seq) => `deliver-${conversationId}-${seq}`;
+/** The catch-up job of a connection that can deliver again (re-enabled, credentials rotated). */
+export const RESUME_JOB = "channel-resume";
+/** Its job id: one per connection and update (`updated_at` in ms; no `:`). */
+export const resumeJobId = (connectionId, at) => `channel-resume-${connectionId}-${at.getTime()}`;
 /**
  * Owes the conversation's delivery job for the log position `seq` in the transaction in context:
  * the caller knows the conversation has a channel target. Shares the job id of

package/dist/channels/inbound.js

@@ -11,6 +11,7 @@ import { randomUUID } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
 import { ConversationsService } from "../conversations/conversations.service.js";
 import { imSenderContext, recipientLocale, } from "../conversations/message-context.js";
+import { channelSource } from "../conversations/source.js";
 import { DevicesService } from "../devices/devices.service.js";
 import { DEFAULT_DEVICE_ALIASES, deviceLabel } from "../devices/label.js";
 import { ApiError } from "../errors.js";
@@ -227,8 +228,7 @@ let ChannelInbound = class ChannelInbound {
             try {
                 // bound to the person's IM default device, else their default (environments spec
                 // §4.2 item 8); an anonymous sender's stays unbound (no sandbox)
-                created = (await this.conversations.create(row.orgId, accountId, row.agentId, { im: true }))
-                    .id;
+                created = (await this.conversations.create(row.orgId, accountId, row.agentId, { im: true }, { source: channelSource(e.target.chatType) })).id;
             }
             catch (err) {
                 if (err instanceof ApiError && err.code === "agent.not_found") {

package/dist/channels/jobs.d.ts

@@ -5,8 +5,8 @@ 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 DeliverJobData } from "./deliver-job.js";
-export { CHANNEL_QUEUE_NAME, DELIVER_JOB, type DeliverJobData, deliverJobId, oweDelivery, } from "./deliver-job.js";
+import { type DeliverJobData, type ResumeJobData } from "./deliver-job.js";
+export { CHANNEL_QUEUE_NAME, DELIVER_JOB, type DeliverJobData, deliverJobId, oweDelivery, RESUME_JOB, type ResumeJobData, resumeJobId, } from "./deliver-job.js";
 /**
  * 结束后复核排的任务 id：每次唯一（带随机后缀，不含 `:`）。不能复用 `deliver-<会话>-<seq>`——同 id 的任务
  * 可能正因锁被占而即将直接结束，BullMQ 会把新任务去重进它，于是没人投递。
@@ -24,7 +24,7 @@ export interface InboundJobData {
     connectionId: string;
     event: InboundEvent;
 }
-export type ChannelJobData = DeliverJobData | InboundJobData;
+export type ChannelJobData = DeliverJobData | InboundJobData | ResumeJobData;
 /** 入站任务名。 */
 export declare const INBOUND_JOB = "inbound";
 /**
@@ -86,7 +86,14 @@ export declare class ChannelJobs implements OnApplicationShutdown {
      */
     enqueueInbound(connectionId: string, event: InboundEvent, jobId: string): Promise<void>;
     /**
-     * 连接重新可投递（轮换了凭据 / 重新启用）：给该连接投递进度落后于会话日志的会话各排一个出站任务，
+     * Owes the catch-up of a connection that can deliver again in the caller's transaction (the
+     * update that re-enabled it or rotated its credentials while active): the deliveries that ran
+     * while it could not deliver have ended, and nothing else finds the conversations lagging the log.
+     * `at` is the connection row's new `updated_at`.
+     */
+    oweResume(connectionId: string, orgId: string, at: Date): Promise<boolean>;
+    /**
+     * The {@link RESUME_JOB} job: 连接重新可投递（轮换了凭据 / 重新启用）：给该连接投递进度落后于会话日志的会话各排一个出站任务，
      * 补投停用或凭据失效期间落下的内容（不必等下一条消息）。
      */
     resumeConnection(connectionId: string): Promise<void>;

package/dist/channels/jobs.js

@@ -17,8 +17,8 @@ import { KernelEvents } from "../infra/events/kernel-events.js";
 import { OutboxService } from "../infra/outbox/outbox.service.js";
 import { OUTBOX_JOBS } from "../infra/outbox/registry.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
-import { CHANNEL_QUEUE_NAME, DELIVER_JOB, deliverJobId, oweDelivery, } from "./deliver-job.js";
-export { CHANNEL_QUEUE_NAME, DELIVER_JOB, deliverJobId, oweDelivery, } from "./deliver-job.js";
+import { CHANNEL_QUEUE_NAME, DELIVER_JOB, deliverJobId, oweDelivery, RESUME_JOB, resumeJobId, } from "./deliver-job.js";
+export { CHANNEL_QUEUE_NAME, DELIVER_JOB, deliverJobId, oweDelivery, RESUME_JOB, resumeJobId, } from "./deliver-job.js";
 /**
  * 结束后复核排的任务 id：每次唯一（带随机后缀，不含 `:`）。不能复用 `deliver-<会话>-<seq>`——同 id 的任务
  * 可能正因锁被占而即将直接结束，BullMQ 会把新任务去重进它，于是没人投递。
@@ -160,7 +160,22 @@ let ChannelJobs = class ChannelJobs {
         });
     }
     /**
-     * 连接重新可投递（轮换了凭据 / 重新启用）：给该连接投递进度落后于会话日志的会话各排一个出站任务，
+     * Owes the catch-up of a connection that can deliver again in the caller's transaction (the
+     * update that re-enabled it or rotated its credentials while active): the deliveries that ran
+     * while it could not deliver have ended, and nothing else finds the conversations lagging the log.
+     * `at` is the connection row's new `updated_at`.
+     */
+    oweResume(connectionId, orgId, at) {
+        return this.outbox.add({
+            queue: CHANNEL_QUEUE_NAME,
+            name: RESUME_JOB,
+            jobId: resumeJobId(connectionId, at),
+            data: { connectionId },
+            orgId,
+        });
+    }
+    /**
+     * The {@link RESUME_JOB} job: 连接重新可投递（轮换了凭据 / 重新启用）：给该连接投递进度落后于会话日志的会话各排一个出站任务，
      * 补投停用或凭据失效期间落下的内容（不必等下一条消息）。
      */
     async resumeConnection(connectionId) {

package/dist/channels/outbound.d.ts

@@ -97,7 +97,7 @@ export declare class ChannelOutbound {
     /** The conversation lock provider; delivery takes it under its own key prefix. */
     lock: Pick<ConversationLock, "scoped">, connections: Pick<ChannelConnections, "outbound">, approvals: Pick<ApprovalsService, "describe">, questions: Pick<QuestionsService, "forCall">, registry: Pick<ToolRegistry, "builtinSpecs" | "extensionToolSpecs">, 
     /** 入站任务的处理（worker 上执行 `ChannelInbound.handle`）；失败抛错由 BullMQ 重试。 */
-    inbound: Pick<ChannelInbound, "handle">, jobs: Pick<ChannelJobs, "enqueue">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "error" | "warn" | "info">, txHost: TransactionHost, 
+    inbound: Pick<ChannelInbound, "handle">, jobs: Pick<ChannelJobs, "enqueue" | "resumeConnection">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "error" | "warn" | "info">, txHost: TransactionHost, 
     /** Pauses the task of a scheduled run whose chat is gone (scheduled tasks spec §8). */
     schedules: Pick<ScheduledTasksService, "pauseFor">);
     /**
@@ -112,7 +112,10 @@ export declare class ChannelOutbound {
     /** Stops: the jobs in flight are handed back at their next checkpoint, the worker closes. */
     close(): Promise<void>;
     private requeue;
-    /** One job of the channel queue (the `@Processor` calls it): a delivery or an inbound event. */
+    /**
+     * One job of the channel queue (the `@Processor` calls it): a delivery, an inbound event or a
+     * connection's catch-up.
+     */
     process(job: Job<ChannelJobData>, token: string | undefined): Promise<void>;
     /** 本副本没有加载连接的插件：推迟重试（不消耗重试次数），排队超过上限才放弃。 */
     private pluginPending;

package/dist/channels/outbound.js

@@ -28,7 +28,7 @@ import { ToolRegistry } from "../tools/registry.js";
 import { approvalCard, cardMessage, connectUrl, conversationUrl, questionCard, webBase, } from "./cards.js";
 import { ChannelConnections } from "./connections.service.js";
 import { ChannelInbound } from "./inbound.js";
-import { ChannelJobs, INBOUND_JOB, idempotencyKey, } from "./jobs.js";
+import { ChannelJobs, INBOUND_JOB, idempotencyKey, RESUME_JOB, } from "./jobs.js";
 import { phrase } from "./phrases.js";
 import { insertThread } from "./threads.js";
 // The queue, job names, ids and priorities live with the producer (jobs.ts)
@@ -233,12 +233,19 @@ let ChannelOutbound = class ChannelOutbound {
         await job.moveToDelayed(Date.now() + delayMs, token);
         throw new DelayedError();
     }
-    /** One job of the channel queue (the `@Processor` calls it): a delivery or an inbound event. */
+    /**
+     * One job of the channel queue (the `@Processor` calls it): a delivery, an inbound event or a
+     * connection's catch-up.
+     */
     async process(job, token) {
         if (this.stopping.signal.aborted)
             return this.requeue(job, token, 0);
         if (job.name === INBOUND_JOB)
             return this.processInbound(job, token);
+        // a connection's catch-up: a failed add fails the job, which BullMQ retries
+        if (job.name === RESUME_JOB) {
+            return this.jobs.resumeConnection(job.data.connectionId);
+        }
         return this.deliver(job, token);
     }
     /** 本副本没有加载连接的插件：推迟重试（不消耗重试次数），排队超过上限才放弃。 */

package/dist/channels/threads.d.ts

@@ -21,9 +21,10 @@ export declare class AnonymousGuests {
     readonly txHost: TransactionHost;
     constructor(db: KernelDb, guestLock: AnonymousGuestLock, txHost: TransactionHost);
     /**
-     * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
-     * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
-     * 跨副本并发首次创建由 {@link AnonymousGuestLock} 串行化，只建一个账号。
+     * The org's one anonymous guest account id, created on first use (`accounts.status = active`, no
+     * way to sign in, org role guest). Every call makes sure the membership exists (a removed guest
+     * is added back on its next use). Concurrent first creations across replicas are serialized by
+     * {@link AnonymousGuestLock}: one account.
      */
     ensure(orgId: string): Promise<string>;
 }

package/dist/channels/threads.js

@@ -55,9 +55,10 @@ let AnonymousGuests = class AnonymousGuests {
         this.txHost = txHost;
     }
     /**
-     * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
-     * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
-     * 跨副本并发首次创建由 {@link AnonymousGuestLock} 串行化，只建一个账号。
+     * The org's one anonymous guest account id, created on first use (`accounts.status = active`, no
+     * way to sign in, org role guest). Every call makes sure the membership exists (a removed guest
+     * is added back on its next use). Concurrent first creations across replicas are serialized by
+     * {@link AnonymousGuestLock}: one account.
      */
     async ensure(orgId) {
         await this.guestLock.lock(orgId);

package/dist/conversations/conversations.controller.d.ts

@@ -312,8 +312,10 @@ export declare class ConversationsController {
     }>;
     /**
      * Stops the current run (the conversation's owner): 202 `{ runId }`; nothing active → 409
-     * `run.not_active`. On a root conversation `runId` is the stopped run, and its background
-     * sub-agents keep working. On a sub-agent's conversation (the root's owner, at any depth) the
+     * `run.not_active`. On a root conversation every active sub-agent of its tree stops with its
+     * run, and nothing they deliver starts the root again until its next run (agent map spec §6,
+     * changed in acceptance 2026-11-13); `runId` is the stopped run (the latest when only sub-agents
+     * ran). On a sub-agent's conversation (the root's owner, at any depth) the
      * sub-agent stops with every sub-agent below it, and `runId` is the sub-agent's latest run,
      * which may already be finished when only its descendants were working (agent map spec §6).
      */

package/dist/conversations/conversations.controller.js

@@ -190,7 +190,9 @@ let ConversationsController = class ConversationsController {
         const pick = body.deviceId === undefined ? {} : { deviceId: body.deviceId };
         if (body.message === undefined) {
             return {
-                conversation: await this.conversations.create(org.orgId, p.account.id, body.agentId, pick),
+                conversation: await this.conversations.create(org.orgId, p.account.id, body.agentId, pick, {
+                    source: "web",
+                }),
             };
         }
         const m = body.message;
@@ -204,7 +206,7 @@ let ConversationsController = class ConversationsController {
             ...(m.skill !== undefined && { skill: m.skill }),
             ...(m.timeZone !== undefined && { timeZone: m.timeZone }),
             ...(m.locale !== undefined && { locale: m.locale }),
-        }, pick);
+        }, pick, { source: "web" });
         reply.status(out.created ? 201 : 200);
         return { conversation: out.conversation, event: out.event, events: out.events };
     }
@@ -454,8 +456,10 @@ let ConversationsController = class ConversationsController {
     }
     /**
      * Stops the current run (the conversation's owner): 202 `{ runId }`; nothing active → 409
-     * `run.not_active`. On a root conversation `runId` is the stopped run, and its background
-     * sub-agents keep working. On a sub-agent's conversation (the root's owner, at any depth) the
+     * `run.not_active`. On a root conversation every active sub-agent of its tree stops with its
+     * run, and nothing they deliver starts the root again until its next run (agent map spec §6,
+     * changed in acceptance 2026-11-13); `runId` is the stopped run (the latest when only sub-agents
+     * ran). On a sub-agent's conversation (the root's owner, at any depth) the
      * sub-agent stops with every sub-agent below it, and `runId` is the sub-agent's latest run,
      * which may already be finished when only its descendants were working (agent map spec §6).
      */

package/dist/conversations/conversations.service.d.ts

@@ -1,3 +1,4 @@
+import type { ConversationSource } from "@capybara-hq/plugin-sdk";
 import { AgentLookup } from "../agents/agent-lookup.js";
 import type { ModelRef } from "../agents/definition.js";
 import type { AgentAvatar } from "../agents/profile.js";
@@ -146,6 +147,8 @@ export interface RunControl {
      * 否则返回 false。
      */
     abortIfOrphaned(conversationId: string, runId: string, byAccountId: string): Promise<boolean>;
+    /** Ends a run still `queued` in PG before a worker started it (`RunQueue.abortQueued`): true. */
+    abortQueued(conversationId: string, runId: string, byAccountId: string): Promise<boolean>;
     /**
      * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
      * 运行已不是 waiting（例如刚被续跑）→ false。
@@ -228,6 +231,14 @@ export interface InternalMessageOptions {
     schedule?: ScheduleMarker;
     timeZoneOverride?: string;
 }
+/** Options of a conversation created by a kernel caller (never an HTTP body). */
+export interface NewConversationOptions {
+    /**
+     * Where it comes from (memory plugin spec §6.2), fixed at creation. Required: a channel or group
+     * conversation that fell back to `web` would be offered what only the web and DMs may see.
+     */
+    source: ConversationSource;
+}
 /**
  * 会话：只有所有者可见；每次访问都实时复核 agent 对所有者仍可用（spec 3.6 R5），
  * 不可用时会话也按不存在处理（`conversation.not_found`）。
@@ -280,9 +291,10 @@ export declare class ConversationsService {
      * Creates an empty conversation bound to its device (`pick`, see
      * {@link ConversationDevices.forNew}); an agent the account cannot use →
      * `agent.not_found`, a device it may not use → `device.not_found` /
-     * `device.unavailable`, and nothing is created.
+     * `device.unavailable`, and nothing is created. `opts.source` records where the conversation
+     * comes from.
      */
-    create(orgId: string, accountId: string, agentId: string, pick?: NewConversationDevice): Promise<ConversationView>;
+    create(orgId: string, accountId: string, agentId: string, pick: NewConversationDevice | undefined, opts: NewConversationOptions): Promise<ConversationView>;
     /**
      * Creates a conversation together with its first message (UI refresh B, create on first send):
      * the conversation row and the `user_message` are written in one transaction, keyed by the
@@ -291,12 +303,12 @@ export declare class ConversationsService {
      * `agent.not_found` and nothing is written. Queues a run afterwards, like `postUserMessage`.
      * `events` are every event the create wrote, in seq order from seq 1 (a `model_switched` before
      * the message when the send switched), so a client can seed the new conversation's log whole.
-     * `internal` (kernel callers only): a scheduled task's marker, which also sets
-     * `conversations.scheduled_task_id`, and its zone override.
+     * `internal`: the conversation's source and, for kernel callers only, a scheduled task's marker,
+     * which also sets `conversations.scheduled_task_id`, and its zone override.
      */
     createWithMessage(orgId: string, accountId: string, agentId: string, input: UserMessageInput & {
         clientMessageId: string;
-    }, pick?: NewConversationDevice, internal?: InternalMessageOptions): Promise<{
+    }, pick: NewConversationDevice | undefined, internal: InternalMessageOptions & NewConversationOptions): Promise<{
         conversation: ConversationView;
         event: ConversationEvent;
         events: ConversationEvent[];
@@ -525,10 +537,43 @@ export declare class ConversationsService {
      * 等人处理的运行没有 worker：直接取消等待并写终态。其余经 Redis 广播，运行所在的任意副本都会收到；
      * 运行已是孤儿（没有任何 worker 在执行）时直接写终态。
      *
-     * A root conversation's stop stops only its own run: its background sub-agents keep working
-     * (agent map spec §6). A sub-agent's conversation (its owner, from the agent map) stops that
-     * sub-agent with every descendant (`RunControl.stopTree`); `run.not_active` when nothing in that
-     * subtree runs, else the sub-agent's latest run id.
+     * A root conversation's stop stops everything below it too (agent map spec §6, changed in
+     * acceptance 2026-11-13: after a person stops, the conversation stays stopped). In order:
+     * 1. `tree_stopped_at` is set on the root under its row lock: by the stopped run's terminal
+     *    transaction (a waiting, queued or orphaned run), before the stop is asked for (a run a
+     *    worker holds, which is active until then), or on its own (nothing of the root ran). From
+     *    then on no sub-agent delivery wakes the root (`wakeDecisionIn`) and no
+     *    sub-agent of the tree starts a run by a wake or a parent's message (`RunQueue.childWakeIn`),
+     *    until the root next starts a run (a person's message, the queue, a background Bash task's
+     *    finish), which clears it. A child that finishes just before or after the stop, `completed`
+     *    or `aborted`, thus never wakes the root; its delivery stays in the log and reaches the
+     *    model with the next run;
+     * 2. (with 1) the root's own active run stops as before ({@link abortRootRun});
+     * 3. every active sub-agent run of the tree stops (`RunControl.stopTree`, as the agent map's stop
+     *    and the deletion do), with the background tasks of every sub-agent. A sub-agent the root's
+     *    run dispatched after that read is stopped when the root run ends
+     *    (`Waits.stopDescendantsOfStopped`).
+     * The root's own background Bash tasks keep running: they are the conversation's tasks, stopped
+     * with `TaskStop` or the task list. `run.not_active` when neither the root nor its tree had an
+     * active run (the stop still holds the tree's wakes); else the root's run id (its latest when only
+     * sub-agents ran).
+     *
+     * A sub-agent's conversation (its owner, from the agent map) stops that sub-agent with every
+     * descendant (`RunControl.stopTree`); `run.not_active` when nothing in that subtree runs, else
+     * the sub-agent's latest run id. Its `aborted` finish never wakes its parent.
      */
     abort(orgId: string, conversationId: string, accountId: string): Promise<string>;
+    /**
+     * Marks a person's stop of the root's tree (`tree_stopped_at`, see {@link abort}); committed
+     * before any stop, so every wake decided after it (under the root's row lock) sees it.
+     */
+    private holdTree;
+    /**
+     * Stops a root conversation's own active run (queued / running / waiting) and returns its id;
+     * null when none is active. Its sub-agents are the caller's. The tree's hold
+     * (`tree_stopped_at`) is written by the stopped run's terminal transaction (`RunFinish.finishIn`
+     * for a run a person stopped), in the lock order every stop and decision takes (conversation,
+     * decided row, run); a run a worker holds is marked before its stop is asked for as well.
+     */
+    private abortRootRun;
 }

package/dist/conversations/conversations.service.js

@@ -177,9 +177,10 @@ let ConversationsService = class ConversationsService {
      * Creates an empty conversation bound to its device (`pick`, see
      * {@link ConversationDevices.forNew}); an agent the account cannot use →
      * `agent.not_found`, a device it may not use → `device.not_found` /
-     * `device.unavailable`, and nothing is created.
+     * `device.unavailable`, and nothing is created. `opts.source` records where the conversation
+     * comes from.
      */
-    async create(orgId, accountId, agentId, pick = {}) {
+    async create(orgId, accountId, agentId, pick = {}, opts) {
         await this.agents.get(orgId, agentId, accountId);
         const deviceId = await this.devices.forNew(orgId, accountId, pick);
         const row = await this.db
@@ -190,6 +191,7 @@ let ConversationsService = class ConversationsService {
             agent_id: agentId,
             account_id: accountId,
             device_id: deviceId,
+            source: opts.source,
         })
             .returning(COLUMNS)
             .executeTakeFirstOrThrow();
@@ -203,10 +205,10 @@ let ConversationsService = class ConversationsService {
      * `agent.not_found` and nothing is written. Queues a run afterwards, like `postUserMessage`.
      * `events` are every event the create wrote, in seq order from seq 1 (a `model_switched` before
      * the message when the send switched), so a client can seed the new conversation's log whole.
-     * `internal` (kernel callers only): a scheduled task's marker, which also sets
-     * `conversations.scheduled_task_id`, and its zone override.
+     * `internal`: the conversation's source and, for kernel callers only, a scheduled task's marker,
+     * which also sets `conversations.scheduled_task_id`, and its zone override.
      */
-    async createWithMessage(orgId, accountId, agentId, input, pick = {}, internal = {}) {
+    async createWithMessage(orgId, accountId, agentId, input, pick = {}, internal) {
         const agent = await this.agents.get(orgId, agentId, accountId);
         const prior = await this.findCreated(orgId, accountId, agentId, input.clientMessageId);
         if (prior)
@@ -242,6 +244,7 @@ let ConversationsService = class ConversationsService {
             device_id: conv.deviceId,
             create_request_id: input.clientMessageId,
             scheduled_task_id: internal.schedule?.taskId ?? null,
+            source: internal.source,
         })
             .onConflict((oc) => oc
             .columns(["org_id", "account_id", "create_request_id"])
@@ -339,13 +342,11 @@ let ConversationsService = class ConversationsService {
      * log, runs and trajectory stay (super admins still see them).
      */
     async remove(orgId, conversationId, accountId) {
-        await this.writable(orgId, conversationId, accountId);
-        try {
-            await this.abort(orgId, conversationId, accountId);
-        }
-        catch (e) {
-            if (!(e instanceof ApiError && e.code === "run.not_active"))
-                throw e;
+        const conv = await this.writable(orgId, conversationId, accountId);
+        // the root's own run only: the tree stops below, after the mark (a sub-agent's conversation
+        // is read-only, so `writable` refused it)
+        if (conv.parentConversationId === null) {
+            await this.abortRootRun(conversationId, accountId);
         }
         await this.markDeleted(orgId, conversationId, accountId);
         // after the mark, so no finish or delivery of the stops below can start a run on the deleted
@@ -978,25 +979,77 @@ let ConversationsService = class ConversationsService {
      * 等人处理的运行没有 worker：直接取消等待并写终态。其余经 Redis 广播，运行所在的任意副本都会收到；
      * 运行已是孤儿（没有任何 worker 在执行）时直接写终态。
      *
-     * A root conversation's stop stops only its own run: its background sub-agents keep working
-     * (agent map spec §6). A sub-agent's conversation (its owner, from the agent map) stops that
-     * sub-agent with every descendant (`RunControl.stopTree`); `run.not_active` when nothing in that
-     * subtree runs, else the sub-agent's latest run id.
+     * A root conversation's stop stops everything below it too (agent map spec §6, changed in
+     * acceptance 2026-11-13: after a person stops, the conversation stays stopped). In order:
+     * 1. `tree_stopped_at` is set on the root under its row lock: by the stopped run's terminal
+     *    transaction (a waiting, queued or orphaned run), before the stop is asked for (a run a
+     *    worker holds, which is active until then), or on its own (nothing of the root ran). From
+     *    then on no sub-agent delivery wakes the root (`wakeDecisionIn`) and no
+     *    sub-agent of the tree starts a run by a wake or a parent's message (`RunQueue.childWakeIn`),
+     *    until the root next starts a run (a person's message, the queue, a background Bash task's
+     *    finish), which clears it. A child that finishes just before or after the stop, `completed`
+     *    or `aborted`, thus never wakes the root; its delivery stays in the log and reaches the
+     *    model with the next run;
+     * 2. (with 1) the root's own active run stops as before ({@link abortRootRun});
+     * 3. every active sub-agent run of the tree stops (`RunControl.stopTree`, as the agent map's stop
+     *    and the deletion do), with the background tasks of every sub-agent. A sub-agent the root's
+     *    run dispatched after that read is stopped when the root run ends
+     *    (`Waits.stopDescendantsOfStopped`).
+     * The root's own background Bash tasks keep running: they are the conversation's tasks, stopped
+     * with `TaskStop` or the task list. `run.not_active` when neither the root nor its tree had an
+     * active run (the stop still holds the tree's wakes); else the root's run id (its latest when only
+     * sub-agents ran).
+     *
+     * A sub-agent's conversation (its owner, from the agent map) stops that sub-agent with every
+     * descendant (`RunControl.stopTree`); `run.not_active` when nothing in that subtree runs, else
+     * the sub-agent's latest run id. Its `aborted` finish never wakes its parent.
      */
     async abort(orgId, conversationId, accountId) {
         const conv = await this.get(orgId, conversationId, accountId);
+        const latest = () => this.db
+            .selectFrom("runs")
+            .select("id")
+            .where("conversation_id", "=", conversationId)
+            .orderBy("created_at", "desc")
+            .executeTakeFirst();
         if (conv.parentConversationId !== null) {
-            const latest = await this.db
-                .selectFrom("runs")
-                .select("id")
-                .where("conversation_id", "=", conversationId)
-                .orderBy("created_at", "desc")
-                .executeTakeFirst();
+            const last = await latest();
             const n = await this.runs.stopTree(conversationId, accountId);
-            if (n === 0 || !latest)
+            if (n === 0 || !last)
                 throw new ApiError("run.not_active", "No active run to abort");
-            return latest.id;
+            return last.id;
         }
+        const stopped = await this.abortRootRun(conversationId, accountId);
+        // nothing of the root's ran: the hold is the stop's own write
+        if (stopped === null)
+            await this.holdTree(conversationId);
+        const n = await this.runs.stopTree(conversationId, accountId, { includeSelf: false });
+        if (stopped !== null)
+            return stopped;
+        const last = await latest();
+        if (n === 0 || !last)
+            throw new ApiError("run.not_active", "No active run to abort");
+        return last.id;
+    }
+    /**
+     * Marks a person's stop of the root's tree (`tree_stopped_at`, see {@link abort}); committed
+     * before any stop, so every wake decided after it (under the root's row lock) sees it.
+     */
+    async holdTree(conversationId) {
+        await this.db
+            .updateTable("conversations")
+            .set({ tree_stopped_at: sql `now()` })
+            .where("id", "=", conversationId)
+            .execute();
+    }
+    /**
+     * Stops a root conversation's own active run (queued / running / waiting) and returns its id;
+     * null when none is active. Its sub-agents are the caller's. The tree's hold
+     * (`tree_stopped_at`) is written by the stopped run's terminal transaction (`RunFinish.finishIn`
+     * for a run a person stopped), in the lock order every stop and decision takes (conversation,
+     * decided row, run); a run a worker holds is marked before its stop is asked for as well.
+     */
+    async abortRootRun(conversationId, accountId) {
         const run = await this.db
             .selectFrom("runs")
             .select(["id", "status"])
@@ -1005,7 +1058,7 @@ let ConversationsService = class ConversationsService {
             .orderBy("created_at", "desc")
             .executeTakeFirst();
         if (!run)
-            throw new ApiError("run.not_active", "No active run to abort");
+            return null;
         const runs = this.runs;
         // 等待中：直接结束；没成功（刚被续跑、已回到 queued）则按下面的常规路径中止。
         // the stop's terminal transaction owed the ensure-run backstop; the direct call starts what
@@ -1014,11 +1067,24 @@ let ConversationsService = class ConversationsService {
             await runs.ensureRunAfterCommit(conversationId);
             return run.id;
         }
+        // a queued run no worker has started yet is ended in PG (ruling R27), never left to the stop
+        // marker's TTL: the marker first, so a worker that takes it meanwhile stops too
+        if (run.status === "queued") {
+            await runs.requestAbort(run.id, accountId);
+            if (await runs.abortQueued(conversationId, run.id, accountId)) {
+                await runs.ensureRunAfterCommit(conversationId);
+            }
+            return run.id;
+        }
         // 孤儿运行没有 worker 在听中止广播：直接写成 aborted，之后再看有没有等待中的消息要起新一轮。
         if (await runs.abortIfOrphaned(conversationId, run.id, accountId)) {
             await runs.ensureRunAfterCommit(conversationId);
             return run.id;
         }
+        // a run a worker holds ends later: the hold is written now, before the stop is asked for,
+        // while the run is still active (no wake can start the root before it), and again by its
+        // terminal transaction
+        await this.holdTree(conversationId);
         await runs.requestAbort(run.id, accountId);
         return run.id;
     }
@@ -1041,6 +1107,9 @@ __decorate([
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], ConversationsService.prototype, "bindIn", null);
+__decorate([
+    Transactional()
+], ConversationsService.prototype, "holdTree", null);
 ConversationsService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),

package/dist/conversations/events.d.ts

@@ -200,6 +200,20 @@ export declare const RunContextSchema: z.ZodObject<{
         person: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * The most UTF-8 bytes a `plugin_context` event's text may hold (memory spec §6.1): the providers'
+ * limit, so the log takes every text a provider may return.
+ */
+export declare const PLUGIN_CONTEXT_MAX_BYTES: number;
+/**
+ * `plugin_context` (memory spec §6.1): the text a `context@1` provider added at a run start. Empty
+ * text means the provider has nothing (any more); `hash` is the sha256 (hex) of `text`.
+ */
+export declare const PluginContextSchema: z.ZodObject<{
+    plugin: z.ZodString;
+    text: z.ZodString;
+    hash: z.ZodString;
+}, z.core.$strip>;
 /**
  * 会话事件（`type` + `payload`）的判别联合。事件日志只追加，写入前用它校验 payload；
  * 读出时按写入时的形状原样返回。
@@ -547,6 +561,13 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             person: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"plugin_context">;
+    payload: z.ZodObject<{
+        plugin: z.ZodString;
+        text: z.ZodString;
+        hash: z.ZodString;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"tools_changed">;
     payload: z.ZodObject<{
@@ -716,6 +737,12 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         byAccountId: z.ZodNullable<z.ZodString>;
         reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"approval_updated">;
+    payload: z.ZodObject<{
+        approvalId: z.ZodString;
+        callId: z.ZodString;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"question_asked">;
     payload: z.ZodObject<{