@sema-agent/server 7.43.0 → 7.44.0

package/dist/question.js

@@ -1,56 +1,14 @@
-/**
- * §4④ tool-panorama — AskUserQuestion LIVE-stream HITL, the SERVICE side of core's `RunnerDeps.onQuestion`
- * seam (core `ask-question.ts`, design/64 §5.2). The SIBLING of {@link import("./elicitation.js").ElicitationCoordinator}:
- * elicitation is an inbound-MCP-server ask; this is the AGENT's own `AskUserQuestion` tool (a structured multiple-choice
- * question to the end user). core EMITS the call and hands it to `onQuestion`; the deployment routes it to a live human
- * over the run's stream and returns their {@link QuestionAnswer}. The durable-disconnected-human case is ALREADY wired
- * separately (`createDurableQuestionPolicy` + `QUESTION_AWAITS_RESUME` on the durable leg — the question SUSPENDS and a
- * resume carries the answer); this is the LIVE-only, same-replica, `steer()`-class half.
- *
- * The service is pure WIRE glue (the abstraction is core's): forward the questions to whoever tails the run's stream (a
- * `question` SSE frame), park a promise, resolve it from `POST /v1/questions/:id/respond`. 🔒 SECURITY: the ANSWER fence
- * is CORE's — core's AskUserQuestion tool echoes a `selected` value ONLY if it is one of the offered option labels
- * (`selected ⊆ options`) and wraps the free-text `note` in an untrusted-DATA fence (design/80 D-F), so a wire answer can
- * never be read as instructions. The service therefore does NOT re-fence the answer; it validates only the outer SHAPE
- * (the HTTP boundary) and REDACTS secrets from the model-authored QUESTION text before it is persisted/streamed (the
- * same redact-at-write contract as elicitation's `message`/tool outputs — the question is shown to a human, never
- * re-fed to a model, so no `delimitUntrusted` is needed on it). Deployment responsibilities core delegates: THROTTLE
- * (bound concurrency/total/ttl per run — an over-eager agent could flood the human).
- *
- * 🔴 VERDICT vs LANDING are separate jobs (#166 裁1). This coordinator is the deployment's HONEST reporter of one fact:
- * "no human answered this". Every arm with no real human answer — no run context, the run aborted, the throttle window
- * is spent, the question cannot be presented, the TTL expired (incl. the run-exit sweep) — returns core's
- * `{kind:"unavailable"}`. It NEVER synthesizes an empty answer set: an empty `{answers:[]}` reads to core as "a human
- * was here and picked nothing", which on a durable deployment consumes the pending approval and hands the model a
- * fabricated human verdict instead of parking the question where an operator can still answer it. Choosing the landing
- * is CORE's job: a durable leg parks a checkpoint (operator answers later via decide), a non-durable leg continues with
- * the `declined_unavailable` synthetic-continuation card (the model is told nobody is reachable and proceeds on its own
- * judgment — a run with no human still never hangs). Only a REAL human answer returns a {@link QuestionAnswer}.
- *
- * ROUTING mirrors elicitation: `onQuestion` lives on the SINGLETON runner's `RunnerDeps` (the request carries no taskId),
- * so the run leg establishes a per-run AsyncLocalStorage context (taskId throttle key, owner respond-gate, `emit`
- * closure). `node:async_hooks` propagates it through every await; no context ⇒ unavailable (never a hang).
- */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { uuidv7 } from "@sema-agent/core";
 import { redactDeep } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
-/** Size bound on the model-authored questions payload before it is persisted to the durable log + streamed (parity
- *  with elicitation's MAX_ELICIT_* — an over-large questions blob amplifies into the socket/log). Over the cap ⇒ the
- *  questions are dropped and the ask reports unavailable (a question the human can't see can't be answered). */
 const MAX_QUESTIONS_BYTES = 16384;
 export const DEFAULT_QUESTION_THROTTLE = {
     maxConcurrentPerRun: 2,
     maxTotalPerRun: 20,
     ttlMs: 5 * 60_000,
 };
-/** The honest "nobody answered this" outcome. Frozen + shared: it is pure data core reads through
- *  `classifyQuestionOutcome`, and it must never be confused with an empty ANSWER (which claims a human chose nothing
- *  and, on a durable leg, spends the approval that park would have preserved). */
 const UNAVAILABLE = Object.freeze({ kind: "unavailable" });
-/** Validate the respond body = core's {@link QuestionAnswer}. `selected`/`note` are OPAQUE passthrough (core fences
- *  them: `selected ⊆ options`, `note` untrusted-fenced) — we validate only the outer SHAPE (answers[] of {header,
- *  selected:string[], note?}), never the option semantics. */
 export function parseQuestionResponse(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
         return { ok: false, error: "body must be an object" };
@@ -73,9 +31,6 @@ export function parseQuestionResponse(body) {
     }
     return { ok: true, value: { answers: out } };
 }
-/** redactDeep + size-bound the UNTRUSTED model-authored questions before they are persisted/streamed (a question's
- *  free-text — question/header/option label+description — can echo a secret from the model's context). Over the byte
- *  cap OR unserializable ⇒ undefined (drop; the ask reports unavailable). */
 function boundQuestions(questions) {
     const redacted = redactDeep(questions);
     try {
@@ -87,12 +42,6 @@ function boundQuestions(questions) {
     }
     return redacted;
 }
-/**
- * Coordinates AskUserQuestion HITL for the singleton runner. Process-local + same-replica (the pending map is in memory,
- * like ElicitationCoordinator / steerableRuns): a respond that lands on another replica finds nothing → 404. Present
- * (passed into `RunnerDeps.onQuestion` + the respond route) ONLY when `ASK_QUESTION_ENABLED` — absent ⇒ core mounts the
- * AskUserQuestion tool with no seam at all (`seam_absent` continuation; the model just can't get a live answer).
- */
 export class QuestionCoordinator {
     als = new AsyncLocalStorage();
     pending = new Map();
@@ -101,8 +50,6 @@ export class QuestionCoordinator {
     constructor(throttle = DEFAULT_QUESTION_THROTTLE) {
         this.throttle = throttle;
     }
-    /** Run `fn` with the per-run question context ambient. On exit, release any still-pending question for this run (a
-     *  live-only question cannot outlive its leg → unavailable) and drop the run's counters (no leak). */
     runWithContext(ctx, fn) {
         return this.als.run(ctx, async () => {
             try {
@@ -117,30 +64,20 @@ export class QuestionCoordinator {
             }
         });
     }
-    /** `RunnerDeps.onQuestion`. core calls this when the agent's AskUserQuestion tool fires; the resolved outcome is what
-     *  core acts on — a {@link QuestionAnswer} ONLY when a human really answered, otherwise `{kind:"unavailable"}` (core
-     *  then parks on a durable leg / continues with the `declined_unavailable` card on a non-durable one; either way the
-     *  run never hangs). Arrow property so it can be passed as `onQuestion: coordinator.question` with `this` bound. */
     question = async (req, signal) => {
         const ctx = this.als.getStore();
-        // No run context (a leg not wrapped by runWithContext — synchronous /v1/tasks, verify/cascade, or a leader sub-task
-        // with no live stream) ⇒ nobody to ask. Sub-tasks run in the parent's ALS frame → a child's question inherits the
-        // top-level run's ctx (one human, one stream, one throttle budget), same as elicitation.
         if (!ctx)
             return UNAVAILABLE;
-        // Aborted (call signal or the run's own): whatever comes back has no consumer, so claiming a human answered is a lie.
         if (signal?.aborted || ctx.abortSignal?.aborted)
             return UNAVAILABLE;
-        // THROTTLE (service's job — core imposes none): bound concurrency + total. Breach ⇒ unavailable, never a denial and
-        // never a fabricated answer — a spent window is a "not now", which is exactly what park/continue is for.
         const rc = this.countersFor(ctx.taskId);
         if (rc.inflight >= this.throttle.maxConcurrentPerRun || rc.total >= this.throttle.maxTotalPerRun)
             return UNAVAILABLE;
         const questions = boundQuestions(req.questions);
         if (!questions)
-            return UNAVAILABLE; // over-cap / unserializable → can't show it → nobody can answer it
+            return UNAVAILABLE;
         const id = uuidv7();
-        rc.inflight += 1; // reserve the concurrency slot; total charged only on a successful emit
+        rc.inflight += 1;
         let done = false;
         let timer;
         let resolveAnswer;
@@ -155,33 +92,17 @@ export class QuestionCoordinator {
             ctx.abortSignal?.removeEventListener("abort", onAbort);
             this.pending.delete(id);
             rc.inflight = Math.max(0, rc.inflight - 1);
-            // stash the outcome for the completion frame emitted below (after the await returns)
             lastOutcome = outcome;
             resolveAnswer(a);
         };
         let lastOutcome = "unanswered";
         const onAbort = () => settle(UNAVAILABLE, "unanswered");
-        // TTL: the human walked away. Release as unavailable — core decides whether that parks (durable, operator can still
-        // answer) or continues (non-durable); holding core past the window is not one of the choices.
         timer = setTimeout(() => settle(UNAVAILABLE, "unanswered"), this.throttle.ttlMs);
         timer.unref?.();
         signal?.addEventListener("abort", onAbort, { once: true });
         ctx.abortSignal?.addEventListener("abort", onAbort, { once: true });
-        // Register BEFORE emitting so a (fast) respond can never miss the entry.
         this.pending.set(id, { settle, owner: ctx.owner, taskId: ctx.taskId });
-        // Emit the OPEN frame AWAITED so its durable append is ORDERED ahead of the answer/completion/terminal appends (a
-        // fire-and-forget append can commit out of seq order and be skipped by the monotonic events-tail cursor). A FAILED
-        // emit settles unavailable (nobody can answer a frame that never arrived) and must NOT burn the per-run total.
-        // 🔴 RACED against the settlement (codex 复审 R2-high): a STALLED delivery (a durable append that never settles, a
-        // half-open socket) is a third shape next to ok/threw, and a bare `await ctx.emit` on it outlives TTL *and* abort —
-        // settle would resolve `answerP` while this frame is still parked on the emit, so `question()` never returns, core's
-        // callTool never unblocks and the leg cannot even reach its own cleanup. "The window always releases" has to hold
-        // for the stalled shape too, so the await ends at whichever comes first. Ordering is unchanged on the normal path
-        // (the settlement is still pending there, so the emit is still fully awaited).
-        // The loser of the race keeps its own handlers — an emit that rejects AFTER the race must not surface as an
-        // unhandled rejection.
         const emitted = (async () => {
-            // [4851]③ 窗三键与上面 setTimeout 用同一个 ttlMs 铸(单源;壳倒计时永不与真释放口径分歧)。
             const now = Date.now();
             return ctx.emit({ type: "question", questionId: id, questions, serverNowMs: now, expiresInMs: this.throttle.ttlMs, expiresAtMs: now + this.throttle.ttlMs });
         })()
@@ -191,23 +112,10 @@ export class QuestionCoordinator {
             rc.total += 1;
         }
         else if (delivery === "failed") {
-            // #157(codex 复审 MEDIUM,2026-08-07):投递失败 ⇒ 人在环这道门被**一次故障**跳过,模型自己往下判。
-            // 「绝不把 run 挂死」是刻意的产品姿态,所以方向不改;但它是 P-DEBT 不是合法兜底——债要在遥测里显形。
-            // #166 后本臂结算成 unavailable(而非空答):留痕语义不变(一次投递故障仍可能让人在环被跳过——非
-            // durable 形 core 合成续跑),durable 形则改由 core park,债的方向与本记账口径一致。
             recordFailOpen("server.question.open-frame-undelivered", `question=${id}`);
             settle(UNAVAILABLE, "unanswered");
         }
-        // delivery==="stalled":窗已由 TTL/abort/清扫结算,这一问就此让位;账在下面那个迟到臂里补(投递还没
-        // 判出成败,现在既不能计费也不能记债)。
         const answer = await answerP;
-        // Completion breadcrumb (dialog dismiss) — FIRE-AND-FORGET so a slow durable append can never delay returning the
-        // answer to core. Best-effort (the shell already has the answer via respond), but CHAINED BEHIND the open frame and
-        // BRANCHED on how that frame ended (codex 复审 R3):
-        //  · 送达(含**迟到**送达)⇒ 人真看见了这张卡:补烧总量额度(否则「反复悬挂再落地」是一条绕过刷屏帽的
-        //    路子),再发消卡帧把它消解掉;
-        //  · 投递失败(含**迟到**失败)⇒ 没有卡可消解,发消卡帧只会在流里留一条无主帧;此时补记那条 P-DEBT
-        //    留痕(同步臂已经记过的不会重复:那条腿的 delivery 不是 stalled)。
         void emitted
             .then((result) => {
             if (result === "failed") {
@@ -219,17 +127,10 @@ export class QuestionCoordinator {
                 rc.total += 1;
             return ctx.emit({ type: "question_complete", questionId: id, outcome: lastOutcome, serverNowMs: Date.now() });
         })
-            // #157:F 类兜底(丢的是收尾渲染,不是答案)——合法,但必须留痕,否则"面包屑成片消失"只能靠
-            // 用户报"对话框不消解"发现。
             .catch(() => recordFailOpen("server.question.complete-breadcrumb-dropped", `question=${id}`));
         return answer;
     };
-    /** `POST /v1/questions/:id/respond` — resolve a parked question with the shell's answer. Owner-gated with a 404 (no
-     *  existence oracle): a non-owner AND an unknown id (answered / expired / wrong replica) both get 404. Returns the
-     *  HTTP {status, body}; the HTTP layer owns auth (gatedPrincipal + REQUIRE_PRINCIPAL) before calling. */
     respond(id, principal, body) {
-        // Validate the body BEFORE the lookup (steer/elicit parity): a bad body is the caller's error regardless of run
-        // state, so 400 is existence-independent (no 400-vs-404 existence oracle).
         const parsed = parseQuestionResponse(body);
         if (!parsed.ok)
             return { status: 400, body: { error: parsed.error, errorCode: "request.body_shape" } };
@@ -240,19 +141,9 @@ export class QuestionCoordinator {
         entry.settle(parsed.value, "answered");
         return { status: 200, body: { questionId: id, delivery: "applied" } };
     }
-    /** Test/observability hook: number of currently-parked questions. */
     pendingCount() {
         return this.pending.size;
     }
-    /** #152 ([2703] 案二):durable 部署上的 AskUserQuestion 判决探针——本调用点是否处在某条**投递得到人的**
-     *  活流腿上(runWithContext 包裹的 bg/SSE 腿=true;sync /v1/tasks、verify/cascade、durable resume 驱动=false)。
-     *  resolve-spec 的 durable question policy 用它在**判决时**分腿:有活流 ⇒ allow(问活人),无 ⇒
-     *  ask(durable park)。ALS 让这个判断天然 per-leg,policy 组装期不必预知腿别。
-     *  🔴 判据是「投递面此刻可达」而不只是「ALS 在场」(复审 A1):detach 腿断连后 run 仍在本作用域里跑,
-     *  只判 ALS 会把一条谁也收不到的问题判成 allow——挂满 ttl 后以 unavailable 结算,非 durable 形 core
-     *  就此合成续跑,活人再没机会答;而 park 才是它该走的腿。
-     *  谓词缺席 ⇒ 恒可达(后台腿的 durable events tail 语义)。谓词本身抛错按不可达处理:判决面
-     *  fail-closed 到 park(park 可由运维补答,续跑掉的问题不可回收)。 */
     hasLiveContext() {
         const ctx = this.als.getStore();
         if (ctx === undefined)

package/dist/resource-suspend.js

@@ -1,21 +1,3 @@
-/**
- * design/80 seam #2 — the resource/preempt durable-suspend opt-in decision (design/74 "失败≠没做完" third state).
- *
- * Pure so it is unit-testable in isolation (the spec is otherwise assembled inside main.ts's bootstrap). When a
- * task opts in, a budget/turns/walltime limit OR a scheduler preempt durably SUSPENDS the task (resumable via
- * `POST /v1/assistant/tasks/:id/resume`) instead of FAILING; absent ⇒ a limit still FAILS.
- *
- * 🔴 EXCLUDE verify/cascade tasks. Core runs their implementation via `runWithVerification`/`runCascade`, which
- * map an inner durable suspend to a FAILED result (`errorCode: "unexpected.suspended"`,内层 status
- * "needs_review" 时铸 `"unexpected.needs_review"` —— 真源是 core `agents/suspend-guard.js` 的
- * `mapNestedSuspend`;`suspended.*` 三码是 bg 子代/委派报告面的词,不落在这条 TaskResult 腿上). The service would then
- * `setTerminal(failed)` while core had already minted a pending `resource_limit` checkpoint + suspended the
- * remote VM — ORPHANING both (the run row is terminal, so nothing resumes them). So a resource-limit hit on a
- * verify/cascade task must FAIL CLEANLY (no suspend), exactly as before the flag. This exclusion is the SAME
- * boundary the `preemptSignal` wiring enforces in runs.ts (stream-path only), so eligibility and the signal stay
- * aligned. (Adversarial review wtyc7ist3 HIGH finding: without this, enabling RESOURCE_SUSPEND leaks a suspended
- * VM + checkpoint on every verify/cascade task that hits a resource limit.)
- */
 export function resourceSuspendOptIn(opts) {
     if (!opts.enabled || opts.isVerify || opts.isCascade)
         return undefined;

package/dist/router/route-orchestration.js

@@ -1,51 +1,13 @@
-/**
- * The A value router — cash out the S1 supervisor value verdict (sema-internal server/docs/S1-VALUE-VERDICT.md §6.3) into a per-task
- * orchestration decision: run a task as `single` / `supervisor` / `team`.
- *
- * The verdict, in one line: **competent tasks have SUP/TEAM dominated (pure overhead) ⇒ default single; the real
- * supervisor value is (a) DANGER backstop (SUP prevention gate-deny > TEAM fan-out which AMPLIFIES danger ×K) and
- * (b) STRUCTURAL view-gap (goal-keeping / ask-aggregation, universally useful).** So this router is CONSERVATIVE
- * by construction:
- *   - default **single** (escalation is never free — the verdict measured it as pure overhead on competent work);
- *   - escalate to **supervisor** ONLY on a positive (a)-danger or (b)-structural signal;
- *   - NEVER auto-select **team** (fan-out is dominated everywhere tested AND amplifies danger; team stays
- *     caller-explicit — a deliberate `council`/`debate`/`team` request, or the `/v1/leader` endpoint).
- *
- * 🔴 ALL signals are DETERMINISTIC (config / mounted tools / exec-env isolation / autonomy / delegation). There is
- * NO LLM "difficulty" judge in the routing decision — the verdict's measurement-integrity rule (design/89 §2.2.1):
- * an LLM judge is a GATE inside an arm, NEVER the routing metric (it would make the router un-auditable + gameable).
- *
- * Pure + unit-testable. The decision is VALIDATED empirically against the S1 harness (a ROUTER arm that runs the
- * router's chosen arm per trap; the objective hidden-test oracle confirms danger→SUP prevents + competent→single
- * is not-worse) BEFORE it is wired into the live task path — never ship an unvalidated router.
- */
 import {} from "@sema-agent/core";
-/**
- * The routing decision (pure). Order matters: explicit caller choice first, then (a) danger, then (b) structural,
- * else the single default. `team` is NEVER produced here — it only ever appears via {@link RoutingSignals.explicitMode}.
- */
 export function routeOrchestration(s) {
-    // 1. Caller-explicit wins — a deliberate council/debate/team request (or the /v1/leader endpoint) is intent.
     if (s.explicitMode)
         return { mode: s.explicitMode, reason: `explicit:${s.explicitMode}` };
-    // 2. (a) DANGER → supervisor prevention. The verdict's strongest value: gate-deny PREVENTS (SUP) beats
-    //    fan-out which AMPLIFIES the danger ×K (TEAM) and even beats single's after-the-fact exposure.
     if (s.dangerousCapability)
         return { mode: "supervisor", reason: "danger:prevention-gate" };
-    // 3. (b) STRUCTURAL → supervisor. Goal-keeping (worker local view vs supervisor global blueprint) +
-    //    cross-subtask ask-aggregation — universally useful when the task delegates / runs long.
     if (s.needsGoalKeeping)
         return { mode: "supervisor", reason: "structural:goal-keeping" };
-    // 4. Default SINGLE — competent tasks: SUP/TEAM measured as pure overhead (dominated). Escalation is not free.
     return { mode: "single", reason: "default:single" };
 }
-/**
- * Derive the routing signals from a task's resolved context — DETERMINISTIC. The danger rule is CONSERVATIVE and
- * fail-safe: a `read-only` task cannot harm (no escalation); EGRESS / irreversible-external capability is danger
- * regardless of sandboxing (it escapes the sandbox); plain write/exec is danger ONLY on a non-isolated env (an
- * isolated sandbox contains it + is torn down). The exact threshold is the one tunable knob — validated
- * empirically against the S1 harness, not guessed.
- */
 export function deriveRoutingSignals(ctx) {
     const readOnly = ctx.autonomy === "read-only";
     const dangerousCapability = !readOnly && (ctx.canEgress || (ctx.canWriteOrExec && !ctx.isolatedExecEnv));
@@ -55,41 +17,18 @@ export function deriveRoutingSignals(ctx) {
         needsGoalKeeping: ctx.delegatedOrLongHorizon,
     };
 }
-/**
- * Service-facing convenience: map a /v1/tasks task's DETERMINISTIC facts → a routing decision (the service signal
- * derivation + {@link deriveRoutingSignals} + {@link routeOrchestration} in one tested call; main.ts's resolveSpec
- * calls this). Signal mapping:
- *  - `isolatedExecEnv` ⟺ a sandboxed remote-exec backend (`e2b`/`k8s` Kata) — `ssh`/`host`/`adb` are NOT isolated.
- *  - hand tools (write_file/bash) are mounted only when an executionEnv exists AND hands aren't read-only/plan.
- *  - `canEgress` is left false in v1 (per-tool egress detection deferred; danger derives from non-isolation).
- *  - `delegatedOrLongHorizon` is false on the single-task path (the (b) value lives on the /v1/leader path).
- */
 export function routeServiceTask(input) {
     const readOnlyHands = input.autonomy === "read-only" || input.autonomy === "plan";
     return routeOrchestration(deriveRoutingSignals({
         ...(input.explicitTeam ? { explicitMode: "team" } : {}),
         ...(input.autonomy ? { autonomy: input.autonomy } : {}),
         canWriteOrExec: input.hasExecutionEnv && !readOnlyHands,
-        // 🔴 v1 EXPLICITLY-ACCEPTED LIMITATION (review MEDIUM): `canEgress` is false here, so an isolated sandbox
-        // with outbound network (e2b defaults internet ON) is NOT auto-routed to SUP for egress. Deriving danger
-        // from network-PRESENCE would over-escalate (a routine `npm install` task needs network) — defeating the
-        // verdict's default-single. The real egress danger is IRREVERSIBLE EXTERNAL actions (git push to a real
-        // repo, a deploy), which are TOOL-specific, not network-presence, and not cleanly detectable here. When a
-        // per-tool egress/irreversibility signal is wired (k8s P3 egress + tool marks), set this from it.
         canEgress: false,
         isolatedExecEnv: input.isolatedExecEnv,
         delegatedOrLongHorizon: false,
     }));
 }
-/** VM-isolation runtime classes — a REAL sandbox boundary (separate kernel). Plain `runc` / `""` / unknown share
- *  the host kernel ⇒ NOT isolated. */
 const VM_ISOLATION_CLASSES = new Set(["kata", "kata-qemu", "kata-clh", "kata-fc", "gvisor", "runsc"]);
-/**
- * Resolve whether a task's execution env STRONGLY isolates side effects (a VM/kernel boundary the sandbox tears
- * down). FAIL-CLOSED (review HIGH): a `k8s` backend is isolated ONLY with a VM-isolation `runtimeClass`
- * (kata-x or gvisor) — a runc downgrade (`runtimeClass: ""` / `runc` / unknown) is NOT isolated (shared kernel,
- * container escape). `e2b` is a Firecracker microVM (isolated). `host`/`ssh`/`adb` and anything unknown ⇒ NOT isolated.
- */
 export function isIsolatedExecEnv(provider, runtimeClass) {
     if (provider === "e2b")
         return true;
@@ -99,23 +38,7 @@ export function isIsolatedExecEnv(provider, runtimeClass) {
     }
     return false;
 }
-/** The write-capable hand tools the SUP posture gates DIRECTLY (Bash is gated via `shellGate`). Q6 (core 1.161):
- *  CC-aligned tool names (was edit_file/write_file). NotebookEdit (core 1.163) is the same fs-mutation class — it
- *  edits a `.ipynb` on the real fs, so it MUST be gated too, else a SUP-routed (capability-danger) task could mutate
- *  a notebook ungated (the exact "write tool bypasses the SUP gate" hole the review-HIGH closed for Edit/Write).
- *  Curated, NOT derived from HAND_TOOL_EFFECTS: that taxonomy is replay-safety (Write="idempotent"; Bash="write" but
- *  shell-gated), not "is an fs mutation". CANONICAL names only (core 1.202 retired MultiEdit into an Edit alias —
- *  (5.0.0:折叠面退役——重放的旧名调用由 core roster 层响亮 miss,不再折到 "Edit";raw 直比)
- *  gated without a stale alias entry here). */
 const WRITE_HAND_TOOLS = new Set(["Edit", "Write", "NotebookEdit"]);
-/**
- * The TaskSpec overrides for the SUP prevention posture (mode=supervisor). Applied via `tightenTaskSpec`
- * (tighten-only — composes with the deployment baseline, never loosens):
- *  - `shellGate: "always"` — gate every `Bash` as an irreversible_ask (the verdict's gate-deny on the shell).
- *  - `toolPolicy` — ALSO ask on the direct write hand tools `Edit`/`Write` (review HIGH: shellGate alone
- *    leaves a non-isolated SUP task able to mutate the real fs via write tools ungated). The worker's existing
- *    approval machinery (durable suspend / poll) enforces the `ask` — same precondition as `shellGate:"always"`.
- */
 export function supPostureOverrides() {
     const ask = (toolName) => ({ action: "ask", message: `${toolName} gated by supervisor routing (capability-danger task)`, decisionReason: "rule" });
     const writeGate = {

package/dist/rules-consent.d.ts

@@ -107,7 +107,26 @@ export type RuleImportRedeemed = {
     detail: string;
     retryable?: true;
 };
-/** 卡道兑付的结果。 */
+/**
+ * #340([4763])—— 一次卡道兑付**要兑的是什么**:两个显式臂,永不折叠。
+ *
+ * 🔴 判别式联合而不是「一个文本 + 一个布尔」:两个臂的文本**含义不同**——候选臂的串是「卡上第几条」的
+ * 定位键(对不上 ⇒ `rule_not_offered`,语义一个字不变),编辑臂的串是**人自己写的规则**(由 core 的
+ * 卡编辑面校验 + 覆盖门判)。同一个字段两种含义会让下一个读者(和下一次改动)分不清哪条路上该做哪道门。
+ */
+export type CardRuleRedemption = 
+/** 人**点了卡上的某条候选**:文本用来在引擎铸的候选表里定位下标。 */
+{
+    kind: "offered";
+    ruleText: string;
+}
+/** 人在卡上**手改了规则文本**(core 的 card-edit 面:同一条已鉴权确认通道,`editedCandidate`)。 */
+ | {
+    kind: "edited";
+    text: string;
+};
+/** 卡道兑付的结果。`canonical` = **真正落盘**的那条规则文本(编辑臂上它可能与人敲的原字节不同 ——
+ *  core 会把 `Bash(adb *)` 规范成 `Bash(adb:*)`;界面要回显的是这一份,不是输入框里的那一份)。 */
 export type CardRulePersisted = {
     ok: true;
     rule: string;
@@ -115,7 +134,25 @@ export type CardRulePersisted = {
     alreadyRedeemed: boolean;
 } | {
     ok: false;
-    reason: "no-candidates" | "unknown-candidate" | "confirm-refused" | "redeem-refused";
+    reason: "no-candidates" | "unknown-candidate" | "confirm-refused" | "redeem-refused"
+    /** #340:编辑面**在这只卡上用不了**——卡没有绑定锚(`boundInputHash` 缺席 ⇒ 无从证明「我编辑的
+     *  是显示了这条命令的那张卡」),或这台部署没有打开编辑面。与下面那个词刻意分家:这个说的是
+     *  「别再渲那个输入框」,那个说的是「你写的这条不行,改一下再来」——壳要做的事完全相反。 */
+     | "edit-unsupported"
+    /**
+     * #340:人写的文本**被引擎的门拒了**——共享校验器不认这个拼写,或它不覆盖本次被裁决的命令
+     * (「编辑可以更宽,但不许换成另一条授权」)。
+     *
+     * 🔴 **这一格不是「重试就好」**(codex 对抗复审 [medium],验真后按实况改词):兑付发生在裁决
+     * **落定之后**(那条顺序是硬的 —— 一次没有生效的裁决不该留下一条永久规则),所以拿到这个词时
+     * 这张卡已经消费掉了,同一个 `approvalId` 再回决是 404。人的「允许这次」照常生效,只是这一次
+     * 没能顺手存下规则;改好的文本要落,得等**下一次同命令的 ask**(与 `rule_input_edited` 逐字
+     * 同一条处置)。壳的措辞据此写,别渲成「点这里重试」。
+     * 想做到「同一张卡上改了再来」需要一次**裁决之前**的预检,而那要求 core 把编辑面的校验(含它自己
+     * 的拼写规范化)导出成一只纯函数 —— 在本层照抄一个更严的校验器会把 `Bash(adb *)` 这条**成因形**
+     * 当场误拒。已登记为上游请托,不在本层用第二个解析器凑。
+     */
+     | "edit-rejected";
     detail: string;
 };
 /** 一层用户交上来的 settings(HTTP 载荷已 zod 校验过的形)。 */
@@ -197,11 +234,13 @@ export interface RuleConsentLane {
     persistCardRule(input: {
         principal: string;
         toolName: string;
-        /** 被裁决的命令**原字节**(与 ask 上的那份同源;规则文本由引擎从它铸,调用方不供文本)。 */
+        /** 被裁决的命令**原字节**(与 ask 上的那份同源;候选臂的规则文本由引擎从它铸,编辑臂的覆盖门也拿它判)。 */
         command: string;
-        /** 客户端选中的候选**文本**——用来在引擎铸出的候选表里定位下标。文本对不上 ⇒ 拒(不猜)。 */
-        ruleText: string;
+        /** 这次要兑的是候选表里的哪一条,还是人手改的自由文本(两个显式臂,见 {@link CardRuleRedemption})。 */
+        redemption: CardRuleRedemption;
         toolCallId?: string;
+        /** 卡上的实参摘要。编辑臂的**必要条件**:core 要求编辑回显它(「我编辑的是显示了这条命令的那张卡」),
+         *  缺席 ⇒ 编辑臂 fail-closed 拒(候选臂不受影响,那条路上它只是记账用)。 */
         boundInputHash?: string;
         scope?: RuleScope;
     }): Promise<CardRulePersisted>;