@capybara-hq/kernel 0.1.0-rc.19 → 0.1.0-rc.20

package/dist/agents/agents.service.d.ts

@@ -1,5 +1,6 @@
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { EvalBudget } from "../evals/budget.js";
+import type { WriteActor } from "../identity/write-actor.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { OrgLock } from "../orgs/org-lock.js";
@@ -76,7 +77,10 @@ export declare class AgentsService {
     private readonly db;
     private readonly lookup;
     private readonly tools;
-    /** 删除 agent 时取消它待处理的技能改动（T15）。 */
+    /**
+     * Cancels the agent's pending skill requests: all of them when it is deleted, share requests
+     * when its owner changes.
+     */
     private readonly skillChanges;
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     private readonly orgLock;
@@ -88,10 +92,13 @@ export declare class AgentsService {
     /** Settles the agent's connector setup request when its pending connectors change (P4-7). */
     private readonly setupRequests;
     constructor(db: KernelDb, lookup: AgentLookup, tools: Pick<ToolRegistry, "checkDisabled">, 
-    /** 删除 agent 时取消它待处理的技能改动（T15）。 */
+    /**
+     * Cancels the agent's pending skill requests: all of them when it is deleted, share requests
+     * when its owner changes.
+     */
     skillChanges: Pick<SkillChangesService, "cancelPendingForAgent" | "finishCancel">, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
-    orgLock: Pick<OrgLock, "lockAndAuthorize">, 
+    orgLock: Pick<OrgLock, "lockAndAuthorize" | "tryLock">, 
     /** Resolves the agent's models (and their parameter declarations) when it is saved. */
     providers: Pick<ProviderRegistry, "resolve">, txHost: TransactionHost, 
     /** Cancels the deleted agent's running eval runs (in the delete's transaction). */
@@ -162,6 +169,17 @@ export declare class AgentsService {
         visibility: AgentVisibility;
         current_version: number;
     }>;
+    /**
+     * Locks the live agent row of `orgId` (the caller holds the org row lock); missing or deleted →
+     * `agent.not_found`.
+     */
+    private lockAgentRow;
+    /**
+     * The platform path's lock (a super admin who need not be a member of the org): finds the live
+     * agent's org, locks the org row, then the agent row. A missing or deleted agent, or one of a
+     * deleted org → `agent.not_found`. The super admin check is the caller's (`@SuperAdmin()`).
+     */
+    private lockForPlatform;
     /**
      * 修改 agent：`definition` 变化时写新版本（`current_version + 1`），只改 visibility / memberIds 不产生新版本。
      * 只有负责人或组织管理员以上可改，在组织行锁内复核。
@@ -183,12 +201,32 @@ export declare class AgentsService {
     /** 软删除：权限同 update。待处理的技能改动与该 agent 评测集在执行的评测运行一并取消，提交后删除草稿（T15）。 */
     softDelete(orgId: string, agentId: string, actorAccountId: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<void>;
     private softDeleteIn;
+    /**
+     * The platform's delete (a super admin who need not be a member of the agent's org): the same
+     * effects as {@link softDelete}, under the org row lock, audited `agent.deleted` with
+     * `detail.via = "platform"`. A missing or deleted agent, or one of a deleted org →
+     * `agent.not_found`. `auditDetail` (a Platform tool write's `viaAgent`) is merged into the
+     * detail; `via` stays `"platform"`.
+     */
+    softDeleteAsPlatform(agentId: string, actor: WriteActor, auditDetail?: Record<string, unknown>): Promise<void>;
+    private softDeleteAsPlatformIn;
+    /** The delete itself; the caller holds the org row and agent row locks. */
+    private softDeleteLocked;
     /**
      * 重新指派负责人（`agents.manage`，admin）：在组织行锁内授权；agent 不存在 / 已删除 → `agent.not_found`；
      * 新负责人不是该组织成员 → `member.not_found`；是匿名访客 → `member.anonymous_guest`。
      * 清除 `needs_reassignment`，审计 `agent.owner_changed`。
      */
     reassignOwner(orgId: string, agentId: string, newOwnerId: string, actorAccountId: string, actorTokenId?: string): Promise<AgentView>;
+    /**
+     * The platform's owner transfer (a super admin who need not be a member of the agent's org):
+     * the same checks and effects as {@link reassignOwner} (the new owner is a member of the agent's
+     * org and not its anonymous guest), audited with `detail.via = "platform"`. A missing or deleted
+     * agent, or one of a deleted org → `agent.not_found`.
+     */
+    reassignOwnerAsPlatform(agentId: string, newOwnerId: string, actor: WriteActor): Promise<AgentView>;
+    /** The owner transfer itself; the caller holds the org row and agent row locks. */
+    private reassignOwnerLocked;
     /**
      * `views` with `createdFrom.available` set (ruling P4-8): whether each recorded template is
      * still usable in the org. One template read for all of them; only the agents API calls it.

package/dist/agents/agents.service.js

@@ -26,7 +26,7 @@ import { assertOrgSkills, assertPinnedSkills } from "../skills/skills.service.js
 import { legacyKeySaveText } from "../tools/legacy-keys.js";
 import { ToolRegistry } from "../tools/registry.js";
 import { AgentLookup, isAgentVisibleTo, visibleTo, } from "./agent-lookup.js";
-import { canonicalDisabledTools, normalizeStoredDefinition, paramIssues, SUBAGENT_NAME_RE, SUBAGENT_ROSTER_MAX, } from "./definition.js";
+import { canonicalDisabledTools, normalizeStoredDefinition, paramIssues, SUBAGENT_NAME_RE, SUBAGENT_ROSTER_MAX, withoutRemovedBuiltinPolicies, } from "./definition.js";
 import { deriveInstructions } from "./instruction-files.js";
 import { PendingConnectorRequests } from "./pending-connector-requests.js";
 import { randomPreset } from "./profile.js";
@@ -275,7 +275,10 @@ let AgentsService = class AgentsService {
     evalBudget;
     setupRequests;
     constructor(db, lookup, tools, 
-    /** 删除 agent 时取消它待处理的技能改动（T15）。 */
+    /**
+     * Cancels the agent's pending skill requests: all of them when it is deleted, share requests
+     * when its owner changes.
+     */
     skillChanges, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     orgLock, 
@@ -417,11 +420,13 @@ let AgentsService = class AgentsService {
         return this.createChecked(orgId, actorAccountId, request, template, actorTokenId, auditDetail);
     }
     async createChecked(orgId, actorAccountId, request, template, actorTokenId, auditDetail) {
+        // a policy key of a removed builtin (e.g. copied from a template) is dropped, never refused
+        const given = withoutRemovedBuiltinPolicies(request.definition);
         const input = {
             ...request,
             // run context spec §3.5: version 1 carries the description (the profile's when the
             // definition gives none)
-            definition: withCanonicalTools(withDescription(deriveInstructions(request.definition, null), request.definition.description ?? request.profile?.description, undefined)),
+            definition: withCanonicalTools(withDescription(deriveInstructions(given, null), given.description ?? request.profile?.description, undefined)),
         };
         // 先解析模型（可能访问供应商），不在持有组织行锁时做
         const warnings = await this.checkModels(orgId, input.definition);
@@ -503,11 +508,29 @@ let AgentsService = class AgentsService {
     async lockForWrite(orgId, agentId, actorAccountId) {
         const t = this.db.db;
         const { role } = await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "agents.create");
+        const agent = await this.lockAgentRow(orgId, agentId);
+        if (agent.owner_account_id === actorAccountId || roleAtLeast(role, "admin"))
+            return agent;
+        const visible = await t
+            .selectFrom("agents")
+            .select("id")
+            .where("id", "=", agentId)
+            .where(visibleTo(actorAccountId))
+            .executeTakeFirst();
+        if (!visible)
+            throw notFound();
+        throw new ApiError("forbidden", "Only the agent owner or an organization admin can modify it");
+    }
+    /**
+     * Locks the live agent row of `orgId` (the caller holds the org row lock); missing or deleted →
+     * `agent.not_found`.
+     */
+    async lockAgentRow(orgId, agentId) {
         // NO KEY UPDATE: a soft delete then appends revert snapshots to conversations; FOR UPDATE would
         // block the agent foreign key check of an append already holding one of them (40P01)
-        const agent = await t
+        const agent = await this.db.db
             .selectFrom("agents")
-            .select(["owner_account_id", "visibility", "current_version"])
+            .select(["owner_account_id", "needs_reassignment", "visibility", "current_version"])
             .where("id", "=", agentId)
             .where("org_id", "=", orgId)
             .where("deleted_at", "is", null)
@@ -515,24 +538,36 @@ let AgentsService = class AgentsService {
             .executeTakeFirst();
         if (!agent)
             throw notFound();
-        if (agent.owner_account_id === actorAccountId || roleAtLeast(role, "admin"))
-            return agent;
-        const visible = await t
+        return agent;
+    }
+    /**
+     * The platform path's lock (a super admin who need not be a member of the org): finds the live
+     * agent's org, locks the org row, then the agent row. A missing or deleted agent, or one of a
+     * deleted org → `agent.not_found`. The super admin check is the caller's (`@SuperAdmin()`).
+     */
+    async lockForPlatform(agentId) {
+        const found = await this.db.db
             .selectFrom("agents")
-            .select("id")
+            .select("org_id")
             .where("id", "=", agentId)
-            .where(visibleTo(actorAccountId))
+            .where("deleted_at", "is", null)
             .executeTakeFirst();
-        if (!visible)
+        if (!found)
             throw notFound();
-        throw new ApiError("forbidden", "Only the agent owner or an organization admin can modify it");
+        const orgId = found.org_id;
+        if (!(await this.orgLock.tryLock(orgId)))
+            throw notFound();
+        return { orgId, agent: await this.lockAgentRow(orgId, agentId) };
     }
     /**
      * 修改 agent：`definition` 变化时写新版本（`current_version + 1`），只改 visibility / memberIds 不产生新版本。
      * 只有负责人或组织管理员以上可改，在组织行锁内复核。
      */
     async update(orgId, agentId, actorAccountId, request, actorTokenId, auditDetail) {
-        const patch = request;
+        // a policy key of a removed builtin (stored before it went) is dropped, never refused
+        const patch = request.definition === undefined
+            ? request
+            : { ...request, definition: withoutRemovedBuiltinPolicies(request.definition) };
         const warnings = patch.definition ? await this.checkModels(orgId, patch.definition) : [];
         const toolKeys = patch.definition
             ? await this.checkTools(orgId, patch.definition, await this.keptDisabled(orgId, agentId))
@@ -641,8 +676,32 @@ let AgentsService = class AgentsService {
         await this.skillChanges.finishCancel(orgId, cancelled);
     }
     async softDeleteIn(orgId, agentId, actorAccountId, actorTokenId, auditDetail) {
-        const t = this.db.db;
         await this.lockForWrite(orgId, agentId, actorAccountId);
+        return this.softDeleteLocked(orgId, agentId, { accountId: actorAccountId, ...(actorTokenId !== undefined && { tokenId: actorTokenId }) }, auditDetail);
+    }
+    /**
+     * The platform's delete (a super admin who need not be a member of the agent's org): the same
+     * effects as {@link softDelete}, under the org row lock, audited `agent.deleted` with
+     * `detail.via = "platform"`. A missing or deleted agent, or one of a deleted org →
+     * `agent.not_found`. `auditDetail` (a Platform tool write's `viaAgent`) is merged into the
+     * detail; `via` stays `"platform"`.
+     */
+    async softDeleteAsPlatform(agentId, actor, auditDetail) {
+        const { orgId, cancelled } = await this.softDeleteAsPlatformIn(agentId, actor, auditDetail);
+        await this.skillChanges.finishCancel(orgId, cancelled);
+    }
+    async softDeleteAsPlatformIn(agentId, actor, auditDetail) {
+        const { orgId } = await this.lockForPlatform(agentId);
+        const cancelled = await this.softDeleteLocked(orgId, agentId, actor, {
+            ...auditDetail,
+            via: "platform",
+        });
+        return { orgId, cancelled };
+    }
+    /** The delete itself; the caller holds the org row and agent row locks. */
+    async softDeleteLocked(orgId, agentId, actor, auditDetail) {
+        const t = this.db.db;
+        const { accountId: actorAccountId, tokenId: actorTokenId } = actor;
         await t
             .updateTable("agents")
             .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
@@ -683,18 +742,23 @@ let AgentsService = class AgentsService {
      * 清除 `needs_reassignment`，审计 `agent.owner_changed`。
      */
     async reassignOwner(orgId, agentId, newOwnerId, actorAccountId, actorTokenId) {
-        const t = this.db.db;
         await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "agents.manage");
-        const agent = await t
-            .selectFrom("agents")
-            .select(["owner_account_id", "needs_reassignment"])
-            .where("id", "=", agentId)
-            .where("org_id", "=", orgId)
-            .where("deleted_at", "is", null)
-            .forUpdate()
-            .executeTakeFirst();
-        if (!agent)
-            throw notFound();
+        const agent = await this.lockAgentRow(orgId, agentId);
+        return this.reassignOwnerLocked(orgId, agentId, agent, newOwnerId, { accountId: actorAccountId, ...(actorTokenId !== undefined && { tokenId: actorTokenId }) }, undefined);
+    }
+    /**
+     * The platform's owner transfer (a super admin who need not be a member of the agent's org):
+     * the same checks and effects as {@link reassignOwner} (the new owner is a member of the agent's
+     * org and not its anonymous guest), audited with `detail.via = "platform"`. A missing or deleted
+     * agent, or one of a deleted org → `agent.not_found`.
+     */
+    async reassignOwnerAsPlatform(agentId, newOwnerId, actor) {
+        const { orgId, agent } = await this.lockForPlatform(agentId);
+        return this.reassignOwnerLocked(orgId, agentId, agent, newOwnerId, actor, { via: "platform" });
+    }
+    /** The owner transfer itself; the caller holds the org row and agent row locks. */
+    async reassignOwnerLocked(orgId, agentId, agent, newOwnerId, actor, auditDetail) {
+        const t = this.db.db;
         const member = await t
             .selectFrom("memberships")
             .select("role")
@@ -711,9 +775,12 @@ let AgentsService = class AgentsService {
             .execute();
         // the new owner hears about the agent's connector setup request (P4-T6-4)
         await this.setupRequests.retargetIn([agentId], newOwnerId);
+        // the previous owner's asks to share the agent's skills lapse (the new owner did not ask);
+        // a share request has no draft or trial, so nothing is left to clean up after the commit
+        await this.skillChanges.cancelPendingForAgent(orgId, agentId, actor.accountId, "owner_changed", actor.tokenId, ["share"]);
         await audit(t, {
-            actorAccountId,
-            ...(actorTokenId !== undefined && { actorTokenId }),
+            actorAccountId: actor.accountId,
+            ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
             orgId,
             action: "agent.owner_changed",
             target: agentId,
@@ -721,6 +788,7 @@ let AgentsService = class AgentsService {
                 from: agent.owner_account_id,
                 to: newOwnerId,
                 neededReassignment: agent.needs_reassignment,
+                ...auditDetail,
             },
         });
         return this.lookup.view(agentId);
@@ -789,15 +857,33 @@ __decorate([
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], AgentsService.prototype, "lockForWrite", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AgentsService.prototype, "lockAgentRow", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AgentsService.prototype, "lockForPlatform", null);
 __decorate([
     Transactional()
 ], AgentsService.prototype, "updateIn", null);
 __decorate([
     Transactional()
 ], AgentsService.prototype, "softDeleteIn", null);
+__decorate([
+    Transactional()
+], AgentsService.prototype, "softDeleteAsPlatformIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AgentsService.prototype, "softDeleteLocked", null);
 __decorate([
     Transactional()
 ], AgentsService.prototype, "reassignOwner", null);
+__decorate([
+    Transactional()
+], AgentsService.prototype, "reassignOwnerAsPlatform", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AgentsService.prototype, "reassignOwnerLocked", null);
 AgentsService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),

package/dist/agents/definition.d.ts

@@ -287,6 +287,22 @@ interface OwnRefs {
  * goes through this: a new definition with an old key is refused (`AgentsService`).
  */
 export declare function normalizeToolKeys(definition: unknown, scope?: LegacyScope, inherited?: OwnRefs): unknown;
+/** The fields {@link withoutRemovedBuiltinPolicies} reads. */
+interface AgentDefinitionLike {
+    toolPolicies?: Record<string, string> | undefined;
+    subagents?: {
+        inline?: readonly {
+            toolPolicies?: Record<string, string> | undefined;
+        }[] | undefined;
+    } | undefined;
+}
+/**
+ * `definition` without the `toolPolicies` keys (its own and its inline sub-agents') of builtins
+ * that no longer exist ({@link isRemovedBuiltinKey}): applied to a definition being saved, so a
+ * key left over from a removed builtin never blocks the save. Returns the same object when
+ * nothing is dropped.
+ */
+export declare function withoutRemovedBuiltinPolicies<T extends AgentDefinitionLike>(definition: T): T;
 /**
  * Does a stored definition or template hold an rc `<x>__<tool>` key, which only a
  * {@link LegacyScope} can map? (Callers load the scope only then.)

package/dist/agents/definition.js

@@ -1,5 +1,6 @@
 import { validateParams } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
+import { isRemovedBuiltinKey } from "../tools/builtin-names.js";
 import { isLegacyBuiltinKey, isLegacyPrefixedKey, legacyToolKey, } from "../tools/legacy-keys.js";
 import { InstructionFilesSchema } from "./instruction-files.js";
 /** 模型引用：供应商插件名 + 模型 id。 */
@@ -219,8 +220,9 @@ export const AgentDefinitionSchema = z.object({
      * 技能（M5 T13）：`orgSkills` 是引用的组织技能 id（保存时校验属于本组织且未删除，不可重复）。
      * agent 自己的技能（`scope=agent`）自动对它生效，不进定义。可省略（较早保存的定义也没有），按空处理；
      * 不给默认值：没用技能的定义保存前后不变，不会因此多出一个版本。
-     * `writePolicy`（M6 T27，D10）：私有 agent 的 `SkillWrite` 是否固定确认，缺省按 `allow`（不写进定义）；
-     * 共享 agent 不论取值都走 R3 + R4。
+     * `writePolicy`: whether registering a skill on a private agent (`agents.register-skill`) needs
+     * the person's confirmation; absent means `allow` (not stored in the definition). On a shared
+     * agent a registration is always confirmed at the org level.
      */
     skills: z
         .object({
@@ -412,6 +414,34 @@ export function normalizeToolKeys(definition, scope, inherited) {
     }
     return changed ? next : definition;
 }
+/**
+ * `definition` without the `toolPolicies` keys (its own and its inline sub-agents') of builtins
+ * that no longer exist ({@link isRemovedBuiltinKey}): applied to a definition being saved, so a
+ * key left over from a removed builtin never blocks the save. Returns the same object when
+ * nothing is dropped.
+ */
+export function withoutRemovedBuiltinPolicies(definition) {
+    const strip = (p) => {
+        if (p === undefined || !Object.keys(p).some(isRemovedBuiltinKey))
+            return p;
+        return Object.fromEntries(Object.entries(p).filter(([k]) => !isRemovedBuiltinKey(k)));
+    };
+    let next = definition;
+    const policies = strip(definition.toolPolicies);
+    if (policies !== definition.toolPolicies)
+        next = { ...next, toolPolicies: policies };
+    const inline = definition.subagents?.inline;
+    if (inline !== undefined) {
+        const stripped = inline.map((t) => {
+            const p = strip(t.toolPolicies);
+            return p === t.toolPolicies ? t : { ...t, toolPolicies: p };
+        });
+        if (stripped.some((t, i) => t !== inline[i])) {
+            next = { ...next, subagents: { ...definition.subagents, inline: stripped } };
+        }
+    }
+    return next;
+}
 /**
  * Does a stored definition or template hold an rc `<x>__<tool>` key, which only a
  * {@link LegacyScope} can map? (Callers load the scope only then.)

package/dist/agents/org-templates.js

@@ -23,6 +23,7 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { skillVersionsById } from "../skills/usable.js";
+import { isRemovedBuiltinKey } from "../tools/builtin-names.js";
 import { canonicalJson } from "../tools/canonical-json.js";
 import { ToolRegistry } from "../tools/registry.js";
 import { AgentLookup } from "./agent-lookup.js";
@@ -204,6 +205,9 @@ extensionTools = []) {
         // is not carried into it
         if (v === "allow")
             continue;
+        // a removed builtin's policy left in a stored definition is not carried
+        if (isRemovedBuiltinKey(k))
+            continue;
         const parsed = parseToolKey(k);
         if (parsed !== null && parsed.kind !== "connector" && TOOL_KEY_RE.test(k)) {
             toolPolicies[k] = v;

package/dist/background/launch.d.ts

@@ -33,7 +33,7 @@ export declare const TASK_ID_RE: RegExp;
  * hand) to `.capybara/tasks/<id>.sh` and starts it with bash (the shell a foreground `Bash` call
  * runs its command in) in a session of its own under `timeout -s KILL <seconds>`, with its exit
  * status written to `<id>.exit` and its output to `<id>.out`; writes the session id (`$!`, the pid
- * `setsid` started) to `<id>.sid` and prints it. A sandbox without one of the needed programs fails with a readable error on
+ * `setsid` started) to `<id>.sid` and prints it. An environment without one of the needed programs fails with a readable error on
  * stderr and exit code 127, before anything starts. `id` must be a task id and `seconds` a
  * positive integer (both go into the script unquoted).
  */

package/dist/background/launch.js

@@ -34,7 +34,7 @@ export function newTaskId() {
         out += BASE32[b & 31];
     return out;
 }
-/** The programs the launch and the later polls and stops need inside the sandbox. */
+/** The programs the launch and the later polls and stops need in the environment. */
 const REQUIRED = ["bash", "setsid", "nohup", "timeout", "pgrep", "pkill", "base64"];
 /** A task id ({@link newTaskId}). */
 export const TASK_ID_RE = /^bt_[a-z2-7]{6}$/;
@@ -43,7 +43,7 @@ export const TASK_ID_RE = /^bt_[a-z2-7]{6}$/;
  * hand) to `.capybara/tasks/<id>.sh` and starts it with bash (the shell a foreground `Bash` call
  * runs its command in) in a session of its own under `timeout -s KILL <seconds>`, with its exit
  * status written to `<id>.exit` and its output to `<id>.out`; writes the session id (`$!`, the pid
- * `setsid` started) to `<id>.sid` and prints it. A sandbox without one of the needed programs fails with a readable error on
+ * `setsid` started) to `<id>.sid` and prints it. An environment without one of the needed programs fails with a readable error on
  * stderr and exit code 127, before anything starts. `id` must be a task id and `seconds` a
  * positive integer (both go into the script unquoted).
  */
@@ -57,7 +57,7 @@ export function launchScript(id, command, seconds) {
     const t = `${TASKS_DIR}/${id}`;
     return [
         "set -e",
-        `for c in ${REQUIRED.join(" ")}; do command -v "$c" >/dev/null 2>&1 || { echo "Background tasks need ${REQUIRED.join(", ")} in the sandbox; $c is missing." >&2; exit 127; }; done`,
+        `for c in ${REQUIRED.join(" ")}; do command -v "$c" >/dev/null 2>&1 || { echo "Background tasks need ${REQUIRED.join(", ")} in this environment; $c is missing." >&2; exit 127; }; done`,
         `mkdir -p ${TASKS_DIR}`,
         `printf '%s' '${b64}' | base64 -d > ${t}.sh`,
         `setsid nohup sh -c 'timeout -s KILL ${seconds} bash ${t}.sh; echo $? > ${t}.exit' > ${t}.out 2>&1 < /dev/null &`,

package/dist/background/tasks.service.d.ts

@@ -24,12 +24,29 @@ export interface BackgroundTaskView {
     /** True while a stop has claimed the task and it is still running. */
     stopping: boolean;
 }
+/**
+ * Why a task's output cannot be read live: `starting` (the launch has not recorded the task's
+ * session yet), `not_started` (the launch failed: the task never ran, its `lostReason` says why),
+ * `device_offline` (the local device's machine is not connected), `suspended` (the instance is
+ * suspended; reading never resumes it), `rebuilt` (the instance the task ran in is gone, and its
+ * files with it), `output_missing` (the instance runs but the output file is gone), `no_access`
+ * (the conversation's owner may no longer use the device), `unavailable` (the device's provider
+ * is not loaded), `read_failed` (the read command failed).
+ */
+export type OutputUnavailableReason = "starting" | "not_started" | "device_offline" | "suspended" | "rebuilt" | "output_missing" | "no_access" | "unavailable" | "read_failed";
+/** Why the live read failed, and where the task ran: a `local` device or a `cloud` sandbox. */
+export interface OutputUnavailable {
+    reason: OutputUnavailableReason;
+    environment: "local" | "cloud";
+}
 export interface BackgroundTaskOutput {
     text: string;
     /** True when `text` is only the end of the output (or, for `event`, the last lines). */
     truncated: boolean;
     /** `live`: read from the running sandbox; `event`: the last lines the finished event kept. */
     source: "live" | "event";
+    /** With `event`: why the output was not read live. */
+    unavailable?: OutputUnavailable;
 }
 /**
  * The HTTP side of background tasks (spec 2026-11-05-background-bash-design §5): the tasks of a
@@ -69,9 +86,24 @@ export declare class BackgroundTasks {
     private deviceUsable;
     /**
      * The end of the task's output, at most `tail` bytes. Read live when the task's device
-     * instance runs (never resuming a suspended one); a finished task whose sandbox does not run answers
-     * with the last lines its finished event kept. Anything else is
-     * `background_task.output_unavailable` (409).
+     * instance runs (never resuming a suspended one); a finished task that cannot be read live
+     * answers with the last lines its finished event kept and why (`unavailable`). Anything else is
+     * `background_task.output_unavailable` (409) with `details: [{ reason, environment }]`.
      */
     output(orgId: string, conversationId: string, accountId: string, taskId: string, tail: number): Promise<BackgroundTaskOutput>;
+    /** Whether the task ran on a local device (its machine) or in a cloud sandbox. */
+    private environmentOf;
+    /** Reads the output from the task's running instance, or says why it cannot. */
+    private readLive;
 }
+/**
+ * Prints `size <bytes>` and `out <base64 of the last `tail` bytes>`, or `missing` when the output
+ * file is not there. Relative to the workspace root; POSIX tools only (`wc -c`, `tail -c`,
+ * `base64`, `tr`), so it reads the same on Linux and macOS.
+ */
+export declare function tailScript(id: string, tail: number): string;
+/**
+ * Decodes {@link tailScript}'s output (`missing`: no output file; null: unreadable); a cut that
+ * splits a UTF-8 character drops its tail bytes.
+ */
+export declare function parseTail(stdout: string, tail: number): Omit<BackgroundTaskOutput, "source"> | "missing" | null;