@sema-agent/server 7.52.1 → 7.54.0

package/dist/plugins/remote-env-e2b.d.ts

@@ -1,13 +1,13 @@
 /**
  * `RemoteContainerExecutionEnv` — the E2B implementation of core's `RemoteExecutionEnv` seam
- * (core src/core/remote-env.ts, design/48 §5). The service control plane owns this backend; core
+ * (core src/core/remote-env.ts, [ref] §5). The service control plane owns this backend; core
  * owns the seam shape (exactly like `CheckpointStore` / `SqlExecutor`).
  *
- * **Scope = design/48 §0.5 v1 minimal slice**: single worker, E2B managed, **Tier 2 only** (every
+ * **Scope = [ref] §0.5 v1 minimal slice**: single worker, E2B managed, **Tier 2 only** (every
  * op runs in a per-task E2B Firecracker VM — no tiering/classification), and the ~4 live seam methods
  * `connect` / `execStream` / `workspaceHandle` / `destroy` + the base `ExecutionEnv` (FileSystem + Shell).
  *
- * **v1.5 (design/49, core 1.69):** `suspendVM` (E2B `pause()`) / `resumeVM` (`Sandbox.connect(id)` auto-resume)
+ * **v1.5 ([ref], core 1.69):** `suspendVM` (E2B `pause()`) / `resumeVM` (`Sandbox.connect(id)` auto-resume)
  * / `postResumeInit` (reachability + at-rest-encryption red line) are IMPLEMENTED — core orchestrates them when
  * a task with this remote env hits a durable-approval `ask` (workspaceHandle → Checkpoint.state). `reconnect`
  * (cross-replica re-attach to a still-running VM) stays deferred to **v2** (v1.5 always snapshots → resumeVM).
@@ -48,7 +48,7 @@ export interface RemoteContainerEnvConfig extends RemoteEnvObservers {
     /** Sandbox metadata (e.g. sessionId/taskId for fleet observability). */
     metadata?: Record<string, string>;
     /**
-     * 🔴 Out-of-band secret/config env injected sandbox-WIDE at create (design/48 §5 gap 7, OA Phase-B): every
+     * 🔴 Out-of-band secret/config env injected sandbox-WIDE at create ([ref] §5 gap 7, OA Phase-B): every
      * command + background process in the VM sees these, but the VALUES never enter the model prompt, the tool
      * `command` string, or the durable event log (which only records the command `args`, redacted). This is the
      * channel for a credential (e.g. a git token the agent uses via GIT_ASKPASS / a credential helper) WITHOUT
@@ -84,7 +84,7 @@ export interface RemoteContainerEnvDeps {
  * FIRST FileSystem/Shell/execStream call (auto `connect()`), so a task that never touches the hand pays zero
  * cost. `connect()` may still be called explicitly (idempotent + concurrency-memoized) if the control plane
  * wants to provision eagerly. `destroy()` on task end (the Runner calls it via `hasDestroy`); a never-used env's
- * destroy is a no-op (nothing to kill, no bill). One container per task (design/48 §5 §7 Q7).
+ * destroy is a no-op (nothing to kill, no bill). One container per task ([ref] §5 §7 Q7).
  */
 export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
     /** Current working directory for relative paths (FileSystem contract; mutable, core may reassign). */
@@ -113,7 +113,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      *  SAME env instance skips the reconnect and every later fs/exec runs against the dead VM. */
     private paused;
     constructor(config: RemoteContainerEnvConfig, deps?: RemoteContainerEnvDeps);
-    /** design/61 §9: E2B is a FULL RemoteExecutionEnv — an isolated, snapshot-suspendable microVM. (SSH/ADB
+    /** [ref] §9: E2B is a FULL RemoteExecutionEnv — an isolated, snapshot-suspendable microVM. (SSH/ADB
      *  adapters declare {isolation:false, suspendable:false} — real machines/devices, not snapshotable.) */
     readonly capabilities: {
         isolation: boolean;
@@ -122,13 +122,13 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     workspaceHandle(): WorkspaceHandle;
     /**
      * Public host for a port inside the sandbox (E2B reverse proxy → `<port>-<id>.e2b.app`). The LSP sidecar
-     * (design/64 §13.1) uses this to reach the in-sandbox language-server WS bridge over `wss://`. Lazily
+     * ([ref] §13.1) uses this to reach the in-sandbox language-server WS bridge over `wss://`. Lazily
      * provisions the VM (like exec/fs); `undefined` if it can't connect → the LSP manager degrades.
      */
     getHost(port: number): Promise<string | undefined>;
     /**
      * Launch a long-running process as a TRUE E2B background command (resolves once launched, E2B keeps it alive)
-     * — for the LSP bridge (design/64 §13.1). NOT the same as `exec` with a shell `&`: E2B reaps a foreground
+     * — for the LSP bridge ([ref] §13.1). NOT the same as `exec` with a shell `&`: E2B reaps a foreground
      * command's process group on completion, which would kill an in-shell `&`/nohup child. Fire-and-forget.
      */
     startBackground(command: string): Promise<void>;
@@ -141,7 +141,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     }>;
     private doConnect;
     /**
-     * v1.5 (design/49): snapshot the workspace via E2B `pause()` (stores fs+memory+process; the snapshot id IS
+     * v1.5 ([ref]): snapshot the workspace via E2B `pause()` (stores fs+memory+process; the snapshot id IS
      * the sandbox id — a paused E2B sandbox is resumed by its id). Atomic contract (council): on failure the VM
      * is left UNTOUCHED (still running) so core can fall back to onAsk. Refuses if a command is in flight
      * (council #4) — never silently snapshot a running command. `abortSignal` bounds a hung pause (council BUG#2).
@@ -167,7 +167,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         error: RemoteExecutionError;
     }>;
     private doResumeVM;
-    /** Cross-replica re-attach to a still-running VM = v2 (design/49 council #15: v1.5 always snapshots→resumeVM). */
+    /** Cross-replica re-attach to a still-running VM = v2 ([ref] council #15: v1.5 always snapshots→resumeVM). */
     reconnect(_sessionToken: SessionToken): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -295,7 +295,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private remoteError;
 }
 /**
- * Build the deployment-level `RunnerDeps.executionEnvFactory` (design/48 v1b). Wiring this onto a
+ * Build the deployment-level `RunnerDeps.executionEnvFactory` ([ref] v1b). Wiring this onto a
  * deployment makes it a "code-agent worker": every task's hand runs in a per-task E2B VM. Deployments that do
  * NOT set this (e.g. OA / review) keep the in-process stub env — routing is **deployment-level** (the factory
  * ctx carries only sessionId/taskId, never a service scenario; that stays out of the generic core seam).

package/dist/plugins/remote-env-file-error.d.ts

@@ -11,7 +11,7 @@
  * 会把**已被取消的操作再打一遍**。host 腿没有这个问题,因为它直接用 `fs` + 自己的分类器
  * (AbortError → `aborted`)—— 也就是说这 4 条腿丢的正是 host 腿有的那个信息。
  *
- * 做成**一个共享函数而不是各腿各修一处**的理由:这一族有 28 个包装点,逐处修必然漏(core [1689] RB-74
+ * 做成**一个共享函数而不是各腿各修一处**的理由:这一族有 28 个包装点,逐处修必然漏(core [ref] [ref]
  * 那条教训:宣布"类修完成"而三个实现只落了一个)。收成一处之后,判据只有一条 ——
  * **文件面的 exec 包装必须走这里**,而这条能被机器检查(见 `test/env-adapter-file-error-parity.test.ts`)。
  */
@@ -19,7 +19,7 @@ import { FileError, type ExecutionError, type RemoteExecutionError } from "@sema
 /** exec 层的错误码 → 文件层的码。只映射**有对应语义**的那些,其余落 `unknown`(诚实降级)。 */
 export declare function fileErrorFromExec(e: ExecutionError | RemoteExecutionError, path?: string): FileError;
 /**
- * shell 命令 exit≠0 时把 **stderr** 分类成 `FileError` 的共享分类器(design/158 B6 R2 裁决:k8s 形=正形)。
+ * shell 命令 exit≠0 时把 **stderr** 分类成 `FileError` 的共享分类器([ref] B6 R2 裁决:k8s 形=正形)。
  *
  * 此前四腿三向分叉:ssh/adb 硬编码 `not_found`(把 EACCES 谎报成"不存在"——keyed-on-code 的调用方会
  * 对一个权限问题走"不存在"分支);local-docker 分类但无 fallback(缺文件报 unknown),且其

package/dist/plugins/remote-env-host.d.ts

@@ -39,16 +39,16 @@ export interface HostEnvConfig {
      */
     workspaceDir?: string;
     /** R7 self-wake: the injected `SchedulerCapability` backend (the TOC self-wake scheduler write side).
-     *  When set, `hasScheduler(env)` is true and core mounts CronCreate/CronDelete/CronList(旧名 CronCancel;Sleep 已 design/136 撤除;挂载在 prepare-task 非 createHandsToolkit——L8 订正); when absent the env
+     *  When set, `hasScheduler(env)` is true and core mounts CronCreate/CronDelete/CronList(旧名 CronCancel;Sleep 已 [ref] 撤除;挂载在 prepare-task 非 createHandsToolkit——L8 订正); when absent the env
      *  reports `supported:false` → INERT (no scheduler tools). Injected at boot only on the single-user host lane. */
     scheduler?: SchedulerCapability;
-    /** design/103 background shell: `false` → INERT (multi-tenant host lane gate). Default (undefined) = on for the
+    /** [ref] background shell: `false` → INERT (multi-tenant host lane gate). Default (undefined) = on for the
      *  single-user TOC host lane. `HOST_BG_ENABLED=false` is an additional global kill switch(🪦 旧名
      *  `HOST_BG_DISABLED` 自 server 3.0.0 起是 fail-loud 墓碑:设了即拒启并指路新名,不再被读取)。 */
     backgroundShell?: boolean;
 }
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability {
-    /** design/61 §9 / DUAL-MODE-DESIGN §5: a `host` env is the operator's real machine — no isolation, no snapshot. */
+    /** [ref] §9 / DUAL-MODE-DESIGN §5: a `host` env is the operator's real machine — no isolation, no snapshot. */
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
@@ -70,7 +70,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     private prepared;
     /** Terminal once {@link destroy} ran — guards fs/exec from running against a removed workspace. */
     private destroyed;
-    /** [1116] 五轮复审:fg/bg spool 根=tmpdir 私有目录(core bgSpoolDir 同形)。workspace 是命令可写区,
+    /** [ref] 五轮复审:fg/bg spool 根=tmpdir 私有目录(core bgSpoolDir 同形)。workspace 是命令可写区,
      *  `git clean -fdx` 类清理会 unlink 活跃 spool(子进程经继承 fd 对 unlinked inode 继续写,而父进程
      *  按路径 statSync/read 静默断=输出丢失+轮转帽失效);顺带不再弄脏 user-owned workspace(TOC/CC
      *  persistent 形)。懒建;destroy 整树清。 */
@@ -78,7 +78,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     /** 🔴 在飞的 fg spool 目录登记表(2026-07-25)。`destroy()` 原来只看 `bgManager.hasShells()` 就 `rm -rf`
      *  spool 根 —— 而**前台** exec 的 spool 也在同一个根下,子进程通过继承的 fd 继续往已 unlink 的 inode 写,
      *  父进程按**路径** stat/read 于是什么都看不到 ⇒ 命令照跑、副作用照落盘,但 stdout 被静默截断,还返回
-     *  `exitCode 0`。对模型而言那与「成功且无输出」**不可区分**。(与 core RB-73 同形:写已释放的 inode。)
+     *  `exitCode 0`。对模型而言那与「成功且无输出」**不可区分**。(与 core [ref] 同形:写已释放的 inode。)
      *  判据与 `hasShells()` 并列:**只要还有人在读写这个根下的文件,就不删它**。 */
     private readonly liveFgSpools;
     private ensureSpoolRoot;
@@ -142,7 +142,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         shellId: BackgroundShellId;
     }, BackgroundShellError>>;
     /**
-     * design/116 detach (core 1.207, clay 排 1.81): ADOPT a still-running FOREGROUND exec child as a background
+     * [ref] detach (core 1.207, clay 排 1.81): ADOPT a still-running FOREGROUND exec child as a background
      * shell — the mid-flight ctrl+b path. The exec child writes to pipes (not files, unlike a `launch`-spawned
      * bg shell), so adoption splices those live pipes into fresh bg spool files: pre-fill them with the output
      * captured so far (the detach TEE, fed from the exec's FIRST chunk → TaskOutput's first read has the full
@@ -171,12 +171,12 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     }, ExecutionError>>;
     /** 管道旧形(win32 / spool 打开失败的回退;行为=1.225 及以前的 exec 原样)。 */
     private execViaPipes;
-    /** [1116] fg spool pair:tmpdir 私有根下专属子目录(五轮复审迁址,workspace=命令可写区不可放)+ "ax"
+    /** [ref] fg spool pair:tmpdir 私有根下专属子目录(五轮复审迁址,workspace=命令可写区不可放)+ "ax"
      *  独占建(core openSpoolPair 同形)。失败=undefined(调用方回退管道形)。 */
     private openFgSpool;
-    /** [1116] spool 形 fg exec(core node-execution-env 1.318-1.321 机制移植;坑图=core CHANGELOG 同段)。 */
+    /** [ref] spool 形 fg exec(core node-execution-env 1.318-1.321 机制移植;坑图=core CHANGELOG 同段)。 */
     private execViaSpool;
-    /** [1116] spool 形 detach adoption:spool 路径+fg 游标直接进 HostBgState 的 FILE 面(launch 同形,poll
+    /** [ref] spool 形 detach adoption:spool 路径+fg 游标直接进 HostBgState 的 FILE 面(launch 同形,poll
      *  共码);同一文件单一字节流=天然无 decoder 接缝(mem-tee 版为此专门修过的病在此结构性不存在)。 */
     private adoptRunningExecSpool;
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
@@ -210,7 +210,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  ⇒ 用户仓库根目录按后台任务数累积 `bash-task-<hex>.output`(内容=命令输出)+ 每次 `createTempDir` 一个
      *  `tmp-XXXXXX/`,**永久**留在他们的 git 树里。两条独立判据说明这是偏差不是设计:①core 自己的 TOC 参照实现
      *  `NodeExecutionEnv.createTempFile` 放的是 `os.tmpdir()`;②**本适配器早就为了同一个理由把 spool 根搬去了
-     *  tmpdir**([1116] 五轮复审明写"不再弄脏 user-owned workspace"),只是 createTempFile/Dir 没跟上。
+     *  tmpdir**([ref] 五轮复审明写"不再弄脏 user-owned workspace"),只是 createTempFile/Dir 没跟上。
      *  改用本 env 自己的 tmp 根(`ensureSpoolRoot()`,已在 `os.tmpdir()` 下):
      *   · 用户目录不再被写入;
      *   · 镜像写仍然可用 —— `isLingeringMirrorTarget` 同批放行这个根(见那里的旁注);

package/dist/plugins/remote-env-k8s.d.ts

@@ -35,7 +35,7 @@ export interface K8sEnvConfig {
         backoffMs?: number;
     };
     /**
-     * Workspace-snapshot store (design/48 §5 WorkspaceHandle/SnapshotId). When set, the Kata pod
+     * Workspace-snapshot store ([ref] §5 WorkspaceHandle/SnapshotId). When set, the Kata pod
      * gains a DURABLE workspace across suspend/resume: `suspendVM` tars the workspace and uploads it to S3, then
      * deletes the pod; `resumeVM` provisions a fresh pod and restores the tar. This raises `capabilities.suspendable`
      * to `true` — but only the *workspace* is durable (files restored byte-for-byte); in-VM process/memory state
@@ -43,7 +43,7 @@ export interface K8sEnvConfig {
      * tolerate. Unset → `suspendable:false` (the original checkpoint + cold-rebuild degrade).
      *
      * 🔴 Credentials are ADAPTER-HELD: the sandbox only ever receives a short-lived, single-object PRESIGNED URL
-     * (never the access/secret key) — a credential reaching code that runs untrusted work is the design/53 lethal
+     * (never the access/secret key) — a credential reaching code that runs untrusted work is the [ref] lethal
      * trifecta. The presigned URL is used only inside an adapter-issued exec at suspend/resume time, so it never
      * reaches an agent turn.
      */
@@ -60,7 +60,7 @@ export interface K8sEnvConfig {
     sessionId?: string;
     /**
      * 🔴 ADDITIVE pod-spec patch (a SERVICE-side adapter seam, NOT a core seam: the K8s pod shape is
-     * provider-specific, so it stays in the adapter per design/48). A deployment supplies extra volumes / volumeMounts
+     * provider-specific, so it stays in the adapter per [ref]). A deployment supplies extra volumes / volumeMounts
      * / securityContext so the pod can carry e.g. a REAL read-only oracle mount (the RSI L8 immutable-mount probe) or
      * a hardened grader env (the graderEnvFactory). DEFAULT absent ⇒ the pod is byte-identical. The patch is TRUSTED
      * deployment config (like the rest of K8sEnvConfig) AND is STRUCTURALLY CONFINED: {@link applyPodSpecPatch} can
@@ -90,7 +90,7 @@ export interface ExecSocket {
     terminate?(): void;
 }
 /**
- * Test seam (design/61 §9.3 fault-injection): inject the REST `request` and/or the exec-socket factory, so pod
+ * Test seam ([ref] §9.3 fault-injection): inject the REST `request` and/or the exec-socket factory, so pod
  * lifecycle, retry policy, channel framing and liveness are deterministically testable without a cluster.
  */
 export interface K8sEnvDeps {
@@ -183,7 +183,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * provision a pod, then download + untar the snapshot into the workspace. A missing object (empty/plan-only
      * snapshot) resumes as a clean workspace.
      *
-     * [1467]①(priorHandle 根保真)——k8s 走**诚实臂**而非绑定臂:pod 的 workspace volume 挂在**当前**
+     * [ref]①(priorHandle 根保真)——k8s 走**诚实臂**而非绑定臂:pod 的 workspace volume 挂在**当前**
      * 配置根(cfg.mountPath),往 priorHandle.mountPath 绑=往容器 rootfs untar 大工作区,ephemeral-storage
      * 触顶即 pod 驱逐(恢复中途死,比「根变了 fail-closed reopen」更糟)。所以 untar 落当前根、handle 回报
      * 真生效根(core 契约明许:「做不到就诚实返回实际 mountPath,勿回显未兑现值」);跨 K8S_MOUNT_PATH
@@ -191,7 +191,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      */
     resumeVM(snapshotId: SnapshotId, options?: VmLifecycleOptions): Promise<ConnectResult>;
     /**
-     * Honest post-resume consistency (design/48 §5 council #8): the workspace FILES are restored byte-for-byte
+     * Honest post-resume consistency ([ref] §5 council #8): the workspace FILES are restored byte-for-byte
      * from the snapshot, so read-before-edit hashing already lines up — there's nothing to re-fetch. In-VM
      * process state (a language server) is gone by design; core/the LSP manager re-establishes it lazily. So
      * this is a successful no-op rather than the previous `unsupported` (which forced a cold rebuild).
@@ -224,7 +224,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
         };
     }, ExecutionError>>;
     /**
-     * LSP surface (lsp/manager.ts `isLspCapable` duck-type, design/64 §13.1): cluster-internal address for a
+     * LSP surface (lsp/manager.ts `isLspCapable` duck-type, [ref] §13.1): cluster-internal address for a
      * port on the sandbox pod. The E2B counterpart returns a public proxy host; a pod has none — the WORKER
      * must be able to reach pod IPs (in-cluster deployment, or on-node), and the transport is plain `ws://`
      * (cluster network, no TLS — the per-session bridge token still gates access like on E2B).

package/dist/plugins/remote-env-local-docker.d.ts

@@ -182,7 +182,7 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     /** Spawn the docker binary with argv; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     private docker;
     /** Lazy connect for an exec path → ExecutionError on failure (fail closed, never throws). */
-    /** S1([1870]):容器内**用户命令**的 shell。缺省 /bin/sh;首次连接后探测一次 `command -v bash`,
+    /** S1([ref]):容器内**用户命令**的 shell。缺省 /bin/sh;首次连接后探测一次 `command -v bash`,
      *  有则切 bash(TB 实测 dash 三病:$'\t' 静默错字节/[[ ]] 127/进程替换)。镜像无 bash(alpine 裸底)
      *  ⇒ 保 sh(修前字节形,诚实降级);探测自身失败同。容器**创建**引导命令(mkdir && tail)不走
      *  本 shell——无 bash 语法且探测尚不可能。 */

package/dist/plugins/remote-env-ssh.d.ts

@@ -5,7 +5,7 @@ export interface SshEnvConfig {
     host: string;
     port?: number;
     username: string;
-    /** PEM private key — from the adapter-held secret env (NEVER the workspace). design/61 §5 #2. */
+    /** PEM private key — from the adapter-held secret env (NEVER the workspace). [ref] §5 #2. */
     privateKey: string;
     passphrase?: string;
     /** Workspace root; relative paths resolve against it. Default "." (the login dir). */
@@ -15,7 +15,7 @@ export interface SshEnvConfig {
     /**
      * Per-command wall-clock bound (ms) when the caller gives none — NOT the connection lifetime.
      *
-     * ⚠️ **值与孪生腿不一致,原因未成文**(2026-08-08,#176 二轮扫描 finding,**候裁**):本腿默认
+     * ⚠️ **值与孪生腿不一致,原因未成文**(2026-08-08,[ref] 二轮扫描 finding,**候裁**):本腿默认
      * `5 * 60_000`(见构造处),而同判据的另外两条腿 —— `remote-env-host.ts` / `remote-env-local-docker.ts`
      * 的 `DEFAULT_COMMAND_TIMEOUT_MS` —— 都是 `30 * 60_000`,JSDoc 措辞还逐字同源。三处无共享常量、无对表
      * 钉,ssh 这一处也没有任何注释说明 5min 是刻意收紧(git 史是 history-free snapshot,「30min 是后来调
@@ -28,12 +28,12 @@ export interface SshEnvConfig {
     commandTimeoutMs?: number;
     /** File-transfer (sftp) bound (ms). */
     dataTimeoutMs?: number;
-    /** connect retry (idempotent establishment only — withRetry, design/61 §2A). */
+    /** connect retry (idempotent establishment only — withRetry, [ref] §2A). */
     retry?: {
         maxAttempts?: number;
         backoffMs?: number;
     };
-    /** #296 / C-R21:主机密钥校验策略(两旋钮,语义见 {@link SshHostKeyPolicy});缺席 = 两旋钮都没配。 */
+    /** [ref] / [ref]:主机密钥校验策略(两旋钮,语义见 {@link SshHostKeyPolicy});缺席 = 两旋钮都没配。 */
     hostKey?: SshHostKeyPolicy;
 }
 type ConnectResult = {
@@ -44,7 +44,7 @@ type ConnectResult = {
     error: RemoteExecutionError;
 };
 /**
- * Test seam (design/61 §9.3 fault-injection): inject a `connectOnce` that replays an error sequence, so the
+ * Test seam ([ref] §9.3 fault-injection): inject a `connectOnce` that replays an error sequence, so the
  * retry policy (retryable codes / maxAttempts / "first fail → second success") is deterministically testable
  * without a live host.
  */
@@ -61,12 +61,12 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     private conn?;
     private sftpPromise?;
     private destroyed;
-    /** [1165] 代际闸:destroy/reconnect 各自 +1。逻辑连接操作(startConnect)起飞时抓拍一次并贯穿全部
+    /** [ref] 代际闸:destroy/reconnect 各自 +1。逻辑连接操作(startConnect)起飞时抓拍一次并贯穿全部
      *  重试轮(四轮复审:抓拍若在 connectOnce 内,被顶替代的下一轮重试会抓到**新**代际混进新代)——
      *  每轮起跳先查代际/destroyed(陈旧=不再开 socket),ready 到达再查一次(在飞握手 late-ready=end
      *  不赋 conn)。关死「A 在飞→reconnect 起 B→A 竞后抢占/成孤儿活连接」的全部竞窗。 */
     private connEpoch;
-    /** [1165] 四轮复审 single-flight:connect()/reconnect()/懒连接三路共用一条代际键在飞记录——任何一路
+    /** [ref] 四轮复审 single-flight:connect()/reconnect()/懒连接三路共用一条代际键在飞记录——任何一路
      *  在飞时其余路 join 同一 promise(同代际),绝不并起两条连接;settle 时按记录身份清(旧败诺清不掉
      *  新记录)。五轮复审:①记录带 kind——并发 reconnect join 已在飞的 replace 记录(不再各自 bump 代际
      *  =重连风暴);②共享尝试**不携带任何 caller 信号**(首创者的 pre-abort 不得毒化 joiner;单 caller
@@ -86,11 +86,11 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     }>;
     /** 五轮复审:per-caller 可中止等待(共享诺不动,只退本 caller)。 */
     private raceConnAbort;
-    /** [1165] 四轮复审:三路(connect/reconnect/懒连接)唯一的连接发起点——同代际在飞记录 join,settle
+    /** [ref] 四轮复审:三路(connect/reconnect/懒连接)唯一的连接发起点——同代际在飞记录 join,settle
      *  身份清;代际抓拍一次贯穿全部重试轮,每轮起跳先查(陈旧/destroyed=不再开 socket,用不可重试的
      *  aborted 码即刻收敛 withRetry)。五轮复审:共享尝试零 caller 信号(取消面全在 per-caller race)。 */
     private startConnect;
-    /** [1165] exec/execStream/sftp 共用的懒连接入口。已连=零开销直过;未连=走完整 connect()(含重试策略)。
+    /** [ref] exec/execStream/sftp 共用的懒连接入口。已连=零开销直过;未连=走完整 connect()(含重试策略)。
      *  caller 的 signal 只中止**它自己的等待**(共享在飞尝试继续伺服其他等待者;彻底取消归 destroy 的代际
      *  闸管,handshake 余命 ≤ readyTimeout 有界)。 */
     private ensureConnected;

package/dist/plugins/remote-scratchpad.d.ts

@@ -1,5 +1,5 @@
 /**
- * [848] remote scratchpad(server 半场)— the REMOTE sandbox lanes' session scratchpad convention.
+ * [ref] remote scratchpad(server 半场)— the REMOTE sandbox lanes' session scratchpad convention.
  *
  * host lane already has one (env-facts.ts ensureScratchpadDir, worker-local under localDataRoot). The remote
  * lanes (e2b/k8s/local-docker/ssh) run their hands OFF this box, so a worker-local dir would be a lie — the

package/dist/plugins/resume-anchor-store-sql.d.ts

@@ -1,5 +1,5 @@
 /**
- * Durable resume-at anchor map (E18) — SINGLE-FILE DUAL-DIALECT (design/158 A12 收编). The service-owned
+ * Durable resume-at anchor map (E18) — SINGLE-FILE DUAL-DIALECT ([ref] A12 收编). The service-owned
  * eventId→entryId translation: the shell holds the live E2 `eventId` (core never persists it); core's
  * `TaskSpec.resumeAt` takes a persisted `SessionTreeEntry.id`. Keyed (session_id, event_id) so `resolve`
  * is a PK point-lookup. `owner` is the single-DB-fleet null-safe defense-in-depth guard, the data-layer

package/dist/plugins/retention-lane-store-sql.d.ts

@@ -1,6 +1,6 @@
 /**
- * 托管留存执行面的**非破坏性 SQL 半场** —— SINGLE-FILE DUAL-DIALECT(design/158 A12;先例 =
- * `retention-store-sql.ts` 本身)。#270 车2,设计稿 `docs/DESIGN-270-retention-lane.md` v1.3。
+ * 托管留存执行面的**非破坏性 SQL 半场** —— SINGLE-FILE DUAL-DIALECT([ref] A12;先例 =
+ * `retention-store-sql.ts` 本身)。[ref] 车2,设计稿 `docs/DESIGN-270-retention-lane.md` v1.3。
  *
  * ── 为什么与车1 的 `retention-store-sql.ts` 分家(而不是往那只店上再挂三组方法)────────────────────
  * 车1 那只店是 core `ManagedRetentionCapability` 的**实现体**:它的每一个公开方法都是一次**破坏性**

package/dist/plugins/retention-store-sql.d.ts

@@ -1,6 +1,6 @@
 /**
- * 托管留存(managed retention)执行面的 **store 半场** —— SINGLE-FILE DUAL-DIALECT(design/158 A12 定型半场;
- * 先例 = `leader-run-store-sql.ts` / `checkpoint-store-sql.ts`)。#270 车1,设计稿
+ * 托管留存(managed retention)执行面的 **store 半场** —— SINGLE-FILE DUAL-DIALECT([ref] A12 定型半场;
+ * 先例 = `leader-run-store-sql.ts` / `checkpoint-store-sql.ts`)。[ref] 车1,设计稿
  * `docs/DESIGN-270-retention-lane.md` v1.2。上游契约真源 = `@sema-agent/core` 的
  * `core/retention.d.ts`(`ManagedRetentionCapability` / `RetentionReceipt` / `RetentionDeclaration`)。
  *
@@ -39,7 +39,7 @@
  *   - schema 属主:MySQL DDL 由本文件导出、展开进 `tidb-pool.ts` 的 `SCHEMA_STATEMENTS`;PG DDL 由本文件的
  *     `ensurePgRetentionSchema` 导出、由 `pg-pool.ts` 的中央 `ensurePgSchema` 组合(与 leader-run 同姿势)。
  *
- * ── 命名(#192 纪律,与设计稿的复数写法的**有意**偏离)────────────────────────────────────────────
+ * ── 命名([ref] 纪律,与设计稿的复数写法的**有意**偏离)────────────────────────────────────────────
  * 设计稿 §5/§2 写的是 `retention_holds` / `retention_tombstones`;本仓的表名闭集词表是**单数**制且由
  * `test/schema-naming-invariants.test.ts` 机器执法(「一张表是一类行的集合,表名说的是『一行是什么』」)。
  * ⇒ 落库名一律单数:`retention_audit` / `retention_hold` / `retention_lease` / `retention_tombstone`。
@@ -136,7 +136,7 @@ export interface SqlRetentionStoreOptions {
      */
     taskAttachmentTable: boolean;
     /**
-     * #318 `task_list_meta` / `task_list_item` 两表是否在场。**必填,没有默认值**(与
+     * [ref] `task_list_meta` / `task_list_item` 两表是否在场。**必填,没有默认值**(与
      * `taskAttachmentTable` 同一条理由:盲发 DELETE 会在没建表的库上把整轮 sweep 打红)。
      * 生产上 `boot/task-list-lane.ts` 在**任何 SQL 后端**都无条件 ensure 这两张表 ⇒ 装配层照实传 true;
      * 纯内存/local 车道压根没有 SQL 留存腿。
@@ -282,17 +282,17 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      *      COMMIT,一个并发的 PUT hold 在此期间提交不了(它抢同一把锁)——一段恒真的"复核"比没有更坏。
      *
      * 视界判据**两条臂都写出来**:`deadline` 在场按 deadline,缺席按 `created_at_ms`。少了后一条臂,一条
-     * 没有审批 TTL 的 pending 行就永远过不了期(design/80 §3 inv#3 的 terminal_at_ms 要挡的正是这种永久泄漏)。
+     * 没有审批 TTL 的 pending 行就永远过不了期([ref] §3 inv#3 的 terminal_at_ms 要挡的正是这种永久泄漏)。
      *
-     * 🔴 **pin 释放 = 本方法的 `pending → expired` 翻转本身**(core [4180] 定谳:retention.ts 契约那句
-     * 「AND release the associated session pins」是真意,[4175] 引错了对象——它引的是引擎 live-path reap
+     * 🔴 **pin 释放 = 本方法的 `pending → expired` 翻转本身**(core [ref] 定谳:retention.ts 契约那句
+     * 「AND release the associated session pins」是真意,[ref] 引错了对象——它引的是引擎 live-path reap
      * 的 JSDoc)。本仓 SQL 后端**没有独立的 pin 存储**:钉住 session 的正是 `checkpoint.status='pending'`
      * 这一状态(它是 deleteExpiredSessions 活引用四腿之一,见下方 lineage 注 :79x),所以状态翻转 = 引用
-     * 解除 = pin 释放——不需要第二个写操作,而幂等(重跑对已 expired 行零命中)恰好满足 [4180] 的
-     * 「释放已释放 pin=no-op」要求。单写者不变式按 [4180] 改述:**每行的 pin 恰好释放一次,由终局该行
+     * 解除 = pin 释放——不需要第二个写操作,而幂等(重跑对已 expired 行零命中)恰好满足 [ref] 的
+     * 「释放已释放 pin=no-op」要求。单写者不变式按 [ref] 改述:**每行的 pin 恰好释放一次,由终局该行
      * 的车道执行**——live 行归 reaper,retention 行归本方法,两行集不交(下一段的 live-pin skip 正是
      * 「不交」的执行判据)。
-     * 边界形([4175] 建议,[4180] 确认仍成立):**live-pinned 且已过视界**的行(`task_active` 还占着这条
+     * 边界形([ref] 建议,[ref] 确认仍成立):**live-pinned 且已过视界**的行(`task_active` 还占着这条
      * 会话)⇒ skip 计数、不动那行 —— 不在一条活会话脚下抽掉它的 resume 坐标,与 legal-hold 的 skip 同形。
      *
      * receipt 口径:`deleted` = **本次 CAS 赢下的行数**(过期销毁的是那道 pending 门,行本身按设计留在库里
@@ -304,7 +304,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * 抽成一处是因为它同时被「可过期候选」与「被 pin 的计数」两条查询用,手抄两份必分家。
      */
     private horizonArms;
-    /** 「这条 checkpoint 的会话被一次活跑占着」= [4175] 的 live-pinned 判据(SQL 谓词形,两方言同文本)。 */
+    /** 「这条 checkpoint 的会话被一次活跑占着」= [ref] 的 live-pinned 判据(SQL 谓词形,两方言同文本)。 */
     private static readonly PINNED_EXISTS;
     /**
      * **可过期**的候选 token(保护谓词写在 SQL 里、扣在 `LIMIT` **之前**)。

package/dist/plugins/roster-store-sql.d.ts

@@ -1,9 +1,9 @@
 /**
- * RosterStore SQL twins(agent-team S1 server 半场,[1070]① 提货单)——core `RunnerDeps.rosterStore`
+ * RosterStore SQL twins(agent-team S1 server 半场,[ref]① 提货单)——core `RunnerDeps.rosterStore`
  * 的 TiDB/PG 双方言实现:具名子 agent 的持久名册(具名 spawn advisory 写入;SendMessage 活注册表
  * miss 后咨询;v1=诚实指针 roster_only,非跨 run resume)。
  *
- * 语义三条([1070]① 必守,与 core roster-store.js 参考实现字节对齐):
+ * 语义三条([ref]① 必守,与 core roster-store.js 参考实现字节对齐):
  *  1. resolve **查询内** filter-before-reduce:access 轴在 SQL WHERE 完成(scope 先拒 → owner 匹配 →
  *     sessionScoped 显式位才认 session 匹配),绝不先取全集再内存过滤(跨租户行连查询结果都不进);
  *  2. 同 `(normalizedName, owner, scope)` 域 upsert(core upsertKey 同键);
@@ -15,14 +15,13 @@
  * spawn 可共享毫秒、多副本时钟可偏斜,无第三键的 LIMIT 1 非确定)。诚实记账:同毫秒并写时选择=
  * agent_id 字典序最大,与 core 单进程的「后遍历者赢」可能不同——多副本本就无全序,确定性优先。
  *
- * normalize 私拷已回收(2026-07-19):core 公共出口落地(黑板 [1070]① 所请的 additive 导出),按
+ * normalize 私拷已回收(2026-07-19):core 公共出口落地(黑板 [ref]① 所请的 additive 导出),按
  * 头注预案换回单行 import。⚠️ 语义仍是**存储键**:DB 行按 normalize 后的键写入——core 若改语义,
  * 存量行查不回;test/roster-store-db-integration.test.ts 的 golden corpus 钉守这条(非私拷漂移钉,
  * 是「core 变语义必须先过迁移裁量」的告警钉)。
  */
 import type { Pool } from "mysql2/promise";
-import { type RosterStore, type RosterEntry } from "@sema-agent/core";
-type RosterAccess = Parameters<RosterStore["resolve"]>[1];
+import { type RosterStore, type RosterEntry, type RosterAccess } from "@sema-agent/core";
 import type { PgQueryFn } from "./pg-query.js";
 export declare const ROSTER_TABLE = "agent_roster";
 export declare function ensureTiDBRosterSchema(pool: Pool): Promise<void>;
@@ -35,7 +34,7 @@ export declare class TiDBRosterStore implements RosterStore {
     resolve(name: string, access: RosterAccess): Promise<RosterEntry | undefined>;
     list(): Promise<RosterEntry[]>;
     releaseAgent(agentId: string): Promise<void>;
-    /** [1522] MED2(server 扩展,非 core 接口;core RB-23②③ 派给部署的清理半场):TTL 清理——
+    /** [ref] MED2(server 扩展,非 core 接口;core [ref]②③ 派给部署的清理半场):TTL 清理——
      *  task-scoped 具名 spawn 的 owner=宿主 taskId=每 run 一新行,无清理=线性无界。按 recorded_at_ms
      *  (最后一次 upsert 触碰)删,latest 语义不受影响(活跃名恒被新 spawn 刷新)。 */
     reapOlderThan(cutoffMs: number): Promise<number>;
@@ -48,8 +47,7 @@ export declare class PgRosterStore implements RosterStore {
     resolve(name: string, access: RosterAccess): Promise<RosterEntry | undefined>;
     list(): Promise<RosterEntry[]>;
     releaseAgent(agentId: string): Promise<void>;
-    /** [1522] MED2(TiDB twin 同案注)。 */
+    /** [ref] MED2(TiDB twin 同案注)。 */
     reapOlderThan(cutoffMs: number): Promise<number>;
 }
-export {};
 //# sourceMappingURL=roster-store-sql.d.ts.map

package/dist/plugins/run-store-sql.d.ts

@@ -1,5 +1,5 @@
 /**
- * Async run registry (S1) + replayable event log (S2) — SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场).
+ * Async run registry (S1) + replayable event log (S2) — SINGLE-FILE DUAL-DIALECT ([ref] A12 定型半场).
  * ONE implementation, TWO dialects; the historical `TiDBRunStore` / `PgRunStore` class names survive as thin
  * ctor subclasses so every consumer (store-backend.ts, the run/reaper/session/usage suites) is untouched.
  *
@@ -15,12 +15,12 @@
  *   - `?` placeholders vs `$n` (transaction control itself is normalized by `SqlDriver`/`SqlTxConn` —
  *     mysql2's native begin/commit/rollback vs PG's statement form; see sql-driver.ts)
  *   - dup-key classification (createRun's task_active claim race) — the PREDICATE has a single owner
- *     (`sql-errors.ts`, A-032 P1-①); only the dialect DISPATCH is visible here
+ *     (`sql-errors.ts`, [ref] P1-①); only the dialect DISPATCH is visible here
  *
  * ⚠️ The run ACTIVE-status word list written out in the `status IN (…)` / `NOT IN (…)` fragments below
  * is the closed set owned by `store-contracts.ts` (`isTerminalRunStatus` / `isParkedRunStatus`). The SQL
  * text stays literal ON PURPOSE (A12: both dialects readable side by side), so the tie is a PARITY GATE:
- * `test/source-hygiene-gate.test.ts` → "A-032 P1-② run 活状态 SQL 字面 ↔ store-contracts 闭集属主 parity".
+ * `test/source-hygiene-gate.test.ts` → "[ref] P1-② run 活状态 SQL 字面 ↔ store-contracts 闭集属主 parity".
  * core adding a TaskStatus member turns that gate red on every fragment here — update them in the same batch.
  *   - null-safe owner compare: `<=>` (TiDB) vs `IS NOT DISTINCT FROM` (PG) — a null-owner run still matches
  *     `owner=null` on both, single-DB-fleet defense-in-depth (see {@link requestCancel})
@@ -51,7 +51,7 @@ export declare class SqlRunStore {
     constructor(db: SqlDriver);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
-    /** Dup-key classification — single owner in `sql-errors.ts` (A-032 P1-①; the old local form read
+    /** Dup-key classification — single owner in `sql-errors.ts` ([ref] P1-①; the old local form read
      *  only mysql2's string `code`, so an error carrying just `errno` fell through the claim-race arm). */
     private isDupKey;
     /** JSON column binding: TiDB stores the string verbatim; PG goes through the protocol-safe envelope
@@ -88,7 +88,7 @@ export declare class SqlRunStore {
     /** Whether a cancel has been requested for this run (polled by the owning instance's heartbeat tick).
      *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}). */
     isCancelRequested(taskId: string, owner: string | null): Promise<boolean>;
-    /** design/80 seam #2: request PREEMPT (graceful durable yield, ≠ cancel's kill) of a RUNNING run — durable +
+    /** [ref] seam #2: request PREEMPT (graceful durable yield, ≠ cancel's kill) of a RUNNING run — durable +
      *  cross-replica. Sets the flag the owning instance's heartbeat tick polls (it then aborts its preemptSignal →
      *  the task suspends at the next clean turn boundary, gate resource_limit/reason preempt); a same-replica caller
      *  additionally aborts the in-flight preempt controller for instant effect. Only flags a `running` row
@@ -112,7 +112,7 @@ export declare class SqlRunStore {
      *  colliding on the (task_id, seq) PK. */
     maxSeq(taskId: string): Promise<number>;
     /** Mark terminal AND release the single-active-run claim atomically — if the DELETE were a separate
-     *  statement that failed, the session would stay permanently locked. [888] FIRST terminal writer wins:
+     *  statement that failed, the session would stay permanently locked. [ref] FIRST terminal writer wins:
      *  the UPDATE is CAS'd POSITIVELY on the live statuses (running/suspended/needs_review) — every call site
      *  is a settle-once flow whose backstops may double-fire (cancel × leg-throw × reaper), and an
      *  unconditional write let the LAST racer overwrite errorCode (a `cancelled` row flipping to a generic
@@ -121,18 +121,18 @@ export declare class SqlRunStore {
      *  unconditional (idempotent; the first writer already released it). */
     setTerminal(taskId: string, status: TaskStatus, result: TaskResult | null, error: string | null): Promise<void>;
     /**
-     * Durable F4 (design/45): a task suspended on a policy `ask`. Sets the run NON-terminal `suspended` and
+     * Durable F4 ([ref]): a task suspended on a policy `ask`. Sets the run NON-terminal `suspended` and
      * KEEPS the `task_active` claim — the session stays locked (no new run) until an operator resumes it to a
      * terminal state or the reaper expires it. The token-bearing result is NOT stored (the submitter polling
      * this row must never receive the capability token); only the status flips.
      */
     setSuspended(taskId: string): Promise<void>;
     /**
-     * design/80 D-B: PARK a run that paused on a REVIEW gate — a `needs_review` result (a dry-run diff review OR a
+     * [ref] D-B: PARK a run that paused on a REVIEW gate — a `needs_review` result (a dry-run diff review OR a
      * pre-action `plan_review`; core assemble-result slot 8.6). Like {@link setSuspended} this is a NON-terminal park
      * that KEEPS the `task_active` session claim (it does NOT delete it — only {@link setTerminal} does), so the
      * resume path (`getActiveTaskId` → `markResuming`) can find + claim the row. core treats a review pause "like a
-     * suspend, an INTENTIONAL durable pause" (design/76 §2.5) — the service MUST park it the same way, else the run is
+     * suspend, an INTENTIONAL durable pause" ([ref] §2.5) — the service MUST park it the same way, else the run is
      * terminalized + its lock released and the plan_review/dry_run_review resume can never run (it gets
      * taskId=undefined and drives the model unprotected on an unlocked session). CAS on `running`/`needs_review`
      * (reaper-revert guard, mirrors setSuspended). The park→resume→claim invariant is pinned on BOTH REAL engines by
@@ -153,7 +153,7 @@ export declare class SqlRunStore {
      * crosses the TTL is marked `failed` mid-run and its session lock (`task_active`) is released. Returns true
      * if it claimed the flip (false ⇒ the reaper already expired it, or it isn't suspended).
      *
-     * S-51(codex R1 [medium],红先双库证):认领 = **接管 `instance_id`**。此前该列只在 createRun 铸、此处不动,
+     * [ref](codex R1 [medium],红先双库证):认领 = **接管 `instance_id`**。此前该列只在 createRun 铸、此处不动,
      * 于是 A 创建、C 认领 resume 的行永远记 A —— 而 steer/interrupt 的「他副本」臂与 sendHandleMiss 都拿这列当
      * 「当前持有者」证据:verify 形 resume 腿(不登记 steerable)在 C 上跑时,C 读到 A≠C 就谎报「run 在别的副本」。
      * 语义自此成文:`instance_id` = **当前持有副本**(createRun 铸、markResuming 认领接管);CAS 输不改列
@@ -286,7 +286,7 @@ export declare class SqlRunStore {
      * the run + RELEASE its task_active (unlock the session). Mirrors the checkpoint reaper's CAS-expire (≈ deny);
      * idempotent across replicas. Returns count.
      *
-     * 🔴 design/80 D-D (blocker fix): SKIPS any row whose checkpoint is STILL pending — that row is
+     * 🔴 [ref] D-D (blocker fix): SKIPS any row whose checkpoint is STILL pending — that row is
      * owned by a checkpoint-state-driven sweep (the SLA deny-sweep for human/irreversible_ask, or
      * failSuspendedWithExpiredCheckpoint once the checkpoint is expired). Without this guard, this time-based
      * UPDATE fired at the SAME instant as the deny-sweep (deadline == createdAt + ttl, both keyed on the TTL),
@@ -302,7 +302,7 @@ export declare class SqlRunStore {
      */
     reapSuspended(olderThanMs: number): Promise<number>;
     /**
-     * design/80 §3 inv#3 (crash-safe backstop — the run-row half of the checkpoint `terminal_at_ms` sweep): fail a
+     * [ref] §3 inv#3 (crash-safe backstop — the run-row half of the checkpoint `terminal_at_ms` sweep): fail a
      * suspended run whose durable checkpoint was ALREADY EXPIRED by `reapExpired` (past its `deadline` or its
      * absolute `terminal_at_ms`), and release its task_active (unlock the session). Runs UNCONDITIONALLY (no
      * approval-TTL gate), CHECKPOINT-STATE-driven not time-driven, so it aligns EXACTLY with the per-row

package/dist/plugins/scheduler-support.d.ts

@@ -10,7 +10,7 @@ type Result<T, E> = {
     ok: false;
     error: E;
 };
-/** Default caps (fail-closed bounds; design/105 §3.9). Override per deployment. */
+/** Default caps (fail-closed bounds; [ref] §3.9). Override per deployment. */
 export declare const DEFAULT_SCHEDULER_CAPS: {
     readonly supported: true;
     readonly maxScheduledPerScope: 32;

package/dist/plugins/send-user-file.d.ts

@@ -1,7 +1,7 @@
 /** SigV4 physical ceiling (AWS: X-Amz-Expires max 604800s = 7 days). */
 export declare const PRESIGN_MAX_TTL_SEC = 604800;
 /**
- * Multi-tenant governance (clay ruling 2026-07-14, blackboard [768]② variant a with a HASHED segment): every
+ * Multi-tenant governance (clay ruling 2026-07-14, blackboard [ref]② variant a with a HASHED segment): every
  * object key carries a per-tenant SCOPE SEGMENT so tenants can be listed/revoked by prefix on the store itself,
  * WITHOUT leaking the principal into the (user-visible, forwardable) URL. The segment is
  * `HMAC-SHA256(secretKey, "sendfile-scope:" + scope)` hex, truncated to 32 chars: