@sema-agent/core 7.51.2 → 7.52.0

package/dist/core/runner-deps.d.ts

@@ -159,12 +159,12 @@ export interface RunnerDeps {
      */
     rosterStore?: import("../agents/roster-store.js").RosterStore;
     /**
-     * design/148 S1 — the center prompt-artifact source (protocol §9.2). `current()` supplies the
-     * validated candidate NEW sessions adopt at session_start; `get(digest)` resolves a PINNED
-     * center artifact on resume (a miss is fail-loud `prompt.snapshot_unavailable` — core never
-     * recomposes a hybrid from same-named newer content). Core bundles `CenterPromptSource`
-     * (+ memory/file artifact & source-state stores); a server deployment feeds it verified
-     * effective-snapshot envelopes via `applySnapshot`. Omitted = bundled-only (today's shape).
+     * The center prompt-artifact source (artifact v2 only — INTEGRATION-CORE §12.11). `current()` supplies the verified
+     * candidate a top-level session adopts at session start and at a compaction; `get(digest)` resolves a PINNED center
+     * layer on resume (a miss is fail-loud `prompt.snapshot_unavailable` — core never recomposes a hybrid from newer
+     * content); `sourceState()` is the tri-state every adoption decision keys on. What a source hands a run is re-checked
+     * before it is adopted. Core bundles `CenterPromptSource` (+ memory/file artifact & source-state stores); a server
+     * feeds it published artifacts via `applySnapshot`. Omitted = no center layer.
      */
     promptSource?: import("../prompt-assembly/artifact-store.js").PromptArtifactSource;
     /**
@@ -518,7 +518,7 @@ export interface RunnerDeps {
     resumePreflight?: (info: ResumePreflightInfo, signal: AbortSignal) => Promise<ResumePreflightVerdict>;
     /**
      * design/380 O2 — the {@link resumePreflight} deadline in ms. Default 10s (its own bound,
-     * deliberately NOT the hooks-record default: a resume preflight sits on every redeem attempt of a
+     * deliberately its own: a resume preflight sits on every redeem attempt of a
      * parked row and must answer promptly or get out of the way). Bad values (non-finite, ≤ 0,
      * non-number) are DISCLOSED loudly through `onError` and fall back to the default (the bad-value
      * loudness default: announce, never silently absorb).
@@ -1117,7 +1117,7 @@ export interface RunnerDeps {
      * CLAUDE.md/git injection — the cure for "say hi → only greets"). The deployment/profile owns the CONTENT
      * (read CLAUDE.md / `.claude/` + fold in `git log -5`/status + a byte budget); core owns the seam + fence +
      * cache placement and NEVER hardcodes a filename (same trust posture as {@link executionEnvFactory}/
-     * {@link promptProvider}/{@link modelKnowledgeCutoffs}). A RunnerDeps FUNCTION, not a `TaskSpec` field: it is
+     * {@link mods}/{@link modelKnowledgeCutoffs}). A RunnerDeps FUNCTION, not a `TaskSpec` field: it is
      * unserializable (durable resume) and reading files for an UNTRUSTED caller would be a confused-deputy hole
      * (design/44 §7 Q4). DECOUPLED from `memoryStore` — injects even with NO long-term memory configured (H5).
      *
@@ -1189,8 +1189,6 @@ export interface RunnerDeps {
         path: string;
         contentHash: string | null;
     }> | null>;
-    /** Override system-prompt assembly. Defaults to `defaultPromptProvider`. */
-    promptProvider?: import("../prompts/default.js").PromptProvider;
     /**
      * design/99 §E23 — the LIVE-ONLY inbound-elicitation seam (an MCP server asking the END USER for input
      * mid-tool-call). Wired ONLY for servers that opted in via {@link McpServerSpec.elicitation}; absent ⇒ core
@@ -1269,20 +1267,13 @@ export interface RunnerDeps {
      */
     artifactHost?: import("./artifact-host.js").ArtifactHost;
     /**
-     * Default in-process hooks for all tasks (design/37) — the FULL lifecycle seam of the `Hooks`
-     * interface, not just the tool-call trio: `preToolUse` (rewrite/restrict args + inject context),
-     * `postToolUse` (rewrite output + inject context), `userPromptSubmit` (design/373 §4.3: screens
-     * EVERY user-lane entrance — the objective, a live `TaskStream.steer`, a wake resume's message,
-     * and a parked steer's redelivery, discriminated by `ctx.source`; a hook that blocks
-     * unconditionally refuses steers/wakes too — see the ⚠️ WIDENED INVOCATION SET banner on
-     * {@link import("./hooks.js").Hooks.userPromptSubmit}), plus `stop` (push back when the run would otherwise end and continue
-     * it), `postToolUseFailure` / `postToolBatch` / `permissionDenied` (failure, batch-boundary and
-     * deny observers), `preCompact` / `postCompact` (compaction gate + observer), `stopFailure`
-     * (API-error terminal observer) and the `preToolUseObservational` declaration flag — each member's
-     * contract is documented on the `Hooks` interface itself. A task's own `hooks` overrides this. A
-     * PreToolUse hook's `allow` never bypasses `toolPolicy` — the policy is always the final say.
-     */
-    hooks?: import("./hooks.js").Hooks;
+     * The deployment seat of the mods bus: extension registrations every task of this Runner carries (every leg — root,
+     * delegated child, resume — admits them at its own prepare). Each declares its tier (`prepend`, `user` or `append`;
+     * absent or another word refuses the prepare, `config.mods_invalid`). A task's own `TaskSpec.mods` run beside these,
+     * never instead of them. A `classic.PreToolUse` handler's `allow` never bypasses `toolPolicy` — the policy is always
+     * the final say.
+     */
+    mods?: readonly import("./mods/kernel/index.js").ModRegistration<import("./mods/dollar.js").EngineDollar>[];
     /**
      * Policy for remote image URLs (`TaskSpec.images[].url`). Return false to reject. When set it
      * **replaces** the built-in SSRF guard (https-only + private/reserved-host block) — e.g. supply a
@@ -1295,9 +1286,10 @@ export interface RunnerDeps {
      *   summaries) is invisible without this and lets a session grow until it tops the window.
      * - `"prompt-cache"` — a prefix-cache hazard on the wire: a detected cache break (design/31), or a
      *   mis-declared/mismatched `promptCacheFamily`. The prefix cache will miss. Log/alert on both.
-     * - `"prompt-constitution"` — a `stableSystem` provider returned an ALREADY-assembled prompt
-     *   (constitution anchor found); core passed it through un-doubled. Upgrade the provider to return
-     *   only the role base (or set `replaceAll: true` to own the whole base).
+     * - `"prompt-constitution"` — a prompt overlay did not take effect as written: a later source (or a later
+     *   declaration in the same source) superseded it on the same target, its target was not in this run's
+     *   prompt, or a mods handler's `prompt.compose` answer was skipped (it rewrote another's overlay, or wrote
+     *   what the band table does not grant its seat). Each overlay is named once per run.
      * - `"degraded"` — the task kept running with a capability quietly reduced: a question auto-answered
      *   with no human present, a skipped env git snapshot, a lost checkpoint-put confirmation, an
      *   unroutable descendant notification, and similar best-effort arms. The run proceeds; the reduced
@@ -1496,7 +1488,7 @@ export interface RunnerDeps {
      * trusted control-plane injection), so it lives on `RunnerDeps` — NOT `TaskSpec`: `TaskSpec` is the
      * serializable, untrusted-caller, durable-resume-round-trippable per-task config (a function can be
      * neither serialized nor durably checkpointed, and the sandbox/env-class injections deliberately sit on
-     * `RunnerDeps` for the same trust reason). Same placement as `promptProvider` / `executionEnvFactory`.
+     * `RunnerDeps` for the same trust reason). Same placement as `mods` / `executionEnvFactory`.
      *
      * When `summaryProvider` is set, BOTH compaction call sites (the within-task turn boundary AND `finish()`
      * at task end) consult it: a NON-EMPTY string is reused verbatim (the real `generateSummary` LLM call is

package/dist/core/safety-merge-corpus.js

@@ -177,12 +177,28 @@ export const SAFETY_MERGE_CONFORMANCE_CORPUS = [
     },
     {
         name: "inert-deny-entry-removed-safe",
-        intent: "removing a deny entry that reads as nothing (an empty entry, a wildcard peer, a `__` name with no protocol prefix) relaxes nothing — the comparison reads the EFFECTIVE entries on both sides",
-        prior: { toolDeny: ["Bash", "", "mcp__*", "github__x"] },
+        intent: "removing a deny entry the grammar reads that names nothing (a wildcard peer, a `__` name with no protocol prefix) relaxes nothing — the comparison reads the EFFECTIVE entries on both sides",
+        prior: { toolDeny: ["Bash", "mcp__*", "github__x"] },
         next: { toolDeny: ["Bash"] },
         loosens: false,
         reasons: [],
     },
+    {
+        name: "unreadable-deny-prior-loosened",
+        intent: "rules whose toolDeny holds an entry no rule grammar reads (an empty entry) cannot be read and refuse every call — an override that can be read loosens them",
+        prior: { toolDeny: ["Bash", ""] },
+        next: { toolDeny: ["Bash"] },
+        loosens: true,
+        reasons: ['the prior rules refuse every call — their toolDeny holds "" (grammar), which no grammar reads'],
+    },
+    {
+        name: "unreadable-deny-next-safe",
+        intent: "an override whose toolDeny holds an entry no rule grammar reads refuses every call — it loosens nothing, whatever else it drops",
+        prior: { toolDeny: ["Bash"], allowDirs: ["/repo"] },
+        next: { toolDeny: [""] },
+        loosens: false,
+        reasons: [],
+    },
     {
         name: "inert-allow-entry-added-safe",
         intent: "adding an allowlist entry that reads as nothing admits nothing, so it widens nothing",

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

@@ -4,8 +4,9 @@
  * A child the engine spawns may run what the MODEL chose (a tool shell, a gate over model-written code, a language
  * server). Under the `"scrub"` policy (the default) it inherits every variable but those the judgment below names —
  * deleted whole, never rewritten; `"all"` and a `string[]` allow list are the caller's explicit alternatives
- * ({@link inheritedHostEnv}). Whatever the policy, a name the deployment declares as its own credential
- * ({@link declareWithheldEnv}) is never inherited. One judgment per variable ({@link classifySecretEnvEntry}), the first rule that answers:
+ * ({@link inheritedHostEnv}). Whatever the policy, an entry that is this deployment's own credential is never inherited:
+ * its name is one the deployment declared, or its value equals a credential value the deployment declared or the
+ * engine holds ({@link declareWithheldEnv}, {@link holdOwnCredentialValues}). One judgment per variable ({@link classifySecretEnvEntry}), the first rule that answers:
  *   1. exempt — git's environment config and the proxy variables, handed on as written ({@link isExemptEnvName});
  *   2. `exact-name` — a known credential name (the vocabulary's exact env names);
  *   3. `prefix-rule` — the OpenTelemetry settings ({@link OTEL_ENV_RE});
@@ -26,8 +27,9 @@ import { type EngineNotice } from "./engine-notice.js";
  *  Reads the first {@link VALUE_SCAN_LIMIT} code units. The value half of the judgment, exported apart from the env
  *  entry's exemptions ({@link isExemptEnvName}): a caller holding a value that is no environment variable asks this. */
 export declare function looksLikeCredentialValue(value: string): boolean;
-/** Which rule withheld an entry: one of the scrub's rules, or `own-credential` — the deployment declared the name as its
- *  own credential ({@link declareWithheldEnv}), which every policy withholds. */
+/** Which rule withheld an entry: one of the scrub's rules, or `own-credential` — the entry is this deployment's own
+ *  credential (its name is declared, or its value equals a declared or engine-held credential value:
+ *  {@link declareWithheldEnv}), which every policy withholds. */
 export type SecretEnvFindingKind = "exact-name" | "name-rule" | "namespace-rule" | "prefix-rule" | "value-rule" | "own-credential";
 /** One env entry withheld (deleted) from a child's environment: its name — never its value, so the record is
  *  loggable —, the rule that withheld it, how strong that claim is, and the minting module. */
@@ -50,34 +52,100 @@ export declare function isSecretEnvKey(key: string, value?: string): boolean;
 export declare function scrubSecretEnv(env: NodeJS.ProcessEnv, findings?: SecretEnvFinding[]): NodeJS.ProcessEnv;
 /** How much of this process's environment a child spawned on this host inherits — the `inheritEnv` value. */
 export type InheritEnvPolicy = "all" | "scrub" | string[];
+/** What {@link declareWithheldEnv} takes: this deployment's own credentials in this process's environment. */
+export interface WithheldEnvDeclaration {
+    /** Names of variables that are this deployment's own credentials: never inherited, and an allow list naming one is refused. */
+    readonly names: readonly string[];
+    /** Credential values this deployment holds: an inherited entry whose value equals one — the same string, compared
+     *  whole, never as a part — is never inherited, whatever its name. A value must be a credential: not white space only,
+     *  a flag or placeholder word, one character repeated, or fewer than eight characters. */
+    readonly values: readonly string[];
+}
 /**
- * Declare the names of this deployment's OWN credentials in this process's environment — the engine's or its host's:
- * an approval bearer, a service token. From then on no child spawned on this host inherits one, whatever the policy:
- * every spawn site reads its environment through {@link inheritedHostEnv}, which subtracts them from `"all"` and from
- * the scrub's result (each one present is a finding of kind `own-credential`), and {@link inheritEnvPolicyProblem}
- * refuses an allow list naming one. Compared as the platform compares variable names: exactly, but case-blind on
- * Windows. A variable a host hands a child itself (a shell's `shellEnv`, a per-exec `env`, a language server's `env`, an MCP server entry's `env`)
- * is its explicit grant and is not read against the list.
+ * Declare this deployment's OWN credentials in this process's environment — the engine's or its host's: an approval
+ * bearer, a service token — by name and by value. From then on no child spawned on this host inherits one, whatever the
+ * policy: every spawn site reads its environment through {@link inheritedHostEnv}, which subtracts from `"all"`, from the
+ * scrub's result and from an allow list's every entry that is this deployment's own credential (each one present is a
+ * finding of kind `own-credential`), and {@link inheritEnvPolicyProblem} refuses an allow list naming a declared name.
+ * A NAME is compared as the platform compares variable names: exactly, but case-blind on Windows. A VALUE is compared
+ * whole, as the same string: an entry holding it as a part (`Bearer <value>`, a URL, an encoding of it) is not its value.
+ * Besides the declared values, every value the engine took in itself ({@link holdOwnCredentialValues}) is withheld the
+ * same way. A variable a host hands a child itself (a shell's `shellEnv`, a per-exec `env`, a language server's `env`,
+ * an MCP server entry's `env`) is its explicit grant and is not read against the table.
  *
- * Declared once, at start-up, before anything spawns; a later call REPLACES the list (a configuration reload), read
- * from the next spawn on — a spawn whose environment is already read (one announcing its findings) keeps it. The
- * list is copied. A malformed list — not an array, an entry that is no variable name, or a name the host hands every
- * child anyway ({@link runtimeSuppliedEnv}) — throws and leaves the declaration as it was.
+ * Declared once, at start-up, before anything spawns; a later call REPLACES the declaration whole (a configuration
+ * reload), read from the next spawn on — a spawn whose environment is already read (one announcing its findings) keeps
+ * it; the values the engine took in stay. The lists are copied, and a value is kept only as a digest (no credential is
+ * held by the table). A malformed table — not a plain object `{ names, values }` (the names-only list of earlier releases
+ * included), a member besides those two, a list that is a Proxy or whose element throws while it is read, a name that
+ * is no variable name or that the host hands every child anyway ({@link runtimeSuppliedEnv}), a value that is not a
+ * string a variable can hold or is no credential ({@link notACredentialReason}: white space only, a flag or placeholder
+ * word, one character repeated, fewer than {@link CREDENTIAL_MIN_CHARS} characters — withholding it would take a setting
+ * such as `CI=true` from every child) or that is, in this process's environment now, the value of such a variable —
+ * throws and leaves the declaration as it was. A value listed twice is the one value (the declaration is a set). No
+ * refusal sentence repeats a value.
  *
  * Two Windows readings, measured on a real machine: a withheld name that the child's own shell or runtime re-creates
  * with a DEFAULT of its own (`ComSpec`, `PATHEXT`, `HOME`, `CommonProgramFiles`, …) shows up in the child's table with
  * that default, never with this process's value — withheld, not leaked; and the disclosure (`detail.ownCredentials`)
  * spells each withheld name as this process's environment spells it, not as the declaration spelled it.
  */
-export declare function declareWithheldEnv(names: readonly string[]): void;
-/** Test seam: never called by production code (a host re-declares `[]`). */
+export declare function declareWithheldEnv(table: WithheldEnvDeclaration): void;
+/**
+ * The engine takes credential values in — each where the engine receives it: a first-party brain's construction
+ * credential (`brainConfigSnapshot`), a model entry's own credential headers (`resolveRouteCredential`), a protocol
+ * peer's credential headers (`resolveProtocolHttpHeaders`), the memory distiller's chat seat key (`openAiCompatChatSeat`,
+ * and `RunnerDeps.memoryConsolidationDriver.chat` at `new Runner`, before that seat is built). From then on, for the
+ * life of the process, no child spawned on this host inherits an entry whose value equals one: the same table, the same
+ * subtraction, finding and disclosure as a declared value ({@link declareWithheldEnv}). A credential the engine is handed
+ * per request (a per-model auth hook's answer) is not taken in: the host that resolves it owns it and declares it.
+ * An absent or empty value adds nothing. A value that is no credential ({@link notACredentialReason}: white space, a
+ * flag or placeholder word, one character repeated, fewer than {@link CREDENTIAL_MIN_CHARS} characters — the key a local
+ * gateway is told to be handed) is not taken in: its holder uses it as given (it is no bad value), and the variables
+ * that hold the same string stay with every child. Said once per process per value, never the value, as the notice
+ * `config.credential_not_withheld` through the engine's one notice throat ({@link deliverEngineNotice}): to `onNotice`
+ * when the intake has the structured seat in hand (the `RunnerDeps` receipt at `new Runner`), else as that notice's
+ * line on `console.warn` (the throat's own arm for an absent seat — a brain's construction, a request's route reading,
+ * a peer's dial, a directly built distiller seat). A value that is, in this process's
+ * environment now, the value of a variable every child is handed whatever the spawn passes cannot be withheld: the intake
+ * throws (`config.invalid_argument`, the variable named, never the value) and takes nothing in — the brain is not built,
+ * the peer is not dialed.
+ */
+export declare function holdOwnCredentialValues(values: Iterable<string | undefined>, onNotice?: (notice: EngineNotice) => void): void;
+/** THE one reading of which HTTP header carries a credential by its NAME — the credential vocabulary's header-name
+ *  reading ({@link isSensitiveHeaderName}: `Authorization`, `Proxy-Authorization`, `X-Api-Key`, Azure's `api-key`,
+ *  `x-goog-api-key`, `Cookie`, any name holding a credential word; not a gateway's own spelling of a name the
+ *  vocabulary declares non-secret, `cf-aig-cache-key` / `X-Idempotency-Key`). The reading of a record MEMBER's name
+ *  (`isSensitiveRecordKey`), which decides what a record shows, takes those declared names whole only. Every face that
+ *  asks "which header is a credential, by its name" reads this one: the withheld-value intake below
+ *  ({@link credentialHeaderValues}) and the route law — which bag carries a credential, which header values a per-model
+ *  credential's identity is read from, which headers the per-model winner strips, which the user-header merge leaves to
+ *  that strip, which the run-static stream options refuse. The NAME is the shared half: the intake adds a half of its
+ *  own, a value that looks like a credential under any name ({@link looksLikeCredentialValue}) — a guess it may make,
+ *  because withholding a value from a child costs little; the route law does not, because a header it reads as a
+ *  credential replaces the deployment's key and is bound to an origin, and a guess that is wrong drops a key that should
+ *  have gone out. */
+export declare function isCredentialHeaderName(name: string): boolean;
+/** Whether a credential header's value is `<auth-scheme> <credentials>` by definition (RFC 9110 §11.6.2 / §11.7.2:
+ *  `Authorization`, `Proxy-Authorization`) — the scheme word is public and the credentials part is the secret. Any other
+ *  credential header's value is opaque, read whole. */
+export declare function isSchemedCredentialHeader(name: string): boolean;
+/** The credential values a header bag carries: each header whose name is a credential header ({@link isCredentialHeaderName})
+ *  or whose value carries one ({@link looksLikeCredentialValue}), as written and, when it reads `<scheme> <credentials>`,
+ *  its credentials part too — the spelling a variable copied from it would carry. A schemed header's
+ *  ({@link isSchemedCredentialHeader}) value over a credentials part that is no credential (`Bearer 1`) gives that part
+ *  alone — the engine's intake then does not take it in — and not the whole value, which carries nothing else. Any other
+ *  header (`User-Agent`, `Accept`, a region) is no credential. */
+export declare function credentialHeaderValues(headers: Readonly<Record<string, string>> | undefined): string[];
+/** Test seam: never called by production code (a host re-declares `{ names: [], values: [] }`; what the engine took in stays). */
 export declare function __resetWithheldEnv(): void;
 /**
- * THE environment a child spawned ON THIS HOST inherits: the policy's arm, less the declared own credentials
- * ({@link declareWithheldEnv}). The arms: `"scrub"` (and absent) is this process's environment through
+ * THE environment a child spawned ON THIS HOST inherits: the policy's arm, less this deployment's own credentials — a
+ * declared name, or a value equal to a declared or engine-held credential value ({@link declareWithheldEnv},
+ * {@link holdOwnCredentialValues}). The arms: `"scrub"` (and absent) is this process's environment through
  * {@link scrubSecretEnv}; `"all"` is this process's environment as written; a `string[]` is exactly the named
  * variables that are set, as written — a strict allow list, so a name it leaves out (`PATH` included) is not
- * inherited. `findings` collects every entry withheld: the scrub's, and each declared own credential the arm held.
+ * inherited. `findings` collects every entry withheld: the scrub's, and each own credential the arm held.
  *
  * A policy {@link inheritEnvPolicyProblem} refuses throws that reason HERE, at every spawn, read against the
  * declaration as it stands: a value that is no policy at all (never read as the scrub), and an allow list naming a

package/dist/core/secret-env.js

@@ -1,6 +1,9 @@
-import { CREDENTIAL_VOCABULARY, envNameView, splitCamelCase } from "./credential-vocabulary.js";
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+import { CREDENTIAL_MIN_CHARS, CREDENTIAL_VOCABULARY, envNameView, isSensitiveHeaderName, splitCamelCase } from "./credential-vocabulary.js";
 import { DEFAULT_INHERITED_ENV_VARS } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { deliverEngineNotice } from "./engine-notice.js";
+import { receiveOwnProperties } from "./own-property-receipt.js";
 const GIT_CONFIG_ENV_RE = /^GIT_CONFIG_(?:COUNT|PARAMETERS|(?:KEY|VALUE)_[0-9]+)$/;
 const PROXY_ENV_RE = /^(?:(?:https?|ftp|all|no)_proxy|npm_config_(?:https?_)?proxy|npm_config_noproxy|yarn_proxy|(?:yarn|global_agent|docker|claude_code)_(?:https?|no)_proxy|cloudsdk_proxy_[a-z]+|electron_get_use_proxy)$/i;
 function isExemptEnvName(name) {
@@ -66,13 +69,14 @@ function carriesSchemelessUserinfo(text) {
     const at = text.lastIndexOf("@", text.search(/\s|$/));
     return !isHostPortPathBeforeAt(text.slice(0, at), text.slice(at + 1)) && !/^(?:mailto|sips?|xmpp|im|acct):/i.test(text);
 }
-const CREDENTIAL_ASSIGNMENT_RE = /(?:(?:^|[;&?#,{]|\/:)\s*|\s)["']?(?!-*jobserver-auth\s*[=:])(?:[a-z0-9_.-]{0,64}(?:password|passwd|pwd|secret|token|(?:account|access|api|private|subscription)[-_]?key|signature|sig|credential)|[a-z0-9_.-]{0,63}[_.-]auth)["']?\s*[=:]\s*["']?(?!(?:true|false|none|null|yes|no|on|off|enabled|disabled|required|optional)(?:$|[;&,\s"']))[^;&,\s"']+/i;
+const FLAG_WORDS = ["true", "false", "none", "null", "yes", "no", "on", "off", "enabled", "disabled", "required", "optional"];
+const CREDENTIAL_ASSIGNMENT_RE = new RegExp(String.raw `(?:(?:^|[;&?#,{]|\/:)\s*|\s)["']?(?!-*jobserver-auth\s*[=:])(?:[a-z0-9_.-]{0,64}(?:password|passwd|pwd|secret|token|(?:account|access|api|private|subscription)[-_]?key|signature|sig|credential)|[a-z0-9_.-]{0,63}[_.-]auth)["']?\s*[=:]\s*["']?(?!(?:${FLAG_WORDS.join("|")})(?:$|[;&,\s"']))[^;&,\s"']+`, "i");
 const WEBHOOK_URL_RE = /https:\/\/(?:hooks\.slack\.com\/(?:services|workflows|triggers)\/|(?:ptb\.|canary\.)?discord(?:app)?\.com\/api\/webhooks\/\d+\/|[\w.-]+\.webhook\.office\.com\/webhookb2\/)[\w\/@.~-]{16,}/i;
-const SONAR_LOGIN_RE = /["']?sonar\.login["']?\s*[:=]\s*["']?[^\s"',}]{8,}/;
+const SONAR_LOGIN_RE = new RegExp(String.raw `["']?sonar\.login["']?\s*[:=]\s*["']?[^\s"',}]{${CREDENTIAL_MIN_CHARS},}`);
 const PRIVATE_KEY_HEADER_RE = /-----BEGIN [A-Z ]*PRIVATE KEY(?: BLOCK)?-----/;
-const AUTHORIZATION_HEADER_RE = /\bauthorization\s*[:=]\s*["']?[a-z][a-z0-9_-]*\s+[A-Za-z0-9._~+\/=-]{8,}/i;
+const AUTHORIZATION_HEADER_RE = new RegExp(String.raw `\bauthorization\s*[:=]\s*["']?[a-z][a-z0-9_-]*\s+[A-Za-z0-9._~+\/=-]{${CREDENTIAL_MIN_CHARS},}`, "i");
 const TOKEN_WORD_RE = /\b(?:[Tt]oken|TOKEN)\s+(?=[A-Za-z0-9_~+=-]*[0-9])(?=[A-Za-z0-9_~+=-]*[A-Z])(?=([A-Za-z0-9_~+=-]{20,}))\1(?![\/.])/;
-const BEARER_BASIC_RE = /\b(?:Bearer|Basic)\s+(?=[A-Za-z._~+\/=-]*[0-9]|(?:[A-Za-z0-9._~+\/=-]*?[a-z][A-Z](?![a-z])){2}|[A-Za-z0-9.-]*[_~+\/=])[A-Za-z0-9._~+\/=-]{8,}/;
+const BEARER_BASIC_RE = new RegExp(String.raw `\b(?:Bearer|Basic)\s+(?=[A-Za-z._~+\/=-]*[0-9]|(?:[A-Za-z0-9._~+\/=-]*?[a-z][A-Z](?![a-z])){2}|[A-Za-z0-9.-]*[_~+\/=])[A-Za-z0-9._~+\/=-]{${CREDENTIAL_MIN_CHARS},}`);
 export function looksLikeCredentialValue(value) {
     const text = value.length > VALUE_SCAN_LIMIT ? value.slice(0, VALUE_SCAN_LIMIT) : value;
     for (let at = text.indexOf("://"); at !== -1; at = text.indexOf("://", at + 3)) {
@@ -149,39 +153,188 @@ const WINDOWS_REQUIRED_ENV = Object.freeze(["HOMEDRIVE", "HOMEPATH", "LOGONSERVE
 function runtimeSuppliedEnv() {
     return ["NODE_V8_COVERAGE", ...DEFAULT_INHERITED_ENV_VARS, ...(process.platform === "win32" ? WINDOWS_REQUIRED_ENV : [])];
 }
-const WITHHELD_ENV = Symbol.for("sema.core.withheldEnv");
-const NOTHING_WITHHELD = Object.freeze([]);
-const withheldEnvOf = () => {
-    const held = Reflect.get(globalThis, WITHHELD_ENV);
-    return Array.isArray(held) ? held : NOTHING_WITHHELD;
+const valueDigest = (value) => createHash("sha256").update(value, "utf16le").digest("base64");
+const indexHas = (index, value) => {
+    const digests = index.get(value.length);
+    return digests !== undefined && digests.has(valueDigest(value));
+};
+const indexAdd = (index, value) => {
+    const digests = index.get(value.length);
+    if (digests === undefined)
+        index.set(value.length, new Set([valueDigest(value)]));
+    else
+        digests.add(valueDigest(value));
 };
-const setWithheldEnv = (names) => {
-    Reflect.set(globalThis, WITHHELD_ENV, Object.freeze([...names]));
+const WITHHELD_ENV = Symbol.for("sema.core.withheldEnvTable");
+const NOTHING_NAMED = Object.freeze([]);
+const isWithheldEnvTable = (t) => typeof t === "object" && t !== null && Array.isArray(t.names) && t.declared instanceof Map && t.held instanceof Map;
+const withheldEnvOf = () => {
+    const slot = Reflect.get(globalThis, WITHHELD_ENV);
+    if (isWithheldEnvTable(slot))
+        return slot;
+    const fresh = { names: NOTHING_NAMED, declared: new Map(), held: new Map() };
+    Reflect.set(globalThis, WITHHELD_ENV, fresh);
+    return fresh;
 };
-export function declareWithheldEnv(names) {
-    const value = names;
-    if (!Array.isArray(value))
-        throw new Error(`declareWithheldEnv: the list must be an array of variable names (got ${typeof value === "string" ? JSON.stringify(value) : value === null ? "null" : typeof value})`);
-    const problem = variableNameListProblem("names", value);
+const kindOf = (v) => (v === null ? "null" : Array.isArray(v) ? "an array" : typeof v);
+function listCopy(label, list) {
+    if (types.isProxy(list))
+        throw new Error(`declareWithheldEnv: ${label} must be a plain array, not a Proxy`);
+    const copy = [];
+    try {
+        for (let i = 0, n = list.length; i < n; i++)
+            copy[i] = list[i];
+    }
+    catch {
+        throw new Error(`declareWithheldEnv: an element of ${label} threw while it was read — refused`);
+    }
+    return Object.freeze(copy);
+}
+const CANNOT_BE_WITHHELD = "which a child is handed from this process's environment whatever the spawn passes (by Node, the MCP stdio transport or Windows) — it cannot be withheld";
+function runtimeSuppliedHolderOf(value) {
+    const supplied = policyArm([...runtimeSuppliedEnv()]);
+    return Object.keys(supplied).find((k) => supplied[k] === value);
+}
+const PLACEHOLDER_KEY_WORDS = new Set([...FLAG_WORDS, "undefined", "placeholder", "lm-studio", "not-needed", "sk-no-key-required"]);
+const ONE_REPEATED_CHARACTER_RE = /^(\S)\1{2,}$/u;
+function notACredentialReason(value) {
+    const text = value.trim();
+    if (text === "")
+        return "white space only, which every blank variable equals";
+    if (text.length < CREDENTIAL_MIN_CHARS)
+        return `a string of fewer than ${CREDENTIAL_MIN_CHARS} characters, which names no secret`;
+    if (PLACEHOLDER_KEY_WORDS.has(text.toLowerCase()))
+        return "a flag or placeholder word, which names no secret";
+    if (ONE_REPEATED_CHARACTER_RE.test(text.replace(CREDENTIAL_VOCABULARY.tokenPrefix, "")))
+        return "one character repeated, which names no secret";
+    return undefined;
+}
+function credentialValueProblem(v) {
+    if (typeof v !== "string")
+        return kindOf(v);
+    if (v === "")
+        return "an empty string, which every variable set to nothing equals";
+    if (v.includes("\0") || UNPAIRED_SURROGATE_RE.test(v))
+        return `a value holding ${v.includes("\0") ? "a NUL" : "an unpaired surrogate"}, which no variable can hold`;
+    return notACredentialReason(v);
+}
+function credentialValueListProblem(value) {
+    for (const [i, v] of value.entries()) {
+        const why = credentialValueProblem(v);
+        if (why !== undefined)
+            return `values[${i}] is not a credential value (got ${why})`;
+    }
+    return undefined;
+}
+export function declareWithheldEnv(table) {
+    const given = table;
+    if (given === null || typeof given !== "object" || Array.isArray(given)) {
+        throw new Error(`declareWithheldEnv: the declaration must be a table { names, values } (got ${Array.isArray(given) ? "an array — a names-only list is no longer a declaration: pass { names, values }" : kindOf(given)})`);
+    }
+    const received = receiveOwnProperties(given, { subject: "declareWithheldEnv's table", unit: "member", moment: "at the declaration" });
+    const stray = Object.keys(received).find((k) => k !== "names" && k !== "values");
+    if (stray !== undefined)
+        throw new Error(`declareWithheldEnv: the table has a member ${JSON.stringify(stray.slice(0, 64))} — it holds names and values only`);
+    const givenNames = received.names;
+    if (!Array.isArray(givenNames))
+        throw new Error(`declareWithheldEnv: names must be an array of variable names (got ${kindOf(givenNames)})`);
+    const names = listCopy("names", givenNames);
+    const problem = variableNameListProblem("names", names);
     if (problem !== undefined)
         throw new Error(`declareWithheldEnv: ${problem}`);
     const supplied = new Set(runtimeSuppliedEnv().map(envNameKey));
-    const unwithholdable = value.findIndex((k) => supplied.has(envNameKey(k)));
+    const unwithholdable = names.findIndex((k) => supplied.has(envNameKey(k)));
     if (unwithholdable !== -1)
-        throw new Error(`declareWithheldEnv: names[${unwithholdable}] is ${value[unwithholdable]}, which a child is handed from this process's environment whatever the spawn passes (by Node, the MCP stdio transport or Windows) — it cannot be withheld`);
-    setWithheldEnv(value);
+        throw new Error(`declareWithheldEnv: names[${unwithholdable}] is ${String(names[unwithholdable])}, ${CANNOT_BE_WITHHELD}`);
+    const givenValues = received.values;
+    if (!Array.isArray(givenValues))
+        throw new Error(`declareWithheldEnv: values must be an array of credential values (got ${kindOf(givenValues)})`);
+    const values = listCopy("values", givenValues);
+    const valueProblem = credentialValueListProblem(values);
+    if (valueProblem !== undefined)
+        throw new Error(`declareWithheldEnv: ${valueProblem}`);
+    for (const [i, v] of values.entries()) {
+        const holder = runtimeSuppliedHolderOf(v);
+        if (holder !== undefined)
+            throw new Error(`declareWithheldEnv: values[${i}] is the value of ${holder}, ${CANNOT_BE_WITHHELD}`);
+    }
+    const declared = new Map();
+    for (const v of values)
+        indexAdd(declared, v);
+    Reflect.set(globalThis, WITHHELD_ENV, { names: names, declared, held: withheldEnvOf().held });
+}
+export function holdOwnCredentialValues(values, onNotice) {
+    const given = [...values].filter((v) => typeof v === "string" && v.length > 0);
+    const taken = given.filter((v) => {
+        const why = notACredentialReason(v);
+        if (why !== undefined)
+            sayNotTaken(v, why, onNotice);
+        return why === undefined;
+    });
+    for (const v of taken) {
+        const holder = runtimeSuppliedHolderOf(v);
+        if (holder !== undefined)
+            throw Object.assign(new Error(`a credential the engine was handed is the value of ${holder}, ${CANNOT_BE_WITHHELD}; the credential is refused`), { code: "config.invalid_argument" });
+    }
+    const { held } = withheldEnvOf();
+    for (const v of taken)
+        indexAdd(held, v);
+}
+const AUTH_SCHEME_VALUE_RE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+ +(\S[\s\S]*)$/;
+const SCHEMED_HEADER_RE = /^(?:proxy-)?authorization$/i;
+export function isCredentialHeaderName(name) {
+    return isSensitiveHeaderName(name);
+}
+export function isSchemedCredentialHeader(name) {
+    return SCHEMED_HEADER_RE.test(name);
+}
+export function credentialHeaderValues(headers) {
+    const out = [];
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        if (typeof value !== "string" || !(isCredentialHeaderName(name) || looksLikeCredentialValue(value)))
+            continue;
+        const credentials = AUTH_SCHEME_VALUE_RE.exec(value)?.[1];
+        if (credentials !== undefined && isSchemedCredentialHeader(name) && notACredentialReason(credentials) !== undefined) {
+            out.push(credentials);
+            continue;
+        }
+        out.push(value);
+        if (credentials !== undefined)
+            out.push(credentials);
+    }
+    return out;
+}
+const intakeSaid = new Set();
+function sayNotTaken(value, why, onNotice) {
+    const key = valueDigest(value.trim());
+    if (intakeSaid.has(key))
+        return;
+    intakeSaid.add(key);
+    try {
+        deliverEngineNotice(onNotice, {
+            code: "config.credential_not_withheld",
+            message: `a credential the engine was handed is ${why} — it is used as given, but a variable holding the same string is not withheld from a spawned child (said once per value; the value is not repeated)`,
+            detail: { reason: why },
+        });
+    }
+    catch {
+    }
 }
 export function __resetWithheldEnv() {
-    setWithheldEnv([]);
+    Reflect.set(globalThis, WITHHELD_ENV, { names: NOTHING_NAMED, declared: new Map(), held: new Map() });
+    intakeSaid.clear();
 }
 function withholdOwnCredentials(inherited, findings) {
-    if (withheldEnvOf().length === 0)
+    const table = withheldEnvOf();
+    if (table.names.length === 0 && table.declared.size === 0 && table.held.size === 0)
         return inherited;
-    const own = new Set(withheldEnvOf().map(envNameKey));
+    const own = new Set(table.names.map(envNameKey));
     const kept = [];
     for (const key of Object.keys(inherited)) {
-        if (!own.has(envNameKey(key)))
-            kept.push([key, inherited[key]]);
+        const value = inherited[key];
+        const ownValue = typeof value === "string" && (indexHas(table.declared, value) || indexHas(table.held, value));
+        if (!own.has(envNameKey(key)) && !ownValue)
+            kept.push([key, value]);
         else
             findings?.push({ key, kind: "own-credential", confidence: SECRET_ENV_KIND_CONFIDENCE["own-credential"], source: "secret-env" });
     }
@@ -198,24 +351,25 @@ export function inheritedHostEnv(policy, findings) {
     const problem = inheritEnvPolicyProblem(policy);
     if (problem !== undefined)
         throw new Error(problem);
-    let arm;
+    return withholdOwnCredentials(policyArm(policy, findings), findings);
+}
+function policyArm(policy, findings) {
     if (policy === "all")
-        arm = { ...process.env };
-    else if (Array.isArray(policy)) {
-        arm = {};
-        for (const k of policy)
-            if (process.env[k] !== undefined)
-                arm[k] = process.env[k];
-    }
-    else
-        arm = scrubSecretEnv(process.env, findings);
-    return withholdOwnCredentials(arm, findings);
+        return { ...process.env };
+    if (!Array.isArray(policy))
+        return scrubSecretEnv(process.env, findings);
+    const arm = {};
+    for (const k of policy)
+        if (process.env[k] !== undefined)
+            arm[k] = process.env[k];
+    return arm;
 }
 export function inheritEnvPolicyProblem(value) {
     const shape = policyShapeProblem(value);
-    if (shape !== undefined || !Array.isArray(value) || withheldEnvOf().length === 0)
+    const { names } = withheldEnvOf();
+    if (shape !== undefined || !Array.isArray(value) || names.length === 0)
         return shape;
-    const own = new Set(withheldEnvOf().map(envNameKey));
+    const own = new Set(names.map(envNameKey));
     const named = value.findIndex((k) => own.has(envNameKey(k)));
     return named === -1 ? undefined : `inheritEnv[${named}] names ${value[named]}, which is this deployment's own credential and cannot be inherited by a child (a configuration error: no retry succeeds until the policy or the declaration changes)`;
 }