@sema-agent/core 7.33.0 → 7.33.1

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 7.33.1 — 2026-09-26
+
+### The first-byte lane's retry is a construction-time seat — `BrainTimeoutConfig.firstByteRetries?: 0 | 1` (#1128; additive; +1 optional type key; +0 exports, +0 codes) (@server)
+
+- **Before.** The lane's budget was a module constant (`FIRST_BYTE_RETRY_BUDGET` = 1) with no seat, and `maxRetries: 0` does not reach it (the lane's budget is its own, by design). A host that keeps a failover ladder of its own — a second gateway it tries when a call fails — waited the first-byte window and then a retry at twice the knob before the failure reached that ladder: 300 s + 600 s at the default, 30 s + 60 s even at an explicit 30 s knob.
+- **Now.** `firstByteRetries: 0 | 1` on every first-party brain's config (absent ⇒ 1, the reference implementation's one retry — unchanged). `0` ⇒ the first window's expiry is the call's terminal: one request, no retry frame, the existing one-window sentence (`[network] first-byte timeout: no response headers within <w1>ms (firstByteTimeoutMs) — …`). Independent of `maxRetries` in both directions, construction only (no per-call advisory twin). A value other than `0` / `1` fails the call before anything is sent, naming the knob (the watchdog knobs' own refusal, `config.stall_timeout_invalid`, at the same resolution point — like theirs, the code stays inside the brain and the caller reads the message) — never folded to the default or to `0`. The derived floors (`firstByteLaneKnobMs`, `WORKFLOW_AGENT_STALL_MS`) read the default and do not move.
+- **Who is hurt.** Nobody: absent is byte-for-byte 7.33.0. **Compensation** n/a.
+- Pins: `test/backlog1128-first-byte-retries.test.ts` (real transport, a local gateway that never writes headers: `0` ⇒ one request and the one-window terminal on all three brains, also under `maxRetries: 10`; explicit `1` and absent ⇒ two requests and one retry frame with `maxRetries: 1` under `maxRetries: 0`; twelve bad values refused by the resolver and through a brain with nothing sent; the derived floors). Docs: `docs/TIMEOUTS.md` (a retry-knob column; "a host with a failover ladder sets `0`"), `docs/sdk/03-brains-and-models.md`. Wire sheet: `docs/wire-consumption/unreleased-1128.md`.
+
+### Fix — git's environment config group survives the secret-env scrub whole: `GIT_CONFIG_KEY_<i>` is no longer taken for a credential unless its value carries one (#1129; behavior; +0 exports; `isSecretEnvKey` gains an optional `value` argument; +0 wire keys) (@server)
+
+- **Before.** The shape rule reads a bare `KEY` word with a numbered suffix as a credential, so `GIT_CONFIG_KEY_<i>` — git's env config, where the member holds a config entry's NAME (`user.name`, `safe.directory`, `http.extraHeader`) and `GIT_CONFIG_VALUE_<i>` its value — was dropped while `GIT_CONFIG_COUNT` and the value stayed. Every git child of a scrubbed env then refused to start: `error: missing config key GIT_CONFIG_KEY_0` / `fatal: unable to parse command-line config`, exit 128 (measured through the default exec env on a host carrying the group).
+- **Now.** The exemption side of the exact-name arm reads a second table beside the exact names, under the same three admission criteria: NAMED FAMILIES, `<STEM>_<i>` with `i` a canonical decimal — the spelling the reading tool builds itself. One member: `GIT_CONFIG_KEY`. Its row states criterion 2 ("the value is not a credential") as a screen on the VALUE rather than a standing claim, because a config key's subsection can be a URL and git authenticates with a URL's userinfo (`url.https://x-access-token:<token>@github.com/.insteadOf`): a member whose value carries `<scheme>://<userinfo>@` (any character but `/` counts as userinfo, whitespace included) is not exempt and drops by the shape rule exactly as before (finding `suffix-rule`). The screen is the row's own admission condition, read by the one classification (`classifySecretEnvKey(name, value?)`); `scrubSecretEnv` passes each entry's value, and `isSecretEnvKey(name)` without a value reads as in 7.33.0 (a family member is `true` — the name alone cannot clear); `isSecretEnvKey(name, value)` gives the scrub's answer for that entry. Unchanged: the bare `GIT_CONFIG_KEY`, a decorated (`X_GIT_CONFIG_KEY_0`), padded (`GIT_CONFIG_KEY_01`) or suffixed (`GIT_CONFIG_KEY_ID`, `GIT_CONFIG_KEY_0_TOKEN`) name, and every credential name (`GIT_API_TOKEN`, `GIT_PASSWORD`, `GH_TOKEN`) still drop and are still reported through `config.secret_env_scrubbed` / `onSecretEnvScrub`; the credential list still wins a collision.
+- **Who needs it.** Any deployment whose host process configures git through the environment (the `GIT_CONFIG_COUNT` protocol — a `safe.directory`, an `http.extraHeader` name, a mirror rewrite set without touching a config file): the two children the engine spawns from a scrubbed copy of its own environment — the default exec env's shell (`inheritEnv: "scrub"`) and an LSP server started without an explicit `env`.
+- **Who is hurt / compensation.** A group whose key carries URL userinfo — a token-bearing `url.<base>.insteadOf`, and also a username-only one such as `url.ssh://git@github.com/.insteadOf` — is still dropped at that key, so git in the child still exits 128 there (fail-closed: the credential does not reach the child; KL-1129b); the compensation is to hand the group explicitly (`inheritEnv` allowlist / `shellEnv`) or move the rewrite into a git config file. `GIT_CONFIG_VALUE_<i>` can carry a credential (an `http.extraHeader: Authorization: …` value) and was already inherited: the shape rule never matched its name, and this change does not touch it either way (KL-1129a).
+- Pins: `test/backlog1129-git-config-key-family.test.ts` (① `user.name` / `safe.directory` / a userinfo-free `insteadOf` through `scrubSecretEnv` and a real git child reading all three, and the default exec env's git child reading the entry while the withheld set names a planted credential and not the member; ② a token-bearing `insteadOf` key dropped with one finding, the token nowhere in the scrubbed env, git refusing with exit 128; the screen across schemes, a username-only userinfo, a userinfo with whitespace in it (git reads the credential out of it all the same) and an `@` in a path; ③ `isSecretEnvKey` without a value unchanged, with a clearing value `false`; an undefined entry drops; ④ the stem, decorated, padded, suffixed and credential names dropped by the shape rule even with a clearing value; the value member unmatched; the credential side winning a collision). Mutation-checked: a screen that always clears reds ②, a screen consulted without a value reds ③.
+
+### The wiring manifest says whether a leg has hands — `WiringManifest.hands?: { mounted, reason? }` (#1039; additive; +1 optional member on `WiringManifest` / `WiringFacts`; +1 wire word `no_execution_env`; +0 exports; `configFingerprint` value moves once) (@server)
+
+- **Before.** A leg whose deployment supplied no execution environment (no factory, no static `executionEnv`) mounts no hand band at all, and the wire said so only indirectly: an empty `mountedBy: "hands"` slice of `tools[]`, or `writeProtection.targetView: "spelling-only"` — which is absent altogether when the protection table is `[]`, where "no hands" and "protection off" read the same and the two assemblies hashed to the same `configFingerprint`.
+- **Now.** Every engine-minted effective manifest carries `hands`, beside `lsp` and in the same shape: `{ mounted: true }` when the band mounted (a factory-minted env, or a static `executionEnv` seat that is not `undefined` — a supplied `StubExecutionEnv` included, the band mounting over it with file tools and no shell, and a JS caller's `null` likewise over the no-I/O placeholder), `{ mounted: false, reason: "no_execution_env" }` otherwise. The value is the one the hand band's mount dispatches on, relayed, not re-derived. `reason` is one literal, not a registered closed set, because the hands decision has one false branch (a second branch promotes it). Unlike `lsp`, the member is IN `configFingerprint` (an assembly fact, the class of `writeProtection`), so a with-hands and a hands-less assembly now hash apart. No `EngineNotice`, no `TaskResult` change; whether a full shell is reachable stays a `tools[]` reading.
+- **Who is hurt.** A consumer that persisted `configFingerprint` values across engine versions sees every effective fingerprint change once (a new member in the hashed body); legs of one assembly still agree. An external `deriveWiringManifest` caller that passes an inconsistent `hands` fact is refused (the `autoMode` / `fileHistory` screen posture). **Compensation** n/a — the member is additive and its absence (older engines, the static half) is not a state.
+- Pins: `test/backlog1039-wiring-manifest-hands.test.ts` (through the Runner: a static env, no env, a supplied `StubExecutionEnv`, a JS caller's `null`, the factory lane — each read against the same leg's `tools[]`; the fingerprint telling the two assemblies apart with no protection judge on either; the value screen's six refusals, `null` included; the static half; no aliasing). Docs: `docs/INTEGRATION-CORE.md` (`wiring_manifest` row). Wire sheet: `docs/wire-consumption/unreleased-1039.md`.
+
+### Pins and wording — an explicit ask rule's ask and a hook's ask carry their own origin word on the card and on the park row (#1117; zero behavior face; +0 exports, +0 wire keys) (@server @cli)
+
+- **What was unpinned.** The origin ladder already mints `ask_rule` from a decision's `matchedAskRule` and `hook` from the hook fold, and gate-level pins read the word the resolver receives — but no pin read the WIRE faces a surface renders from: `AskRequest.origin` on a live approver and `PendingAction.tool_approval.origin` / `CheckpointSummary.origin` on a park, through the real Runner. A host policy that raises an operator's must-ask as an `ask` WITH `matchedAskRule` (composed through `combinePolicies`, beside a base policy's plain ask) reaches both faces as `ask_rule` today; without the member it reads `policy`.
+- **Now pinned**, and said where the words are listed: `docs/INTEGRATION-CORE.md` §4.6b (the enumerated set brought to its eleven words) states that `ask_rule` has one input — a minter raising an ask for a rule someone wrote must set `matchedAskRule`, or a plain policy ask reads `policy` on the card and the row — and what setting it means (the classifier does not answer it, a persisted allow rule does not clear it, an answer for this call does); the `PermissionResult.matchedAskRule` doc says the same. Two internal comments on the inherited-lane mint stations and the 7.26.0 `AskRequest.mandated` entry used "standing posture" for what a mandate refuses; the contract's word is a STANDING ANSWER (a release remembered from an earlier call) — an answer given for this call still clears a mandated ask. Wording only.
+- Pins: `test/backlog1117-ask-origin-rule-and-hook.test.ts` (live card and park row for the operator ask folded beside a base ask and alone, with the no-`matchedAskRule` negative control reading `policy`; live card — over an allowing policy and folded over a policy ask — and park row for a hook ask). Mutation-checked: removing the ladder's `ask_rule` arm reds three, its `hook` arm two, the fold's `matchedAskRule` carry two.
+
+### Forensics — the exit hard face says which of three causes a `no_pgid` receipt had (+2 trace lines; zero behavior face; +0 exports, +0 wire keys) (@server)
+
+- `killAllBackgroundShellsNow` folds three facts into one `no_pgid` receipt: the env has no synchronous kill seat, the seat answered `no_pgid` itself, or the seat threw. Only the third left a trace line. Two more, same form, same opt-in (`SEMA_DEBUG_SHUTDOWN=1`, stderr): `hard kill: seat absent` and `hard kill: seat answered no_pgid`, each with `{ id, shellId }`. The seat is now read once, inside the guard, so a READ that throws (a revoked membrane) is traced as `seat threw` and costs only its row — before this, the presence check sat inside the guard too. Receipts, row states and the per-row `hard kill: row` line are unchanged; an answer outside the closed set is still folded to `no_pgid` with the per-row line only. Contract text: `docs/background-process-lifetime.md` (Receipts). Pins: `test/backlog1107-hard-kill-forensics.test.ts` (the trace sink mocked: three arms, one line each, receipts `no_pgid`, rows `running`; a throwing READ of the seat costs its row only and the next row is killed; the seat called with its env as `this`; a seat that killed or found the shell gone leaves no seat line).
+
+### Test hygiene — `test/mcp-pagination.test.ts` no longer reads the host's `MCP_TOOL_TIMEOUT` (zero behavior face; +0 exports)
+
+- The page-walk pins measure the DEFAULT budget; with the variable set in the host env two of them went red on any branch. The file now clears it for its own run and restores it after (red-before / green-after verified at the fix).
+- `test/backlog994-s1-gaps-real-shells.test.ts`: the `echo x |& cat` pin compared the two pipeline stages' xtrace lines in a fixed order; the stages are concurrent processes, so the order is a race (one red in 23 546 on the stage run). The pin now compares membership; the other assertions of that pin are unchanged.
+
 ## 7.33.0 — 2026-09-26
 
 ### Model-call timeouts re-cut by segment: the header wait gets its own `firstByteTimeoutMs`, and every request carries the engine's dispatcher with the transport's header/body clocks off (#1121 #1122; behaviour: a pre-headers stall is a `stall` with its own one-retry lane, not a `transport` failure re-sent ten times; every watchdog defaults ON; +1 optional key `BrainTimeoutConfig.firstByteTimeoutMs`; **`BrainTimeoutConfig.connectTimeoutMs` REMOVED**; `StallTimeouts.connectMs` → `firstByteMs` (type-face breaking, see below); `WORKFLOW_AGENT_STALL_MS` 630 s → 1 500 s (derived); +1 dependency `undici@7.30.0`; `engines.node` `>=20.18.1`) (@server @cli @client-core)
@@ -1089,7 +1128,7 @@ with the next package release.
 - **Who is hurt.** A caller that relied on the file backend folding an unnamed kind into a delete — none in-tree, and the behaviour was unreachable through a typed call. Exports +2 (`permissionRuleWriteContract`, `PermissionRuleWriteContractHooks`), removals 0.
 - Reach: **@server** — the store twin's acceptance floor gains one suite to run (the sync kit is unchanged); **@cli** / **@client-core** — zero. Headless: a malformed delta from a foreign backend caller now throws where the file backend previously wrote a tombstone. `test/backlog996-write-delta-kinds.test.ts`.
 ### A mandate is a fact about the ask, not about a lane — `AskRequest.mandated` (#997; P2; approval face; additive, no export change)
-- **Before.** The only way an approval surface could learn that a card was MANDATED — that no persisted allow rule and no standing posture could retire it — was `AskRequest.ruleOffersAbsence === "mandated"`, a seat that reports what the RULE-OFFER LANE has to give. That lane speaks for one tool, only where a rule store is wired, and only on a task that can hold a rule; its own contract says absence is not a claim. Measured on the base of this entry, real Runner, `cat <path outside the session roots>`, both `shellGate` doctrines: `Bash` with a store and a principal carried `"mandated"`; the SAME command on `Monitor`, on `Bash` with no store, and on an anonymous task carried nothing. One approval card in every row; the mandate — the read station's own structural demotion — present in every row.
+- **Before.** The only way an approval surface could learn that a card was MANDATED — that no persisted allow rule and no standing answer (a release remembered from an earlier call) could retire it, while an answer given for that call still could — was `AskRequest.ruleOffersAbsence === "mandated"`, a seat that reports what the RULE-OFFER LANE has to give. That lane speaks for one tool, only where a rule store is wired, and only on a task that can hold a rule; its own contract says absence is not a claim. Measured on the base of this entry, real Runner, `cat <path outside the session roots>`, both `shellGate` doctrines: `Bash` with a store and a principal carried `"mandated"`; the SAME command on `Monitor`, on `Bash` with no store, and on an anonymous task carried nothing. One approval card in every row; the mandate — the read station's own structural demotion — present in every row.
 - **After.** `AskRequest.mandated?: true` (and the `PermissionResult` ask-arm member it is copied from) states it on the ask. Minted ONCE, at the gate's single origin stamp, from the one derivation the card's rule-offer word is also read from (`ruleClearanceOf`): the door SET decides the bit, the incumbent display ladder decides the word. Which door a card shows is a display choice; whether the ask is mandated is not — so a card worded `shadowed` over a probe mandate is mandated all the same, which the two-enumeration shape got wrong.
 - **The doors,** in one place: the tool seat's `egress` / `irreversibility` marks, an operator `shellGate: "always"`, the shell read station's structural demotion or a probe that timed out or threw, a write the protection judge matched or could not resolve, `requiresRealApproval`, a hook-raised ask, and an ask decided at an ANCESTOR's frozen approver. **Not** a door: a person's own explicit `ask` permission rule — the lane words that `shadowed`, because a rule they wrote is already speaking.
 - **What the bit says, and what it does not.** It says a persisted allow RULE may not clear the card. It does NOT say an approver may not answer it: a person, a hook and a deployment's blanket `onAsk: "allow"` seat all resolve a mandated ask exactly as before, and `requiresRealApproval` remains the separate, stronger "a person, not a configuration" demand. A shell whose POSTURE seat declines to auto-answer mandated cards reads this member to know which they are — @cli L-459, @client-core CC-110 (frame mirror), @server in transit. Absent on an older engine is not the opposite claim; tell the two apart by engine version, not by this seat.

package/dist/brain/stream-engine.js

@@ -6,7 +6,7 @@ import { stripUrlCredentials } from "./route-adjudicator.js";
 import { classifyInputTooLong } from "./input-too-long.js";
 import { FAST_MAX_BACKOFF_MS, providerWaitHint, retryBackoffMs } from "./retry.js";
 import { bindBrainStatusEmitter, emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
-import { createAttemptController, FIRST_BYTE_RETRY_BUDGET, firstByteWindow, refuseRetiredTimeoutKnobs, resolveWatchdogMs, STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, } from "./timeout.js";
+import { createAttemptController, firstByteWindow, refuseRetiredTimeoutKnobs, resolveFirstByteRetries, resolveWatchdogMs, STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, } from "./timeout.js";
 import { readMember, thrownText } from "../core/thrown-value.js";
 import { redactSecrets } from "../core/untrusted-egress.js";
 const DEFAULT_MAX_RETRIES = 10;
@@ -334,6 +334,7 @@ export function runStreamingBrain(args) {
         const firstByteTimeoutMs = resolveWatchdogMs(config.firstByteTimeoutMs, stallTimeouts?.firstByteMs, STALL_FIRST_BYTE_MS, "firstByteTimeoutMs");
         const firstTokenTimeoutMs = resolveWatchdogMs(config.firstTokenTimeoutMs, stallTimeouts?.firstTokenMs, STALL_FIRST_TOKEN_MS, "firstTokenTimeoutMs");
         const idleTimeoutMs = resolveWatchdogMs(config.idleTimeoutMs, stallTimeouts?.idleMs, STALL_IDLE_MS, "idleTimeoutMs");
+        const firstByteRetryBudget = resolveFirstByteRetries(config.firstByteRetries);
         const armWaitDisclosure = (ceilingMs) => {
             if (!(ceilingMs > WAITING_FIRST_TOKEN_AFTER_MS))
                 return { stop: () => undefined };
@@ -433,7 +434,7 @@ export function runStreamingBrain(args) {
                 cc.clearTimer();
                 try {
                     if (firstByteStall !== undefined) {
-                        if (firstByteStalls >= FIRST_BYTE_RETRY_BUDGET)
+                        if (firstByteStalls >= firstByteRetryBudget)
                             throw firstByteStall.err;
                         firstByteStalls++;
                         const announcement = retryAnnouncement(firstByteStall);
@@ -448,7 +449,7 @@ export function runStreamingBrain(args) {
                             retryInSec: Math.ceil(remainingMs / 1000),
                             retryInMs: remainingMs,
                             attempt: firstByteStalls,
-                            maxRetries: FIRST_BYTE_RETRY_BUDGET,
+                            maxRetries: firstByteRetryBudget,
                             errClass: announcement.errClass,
                         }));
                         continue;

package/dist/brain/timeout.d.ts

@@ -88,10 +88,13 @@ export declare function refuseRetiredTimeoutKnobs(holder: object | undefined, le
  *  reference implementation's allowance) — a large context on a slow uplink is still UPLOADING when a
  *  fixed window would call the gateway silent. */
 export declare const FIRST_BYTE_UPLOAD_BYTES_PER_SECOND = 32768;
-/** A first-byte stall is re-sent at most this many times, out of its OWN budget rather than
- *  `maxRetries` (the reference implementation: "normally one retry, not the session budget"); the shared
- *  ladder counts transport failures, and this is not one. */
+/** A first-byte stall is re-sent at most this many times by default ({@link BrainTimeoutConfig.firstByteRetries}),
+ *  out of its OWN budget rather than `maxRetries` (the reference implementation: "normally one retry, not the
+ *  session budget"); the shared ladder counts transport failures, and this is not one. */
 export declare const FIRST_BYTE_RETRY_BUDGET = 1;
+/** The first-byte lane's retry budget: absent ⇒ {@link FIRST_BYTE_RETRY_BUDGET}; `0` / `1` are themselves; anything
+ *  else is refused (`config.stall_timeout_invalid`), never folded to the default or to `0`. */
+export declare function resolveFirstByteRetries(value: unknown): 0 | 1;
 /** The retry's knob is the first times this — the reference implementation widens its retry to a second
  *  knob's default (599s against a 300s first window); one knob here keeps that ratio instead. */
 export declare const FIRST_BYTE_RETRY_WINDOW_FACTOR = 2;
@@ -125,10 +128,17 @@ export interface BrainTimeoutConfig {
      * `fetch()` call → response headers, ms: the window a gateway has to START answering (until 7.33.0 a
      * knob named `connectTimeoutMs` bounded this wait; it is gone — the connect clock is the transport's). Absent ⇒
      * {@link STALL_FIRST_BYTE_MS}; the armed window grows with the request body ({@link firstByteWindow});
-     * a stall earns ONE retry at a widened window out of its own budget, then fails naming this knob.
+     * a stall earns ONE retry at a widened window ({@link firstByteRetries}), then fails naming this knob.
      * Fires as a `stall` (this process cancelled its own request), never as a transport fault. `0` ⇒ off.
      */
     firstByteTimeoutMs?: number;
+    /**
+     * The first-byte lane's own retry budget: `1` (absent ⇒ {@link FIRST_BYTE_RETRY_BUDGET}) or `0` — the first
+     * window's expiry is the call's terminal, for a host whose own failover ladder should take a silent gateway after
+     * one window. Independent of `maxRetries` both ways; construction only; any other value fails the call naming this
+     * knob. The derived floors ({@link firstByteLaneKnobMs}) read the default.
+     */
+    firstByteRetries?: 0 | 1;
     /**
      * After the stream opens, cancel it if no content delta (text / thinking / tool input) arrives
      * within this many ms → `BrainError("network", "first-token timeout")`. For reasoning models the

package/dist/brain/timeout.js

@@ -34,6 +34,16 @@ export function refuseRetiredTimeoutKnobs(holder, level, where) {
 }
 export const FIRST_BYTE_UPLOAD_BYTES_PER_SECOND = 32_768;
 export const FIRST_BYTE_RETRY_BUDGET = 1;
+export function resolveFirstByteRetries(value) {
+    if (value === undefined)
+        return FIRST_BYTE_RETRY_BUDGET;
+    if (value === 0 || value === 1)
+        return value;
+    const shown = typeof value === "string" ? JSON.stringify(value) : typeof value === "bigint" ? `${value}n` : typeof value === "object" && value !== null ? "an object" : String(value);
+    const e = new Error(`firstByteRetries must be 0 or 1 (got ${shown}) — 1 re-sends a first-byte stall once at a widened window (the default), 0 ends the call at the first window so the caller's own failover takes it`);
+    e.code = "config.stall_timeout_invalid";
+    throw e;
+}
 export const FIRST_BYTE_RETRY_WINDOW_FACTOR = 2;
 export function resolveWatchdogMs(configured, advisory, engineDefault, knob) {
     return resolveStallTimeoutMs(configured ?? advisory, knob) ?? engineDefault;

package/dist/core/runner/prepare-wiring-manifest.js

@@ -11,7 +11,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { mountWriteProtection } from "./write-protection-station.js";
 import { autoRunOnRecommendationEffective } from "./memory-consolidation-driver.js";
 import { GLOBAL_USAGE_KEY, usageRetryAfterMs, windowsGovernCost } from "../usage-window-store.js";
-import { LSP_CONTRACT_ID, countElicitOptIns, deriveLspSeam, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam, resolveSubagentTranscriptTier } from "../wiring-manifest.js";
+import { LSP_CONTRACT_ID, countElicitOptIns, deriveHandsSeam, deriveLspSeam, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam, resolveSubagentTranscriptTier } from "../wiring-manifest.js";
 import { DEFAULT_IRREVERSIBLE_SCOPE } from "./checkpoint-scope.js";
 export function mcpManifestEntries(entries, statuses) {
     return (entries ?? []).map((entry) => {
@@ -218,6 +218,7 @@ export function prepareWiringManifest(input) {
         tools: toolRoster,
         hooks: wiredHookEntries(hooks, spec.hooks !== undefined ? "spec" : "deps", preToolUseObservational),
         ...(lspManagerWired ? { lsp: deriveLspSeam(toolRoster.entries.some((e) => e.contract.contractId === LSP_CONTRACT_ID), lspDiagnosticsLive) } : {}),
+        hands: deriveHandsSeam(handsEnabled),
         fileHistory: fileHistoryFact,
     });
     peerLaneRefs.askEffective = wiringManifest.ask.effective;

package/dist/core/secret-env.d.ts

@@ -18,6 +18,12 @@
  */
 import type { RedactionConfidence, RedactionSource } from "./arg-summary.js";
 import { type EngineNotice } from "./engine-notice.js";
+/** A name table as the exact-name arm reads it: membership of an UPPER-CASED name, given the entry's value when
+ *  the caller has one. A `Set` of exact names is one (it ignores the value); the exemption side is the union of
+ *  its two tables. */
+export interface EnvNameTable {
+    has(upperName: string, value?: string): boolean;
+}
 /** Which rule classified a key as secret-shaped — the env arm's `kind` vocabulary. */
 export type SecretEnvFindingKind = "suffix-rule" | "namespace-rule" | "exact-name";
 /** One env entry the `scrub` policy dropped: the key (the VALUE is never carried — this record is meant
@@ -30,14 +36,17 @@ export interface SecretEnvFinding {
 }
 /** What the two exact-name lists say about a name, before any shape rule is consulted. */
 export type ExactEnvNameVerdict = "credential" | "exempt" | "unknown";
-/** The exact-name arm of the classification, taking both lists as arguments. The credential list is read
+/** The exact-name arm of the classification, taking both lists as arguments (the exemption side is the exact
+ *  names plus the named families). The credential list is read
  *  FIRST: an exemption can never take a name away from it, so a name landing on both lists resolves to the
  *  credential reading — the fail-closed direction (a wrongly-exempted name leaks; a wrongly-dropped one
  *  does not). Module-level export (not part of the package surface): the two real lists are disjoint, so
  *  only a controlled collision can tell this precedence from an inverted one. */
-export declare function classifyExactEnvName(key: string, credentialNames: ReadonlySet<string>, exemptNames: ReadonlySet<string>): ExactEnvNameVerdict;
-/** Is `key` a secret-pattern env var (one the fail-closed `scrub` policy drops before spawning a shell)? */
-export declare function isSecretEnvKey(key: string): boolean;
+export declare function classifyExactEnvName(key: string, credentialNames: EnvNameTable, exemptNames: EnvNameTable, value?: string): ExactEnvNameVerdict;
+/** Is `key` a secret-pattern env var (one the fail-closed `scrub` policy drops before spawning a shell)? Pass the
+ *  entry's `value` to get exactly the scrub's answer for that entry: a named-family exemption holds only for a value
+ *  that clears the family's screen, so without a value such a member reads as secret (the name alone cannot clear). */
+export declare function isSecretEnvKey(key: string, value?: string): boolean;
 /** Drop every secret-pattern key (see {@link isSecretEnvKey}) from an env object — the fail-closed `scrub`
  *  policy. `findings` is an OPTIONAL caller-owned collector: pass an array to learn which entries were
  *  dropped and why, read it back after the call. Omitting it leaves this function byte-for-byte what it

package/dist/core/secret-env.js

@@ -15,21 +15,30 @@ const NON_SECRET_ENV_EXACT_NAMES = new Set([
     "MAX_BATCH_PREFILL_TOKENS", "MAX_WAITING_TOKENS", "MAX_TOP_N_TOKENS", "RATE_LIMIT_TOKENS",
     "PROMPT_TOKENS", "CONTEXT_TOKENS",
 ]);
+const NON_SECRET_ENV_INDEXED_FAMILIES = [
+    { stem: "GIT_CONFIG_KEY", valueClears: (value) => !/[a-z][a-z0-9+.-]*:\/\/[^/@]+@/i.test(value) },
+];
+const indexedFamilyMember = (stem) => new RegExp(`^${stem}_(?:0|[1-9][0-9]*)$`);
+const NON_SECRET_ENV_INDEXED_FAMILY_ROWS = NON_SECRET_ENV_INDEXED_FAMILIES.map((f) => ({ member: indexedFamilyMember(f.stem), valueClears: f.valueClears }));
+const NON_SECRET_ENV_NAMES = {
+    has: (upperName, value) => NON_SECRET_ENV_EXACT_NAMES.has(upperName) ||
+        (value !== undefined && NON_SECRET_ENV_INDEXED_FAMILY_ROWS.some((row) => row.member.test(upperName) && row.valueClears(value))),
+};
 const SECRET_ENV_KIND_CONFIDENCE = {
     "exact-name": "high",
     "suffix-rule": "medium",
     "namespace-rule": "medium",
 };
-export function classifyExactEnvName(key, credentialNames, exemptNames) {
+export function classifyExactEnvName(key, credentialNames, exemptNames, value) {
     const upper = key.toUpperCase();
-    if (credentialNames.has(upper))
+    if (credentialNames.has(upper, value))
         return "credential";
-    if (exemptNames.has(upper))
+    if (exemptNames.has(upper, value))
         return "exempt";
     return "unknown";
 }
-function classifySecretEnvKey(key) {
-    const byExactName = classifyExactEnvName(key, SECRET_ENV_EXACT_NAMES, NON_SECRET_ENV_EXACT_NAMES);
+function classifySecretEnvKey(key, value) {
+    const byExactName = classifyExactEnvName(key, SECRET_ENV_EXACT_NAMES, NON_SECRET_ENV_NAMES, value);
     if (byExactName === "credential")
         return "exact-name";
     if (byExactName === "exempt")
@@ -38,13 +47,13 @@ function classifySecretEnvKey(key) {
         return "suffix-rule";
     return SEMA_NAMESPACE_SECRET_RE.test(key) ? "namespace-rule" : undefined;
 }
-export function isSecretEnvKey(key) {
-    return classifySecretEnvKey(key) !== undefined;
+export function isSecretEnvKey(key, value) {
+    return classifySecretEnvKey(key, value) !== undefined;
 }
 export function scrubSecretEnv(env, findings) {
     const out = {};
     for (const k of Object.keys(env)) {
-        const kind = classifySecretEnvKey(k);
+        const kind = classifySecretEnvKey(k, env[k]);
         if (kind === undefined) {
             out[k] = env[k];
             continue;

package/dist/core/task-registry.js

@@ -606,7 +606,12 @@ export class TaskRegistry {
             }
             let outcome;
             try {
-                outcome = handle.env.killBackgroundNow !== undefined ? handle.env.killBackgroundNow(handle.shellId) : "no_pgid";
+                const seat = handle.env.killBackgroundNow;
+                if (seat === undefined)
+                    shutdownDebug("hard kill: seat absent", { id: handle.id, shellId: handle.shellId });
+                outcome = seat === undefined ? "no_pgid" : seat.call(handle.env, handle.shellId);
+                if (seat !== undefined && outcome === "no_pgid")
+                    shutdownDebug("hard kill: seat answered no_pgid", { id: handle.id, shellId: handle.shellId });
             }
             catch (err) {
                 shutdownDebug("hard kill: seat threw", { id: handle.id, shellId: handle.shellId, error: thrownText(err) });

package/dist/core/tool-policy.d.ts

@@ -341,18 +341,18 @@ export type PermissionResult = {
      *  `probe*` above; ENGINE-STAMPED and VALIDATED at the tighten, and deliberately NOT merged onto an ask
      *  another layer raised, which a grant leaves standing. */
     probeReadRootCandidate?: import("./types.js").ReadRootGrantCandidate;
-    /** An EXPLICIT `ask` permission rule matched this call (design/127 DSL — the CC `alwaysAskRules`
-     *  shape); carries the matched rule's text. Present ⇔ a rule someone WROTE says "ask about this",
-     *  never for a `defaultAction:"ask"` fallback (an unmatched call is default-closed posture, not a
-     *  per-call instruction — CC draws the same line: only a matched ask rule diverts the auto-mode
-     *  lane, a mode-default ask stays classifier-eligible). Consumer: the gate's auto-mode classifier
-     *  step refuses to resolve an ask carrying it — a person's standing "ask me each time" is not
-     *  classifier hesitation, so a classifier verdict must not be the thing that clears it. A policy
-     *  self-declaring the member only ever OPTS ITS OWN ask OUT of classifier auto-resolution
-     *  (tightening — the false-claim direction is safe, unlike the engine-stamped `"hook"` word whose
-     *  risk was laundering provenance AWAY). {@link combinePolicies} carries it onto the surviving ask
-     *  when ANY folded-away concurrent ask bore it (monotone, tighten-only); it is consumed inside the
-     *  gate and deliberately NOT copied onto the park/approval-card request. */
+    /** An EXPLICIT `ask` permission rule matched this call (design/127 DSL — the CC `alwaysAskRules` shape); carries the
+     *  matched rule's text. Present ⇔ a rule someone WROTE says "ask about this", never for a `defaultAction:"ask"` fallback
+     *  (an unmatched call is default-closed posture, not a per-call instruction — CC draws the same line: only a matched ask
+     *  rule diverts the auto-mode lane, a mode-default ask stays classifier-eligible). Consumer: the gate's auto-mode
+     *  classifier step refuses to resolve an ask carrying it — a person's standing "ask me each time" is not classifier
+     *  hesitation, so a classifier verdict must not be the thing that clears it. A policy self-declaring the member only
+     *  ever OPTS ITS OWN ask OUT of classifier auto-resolution (tightening — the false-claim direction is safe, unlike the
+     *  engine-stamped `"hook"` word whose risk was laundering provenance AWAY). {@link combinePolicies} carries it onto the
+     *  surviving ask when ANY folded-away concurrent ask bore it (monotone, tighten-only); it is consumed inside the gate
+     *  and NOT copied onto the park/approval-card request — but it is the ONE input of the `ask_rule` origin word they DO
+     *  carry ({@link origin}): a minter raising an ask for a written rule (a person's settings rule, an operator's must-ask
+     *  list) that leaves it unset gets `policy` there, indistinguishable from hesitation. */
     matchedAskRule?: string;
     /** design/252 G-2 (additive): the RULE-PROVENANCE evidence behind this ask — see
      *  {@link AskRuleEvidence}. ENGINE-STAMPED inside the gate, once, after the org layer and the

package/dist/core/wiring-manifest.d.ts

@@ -137,6 +137,15 @@ export interface WiringManifestMcpEntry {
  *  both. A leg whose `LSP` tool was excluded can still be pushing diagnostics. */
 export declare const LSP_LANES: readonly ["tool", "diagnostics", "tool_and_diagnostics"];
 export type LspLane = (typeof LSP_LANES)[number];
+/** Why a leg's hand band is NOT mounted ({@link WiringManifest.hands}`.reason`), one word per false branch of the
+ *  hands decision (`prepare-execution-env.ts`); it has one: `no_execution_env` = neither env seat supplied one. A
+ *  literal, not a registered closed set (the gate admits sets of two or more) until a second branch exists. */
+export type HandsUnmountedReason = "no_execution_env";
+/** The manifest's hands seam from the leg's one hands fact (see {@link WiringManifest.hands}). */
+export declare function deriveHandsSeam(handsMounted: boolean): {
+    mounted: boolean;
+    reason?: HandsUnmountedReason;
+};
 /** The contract id the LSP tool mounts under (`createLspTool`) — the roster's structural discriminator, which
  *  a disclosure keys on instead of re-spelling the wire name. */
 export declare const LSP_CONTRACT_ID = "core.lsp@1";
@@ -347,6 +356,19 @@ export interface WiringManifest {
         mounted: boolean;
         lane?: LspLane;
     };
+    /**
+     * EFFECTIVE half only, ALWAYS present on an engine-minted effective manifest: is this leg's HAND band (the file
+     * tools, and the shell tools where the env has a shell) mounted — the value the band's mount reads, stated
+     * positively instead of inferred from `tools[]` or the write-protection word. `true` ⇔ the factory minted an env
+     * or the static `executionEnv` seat is not `undefined` (a JS caller's `null` and a `StubExecutionEnv` count: the
+     * band mounts over them, without a shell); `false` carries `reason` ({@link HandsUnmountedReason}), which is absent
+     * beside `true`. Whether a full shell is reachable is `tools[]`'s fact. ABSENT = an older mint or an external
+     * derivation, never a state. IN {@link configFingerprint}: an ASSEMBLY fact (the {@link writeProtection} class).
+     */
+    hands?: {
+        mounted: boolean;
+        reason?: HandsUnmountedReason;
+    };
     /**
      * EFFECTIVE half only, PRESENT IFF this leg compiled a write-protection judge — a deployment that
      * replaced the table with `[]` opted the layer out entirely, and reports nothing here rather than a
@@ -497,6 +519,11 @@ export interface WiringFacts {
         mounted: boolean;
         lane?: LspLane;
     };
+    /** Effective half only — the hands seam ({@link WiringManifest.hands}, {@link deriveHandsSeam}); the engine always passes it. */
+    hands?: {
+        mounted: boolean;
+        reason?: HandsUnmountedReason;
+    };
     /** Effective half only — the compiled write-protection judge's OWN target-view word
      *  ({@link WiringManifest.writeProtection}); absent ⇒ this leg compiled no judge (an emptied table). */
     writeProtectionTargetView?: WriteProtectionTargetView;

package/dist/core/wiring-manifest.js

@@ -5,6 +5,9 @@ import { isLiveQuestionFace } from "./ask-question.js";
 import { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
 export const AUTO_MODE_ARM_REASONS = ["armed", "no_intent", "no_face", "denied", "resolver_fault"];
 export const LSP_LANES = ["tool", "diagnostics", "tool_and_diagnostics"];
+export function deriveHandsSeam(handsMounted) {
+    return handsMounted ? { mounted: true } : { mounted: false, reason: "no_execution_env" };
+}
 export const LSP_CONTRACT_ID = "core.lsp@1";
 export function deriveLspSeam(mounted, diagnosticsLive) {
     const lane = mounted ? (diagnosticsLive ? "tool_and_diagnostics" : "tool") : diagnosticsLive ? "diagnostics" : undefined;
@@ -84,6 +87,13 @@ function readAutoModeFact(fact) {
     }
     return { armed, reason, ...(deniedSource !== undefined ? { deniedSource } : {}) };
 }
+function readHandsFact(fact) {
+    const { mounted, reason } = typeof fact === "object" && fact !== null ? fact : { mounted: undefined, reason: undefined };
+    if (typeof mounted !== "boolean" || (mounted ? reason !== undefined : reason !== "no_execution_env")) {
+        throw new Error(`the hands wiring fact is inconsistent (${JSON.stringify(fact)}) — mounted is a boolean, and reason stands exactly when it is false, as "no_execution_env"`);
+    }
+    return mounted ? { mounted } : { mounted, reason };
+}
 function readFileHistoryFact(word) {
     if (word !== "on" && word !== "disabled")
         throw new Error(`the file-history wiring fact ${JSON.stringify(word)} is not one of on|disabled`);
@@ -146,6 +156,7 @@ export function deriveWiringManifest(facts) {
         ...(facts.half === "effective" && facts.tools !== undefined ? { tools: facts.tools } : {}),
         ...(facts.half === "effective" && facts.hooks !== undefined && facts.hooks.length > 0 ? { hooks: facts.hooks.map((h) => ({ ...h })) } : {}),
         ...(facts.half === "effective" && facts.lsp !== undefined ? { lsp: { ...facts.lsp } } : {}),
+        ...(facts.half === "effective" && facts.hands !== undefined ? { hands: readHandsFact(facts.hands) } : {}),
         ...(facts.half === "effective" && facts.writeProtectionTargetView !== undefined ? { writeProtection: { targetView: facts.writeProtectionTargetView } } : {}),
         ...(facts.half === "effective" && facts.readDenyBuiltinTiersActive !== undefined && facts.readDenyBuiltinTiersActive.length > 0
             ? { readDeny: { builtinTiers: [...facts.readDenyBuiltinTiersActive] } }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.33.0",
+  "version": "7.33.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/wire-changes/core@7.33.1.json

@@ -0,0 +1,237 @@
+{
+  "repo": "core",
+  "version": "7.33.1",
+  "from": "88d7026bbe5019e8a8b1158551e23b1bf5adb53e",
+  "to": "v7.33.1",
+  "added": [],
+  "removed": [],
+  "changed": [],
+  "narrowed": [],
+  "closedSetMembers": [
+    {
+      "set": "HandsUnmountedReason",
+      "at": [
+        "src/core/wiring-manifest.ts:168"
+      ],
+      "newSet": true,
+      "added": [
+        "no_execution_env"
+      ],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": false
+    }
+  ],
+  "closedSetsUnreadable": [],
+  "typeKeys": [
+    {
+      "type": "AnthropicBrainConfig",
+      "at": [
+        "src/brain/anthropic.ts:25"
+      ],
+      "added": [
+        "firstByteRetries"
+      ],
+      "addedDetail": [
+        {
+          "key": "firstByteRetries",
+          "optional": true
+        }
+      ],
+      "addedRequired": [],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": false
+    },
+    {
+      "type": "BrainTimeoutConfig",
+      "at": [
+        "src/brain/timeout.ts:179"
+      ],
+      "added": [
+        "firstByteRetries"
+      ],
+      "addedDetail": [
+        {
+          "key": "firstByteRetries",
+          "optional": true
+        }
+      ],
+      "addedRequired": [],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": true
+    },
+    {
+      "type": "OpenAIBrainConfig",
+      "at": [
+        "src/brain/openai.ts:27"
+      ],
+      "added": [
+        "firstByteRetries"
+      ],
+      "addedDetail": [
+        {
+          "key": "firstByteRetries",
+          "optional": true
+        }
+      ],
+      "addedRequired": [],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": false
+    },
+    {
+      "type": "OpenResponsesBrainConfig",
+      "at": [
+        "src/brain/open-responses.ts:101"
+      ],
+      "added": [
+        "firstByteRetries"
+      ],
+      "addedDetail": [
+        {
+          "key": "firstByteRetries",
+          "optional": true
+        }
+      ],
+      "addedRequired": [],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": false
+    },
+    {
+      "type": "StreamEngineConfig",
+      "at": [
+        "src/brain/stream-engine.ts:45"
+      ],
+      "via": "AnthropicBrainConfig.StreamEngineConfig",
+      "added": [
+        "firstByteRetries"
+      ],
+      "addedDetail": [
+        {
+          "key": "firstByteRetries",
+          "optional": true
+        }
+      ],
+      "addedRequired": [],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": false
+    },
+    {
+      "type": "WiringFacts",
+      "at": [
+        "src/core/wiring-manifest.ts:451"
+      ],
+      "added": [
+        "hands"
+      ],
+      "addedDetail": [
+        {
+          "key": "hands",
+          "optional": true
+        }
+      ],
+      "addedRequired": [],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": false
+    },
+    {
+      "type": "WiringManifest",
+      "at": [
+        "src/core/wiring-manifest.ts:193"
+      ],
+      "added": [
+        "hands"
+      ],
+      "addedDetail": [
+        {
+          "key": "hands",
+          "optional": true
+        }
+      ],
+      "addedRequired": [],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": true
+    }
+  ],
+  "typeKeysUnreadableArms": [],
+  "typeKeysFlattenedCount": 217,
+  "declarationMoves": [],
+  "mintMoves": [],
+  "criteriaObserves": [
+    {
+      "kind": "taskEventField",
+      "name": "wiring_manifest.manifest",
+      "assertions": [
+        "G3.a"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "BrainTimeoutConfig.firstByteRetries",
+      "assertions": [
+        "G1.a",
+        "G1.b"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "BrainTimeoutConfig.firstByteTimeoutMs",
+      "assertions": [
+        "G1.a"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "SecretEnvFinding.key",
+      "assertions": [
+        "G2.a"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "SecretEnvFinding.kind",
+      "assertions": [
+        "G2.a",
+        "G2.b"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "WiringManifest.configFingerprint",
+      "assertions": [
+        "G3.b"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "WiringManifest.hands",
+      "assertions": [
+        "G3.a",
+        "G3.b"
+      ]
+    }
+  ],
+  "consumersHint": {
+    "cli": [
+      "WiringFacts",
+      "WiringManifest"
+    ],
+    "server": [
+      "WiringFacts",
+      "WiringManifest"
+    ],
+    "sdk": [
+      "WiringManifest"
+    ],
+    "note": "scanned cli@4e593722 server@7a9240f9 sdk@4031f42 — a name listed is MENTIONED there today, which is evidence of consumption, not proof of it. Ledger files (**/docs/core-consumption/**, **/docs/wire-consumption/**, **/*LEDGER*.json) are not evidence of use — server: 4 name(s) matched ONLY in bookkeeping files and were set aside (AnthropicBrainConfig, BrainTimeoutConfig, OpenAIBrainConfig, OpenResponsesBrainConfig)"
+  },
+  "breakingCount": 0,
+  "breakingItems": [],
+  "toResolvedAt": "093aeef4709628f9cabb0d4b1c88621c98d57bda"
+}