@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/gates/credentials.d.ts

@@ -6,6 +6,25 @@ export interface SourceProbe {
     outcome: "clean" | "resolvable" | "error";
     detail: string;
 }
+/**
+ * THIS VOCABULARY IS NOW READ BY THE KERNEL AS WELL AS BY THIS GATE
+ * (M4-P8 step 4, and this comment IS the record that step requires).
+ *
+ * `src/exec/env.ts` imports `GH_TOKEN_VARIABLES` and `isDangerousEnvName`
+ * from here to refuse a per-invocation allowlist extension naming one of
+ * them. The plan offered two shapes, move the vocabulary to a third module
+ * or export it from here, and the choice taken is EXPORT FROM HERE: the
+ * walk above, the per-name sources below and the constants stay in one
+ * file, so a future editor extending the vocabulary cannot extend it
+ * somewhere the other reader does not see. What is forbidden is a second
+ * copy: two lists drift, and they drift silently toward the permissive
+ * side.
+ *
+ * NOTHING ABOUT WHAT EITHER GATE DECIDES CHANGES WITH THAT IMPORT. The
+ * constants, the pattern and `isDangerousEnvName` are byte-identical to
+ * their M2-P8 form; the only difference is that a second module now reads
+ * them.
+ */
 /**
  * gh's documented token vocabulary (see the module comment for the walk).
  * Never permitted in a child environment, allowlisted or not.
@@ -32,6 +51,27 @@ export declare const GH_TOKEN_VARIABLES: readonly string[];
  *                         are matched by isDangerousEnvName's pattern.
  *   ssh (ssh(1), ssh-add(1)):
  *     SSH_ASKPASS       - program ssh runs to obtain a passphrase.
+ *     SSH_AUTH_SOCK     - the agent socket. ADDED BY THE DR-0047 SWEEP FIX
+ *                         ROUND, and the basis is stated here rather than
+ *                         implied because HALF OF IT IS UNVERIFIED. What was
+ *                         MEASURED in this container: the name sat in neither
+ *                         walked vocabulary, so the audited route ACCEPTED it
+ *                         (clean-room-final-credential-criteria CR-F-CRED-004),
+ *                         and buildChildEnv's default child does not carry it,
+ *                         so refusing an extension that names it withdraws
+ *                         nothing the default grants. What could NOT be
+ *                         verified here: this container has no ssh binary and
+ *                         no man page (`ssh -V` -> command not found, `man 1
+ *                         ssh` -> nothing), so the claim that ssh(1)'s own
+ *                         ENVIRONMENT section documents it was NOT read from
+ *                         the page. The row therefore rests on capability
+ *                         reasoning, not on the walk: the socket is a SIGNING
+ *                         channel (any holder can authenticate as the owner to
+ *                         any host the agent holds a key for), which is
+ *                         strictly stronger than SSH_ASKPASS, a passphrase
+ *                         PROMPT, which the same row already refuses. A later
+ *                         round with the page should either confirm this row
+ *                         from ssh(1) or move it and say why.
  *   node / dynamic loader / shell startup (node(1), ld.so(8), bash(1)):
  *     NODE_OPTIONS       - options node applies at startup (can require
  *                          arbitrary modules), arbitrary code execution.
@@ -48,8 +88,127 @@ export declare const GH_TOKEN_VARIABLES: readonly string[];
  * real run.
  */
 export declare const DANGEROUS_ENV_VOCABULARY: readonly string[];
+/**
+ * THE EGRESS VOCABULARY (M4-P29, and this comment is the record of why it
+ * exists as a SEPARATE list rather than as more rows of the one above).
+ *
+ * WHAT WAS MEASURED. delivery/verification/m4-prototype-probes.md:46
+ * recorded that this gate's verdict is INVERTED with respect to real
+ * capability: it reddens `GIT_CONFIG_*`, which in that container bought
+ * only URL rewriting, and it greens `HTTPS_PROXY`, which bought full
+ * GitHub reach. M4-P8 then measured the same thing from the other side,
+ * four arms through `spawnTask` differing only in the allowlist extension
+ * (delivery/work-history/m4-p8.md:116): arm A, ten variables, HTTP 403
+ * from `api.github.com/user`; arm B, the same ten plus `HTTPS_PROXY`,
+ * HTTP 200. One variable, and it is the one nothing in this module knew
+ * about. A gate that cannot go red for the case that matters is the shape
+ * this repository keeps paying for.
+ *
+ * WHAT THIS FIXES AND WHAT IT DOES NOT, stated here rather than left to be
+ * discovered. It closes the case where the DEFAULT allowlist in
+ * src/exec/env.ts gains an egress name: this tripwire is
+ * allowlist-INDEPENDENT, exactly like the two above it, so the widening
+ * costs a red instead of buying a green. It does NOT close the case
+ * M4-P8's arm B actually used, which is a PER-INVOCATION
+ * `extraAllowlist`: that argument is runtime data of one spawn, this gate
+ * probes the constructed default child, and no probe of a default can see
+ * an argument a caller has not passed yet. Closing that half means
+ * auditing the extension record a task writes, which is a different gate
+ * and a different phase.
+ *
+ * WHY A SEPARATE LIST, AND WHAT DR-0048 CHANGED ABOUT ITS CONSEQUENCE.
+ * M4-P29 kept these names out of `DANGEROUS_ENV_VOCABULARY` so that a data
+ * edit in this file would not, as a side effect, refuse M4-P8's audited
+ * extension in a module that phase did not touch. It named the underlying
+ * question (whether an egress name may ever be extended) as a kernel design
+ * question with an owner-facing cost, and routed it onward rather than
+ * taking it by accident.
+ *
+ * DR-0048 answered that question: the audited route REFUSES egress names.
+ * The two lists still stay separate, because they are walked from different
+ * programs' documentation and their per-name evidence is different, and
+ * `isDangerousEnvName` is still byte-for-byte what it was. What changed is
+ * that the refusal in src/exec/env.ts no longer walks a HAND-PICKED PAIR of
+ * vocabularies: it walks `REFUSED_CHILD_ENV_VOCABULARIES` below, which is
+ * the declared list of every vocabulary in this module, this one included.
+ *
+ * THE WALK, per name, from the consuming programs' own documentation
+ * (curl(1) "ENVIRONMENT", git(1) "http_proxy", wget(1) "ENVIRONMENT"):
+ * each of these names a proxy a child's HTTP client will route through,
+ * in both the upper-case and lower-case spellings those pages document.
+ *
+ *   HTTP_PROXY / http_proxy   - proxy for http:// requests.
+ *   HTTPS_PROXY / https_proxy - proxy for https:// requests. THE MEASURED
+ *                               NAME: arm A 403 against arm B 200.
+ *   ALL_PROXY / all_proxy     - proxy for every scheme.
+ *   FTP_PROXY / ftp_proxy     - proxy for ftp:// requests.
+ *
+ * TWO NAMES ARE DELIBERATELY ABSENT, and both absences are measured rather
+ * than assumed. `NO_PROXY` / `no_proxy` NARROW reach instead of granting
+ * it, so listing them would redden a child that is strictly less capable.
+ * `CURL_CA_BUNDLE` is a TLS-trust channel and not an egress grant: M4-P8's
+ * arm C added it on top of arm B and measured the same HTTP 200 arm B
+ * already had (delivery/work-history/m4-p8.md:117), so it buys no reach,
+ * and its node-side sibling `NODE_EXTRA_CA_CERTS` is already covered by
+ * `DANGEROUS_ENV_VOCABULARY` above.
+ *
+ * LIKE THE LIST ABOVE THIS IS A BOUNDED DENYLIST. The allowlist in
+ * src/exec/env.ts is still the real defense; this makes a widening cost a
+ * red for the names walked here, it does not enumerate every way a child
+ * could be handed network reach.
+ */
+export declare const EGRESS_ENV_VOCABULARY: readonly string[];
+/** Whether a variable name is in the walked egress vocabulary. */
+export declare function isEgressEnvName(name: string): boolean;
 /** Whether a variable name is in the walked dangerous vocabulary. */
 export declare function isDangerousEnvName(name: string): boolean;
+/** One walked vocabulary, as a refusal walks it. */
+export interface RefusedEnvVocabulary {
+    /** Stable id, used in tests and in nothing an operator reads. */
+    id: string;
+    /** The exported constant this row stands for, named for the drift test. */
+    constantName: string;
+    /** Whether this vocabulary claims the name. */
+    includes: (name: string) => boolean;
+    /**
+     * The middle of the refusal sentence: "the allowlist extension entry X "
+     * + this + " and may never cross into a child environment".
+     */
+    clause: string;
+}
+/**
+ * EVERY VOCABULARY A CHILD-ENVIRONMENT REFUSAL MUST WALK, IN ONE PLACE.
+ *
+ * THE MECHANISM THIS EXISTS AGAINST (CH-001 high, CR-F-CRED-003, CR-F-CRED-004;
+ * DR-0048): a refusal that walks ONE vocabulary, or a hand-picked subset of
+ * them, while several exist. `refuseExtraAllowlist` (src/exec/env.ts) named
+ * `GH_TOKEN_VARIABLES` and `isDangerousEnvName` as two literal `if` arms and
+ * therefore could not see `EGRESS_ENV_VOCABULARY`, which this module had held
+ * since M4-P29. The defect is not that the third name was forgotten once; it
+ * is that ADDING a vocabulary to this module left every consumer's coverage
+ * unchanged and silent, so the subset could only be discovered by probing a
+ * name.
+ *
+ * So the list of vocabularies is data, exported from the module that owns
+ * them, and a consumer walks the LIST rather than naming members of it. A
+ * fourth vocabulary added below is walked by every consumer of this array the
+ * moment it gains a row here, and `test/payload-credentials.test.ts` reddens
+ * if a `*_VOCABULARY` or `*_VARIABLES` export of this module has NO row,
+ * which is the case a reader cannot see by reading either file alone.
+ *
+ * `probeCredentialSources` deliberately does NOT walk this array: it reports a
+ * different sentence per vocabulary in one fixed order, strongest first, and the three
+ * sentences are read by operators. It is covered by the same drift test from
+ * the other side.
+ */
+export declare const REFUSED_CHILD_ENV_VOCABULARIES: readonly RefusedEnvVocabulary[];
+/**
+ * The first vocabulary claiming `name`, or undefined. The ORDER of
+ * `REFUSED_CHILD_ENV_VOCABULARIES` is the order the refusal reports, and it
+ * is narrowest-first so that a name in two vocabularies is reported as the
+ * more specific one.
+ */
+export declare function refusedEnvVocabulary(name: string): RefusedEnvVocabulary | undefined;
 /** The names credential-scrub probes, in probe order. */
 export declare const CREDENTIAL_SOURCES: readonly string[];
 export interface ProbeOptions {

package/dist/src/gates/credentials.js

@@ -42,6 +42,14 @@ import { exitCodeForStatus, makeGateResult, renderGateResult, } from "./result.j
  *     ssh(1), node(1) and bash(1) document (DANGEROUS_ENV_VOCABULARY;
  *     see that constant for the per-name source).
  *
+ * A SECOND ALLOWLIST-INDEPENDENT TRIPWIRE WAS ADDED IN M4-P29, and its
+ * absence was a measured defect rather than an omission: this gate greened
+ * `HTTPS_PROXY`, the one name M4-P8 measured as the difference between
+ * HTTP 403 and HTTP 200 against `api.github.com/user` from inside a
+ * scrubbed child. The walk is `EGRESS_ENV_VOCABULARY` below; read its
+ * comment for what the addition does and does NOT close, because the
+ * per-invocation extension route stays outside this gate's view.
+ *
  * WHY THIS IS A TRIPWIRE, NOT THE SCRUB. The scrub is the allowlist in
  * src/exec/env.ts: nothing outside it can appear in a child by
  * construction, so the allowlist is the real defense. This tripwire is a
@@ -79,6 +87,25 @@ import { exitCodeForStatus, makeGateResult, renderGateResult, } from "./result.j
  * (plan criterion 7, owner-blocked).
  */
 const EX_USAGE = 64; // BSD sysexits, same value src/cli.ts exports.
+/**
+ * THIS VOCABULARY IS NOW READ BY THE KERNEL AS WELL AS BY THIS GATE
+ * (M4-P8 step 4, and this comment IS the record that step requires).
+ *
+ * `src/exec/env.ts` imports `GH_TOKEN_VARIABLES` and `isDangerousEnvName`
+ * from here to refuse a per-invocation allowlist extension naming one of
+ * them. The plan offered two shapes, move the vocabulary to a third module
+ * or export it from here, and the choice taken is EXPORT FROM HERE: the
+ * walk above, the per-name sources below and the constants stay in one
+ * file, so a future editor extending the vocabulary cannot extend it
+ * somewhere the other reader does not see. What is forbidden is a second
+ * copy: two lists drift, and they drift silently toward the permissive
+ * side.
+ *
+ * NOTHING ABOUT WHAT EITHER GATE DECIDES CHANGES WITH THAT IMPORT. The
+ * constants, the pattern and `isDangerousEnvName` are byte-identical to
+ * their M2-P8 form; the only difference is that a second module now reads
+ * them.
+ */
 /**
  * gh's documented token vocabulary (see the module comment for the walk).
  * Never permitted in a child environment, allowlisted or not.
@@ -110,6 +137,27 @@ export const GH_TOKEN_VARIABLES = [
  *                         are matched by isDangerousEnvName's pattern.
  *   ssh (ssh(1), ssh-add(1)):
  *     SSH_ASKPASS       - program ssh runs to obtain a passphrase.
+ *     SSH_AUTH_SOCK     - the agent socket. ADDED BY THE DR-0047 SWEEP FIX
+ *                         ROUND, and the basis is stated here rather than
+ *                         implied because HALF OF IT IS UNVERIFIED. What was
+ *                         MEASURED in this container: the name sat in neither
+ *                         walked vocabulary, so the audited route ACCEPTED it
+ *                         (clean-room-final-credential-criteria CR-F-CRED-004),
+ *                         and buildChildEnv's default child does not carry it,
+ *                         so refusing an extension that names it withdraws
+ *                         nothing the default grants. What could NOT be
+ *                         verified here: this container has no ssh binary and
+ *                         no man page (`ssh -V` -> command not found, `man 1
+ *                         ssh` -> nothing), so the claim that ssh(1)'s own
+ *                         ENVIRONMENT section documents it was NOT read from
+ *                         the page. The row therefore rests on capability
+ *                         reasoning, not on the walk: the socket is a SIGNING
+ *                         channel (any holder can authenticate as the owner to
+ *                         any host the agent holds a key for), which is
+ *                         strictly stronger than SSH_ASKPASS, a passphrase
+ *                         PROMPT, which the same row already refuses. A later
+ *                         round with the page should either confirm this row
+ *                         from ssh(1) or move it and say why.
  *   node / dynamic loader / shell startup (node(1), ld.so(8), bash(1)):
  *     NODE_OPTIONS       - options node applies at startup (can require
  *                          arbitrary modules), arbitrary code execution.
@@ -131,12 +179,96 @@ export const DANGEROUS_ENV_VOCABULARY = [
     "GIT_PROXY_COMMAND",
     "GIT_CONFIG_COUNT",
     "SSH_ASKPASS",
+    "SSH_AUTH_SOCK",
     "NODE_OPTIONS",
     "NODE_EXTRA_CA_CERTS",
     "LD_PRELOAD",
     "BASH_ENV",
     "ENV",
 ];
+/**
+ * THE EGRESS VOCABULARY (M4-P29, and this comment is the record of why it
+ * exists as a SEPARATE list rather than as more rows of the one above).
+ *
+ * WHAT WAS MEASURED. delivery/verification/m4-prototype-probes.md:46
+ * recorded that this gate's verdict is INVERTED with respect to real
+ * capability: it reddens `GIT_CONFIG_*`, which in that container bought
+ * only URL rewriting, and it greens `HTTPS_PROXY`, which bought full
+ * GitHub reach. M4-P8 then measured the same thing from the other side,
+ * four arms through `spawnTask` differing only in the allowlist extension
+ * (delivery/work-history/m4-p8.md:116): arm A, ten variables, HTTP 403
+ * from `api.github.com/user`; arm B, the same ten plus `HTTPS_PROXY`,
+ * HTTP 200. One variable, and it is the one nothing in this module knew
+ * about. A gate that cannot go red for the case that matters is the shape
+ * this repository keeps paying for.
+ *
+ * WHAT THIS FIXES AND WHAT IT DOES NOT, stated here rather than left to be
+ * discovered. It closes the case where the DEFAULT allowlist in
+ * src/exec/env.ts gains an egress name: this tripwire is
+ * allowlist-INDEPENDENT, exactly like the two above it, so the widening
+ * costs a red instead of buying a green. It does NOT close the case
+ * M4-P8's arm B actually used, which is a PER-INVOCATION
+ * `extraAllowlist`: that argument is runtime data of one spawn, this gate
+ * probes the constructed default child, and no probe of a default can see
+ * an argument a caller has not passed yet. Closing that half means
+ * auditing the extension record a task writes, which is a different gate
+ * and a different phase.
+ *
+ * WHY A SEPARATE LIST, AND WHAT DR-0048 CHANGED ABOUT ITS CONSEQUENCE.
+ * M4-P29 kept these names out of `DANGEROUS_ENV_VOCABULARY` so that a data
+ * edit in this file would not, as a side effect, refuse M4-P8's audited
+ * extension in a module that phase did not touch. It named the underlying
+ * question (whether an egress name may ever be extended) as a kernel design
+ * question with an owner-facing cost, and routed it onward rather than
+ * taking it by accident.
+ *
+ * DR-0048 answered that question: the audited route REFUSES egress names.
+ * The two lists still stay separate, because they are walked from different
+ * programs' documentation and their per-name evidence is different, and
+ * `isDangerousEnvName` is still byte-for-byte what it was. What changed is
+ * that the refusal in src/exec/env.ts no longer walks a HAND-PICKED PAIR of
+ * vocabularies: it walks `REFUSED_CHILD_ENV_VOCABULARIES` below, which is
+ * the declared list of every vocabulary in this module, this one included.
+ *
+ * THE WALK, per name, from the consuming programs' own documentation
+ * (curl(1) "ENVIRONMENT", git(1) "http_proxy", wget(1) "ENVIRONMENT"):
+ * each of these names a proxy a child's HTTP client will route through,
+ * in both the upper-case and lower-case spellings those pages document.
+ *
+ *   HTTP_PROXY / http_proxy   - proxy for http:// requests.
+ *   HTTPS_PROXY / https_proxy - proxy for https:// requests. THE MEASURED
+ *                               NAME: arm A 403 against arm B 200.
+ *   ALL_PROXY / all_proxy     - proxy for every scheme.
+ *   FTP_PROXY / ftp_proxy     - proxy for ftp:// requests.
+ *
+ * TWO NAMES ARE DELIBERATELY ABSENT, and both absences are measured rather
+ * than assumed. `NO_PROXY` / `no_proxy` NARROW reach instead of granting
+ * it, so listing them would redden a child that is strictly less capable.
+ * `CURL_CA_BUNDLE` is a TLS-trust channel and not an egress grant: M4-P8's
+ * arm C added it on top of arm B and measured the same HTTP 200 arm B
+ * already had (delivery/work-history/m4-p8.md:117), so it buys no reach,
+ * and its node-side sibling `NODE_EXTRA_CA_CERTS` is already covered by
+ * `DANGEROUS_ENV_VOCABULARY` above.
+ *
+ * LIKE THE LIST ABOVE THIS IS A BOUNDED DENYLIST. The allowlist in
+ * src/exec/env.ts is still the real defense; this makes a widening cost a
+ * red for the names walked here, it does not enumerate every way a child
+ * could be handed network reach.
+ */
+export const EGRESS_ENV_VOCABULARY = [
+    "HTTP_PROXY",
+    "http_proxy",
+    "HTTPS_PROXY",
+    "https_proxy",
+    "ALL_PROXY",
+    "all_proxy",
+    "FTP_PROXY",
+    "ftp_proxy",
+];
+/** Whether a variable name is in the walked egress vocabulary. */
+export function isEgressEnvName(name) {
+    return EGRESS_ENV_VOCABULARY.includes(name);
+}
 /**
  * git-config(1)'s numbered environment config-injection members:
  * GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> for n in [0, COUNT). The
@@ -149,6 +281,66 @@ export function isDangerousEnvName(name) {
     return (DANGEROUS_ENV_VOCABULARY.includes(name) ||
         GIT_CONFIG_INJECTION_MEMBER.test(name));
 }
+/**
+ * EVERY VOCABULARY A CHILD-ENVIRONMENT REFUSAL MUST WALK, IN ONE PLACE.
+ *
+ * THE MECHANISM THIS EXISTS AGAINST (CH-001 high, CR-F-CRED-003, CR-F-CRED-004;
+ * DR-0048): a refusal that walks ONE vocabulary, or a hand-picked subset of
+ * them, while several exist. `refuseExtraAllowlist` (src/exec/env.ts) named
+ * `GH_TOKEN_VARIABLES` and `isDangerousEnvName` as two literal `if` arms and
+ * therefore could not see `EGRESS_ENV_VOCABULARY`, which this module had held
+ * since M4-P29. The defect is not that the third name was forgotten once; it
+ * is that ADDING a vocabulary to this module left every consumer's coverage
+ * unchanged and silent, so the subset could only be discovered by probing a
+ * name.
+ *
+ * So the list of vocabularies is data, exported from the module that owns
+ * them, and a consumer walks the LIST rather than naming members of it. A
+ * fourth vocabulary added below is walked by every consumer of this array the
+ * moment it gains a row here, and `test/payload-credentials.test.ts` reddens
+ * if a `*_VOCABULARY` or `*_VARIABLES` export of this module has NO row,
+ * which is the case a reader cannot see by reading either file alone.
+ *
+ * `probeCredentialSources` deliberately does NOT walk this array: it reports a
+ * different sentence per vocabulary in one fixed order, strongest first, and the three
+ * sentences are read by operators. It is covered by the same drift test from
+ * the other side.
+ */
+export const REFUSED_CHILD_ENV_VOCABULARIES = [
+    {
+        id: "gh-token",
+        constantName: "GH_TOKEN_VARIABLES",
+        includes: (name) => GH_TOKEN_VARIABLES.includes(name),
+        clause: "is a documented gh token variable and may never cross into a child " +
+            "environment; the default allowlist gains no credential name and " +
+            "neither may an extension",
+    },
+    {
+        id: "dangerous",
+        constantName: "DANGEROUS_ENV_VOCABULARY",
+        includes: isDangerousEnvName,
+        clause: "is in the walked credential- or code-execution-capable vocabulary " +
+            "(src/gates/credentials.ts) and may never cross into a child environment",
+    },
+    {
+        id: "egress",
+        constantName: "EGRESS_ENV_VOCABULARY",
+        includes: isEgressEnvName,
+        clause: "is in the walked network-egress vocabulary (src/gates/credentials.ts) " +
+            "and may never cross into a child environment; DR-0048 decided that " +
+            "egress is granted through a declared route with a reader, never " +
+            "through an allowlist extension whose only audit is a prose reason",
+    },
+];
+/**
+ * The first vocabulary claiming `name`, or undefined. The ORDER of
+ * `REFUSED_CHILD_ENV_VOCABULARIES` is the order the refusal reports, and it
+ * is narrowest-first so that a name in two vocabularies is reported as the
+ * more specific one.
+ */
+export function refusedEnvVocabulary(name) {
+    return REFUSED_CHILD_ENV_VOCABULARIES.find((vocabulary) => vocabulary.includes(name));
+}
 /** The names credential-scrub probes, in probe order. */
 export const CREDENTIAL_SOURCES = [
     "environment",
@@ -222,6 +414,7 @@ export function probeCredentialSources(env, options = {}) {
     const names = Object.keys(env).filter((name) => env[name] !== undefined);
     const tokens = names.filter((name) => GH_TOKEN_VARIABLES.includes(name));
     const dangerous = names.filter((name) => isDangerousEnvName(name));
+    const egress = names.filter((name) => isEgressEnvName(name));
     const strays = names.filter((name) => !permitted.has(name));
     if (tokens.length > 0) {
         probes.push(probe("environment", "resolvable", `pull-request-capable token variable(s) present in the child environment: ${tokens.join(", ")}`));
@@ -229,11 +422,19 @@ export function probeCredentialSources(env, options = {}) {
     else if (dangerous.length > 0) {
         probes.push(probe("environment", "resolvable", `credential- or code-execution-capable variable(s) from the walked vocabulary present in the child environment: ${dangerous.join(", ")}`));
     }
+    else if (egress.length > 0) {
+        // ALLOWLIST-INDEPENDENT, and that placement is the whole point: it sits
+        // ABOVE the stray check so it still fires on a name the allowlist has
+        // been widened to permit. Below it, a widened allowlist would make the
+        // name non-stray and this probe would report clean, which is the green
+        // M4-P8's arm B measured while the child had HTTP 200 to the GitHub API.
+        probes.push(probe("environment", "resolvable", `network-egress variable(s) from the walked proxy vocabulary present in the child environment: ${egress.join(", ")}`));
+    }
     else if (strays.length > 0) {
         probes.push(probe("environment", "resolvable", `variable(s) outside the constructed contract present in the child environment: ${strays.join(", ")}`));
     }
     else {
-        probes.push(probe("environment", "clean", `${String(names.length)} variable(s), all inside the constructed contract, no gh token or walked-vocabulary variable`));
+        probes.push(probe("environment", "clean", `${String(names.length)} variable(s), all inside the constructed contract, no gh token, no walked-vocabulary variable and no walked proxy variable`));
     }
     // Source 2: gh configuration. The store is hosts.yml at gh's documented
     // resolution order (GH_CONFIG_DIR, else XDG_CONFIG_HOME/gh, else
@@ -528,6 +729,24 @@ const entry = process.argv[1];
 if (entry !== undefined) {
     const isMain = pathsIdentifySameObject(fileURLToPath(import.meta.url), entry);
     if (isMain) {
-        process.exit(gateMain(process.argv.slice(2)));
+        // `process.exitCode`, NEVER `process.exit(gateMain(...))` (M4-P29). This
+        // gate runs as a SUBPROCESS, so its output goes to a buffered stream the
+        // parent owns and a write to one is QUEUED rather than completed.
+        // `process.exit` ends the process without draining that queue, so
+        // everything past the buffer is DISCARDED, while the exit code survives
+        // and the loss is silent.
+        //
+        // THE MEASURED INSTANCE HERE IS STDERR, which the plan section states in
+        // as many words it did not examine: this module writes nothing to
+        // stdout. A 130,143-byte usage refusal from `gateMain` arrived as 65,536
+        // bytes through `| cat` at the pre-fix parent commit, one pipe buffer
+        // exactly, and arrives whole after this change. It arrives whole through
+        // a file redirection either way, which is why the defect survives casual
+        // testing. Assigning `process.exitCode` lets the process end normally,
+        // which drains the queue first. The same rule holds for stdout and is
+        // why src/gates/citations.ts, src/gates/scope.ts and
+        // src/gates/gate-classes.ts already read this way; the full capture is
+        // witness/captures/m4-p29-gate-cli-stdio.txt.
+        process.exitCode = gateMain(process.argv.slice(2));
     }
 }

package/dist/src/gates/gate-classes.d.ts

@@ -0,0 +1,56 @@
+/** DR-0029's three required classes, in the order the record reports them. */
+declare const REQUIRED_CLASSES: readonly ["correctness", "scope", "review"];
+type RequiredClass = (typeof REQUIRED_CLASSES)[number];
+interface ClassDeclaration {
+    gates?: string[];
+    status?: string;
+    reason?: string;
+    establishedBy?: string;
+}
+type RegistryIdsResult = {
+    ok: true;
+    ids: Set<string>;
+    conditional: Set<string>;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The legal gate ids: every entry of this repository's own registry.
+ *
+ * A failure here is `error` at the call site and never a skipped check. The
+ * registry is DECODED rather than JSON-parsed because it ships as YAML and
+ * `decodeDocument` is the delivered decoder for both (DR-0013 YAML clause 3).
+ */
+declare function registryGateIds(path: string): RegistryIdsResult;
+interface ClassVerdict {
+    name: RequiredClass;
+    ok: boolean;
+    /** One sentence, printed on either arm. */
+    sentence: string;
+    /** True when this class is satisfied by a declared escape rather than a gate. */
+    escape: boolean;
+    /**
+     * The gate ids this class names that are `applicability: conditional`.
+     *
+     * NOT A FAILURE AND NOT AN ESCAPE, which is why it is a third field rather
+     * than a reuse of either (CR-FS-GATES-01). A conditional gate is a legitimate
+     * satisfier; what a reader is owed is that it can report not-applicable at a
+     * head and that nothing here checked whether it did.
+     */
+    conditionalGates: string[];
+}
+/**
+ * Judge ONE class. Every red arm names the class, so the detail a reader sees
+ * says which of the three is wrong rather than only that something is.
+ */
+declare function judgeClass(name: RequiredClass, entry: ClassDeclaration | undefined, knownGateIds: Set<string>, conditionalGateIds?: Set<string>): ClassVerdict;
+interface CompilerReading {
+    files: string[];
+    errors: string[];
+}
+/** Split a real `tsc --listFiles` capture into its file list and its errors. */
+declare function readCompilerOutput(text: string): CompilerReading;
+export declare function main(argv: string[]): number;
+export { judgeClass, readCompilerOutput, registryGateIds, REQUIRED_CLASSES };
+export type { ClassDeclaration, ClassVerdict, RequiredClass };