@sema-agent/client-core 0.77.1 → 0.77.2

package/dist/approvalsStreamLiveCapability.js

@@ -1,25 +1,8 @@
-/**
- * approvalsStreamLiveCapability — `GET /v1/capabilities.approvalsStreamLive`(server ≥7.87.1;sdk 9.7.1 `Capabilities.approvalsStreamLive?: boolean`)
- * 的三端共用读面(0.73.3;与 sql / writeProtection / webSearch.backend / executionLane 四只兄弟同一套四态词汇)。
- *
- * ── 这一位答的是哪一个问题 ────────────────────────────────────────────────────────────────
- * 「这台引擎会不会在 `approvals.stream` 上推流内 ask 的进出(`live_pending` / `live_resolved`)」= checkpointStore ∧ toolApproval。
- * 它决定 feed 消费方要不要**靠**推面:位为 true ⇒ 推面可靠,对账节拍(`ApprovalsFeedOptions.reconcile`)只是兜底;
- * 位为 false / 键缺席 / 从没观测 ⇒ 推面**不可靠或判不出**,对账节拍是悬挂 ask 的唯一拉面 —— **别等** `live_pending`。
- *
- * ── 🔴 读法 ─────────────────────────────────────────────────────────────────────────────────
- *  ① **键缺席 ≠ false**:老 server(<7.87.1)不报这一位 ⇒ `not_reported`(判不出),按「要拉」处理;折成 false 是替引擎断言「不推」。
- *  ② 严格布尔;`null` / 串 / 数 / 数组 / 对象 ⇒ 畸形(删格 ⇒ `unobserved`)。
- *  ③ 「要不要对账」的判据归包:{@link livePendingNeedsReconcile} —— 只有 present 且 true 才 false;其余一律 true(少查一次 = 一只等人的 ask 迟迟不出现)。
- */
 import { engineWireTarget } from './engineWireTarget.js';
 import { createEngineCapReader } from './engineCapReader.js';
-/** caps 回体 → 本格读数;畸形一律 `undefined`(= 这一格不写 ⇒ 读口答 `unobserved`)。 */
 export function projectApprovalsStreamLiveCapability(caps) {
     if (caps === null || typeof caps !== 'object')
         return undefined;
-    // 0.77.0 整族改齐:① 非对象 / 数组 caps 不是能力表 ⇒ 畸形(投影答 undefined ⇒ 删格 ⇒ 读口答 unobserved),不再答 not_reported
-    //    (那是把「取不到」冒充「报了但没提」);② 在场判据改 hasOwn —— 原型链上的同名键永远不会被序列化上 wire,读成在场 = 凭空造一格。
     if (caps === null || typeof caps !== 'object' || Array.isArray(caps))
         return undefined;
     if (!Object.hasOwn(caps, 'approvalsStreamLive'))
@@ -31,32 +14,20 @@ export function projectApprovalsStreamLiveCapability(caps) {
         return undefined;
     return { kind: 'present', live: v };
 }
-/**
- * 本格的 per-baseUrl 读账 + tee / 读口 / 失效口 / 测试钩四口 —— 各只能力位读器**共用同一份实现**
- * ({@link createEngineCapReader});本文件只留这一格真正不同的部分:投影函数 {@link projectApprovalsStreamLiveCapability}、doctor 措辞表,以及本位自己的判据助手(如有)。
- * 🔴 Map 在工厂闭包里,**一只读器一张**:收到读不懂的回体只删自己这一格,绝不连坐别的能力面。
- */
 const reader = createEngineCapReader({
     name: 'approvalsStreamLive',
     project: projectApprovalsStreamLiveCapability,
     makeUnobserved: () => ({ kind: 'unobserved' }),
 });
-/** 宿主 caps probe 的读面 tee 落点(与四只兄弟并列)。绝不 throw;畸形 ⇒ 删格;`opts.generation` 关掉旧探测覆盖新读数的竞态。 */
 export function noteEngineCapsForApprovalsStreamLive(baseUrl, caps, opts) {
     reader.note(baseUrl, caps, opts);
 }
-/** 本进程观测到的读数;这一格空缺 ⇒ `{kind:'unobserved'}`。 */
 export function observedApprovalsStreamLive(baseUrl = engineWireTarget()?.baseUrl) {
     return reader.observed(baseUrl);
 }
-/**
- * feed 消费方「要不要靠对账节拍拉悬挂 ask」的判据单源:只有引擎明说会推(present ∧ true)才 `false`;
- * 位为 false / 老 server 判不出 / 从没观测 ⇒ `true`。fail-safe 方向定在「查」(与 `shouldPoll` 同一条理由)。
- */
 export function livePendingNeedsReconcile(reading) {
     return !(reading.kind === 'present' && reading.live === true);
 }
-/** doctor 那一行的 detail 串,唯一措辞真源。🔴 `not_reported` 句不许暗示「不推」。 */
 export function approvalsStreamLiveDoctorDetail(reading) {
     switch (reading.kind) {
         case 'unobserved':
@@ -69,11 +40,9 @@ export function approvalsStreamLiveDoctorDetail(reading) {
                 : 'live approval push off on this deployment (no checkpoint store or tool approvals disabled) — suspended asks are only visible through the reconcile cadence, so the client polls for them';
     }
 }
-/** 换代失效口(引擎温切成功后调):清成未观测。空串 ⇒ no-op;绝不 throw。 */
 export function forgetApprovalsStreamLiveReading(baseUrl) {
     reader.forget(baseUrl);
 }
-/** 测试钩子。 */
 export function __resetApprovalsStreamLiveReadingsForTests() {
     reader.__resetForTests();
 }

package/dist/argvFlagValue.d.ts

@@ -1,41 +1,8 @@
-/**
- * src/argvFlagValue.ts — shared CC/commander-style "last flag value" argv-scan primitive
- * (REF-CC-143 / REF-CC-dup-07, P3 wave1 卡C-argv, 2026-08-01;缺值策略位补于 wave1 回炉,
- * blocker 修复,同日).
- *
- * Five call sites (limitsWire / sandboxWire / scenarioWire / headlessPermissionModeWire —
- * interactiveToolsWire's own copy folds away entirely per REF-CC-dup-10, delegating to
- * headlessPermissionModeWire instead) each hand-rolled the identical loop: scan everything
- * before a bare `--` (positionals are never flags), accept both `--name <v>` and `--name=<v>`
- * forms, repeated flag ⇒ LAST wins (commander convention).
- *
- * 缺值策略(收编口径,`onMissingValue` 显式位):当某一次 occurrence 的值缺席/长得像另一个 flag
- * 时,这个共用叶提供两种可命名的处置——**调用方选,不由本叶替调用方决定**:
- *   · `'invalidate'`(缺省,limitsWire/sandboxWire/scenarioWire 用这个):那次缺值让整个旗的最终
- *     取值塌缩成「有旗、无值」(`{present:true}`,raw 缺席)——与这三处一直以来的 fail-LOUD 立场
- *     一致:重复旗严格 LAST occurrence 定生死,哪怕最后一次是缺值也不会回落到更早的合法值。
- *   · `'latch-previous'`(headlessPermissionModeWire 用这个):那次缺值被当作「这次 occurrence 没
- *     提供新信息」,直接跳过,锁存(latch)住之前已经取到的合法值不动——这是收编前那份手写循环
- *     的原语义(`if (typeof v === 'string' && !v.startsWith('-')) { mode = v }`,缺值分支从不碰
- *     `mode`),收编成共用叶不能悄悄把它改造成 invalidate 语义。
- * 两种策略都遵守同一条不变量:**从未出现过合法值** ⇒ 恒回 `{present:true}`(raw 缺席),从不
- * 编造一个值;调用方各自决定「有旗无值」之后怎么办(fail-loud 用法提示,或落到下一车道)。
- */
-/** `lastFlagValue` 的判别式返回型(非法组合 `{present:false, raw:'x'}` 在类型层就不可构造)。 */
 export type FlagValue = {
     present: false;
 } | {
     present: true;
     raw?: string;
 };
-/** 缺值(occurrence 存在但值缺席/长得像另一个 flag)时的处置策略——见上方模块 doc。 */
 export type OnMissingFlagValue = 'invalidate' | 'latch-previous';
-/**
- * Pull the LAST value of a `--name <v>` / `--name=<v>` flag out of an argv slice (everything
- * before a bare `--` — positionals are never flags). Returns:
- *   {present:false}                 — flag absent
- *   {present:true, raw}             — flag present with a value token (possibly empty string)
- *   {present:true, raw:undefined}   — flag present but no value was ever captured (see
- *                                      `onMissingValue` for what "captured" means across repeats)
- */
 export declare function lastFlagValue(argv: readonly string[], name: string, onMissingValue?: OnMissingFlagValue): FlagValue;

package/dist/argvFlagValue.js

@@ -1,34 +1,3 @@
-/**
- * src/argvFlagValue.ts — shared CC/commander-style "last flag value" argv-scan primitive
- * (REF-CC-143 / REF-CC-dup-07, P3 wave1 卡C-argv, 2026-08-01;缺值策略位补于 wave1 回炉,
- * blocker 修复,同日).
- *
- * Five call sites (limitsWire / sandboxWire / scenarioWire / headlessPermissionModeWire —
- * interactiveToolsWire's own copy folds away entirely per REF-CC-dup-10, delegating to
- * headlessPermissionModeWire instead) each hand-rolled the identical loop: scan everything
- * before a bare `--` (positionals are never flags), accept both `--name <v>` and `--name=<v>`
- * forms, repeated flag ⇒ LAST wins (commander convention).
- *
- * 缺值策略(收编口径,`onMissingValue` 显式位):当某一次 occurrence 的值缺席/长得像另一个 flag
- * 时,这个共用叶提供两种可命名的处置——**调用方选,不由本叶替调用方决定**:
- *   · `'invalidate'`(缺省,limitsWire/sandboxWire/scenarioWire 用这个):那次缺值让整个旗的最终
- *     取值塌缩成「有旗、无值」(`{present:true}`,raw 缺席)——与这三处一直以来的 fail-LOUD 立场
- *     一致:重复旗严格 LAST occurrence 定生死,哪怕最后一次是缺值也不会回落到更早的合法值。
- *   · `'latch-previous'`(headlessPermissionModeWire 用这个):那次缺值被当作「这次 occurrence 没
- *     提供新信息」,直接跳过,锁存(latch)住之前已经取到的合法值不动——这是收编前那份手写循环
- *     的原语义(`if (typeof v === 'string' && !v.startsWith('-')) { mode = v }`,缺值分支从不碰
- *     `mode`),收编成共用叶不能悄悄把它改造成 invalidate 语义。
- * 两种策略都遵守同一条不变量:**从未出现过合法值** ⇒ 恒回 `{present:true}`(raw 缺席),从不
- * 编造一个值;调用方各自决定「有旗无值」之后怎么办(fail-loud 用法提示,或落到下一车道)。
- */
-/**
- * Pull the LAST value of a `--name <v>` / `--name=<v>` flag out of an argv slice (everything
- * before a bare `--` — positionals are never flags). Returns:
- *   {present:false}                 — flag absent
- *   {present:true, raw}             — flag present with a value token (possibly empty string)
- *   {present:true, raw:undefined}   — flag present but no value was ever captured (see
- *                                      `onMissingValue` for what "captured" means across repeats)
- */
 export function lastFlagValue(argv, name, onMissingValue = 'invalidate') {
     const eq = `${name}=`;
     let present = false;
@@ -39,21 +8,20 @@ export function lastFlagValue(argv, name, onMissingValue = 'invalidate') {
         if (a === undefined)
             continue;
         if (a === '--')
-            break; // positionals — never flags
+            break;
         if (a === name) {
             present = true;
             const nxt = argv[i + 1];
             if (nxt === undefined || nxt.startsWith('-')) {
-                // a value that LOOKS like another flag (or is plain missing) is not a value.
                 if (onMissingValue === 'latch-previous')
-                    continue; // keep whatever raw/valueMissing already hold
+                    continue;
                 valueMissing = true;
                 raw = undefined;
                 continue;
             }
             valueMissing = false;
             raw = nxt;
-            i++; // consume the value token
+            i++;
         }
         else if (a.startsWith(eq)) {
             present = true;

package/dist/attachmentsWireCaps.d.ts

@@ -1,146 +1,19 @@
-/**
- * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/attachmentsWireCaps.ts 逐字搬入(零依赖)。
- */
-/**
- * src/sema/attachmentsWireCaps.ts — design/133 + G1 turn-boundary attachments WIRE pure-projection:
- * the shell's intent → the top-level `TaskRequest.attachments` object the service normalizes
- * (spec-fields.ts normalizeAttachments) → core `TaskSpec.attachments`.
- *
- * DEFAULT ON for the TOC live path ([487]② — CC parity): CC's own /compact announces the still
- * pending/running background tasks after compaction and notices newly-available deferred tools at
- * boundaries — a TOC user gets that behavior without flipping anything. The default therefore
- * carries the G1 announce pair `{backgroundTasks, toolsDelta}`:
- *   - both are ONE-SHOT/quiet engine-side (no compaction ⇒ backgroundTasks permanently silent; no
- *     deferred-tool materialization ⇒ toolsDelta permanently silent), so the default costs nothing
- *     on an ordinary session;
- *   - the design/133 reminder trio (todoReminder/changedFiles/planModeReminder) stays OPT-IN
- *     (`SEMA_ATTACHMENTS=full`) — core's own default-face judgment (evidence from autonomous legs
- *     only; interactive deployments stay byte-identical) is respected until a behavior leg says
- *     otherwise.
- *
- * ══ 🔴 FIX⑤(2026-08-07)—— 这个字段下面其实躺着**两族契约**,此前只实现了一族 ═══════════════
- *
- * 契约真源 = `@sema-agent/sdk` `types.d.ts` 的 `TaskRequest.attachments`(6.3.0 起 10 键)。
- * 两族的「关」是两种**不同**的动作,混为一谈就必然有一族关不掉:
- *
- *  ① **literal-true 族**(7 员:todoReminder / changedFiles / planModeReminder / budgetUsd /
- *     backgroundTasks / toolsDelta / mcpInstructions,外加取值型的 todoReminderMode):
- *     引擎侧默认**关**,键在场即开。板 [479] ask-2 的原话是「off = DELETE the key, never send
- *     false」—— 对这一族,发 `false` 是违约(核心根本没有「显式关」这个语义位),所以本模块对
- *     它们**永不产出 false**:OFF ⇒ 键不出现。
- *
- *  ② **explicit-false 族**(3 员:agentListing / skillsListing / **backgroundTasks**):
- *     它们在 core 里是 **DEFAULT-ON**,SDK 头注写死「`agentListing`/`skillsListing` 是 core
- *     DEFAULT-ON —— **explicit false 才关**(1.254 起 false 真透传;更老 server 静默丢)」。
- *     于是「删键」在这一族上的含义是**保持开着**,而不是关掉。旧的 `AttachmentsSpec` 把全部键
- *     钉成 `?: true`,literal 类型层面就表达不出 `false` ⇒ 这两个 DEFAULT-ON 的附件**没有任何
- *     路径可以关闭**(不是「难关」,是类型层封死)。本批把这两键的类型放宽成 `boolean` 并给出
- *     产出 `false` 的路径。
- *
- * ══ 🔴 [4982] 候选①(P0-KPI,0.42.0)—— **第三员漏族:`backgroundTasks`** ════════════════════
- *
- * core **5.12.0 (BREAKING)** 把 `attachments.backgroundTasks` 与 `agentListing`/`skillsListing`
- * **同批**翻成 DEFAULT-ON(core `types.d.ts` 逐字:「Post-compact background-task restatement —
- * DEFAULT ON since 5.12.0 (**boolean, not `true`**: explicit `false` is the opt-out; **same contract
- * as the listing family below**)」)。三兄弟同批翻转,本模块**跟修了后两个、漏了第一个** ——
- * `backgroundTasks` 一直留在 ① 族(off = 删键,永不发 false)。
- * 后果是这个旋钮上最坏的一种失效:`SEMA_ATTACHMENTS=off`(文件自称「真·全关」)对这一位与
- * **什么都不配**逐字节同效(两条路都不发这个键 = 都是「开」),**且零报错** —— 用户以为关掉了,
- * 附件照进上下文,没有任何一处会说出来。与 ② 族当初那个洞是同一个病形的第三例。
- *
- * ── 修法:把「能不能显式打开」与「能不能显式关掉」拆成**两条正交的轴** ────────────────────────
- * `backgroundTasks` 同时住两族,这不是分类含糊,这**就是**它的契约:
- *   · **轴 A(可显式开)** = `full` 会全开的那 7 员 —— `backgroundTasks` 在内,**membership 不动**;
- *   · **轴 B(可显式关)** = core DEFAULT-ON 的 3 员 —— `backgroundTasks` 新入。
- * 只把它整个搬进 ② 族(= 从轴 A 里删掉)是**错的修法**,两条理由都是硬的:
- *   ① `full` / `default` / `+backgroundTasks` 三条既有路会当场少发一个 `backgroundTasks: true`
- *      —— 对 core ≥5.12.0 行为等价(默认就是开),但对**更老引擎**那是真的从「开」变成「关」,
- *      而本模块手里没有 server 版本这个量(见下面 §能力边界),没资格替用户做那个降级;
- *   ② 空 env 的默认产出 `{backgroundTasks: true, toolsDelta: true}` 是 [487]② CC-parity 那一对的
- *      字面承诺,删掉它就是把「默认逐字节不变」这条本模块的立身纪律自己破了。
- * ⇒ 本批**只加一条出路**(`off` 与 `-backgroundTasks` 产出 `false`),其余取值逐字节不变。
- *
- * ── env 面(`SEMA_ATTACHMENTS`)的取值语法,以及为什么选这一种 ────────────────────────────────
- * 目标是「**默认行为逐字节不变** + 有路可关 DEFAULT-ON 两键」,所以选了**在既有值上加逗号 token
- * 列表**,而不是新开一个 env:
- *   · 新开一个 env(如 `SEMA_ATTACHMENTS_OFF`)会让「附件面怎么配」有两个入口,而两个入口之间的
- *     优先级又要再定义一次 —— 这类第二真源正是本仓反复登记的病族;
- *   · 逗号 token 列表对**存量取值零影响**:`unset` / `full` / `all` / off 拼法四种老写法解析结果
- *     逐字节不变(FIX7 段 ⑤ 有正面钉),新语法只在用户真写了逗号 token 时才被触发。
- * 语法(逗号分隔,大小写不敏感,允许空白):
- *   · `off|0|false|no|none`(整值)     ⇒ **真·全关**:只可显式开的那一族一个不发(它们的 off 就是
- *                                        删键)+ DEFAULT-ON **三键**(agentListing / skillsListing /
- *                                        backgroundTasks)发 `false`。
- *     🔴 对抗复审 [medium](2026-08-07)判的真病:这一支此前直接 `return undefined`(不发字段),
- *     而「不发字段」对 DEFAULT-ON 两键的含义**恰恰是保持开着** —— 一个叫 off 的总开关关不掉十件里
- *     的两件,且用户没有任何办法察觉。旧行为在 <1.254 的 server 上与新行为**逐字节等价**(那些
- *     server 静默丢 false),在 ≥1.254 上新行为才第一次兑现这个旋钮的字面承诺。
- *     ⚠️ **能力边界说清楚**(对抗复审二轮):本模块是**纯 env→spec 投影**,手里没有 server
- *     版本/capability 这个量,所以对 <1.254 的部署它兑现不了「全关」—— 那两键仍会默认开着,而
- *     壳侧无从察觉。补这个洞的正位在**请求装配层**(按已探到的 capability 判,与 limitsWire 的
- *     两道地板同族),已记进 docs/refactor/README.md 的宿主/上游工单表。本层只保证两件:
- *     ① 新行为在任何 server 代际上都**不比旧行为差**(旧行为在所有代际上都关不掉那两键);
- *     ② 不在自己的能力之外说大话 —— 所以上面那句「真·全关」的适用范围就是 ≥1.254。
- *   · `full` / `all`                   ⇒ literal-true 族 7 员全开(**不含** DEFAULT-ON 两键 ——
- *                                        不发 = 保持 core 默认开,壳不替 core 做那个决定)
- *   · `default`                        ⇒ CC-parity 那一对(显式写出「默认」这个意思)
- *   · `<key>` / `+<key>`               ⇒ 单点打开一个「可显式开」族成员(轴 A 的 7 员)
- *   · `-agentListing` / `-skillsListing` / `-backgroundTasks` ⇒ 产出 **`false`**(DEFAULT-ON 三键
- *                                        唯一的关法;`-backgroundTasks` 是 [4982] 候选① 补的那条)
- *   · `todoReminderMode=baseline|off`  ⇒ 取值型键
- * 🔴 未登记 token / 对 literal-true 族用 `-` / todoReminderMode 取闭集外的值 ⇒ **fail-loud 抛错**。
- *    静默忽略是这条链上最坏的失效形:用户以为自己关掉了 agentListing,而请求照发、附件照进上下文,
- *    并且没有任何一处会说出来。
- *
- * PURE — no env/file IO of its own (callers pass `env`), the verified wireCaps pattern. The CALLER
- * (seamQuery / the print-mode ask) gates the read to LIVE mode so the mock request shape never
- * changes.
- */
 import { type EnvLike } from './hostEnv.js';
-/** The env key the shell reads. 取值语法见文件头注 §env。 */
 export declare const ATTACHMENTS_ENV: "SEMA_ATTACHMENTS";
-/**
- * Mirror of `@sema-agent/sdk` `TaskRequest.attachments`(6.3.0,`types.d.ts`)—— **10 键全镜像**。
- * 两族的类型形不同,而这个不同**就是**契约本身(见文件头注):literal-true 族只能是 `true`
- * (发 `false` 违约),DEFAULT-ON 两族是 `boolean`(`false` 才是它们的关)。
- */
 export interface AttachmentsSpec {
     todoReminder?: true;
-    /** 取值型:`"baseline"` | `"off"`(缺席 = 引擎默认)。 */
     todoReminderMode?: 'baseline' | 'off';
     changedFiles?: true | {
         maxFiles?: number;
     };
     planModeReminder?: true;
     budgetUsd?: true;
-    /**
-     * 🔴 **两族兼属**([4982] 候选①,0.42.0):它在轴 A(`full` 会开)也在轴 B(core ≥5.12.0
-     * DEFAULT-ON,`false` 才是关)。类型因此是 `boolean` 而不是 `true` —— 钉成 `true` 正是
-     * 「关不掉」那个洞的类型层根因。
-     */
     backgroundTasks?: boolean;
     toolsDelta?: true;
     mcpInstructions?: true;
     agentListing?: boolean;
     skillsListing?: boolean;
 }
-/** 键面台账(机读位):加键必须同批登记,否则下方 `Covers` 双向钉编译红。 */
 export declare const ATTACHMENTS_SPEC_KEYS: readonly ["todoReminder", "todoReminderMode", "changedFiles", "planModeReminder", "budgetUsd", "backgroundTasks", "toolsDelta", "mcpInstructions", "agentListing", "skillsListing"];
-/**
- * **轴 B —— 可显式关**(core DEFAULT-ON,`false` 才是关;`-<key>` 与总开关 `off` 的作用面)。
- * 🔴 [4982] 候选①(0.42.0):`backgroundTasks` 补入 —— core 5.12.0 与另两员**同批**翻 DEFAULT-ON,
- *    本模块当时只跟修了两员。这张表**不是** ① 族的补集(`backgroundTasks` 两族兼属,见 AttachmentsSpec
- *    上的键注与文件头注的「两条正交的轴」段)。
- */
 export declare const ATTACHMENTS_DEFAULT_ON_KEYS: readonly ["agentListing", "skillsListing", "backgroundTasks"];
-/**
- * ENV source → the `TaskRequest.attachments` stamp.
- *
- * 恒返回一个对象:literal-true 族永远只出现 `true`(core 契约:off = 删键),而
- * `agentListing`/`skillsListing` 只在被显式关掉时出现,值恒为 `false`(它们的 core 默认是开,
- * 不发 = 不动那个默认)。返回型保留 `| undefined` 是给未来留位,今天没有分支产出它。
- *
- * @throws 未登记 token / 对 literal-true 族用 `-` / todoReminderMode 取闭集外的值(fail-loud:
- *         静默忽略会让「我明明关了」与「它其实还开着」同时为真)。
- */
 export declare function attachmentsForRequest(env?: EnvLike): AttachmentsSpec | undefined;

package/dist/attachmentsWireCaps.js

@@ -1,106 +1,6 @@
-/**
- * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/attachmentsWireCaps.ts 逐字搬入(零依赖)。
- */
-/**
- * src/sema/attachmentsWireCaps.ts — design/133 + G1 turn-boundary attachments WIRE pure-projection:
- * the shell's intent → the top-level `TaskRequest.attachments` object the service normalizes
- * (spec-fields.ts normalizeAttachments) → core `TaskSpec.attachments`.
- *
- * DEFAULT ON for the TOC live path ([487]② — CC parity): CC's own /compact announces the still
- * pending/running background tasks after compaction and notices newly-available deferred tools at
- * boundaries — a TOC user gets that behavior without flipping anything. The default therefore
- * carries the G1 announce pair `{backgroundTasks, toolsDelta}`:
- *   - both are ONE-SHOT/quiet engine-side (no compaction ⇒ backgroundTasks permanently silent; no
- *     deferred-tool materialization ⇒ toolsDelta permanently silent), so the default costs nothing
- *     on an ordinary session;
- *   - the design/133 reminder trio (todoReminder/changedFiles/planModeReminder) stays OPT-IN
- *     (`SEMA_ATTACHMENTS=full`) — core's own default-face judgment (evidence from autonomous legs
- *     only; interactive deployments stay byte-identical) is respected until a behavior leg says
- *     otherwise.
- *
- * ══ 🔴 FIX⑤(2026-08-07)—— 这个字段下面其实躺着**两族契约**,此前只实现了一族 ═══════════════
- *
- * 契约真源 = `@sema-agent/sdk` `types.d.ts` 的 `TaskRequest.attachments`(6.3.0 起 10 键)。
- * 两族的「关」是两种**不同**的动作,混为一谈就必然有一族关不掉:
- *
- *  ① **literal-true 族**(7 员:todoReminder / changedFiles / planModeReminder / budgetUsd /
- *     backgroundTasks / toolsDelta / mcpInstructions,外加取值型的 todoReminderMode):
- *     引擎侧默认**关**,键在场即开。板 [479] ask-2 的原话是「off = DELETE the key, never send
- *     false」—— 对这一族,发 `false` 是违约(核心根本没有「显式关」这个语义位),所以本模块对
- *     它们**永不产出 false**:OFF ⇒ 键不出现。
- *
- *  ② **explicit-false 族**(3 员:agentListing / skillsListing / **backgroundTasks**):
- *     它们在 core 里是 **DEFAULT-ON**,SDK 头注写死「`agentListing`/`skillsListing` 是 core
- *     DEFAULT-ON —— **explicit false 才关**(1.254 起 false 真透传;更老 server 静默丢)」。
- *     于是「删键」在这一族上的含义是**保持开着**,而不是关掉。旧的 `AttachmentsSpec` 把全部键
- *     钉成 `?: true`,literal 类型层面就表达不出 `false` ⇒ 这两个 DEFAULT-ON 的附件**没有任何
- *     路径可以关闭**(不是「难关」,是类型层封死)。本批把这两键的类型放宽成 `boolean` 并给出
- *     产出 `false` 的路径。
- *
- * ══ 🔴 [4982] 候选①(P0-KPI,0.42.0)—— **第三员漏族:`backgroundTasks`** ════════════════════
- *
- * core **5.12.0 (BREAKING)** 把 `attachments.backgroundTasks` 与 `agentListing`/`skillsListing`
- * **同批**翻成 DEFAULT-ON(core `types.d.ts` 逐字:「Post-compact background-task restatement —
- * DEFAULT ON since 5.12.0 (**boolean, not `true`**: explicit `false` is the opt-out; **same contract
- * as the listing family below**)」)。三兄弟同批翻转,本模块**跟修了后两个、漏了第一个** ——
- * `backgroundTasks` 一直留在 ① 族(off = 删键,永不发 false)。
- * 后果是这个旋钮上最坏的一种失效:`SEMA_ATTACHMENTS=off`(文件自称「真·全关」)对这一位与
- * **什么都不配**逐字节同效(两条路都不发这个键 = 都是「开」),**且零报错** —— 用户以为关掉了,
- * 附件照进上下文,没有任何一处会说出来。与 ② 族当初那个洞是同一个病形的第三例。
- *
- * ── 修法:把「能不能显式打开」与「能不能显式关掉」拆成**两条正交的轴** ────────────────────────
- * `backgroundTasks` 同时住两族,这不是分类含糊,这**就是**它的契约:
- *   · **轴 A(可显式开)** = `full` 会全开的那 7 员 —— `backgroundTasks` 在内,**membership 不动**;
- *   · **轴 B(可显式关)** = core DEFAULT-ON 的 3 员 —— `backgroundTasks` 新入。
- * 只把它整个搬进 ② 族(= 从轴 A 里删掉)是**错的修法**,两条理由都是硬的:
- *   ① `full` / `default` / `+backgroundTasks` 三条既有路会当场少发一个 `backgroundTasks: true`
- *      —— 对 core ≥5.12.0 行为等价(默认就是开),但对**更老引擎**那是真的从「开」变成「关」,
- *      而本模块手里没有 server 版本这个量(见下面 §能力边界),没资格替用户做那个降级;
- *   ② 空 env 的默认产出 `{backgroundTasks: true, toolsDelta: true}` 是 [487]② CC-parity 那一对的
- *      字面承诺,删掉它就是把「默认逐字节不变」这条本模块的立身纪律自己破了。
- * ⇒ 本批**只加一条出路**(`off` 与 `-backgroundTasks` 产出 `false`),其余取值逐字节不变。
- *
- * ── env 面(`SEMA_ATTACHMENTS`)的取值语法,以及为什么选这一种 ────────────────────────────────
- * 目标是「**默认行为逐字节不变** + 有路可关 DEFAULT-ON 两键」,所以选了**在既有值上加逗号 token
- * 列表**,而不是新开一个 env:
- *   · 新开一个 env(如 `SEMA_ATTACHMENTS_OFF`)会让「附件面怎么配」有两个入口,而两个入口之间的
- *     优先级又要再定义一次 —— 这类第二真源正是本仓反复登记的病族;
- *   · 逗号 token 列表对**存量取值零影响**:`unset` / `full` / `all` / off 拼法四种老写法解析结果
- *     逐字节不变(FIX7 段 ⑤ 有正面钉),新语法只在用户真写了逗号 token 时才被触发。
- * 语法(逗号分隔,大小写不敏感,允许空白):
- *   · `off|0|false|no|none`(整值)     ⇒ **真·全关**:只可显式开的那一族一个不发(它们的 off 就是
- *                                        删键)+ DEFAULT-ON **三键**(agentListing / skillsListing /
- *                                        backgroundTasks)发 `false`。
- *     🔴 对抗复审 [medium](2026-08-07)判的真病:这一支此前直接 `return undefined`(不发字段),
- *     而「不发字段」对 DEFAULT-ON 两键的含义**恰恰是保持开着** —— 一个叫 off 的总开关关不掉十件里
- *     的两件,且用户没有任何办法察觉。旧行为在 <1.254 的 server 上与新行为**逐字节等价**(那些
- *     server 静默丢 false),在 ≥1.254 上新行为才第一次兑现这个旋钮的字面承诺。
- *     ⚠️ **能力边界说清楚**(对抗复审二轮):本模块是**纯 env→spec 投影**,手里没有 server
- *     版本/capability 这个量,所以对 <1.254 的部署它兑现不了「全关」—— 那两键仍会默认开着,而
- *     壳侧无从察觉。补这个洞的正位在**请求装配层**(按已探到的 capability 判,与 limitsWire 的
- *     两道地板同族),已记进 docs/refactor/README.md 的宿主/上游工单表。本层只保证两件:
- *     ① 新行为在任何 server 代际上都**不比旧行为差**(旧行为在所有代际上都关不掉那两键);
- *     ② 不在自己的能力之外说大话 —— 所以上面那句「真·全关」的适用范围就是 ≥1.254。
- *   · `full` / `all`                   ⇒ literal-true 族 7 员全开(**不含** DEFAULT-ON 两键 ——
- *                                        不发 = 保持 core 默认开,壳不替 core 做那个决定)
- *   · `default`                        ⇒ CC-parity 那一对(显式写出「默认」这个意思)
- *   · `<key>` / `+<key>`               ⇒ 单点打开一个「可显式开」族成员(轴 A 的 7 员)
- *   · `-agentListing` / `-skillsListing` / `-backgroundTasks` ⇒ 产出 **`false`**(DEFAULT-ON 三键
- *                                        唯一的关法;`-backgroundTasks` 是 [4982] 候选① 补的那条)
- *   · `todoReminderMode=baseline|off`  ⇒ 取值型键
- * 🔴 未登记 token / 对 literal-true 族用 `-` / todoReminderMode 取闭集外的值 ⇒ **fail-loud 抛错**。
- *    静默忽略是这条链上最坏的失效形:用户以为自己关掉了 agentListing,而请求照发、附件照进上下文,
- *    并且没有任何一处会说出来。
- *
- * PURE — no env/file IO of its own (callers pass `env`), the verified wireCaps pattern. The CALLER
- * (seamQuery / the print-mode ask) gates the read to LIVE mode so the mock request shape never
- * changes.
- */
 import { hostEnv } from './hostEnv.js';
 import { envFlagOff } from './envFlag.js';
-/** The env key the shell reads. 取值语法见文件头注 §env。 */
 export const ATTACHMENTS_ENV = 'SEMA_ATTACHMENTS';
-/** 键面台账(机读位):加键必须同批登记,否则下方 `Covers` 双向钉编译红。 */
 export const ATTACHMENTS_SPEC_KEYS = [
     'todoReminder',
     'todoReminderMode',
@@ -113,19 +13,7 @@ export const ATTACHMENTS_SPEC_KEYS = [
     'agentListing',
     'skillsListing',
 ];
-/**
- * **轴 B —— 可显式关**(core DEFAULT-ON,`false` 才是关;`-<key>` 与总开关 `off` 的作用面)。
- * 🔴 [4982] 候选①(0.42.0):`backgroundTasks` 补入 —— core 5.12.0 与另两员**同批**翻 DEFAULT-ON,
- *    本模块当时只跟修了两员。这张表**不是** ① 族的补集(`backgroundTasks` 两族兼属,见 AttachmentsSpec
- *    上的键注与文件头注的「两条正交的轴」段)。
- */
 export const ATTACHMENTS_DEFAULT_ON_KEYS = ['agentListing', 'skillsListing', 'backgroundTasks'];
-/**
- * **轴 A —— 可显式开**:`full` 会全开的那 7 员(`todoReminderMode` 是取值型,不搭 full 的车)。
- * 🔴 `backgroundTasks` **留在本表**([4982] 候选① 的取舍,理由见文件头注):把它从这里删掉会让
- *    `full`/`default`/`+backgroundTasks` 三条既有路少发一个 `true`,对 core <5.12.0 是真的从
- *    「开」变成「关」,而本模块手里没有 server 版本这个量。
- */
 const OPT_IN_KEYS = [
     'todoReminder',
     'changedFiles',
@@ -135,47 +23,25 @@ const OPT_IN_KEYS = [
     'toolsDelta',
     'mcpInstructions',
 ];
-/**
- * **只可显式关、不可显式开**的那两员(轴 B ∖ 轴 A)。`+agentListing` 这类写法的 fail-loud 判据
- * 锚在**本表**而不是整个轴 B —— 锚轴 B 会把 `+backgroundTasks` / `full` 一起误拒([4982] 候选①
- * 修复批的判别力所在:两条轴各判各的,不许拿一条去代另一条)。
- */
 const DEFAULT_ON_ONLY_KEYS = ['agentListing', 'skillsListing'];
-/** CC-parity 默认对(TOC live 路径,[487]②)。 */
 const DEFAULT_PAIR = ['backgroundTasks', 'toolsDelta'];
 const _attachmentsKeyPins = [true, true, true, true, true, true];
 void _attachmentsKeyPins;
 const TODO_REMINDER_MODES = ['baseline', 'off'];
-/** fail-loud 的统一措辞:说清**哪个 token 坏了**、以及合法形是什么(判词要指得出下一步)。 */
 function refuse(token, why) {
     throw new Error(`${ATTACHMENTS_ENV}: refusing token "${token}" — ${why}. ` +
         `Legal tokens: off | full | all | default | <literalTrueKey> | +<literalTrueKey> | ` +
         `-agentListing | -skillsListing | todoReminderMode=baseline|off`);
 }
-/**
- * ENV source → the `TaskRequest.attachments` stamp.
- *
- * 恒返回一个对象:literal-true 族永远只出现 `true`(core 契约:off = 删键),而
- * `agentListing`/`skillsListing` 只在被显式关掉时出现,值恒为 `false`(它们的 core 默认是开,
- * 不发 = 不动那个默认)。返回型保留 `| undefined` 是给未来留位,今天没有分支产出它。
- *
- * @throws 未登记 token / 对 literal-true 族用 `-` / todoReminderMode 取闭集外的值(fail-loud:
- *         静默忽略会让「我明明关了」与「它其实还开着」同时为真)。
- */
 export function attachmentsForRequest(env = hostEnv()) {
     const raw = (env[ATTACHMENTS_ENV] ?? '').trim().toLowerCase();
-    // 总开关 off = 真·全关(见文件头注 §env 的 复审 [medium] 登记),不是「不发字段」。
     if (envFlagOff(raw))
         return allDefaultOnOff();
     const tokens = raw.split(',').map(t => t.trim()).filter(t => t.length > 0);
-    // 存量取值零变化:空 / `full` / `all` 单 token 走与本批之前逐字节相同的两条老路。
     if (tokens.length === 0)
         return { backgroundTasks: true, toolsDelta: true };
     if (tokens.length === 1 && (tokens[0] === 'full' || tokens[0] === 'all'))
         return allLiteralTrue();
-    // 单 token 且不是任何已登记词 ⇒ 维持历史语义(「unset/anything else ⇒ 默认对」),不 fail-loud:
-    // 那是本模块自建起就写在头注里的契约,收紧它属于行为面改动,不在本批。多 token 形是**本批新增
-    // 的语法**,没有存量语义可破,所以它逐 token fail-loud。
     if (tokens.length === 1 && !isKnownToken(tokens[0])) {
         return { backgroundTasks: true, toolsDelta: true };
     }
@@ -215,9 +81,6 @@ export function attachmentsForRequest(env = hostEnv()) {
         const key = canonicalKey(lhs.startsWith('+') ? lhs.slice(1) : lhs);
         if (key === undefined)
             refuse(token, 'unknown attachments key');
-        // 🔴 判据锚 `DEFAULT_ON_ONLY_KEYS`(轴 B ∖ 轴 A),**不是**整个轴 B:0.42.0 起
-        //    `backgroundTasks` 两族兼属,拿轴 B 判会把 `+backgroundTasks` 一起误拒(而它在
-        //    `full` 里本来就开得出来,拒它等于同一件事有两个答案)。
         if (isDefaultOnOnlyKey(key)) {
             refuse(token, `"${key}" is core DEFAULT-ON — turning it "on" is a no-op that would send a redundant true; ` +
                 `use "-${key}" to turn it OFF`);
@@ -228,8 +91,6 @@ export function attachmentsForRequest(env = hostEnv()) {
     }
     return spec;
 }
-/** 总开关 off 的产出:只可显式开的那族一个不发(删键即关)+ DEFAULT-ON **三键**显式 `false`
- *  ([4982] 候选①:`backgroundTasks` 从 0.42.0 起真的在这条路上被关掉)。 */
 function allDefaultOnOff() {
     const out = {};
     for (const k of ATTACHMENTS_DEFAULT_ON_KEYS)
@@ -242,24 +103,19 @@ function allLiteralTrue() {
         out[k] = true;
     return out;
 }
-/** `k=v` 的一次拆分(值里再有 `=` 一律归右侧,交给取值校验去拒)。 */
 function splitAssign(token) {
     const i = token.indexOf('=');
     return i < 0 ? [token, undefined] : [token.slice(0, i).trim(), token.slice(i + 1).trim()];
 }
-/** 大小写不敏感的键名归一(env 值整体已 lowercase,而键名是 camelCase)。 */
 function canonicalKey(lower) {
     return ATTACHMENTS_SPEC_KEYS.find(k => k.toLowerCase() === lower);
 }
-/** 轴 B:可显式关(`-<key>` 的合法作用面)。 */
 function isDefaultOnKey(k) {
     return ATTACHMENTS_DEFAULT_ON_KEYS.includes(k);
 }
-/** 轴 B ∖ 轴 A:只可关不可开(`+<key>` 的 fail-loud 作用面)。 */
 function isDefaultOnOnlyKey(k) {
     return DEFAULT_ON_ONLY_KEYS.includes(k);
 }
-/** 单 token 形的历史回落判据(见 `attachmentsForRequest` 里那段注释)。 */
 function isKnownToken(token) {
     if (token === 'full' || token === 'all' || token === 'default')
         return true;