@sema-agent/client-core 0.6.0 → 0.8.0

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;

package/dist/scenarioWire.js

@@ -0,0 +1,115 @@
+/**
+ * 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';
+/** 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`).
+ */
+export function parseScenarioArgv(argv) {
+    let scenario;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--')
+            break; // positionals — never flags
+        let raw;
+        if (a === '--scenario') {
+            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('--scenario=')) {
+            raw = a.slice('--scenario='.length);
+        }
+        else {
+            continue;
+        }
+        const v = 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,
+                error: `sema: --scenario got "${v.length > 48 ? `${v.slice(0, 48)}…` : v}" — that looks like your prompt, not a scenario name.\n` +
+                    'Put the flag AFTER the value form (--scenario=<name>) or keep the name and prompt as separate tokens.\n' +
+                    USAGE_HINT,
+            };
+        }
+        if (!SCENARIO_NAME_RE.test(v)) {
+            return { ok: false, error: USAGE_HINT };
+        }
+        scenario = v;
+    }
+    return { ok: true, ...(scenario ? { scenario } : {}) };
+}
+/**
+ * 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)
+        return parsed;
+    if (parsed.scenario)
+        return parsed;
+    const fromEnv = headlessScenarioFromEnv(env);
+    return { ok: true, ...(fromEnv ? { scenario: fromEnv } : {}) };
+}

package/dist/seam.d.ts

@@ -98,6 +98,20 @@ export type ChromeEvent = {
     taskId: string;
     status: string;
     outputPath?: string;
+}
+/**
+ * B5 新臂(#117a,E 层 Bash 分臂的**执行半场**)—— 模型发起的后台 Bash 回执被认出来了。
+ * 判定在库(`detectEngineBgShellReceipt`,纯文案锚定 + `run_in_background` 门);执行留宿主:
+ * 宿主消费义务 = ① 把 registration 发给自己的后台 shell 面板 store(壳 =
+ * `publishEngineBgShellPanelEvent`)② 登记「句柄 → 宿主 run」映射(壳 = `recordBgParentRun(
+ * taskId, getActiveEngineTaskId())`,[1501] A/B 寻址的硬证据)。
+ * 缺席 = ctrl+B 面板看不到这条后台命令(不是报错,是这一面在该宿主上哑掉)。
+ */
+ | {
+    kind: 'bgshell_register';
+    laneProof: LaneProof;
+    taskId: string;
+    registration: unknown;
 } | {
     kind: 'tasks_expand';
     laneProof: LaneProof;
@@ -165,8 +179,11 @@ export type ChromeEvent = {
  *  🔴 配对纪律([paired-mechanisms-must-share-premise]):这两件从「宿主义务」改成「库自持」是
  *     **整臂让位**,不是两边都做——宿主若仍照旧实现,两次 drop/clear 幂等无害,但**记号必须删**,
  *     否则下一棒会以为库没做。
- * 跨通道去重(「补发通道不得再注入模型一遍」)由**适配器自持台账**负责,不摊给宿主——
- * 见 adapt.ts 的 notifiedRuns / workflow_notification_enqueue 臂的发射门。
+ * 跨通道去重(「补发通道不得再注入模型一遍」)由**库自持**,不摊给宿主 —— B5 起台账回到
+ * `notifications.ts` 的 **module 级** `notifiedRunIds` / `cardEnqueuedRunIds`(0.6.0 曾放在适配器
+ * 实例上,与清账/记账的另一半不共享前提 = [1857] 那个缺口)。
+ * 🔴 宿主**不要**再在本臂上调 `markEngineWorkflowNotified` —— 库已在同一位置调过(幂等,
+ *   宿主照调无害,但记号该删:整臂让位,不是两边都做)。
  * 注:面板行 end 事件本身走 panel_task 臂、SubagentStop 走 subagent_lifecycle 臂,不重复。
  */
  | {
@@ -235,9 +252,25 @@ export type ChromeEvent = {
 }
 /**
  * 带外后台 workflow 完成推送(service 1.75 Path B:引擎**没有** server-side 注入,壳负责喂模型)。
- * 宿主消费义务:把 `message`(模型面 `<task-notification>` 正文,适配器已按 core 同形铸好)
- * 入「完成通知队列」,idle 时 auto-submit 给模型(CC RemoteAgentTask 先例,默认 'later' 优先级)。
- * 跨通道去重(同一 run 已由推送帧记账 ⇒ 本臂根本不会发)由适配器台账保证,宿主无需再判。
+ * 宿主消费义务 = **只有投递一件**:把 `message`(模型面 `<task-notification>` 正文,适配器已按 core
+ * 同形铸好)入「完成通知队列」,idle 时 auto-submit 给模型(CC RemoteAgentTask 先例,默认 'later'
+ * 优先级)。
+ *
+ * 🔴 **切缝 = 「门归包、投递归宿主」**([1857] Path B 回归的定谳形,B5 壳侧收批实撞;
+ *   [paired-mechanisms-must-share-premise]):`workflow_complete` 臂在**发本臂之前**已经在库内
+ *   一次做完三件 —— ① 跨通道去重门 `isEngineWorkflowNotified(runId)` 早退;
+ *   ② `markEngineWorkflowNotified(runId)`;③ `noteWorkflowCompletionCardEnqueued(runId)`
+ *   (adapt.ts `case 'workflow_complete'` 三行连坐)。⇒ 宿主这三件**一件都不要再做**:
+ *   · 绝不要借任何「自带同一道门」的宿主老函数投递(cli 的 `enqueueEngineWorkflowNotification()`
+ *     首行就是 `if (notifiedRunIds.has(runId)) return`,读的正是库刚写的记账 ⇒ **恒早退,
+ *     一条都进不了队列**,两半各自都对、组合零结果);投递要用**裸入队**口。
+ *   · 也不要再补 `noteWorkflowCompletionCardEnqueued` —— 库已落(幂等 Set.add,宿主照落无害,
+ *     但记号该删:整臂让位,不是两边都做)。
+ *     🔴 **这条建议在 B6 之前是不安全的,别照抄旧结论**:库里那一行原本写在 `yield` **之后**,
+ *     消费者早退时永不执行 ⇒ 那时壳 `upstreamBridge.ts:488` 的显式落记号是**真的在补一个洞**。
+ *     B6 已把它移到 `yield` 之前(adapt.ts `case 'workflow_complete'`,pure 门「早退 ⇒
+ *     cardEnqueued 仍落」先红后绿钉住)⇒ 库侧现在**无条件**落,壳那一行才成为可删的冗余。
+ *   ⇒ 判据只能锚在「队列里到底有没有多出这一条」,不能锚在「谁调了什么」。
  */
  | {
     kind: 'workflow_notification_enqueue';
@@ -261,6 +294,20 @@ export type ChromeEvent = {
     toolUseId: string;
     input: unknown;
 }
+/**
+ * B5 —— 同一台账的**第二个来源**:core 1.217([379])的 `task` / `task-list` structured 权威全量态。
+ * `source:'tool_use'` 那条是旧引擎兜底(从 input 重建),本条是引擎真实 id 的精确同步。
+ * 宿主消费义务:壳 = `handleEngineTaskStructured(structured)`(两路经 engineToShellTaskId 收敛)。
+ * 🔴 两条**不是**二选一 —— 旧引擎只有前者、新引擎两者都来且后者更准,宿主按幂等处理即可。
+ */
+ | {
+    kind: 'task_ledger_sync';
+    laneProof: LaneProof;
+    source: 'structured';
+    /** `'task' | 'task-list'`(白名单已在库内判过)。 */
+    structuredType: string;
+    structured: unknown;
+}
 /**
  * B3 新臂 ①(T38 三清的第三清 + T57 五处断闸的第五处)—— E12「下一步可问什么」建议**批**。
  * `suggestions: null` = 作废(turn 开场必发一次:上一轮的建议对新上下文是噪声,挂着不掉会让人

package/dist/seam.js

@@ -13,6 +13,7 @@ export const CHROME_ARMS = [
     { kind: 'retry_status', required: false, duty: '渲/清 spinner 的重试覆盖层' },
     { kind: 'panel_task', required: true, duty: 'publishEngineAgentPanelEvent(event) 原样转发' },
     { kind: 'bgshell_settle', required: true, duty: '后台 shell 面板行落终态(含 outputPath)' },
+    { kind: 'bgshell_register', required: true, duty: '后台 shell 面板行建行 + 登记「句柄→宿主 run」' },
     { kind: 'tasks_expand', required: false, duty: '展开 ctrl+t 任务面板' },
     { kind: 'thinking_activity', required: false, duty: '开/收活体 "∴ Thinking…" 行' },
     { kind: 'request_start', required: false, duty: 'spinner 置 requesting 态' },
@@ -21,8 +22,20 @@ export const CHROME_ARMS = [
     { kind: 'attachment', required: false, duty: '渲 attachment 行(必须带 default 臂)' },
     { kind: 'notification_terminal', required: false, duty: '可选 UI 提示(记账已由库自持)' },
     { kind: 'subagent_lifecycle', required: true, duty: 'fire SubagentStart/Stop hooks(去重已由库解)' },
-    { kind: 'workflow_notification_enqueue', required: true, duty: 'message 入完成通知队列,idle 时喂模型' },
-    { kind: 'task_ledger_sync', required: true, duty: '按 toolUseId 幂等落 TaskCreate/TaskUpdate' },
+    {
+        kind: 'workflow_notification_enqueue',
+        required: true,
+        // 门/notified 记账/cardEnqueued 记号三件已由库在发臂前做完 ⇒ 宿主只投递,且必须用**裸入队**口。
+        duty: 'message 裸入完成通知队列(不要用自带去重门的老函数),idle 时喂模型;门与两条记号归库',
+    },
+    {
+        kind: 'task_ledger_sync',
+        required: true,
+        // 🔴 **两个 source 都要接**(B6 核实:同一张任务卡实测出两条)——`tool_use` 是卡刚开时的
+        // 乐观建行(旧引擎只有它),`structured` 是引擎回来的权威全量态(带真实 id/状态)。
+        // 只接前者 ⇒ 引擎真实 id 永不回填;只接后者 ⇒ 面板要等工具跑完才出现。幂等键 = toolUseId。
+        duty: '按 toolUseId 幂等落 TaskCreate/TaskUpdate —— source 的 tool_use(乐观建行)与 structured(权威全量态)两条都要接',
+    },
     { kind: 'inline_task_stats', required: true, duty: 'tick/settle/settle_all 转发给 engineInlineTaskStats' },
     { kind: 'prompt_suggestions', required: false, duty: '推 composer 上方 chips(绝不回喂模型)' },
     { kind: 'last_turn_usage', required: true, duty: '落最近一次 turn 真 usage(statusline 回落源)' },

package/dist/subagent/engineCompactWire.d.ts

@@ -0,0 +1,12 @@
+/** Test/introspection hook. */
+export declare function isEngineCompactPending(): boolean;
+/** Test hook: reset the cached capability (fresh engine / respawn). */
+export declare function resetManualCompactCapability(): void;
+/**
+ * The /compact command's live half. Mid-turn: fire now. Idle: arm for the next run bind.
+ * Returns what it did (for the command's display line / tests). No-op ('offline') without a live
+ * wire; 'unsupported' when the engine's capabilities said manualCompact:false ([488] TOC-local) —
+ * the client-side projection compaction still runs, but the ENGINE session context does not shrink.
+ */
+export declare function requestEngineCompact(): 'fired' | 'armed' | 'offline' | 'unsupported';
+export declare function onEngineTaskBound(taskId: string): void;