@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.4

package/dist/runtime/subagents/org-agents.js

@@ -1,6 +1,7 @@
 import { isAgentVisibleTo } from "../../agents/agent-lookup.js";
 import { normalizeStoredDefinition } from "../../agents/definition.js";
 import { audit } from "../../identity/audit.js";
+import { normalizeStoredDefinitionIn } from "../../tools/legacy-data.js";
 /**
  * Checks the gates for dispatching `agentId` from a parent whose current definition is
  * `parentDefinition` (read live by the caller: R5, removing an allowlist entry stops new
@@ -23,7 +24,7 @@ export async function checkOrgAgent(db, a) {
     if (!(a.parentDefinition.subagents?.agents ?? []).some((x) => x.agentId === a.agentId)) {
         return { ok: false, gate: "allowlist" };
     }
-    const definition = normalizeStoredDefinition(row.definition);
+    const definition = await normalizeStoredDefinitionIn(db, a.orgId, row.definition);
     if (definition.subagents?.dispatchable !== true)
         return { ok: false, gate: "dispatchable" };
     if (!(await isAgentVisibleTo(db, a.agentId, a.triggerAccountId))) {

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

@@ -45,7 +45,7 @@ export declare const isGeneralAlias: (agent: string) => boolean;
  * `general-purpose` for no `agent` and Claude's built-in types; else a roster type (a bare name
  * prefers the skill's own plugin's template `<plugin>:<name>`, then {@link findType}). An `agent`
  * that does not resolve falls back to `general-purpose` and is returned as `unknown`. `inRoster`:
- * the type is one the parent's `agent` tool offers (`general-purpose` is not when
+ * the type is one the parent's `Agent` tool offers (`general-purpose` is not when
  * `subagents.general === false`, which does not block a person's fork invocation).
  */
 export declare function resolveSkillForkType(db: KernelSchemaDb, orgId: string, parent: Pick<AgentDefinition, "subagents">, agent: string | undefined, plugin: string | undefined): Promise<{

package/dist/runtime/subagents/roster.js

@@ -90,7 +90,7 @@ export const isGeneralAlias = (agent) => GENERAL_ALIASES.has(agent);
  * `general-purpose` for no `agent` and Claude's built-in types; else a roster type (a bare name
  * prefers the skill's own plugin's template `<plugin>:<name>`, then {@link findType}). An `agent`
  * that does not resolve falls back to `general-purpose` and is returned as `unknown`. `inRoster`:
- * the type is one the parent's `agent` tool offers (`general-purpose` is not when
+ * the type is one the parent's `Agent` tool offers (`general-purpose` is not when
  * `subagents.general === false`, which does not block a person's fork invocation).
  */
 export async function resolveSkillForkType(db, orgId, parent, agent, plugin) {

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

@@ -8,7 +8,7 @@ import { type DispatchDeps } from "./dispatch.js";
 /**
  * Forked skills (phase D spec §6): a person's invocation of a `context: fork` skill starts its own
  * run (the run boundary, {@link forkBoundary}), whose `prepare` node dispatches the sub-agent
- * through phase C's `dispatchSubagent` before any model call and waits on it like an `agent` call
+ * through phase C's `dispatchSubagent` before any model call and waits on it like an `Agent` call
  * (`subagents` wait `sa-<runId>-0`). 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
@@ -110,7 +110,7 @@ export declare const recordedSkillForks: (eventLog: Pick<EventLog, "append" | "f
  * In the transaction of a run's terminal path (or the wait sweep): 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
+ * child still active (the caller stops it after its commit, as for `Agent` calls), or
  * {@link FORK_NOT_STARTED_TEXT} when nothing was dispatched. Returns the call ids written
  * (`skill-<seq>`) and the highest seq; the caller notifies after its commit.
  */

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

@@ -7,7 +7,7 @@ import { dispatchSubagent } from "./dispatch.js";
 /**
  * Forked skills (phase D spec §6): a person's invocation of a `context: fork` skill starts its own
  * run (the run boundary, {@link forkBoundary}), whose `prepare` node dispatches the sub-agent
- * through phase C's `dispatchSubagent` before any model call and waits on it like an `agent` call
+ * through phase C's `dispatchSubagent` before any model call and waits on it like an `Agent` call
  * (`subagents` wait `sa-<runId>-0`). 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
@@ -190,7 +190,7 @@ export const recordedSkillForks = (eventLog, recorded) => ({
  * In the transaction of a run's terminal path (or the wait sweep): 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
+ * child still active (the caller stops it after its commit, as for `Agent` calls), or
  * {@link FORK_NOT_STARTED_TEXT} when nothing was dispatched. Returns the call ids written
  * (`skill-<seq>`) and the highest seq; the caller notifies after its commit.
  */

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

@@ -12,7 +12,7 @@ import { type ChildWriter, type DispatchArgs, type DispatchCommit, type Dispatch
 import { type SubagentStep } from "./progress.js";
 import { type SkillForkDeps, type SkillForks } from "./skill-fork.js";
 /**
- * Sub-agents (phase C, spec §7) and forked skills (phase D): the `agent` tool's dispatch (the
+ * Sub-agents (phase C, spec §7) and forked skills (phase D): the `Agent` tool's dispatch (the
  * tool pipeline calls {@link dispatch}), a run's fork invocation ({@link skillForks}, the loop's
  * `prepare`) and a child step's progress on the parent's stream ({@link progress}). Child runs go
  * to the sub-agent run queue through {@link RunJobs}. The child lifecycle after dispatch (a
@@ -28,13 +28,13 @@ export declare class SubagentsService {
     /** The live fork handler of the loop (`LoopDeps.skillForks`). */
     readonly skillForks: SkillForks;
     constructor(kdb: KernelDb, eventLog: EventLog, purposes: ModelPurposesService, registry: ProviderRegistry, config: KernelConfigService, jobs: RunJobs, invoker: SkillInvoker, bus: ExtensionContext["bus"], log: KernelLogger, txHost: TransactionHost);
-    /** Dispatches the sub-agent of one `agent` call (`dispatchSubagent`). */
+    /** Dispatches the sub-agent of one `Agent` call (`dispatchSubagent`). */
     dispatch(a: DispatchArgs): Promise<DispatchOutcome>;
     /** The dispatch's writes in a transaction of their own (see `commitDispatchIn`). */
     commitDispatch(a: DispatchArgs, plan: DispatchPlan, child: ChildWriter): Promise<DispatchCommit | null>;
     /** A sub-agent's finished step on its parent's stream (sub-agents spec §14.2). Never throws. */
     progress(s: SubagentStep): Promise<void>;
 }
-/** Sub-agent dispatch (the tools domain's `agent` tool and the run loop use it). */
+/** Sub-agent dispatch (the tools domain's `Agent` tool and the run loop use it). */
 export declare class SubagentsModule {
 }

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

@@ -24,7 +24,7 @@ import { commitDispatchIn, dispatchSubagent, } from "./dispatch.js";
 import { publishSubagentProgress } from "./progress.js";
 import { liveSkillForks } from "./skill-fork.js";
 /**
- * Sub-agents (phase C, spec §7) and forked skills (phase D): the `agent` tool's dispatch (the
+ * Sub-agents (phase C, spec §7) and forked skills (phase D): the `Agent` tool's dispatch (the
  * tool pipeline calls {@link dispatch}), a run's fork invocation ({@link skillForks}, the loop's
  * `prepare`) and a child step's progress on the parent's stream ({@link progress}). Child runs go
  * to the sub-agent run queue through {@link RunJobs}. The child lifecycle after dispatch (a
@@ -58,7 +58,7 @@ let SubagentsService = class SubagentsService {
         };
         this.skillForks = liveSkillForks(this.deps);
     }
-    /** Dispatches the sub-agent of one `agent` call (`dispatchSubagent`). */
+    /** Dispatches the sub-agent of one `Agent` call (`dispatchSubagent`). */
     dispatch(a) {
         return dispatchSubagent(this.deps, a);
     }
@@ -88,7 +88,7 @@ SubagentsService = __decorate([
     __param(9, Inject(TransactionHost))
 ], SubagentsService);
 export { SubagentsService };
-/** Sub-agent dispatch (the tools domain's `agent` tool and the run loop use it). */
+/** Sub-agent dispatch (the tools domain's `Agent` tool and the run loop use it). */
 let SubagentsModule = class SubagentsModule {
 };
 SubagentsModule = __decorate([

package/dist/runtime/usage-report.d.ts

@@ -93,7 +93,8 @@ export declare function narrowPending(stored: readonly string[] | undefined, fai
  *   using up an attempt.
  * Handlers must be idempotent by `eventId` (`<conversationId>/<seq>`). Nothing is written to the event
  * log (never model-visible). Compaction calls log usage too (`purpose: "compaction"`) and are reported,
- * as are conversation title calls (`purpose: "title"`, no run: `runId` is "").
+ * as are conversation title calls (`purpose: "title"`, no run: `runId` is "") and `WebFetch`
+ * extraction calls (`purpose: "web_fetch"`).
  * Single-step eval replays and judge requests log no usage: not reported (M7).
  */
 export declare class UsageReporter {

package/dist/runtime/usage-report.js

@@ -160,7 +160,8 @@ export function narrowPending(stored, failed) {
  *   using up an attempt.
  * Handlers must be idempotent by `eventId` (`<conversationId>/<seq>`). Nothing is written to the event
  * log (never model-visible). Compaction calls log usage too (`purpose: "compaction"`) and are reported,
- * as are conversation title calls (`purpose: "title"`, no run: `runId` is "").
+ * as are conversation title calls (`purpose: "title"`, no run: `runId` is "") and `WebFetch`
+ * extraction calls (`purpose: "web_fetch"`).
  * Single-step eval replays and judge requests log no usage: not reported (M7).
  */
 let UsageReporter = class UsageReporter {

package/dist/runtime/waits.d.ts

@@ -1,6 +1,7 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import { type OnApplicationShutdown } from "@nestjs/common";
 import { type Job, type Queue } from "bullmq";
+import { BackgroundTaskStopper } from "../background/stop.js";
 import { EventLog } from "../conversations/event-log.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -42,7 +43,7 @@ export interface WaitSweepResult {
     /** 运行已终态、被本次扫描取消的审批 / 输入请求。 */
     cancelled: number;
     /**
-     * Finished parent runs whose open `agent` calls had no `tool_result`, repaired (final review
+     * Finished parent runs whose open `Agent` calls had no `tool_result`, repaired (final review
      * I3: the next run would send an unpaired tool call, which providers refuse).
      */
     repaired: number;
@@ -75,7 +76,7 @@ export declare class Waits implements OnApplicationShutdown {
     private readonly questions;
     private readonly runQueue;
     /**
-     * Writes, in the caller's transaction, the results of a stopped run's open `agent` calls;
+     * Writes, in the caller's transaction, the results of a stopped run's open `Agent` calls;
      * `fire` runs their observe hooks after the commit.
      */
     private readonly pipeline;
@@ -91,12 +92,14 @@ export declare class Waits implements OnApplicationShutdown {
     /** The maintenance queue: wait timeout jobs (`MaintenanceProcessor` consumes them). */
     private readonly timeouts;
     private readonly log;
+    /** Stops a finished sub-agent run's background tasks ({@link childFinished}). */
+    private readonly background;
     readonly txHost: TransactionHost;
     /** Drops the `run.orphaned` subscription (the events may outlive this instance). */
     private readonly unsubscribe;
     constructor(kdb: KernelDb, eventLog: EventLog, approvals: Pick<ApprovalsService, "expire" | "cancelPendingIn">, questions: Pick<QuestionsService, "expire" | "cancelPendingIn">, runQueue: Pick<RunQueue, "enqueue" | "repairOrphan" | "abortIfOrphaned">, 
     /**
-     * Writes, in the caller's transaction, the results of a stopped run's open `agent` calls;
+     * Writes, in the caller's transaction, the results of a stopped run's open `Agent` calls;
      * `fire` runs their observe hooks after the commit.
      */
     pipeline: Pick<ToolPipeline, "stopOpenAgentCalls">, finisher: Pick<RunFinish, "finishIn">, 
@@ -109,7 +112,9 @@ export declare class Waits implements OnApplicationShutdown {
      */
     abort: Pick<RunAbort, "requested" | "request">, 
     /** The maintenance queue: wait timeout jobs (`MaintenanceProcessor` consumes them). */
-    timeouts: Pick<Queue, "add">, events: KernelEvents, log: Pick<Logger, "error" | "warn">, txHost: TransactionHost);
+    timeouts: Pick<Queue, "add">, events: KernelEvents, log: Pick<Logger, "error" | "warn">, 
+    /** Stops a finished sub-agent run's background tasks ({@link childFinished}). */
+    background: Pick<BackgroundTaskStopper, "stopSubagentTasks">, txHost: TransactionHost);
     /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
     onApplicationShutdown(): void;
     /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
@@ -163,7 +168,7 @@ export declare class Waits implements OnApplicationShutdown {
      * 运行已不是 waiting（例如刚被续跑）→ 返回 false，由调用方走常规中止。
      */
     abortWaiting(conversationId: string, runId: string, byAccountId: string | null, detail?: RunAbortDetail): Promise<boolean>;
-    /** {@link abortWaiting}'s transaction; the open `agent` calls it wrote go back through `st`. */
+    /** {@link abortWaiting}'s transaction; the open `Agent` calls it wrote go back through `st`. */
     private abortWaitingIn;
     /** 扫描 3：运行已终态（如暂停途中失败）仍 pending 的审批 / 输入请求 → 取消（写决定 / 回答事件）。 */
     private sweepFinishedRuns;
@@ -193,7 +198,7 @@ export declare class Waits implements OnApplicationShutdown {
      */
     private sweepSubagentOrphans;
     /**
-     * Finished parent runs (past the grace period, within the last day) with an `agent` call that has
+     * Finished parent runs (past the grace period, within the last day) with an `Agent` call that has
      * no `tool_result` (final review I3): a terminal path that skipped `stopOpenAgentCalls`, such as
      * an old replica's abort, would otherwise leave an unpaired tool call that every later request of
      * the conversation sends and providers refuse. Each is repaired under the conversation row lock
@@ -247,7 +252,8 @@ export declare class Waits implements OnApplicationShutdown {
      * the conditional resume lets exactly one succeed, the last to see all its siblings terminal. A
      * run that is not a dispatched child, or not terminal yet, is left alone. A crash in between is
      * repaired by the wait sweep and by the parent's tools node, which writes a missing
-     * `subagent_finished` itself.
+     * `subagent_finished` itself. The running background tasks the terminal child run started are
+     * then stopped (not those of a later follow-up run of the same child).
      */
     childFinished(childRunId: string): Promise<void>;
     /**

package/dist/runtime/waits.js

@@ -11,6 +11,7 @@ import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable } from "@nestjs/common";
 import { DelayedError } from "bullmq";
 import { sql } from "kysely";
+import { BackgroundTaskStopper } from "../background/stop.js";
 import { EventLog } from "../conversations/event-log.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -70,12 +71,13 @@ let Waits = class Waits {
     abort;
     timeouts;
     log;
+    background;
     txHost;
     /** Drops the `run.orphaned` subscription (the events may outlive this instance). */
     unsubscribe;
     constructor(kdb, eventLog, approvals, questions, runQueue, 
     /**
-     * Writes, in the caller's transaction, the results of a stopped run's open `agent` calls;
+     * Writes, in the caller's transaction, the results of a stopped run's open `Agent` calls;
      * `fire` runs their observe hooks after the commit.
      */
     pipeline, finisher, 
@@ -88,7 +90,9 @@ let Waits = class Waits {
      */
     abort, 
     /** The maintenance queue: wait timeout jobs (`MaintenanceProcessor` consumes them). */
-    timeouts, events, log, txHost) {
+    timeouts, events, log, 
+    /** Stops a finished sub-agent run's background tasks ({@link childFinished}). */
+    background, txHost) {
         this.kdb = kdb;
         this.eventLog = eventLog;
         this.approvals = approvals;
@@ -100,6 +104,7 @@ let Waits = class Waits {
         this.abort = abort;
         this.timeouts = timeouts;
         this.log = log;
+        this.background = background;
         this.txHost = txHost;
         // an orphaned parent run (marked failed by `ensureRun`) stops its children at once; the
         // sweep's `sweepChildrenOfFinished` is the backstop
@@ -193,9 +198,17 @@ let Waits = class Waits {
             const row = waitingFor.kind === "approval"
                 ? await this.db
                     .selectFrom("approvals")
-                    .select(["tool_key", "expires_at"])
+                    .select(["tool_key", "expires_at", "requested_for", "approver_role"])
                     .where("id", "=", waitingFor.id)
                     .executeTakeFirst()
+                    .then((r) => r && {
+                    tool_key: r.tool_key,
+                    expires_at: r.expires_at,
+                    approver: {
+                        requestedFor: r.requested_for,
+                        approverRole: r.approver_role,
+                    },
+                })
                 : await this.db
                     .selectFrom("questions")
                     .select([sql `spec->>'toolKey'`.as("tool_key"), "expires_at"])
@@ -213,7 +226,10 @@ let Waits = class Waits {
                         childRunId: runId,
                         kind: waitingFor.kind,
                         ...(waitingFor.kind === "approval"
-                            ? { approvalId: waitingFor.id }
+                            ? {
+                                approvalId: waitingFor.id,
+                                ...row.approver,
+                            }
                             : { questionId: waitingFor.id }),
                         toolKey: row.tool_key,
                         expiresAt: new Date(row.expires_at).toISOString(),
@@ -337,7 +353,7 @@ let Waits = class Waits {
         await this.stopChildren(runId, null).catch((err) => this.log.error("cannot stop the sub-agents of a run", { runId, err }));
         return true;
     }
-    /** {@link abortWaiting}'s transaction; the open `agent` calls it wrote go back through `st`. */
+    /** {@link abortWaiting}'s transaction; the open `Agent` calls it wrote go back through `st`. */
     async abortWaitingIn(conversationId, runId, byAccountId, detail, st) {
         const t = this.db;
         await t
@@ -385,7 +401,7 @@ let Waits = class Waits {
             if (typeof spec.step === "number")
                 steps.add(spec.step);
         }
-        // a parent waiting on sub-agents (spec §12): its open `agent` calls get their results
+        // a parent waiting on sub-agents (spec §12): its open `Agent` calls get their results
         const agents = await this.pipeline.stopOpenAgentCalls(runId);
         for (const step of agents.steps)
             steps.add(step);
@@ -626,7 +642,7 @@ let Waits = class Waits {
         return out;
     }
     /**
-     * Finished parent runs (past the grace period, within the last day) with an `agent` call that has
+     * Finished parent runs (past the grace period, within the last day) with an `Agent` call that has
      * no `tool_result` (final review I3): a terminal path that skipped `stopOpenAgentCalls`, such as
      * an old replica's abort, would otherwise leave an unpaired tool call that every later request of
      * the conversation sends and providers refuse. Each is repaired under the conversation row lock
@@ -887,7 +903,7 @@ let Waits = class Waits {
      * 等待中的调用给取消说明，其余（排在等待调用之后、尚未执行的）给「未执行」说明。
      */
     async stoppedResults(t, conversationId, runId, steps, cancelled, 
-    /** Calls whose result the caller writes itself (open `agent` calls). */
+    /** Calls whose result the caller writes itself (open `Agent` calls). */
     skip = new Set()) {
         const out = [];
         for (const step of steps.sort((a, b) => a - b)) {
@@ -925,7 +941,8 @@ let Waits = class Waits {
      * the conditional resume lets exactly one succeed, the last to see all its siblings terminal. A
      * run that is not a dispatched child, or not terminal yet, is left alone. A crash in between is
      * repaired by the wait sweep and by the parent's tools node, which writes a missing
-     * `subagent_finished` itself.
+     * `subagent_finished` itself. The running background tasks the terminal child run started are
+     * then stopped (not those of a later follow-up run of the same child).
      */
     async childFinished(childRunId) {
         const row = await dispatchOfChildRun(this.db, childRunId);
@@ -938,13 +955,21 @@ let Waits = class Waits {
             .executeTakeFirst();
         if (!run || !TERMINAL_STATUSES.has(run.status))
             return;
-        const r = await childResult(this.eventLog, row);
-        if (!r) {
-            this.log.warn("sub-agent run is terminal without a terminal event", { childRunId });
-            return;
+        try {
+            const r = await childResult(this.eventLog, row);
+            if (!r) {
+                this.log.warn("sub-agent run is terminal without a terminal event", { childRunId });
+                return;
+            }
+            await this.eventLog.append(row.parentConversationId, [finishedEvent(row, r.finished)]);
+            await this.resume(row.parentRunId, childRunId);
+        }
+        finally {
+            // whichever way the child run ended (its worker, a stop while waiting, an orphan repair):
+            // nobody can read or stop the background tasks it started through its model any more
+            // (background Bash spec §4.3). Never throws.
+            await this.background.stopSubagentTasks(row.childConversationId, childRunId);
         }
-        await this.eventLog.append(row.parentConversationId, [finishedEvent(row, r.finished)]);
-        await this.resume(row.parentRunId, childRunId);
     }
     /**
      * Stops the active children of a parent run (sub-agents spec §12), or only those dispatched in
@@ -1020,7 +1045,8 @@ Waits = __decorate([
     __param(9, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
     __param(10, Inject(KernelEvents)),
     __param(11, Inject(KERNEL_LOGGER)),
-    __param(12, Inject(TransactionHost))
+    __param(12, Inject(BackgroundTaskStopper)),
+    __param(13, Inject(TransactionHost))
 ], Waits);
 export { Waits };
 /**

package/dist/sandbox/sandbox.module.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { BackgroundStoreModule } from "../background/store.module.js";
 import { ExtensionRegistryModule } from "../extensions/registry.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
 import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
@@ -22,7 +23,11 @@ let SandboxModule = class SandboxModule {
 };
 SandboxModule = __decorate([
     Module({
-        imports: [ExtensionRegistryModule, QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME)],
+        imports: [
+            ExtensionRegistryModule,
+            BackgroundStoreModule,
+            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
+        ],
         providers: [SandboxProviders, SandboxLeases, SandboxService, SandboxJobs],
         exports: [SandboxService, SandboxJobs],
     })

package/dist/sandbox/sandbox.service.d.ts

@@ -1,6 +1,7 @@
 import { type SandboxHandle, type SandboxProvider } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { type Selectable } from "kysely";
+import { BackgroundTaskStore } from "../background/store.js";
 import { type KernelConfig } from "../config/schema.js";
 import type { SandboxesTable } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
@@ -28,6 +29,28 @@ interface Instance {
     handle: SandboxHandle;
     createdAt: number;
 }
+/**
+ * The provider {@link SandboxService.ifRunning} passes to its callback: every `exec` carries the
+ * holder's tag, like the one `withSandbox` passes.
+ */
+export type TaggedProvider = SandboxProvider;
+/** What {@link SandboxService.ifRunning} did. */
+export type IfRunningResult<T> = {
+    kind: "ran";
+    value: T;
+}
+/**
+ * No sandbox, or the instance is not running: `status` is the sandbox row's (`suspended`,
+ * `creating`, `destroyed`, or `running` recorded with another provider), `gone` without a row.
+ */
+ | {
+    kind: "not_running";
+    status: SandboxesTable["status"] | "gone";
+}
+/** The sandbox now records another instance (a rebuild). */
+ | {
+    kind: "other_instance";
+};
 /**
  * The row still records the instance `gone` (same handle and same `created_at`). Handles compare
  * canonically: a jsonb round trip reorders a multi-key handle's keys (final review m9).
@@ -100,11 +123,15 @@ export declare class SandboxService {
     private readonly providers;
     private readonly config;
     private readonly log;
+    /** Background tasks lost while their process may live on (killed after a resume). */
+    private readonly background;
     constructor(db: KernelDb, 
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     redis: Pick<Redis, "set">, leases: SandboxLeases, 
     /** The `sandbox@1` provider (read at every call: providers are ready after the extension load). */
-    providers: Pick<SandboxProviders, "current" | "lookup">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "info" | "warn">);
+    providers: Pick<SandboxProviders, "current" | "lookup">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "info" | "warn">, 
+    /** Background tasks lost while their process may live on (killed after a resume). */
+    background: Pick<BackgroundTaskStore, "pendingKills" | "clearKill">);
     /** Poll interval while waiting for a lease (the leases' own). */
     private get pollMs();
     /** 是否有沙箱提供方。 */
@@ -119,6 +146,29 @@ export declare class SandboxService {
         status: "running" | "suspended";
         lastUsedAt: Date;
     } | null>;
+    /**
+     * The instance the conversation's sandbox records now (its `created_at`), while it has one that
+     * runs or is suspended; null otherwise. Read without a lease: a caller inside `withSandbox`
+     * reads the instance its own lease keeps.
+     */
+    currentInstance(conversationId: string): Promise<{
+        createdAt: Date;
+    } | null>;
+    /**
+     * Runs `fn` on the conversation's sandbox only while it runs the instance created at
+     * `instance.createdAt` (background tasks, spec 2026-11-05-background-bash-design §4.3). It never
+     * creates, resumes or rebuilds a sandbox: a sandbox that is missing, suspended, being created or
+     * destroyed (or recorded with another provider) is `not_running`, one that records another
+     * instance is `other_instance`. Otherwise `fn` runs under a shared lease, as a `withSandbox`
+     * holder does (its tag on every exec, crashed holders' commands killed), and `last_used_at`
+     * moves forward when it ends. Waits for the lease up to `sandbox.lockWaitSeconds`
+     * (`sandbox.busy`); `signal` (optional) ends the wait with its abort reason. The signal passed
+     * to `fn` aborts with `signal` or when the lease is lost. Errors of `fn` (`SandboxGoneError`
+     * too) are thrown as they are.
+     */
+    ifRunning<T>(conversationId: string, instance: {
+        createdAt: Date;
+    }, fn: (p: TaggedProvider, h: SandboxHandle, signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<IfRunningResult<T>>;
     /**
      * A short lease on one path of the conversation's sandbox around the kernel's own
      * read-modify-write of that file (spec §10.4); waits up to 30 s, then throws
@@ -164,8 +214,8 @@ export declare class SandboxService {
     /** Recorded running with the current provider, and not the instance found gone. */
     private usable;
     /**
-     * Under a just-taken shared lease: confirms the row is still usable (else releases and returns
-     * null), records the holder and kills crashed holders' commands.
+     * Under a just-taken shared lease: confirms the row is still `accept`ed (else releases and
+     * returns null), records the holder and kills crashed holders' commands.
      */
     private asShared;
     /**
@@ -206,6 +256,14 @@ export declare class SandboxService {
      * 结束）；其余失败只记 warn。提供方没有 `killAll` 时只记 info。
      */
     private killLeftovers;
+    /**
+     * Under the exclusive lease, right after a resume or a (re)build: kills the sessions of the
+     * background tasks marked lost while their process may live on (`kill_pending`), in one exec of
+     * `pkill -KILL -s <sid>`, then clears their flags. Tasks of another instance have no process
+     * here and are only cleared. A gone instance and an abort are thrown; another failure is warned
+     * and leaves the flags of this instance's tasks for the next resume.
+     */
+    private killPendingTasks;
     private require;
     /**
      * 防护写入：lease 仍在、且记录的 generation 仍是锁内读到的值时才写（并加一）；否则抛 {@link SandboxLockLostError}。