@@ -1,7 +1,7 @@
 name: CI
 on:
   push:
-    branches: [main]
+    branches: [main, agent/environment-precedence-prototype]
   pull_request:
 permissions:
   contents: read
 
@@ -18,7 +18,9 @@
       "env": {
         "APC_VALUE": "fixture value with spaces",
         "APC_EXPANSION": "${PLUGIN_ROOT}|${PLUGIN_DATA}|${PLUGIN_ROOT}",
-        "APC_LITERAL": "${APC_UNKNOWN}|$APC_VALUE|${PLUGIN_ROOT_SUFFIX}"
+        "APC_LITERAL": "${APC_UNKNOWN}|$APC_VALUE|${PLUGIN_ROOT_SUFFIX}",
+        "USER": "apc-configured-environment-precedence",
+        "USERNAME": "apc-configured-environment-precedence"
       }
     },
     "relative": {
 
@@ -14,6 +14,7 @@ if (!['default', 'relative', 'root', 'data', 'command-token-posix', 'command-tok
 // This value is independent of the client-provided PLUGIN_ROOT environment.
 const root = realpathSync.native(fileURLToPath(new URL('..', import.meta.url)));
 const environmentNames = ['PLUGIN_ROOT', 'PLUGIN_DATA', 'APC_VALUE', 'APC_EXPANSION', 'APC_LITERAL'];
+const environmentPrecedenceNames = ['USER', 'USERNAME'];
 let resolvedData = null;
 if (process.env.PLUGIN_DATA && isAbsolute(process.env.PLUGIN_DATA)) {
   try { resolvedData = realpathSync.native(process.env.PLUGIN_DATA); } catch { /* Unobservable target remains null. */ }
@@ -38,7 +39,15 @@ const observeTool = {
   inputSchema: { type: 'object', properties: {}, additionalProperties: false },
   annotations: { readOnlyHint: serverName !== 'default', destructiveHint: false, idempotentHint: serverName !== 'default', openWorldHint: false },
 };
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [observeTool] }));
+const inspectEnvironmentPrecedenceTool = {
+  name: 'inspect_environment_precedence',
+  description: 'Research-only: return the exact candidate environment variables visible to this process. Do not record this result with the normal conformance reporter.',
+  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+const tools = [observeTool];
+if (serverName === 'default' || serverName === 'data') tools.push(inspectEnvironmentPrecedenceTool);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
 server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
   try {
     const args = params.arguments;
@@ -50,6 +59,23 @@ server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
       if (serverName === 'default') observation.evidence.dataWrite = observeDataWrite(process.env.PLUGIN_DATA);
       return { content: [{ type: 'text', text: JSON.stringify(observation) }], structuredContent: observation };
     }
+    if (params.name === 'inspect_environment_precedence' &&
+        (serverName === 'default' || serverName === 'data')) {
+      if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).length !== 0) {
+        throw new Error('inspect_environment_precedence requires an empty object');
+      }
+      const observation = {
+        kind: 'mcp-environment-precedence-research',
+        server: serverName,
+        evidence: {
+          version: 1,
+          env: Object.fromEntries(environmentPrecedenceNames
+            .filter((name) => process.env[name] !== undefined)
+            .map((name) => [name, process.env[name]])),
+        },
+      };
+      return { content: [{ type: 'text', text: JSON.stringify(observation) }], structuredContent: observation };
+    }
     throw new Error(`Unknown tool: ${params.name}`);
   } catch (error) {
     return { isError: true, content: [{ type: 'text', text: error.message }] };
 
@@ -0,0 +1,55 @@
+const STATUS = Object.freeze({ PASS: 'pass', FAIL: 'fail', NOT_VERIFIED: 'not_verified' });
+
+export function evaluateEnvironmentPrecedence({ control, configured, expected }) {
+  if (!control || !configured) {
+    const missing = [!control && 'control', !configured && 'configured'].filter(Boolean);
+    return {
+      status: STATUS.NOT_VERIFIED,
+      detail: `Missing ${missing.join(' and ')} observation.`,
+      candidates: Object.entries(expected).map(([name, expectedValue]) => ({
+        name,
+        ...(control && Object.hasOwn(control, name) ? { control: control[name] } : {}),
+        ...(configured && Object.hasOwn(configured, name) ? { configured: configured[name] } : {}),
+        expected: expectedValue,
+        status: STATUS.NOT_VERIFIED,
+        detail: `The ${missing.join(' and ')} observation was unavailable.`,
+      })),
+    };
+  }
+  const candidates = Object.entries(expected).map(([name, expectedValue]) => {
+    const controlPresent = Object.hasOwn(control, name);
+    const configuredPresent = Object.hasOwn(configured, name);
+    const values = {
+      name,
+      ...(controlPresent ? { control: control[name] } : {}),
+      ...(configuredPresent ? { configured: configured[name] } : {}),
+      expected: expectedValue,
+    };
+    if (!configuredPresent || configured[name] !== expectedValue) {
+      return { ...values, status: STATUS.FAIL,
+        detail: configuredPresent ? 'The configured value was not delivered.' : 'The configured variable was missing.' };
+    }
+    if (!controlPresent) {
+      return { ...values, status: STATUS.NOT_VERIFIED,
+        detail: 'The control process had no ambient value, so replacement was not observable.' };
+    }
+    if (control[name] === expectedValue) {
+      return { ...values, status: STATUS.NOT_VERIFIED,
+        detail: 'The control value already matched the configured value, so replacement was not observable.' };
+    }
+    return { ...values, status: STATUS.PASS,
+      detail: 'The configured value replaced a different ambient control value.' };
+  });
+  const failed = candidates.filter(({ status }) => status === STATUS.FAIL).map(({ name }) => name);
+  const passed = candidates.filter(({ status }) => status === STATUS.PASS).map(({ name }) => name);
+  if (failed.length > 0) {
+    return { status: STATUS.FAIL,
+      detail: `Configured overrides were not delivered for: ${failed.join(', ')}.`, candidates };
+  }
+  if (passed.length > 0) {
+    return { status: STATUS.PASS,
+      detail: `Configured overrides replaced ambient values for: ${passed.join(', ')}.`, candidates };
+  }
+  return { status: STATUS.NOT_VERIFIED,
+    detail: 'No candidate had a different ambient control value to replace.', candidates };
+}
@@ -8,17 +8,20 @@ import { delimiter, dirname, isAbsolute, join, relative } from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { CASE_IDS } from '../plugins/agent-plugins-conformance/src/cases.mjs';
+import { evaluateEnvironmentPrecedence } from './environment-precedence.mjs';
 
 const root = fileURLToPath(new URL('..', import.meta.url));
 const output = join(root, 'reports/codex');
 const reportPath = join(output, 'report.json');
+const environmentPrecedencePath = join(output, 'environment-precedence-research.json');
 const [codex, ...extra] = process.argv.slice(2);
 assert.ok(codex && isAbsolute(codex) && extra.length === 0,
   'Usage: node scripts/smoke-codex.mjs <absolute-codex-binary>');
 const names = ['agent-plugins-conformance-core', 'agent-plugins-conformance', 'agent-plugins-conformance-recovery'];
 const commandPlatform = process.platform === 'win32' ? 'windows' : 'posix';
 const commandServer = `command-token-${commandPlatform}`;
 const commandSymlinkServers = ['recovery-command-symlink-posix', 'recovery-command-symlink-windows'];
+const environmentPrecedenceNames = ['USER', 'USERNAME'];
 const servers = ['default', 'relative', 'root', 'data', commandServer, 'http', 'recovery-valid'];
 const invalidSseServers = [
   'recovery-sse-non-loopback', 'recovery-sse-relative-url', 'recovery-sse-fragment', 'recovery-sse-userinfo',
@@ -278,6 +281,52 @@ try {
     }
     record({ action: 'record', observation });
   }
+  const environmentPrecedenceObservations = {};
+  for (const server of ['data', 'default']) {
+    const entry = status.data.find(({ name }) => name === server);
+    assert.ok(entry && Object.hasOwn(entry.tools, 'inspect_environment_precedence'),
+      `${server}: research environment precedence tool was not advertised`);
+    const result = await rpc('mcpServer/tool/call', {
+      threadId: thread.id, server, tool: 'inspect_environment_precedence', arguments: {},
+    });
+    assert.ok(!result.isError && !result.error,
+      `${server}: inspect_environment_precedence failed: ${JSON.stringify(result)}`);
+    const observation = result.structuredContent;
+    assert.deepEqual(Object.keys(observation).sort(), ['evidence', 'kind', 'server']);
+    assert.equal(observation.kind, 'mcp-environment-precedence-research');
+    assert.equal(observation.server, server);
+    assert.deepEqual(Object.keys(observation.evidence).sort(), ['env', 'version']);
+    assert.equal(observation.evidence.version, 1);
+    assert.ok(observation.evidence.env && typeof observation.evidence.env === 'object' &&
+      !Array.isArray(observation.evidence.env), `${server}: expected an environment object`);
+    assert.ok(Object.keys(observation.evidence.env).every((name) => environmentPrecedenceNames.includes(name)),
+      `${server}: research tool returned a non-candidate environment key`);
+    assert.ok(Object.values(observation.evidence.env).every((value) => typeof value === 'string'),
+      `${server}: research tool returned a non-string environment value`);
+    environmentPrecedenceObservations[server] = observation;
+  }
+  const expectedEnvironment = {
+    USER: 'apc-configured-environment-precedence',
+    USERNAME: 'apc-configured-environment-precedence',
+  };
+  const environmentPrecedenceEvaluation = evaluateEnvironmentPrecedence({
+    control: environmentPrecedenceObservations.data.evidence.env,
+    configured: environmentPrecedenceObservations.default.evidence.env,
+    expected: expectedEnvironment,
+  });
+  await writeFile(environmentPrecedencePath, `${JSON.stringify({
+    research: true,
+    productionConformanceReport: false,
+    note: 'Prototype evidence only; this result is intentionally excluded from the normal conformance reporter.',
+    client: { name: 'Codex', version },
+    platform: process.platform,
+    candidates: environmentPrecedenceNames,
+    control: environmentPrecedenceObservations.data,
+    configured: environmentPrecedenceObservations.default,
+    evaluation: environmentPrecedenceEvaluation,
+  }, null, 2)}\n`);
+  assert.equal(environmentPrecedenceEvaluation.status, 'pass',
+    `Environment precedence research did not pass: ${environmentPrecedenceEvaluation.detail}`);
   // SSE is optional. Preserve native diagnostics even when the loader omits entries.
   const sseObservations = [];
   for (const server of ['sse', 'sse-header-precedence', 'sse-redirect', 'sse-endpoint-origin']) {
@@ -303,6 +352,8 @@ try {
     sseObservations.push(observation);
   }
   const report = JSON.parse(await readFile(reportPath, 'utf8'));
+  assert.equal(report.observations.some(({ kind }) => kind === 'mcp-environment-precedence-research'), false,
+    'Research-only environment evidence leaked into the normal conformance report');
   assert.deepEqual(report.observations.filter(({ kind, server }) => kind === 'mcp-sse' && !invalidSseServers.includes(server)), sseObservations,
     'SSE observations or native diagnostics were not preserved');
   const baselineSse = sseObservations[0].evidence;
@@ -343,6 +394,7 @@ try {
     `Native runtime connected through escaping executable symlinks: ${connectedCommandSymlinkServers.join(', ')}`);
   console.log(`Native Codex smoke passed: ${coveredCases.length} Core and Recovery cases; ${report.summary.not_verified} not verified.`);
   console.log(`Report: ${reportPath}`);
+  console.log(`Environment precedence research (${environmentPrecedenceEvaluation.status}): ${environmentPrecedencePath}`);
 } catch (error) {
   console.error(`Native Codex smoke failed: ${error.message}`);
   process.exitCode = 1;
 
@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { evaluateEnvironmentPrecedence } from '../scripts/environment-precedence.mjs';
+
+test('environment precedence passes only for a delivered override with a conflicting baseline', () => {
+  const result = evaluateEnvironmentPrecedence({
+    control: { USER: 'ambient-user', USERNAME: 'ambient-username' },
+    configured: { USER: 'fixture-user', USERNAME: 'fixture-username' },
+    expected: { USER: 'fixture-user', USERNAME: 'fixture-username' },
+  });
+  assert.equal(result.status, 'pass');
+  assert.deepEqual(result.candidates.map(({ name, status }) => [name, status]), [
+    ['USER', 'pass'], ['USERNAME', 'pass'],
+  ]);
+});
+
+test('environment precedence fails a missing or mismatched configured value', () => {
+  const result = evaluateEnvironmentPrecedence({
+    control: { USER: 'ambient-user', USERNAME: 'ambient-username' },
+    configured: { USER: 'ambient-user' },
+    expected: { USER: 'fixture-user', USERNAME: 'fixture-username' },
+  });
+  assert.equal(result.status, 'fail');
+  assert.deepEqual(result.candidates.map(({ name, status }) => [name, status]), [
+    ['USER', 'fail'], ['USERNAME', 'fail'],
+  ]);
+});
+
+test('environment precedence is not verified when either process observation is missing', () => {
+  for (const input of [
+    { control: null, configured: { USER: 'fixture-user' } },
+    { control: { USER: 'ambient-user' }, configured: null },
+  ]) {
+    const result = evaluateEnvironmentPrecedence({ ...input, expected: { USER: 'fixture-user' } });
+    assert.equal(result.status, 'not_verified');
+    assert.equal(result.candidates[0].status, 'not_verified');
+  }
+});
+
+test('environment precedence is not verified without a conflicting ambient baseline', () => {
+  const result = evaluateEnvironmentPrecedence({
+    control: { USERNAME: 'fixture-username' },
+    configured: { USER: 'fixture-user', USERNAME: 'fixture-username' },
+    expected: { USER: 'fixture-user', USERNAME: 'fixture-username' },
+  });
+  assert.equal(result.status, 'not_verified');
+  assert.deepEqual(result.candidates.map(({ name, status }) => [name, status]), [
+    ['USER', 'not_verified'], ['USERNAME', 'not_verified'],
+  ]);
+});
+
+test('one wrong configured value fails the aggregate despite another genuine replacement', () => {
+  const result = evaluateEnvironmentPrecedence({
+    control: { USER: 'ambient-user', USERNAME: 'ambient-username' },
+    configured: { USER: 'fixture-user', USERNAME: 'ambient-username' },
+    expected: { USER: 'fixture-user', USERNAME: 'fixture-username' },
+  });
+  assert.equal(result.status, 'fail');
+  assert.deepEqual(result.candidates.map(({ name, status }) => [name, status]), [
+    ['USER', 'pass'], ['USERNAME', 'fail'],
+  ]);
+});