@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/sandboxWire.d.ts

@@ -13,52 +13,14 @@ export type SandboxParseResult = {
     ok: false;
     error: string;
 };
-/**
- * Parse `--sandbox` out of an argv slice (everything before a bare `--`; both `--sandbox <v>` and
- * `--sandbox=<v>` forms). No flag ⇒ `{mode:'default'}`. Repeated flag ⇒ LAST wins (commander convention).
- * Missing value / flag-shaped value / empty / over-long ⇒ fail-LOUD parse error (never a silent default —
- * a mis-typed environment choice must not quietly run on the wrong image).
- *
- * 🔴 [2393] sweep-F10(2026-08-03 全窗复审)**承诺范围如实收窄**(裁定:行为不改,话改):
- * 「fail-LOUD,never a silent default」这句话现在**不**覆盖一种输入 —— 同一个旗**重复出现**且
- * 前一次缺值/非法、后一次合法(`--sandbox --sandbox foo`):
- * 收编前是 per-occurrence eager validate,在**第一个**缺值 occurrence 上就 fail-loud;收编后走
- * `lastFlagValue`('invalidate' 缺省)= 后一次合法 occurrence 覆盖前一次,整体接受。
- * 为什么裁定不改回去:本模块自己写着的契约就是「Repeated flag ⇒ LAST wins(commander convention)」,
- * eager-validate 违反的正是这条契约(它让**被覆盖掉的**那一次决定整条命令的成败)。
- * 剩下的形(唯一一次出现却缺值 / 值是旗形 / 空 / 超长 / 带空白)**仍然全部 fail-loud** —— 那才是
- * 「打错一个字就悄悄跑在别的镜像上」真正要防的那一族。
- * ⚠️ `docs/REFACTOR-LEDGER.md` REF-CC-143 的处置列此前写的是「缺值策略**统一** fail-loud」,
- * 与落地的两策略叶(`'invalidate'` / `'latch-previous'`)相悖,已同批改正(sweep-F11)。 */
 export declare function parseSandboxArgv(argv: readonly string[]): SandboxParseResult;
-/** The request-body stamp for a selection: EXPLICIT ⇒ `{sandboxImageProfile}`, default/auto ⇒ nothing
- *  (auto is advisory-by-prompt — the submit itself never carries a profile, per clay's c) 口径). */
 export declare function sandboxRequestFields(sel: SandboxSelection | undefined): {
     sandboxImageProfile?: string;
 };
-/**
- * The `--sandbox auto` advisory block. Design choices (each deliberate):
- *  - Conditional on the tool being mounted: `SelectEnvironment` reaches the model via the deployment's
- *    `spec.tools` injection (service select-environment-tool.ts RFC A2) — a worker without it must degrade
- *    HONESTLY (model says so and continues on the default), not hallucinate a selection.
- *  - The `Sandbox: <profile> — <reason>` reply line IS the run-card echo (可观测可纠正): the tool call
- *    renders as a normal tool card and the choice+reason line lands in the assistant reply — zero new
- *    renderer machinery, zero new server endpoints.
- *  - Boundary honesty: the server applies a session's selection from the NEXT task boundary ([440] F3),
- *    so the advisory says so — the model must not promise the current turn already runs on the new image.
- */
 export declare const AUTO_SANDBOX_ADVISORY: string;
-/** Prefix an objective with the auto-select advisory (one-shot — the caller owns the latch). */
 export declare function wrapObjectiveWithAutoSandboxAdvisory(objective: string): string;
 export declare const SANDBOX_K8S_ONLY_400_ANCHOR = "only supported on the k8s sandbox backend";
 export declare const SANDBOX_NO_IMAGE_INDEX_400_ANCHOR = "requires the image index";
 export declare const SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR = "no published sandbox image for profile";
 export declare const SANDBOX_CASCADE_CONFLICT_400_ANCHOR = "not supported together with cascade/verify";
-/**
- * Map a submit failure → the sandbox DEGRADATION HINT, or undefined when the error is not sandbox-shaped.
- * Keys on the server's honest reject texts (the four `SANDBOX_*_ANCHOR` constants above) — status+substring,
- * the same recognize-by-wire-shape idiom the quota/scenario copy modules use. The caller renders it under
- * the raw "API Error: …" row (original message preserved — the hint supplements, never masks, the server's
- * own words).
- */
 export declare function sandboxDegradeHint(err: unknown): string | undefined;

package/dist/sandboxWire.js

@@ -1,60 +1,10 @@
-/**
- * src/sema/sandboxWire.ts — [686]② `--sandbox` TRI-STATE flag (clay 拍, 2026-07-13): the CLI face of the
- * per-task SANDBOX IMAGE PROFILE the server already ships end-to-end (`TaskRequest.sandboxImageProfile`
- * per-task binding + the model-facing `SelectEnvironment` tool + the `GET /v1/images` catalog).
- *
- * TRI-STATE (clay 口径):
- *  a) DEFAULT (no flag)      → NO `sandboxImageProfile` on the POST body — the worker's default image runs.
- *  b) `--sandbox <profile>`  → EXPLICIT: stamp `sandboxImageProfile` (SDK types.ts:115 → service
- *     main.ts:2316 resolves profile→digest FAIL-CLOSED with the caller's principal — we only ever send the
- *     PROFILE, never a digest). Vocabulary = the live catalog (`sema cloud images list` / GET /v1/images) —
- *     the shell does NOT pre-validate against it (fail-closed admission is the server's job; a typo comes
- *     back as an honest 404, mapped to a hint by sandboxDegradeHint below).
- *  c) `--sandbox auto`       → ADVISORY: the submit carries NO profile; instead the FIRST live turn's
- *     objective is prefixed with an advisory block asking the model to drive the `SelectEnvironment` tool
- *     itself (list → pick → report `Sandbox: <profile> — <reason>` in its reply, so the choice + reason are
- *     visible on the run card and correctable by the user). NOT a hard route — server keeps zero new
- *     endpoints; the tool's session binding takes effect from the NEXT task boundary ([440] F3 contract).
- *
- * LANE HONESTY (诚实不撒谎 UI, [686] constraint): the profile only works on the k8s sandbox lane — an
- * e2b/host-lane worker (including the local TOC self-spawned engine) 400s the submit honestly
- * (service main.ts:2323 "sandboxImageProfile is only supported on the k8s sandbox backend"). The shell does
- * NOT pre-judge the lane (no caps sniffing before submit — per [686]: "不预判 lane,收到 400 再提示");
- * it maps the server's honest reject into a degradation hint (sandboxDegradeHint) rendered on the error row.
- * So on the local self-spawned engine `--sandbox <profile>` = a LOUD per-turn failure with an actionable
- * hint — never a silent ignore (silently dropping the user's explicit environment choice would be lying).
- */
 import { lastFlagValue } from './argvFlagValue.js';
-/** Mirror of the server's own body validation (server.ts:4651): non-empty, ≤128 chars. Validating locally
- *  just converts a guaranteed 400 into an immediate CLI error — same rule, earlier and cheaper. */
 const MAX_PROFILE_LEN = 128;
 const USAGE_HINT = "sema: --sandbox expects a profile name or 'auto'.\n" +
     '  --sandbox <profile>  run on that sandbox image profile (k8s-lane workers; list: sema cloud images list)\n' +
     '  --sandbox auto       let the model pick via its SelectEnvironment tool (advisory — choice + reason shown in the reply)\n' +
     '  (no flag)            the worker default image';
-/**
- * Parse `--sandbox` out of an argv slice (everything before a bare `--`; both `--sandbox <v>` and
- * `--sandbox=<v>` forms). No flag ⇒ `{mode:'default'}`. Repeated flag ⇒ LAST wins (commander convention).
- * Missing value / flag-shaped value / empty / over-long ⇒ fail-LOUD parse error (never a silent default —
- * a mis-typed environment choice must not quietly run on the wrong image).
- *
- * 🔴 [2393] sweep-F10(2026-08-03 全窗复审)**承诺范围如实收窄**(裁定:行为不改,话改):
- * 「fail-LOUD,never a silent default」这句话现在**不**覆盖一种输入 —— 同一个旗**重复出现**且
- * 前一次缺值/非法、后一次合法(`--sandbox --sandbox foo`):
- * 收编前是 per-occurrence eager validate,在**第一个**缺值 occurrence 上就 fail-loud;收编后走
- * `lastFlagValue`('invalidate' 缺省)= 后一次合法 occurrence 覆盖前一次,整体接受。
- * 为什么裁定不改回去:本模块自己写着的契约就是「Repeated flag ⇒ LAST wins(commander convention)」,
- * eager-validate 违反的正是这条契约(它让**被覆盖掉的**那一次决定整条命令的成败)。
- * 剩下的形(唯一一次出现却缺值 / 值是旗形 / 空 / 超长 / 带空白)**仍然全部 fail-loud** —— 那才是
- * 「打错一个字就悄悄跑在别的镜像上」真正要防的那一族。
- * ⚠️ `docs/REFACTOR-LEDGER.md` REF-CC-143 的处置列此前写的是「缺值策略**统一** fail-loud」,
- * 与落地的两策略叶(`'invalidate'` / `'latch-previous'`)相悖,已同批改正(sweep-F11)。 */
 export function parseSandboxArgv(argv) {
-    // REF-CC-143(dup-07)收编:extraction 改吃共用 lastFlagValue(argvFlagValue.ts)——scan-all-then-
-    // validate-once, matching this module's own documented "Repeated flag ⇒ LAST wins" contract (the
-    // former per-occurrence eager-validate loop actually violated that contract: an earlier INVALID
-    // occurrence overridden by a later VALID one used to fail-loud on the earlier one instead of
-    // honoring the later value — fixed as a side effect of the consolidation, not a logic rewrite).
     const flag = lastFlagValue(argv, '--sandbox');
     if (!flag.present)
         return { ok: true, sel: { mode: 'default' } };
@@ -63,10 +13,6 @@ export function parseSandboxArgv(argv) {
     const v = flag.raw.trim();
     if (v.length === 0)
         return { ok: false, error: USAGE_HINT };
-    // audit #17: a bare `--sandbox` EATS the following positional — `-p --sandbox 'say hi'`
-    // consumed the prompt as the profile, then died on an unrelated "Input must be provided…"
-    // error. Profile names never contain whitespace; a value that does is almost certainly the
-    // user's prompt — say exactly that instead of silently mis-parsing.
     if (/\s/.test(v)) {
         return {
             ok: false,
@@ -84,49 +30,21 @@ export function parseSandboxArgv(argv) {
     const sel = v === 'auto' ? { mode: 'auto' } : { mode: 'explicit', profile: v };
     return { ok: true, sel };
 }
-/** The request-body stamp for a selection: EXPLICIT ⇒ `{sandboxImageProfile}`, default/auto ⇒ nothing
- *  (auto is advisory-by-prompt — the submit itself never carries a profile, per clay's c) 口径). */
 export function sandboxRequestFields(sel) {
     return sel?.mode === 'explicit' ? { sandboxImageProfile: sel.profile } : {};
 }
-/**
- * The `--sandbox auto` advisory block. Design choices (each deliberate):
- *  - Conditional on the tool being mounted: `SelectEnvironment` reaches the model via the deployment's
- *    `spec.tools` injection (service select-environment-tool.ts RFC A2) — a worker without it must degrade
- *    HONESTLY (model says so and continues on the default), not hallucinate a selection.
- *  - The `Sandbox: <profile> — <reason>` reply line IS the run-card echo (可观测可纠正): the tool call
- *    renders as a normal tool card and the choice+reason line lands in the assistant reply — zero new
- *    renderer machinery, zero new server endpoints.
- *  - Boundary honesty: the server applies a session's selection from the NEXT task boundary ([440] F3),
- *    so the advisory says so — the model must not promise the current turn already runs on the new image.
- */
 export const AUTO_SANDBOX_ADVISORY = '<sandbox-auto-select>\n' +
     'The user launched this session with `--sandbox auto`: choose the best sandbox environment (image profile) for the work in this session yourself.\n' +
     'If a SelectEnvironment tool is available: call it with no arguments to list the available profiles and their capabilities, then select the one that best fits the task (keep the default if nothing fits better). After deciding, report your choice on its own line, exactly in this form: `Sandbox: <profile> — <one-line reason>` (use `Sandbox: default — <reason>` if you kept the default). Note the selection takes effect from the next task boundary — the current turn keeps the environment it started with.\n' +
     'If no SelectEnvironment tool is available, briefly say so and continue in the default environment.\n' +
     '</sandbox-auto-select>';
-/** Prefix an objective with the auto-select advisory (one-shot — the caller owns the latch). */
 export function wrapObjectiveWithAutoSandboxAdvisory(objective) {
     return `${AUTO_SANDBOX_ADVISORY}\n\n${objective}`;
 }
-// ── REF-CC-124(域词表-03,P3 wave1 卡C-argv):四条拒绝 hint 判别锚常量化 ─────────────────────────
-// ALLOW 登记(与 detachWire.DETACH_DURABLE_OFF_400_ANCHOR 同形):这四条锚的是**另一个仓**
-// (ai-agent-service)当下的拒绝原文(main.ts SelectEnvironment 校验分支 / per-task-image.ts 镜像
-// 索引缺席分支 / server.ts submit 校验分支)——只留文件名+分支语义,不锚外仓行号(它们会腐烂,
-// wave1 回炉 advisory 修:server 改字即静默失效,失效方向只丢 hint、不误伤,是本族里后果最轻的
-// 一处,故过渡期常量化而非阻断发车)。
-// 候 server 5.0.0 errorCode 换轨,#117(上游到货后这四条整族改吃 errorCode,判别不再靠字符串锚)。
 export const SANDBOX_K8S_ONLY_400_ANCHOR = 'only supported on the k8s sandbox backend';
 export const SANDBOX_NO_IMAGE_INDEX_400_ANCHOR = 'requires the image index';
 export const SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR = 'no published sandbox image for profile';
 export const SANDBOX_CASCADE_CONFLICT_400_ANCHOR = 'not supported together with cascade/verify';
-/**
- * Map a submit failure → the sandbox DEGRADATION HINT, or undefined when the error is not sandbox-shaped.
- * Keys on the server's honest reject texts (the four `SANDBOX_*_ANCHOR` constants above) — status+substring,
- * the same recognize-by-wire-shape idiom the quota/scenario copy modules use. The caller renders it under
- * the raw "API Error: …" row (original message preserved — the hint supplements, never masks, the server's
- * own words).
- */
 export function sandboxDegradeHint(err) {
     const e = err;
     if (typeof e?.status !== 'number' || typeof e?.message !== 'string')

package/dist/scenarioWire.d.ts

@@ -1,37 +1,5 @@
-/**
- * src/sema/scenarioWire.ts — `--scenario <name>` wire (clay 拍, 2026-07-15): expose the engine's
- * REQUEST-LEVEL scenario routing axis on the headless `-p` path. The server has shipped scenario
- * routing since day one (ai-agent-service capabilities/scenarios.ts — `TaskRequest.scenario` picks the
- * tool roster + prompt provider per request: default / code-review / scan / oa / team + center-declared
- * overlays); the shell simply never exposed the field to users. This module is the CLI face.
- *
- * PRECEDENCE (flag > settings > default):
- *  a) `--scenario <name>` (explicit flag)                 → stamp `TaskRequest.scenario`.
- *  b) `SEMA_HEADLESS_SCENARIO` env — the settings lane:   → stamp when no flag. Set it in the user
- *     settings.json `env` block (seeded into process.env by the SAME 1a-envseed both the REPL boot and
- *     printModeEngine run), the lane every other wire config rides (SEMA_SELF_ORCHESTRATION,
- *     SEMA_WEBSEARCH_*, SEMA_ENABLE_FORK). One mechanism serves both "env var" and "settings file".
- *  c) neither                                             → NO stamp = today's behaviour, verbatim.
- *
- * VOCABULARY = the server's scenario registry (builtin + center-declared). The shell does NOT
- * pre-validate against it (the registry is deployment-side truth): an UNKNOWN name falls back to the
- * `default` scenario server-side (scenarios.ts selectScenario — safe), and a center allowlist violation
- * comes back as an honest 400 `scenario_not_allowed` (already rendered by scenarioNotAllowedCopy.ts).
- * We only mirror the server's NAME-SHAPE rule (scenarios.ts:318 SCENARIO_NAME_RE) locally — same rule,
- * earlier and cheaper, and it keeps prompt-looking values (whitespace etc.) from being eaten as a name.
- *
- * NOTE (mock-key shadow): the seam also uses `scenario` as the MOCK transcript selector
- * (seamQuery.selectScenario / SEMA_SCENARIO). liveClient strips those mock keys before a live forward;
- * a `--scenario` value that collides with a mock key (e.g. `bash`) is therefore equivalent to `default`
- * on the live engine — which is exactly what the server would resolve for it anyway (no such scenario).
- *
- * SEMA_SCENARIO (the mock harness opt-in — "never spawn a real engine", printModeEngine.ts) is
- * deliberately NOT reused here: it selects offline mock transcripts, not live engine routing.
- */
 import { type EnvLike } from './hostEnv.js';
-/** Mirror of the server's scenario NAME shape (ai-agent-service scenarios.ts:318). */
 export declare const SCENARIO_NAME_RE: RegExp;
-/** Settings-lane env knob (settings.json `env` block → 1a-envseed → process.env). */
 export declare const HEADLESS_SCENARIO_ENV = "SEMA_HEADLESS_SCENARIO";
 export type ScenarioParseResult = {
     ok: true;
@@ -40,34 +8,6 @@ export type ScenarioParseResult = {
     ok: false;
     error: string;
 };
-/**
- * Parse `--scenario` out of an argv slice (everything before a bare `--`; both `--scenario <v>` and
- * `--scenario=<v>` forms — the sandboxWire idiom). No flag ⇒ `{ok:true}` with no scenario. Repeated
- * flag ⇒ LAST wins (commander convention). Missing value / flag-shaped value / name-shape violation ⇒
- * fail-LOUD parse error (never a silent default — a mis-typed routing choice must not quietly run on
- * the wrong tool surface; same stance as `--sandbox`).
- *
- * 🔴 [2393] sweep-F10(2026-08-03 全窗复审)**承诺范围如实收窄**(裁定:行为不改,话改):
- * 「fail-LOUD,never a silent default」这句话现在**不**覆盖一种输入 —— 同一个旗**重复出现**且
- * 前一次缺值/非法、后一次合法(`--scenario --scenario foo`):
- * 收编前是 per-occurrence eager validate,在**第一个**缺值 occurrence 上就 fail-loud;收编后走
- * `lastFlagValue`('invalidate' 缺省)= 后一次合法 occurrence 覆盖前一次,整体接受。
- * 为什么裁定不改回去:本模块自己写着的契约就是「Repeated flag ⇒ LAST wins(commander convention)」,
- * eager-validate 违反的正是这条契约(它让**被覆盖掉的**那一次决定整条命令的成败)。
- * 剩下的形(唯一一次出现却缺值 / 值是旗形 / 空 / 超长 / 带空白)**仍然全部 fail-loud** —— 那才是
- * 「打错一个字就悄悄跑在别的镜像上」真正要防的那一族。
- * ⚠️ `docs/REFACTOR-LEDGER.md` REF-CC-143 的处置列此前写的是「缺值策略**统一** fail-loud」,
- * 与落地的两策略叶(`'invalidate'` / `'latch-previous'`)相悖,已同批改正(sweep-F11)。 */
 export declare function parseScenarioArgv(argv: readonly string[]): ScenarioParseResult;
-/**
- * The settings-lane default (`SEMA_HEADLESS_SCENARIO`). FAIL-SOFT on a bad value (stderr warning +
- * no stamp): a settings-file typo must not hard-brick every headless run the way an explicit flag
- * typo fails the one run it was typed on.
- */
 export declare function headlessScenarioFromEnv(env?: EnvLike): string | undefined;
-/**
- * Resolve the scenario for a headless `-p` submit: explicit `--scenario` flag > `SEMA_HEADLESS_SCENARIO`
- * settings default > none (= the engine's default scenario, today's behaviour). Flag parse errors
- * propagate fail-loud; the caller exits.
- */
 export declare function scenarioForPrint(argv: string[], env?: EnvLike): ScenarioParseResult;

package/dist/scenarioWire.js

@@ -1,75 +1,18 @@
-/**
- * src/sema/scenarioWire.ts — `--scenario <name>` wire (clay 拍, 2026-07-15): expose the engine's
- * REQUEST-LEVEL scenario routing axis on the headless `-p` path. The server has shipped scenario
- * routing since day one (ai-agent-service capabilities/scenarios.ts — `TaskRequest.scenario` picks the
- * tool roster + prompt provider per request: default / code-review / scan / oa / team + center-declared
- * overlays); the shell simply never exposed the field to users. This module is the CLI face.
- *
- * PRECEDENCE (flag > settings > default):
- *  a) `--scenario <name>` (explicit flag)                 → stamp `TaskRequest.scenario`.
- *  b) `SEMA_HEADLESS_SCENARIO` env — the settings lane:   → stamp when no flag. Set it in the user
- *     settings.json `env` block (seeded into process.env by the SAME 1a-envseed both the REPL boot and
- *     printModeEngine run), the lane every other wire config rides (SEMA_SELF_ORCHESTRATION,
- *     SEMA_WEBSEARCH_*, SEMA_ENABLE_FORK). One mechanism serves both "env var" and "settings file".
- *  c) neither                                             → NO stamp = today's behaviour, verbatim.
- *
- * VOCABULARY = the server's scenario registry (builtin + center-declared). The shell does NOT
- * pre-validate against it (the registry is deployment-side truth): an UNKNOWN name falls back to the
- * `default` scenario server-side (scenarios.ts selectScenario — safe), and a center allowlist violation
- * comes back as an honest 400 `scenario_not_allowed` (already rendered by scenarioNotAllowedCopy.ts).
- * We only mirror the server's NAME-SHAPE rule (scenarios.ts:318 SCENARIO_NAME_RE) locally — same rule,
- * earlier and cheaper, and it keeps prompt-looking values (whitespace etc.) from being eaten as a name.
- *
- * NOTE (mock-key shadow): the seam also uses `scenario` as the MOCK transcript selector
- * (seamQuery.selectScenario / SEMA_SCENARIO). liveClient strips those mock keys before a live forward;
- * a `--scenario` value that collides with a mock key (e.g. `bash`) is therefore equivalent to `default`
- * on the live engine — which is exactly what the server would resolve for it anyway (no such scenario).
- *
- * SEMA_SCENARIO (the mock harness opt-in — "never spawn a real engine", printModeEngine.ts) is
- * deliberately NOT reused here: it selects offline mock transcripts, not live engine routing.
- */
 import { hostEnv } from './hostEnv.js';
 import { lastFlagValue } from './argvFlagValue.js';
-/** Mirror of the server's scenario NAME shape (ai-agent-service scenarios.ts:318). */
 export const SCENARIO_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
-/** Settings-lane env knob (settings.json `env` block → 1a-envseed → process.env). */
 export const HEADLESS_SCENARIO_ENV = 'SEMA_HEADLESS_SCENARIO';
 const USAGE_HINT = "sema: --scenario expects a scenario name (lowercase letters/digits/hyphens, starting with a letter, ≤32 chars).\n" +
     '  --scenario <name>    route this run through the named engine scenario (deployment-defined tool\n' +
     '                       roster + system prompt; unknown names fall back to the default scenario)\n' +
     '  (no flag)            the default scenario — today\'s behaviour';
-/**
- * Parse `--scenario` out of an argv slice (everything before a bare `--`; both `--scenario <v>` and
- * `--scenario=<v>` forms — the sandboxWire idiom). No flag ⇒ `{ok:true}` with no scenario. Repeated
- * flag ⇒ LAST wins (commander convention). Missing value / flag-shaped value / name-shape violation ⇒
- * fail-LOUD parse error (never a silent default — a mis-typed routing choice must not quietly run on
- * the wrong tool surface; same stance as `--sandbox`).
- *
- * 🔴 [2393] sweep-F10(2026-08-03 全窗复审)**承诺范围如实收窄**(裁定:行为不改,话改):
- * 「fail-LOUD,never a silent default」这句话现在**不**覆盖一种输入 —— 同一个旗**重复出现**且
- * 前一次缺值/非法、后一次合法(`--scenario --scenario foo`):
- * 收编前是 per-occurrence eager validate,在**第一个**缺值 occurrence 上就 fail-loud;收编后走
- * `lastFlagValue`('invalidate' 缺省)= 后一次合法 occurrence 覆盖前一次,整体接受。
- * 为什么裁定不改回去:本模块自己写着的契约就是「Repeated flag ⇒ LAST wins(commander convention)」,
- * eager-validate 违反的正是这条契约(它让**被覆盖掉的**那一次决定整条命令的成败)。
- * 剩下的形(唯一一次出现却缺值 / 值是旗形 / 空 / 超长 / 带空白)**仍然全部 fail-loud** —— 那才是
- * 「打错一个字就悄悄跑在别的镜像上」真正要防的那一族。
- * ⚠️ `docs/REFACTOR-LEDGER.md` REF-CC-143 的处置列此前写的是「缺值策略**统一** fail-loud」,
- * 与落地的两策略叶(`'invalidate'` / `'latch-previous'`)相悖,已同批改正(sweep-F11)。 */
 export function parseScenarioArgv(argv) {
-    // REF-CC-143(dup-07)收编:extraction 改吃共用 lastFlagValue(argvFlagValue.ts)——scan-all-then-
-    // validate-once, matching this function's own documented "Repeated flag ⇒ LAST wins" contract (the
-    // former per-occurrence eager-validate loop actually violated that contract the same way sandboxWire's
-    // did: an earlier INVALID occurrence overridden by a later VALID one used to fail-loud on the earlier
-    // one instead of honoring the later value — fixed as a side effect of the consolidation).
     const flag = lastFlagValue(argv, '--scenario');
     if (!flag.present)
         return { ok: true };
     if (flag.raw === undefined)
         return { ok: false, error: USAGE_HINT };
     const v = flag.raw.trim();
-    // sandboxWire audit #17 lesson: a bare `--scenario` EATS the following positional — a value with
-    // whitespace is almost certainly the user's prompt; say exactly that instead of mis-parsing.
     if (/\s/.test(v)) {
         return {
             ok: false,
@@ -83,27 +26,16 @@ export function parseScenarioArgv(argv) {
     }
     return { ok: true, scenario: v };
 }
-/**
- * The settings-lane default (`SEMA_HEADLESS_SCENARIO`). FAIL-SOFT on a bad value (stderr warning +
- * no stamp): a settings-file typo must not hard-brick every headless run the way an explicit flag
- * typo fails the one run it was typed on.
- */
 export function headlessScenarioFromEnv(env = hostEnv()) {
     const v = env[HEADLESS_SCENARIO_ENV]?.trim();
     if (!v)
         return undefined;
     if (!SCENARIO_NAME_RE.test(v)) {
-        // eslint-disable-next-line no-console
         console.error(`[sema] ${HEADLESS_SCENARIO_ENV}="${v}" is not a valid scenario name (want ${String(SCENARIO_NAME_RE)}) — ignoring the settings default`);
         return undefined;
     }
     return v;
 }
-/**
- * Resolve the scenario for a headless `-p` submit: explicit `--scenario` flag > `SEMA_HEADLESS_SCENARIO`
- * settings default > none (= the engine's default scenario, today's behaviour). Flag parse errors
- * propagate fail-loud; the caller exits.
- */
 export function scenarioForPrint(argv, env = hostEnv()) {
     const parsed = parseScenarioArgv(argv);
     if (!parsed.ok)

package/dist/scratchpadWireCaps.d.ts

@@ -1,16 +1,5 @@
 export interface ScratchpadDirField {
     scratchpadDir?: string;
 }
-/**
- * Per-turn scratchpadDir stamp。gate off(tengu_scratch)⇒ 空对象(请求形状不变,mock parity)。
- * 路径 per-session 稳定(sessionId 定 getScratchpadDir),重复调用幂等。
- *
- * 与 cli 的差分记账:
- *  · `ensureScratchpadDir` 在壳里是 async(mkdir 0o700),这里 **两种返回都吞**(端可给同步实现);
- *    建失败只影响引擎首写时自建(server 半场也建),**不阻 turn** —— 与 cli 逐字同语义。
- *  · fs 口缺席(浏览器宿主)⇒ 返回空对象 = 不 stamp。additive 字段缺席对引擎无害,
- *    但会计一次 `hostPortMisses().fs`,让「Node 宿主漏装」与「浏览器本就没有」在自检里可区分。
- */
 export declare function scratchpadDirField(): ScratchpadDirField;
-/** 测试钩:复位 module 级建目录闩。 */
 export declare function _resetScratchpadEnsuredForTest(): void;

package/dist/scratchpadWireCaps.js

@@ -1,36 +1,5 @@
-/**
- * ⇄ B4 批搬迁(2026-07-27,多端改造设计稿 §3 B4 第五件):cli `src/sema/scratchpadWireCaps.ts` 搬入。
- * 拆缝 = 两条外向边换 host port:`utils/permissions/filesystem`(getScratchpadDir /
- * isScratchpadEnabled / ensureScratchpadDir)→ `hostFs()`;`utils/debug.logForDebugging` → `hostLog()`。
- * 本文件是 B2 判给 B4 的两件「宿主耦合 WireCaps」里的**小的那件**,同时充当 `FsPort` 的端到端证明。
- */
-/**
- * scratchpad 域的 wire 半场([816] 壳侧承诺③ / [819]④ / [820]③,2026-07-14)。
- *
- * 链路:core `TaskSpec.envFacts.scratchpadDir` 字段 + 提示词消费链(buildScratchpadSection)1.257.3
- * 起全在;server 半场 = buildEnvFacts 填字段 + 建目录 + 塞进 createFsWriteGatePolicy 的 exemptDirs。
- * 客户端把 getScratchpadDir()(CC 同型:`/tmp/claude-{uid}/{sanitized-cwd}/{sessionId}/scratchpad`)
- * stamp 到 `TaskRequest.scratchpadDir` —— server 半场没到时字段发了引擎忽略 = 无害(additive 铁律);
- * 到货后 server 以客户端带的路径为准(本机 TOC 引擎与壳同 fs,壳造的目录引擎直接可写),或自造(TOB 远端)。
- *
- * 🔴 [1840] 勘误:G3 `scratchpadDir` **不是死键** —— server 已把「死键」的说法收回改接单
- * ([816]③/[820]③ additive 预挂)。别再按「没人读」把这条 stamp 删掉。
- *
- * 🔴 单实例纪律:本模块持 module 级 `ensured` 闩(整进程只 fire-and-forget 建一次目录)。
- * 两份实例 = 建两次(幂等无害),但与本包其余台账同理,壳侧必须只解析到一份。
- */
 import { hostFs, hostLog } from './host.js';
 let ensured = false;
-/**
- * Per-turn scratchpadDir stamp。gate off(tengu_scratch)⇒ 空对象(请求形状不变,mock parity)。
- * 路径 per-session 稳定(sessionId 定 getScratchpadDir),重复调用幂等。
- *
- * 与 cli 的差分记账:
- *  · `ensureScratchpadDir` 在壳里是 async(mkdir 0o700),这里 **两种返回都吞**(端可给同步实现);
- *    建失败只影响引擎首写时自建(server 半场也建),**不阻 turn** —— 与 cli 逐字同语义。
- *  · fs 口缺席(浏览器宿主)⇒ 返回空对象 = 不 stamp。additive 字段缺席对引擎无害,
- *    但会计一次 `hostPortMisses().fs`,让「Node 宿主漏装」与「浏览器本就没有」在自检里可区分。
- */
 export function scratchpadDirField() {
     try {
         const fs = hostFs();
@@ -59,7 +28,6 @@ export function scratchpadDirField() {
         return {};
     }
 }
-/** 测试钩:复位 module 级建目录闩。 */
 export function _resetScratchpadEnsuredForTest() {
     ensured = false;
 }

package/dist/sdkWireTransit.d.ts

@@ -1,41 +1,3 @@
-/**
- * src/sdkWireTransit.ts — SDK **wire 面**的转口口(L-61 存量清零;clay 令 C-R43「所有欠账绝不延期」)。
- *
- * ── 为什么开这一只(与 `engineHttpTools.ts` 的分界)──────────────────────────────────────────
- * `engineHttpTools.ts` 转的是两件**纯工具**(URL builder / 存活探针)。本文件转的是 wire 面的
- * **客户端类**、**帧谓词**与**型面** —— 端至今只能直连 `@sema-agent/sdk` 去取它们
- * (cli sdk-isolation 存量册 `sdk-value` 桶的剩余条目),而「壳对引擎 wire 的一切消费必须经本包」
- * 这条公约对它们一直不成立。
- *
- * 🔴 **为什么 0.68.2 之前把 `AgentClient` 记成 declined,现在改成转口**(改口要给理由,不能只改结论):
- *    此前的理由是「转口一个客户端类 = 本包为它的连接姿势/鉴权头/重试语义背书」。这条**顾虑仍然
- *    成立**,但它指向的是「端该不该直接 new 一个 AgentClient」这个**设计问题**,而不是「这条 import
- *    该不该经本包」这个**归层问题**——把两者绑在一起的代价是:归层这件事被一个未排期的设计件
- *    无限期挡住(存量窗已因此过期两代)。⇒ 分开处理:
- *      · **归层现在做**(本文件,原样转口,零包装);
- *      · **设计件照旧欠着**:本包已有的自有路 `makeEngineWireClient` 才是推荐姿势,端上新码一律走
- *        那一条;本转口口只给**存量**用,不是新码的入口。这一条写在这里,不靠人记得。
- *
- * 🔴 **原样转口,一个字节都不加工**(与 `engineHttpTools.ts` 同一条纪律):不包装、不改签名、
- *    不补默认值 —— 包一层就是把「同一实现」这条唯一的抗漂移保证亲手拆掉。
- *
- * ── 可移植门为什么不受影响(实测,不是推断)────────────────────────────────────────────────
- *  · `@sema-agent/sdk` **本来就在** `EXPECTED_PACKAGES_INDEX` 等值集里(本包已有值级 SDK import)
- *    ⇒ 集合一个字节不动;
- *  · SDK 的 `dist/` 全树 **零 `node:` 内建**(实测:`grep -rl "node:" dist/*.js` 空),传输走全局
- *    `fetch`/`AbortController` = web 标准 ⇒ ③ 段的 `--platform=browser` 真打包面零风险;
- *  · 型面转口是 `export type`,编译后整段消失 ⇒ 闭包扫描的「剥 type-only」那一步本来就不看它。
- */
 export { AgentClient } from '@sema-agent/sdk';
 export { isApprovalRequestFrameV1, isApprovalRevokeFrameV1 } from '@sema-agent/sdk';
-/**
- * ── ③ wire **型面**(零运行期,`export type`)────────────────────────────────────────────────
- *
- * 🔴 **射程写明**(免得下一棒把这里当成「SDK 型面的全量镜像」):本表**只**收端上存量直连实际用到
- *    的那些名字,一个不多。全量镜像是另一件事(会把本包的 `.d.ts` 与 SDK 的每一次型面改动绑死),
- *    与 `@sema-agent/agent-types` 的**CC 形**全量镜像不是一回事 —— 那边镜的是 CC SDK 的会话词汇,
- *    这边是引擎 wire 的请求/事件/回执形。
- * 🔴 **谁是权威**:权威恒是 `@sema-agent/sdk` 本身。本文件是**别名**,上游改名 ⇒ 本文件当场编译红,
- *    端跟着红 —— 这正是型面转口相对「端各自直连」唯一多出来的那点好处(红在一处,不是散在九处)。
- */
 export type { TaskRequest, SessionPermissionRules, SemaSettings, SkillSpec, AgentEvent, RunReceipt, CancelAck, RunRecord, ToolApprovalRespondAck, FleetTaskRow, FleetWorkflowRow, ApprovalCard, ApprovalRequestFrame, ApprovalRiskAxes, AskDecisionAck, AskDecisionBody, } from '@sema-agent/sdk';

package/dist/sdkWireTransit.js

@@ -1,32 +1,2 @@
-/**
- * src/sdkWireTransit.ts — SDK **wire 面**的转口口(L-61 存量清零;clay 令 C-R43「所有欠账绝不延期」)。
- *
- * ── 为什么开这一只(与 `engineHttpTools.ts` 的分界)──────────────────────────────────────────
- * `engineHttpTools.ts` 转的是两件**纯工具**(URL builder / 存活探针)。本文件转的是 wire 面的
- * **客户端类**、**帧谓词**与**型面** —— 端至今只能直连 `@sema-agent/sdk` 去取它们
- * (cli sdk-isolation 存量册 `sdk-value` 桶的剩余条目),而「壳对引擎 wire 的一切消费必须经本包」
- * 这条公约对它们一直不成立。
- *
- * 🔴 **为什么 0.68.2 之前把 `AgentClient` 记成 declined,现在改成转口**(改口要给理由,不能只改结论):
- *    此前的理由是「转口一个客户端类 = 本包为它的连接姿势/鉴权头/重试语义背书」。这条**顾虑仍然
- *    成立**,但它指向的是「端该不该直接 new 一个 AgentClient」这个**设计问题**,而不是「这条 import
- *    该不该经本包」这个**归层问题**——把两者绑在一起的代价是:归层这件事被一个未排期的设计件
- *    无限期挡住(存量窗已因此过期两代)。⇒ 分开处理:
- *      · **归层现在做**(本文件,原样转口,零包装);
- *      · **设计件照旧欠着**:本包已有的自有路 `makeEngineWireClient` 才是推荐姿势,端上新码一律走
- *        那一条;本转口口只给**存量**用,不是新码的入口。这一条写在这里,不靠人记得。
- *
- * 🔴 **原样转口,一个字节都不加工**(与 `engineHttpTools.ts` 同一条纪律):不包装、不改签名、
- *    不补默认值 —— 包一层就是把「同一实现」这条唯一的抗漂移保证亲手拆掉。
- *
- * ── 可移植门为什么不受影响(实测,不是推断)────────────────────────────────────────────────
- *  · `@sema-agent/sdk` **本来就在** `EXPECTED_PACKAGES_INDEX` 等值集里(本包已有值级 SDK import)
- *    ⇒ 集合一个字节不动;
- *  · SDK 的 `dist/` 全树 **零 `node:` 内建**(实测:`grep -rl "node:" dist/*.js` 空),传输走全局
- *    `fetch`/`AbortController` = web 标准 ⇒ ③ 段的 `--platform=browser` 真打包面零风险;
- *  · 型面转口是 `export type`,编译后整段消失 ⇒ 闭包扫描的「剥 type-only」那一步本来就不看它。
- */
-// ── ① 客户端类(存量转口;新码走 `makeEngineWireClient`)────────────────────────────────────
 export { AgentClient } from '@sema-agent/sdk';
-// ── ② 流内审批帧的**信封谓词**(v1 窄化判据;端拿它判「这一帧是不是我认得的那一代」)──────────
 export { isApprovalRequestFrameV1, isApprovalRevokeFrameV1 } from '@sema-agent/sdk';