@sema-agent/client-core 0.6.0 → 0.7.0

package/dist/limitsWire.d.ts

@@ -0,0 +1,89 @@
+/**
+ * src/sema/limitsWire.ts — headless `-p` run-limits wire (TB2.0 反馈批 E · P2-3-b, 2026-07-15):
+ * expose the engine's REQUEST-LEVEL pacing limits on the headless `-p` path via `TaskRequest.limits`.
+ * The server accepts `limits:{timeoutSec?,maxOutputTokens?,maxTurns?}` since 1.196.0 (positive-integer
+ * 400 gate, board [857]) and feeds the EXISTING pacing machinery (deadlineNudge / callCapByDeadline /
+ * gracefulFinalize) — the shell simply never stamped the field. This module is the CLI face.
+ *
+ * TWO FLAGS, TWO ALIGNMENT BUCKETS:
+ *  · `--deadline <sec>`   → limits.timeoutSec. Upstream CC 2.1.207 has NO deadline flag (nearest kin:
+ *    --max-turns / --task-budget / --max-budget-usd) → SUPERSET, help copy says so.
+ *  · `--max-turns <n>`    → limits.maxTurns. Upstream CC 2.1.207 HAS `--max-turns` (source 199676 /
+ *    793380) → ALIGNMENT-GAP fill: the flag was already registered (main.tsx CC-inherited surface) and
+ *    drove the local query loop, but the seam path executes turns ENGINE-side — this wire finally
+ *    carries the cap to where the turns actually run.
+ *
+ * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
+ *  a) explicit flag                                   → strict validation, FAIL-LOUD on an invalid
+ *     value (integer domain below; a mis-typed pacing bound must not quietly run unbounded).
+ *  b) settings env lane (settings.json `env` block → 1a-envseed → process.env):
+ *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` → SILENT degrade on an invalid value
+ *     (spec'd 静默降级 — a settings typo must never brick every headless run; unlike scenarioWire we
+ *     don't even warn, per the batch-E triage shape. SEMA_DEBUG surfaces the drop for diagnosis).
+ *  c) neither                                          → NO stamp = today's behaviour, verbatim.
+ *
+ * DOMAINS (integer, inclusive): timeoutSec 30..86400 · maxTurns 1..1000.
+ *
+ * VERSION GATE (triage risk ③ — an OLD server SILENTLY SWALLOWS unknown body fields, worse than not
+ * shipping): the self-spawned engine is release-pinned ≥1.197.0 so the dev/release lanes are safe by
+ * construction; but a user-supplied SEMA_ENGINE_URL may point at an older engine. When the user
+ * EXPLICITLY passed a flag (env-lane defaults stay quiet) and SEMA_ENGINE_URL is in play, the caller
+ * probes `${baseUrl}/health` (the engine self-describes `version` since 1.96) and prints ONE honest
+ * stderr line when version <1.196.0 — the request still goes out unchanged (warn, don't block).
+ * Unreachable /health or an unparsable version stays silent (can't confirm staleness — fail-soft).
+ */
+import { type EnvLike } from './hostEnv.js';
+/** Settings-lane env knobs (settings.json `env` block → 1a-envseed → process.env). */
+export declare const HEADLESS_DEADLINE_ENV = "SEMA_HEADLESS_DEADLINE_SEC";
+export declare const HEADLESS_MAX_TURNS_ENV = "SEMA_HEADLESS_MAX_TURNS";
+/** Integer domains (inclusive). timeoutSec: 30s..24h; maxTurns: 1..1000. */
+export declare const DEADLINE_SEC_MIN = 30;
+export declare const DEADLINE_SEC_MAX = 86400;
+export declare const MAX_TURNS_MIN = 1;
+export declare const MAX_TURNS_MAX = 1000;
+/** First server version whose /v1/tasks|/v1/tasks/stream accept body.limits (board [857]). */
+export declare const LIMITS_WIRE_MIN_ENGINE: readonly [number, number, number];
+export interface HeadlessLimits {
+    timeoutSec?: number;
+    maxTurns?: number;
+}
+export type LimitsParseResult = {
+    ok: true;
+    limits?: HeadlessLimits;
+    flaggedFlags: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse `--deadline` + `--max-turns` out of an argv slice. No flags ⇒ `{ok:true}` with no limits.
+ * Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer / out-of-domain ⇒
+ * fail-LOUD parse error (never a silent default — same stance as `--scenario`/`--sandbox`).
+ * `flaggedFlags` names the flags that EXPLICITLY contributed (the version-gate probe trigger).
+ */
+export declare function parseLimitsArgv(argv: string[]): LimitsParseResult;
+/**
+ * The settings-lane defaults. SILENT degrade on a bad value (batch-E triage shape — stricter than
+ * scenarioWire's warn-and-ignore: these are pacing hints, and a settings typo must neither brick nor
+ * spam every headless run). SEMA_DEBUG surfaces the drop.
+ */
+export declare function headlessLimitsFromEnv(env?: EnvLike): HeadlessLimits | undefined;
+/**
+ * Resolve the limits for a headless `-p` submit: explicit flags > settings env defaults > none
+ * (= no stamp, today's behaviour). Merge is PER-KNOB: `--deadline 300` + SEMA_HEADLESS_MAX_TURNS=50
+ * yields {timeoutSec:300, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
+ */
+export declare function limitsForPrint(argv: string[], env?: EnvLike): LimitsParseResult;
+/** True when the engine version string satisfies the limits-wire minimum (≥1.196.0). Unparsable ⇒ false. */
+export declare function versionSupportsLimits(v: string | undefined): boolean;
+/**
+ * Version-gate probe (triage risk ③): GET `${baseUrl}/health`, read `version`, and return ONE honest
+ * stderr line when the engine is confirmed <1.196.0 — the caller prints it and SENDS ANYWAY (the old
+ * server drops the field server-side; warn, don't block). Returns undefined when the engine is new
+ * enough, unreachable, or self-describes no parsable version (can't confirm staleness — fail-soft
+ * silent; the release-pinned self-spawn lane never even reaches this probe).
+ */
+export declare function engineLimitsSupportWarning(baseUrl: string, flaggedFlags: string[], opts?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<string | undefined>;

package/dist/limitsWire.js

@@ -0,0 +1,225 @@
+/**
+ * src/sema/limitsWire.ts — headless `-p` run-limits wire (TB2.0 反馈批 E · P2-3-b, 2026-07-15):
+ * expose the engine's REQUEST-LEVEL pacing limits on the headless `-p` path via `TaskRequest.limits`.
+ * The server accepts `limits:{timeoutSec?,maxOutputTokens?,maxTurns?}` since 1.196.0 (positive-integer
+ * 400 gate, board [857]) and feeds the EXISTING pacing machinery (deadlineNudge / callCapByDeadline /
+ * gracefulFinalize) — the shell simply never stamped the field. This module is the CLI face.
+ *
+ * TWO FLAGS, TWO ALIGNMENT BUCKETS:
+ *  · `--deadline <sec>`   → limits.timeoutSec. Upstream CC 2.1.207 has NO deadline flag (nearest kin:
+ *    --max-turns / --task-budget / --max-budget-usd) → SUPERSET, help copy says so.
+ *  · `--max-turns <n>`    → limits.maxTurns. Upstream CC 2.1.207 HAS `--max-turns` (source 199676 /
+ *    793380) → ALIGNMENT-GAP fill: the flag was already registered (main.tsx CC-inherited surface) and
+ *    drove the local query loop, but the seam path executes turns ENGINE-side — this wire finally
+ *    carries the cap to where the turns actually run.
+ *
+ * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
+ *  a) explicit flag                                   → strict validation, FAIL-LOUD on an invalid
+ *     value (integer domain below; a mis-typed pacing bound must not quietly run unbounded).
+ *  b) settings env lane (settings.json `env` block → 1a-envseed → process.env):
+ *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` → SILENT degrade on an invalid value
+ *     (spec'd 静默降级 — a settings typo must never brick every headless run; unlike scenarioWire we
+ *     don't even warn, per the batch-E triage shape. SEMA_DEBUG surfaces the drop for diagnosis).
+ *  c) neither                                          → NO stamp = today's behaviour, verbatim.
+ *
+ * DOMAINS (integer, inclusive): timeoutSec 30..86400 · maxTurns 1..1000.
+ *
+ * VERSION GATE (triage risk ③ — an OLD server SILENTLY SWALLOWS unknown body fields, worse than not
+ * shipping): the self-spawned engine is release-pinned ≥1.197.0 so the dev/release lanes are safe by
+ * construction; but a user-supplied SEMA_ENGINE_URL may point at an older engine. When the user
+ * EXPLICITLY passed a flag (env-lane defaults stay quiet) and SEMA_ENGINE_URL is in play, the caller
+ * probes `${baseUrl}/health` (the engine self-describes `version` since 1.96) and prints ONE honest
+ * stderr line when version <1.196.0 — the request still goes out unchanged (warn, don't block).
+ * Unreachable /health or an unparsable version stays silent (can't confirm staleness — fail-soft).
+ */
+import { hostEnv } from './hostEnv.js';
+/** Settings-lane env knobs (settings.json `env` block → 1a-envseed → process.env). */
+export const HEADLESS_DEADLINE_ENV = 'SEMA_HEADLESS_DEADLINE_SEC';
+export const HEADLESS_MAX_TURNS_ENV = 'SEMA_HEADLESS_MAX_TURNS';
+/** Integer domains (inclusive). timeoutSec: 30s..24h; maxTurns: 1..1000. */
+export const DEADLINE_SEC_MIN = 30;
+export const DEADLINE_SEC_MAX = 86_400;
+export const MAX_TURNS_MIN = 1;
+export const MAX_TURNS_MAX = 1_000;
+/** First server version whose /v1/tasks|/v1/tasks/stream accept body.limits (board [857]). */
+export const LIMITS_WIRE_MIN_ENGINE = [1, 196, 0];
+const DEADLINE_USAGE = `sema: --deadline expects a whole number of seconds between ${DEADLINE_SEC_MIN} and ${DEADLINE_SEC_MAX}.\n` +
+    '  --deadline <sec>     soft wall-clock budget for this run (sema superset — no upstream equivalent):\n' +
+    '                       the engine paces itself (nudges + call caps) and finalizes gracefully near the deadline\n' +
+    '  (no flag)            no deadline — today\'s behaviour';
+const MAX_TURNS_USAGE = `sema: --max-turns expects a whole number of turns between ${MAX_TURNS_MIN} and ${MAX_TURNS_MAX}.\n` +
+    '  --max-turns <n>      maximum number of agentic turns for this run (upstream-aligned flag,\n' +
+    '                       enforced engine-side on the sema seam)\n' +
+    '  (no flag)            no turn cap — today\'s behaviour';
+/** STRICT integer shape for explicit flag values: ASCII digits only (no sign/decimal/exponent/space). */
+const INT_RE = /^\d+$/;
+/**
+ * Pull the LAST value of a `--name <v>` / `--name=<v>` flag out of an argv slice (everything before a
+ * bare `--` — positionals are never flags; scenarioWire 纪律). Returns:
+ *   {present:false}                 — flag absent
+ *   {present:true, raw}             — flag present with a value token
+ *   {present:true, raw:undefined}   — flag present but the value is missing/flag-shaped (fail-loud at caller)
+ */
+function lastFlagValue(argv, name) {
+    const eq = `${name}=`;
+    let present = false;
+    let raw;
+    let valueMissing = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--')
+            break; // positionals — never flags
+        if (a === name) {
+            present = true;
+            const nxt = argv[i + 1];
+            if (nxt === undefined || nxt.startsWith('-')) {
+                // note: a NEGATIVE number would look flag-shaped too — the domains are all-positive, so the
+                // fail-loud usage hint is the right answer for `--deadline -5` as well.
+                valueMissing = true;
+                raw = undefined;
+                continue;
+            }
+            valueMissing = false;
+            raw = nxt;
+            i++; // consume the value token
+        }
+        else if (a.startsWith(eq)) {
+            present = true;
+            valueMissing = false;
+            raw = a.slice(eq.length);
+        }
+    }
+    if (present && (valueMissing || raw === undefined))
+        return { present: true };
+    return present ? { present: true, raw } : { present: false };
+}
+/** Validate a RAW flag value against an inclusive integer domain. Returns the number or null. */
+function parseIntInDomain(raw, min, max) {
+    const v = raw.trim();
+    if (!INT_RE.test(v))
+        return null;
+    const n = Number(v);
+    if (!Number.isSafeInteger(n) || n < min || n > max)
+        return null;
+    return n;
+}
+/**
+ * Parse `--deadline` + `--max-turns` out of an argv slice. No flags ⇒ `{ok:true}` with no limits.
+ * Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer / out-of-domain ⇒
+ * fail-LOUD parse error (never a silent default — same stance as `--scenario`/`--sandbox`).
+ * `flaggedFlags` names the flags that EXPLICITLY contributed (the version-gate probe trigger).
+ */
+export function parseLimitsArgv(argv) {
+    const limits = {};
+    const flaggedFlags = [];
+    const dl = lastFlagValue(argv, '--deadline');
+    if (dl.present) {
+        const n = dl.raw !== undefined ? parseIntInDomain(dl.raw, DEADLINE_SEC_MIN, DEADLINE_SEC_MAX) : null;
+        if (n === null)
+            return { ok: false, error: DEADLINE_USAGE };
+        limits.timeoutSec = n;
+        flaggedFlags.push('--deadline');
+    }
+    const mt = lastFlagValue(argv, '--max-turns');
+    if (mt.present) {
+        const n = mt.raw !== undefined ? parseIntInDomain(mt.raw, MAX_TURNS_MIN, MAX_TURNS_MAX) : null;
+        if (n === null)
+            return { ok: false, error: MAX_TURNS_USAGE };
+        limits.maxTurns = n;
+        flaggedFlags.push('--max-turns');
+    }
+    return {
+        ok: true,
+        ...(flaggedFlags.length > 0 ? { limits } : {}),
+        flaggedFlags,
+    };
+}
+/**
+ * The settings-lane defaults. SILENT degrade on a bad value (batch-E triage shape — stricter than
+ * scenarioWire's warn-and-ignore: these are pacing hints, and a settings typo must neither brick nor
+ * spam every headless run). SEMA_DEBUG surfaces the drop.
+ */
+export function headlessLimitsFromEnv(env = hostEnv()) {
+    const out = {};
+    const dl = env[HEADLESS_DEADLINE_ENV]?.trim();
+    if (dl) {
+        const n = parseIntInDomain(dl, DEADLINE_SEC_MIN, DEADLINE_SEC_MAX);
+        if (n !== null)
+            out.timeoutSec = n;
+        else if (env.SEMA_DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error(`[sema] ${HEADLESS_DEADLINE_ENV}="${dl}" is not an integer in ${DEADLINE_SEC_MIN}..${DEADLINE_SEC_MAX} — ignoring the settings default`);
+        }
+    }
+    const mt = env[HEADLESS_MAX_TURNS_ENV]?.trim();
+    if (mt) {
+        const n = parseIntInDomain(mt, MAX_TURNS_MIN, MAX_TURNS_MAX);
+        if (n !== null)
+            out.maxTurns = n;
+        else if (env.SEMA_DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error(`[sema] ${HEADLESS_MAX_TURNS_ENV}="${mt}" is not an integer in ${MAX_TURNS_MIN}..${MAX_TURNS_MAX} — ignoring the settings default`);
+        }
+    }
+    return out.timeoutSec !== undefined || out.maxTurns !== undefined ? out : undefined;
+}
+/**
+ * Resolve the limits for a headless `-p` submit: explicit flags > settings env defaults > none
+ * (= no stamp, today's behaviour). Merge is PER-KNOB: `--deadline 300` + SEMA_HEADLESS_MAX_TURNS=50
+ * yields {timeoutSec:300, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
+ */
+export function limitsForPrint(argv, env = hostEnv()) {
+    const parsed = parseLimitsArgv(argv);
+    if (!parsed.ok)
+        return parsed;
+    const fromEnv = headlessLimitsFromEnv(env);
+    const merged = { ...(fromEnv ?? {}), ...(parsed.limits ?? {}) };
+    const any = merged.timeoutSec !== undefined || merged.maxTurns !== undefined;
+    return { ok: true, ...(any ? { limits: merged } : {}), flaggedFlags: parsed.flaggedFlags };
+}
+/** True when the engine version string satisfies the limits-wire minimum (≥1.196.0). Unparsable ⇒ false. */
+export function versionSupportsLimits(v) {
+    const m = v ? /^(\d+)\.(\d+)\.(\d+)/.exec(v) : null;
+    if (!m)
+        return false;
+    const [a, b, c] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const [ma, mb, mc] = LIMITS_WIRE_MIN_ENGINE;
+    if (a !== ma)
+        return a > ma;
+    if (b !== mb)
+        return b > mb;
+    return c >= mc;
+}
+/**
+ * Version-gate probe (triage risk ③): GET `${baseUrl}/health`, read `version`, and return ONE honest
+ * stderr line when the engine is confirmed <1.196.0 — the caller prints it and SENDS ANYWAY (the old
+ * server drops the field server-side; warn, don't block). Returns undefined when the engine is new
+ * enough, unreachable, or self-describes no parsable version (can't confirm staleness — fail-soft
+ * silent; the release-pinned self-spawn lane never even reaches this probe).
+ */
+export async function engineLimitsSupportWarning(baseUrl, flaggedFlags, opts) {
+    const fetchImpl = opts?.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 1500);
+    try {
+        const res = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}/health`, {
+            method: 'GET',
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        const version = typeof body?.version === 'string' ? body.version : undefined;
+        // No version field = pre-1.96 engine — definitely older than 1.196.0, warn honestly.
+        if (versionSupportsLimits(version))
+            return undefined;
+        const flags = flaggedFlags.length > 0 ? flaggedFlags.join('/') : '--deadline/--max-turns';
+        return `[sema] engine ${version ?? '(unversioned, pre-1.96)'} does not support ${flags} (needs ≥1.196.0); the flag will be ignored by the engine`;
+    }
+    catch {
+        return undefined; // unreachable/timeout — cannot confirm staleness, stay silent
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/notifications.d.ts

@@ -90,6 +90,13 @@ export declare function dropQueuedNotificationsForRun(taskId: string): number;
  * steer-inject 的 task_notification 帧)即预标记,Channel A 对同 runId 的补发直接丢弃。
  */
 export declare function markEngineWorkflowNotified(runId: string): void;
+/** 跨通道去重的**读**口(适配器 workflow_complete 臂的发射门;cli 同域)。 */
+export declare function isEngineWorkflowNotified(runId: string): boolean;
+/** 「这个 run 的完成卡已入队」的**写**口(cli 侧等价物 = 两个 enqueue 函数内的 `cardEnqueuedRunIds.add`)。 */
+export declare function noteWorkflowCompletionCardEnqueued(runId: string): void;
+/** 台账序列化面(`exportLedger`)—— 只读快照,顺序 = 插入序。 */
+export declare function listNotifiedRuns(): string[];
+export declare function listWorkflowCompletionCardsEnqueued(): string[];
 export declare function isWorkflowCompletionCardEnqueued(runId: string): boolean;
 type WorkflowStatusProbe = (runId: string) => Promise<{
     terminal: boolean;

package/dist/notifications.js

@@ -215,6 +215,38 @@ export function markEngineWorkflowNotified(runId) {
     if (outstandingRuns.delete(runId))
         notifyOutstanding();
 }
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// B5 ①(0.7.0)—— **配对台账折回**([1857];记忆 paired-mechanisms-must-share-premise)。
+// 0.6.0 把 `notifiedRuns` / `cardEnqueuedRuns` 放在**适配器实例**上,而与它们配对的另一半全在
+// 本模块的 module 台账上:清账的 `dropQueuedNotificationsForRun`、记账的
+// `enqueueBgChildNotification` / `enqueueEngineWorkflowNotification`、以及 idle watcher 那条
+// (壳根本拦不到的调用点)。两半前提不共享 = 四个方向同时错:
+//   ① module 记过账 ⇒ 实例不知道 ⇒ 推送帧渲第二张卡(双卡)
+//   ② 宿主回钩写实例、drop 清 module ⇒ 实例只增不减 ⇒ 那一行永不上屏(a0110e88 复发)
+//   ③④ 跨通道去重两向失效 ⇒ 同一完成二次喂模型
+// 修法 = 台账**整体**回到 module(与 cli 的 module 级 Set 逐字同域),适配器只经下面这四个口读写;
+// 实例上只留 `renderedNotifications`(渲染去重,天然 per-session)与 `firedSubagentStartHookTaskIds`
+// (DIVERGENCE-6 有意的实例级)。
+// 🔴 多 session 宿主(web 一个页面两个会话)上本对台账是**进程级共享**的 —— 这与 cli 一致,
+//   且必须如此:队列 port、idle watcher、outstanding 药丸也都是进程级的,台账单独 per-session
+//   就又造出一对「前提不共享」的机制。
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+/** 跨通道去重的**读**口(适配器 workflow_complete 臂的发射门;cli 同域)。 */
+export function isEngineWorkflowNotified(runId) {
+    return notifiedRunIds.has(runId);
+}
+/** 「这个 run 的完成卡已入队」的**写**口(cli 侧等价物 = 两个 enqueue 函数内的 `cardEnqueuedRunIds.add`)。 */
+export function noteWorkflowCompletionCardEnqueued(runId) {
+    if (runId.length > 0)
+        cardEnqueuedRunIds.add(runId);
+}
+/** 台账序列化面(`exportLedger`)—— 只读快照,顺序 = 插入序。 */
+export function listNotifiedRuns() {
+    return [...notifiedRunIds];
+}
+export function listWorkflowCompletionCardsEnqueued() {
+    return [...cardEnqueuedRunIds];
+}
 /** 双通道「完成卡」去重(clay dogfood 2026-07-19 双通知案):与 notifiedRunIds(模型通知去重,
  *  external mark 也写它)**分键**——本集只由 probe 合成 enqueue 写入(workflow+bg agent 两族,
  *  对抗复审§1:bg 合成不写此集时 probe 先到→后到推送帧仍渲第二张卡)、只由推送帧渲染前读,

package/dist/sandboxWire.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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).
+ */
+export type SandboxSelection = {
+    mode: 'default';
+} | {
+    mode: 'auto';
+} | {
+    mode: 'explicit';
+    profile: string;
+};
+export type SandboxParseResult = {
+    ok: true;
+    sel: SandboxSelection;
+} | {
+    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).
+ */
+export declare function parseSandboxArgv(argv: 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;
+/**
+ * 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 (ai-agent-service main.ts:2323-2330, per-task-image.ts:52,
+ * server.ts:4651/4670) — 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

@@ -0,0 +1,138 @@
+/**
+ * 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).
+ */
+/** 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).
+ */
+export function parseSandboxArgv(argv) {
+    let sel = { mode: 'default' };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--')
+            break; // positionals — never flags
+        let raw;
+        if (a === '--sandbox') {
+            const nxt = argv[i + 1];
+            if (nxt === undefined || nxt.startsWith('-')) {
+                return { ok: false, error: USAGE_HINT };
+            }
+            raw = nxt;
+            i++; // consume the value token
+        }
+        else if (a.startsWith('--sandbox=')) {
+            raw = a.slice('--sandbox='.length);
+        }
+        else {
+            continue;
+        }
+        const v = 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,
+                error: `Invalid sandbox profile "${v}". Profile names cannot contain spaces — if you meant it as the prompt, ` +
+                    `pass --sandbox a profile name (or 'auto') first, or omit --sandbox to use the worker default image.\n` +
+                    USAGE_HINT,
+            };
+        }
+        if (v.length > MAX_PROFILE_LEN) {
+            return {
+                ok: false,
+                error: `sema: --sandbox profile must be at most ${MAX_PROFILE_LEN} characters (same rule the server enforces).`,
+            };
+        }
+        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}`;
+}
+/**
+ * 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 (ai-agent-service main.ts:2323-2330, per-task-image.ts:52,
+ * server.ts:4651/4670) — 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')
+        return undefined;
+    const msg = e.message;
+    if (e.status === 400 && msg.includes('only supported on the k8s sandbox backend')) {
+        return ('--sandbox <profile> only applies on k8s-lane workers; this engine runs a host/e2b sandbox lane, so the request was honestly rejected.\n' +
+            'Re-run without --sandbox (worker default image), or point the shell at a k8s-lane worker (sema cloud engine connect <url>).');
+    }
+    if (e.status === 400 && msg.includes('requires the image index')) {
+        return ('This worker has no sandbox image index configured (sema-registry backend absent), so per-task profiles cannot resolve.\n' +
+            'Re-run without --sandbox, or use a worker with the image index enabled.');
+    }
+    if (e.status === 404 && msg.includes('no published sandbox image for profile')) {
+        return 'No published image matches that profile for your principal. List what you can use: sema cloud images list';
+    }
+    if (e.status === 400 && msg.includes('not supported together with cascade/verify')) {
+        return '--sandbox cannot combine with cascade/verify submits in v1 (the per-task image would not bind to the sub-runs). Drop one of the two.';
+    }
+    return undefined;
+}

package/dist/scenarioWire.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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;
+    scenario?: string;
+} | {
+    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`).
+ */
+export declare function parseScenarioArgv(argv: 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;