From dacfaa8e495156040dcfcc5f42a6d512fcd28de6 Mon Sep 17 00:00:00 2001
From: Renn F <rennf93@users.noreply.github.com>
Date: Tue, 29 Sep 2026 06:03:56 +0200
Subject: [PATCH 1/7] test: extend the suite to full reachable-line coverage

---
 bin/test_agent.php          | 1509 ++++++++++++++++++++++++++++++++++-
 tests/fake_redis_server.php |  102 +++
 tests/mock_server.php       |    8 +
 3 files changed, 1591 insertions(+), 28 deletions(-)
 create mode 100644 tests/fake_redis_server.php

diff --git a/bin/test_agent.php b/bin/test_agent.php
index f6e6a74..c0c5bf3 100644
--- a/bin/test_agent.php
+++ b/bin/test_agent.php
@@ -24,8 +24,12 @@
 use RenzoFranceschini\GuardAgent\Encryption\PayloadEncryptor;
 use RenzoFranceschini\GuardAgent\Exception\EncryptionConfigException;
 use RenzoFranceschini\GuardAgent\Exception\EncryptionException;
+use RenzoFranceschini\GuardAgent\Exception\RedisException;
 use RenzoFranceschini\GuardAgent\Exception\SerializationException;
+use RenzoFranceschini\GuardAgent\Persistence\ExtRedisClient;
+use RenzoFranceschini\GuardAgent\Persistence\PredisRedisClient;
 use RenzoFranceschini\GuardAgent\Utils\CanonicalJson;
+use RenzoFranceschini\GuardAgent\Utils\ErrorHook;
 use RenzoFranceschini\GuardAgent\GuardAgent;
 use RenzoFranceschini\GuardAgent\Install\InstallId;
 use RenzoFranceschini\GuardAgent\Log\AgentLogger;
@@ -143,6 +147,9 @@ final class CaptureLogger implements AgentLogger
     /** @var list<string> */
     public array $warnings = [];
 
+    /** @var list<string> */
+    public array $errors = [];
+
     public function debug(string $message): void
     {
     }
@@ -158,6 +165,7 @@ public function warning(string $message): void
 
     public function error(string $message): void
     {
+        $this->errors[] = $message;
     }
 }
 
@@ -504,43 +512,490 @@ function readMockState(string $stateFile): array
         }
     }
 
-    return $records;
-}
-
-function flushState(string $stateFile): void
-{
-    file_put_contents($stateFile, '');
+    return $records;
+}
+
+function flushState(string $stateFile): void
+{
+    file_put_contents($stateFile, '');
+}
+
+/**
+ * @return list<array<string, mixed>>
+ */
+function stateFor(string $stateFile, string $path): array
+{
+    return array_values(array_filter(
+        readMockState($stateFile),
+        static fn (array $record): bool => ($record['path'] ?? '') === $path
+    ));
+}
+
+/**
+ * @param list<array<string, mixed>> $records
+ *
+ * @return list<int|string>
+ */
+function statuses(array $records): array
+{
+    return array_map(static fn (array $record): int|string => $record['status'], $records);
+}
+
+function redisUrl(): string
+{
+    $host = getenv('REDIS_HOST');
+    if ($host === false || $host === '' || $host === '0') {
+        return '';
+    }
+
+    return 'redis://' . $host . ':6379/0';
+}
+
+/**
+ * Redis client double whose every method throws: exercises the failure paths
+ * of RedisHandler and the EventBuffer persistence hooks.
+ */
+final class ThrowingRedisClient implements RedisClientInterface
+{
+    public function ping(): void
+    {
+        throw new RuntimeException('throwing redis client');
+    }
+
+    public function get(string $key): ?string
+    {
+        throw new RuntimeException('throwing redis client');
+    }
+
+    public function set(string $key, string $value, ?int $ttlSeconds = null): bool
+    {
+        throw new RuntimeException('throwing redis client');
+    }
+
+    public function delete(string ...$keys): int
+    {
+        throw new RuntimeException('throwing redis client');
+    }
+
+    public function keys(string $pattern): array
+    {
+        throw new RuntimeException('throwing redis client');
+    }
+
+    public function close(): void
+    {
+    }
+}
+
+/**
+ * Redis client double that fails only on close.
+ */
+/**
+ * Redis double that lists keys but never has data: exercises the startup
+ * load path for records whose value disappeared before the reload.
+ */
+final class KeysOnlyRedisClient implements RedisClientInterface
+{
+    /** @var list<string> */
+    public array $listed = [];
+
+    public function ping(): void
+    {
+    }
+
+    public function get(string $key): ?string
+    {
+        return null;
+    }
+
+    public function set(string $key, string $value, ?int $ttlSeconds = null): bool
+    {
+        return true;
+    }
+
+    public function delete(string ...$keys): int
+    {
+        return 0;
+    }
+
+    public function keys(string $pattern): array
+    {
+        return $this->listed;
+    }
+
+    public function close(): void
+    {
+    }
+}
+
+final class ThrowingCloseClient implements RedisClientInterface
+{
+    public function ping(): void
+    {
+    }
+
+    public function get(string $key): ?string
+    {
+        return null;
+    }
+
+    public function set(string $key, string $value, ?int $ttlSeconds = null): bool
+    {
+        return true;
+    }
+
+    public function delete(string ...$keys): int
+    {
+        return 0;
+    }
+
+    public function keys(string $pattern): array
+    {
+        return [];
+    }
+
+    public function close(): void
+    {
+        throw new RuntimeException('close exploded');
+    }
+}
+
+/**
+ * Scriptable Redis double with per-method scripted replies, for the
+ * ExtRedisClient adapter surface.
+ */
+final class ScriptedExtRedis
+{
+    /** @var list<mixed> */
+    public array $getReplies = [];
+
+    public bool $setReply = true;
+
+    public bool $setexReply = true;
+
+    /** @var list<mixed> */
+    public array $keysReplies = [];
+
+    public bool $closeThrows = false;
+
+    public int $delCount = 0;
+
+    public function ping(): bool
+    {
+        return true;
+    }
+
+    public function get(string $key): mixed
+    {
+        $reply = array_shift($this->getReplies);
+
+        return $reply === null ? false : $reply;
+    }
+
+    public function set(string $key, string $value, $timeout = 0): bool
+    {
+        return $this->setReply;
+    }
+
+    public function setex(string $key, $ttl, string $value): bool
+    {
+        return $this->setexReply;
+    }
+
+    public function del(string ...$keys): int
+    {
+        $this->delCount += count($keys);
+
+        return count($keys);
+    }
+
+    public function keys(string $pattern): mixed
+    {
+        $reply = array_shift($this->keysReplies);
+
+        return $reply ?? false;
+    }
+
+    public function close(): void
+    {
+        if ($this->closeThrows) {
+            throw new RuntimeException('close exploded');
+        }
+    }
+}
+
+/**
+ * Minimal scripted predis-style client for the PredisRedisClient adapter.
+ */
+final class ScriptedPredis
+{
+    public string $pingReply = 'PONG';
+
+    public mixed $getReply = null;
+
+    public bool $setReply = true;
+
+    public bool $setexReply = true;
+
+    public mixed $keysReply = [];
+
+    public function get(string $key): mixed
+    {
+        return $this->getReply;
+    }
+
+    public function set(string $key, string $value): bool
+    {
+        return $this->setReply;
+    }
+
+    public function setex(string $key, $ttl, string $value): bool
+    {
+        return $this->setexReply;
+    }
+
+    public function del(string ...$keys): int
+    {
+        return count($keys);
+    }
+
+    public function keys(string $pattern): mixed
+    {
+        return $this->keysReply;
+    }
+
+    public function ping(): string
+    {
+        return $this->pingReply;
+    }
+
+    public function disconnect(): void
+    {
+    }
+}
+
+/**
+ * Transport double with injection points for every lifecycle failure mode.
+ */
+final class StubTransport implements TransportInterface
+{
+    public bool $initializeThrows = false;
+
+    public bool $closeThrows = false;
+
+    public bool $getStatsThrows = false;
+
+    /** @var list<bool|Throwable> */
+    public array $eventOutcomes = [];
+
+    /** @var list<bool|Throwable> */
+    public array $metricOutcomes = [];
+
+    public bool|Throwable|null $statusOutcome = true;
+
+    public ?DynamicRules $rulesOutcome = null;
+
+    public string $breakerState = 'CLOSED';
+
+    public int $initialized = 0;
+
+    public int $closed = 0;
+
+    /** @var list<list<SecurityEvent>> */
+    public array $eventBatches = [];
+
+    /** @var list<list<SecurityMetric>> */
+    public array $metricBatches = [];
+
+    public function initialize(): void
+    {
+        $this->initialized++;
+        if ($this->initializeThrows) {
+            throw new RuntimeException('initialize exploded');
+        }
+    }
+
+    public function sendEvents(array $events): bool
+    {
+        $this->eventBatches[] = array_values($events);
+        if ($this->eventOutcomes === []) {
+            return true;
+        }
+        $outcome = array_shift($this->eventOutcomes);
+        if ($outcome instanceof Throwable) {
+            throw $outcome;
+        }
+
+        return $outcome;
+    }
+
+    public function sendMetrics(array $metrics): bool
+    {
+        $this->metricBatches[] = array_values($metrics);
+        if ($this->metricOutcomes === []) {
+            return true;
+        }
+        $outcome = array_shift($this->metricOutcomes);
+        if ($outcome instanceof Throwable) {
+            throw $outcome;
+        }
+
+        return $outcome;
+    }
+
+    public function sendStatus(AgentStatus $status): bool
+    {
+        if ($this->statusOutcome instanceof Throwable) {
+            throw $this->statusOutcome;
+        }
+
+        return $this->statusOutcome ?? false;
+    }
+
+    public function fetchDynamicRules(): ?DynamicRules
+    {
+        if ($this->rulesOutcome instanceof Throwable) {
+            throw $this->rulesOutcome;
+        }
+
+        return $this->rulesOutcome;
+    }
+
+    public function getStats(): array
+    {
+        if ($this->getStatsThrows) {
+            throw new RuntimeException('getStats exploded');
+        }
+
+        return [
+            'requestsSent' => 0,
+            'requestsFailed' => 0,
+            'bytesSent' => 0,
+            'circuitBreakerState' => $this->breakerState,
+            'failureCount' => 0,
+            'sessionClosed' => false,
+        ];
+    }
+
+    public function close(): void
+    {
+        $this->closed++;
+        if ($this->closeThrows) {
+            throw new RuntimeException('close exploded');
+        }
+    }
+}
+
+/**
+ * Logger that throws exactly once, on the first warning: used to prove the
+ * agent's tick() surface never propagates even a hostile logger.
+ */
+final class FickleLogger implements AgentLogger
+{
+    public bool $spent = false;
+
+    public function debug(string $message): void
+    {
+    }
+
+    public function info(string $message): void
+    {
+    }
+
+    public function warning(string $message): void
+    {
+        if (!$this->spent) {
+            $this->spent = true;
+            throw new RuntimeException('hostile logger');
+        }
+    }
+
+    public function error(string $message): void
+    {
+    }
+}
+
+/**
+ * Starts tests/fake_redis_server.php on an ephemeral port.
+ *
+ * @param list<string|list<string>> $script
+ *
+ * @return array{0: resource, 1: int, 2: string} proc, port, control file
+ */
+function startFakeRedis(array $script, string $mode = 'script'): array
+{
+    $sock = stream_socket_server('tcp://127.0.0.1:0', $errno, $errstr);
+    if ($sock === false) {
+        fwrite(STDERR, "cannot pick a fake redis port: {$errstr}\n");
+        exit(1);
+    }
+    $name = (string) stream_socket_get_name($sock, false);
+    $port = (int) substr($name, (int) strrpos($name, ':') + 1);
+    fclose($sock);
+
+    $controlFile = (string) tempnam(sys_get_temp_dir(), 'gaph-redis');
+    file_put_contents($controlFile, json_encode(['mode' => $mode, 'script' => $script]));
+
+    $env = getenv();
+    $env['FAKE_REDIS_CONTROL_FILE'] = $controlFile;
+    $env['FAKE_REDIS_PORT'] = (string) $port;
+    $proc = proc_open(
+        [PHP_BINARY, __DIR__ . '/../tests/fake_redis_server.php'],
+        [1 => ['file', '/dev/null', 'w'], 2 => ['file', '/dev/null', 'w']],
+        $pipes,
+        dirname(__DIR__),
+        $env
+    );
+    if ($proc === false) {
+        fwrite(STDERR, "cannot start fake redis server\n");
+        exit(1);
+    }
+    $ready = false;
+    for ($i = 0; $i < 100; $i++) {
+        $conn = @fsockopen('127.0.0.1', $port, $e, $es, 0.2);
+        if ($conn !== false) {
+            fclose($conn);
+            $ready = true;
+            break;
+        }
+        usleep(50_000);
+    }
+    if (!$ready) {
+        fwrite(STDERR, "fake redis server did not become ready\n");
+        exit(1);
+    }
+
+    return [$proc, $port, $controlFile];
 }
 
 /**
- * @return list<array<string, mixed>>
+ * Invoke the private constructor of a static-only class: asserts the class is
+ * final-by-construction (a private constructor forbids instantiation) and
+ * executes the constructor body.
  */
-function stateFor(string $stateFile, string $path): array
-{
-    return array_values(array_filter(
-        readMockState($stateFile),
-        static fn (array $record): bool => ($record['path'] ?? '') === $path
-    ));
-}
-
 /**
- * @param list<array<string, mixed>> $records
- *
- * @return list<int|string>
+ * Fill a rate limiter's call log with stamps at the edge of its window so the
+ * next acquire is denied with a tiny retry-after (HttpTransport wires its own
+ * limiter, and the property is readonly).
  */
-function statuses(array $records): array
+function saturateRateLimiter(RateLimiter $limiter): void
 {
-    return array_map(static fn (array $record): int|string => $record['status'], $records);
+    $now = microtime(true);
+    $calls = array_fill(0, 100, $now - 59.9);
+    $calls[0] = $now - 59.95;
+    refl($limiter, 'calls')->setValue($limiter, $calls);
 }
 
-function redisUrl(): string
+function assertStaticOnlyClass(T $t, string $class): void
 {
-    $host = getenv('REDIS_HOST');
-    if ($host === false || $host === '' || $host === '0') {
-        return '';
+    $reflection = new ReflectionClass($class);
+    $constructor = $reflection->getConstructor();
+    $t->ok($constructor !== null && $constructor->isPrivate(), "{$class} has a private constructor (static-only)");
+    if ($constructor !== null) {
+        $constructor->setAccessible(true);
+        $constructor->invoke($reflection->newInstanceWithoutConstructor());
+        $t->ok(true, "{$class} constructor body executes");
     }
-
-    return 'redis://' . $host . ':6379/0';
 }
 
 $t = new T();
@@ -1759,10 +2214,1008 @@ static function (): void {
 @unlink($rulesControlFile);
 @unlink($rulesStateFile);
 
-proc_terminate($proc);
-proc_close($proc);
+// =====================================================================
+// 12. Static-only utility classes and their defensive edges
+// =====================================================================
+$t->section('static-only classes');
+
+foreach ([
+    CanonicalJson::class,
+    ErrorHook::class,
+    HeadersRedactor::class,
+    Json::class,
+    Backoff::class,
+    BatchId::class,
+    IpHasher::class,
+    PayloadTruncator::class,
+    ResponseSummary::class,
+    RetryAfter::class,
+    Uuid::class,
+    Signer::class,
+    WireFormat::class,
+    \RenzoFranceschini\GuardAgent\Model\KnownTypes::class,
+    AgentConfigResolver::class,
+    InstallId::class,
+] as $staticOnlyClass) {
+    assertStaticOnlyClass($t, $staticOnlyClass);
+}
+
+$t->section('canonical json edges');
+
+$t->same('false', CanonicalJson::encode(false), 'canonical json: false literal encodes');
+$t->throws(SerializationException::class, static function (): void {
+    $deep = ['x' => 1];
+    for ($i = 0; $i < 600; $i++) {
+        $deep = ['n' => $deep];
+    }
+    CanonicalJson::encode($deep);
+}, 'canonical json: nesting beyond 512 rejected');
+$t->throws(SerializationException::class, static fn () => CanonicalJson::encode(NAN), 'canonical json: NaN rejected');
+$t->throws(SerializationException::class, static fn () => CanonicalJson::encode(INF), 'canonical json: Inf rejected');
+$t->throws(SerializationException::class, static fn () => CanonicalJson::encode(fopen('php://memory', 'rb')), 'canonical json: resource rejected');
+$t->same(
+    '"2026-01-02T03:04:05.000Z"',
+    CanonicalJson::encode(new DateTimeImmutable('2026-01-02 03:04:05', new DateTimeZone('UTC'))),
+    'canonical json: DateTimeInterface renders as ISO UTC with milliseconds'
+);
+$t->same('"\\ud83d\\ude00"', CanonicalJson::encode("\u{1F600}"), 'canonical json: astral plane escapes as a surrogate pair');
+
+$t->section('error hook edges');
+
+$hookErrors = [];
+$hookLogger = new CaptureLogger();
+$hookCalls = [];
+ErrorHook::fire(
+    static function (string $stage, Throwable $error, array $context) use (&$hookCalls): void {
+        $hookCalls[] = [$stage, $error->getMessage(), $context];
+    },
+    $hookLogger,
+    'transport_send',
+    new RuntimeException('upstream down'),
+    ['endpoint' => 'https://x']
+);
+$t->same(1, count($hookCalls), 'error hook invoked with stage, error, and context');
+$t->same('transport_send', $hookCalls[0][0], 'error hook receives the stage');
+$t->same([], $hookLogger->errors, 'a healthy hook logs nothing');
+ErrorHook::fire(
+    static fn (): never => throw new LogicException('hook exploded'),
+    $hookLogger,
+    'flush_events',
+    new RuntimeException('upstream down'),
+    []
+);
+$t->same(1, count($hookLogger->errors), 'a throwing hook is caught and logged');
+$t->ok(str_contains($hookLogger->errors[0] ?? '', "onError hook raised while handling 'flush_events'"), 'throwing hook log names the stage');
+$t->same('RuntimeException: upstream down', ErrorHook::message(new RuntimeException('upstream down')), 'message formats Throwables');
+$t->same('plain string', ErrorHook::message('plain string'), 'message passes unknown values through');
+
+$t->section('headers redactor edges');
+
+$t->same(
+    ['n' => null, 'i' => 3, 'f' => 1.5, 'b' => true],
+    HeadersRedactor::sanitize(['n' => null, 'i' => 3, 'f' => 1.5, 'b' => true], ['authorization']),
+    'scalars pass through sanitization untouched'
+);
+$when = new DateTimeImmutable('2026-01-02T03:04:05Z');
+$t->same($when, HeadersRedactor::sanitize($when, ['authorization']), 'DateTimeInterface values pass through untouched');
+$t->same(HeadersRedactor::REDACTED, HeadersRedactor::sanitize(new stdClass(), ['authorization']), 'plain objects are redacted wholesale');
+$t->same(HeadersRedactor::REDACTED, HeadersRedactor::sanitize(STDIN, ['authorization']), 'resources are redacted wholesale');
+$deep = ['authorization' => 'deep-secret'];
+for ($i = 0; $i < 12; $i++) {
+    $deep = ['w' => $deep];
+}
+$sanitizedDeep = HeadersRedactor::sanitize($deep, ['authorization']);
+for ($i = 0; $i < 11; $i++) {
+    $sanitizedDeep = $sanitizedDeep['w'];
+}
+$t->same(HeadersRedactor::REDACTED, $sanitizedDeep, 'nesting beyond the sanitize depth is redacted');
+$t->same('   ', HeadersRedactor::sanitize('   ', ['authorization']), 'whitespace-only strings are returned as-is');
+$t->same(HeadersRedactor::REDACTED, HeadersRedactor::sanitize('{"a":' . str_repeat('1', 9000) . '}', ['authorization']), 'json-looking strings above the scan cap are redacted');
+$t->same('{"bad json', HeadersRedactor::sanitize('{"bad json', ['authorization']), 'malformed json strings are returned as-is');
+
+$t->section('json helpers edges');
+
+$t->same(null, Json::decodeAnyOrNull('not json'), 'decodeAnyOrNull returns null on invalid JSON');
+$t->same(null, Json::decodeAnyOrNull('null'), 'decodeAnyOrNull disambiguates a literal null body');$t->section('rate limiter and circuit breaker edges');
+
+$freshLimiter = new RateLimiter(2, 60.0);
+$t->same(0.0, $freshLimiter->getRetryAfter(), 'retry-after is 0 with no recorded calls');
+$breaker = new CircuitBreaker(2, 60.0);
+$t->ok(!$breaker->isOpen(), 'a fresh breaker is not open');
+$t->ok((new CircuitBreaker(2, 0.0))->isOpen() === false, 'isOpen reflects the state field');
+
+$t->section('payload encryptor edges');
+
+$t->throws(EncryptionException::class, static fn () => new PayloadEncryptor('!!!not-base64!!!'), 'encryption: undecodable key format rejected');
+$t->throws(EncryptionException::class, static fn () => (new PayloadEncryptor($vectors[0]['key_b64']))->decrypt('AAA'), 'encryption: truncated payload rejected');
+$t->throws(EncryptionException::class, static fn () => (new PayloadEncryptor($vectors[0]['key_b64']))->encrypt(['r' => fopen('php://memory', 'rb')]), 'encryption: an unserializable payload raises the typed error');
+$t->throws(
+    EncryptionException::class,
+    static fn () => (new PayloadEncryptor($vectors[0]['key_b64']))->decrypt((new PayloadEncryptor($vectors[0]['key_b64']))->encrypt(['a', 'b'])),
+    'encryption: a list-shaped plaintext is rejected as tampered'
+);
+
+$t->section('buffer overflow policy parsing');
+
+$t->same(BufferOverflowPolicy::Block, BufferOverflowPolicy::tryFromValue(BufferOverflowPolicy::Block), 'policy instances pass through');
+$t->same(null, BufferOverflowPolicy::tryFromValue(5), 'non-string non-instance policies parse to null');
+
+$t->section('wire model edges');
+
+$t->throws(InvalidEventException::class, static fn () => SecurityEvent::normalize(['event_type' => 42, 'timestamp' => WireFormat::now()]), 'event: non-string event_type rejected');
+$t->throws(InvalidEventException::class, static fn () => SecurityEvent::normalize(['event_type' => 'x', 'timestamp' => WireFormat::now(), 'country' => 5]), 'event: non-string country rejected');
+$countryEvent = SecurityEvent::normalize(['event_type' => 'x', 'timestamp' => WireFormat::now(), 'country' => 'CN']);
+$t->same('CN', $countryEvent->country, 'event: string country kept');
+$t->throws(InvalidEventException::class, static fn () => SecurityEvent::normalize(['event_type' => 'x', 'timestamp' => WireFormat::now(), 'status_code' => 2.5]), 'event: fractional status_code rejected');
+$statusCodeEvent = SecurityEvent::normalize(['event_type' => 'x', 'timestamp' => WireFormat::now(), 'status_code' => 200]);
+$t->same(200, $statusCodeEvent->statusCode, 'event: integer status_code kept');
+$t->throws(InvalidEventException::class, static fn () => SecurityEvent::normalize(['event_type' => 'x', 'timestamp' => WireFormat::now(), 'response_time' => NAN]), 'event: NaN response_time rejected');
+$responseTimeEvent = SecurityEvent::normalize(['event_type' => 'x', 'timestamp' => WireFormat::now(), 'response_time' => 1.5]);
+$t->same(1.5, $responseTimeEvent->responseTime, 'event: float response_time kept');
+$stringNumberEvent = SecurityEvent::normalize(['event_type' => 'x', 'timestamp' => WireFormat::now(), 'response_time' => '0.5']);
+$t->same(0.5, $stringNumberEvent->responseTime, 'event: numeric-string response_time coerced');
+$t->throws(InvalidEventException::class, static fn () => SecurityEvent::normalize(['event_type' => 'x', 'timestamp' => WireFormat::now(), 'response_time' => 'abc']), 'event: non-numeric response_time rejected');
+$t->throws(InvalidEventException::class, static fn () => SecurityEvent::normalize(['event_type' => 'x', 'timestamp' => WireFormat::now(), 'metadata' => 'junk']), 'event: non-array metadata rejected');
+
+$t->throws(InvalidEventException::class, static fn () => SecurityMetric::normalize('a string'), 'metric: non-array payload rejected');
+$t->throws(InvalidEventException::class, static fn () => SecurityMetric::normalize(['metric_type' => 'request_count', 'value' => 'abc']), 'metric: non-numeric value rejected');
+$t->throws(InvalidEventException::class, static fn () => SecurityMetric::normalize(['metric_type' => 'request_count', 'value' => NAN]), 'metric: NaN value rejected');
+$t->throws(InvalidEventException::class, static fn () => SecurityMetric::normalize(['metric_type' => 'request_count', 'value' => 1, 'endpoint' => 5, 'timestamp' => WireFormat::now()]), 'metric: non-string endpoint rejected');
+$t->throws(InvalidEventException::class, static fn () => SecurityMetric::normalize(['metric_type' => 'request_count', 'value' => 1, 'tags' => 'junk', 'timestamp' => WireFormat::now()]), 'metric: non-array tags rejected');
+$metricWithStringEndpoint = SecurityMetric::normalize(['metric_type' => 'request_count', 'value' => 1, 'endpoint' => '/api/x', 'timestamp' => WireFormat::now()]);
+$t->same('/api/x', $metricWithStringEndpoint->endpoint, 'metric: string endpoint kept');
+
+$directMetric = new SecurityMetric(WireFormat::now(), 'request_count', 2, null, ['n' => 3]);
+$agentForCoercion = makeAgent([], new RecordingTransport());
+$agentForCoercion->sendMetric($directMetric);
+[$flushedMetrics] = $agentForCoercion->buffer->flushMetricsWithKeys();
+$t->same(['n' => '3'], $flushedMetrics[0]->tags, 'sendMetric coerces non-string tag values at the redaction boundary');
+
+$t->throws(InvalidRulesException::class, static fn () => DynamicRules::normalize(['rule_id' => 5]), 'rules: non-string rule_id rejected');
+$t->throws(InvalidRulesException::class, static fn () => DynamicRules::normalize(['version' => 'abc']), 'rules: non-integer version rejected');
+$t->throws(InvalidRulesException::class, static fn () => DynamicRules::normalize(['auto_ban_threshold' => 'abc']), 'rules: non-numeric auto_ban_threshold rejected');
+$t->same(5, DynamicRules::normalize(['auto_ban_threshold' => 5])->autoBanThreshold, 'rules: a valid auto_ban_threshold parses');
+$rulesInstance = DynamicRules::normalize(['rule_id' => 'instance']);
+$t->same($rulesInstance, DynamicRules::normalize($rulesInstance), 'rules: instance passthrough');
+
+$wireNow = WireFormat::parseTimestamp(new DateTime('2026-01-02 03:04:05', new DateTimeZone('UTC')), 'ts');
+$t->same('2026-01-02T03:04:05+00:00', $wireNow->format(DATE_ATOM), 'wire: mutable DateTime inputs are converted to immutable');
+$t->ok(WireFormat::timestampOrDefault(null)->getTimestamp() > 1_500_000_000, 'wire: null timestamp defaults to now');
+$t->same(1_700_000_000, WireFormat::timestampOrDefault(1_700_000_000)->getTimestamp(), 'wire: epoch input parsed');
+
+$t->section('config resolver edges');
+
+$t->throws(ConfigException::class, static fn () => AgentConfigResolver::normalizeEndpoint('not a url', new SilentLogger()), 'endpoint without scheme and host rejected');
+$t->throws(ConfigException::class, static fn () => AgentConfigResolver::resolve(['apiKey' => 'test-api-key-123', 'endpoint' => 123]), 'non-string endpoint rejected');
+$noLoggerConfig = AgentConfigResolver::resolve(['apiKey' => 'test-api-key-123']);
+$t->ok($noLoggerConfig->logger instanceof \RenzoFranceschini\GuardAgent\Log\DefaultAgentLogger, 'a non-logger input falls back to the default logger');
+$redisInstanceConfig = AgentConfigResolver::resolve([
+    'apiKey' => 'test-api-key-123',
+    'redis' => new \RenzoFranceschini\GuardAgent\Config\RedisConfig(url: 'redis://127.0.0.1:6379/0', commandTimeoutMs: 250.0),
+    'logger' => new SilentLogger(),
+]);
+$t->same(250.0, $redisInstanceConfig->redis?->commandTimeoutMs, 'a RedisConfig instance is accepted as-is');
+$coercedConfig = AgentConfigResolver::resolve([
+    'apiKey' => 'test-api-key-123',
+    'bufferSize' => '55',
+    'high_watermark_ratio' => '0.5',
+    'enable_metrics' => 0,
+    'sensitiveHeaders' => ['x-secret', 7],
+    'logger' => new SilentLogger(),
+]);
+$t->same(55, $coercedConfig->bufferSize, 'numeric-string bufferSize coerced');
+$t->same(0.5, $coercedConfig->highWatermarkRatio, 'numeric-string watermark coerced');
+$t->same(false, $coercedConfig->enableMetrics, 'integer-boolean enable_metrics coerced');
+$t->same(['x-secret', '7'], $coercedConfig->sensitiveHeaders, 'sensitive header lists coerce entries to strings');
+$t->throws(ConfigException::class, static fn () => makeConfig(['flushInterval' => 0]), 'flushInterval <= 0 rejected');
+$t->throws(ConfigException::class, static fn () => makeConfig(['timeout' => 0]), 'timeout <= 0 rejected');
+$t->throws(ConfigException::class, static fn () => makeConfig(['backoffFactor' => 0]), 'backoffFactor <= 0 rejected');
+$t->throws(ConfigException::class, static fn () => makeConfig(['maxConcurrentFlushes' => 0]), 'maxConcurrentFlushes below 1 rejected');
+$t->throws(ConfigException::class, static fn () => makeConfig(['compressionThreshold' => -1]), 'negative compressionThreshold rejected');
+$t->throws(
+    ConfigException::class,
+    static fn () => makeConfig(['redis' => ['url' => 'redis://127.0.0.1:6379/0', 'commandTimeoutMs' => 0]]),
+    'redis commandTimeoutMs <= 0 rejected'
+);
+$validatorTarget = new AgentConfig('short', 'ftp://bad.example');
+$t->ok(AgentConfigResolver::validate($validatorTarget) !== [], 'validate() flags a non-http endpoint directly');
+
+$t->section('install id filesystem edges');
+
+$realHome = getenv('HOME') ?: '';
+putenv('HOME');
+$homelessPath = InstallId::defaultPath();
+$t->ok(str_ends_with($homelessPath, '/.guard-agent/install-id'), 'default path falls back without HOME');
+putenv('HOME=' . $realHome);
+$unreadable = (string) tempnam(sys_get_temp_dir(), 'gaph-locked');
+chmod($unreadable, 0000);
+if (!is_readable($unreadable)) {
+    $logger = new CaptureLogger();
+    $generated = InstallId::resolve($unreadable, null, $logger);
+    $t->ok(Uuid::isUuid($generated), 'an unreadable install id file falls back to a fresh uuid');
+    $t->ok((bool) array_filter($logger->warnings, static fn (string $w): bool => str_contains($w, 'install_id.read_failed')), 'read failures are warned about');
+    $t->ok((bool) array_filter($logger->warnings, static fn (string $w): bool => str_contains($w, 'install_id.write_failed')), 'write failures are warned about');
+} else {
+    $t->skip('privileges bypass file permissions; unreadable fixture unavailable');
+}
+@unlink($unreadable);
+$logger = new CaptureLogger();
+$mkdirFailed = InstallId::resolve('/proc/self/environ/guard-agent-install', null, $logger);
+$t->ok(Uuid::isUuid($mkdirFailed), 'an unwritable directory still yields a fresh uuid');
+$t->ok((bool) array_filter($logger->warnings, static fn (string $w): bool => str_contains($w, 'install_id.write_failed')), 'unwritable directories are warned about');
+
+$t->section('default logger');
+
+putenv('GUARD_AGENT_DEBUG');
+$quietLogger = new \RenzoFranceschini\GuardAgent\Log\DefaultAgentLogger();
+$t->ok(true, 'default logger constructs with debug unset');
+putenv('GUARD_AGENT_DEBUG=1');
+$loudLogger = new \RenzoFranceschini\GuardAgent\Log\DefaultAgentLogger();
+$loudLogger->debug('debug line');
+$loudLogger->info('info line');
+putenv('GUARD_AGENT_DEBUG');
+$warnLogger = new \RenzoFranceschini\GuardAgent\Log\DefaultAgentLogger();
+$warnLogger->warning('warning line');
+$warnLogger->error('error line');
+$t->ok(true, 'default logger writes all levels without raising');
+
+$t->section('redis handler edges');
+
+$fake = new FakeRedisClient();
+$handler = new RedisHandler($fake, 'gatest-edges', new SilentLogger());
+$handler->ping();
+$t->ok(true, 'redis handler pings through the client');
+$handler->setKey('agent_events', 'k', 'v', 60);
+$t->same(1, $handler->delete('agent_events', 'k'), 'redis handler deletes through the client');
+$deadHandler = new RedisHandler(new StreamRedisClient('redis://127.0.0.1:1/0', null, null, 0.2), 'gatest-edges', new SilentLogger());
+$t->same(0, $deadHandler->delete('agent_events', 'k'), 'delete failures return 0 and warn');
+$t->same([], $deadHandler->keys('agent_events:*'), 'keys failures return empty');
+$throwCloseHandler = new RedisHandler(new ThrowingCloseClient(), 'gatest-edges', new SilentLogger());
+$throwCloseHandler->close();
+$t->ok(true, 'redis handler close is best effort');
+
+$t->section('ext-redis adapter');
+
+if (!class_exists('Redis', false)) {
+    class_alias(ScriptedExtRedis::class, 'Redis');
+}
+$scriptedExt = new ScriptedExtRedis();
+$scriptedExt->getReplies = ['cached-value', false];
+$extClient = new ExtRedisClient($scriptedExt);
+$extClient->ping();
+$t->same('cached-value', $extClient->get('k'), 'ext adapter returns string values');
+$t->same(null, $extClient->get('missing'), 'ext adapter maps misses to null');
+$t->ok($extClient->set('k', 'v'), 'ext adapter sets without a ttl');
+$t->ok($extClient->set('k', 'v', 60), 'ext adapter sets with a ttl');
+$t->same(0, $extClient->delete(), 'ext adapter deletes nothing without keys');
+$t->same(2, $extClient->delete('a', 'b'), 'ext adapter deletes through the client');
+$scriptedExt->keysReplies = [['a', 'b']];
+$t->same(['a', 'b'], $extClient->keys('p:*'), 'ext adapter normalizes key lists');
+$scriptedExt->keysReplies = [false];
+$t->same([], $extClient->keys('p:*'), 'ext adapter maps non-array key replies to empty');
+$scriptedExt->closeThrows = true;
+$extClient->close();
+$t->ok(true, 'ext adapter close is best effort');
+$scriptedExt->setReply = false;
+$t->ok(!$extClient->set('k', 'v'), 'ext adapter propagates set failures');
+$scriptedExt->setReply = true;
+$scriptedExt->setexReply = false;
+$t->ok(!$extClient->set('k', 'v', 60), 'ext adapter propagates setex failures');
+
+$t->section('predis adapter');
+
+$t->throws(
+    \RenzoFranceschini\GuardAgent\Exception\RedisException::class,
+    static fn () => new PredisRedisClient(new stdClass()),
+    'predis adapter rejects objects without the client surface'
+);
+$predis = new PredisRedisClient(new ScriptedPredis());
+$predis->ping();
+$t->ok(true, 'predis adapter pings through the client');
+$scriptedPredis = new ScriptedPredis();
+$scriptedPredis->getReply = 'cached';
+$t->same('cached', (new PredisRedisClient($scriptedPredis))->get('k'), 'predis adapter returns string values');
+$scriptedPredis->getReply = false;
+$t->same(null, (new PredisRedisClient($scriptedPredis))->get('k'), 'predis adapter maps misses to null');
+$scriptedPredis->setReply = true;
+$t->ok((new PredisRedisClient($scriptedPredis))->set('k', 'v'), 'predis adapter sets without a ttl');
+$scriptedPredis->setexReply = false;
+$t->ok(!(new PredisRedisClient($scriptedPredis))->set('k', 'v', 60), 'predis adapter propagates setex failures');
+$t->same(0, (new PredisRedisClient($scriptedPredis))->delete(), 'predis adapter deletes nothing without keys');
+$t->same(1, (new PredisRedisClient($scriptedPredis))->delete('a'), 'predis adapter deletes through the client');
+$scriptedPredis->keysReply = ['a'];
+$t->same(['a'], (new PredisRedisClient($scriptedPredis))->keys('p:*'), 'predis adapter normalizes key lists');
+$scriptedPredis->keysReply = 'junk';
+$t->same([], (new PredisRedisClient($scriptedPredis))->keys('p:*'), 'predis adapter maps non-array key replies to empty');
+(new PredisRedisClient($scriptedPredis))->close();
+$t->ok(true, 'predis adapter closes through the client');
+
+$t->section('stream redis client against a scripted fake');
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis(['+NOPE']);
+try {
+    (new StreamRedisClient("redis://127.0.0.1:{$fakePort}"))->ping();
+    $t->failed++;
+    echo "FAIL - an unexpected PING reply raises\n";
+} catch (\RenzoFranceschini\GuardAgent\Exception\RedisException $error) {
+    $t->ok(str_contains($error->getMessage(), 'Unexpected PING reply'), 'an unexpected PING reply raises');
+}
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis([':0']);
+$t->same([], (new StreamRedisClient("redis://127.0.0.1:{$fakePort}"))->keys('*'), 'integer KEYS replies map to an empty list');
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis(['*-1']);
+$t->same([], (new StreamRedisClient("redis://127.0.0.1:{$fakePort}"))->keys('*'), 'null KEYS replies map to an empty list');
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+$emptyDeleteStream = new StreamRedisClient('redis://127.0.0.1:1/0', null, null, 0.2);
+$t->same(0, $emptyDeleteStream->delete(), 'delete without keys is a zero no-op');
+
+$freshStream = new StreamRedisClient("redis://127.0.0.1:{$fakePort}");
+$freshStream->close();
+$t->ok(true, 'closing an unconnected stream client is a no-op');
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis(['+PONG']);
+$openStream = new StreamRedisClient("redis://127.0.0.1:{$fakePort}");
+$openStream->ping();
+$openStream->close();
+$t->ok(true, 'closing a connected stream client quits the socket');
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis([], 'halfclose');
+$halfClosed = new StreamRedisClient("redis://127.0.0.1:{$fakePort}", null, null, 1.0);
+try {
+    $halfClosed->ping();
+    $t->failed++;
+    echo "FAIL - a half-closed connection raises on read\n";
+} catch (\RenzoFranceschini\GuardAgent\Exception\RedisException $error) {
+    $t->ok(str_contains($error->getMessage(), 'redis read failed'), 'a half-closed connection raises on read');
+}
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis(['+nope']);
+try {
+    (new StreamRedisClient("redis://127.0.0.1:{$fakePort}", 'pass'))->ping();
+    $t->failed++;
+    echo "FAIL - a failed AUTH raises\n";
+} catch (\RenzoFranceschini\GuardAgent\Exception\RedisException $error) {
+    $t->same('redis AUTH failed', $error->getMessage(), 'a non-OK AUTH reply raises');
+}
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis(['+OK', '+nope']);
+try {
+    (new StreamRedisClient("redis://127.0.0.1:{$fakePort}", 'pass', 2))->ping();
+    $t->failed++;
+    echo "FAIL - a failed SELECT raises\n";
+} catch (\RenzoFranceschini\GuardAgent\Exception\RedisException $error) {
+    $t->same('redis SELECT 2 failed', $error->getMessage(), 'a non-OK SELECT reply raises');
+}
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis(['-ERR bad command']);
+try {
+    (new StreamRedisClient("redis://127.0.0.1:{$fakePort}"))->ping();
+    $t->failed++;
+    echo "FAIL - an error reply raises\n";
+} catch (\RenzoFranceschini\GuardAgent\Exception\RedisException $error) {
+    $t->same('redis error reply: ERR bad command', $error->getMessage(), 'an -ERR reply raises');
+}
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis(['Xbogus']);
+try {
+    (new StreamRedisClient("redis://127.0.0.1:{$fakePort}"))->ping();
+    $t->failed++;
+    echo "FAIL - a protocol violation raises\n";
+} catch (\RenzoFranceschini\GuardAgent\Exception\RedisException $error) {
+    $t->ok(str_contains($error->getMessage(), 'redis protocol error'), 'an unknown reply type raises a protocol error');
+}
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis([[ '$6', 'abc' ]]);
+try {
+    (new StreamRedisClient("redis://127.0.0.1:{$fakePort}"))->get('k');
+    $t->failed++;
+    echo "FAIL - a truncated bulk reply raises\n";
+} catch (\RenzoFranceschini\GuardAgent\Exception\RedisException $error) {
+    $t->ok(str_contains($error->getMessage(), 'bulk string truncated'), 'a truncated bulk reply raises');
+}
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis([], 'close');
+$closedPeer = new StreamRedisClient("redis://127.0.0.1:{$fakePort}", null, null, 1.0);
+try {
+    $closedPeer->ping();
+    $t->failed++;
+    echo "FAIL - a server that closes immediately raises on read\n";
+} catch (\RenzoFranceschini\GuardAgent\Exception\RedisException $error) {
+    $t->ok(str_contains($error->getMessage(), 'redis read failed') || str_contains($error->getMessage(), 'write failed'), 'an immediate server close raises');
+}
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis(['+PONG'], 'rst-after-reply');
+$rstStream = new StreamRedisClient("redis://127.0.0.1:{$fakePort}", null, null, 1.0);
+$rstStream->ping();
+usleep(300_000);
+$rstStream->close();
+$t->ok(true, 'closing a reset peer is a best-effort QUIT (the QUIT write failure is contained)');
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+[$fakeProc, $fakePort, $fakeControl] = startFakeRedis([], 'partial');
+$hungStream = new StreamRedisClient("redis://127.0.0.1:{$fakePort}", null, null, 0.3);
+$hungStart = microtime(true);
+try {
+    $hungStream->ping();
+    $t->failed++;
+    echo "FAIL - a hung server times out\n";
+} catch (\RenzoFranceschini\GuardAgent\Exception\RedisException $error) {
+    $t->ok(str_contains($error->getMessage(), 'timed out'), 'a hung server times out per the command timeout');
+}
+$t->ok(microtime(true) - $hungStart < 5.0, 'the command timeout bounds the wait');
+proc_terminate($fakeProc);
+proc_close($fakeProc);
+@unlink($fakeControl);
+
+$t->throws(
+    \RenzoFranceschini\GuardAgent\Exception\RedisException::class,
+    static fn () => new StreamRedisClient('localhost:6379'),
+    'a redis URL without scheme and host is rejected'
+);
+$t->throws(
+    \RenzoFranceschini\GuardAgent\Exception\RedisException::class,
+    static fn () => new StreamRedisClient('ftp://127.0.0.1:6379'),
+    'a non-redis scheme is rejected'
+);
+
 
 @unlink($controlFile);
 @unlink($stateFile);
 
+// =====================================================================
+// 13. Buffer persistence edges
+// =====================================================================
+$t->section('buffer persistence edges');
+
+// Persist failures through a throwing client hit the catch paths.
+$throwingBuffer = new EventBuffer(makeConfig());
+$throwingBuffer->initializeRedis(new RedisHandler(new ThrowingRedisClient(), 'gatest', new SilentLogger()));
+$throwingBuffer->addEvent(makeEvent(['event_type' => 'a']));
+$t->same(1, $throwingBuffer->getStats()['redisPersistFailures'], 'a throwing persist counts a failure (events)');
+$t->same('', $throwingBuffer->flushEventsWithKeys()[1][0], 'a throwing persist stores no key');
+$throwingBuffer->addMetric(makeMetric());
+$t->same(2, $throwingBuffer->getStats()['redisPersistFailures'], 'a throwing persist counts a failure (metrics)');
+
+// Persist rejections (SET not OK) count too.
+$rejectFake = new FakeRedisClient();
+$rejectFake->failWrites(true);
+$rejectBuffer = new EventBuffer(makeConfig());
+$rejectBuffer->initializeRedis(new RedisHandler($rejectFake, 'gatest', new SilentLogger()));
+$rejectBuffer->addMetric(makeMetric());
+$t->same(1, $rejectBuffer->getStats()['redisPersistFailures'], 'a rejected metric persist counts a failure');
+
+// Startup load: valid seeds, missing data, corrupt json, invalid payloads,
+// and eviction when the buffer is full during the load.
+$seedFake = new FakeRedisClient();
+$seedPrefix = 'gatest-seeds';
+$validEvent = Json::encode(makeEvent(['event_type' => 'seeded'])->toWire());
+$validMetric = Json::encode(makeMetric(['metric_type' => 'request_count', 'value' => 9])->toWire());
+$seedFake->set($seedPrefix . ':agent_events:event_good', $validEvent, 60);
+$seedFake->set($seedPrefix . ':agent_events:event_nodata', 'whatever', 60);
+$seedFake->set($seedPrefix . ':agent_events:event_corrupt', '{not json', 60);
+$seedFake->set($seedPrefix . ':agent_events:event_invalid', Json::encode(['unexpected' => true]), 60);
+$seedFake->set($seedPrefix . ':agent_metrics:metric_good', $validMetric, 60);
+$seedFake->set($seedPrefix . ':agent_metrics:metric_corrupt', '{not json', 60);
+$seedFake->set($seedPrefix . ':agent_metrics:metric_invalid', Json::encode(['unexpected' => true]), 60);
+$seededBuffer = new EventBuffer(makeConfig(['bufferSize' => 1]));
+$seededBuffer->initializeRedis(new RedisHandler($seedFake, $seedPrefix, new SilentLogger()));
+$t->same(2, $seededBuffer->getBufferSize(), 'one event and one metric seeded from redis (invalid skipped)');
+[$seededEvents] = $seededBuffer->flushEventsWithKeys();
+$t->same(['seeded'], eventTypes($seededEvents), 'the valid seeded event loaded with its key');
+[$seededMetrics] = $seededBuffer->flushMetricsWithKeys();
+$t->same(9, $seededMetrics[0]->value, 'the valid seeded metric loaded');
+
+// A load-time full buffer evicts the oldest entry's key.
+$evictFake = new FakeRedisClient();
+$evictFake->set('gatest-evict:agent_events:event_first', Json::encode(makeEvent(['event_type' => 'first'])->toWire()), 60);
+$evictFake->set('gatest-evict:agent_events:event_second', Json::encode(makeEvent(['event_type' => 'second'])->toWire()), 60);
+$evictFake->set('gatest-evict:agent_metrics:metric_first', Json::encode(makeMetric(['value' => 1])->toWire()), 60);
+$evictFake->set('gatest-evict:agent_metrics:metric_second', Json::encode(makeMetric(['value' => 2])->toWire()), 60);
+$evictBuffer = new EventBuffer(makeConfig(['bufferSize' => 1]));
+$evictBuffer->initializeRedis(new RedisHandler($evictFake, 'gatest-evict', new SilentLogger()));
+$t->same(4, $evictBuffer->getBufferSize(), 'load-time overflow forgets keys but retains the items in memory');
+[$evictedEvents, $evictedEventKeys] = $evictBuffer->flushEventsWithKeys();
+$t->same(['first', 'second'], eventTypes($evictedEvents), 'both seeded events loaded');
+$t->same('', $evictedEventKeys[0], 'the overflowed seed lost its persistence key');
+$t->ok($evictedEventKeys[1] !== '', 'the newest seed keeps its key');
+
+// Keys listed in redis whose values vanished before the reload.
+$keysOnly = new KeysOnlyRedisClient();
+$keysOnly->listed = ['gatest-keys:agent_events:event_ghost', 'gatest-keys:agent_metrics:metric_ghost'];
+$ghostBuffer = new EventBuffer(makeConfig());
+$ghostBuffer->initializeRedis(new RedisHandler($keysOnly, 'gatest-keys', new SilentLogger()));
+$t->same(0, $ghostBuffer->getBufferSize(), 'vanished records are skipped with a warning');
+
+// Metric overflow under drop policy without redis (no keys to forget).
+$keylessMetricDrop = new EventBuffer(makeConfig(['bufferSize' => 1]));
+$keylessMetricDrop->addMetric(makeMetric(['value' => 1]));
+$keylessMetricDrop->addMetric(makeMetric(['value' => 2]));
+$t->same(1, $keylessMetricDrop->getBufferSize(), 'drop policy evicted the keyless oldest metric');
+
+// Metric requeue eviction with persisted keys returns those keys.
+$keyedRequeueFake = new FakeRedisClient();
+$keyedBuffer = new EventBuffer(makeConfig(['bufferSize' => 2]));
+$keyedBuffer->initializeRedis(new RedisHandler($keyedRequeueFake, 'gatest-keyed', new SilentLogger()));
+$keyedBuffer->addMetric(makeMetric(['value' => 1]));
+$keyedBuffer->addMetric(makeMetric(['value' => 2]));
+[$keyedMetrics, $keyedKeys] = $keyedBuffer->flushMetricsWithKeys();
+$requeueMetricEvicted = $keyedBuffer->requeueMetricsInMemory(
+    [makeMetric(['value' => 4]), makeMetric(['value' => 3]), $keyedMetrics[1], $keyedMetrics[0]],
+    ['', '', $keyedKeys[1], $keyedKeys[0]]
+);
+$t->ok($requeueMetricEvicted !== [], 'requeue eviction returns the evicted metric keys');
+$t->same(2, $keyedBuffer->getBufferSize(), 'the metric requeue stayed within the buffer');
+
+// Persist failures through a batch carrying unencodable payloads.
+$utf8Fake = new FakeRedisClient();
+$utf8Buffer = new EventBuffer(makeConfig());
+$utf8Buffer->initializeRedis(new RedisHandler($utf8Fake, 'gatest-utf8', new SilentLogger()));
+$utf8Buffer->addEvent(makeEvent(['metadata' => ['bad' => "\xB1\x31"]]));
+$t->same(1, $utf8Buffer->getStats()['redisPersistFailures'], 'an unencodable event payload counts a persist failure');
+$utf8Buffer->addMetric(makeMetric(['tags' => ['bad' => "\xB1\x31"]]));
+$t->same(2, $utf8Buffer->getStats()['redisPersistFailures'], 'an unencodable metric payload counts a persist failure');
+
+// Confirm paths without a handler and with delete failures.
+$keylessBuffer = new EventBuffer(makeConfig());
+$keylessBuffer->confirmEventRedisKeys(['k1', '', null]);
+$keylessBuffer->confirmMetricRedisKeys(['k1', '', null]);
+$t->ok(true, 'confirm calls are no-ops without a redis handler');
+$throwingConfirm = new EventBuffer(makeConfig());
+$throwingConfirm->initializeRedis(new RedisHandler(new ThrowingRedisClient(), 'gatest', new SilentLogger()));
+$throwingConfirm->confirmEventRedisKeys(['k1']);
+$throwingConfirm->confirmMetricRedisKeys(['k1', '', null]);
+$t->ok(true, 'confirm failures are contained');
+
+// clearBuffer with a throwing client is contained.
+$throwingClear = new EventBuffer(makeConfig());
+$throwingClear->initializeRedis(new RedisHandler(new ThrowingRedisClient(), 'gatest', new SilentLogger()));
+$throwingClear->clearBuffer();
+$t->ok(true, 'clearBuffer failures are contained');
+
+// Requeue with null entries and keyless items.
+$requeueBuffer = new EventBuffer(makeConfig(['bufferSize' => 2]));
+$residentA = makeEvent(['event_type' => 'a']);
+$residentB = makeEvent(['event_type' => 'b']);
+$requeueBuffer->requeueEventsInMemory([$residentA, $residentB], ['', '']);
+$t->ok(true, 'requeue accepts keyless items');
+$requeueBuffer->requeueEventsInMemory([null], ['k']);
+$t->same(2, $requeueBuffer->getBufferSize(), 'null requeue entries are skipped');
+$requeueBuffer->requeueMetricsInMemory([null], ['k']);
+$requeueBuffer->requeueMetricsInMemory([makeMetric()], ['']);
+$t->same(3, $requeueBuffer->getBufferSize(), 'metric requeue accepts keyless items');
+
+// Requeue under pressure with keyless residents returns no keys.
+$pressureBuffer = new EventBuffer(makeConfig(['bufferSize' => 2]));
+$pressureBuffer->addEvent(makeEvent(['event_type' => 'r1']));
+$pressureBuffer->addEvent(makeEvent(['event_type' => 'r2']));
+$pressureEvicted = $pressureBuffer->requeueEventsInMemory([makeEvent(['event_type' => 'n1']), makeEvent(['event_type' => 'n2'])], ['', '']);
+$t->same([], $pressureEvicted, 'requeue eviction without keys returns nothing to confirm');
+$pressureBuffer->addMetric(makeMetric());
+$pressureBuffer->addMetric(makeMetric());
+$pressureMetricEvicted = $pressureBuffer->requeueMetricsInMemory([makeMetric(), makeMetric()], ['', '']);
+$t->same([], $pressureMetricEvicted, 'metric requeue eviction without keys returns nothing');
+
+// Overflow policies through the metric side.
+$metricRaise = new EventBuffer(makeConfig(['bufferSize' => 1, 'bufferOverflowPolicy' => 'raise']));
+$metricRaise->addMetric(makeMetric());
+$t->throws(BufferFullException::class, static fn () => $metricRaise->addMetric(makeMetric()), 'raise policy throws for metrics');
+
+$metricBlock = new EventBuffer(makeConfig(['bufferSize' => 1, 'bufferOverflowPolicy' => 'block']));
+$metricBlock->addMetric(makeMetric());
+$metricDrains = 0;
+$metricBlock->drainCallback = function () use (&$metricDrains, $metricBlock): void {
+    $metricDrains++;
+    $metricBlock->flushMetricsWithKeys();
+};
+$metricBlock->addMetric(makeMetric());
+$t->ok($metricDrains >= 1, 'block policy drained inline for metrics');
+
+$dropFake = new FakeRedisClient();
+$metricDrop = new EventBuffer(makeConfig(['bufferSize' => 1]));
+$metricDrop->initializeRedis(new RedisHandler($dropFake, 'gatest-drop', new SilentLogger()));
+$metricDrop->addMetric(makeMetric(['value' => 1]));
+$metricDrop->addMetric(makeMetric(['value' => 2]));
+$t->same(1, $metricDrop->getBufferSize(), 'drop policy evicted the oldest metric');
+
+$eventDrop = new EventBuffer(makeConfig(['bufferSize' => 1]));
+$eventDrop->initializeRedis(new RedisHandler(new FakeRedisClient(), 'gatest-drop', new SilentLogger()));
+$eventDrop->addEvent(makeEvent(['event_type' => 'r1']));
+$eventDrop->addEvent(makeEvent(['event_type' => 'r2']));
+$t->same(1, $eventDrop->getBufferSize(), 'drop policy evicted the oldest event');
+
+// =====================================================================
+// 14. Transport edges against the mock ingestion API
+// =====================================================================
+$t->section('transport edges');
+
+$edgeOverrides = array_merge($baseOverrides, ['retryAttempts' => 1, 'backoffFactor' => 0.01, 'timeout' => 10]);
+
+$edgeTransport = new HttpTransport(makeConfig($edgeOverrides));
+$edgeTransport->initialize();
+$edgeTransport->initialize();
+$t->ok(true, 'transport initialization is idempotent');
+$edgeTransport->close();
+$t->ok($edgeTransport->getStats()['sessionClosed'], 'close marks the session closed');
+$t->same(true, $edgeTransport->sendEvents([]), 'sendEvents on an empty batch is a no-op success');
+$t->same(true, $edgeTransport->sendMetrics([]), 'sendMetrics on an empty batch is a no-op success');
+
+// 201 accepted; small 409 responses exhaust the retries and return false.
+flushState($stateFile);
+setScript($controlFile, ['events' => [201]], $secret, true);
+$edgeTransport = new HttpTransport(makeConfig($edgeOverrides));
+$t->same(true, $edgeTransport->sendEvents([makeEvent()]), 'a 201 counts as accepted');
+
+flushState($stateFile);
+setScript($controlFile, ['events' => [409, 409]], $secret, true);
+$edgeTransport = new HttpTransport(makeConfig($edgeOverrides));
+$t->same(false, $edgeTransport->sendEvents([makeEvent()]), 'an unclassified 4xx is a transient failure');
+$t->ok($edgeTransport->requestsFailed >= 1, 'the unclassified 4xx counted a failed request');
+
+// A malformed batch (non-SecurityEvent element) fails inside the send path
+// and is contained as a transient failure instead of crashing the caller.
+$edgeTransport = new HttpTransport(makeConfig($edgeOverrides));
+$t->same(false, $edgeTransport->sendEvents(['not-an-event']), 'a malformed event batch is a contained transient failure');
+$t->ok($edgeTransport->requestsFailed >= 1, 'the malformed event batch counted a failed request');
+$edgeTransport = new HttpTransport(makeConfig($edgeOverrides));
+$t->same(false, $edgeTransport->sendMetrics(['not-a-metric']), 'a malformed metric batch is a contained transient failure');
+
+// A 200 with an unparseable body is a partial failure, then the retry passes.
+flushState($stateFile);
+setScript($controlFile, ['events' => [['status' => 200, 'body' => ['__raw' => '{oops']]]], $secret, true);
+$edgeTransport = new HttpTransport(makeConfig($edgeOverrides));
+$t->same(true, $edgeTransport->sendEvents([makeEvent()]), 'an unparseable 200 body retries and succeeds');
+$t->same([200, 200], statuses(stateFor($stateFile, '/api/v1/events')), 'the unparseable 200 was retried once');
+
+// Serialization failure: invalid UTF-8 metadata aborts the POST, retains the
+// batch as a transient failure, and fires the onError hook.
+flushState($stateFile);
+$hookSeen = [];
+$edgeConfig = makeConfig(array_merge($edgeOverrides, [
+    'onError' => static function (string $stage, Throwable $error, array $context) use (&$hookSeen): void {
+        $hookSeen[] = [$stage, $error->getMessage(), $context];
+    },
+]));
+$edgeTransport = new HttpTransport($edgeConfig);
+$t->same(false, $edgeTransport->sendEvents([makeEvent(['metadata' => ['bad' => "\xB1\x31"]])]), 'an unserializable batch is a transient failure');
+$t->ok($hookSeen !== [] && $hookSeen[0][0] === 'transport_send', 'the onError hook fired for the serialization failure');
+
+// The wire batch carries the metadata/tags objects through makeRequest's
+// redaction pass (ingest-time redaction already ran inside the agent).
+flushState($stateFile);
+setScript($controlFile, [], $secret, true);
+$edgeTransport = new HttpTransport(makeConfig($edgeOverrides));
+$edgeTransport->sendEvents([makeEvent(['metadata' => ['keep' => 'yes']])]);
+$edgeRecords = stateFor($stateFile, '/api/v1/events');
+$t->same('yes', $edgeRecords[0]['body_json']['events'][0]['metadata']['keep'] ?? null, 'event metadata rides the wire batch unchanged at the boundary');
+flushState($stateFile);
+$edgeTransport->sendMetrics([makeMetric(['tags' => ['route' => '/x']])]);
+$edgeRecords = stateFor($stateFile, '/api/v1/metrics');
+$t->same('/x', $edgeRecords[0]['body_json']['metrics'][0]['tags']['route'] ?? null, 'metric tags ride the wire batch unchanged at the boundary');
+
+// Metrics: 413 splits, 400 drops permanently.
+flushState($stateFile);
+setScript($controlFile, ['metrics' => [413, 200, 200]], $secret, true);
+$edgeTransport = new HttpTransport(makeConfig($edgeOverrides));
+$t->same(true, $edgeTransport->sendMetrics([makeMetric(['value' => 1]), makeMetric(['value' => 2]), makeMetric(['value' => 3])]), 'a metrics 413 splits into accepted halves');
+$t->same([413, 200, 200], statuses(stateFor($stateFile, '/api/v1/metrics')), 'the metrics 413 split was retried as two halves');
+
+flushState($stateFile);
+setScript($controlFile, ['metrics' => [400]], $secret, true);
+$edgeTransport = new HttpTransport(makeConfig($edgeOverrides));
+$t->same(true, $edgeTransport->sendMetrics([makeMetric()]), 'a permanently rejected metrics batch is dropped durably');
+$t->same([400], statuses(stateFor($stateFile, '/api/v1/metrics')), 'the metrics 400 was observed exactly once');
+
+// Status: a permanent 400 is contained (never retried, returns false).
+flushState($stateFile);
+setScript($controlFile, ['status' => [400]], $secret, true);
+$edgeTransport = new HttpTransport(makeConfig($edgeOverrides));
+$t->same(false, $edgeTransport->sendStatus(new AgentStatus(
+    timestamp: WireFormat::now(),
+    status: 'healthy',
+    uptime: 1.0,
+    eventsSent: 0,
+    eventsFailed: 0,
+    bufferSize: 0,
+    lastFlush: null,
+    errors: [],
+)), 'a permanent status rejection returns false without retries');
+$t->same([400], statuses(stateFor($stateFile, '/api/v1/status')), 'the status 400 was observed exactly once');
+
+// Local rate limiter: denied sends wait for the window instead of giving up.
+flushState($stateFile);
+setScript($controlFile, ['events' => [500, 200]], $secret, true);
+$limitedOverrides = array_merge($edgeOverrides, ['retryAttempts' => 3]);
+$limitedTransport = new HttpTransport(makeConfig($limitedOverrides));
+saturateRateLimiter(refl($limitedTransport, 'rateLimiter')->getValue($limitedTransport));
+$t->same(true, $limitedTransport->sendEvents([makeEvent()]), 'the local rate limiter waits and retries');
+$t->same([500, 200], statuses(stateFor($stateFile, '/api/v1/events')), 'the denied wait never reached the server');
+
+flushState($stateFile);
+setScript($controlFile, ['rules' => [500, ['status' => 200, 'body' => ['rule_id' => 'rl']]]]);
+$limitedRulesTransport = new HttpTransport(makeConfig($limitedOverrides));
+saturateRateLimiter(refl($limitedRulesTransport, 'rateLimiter')->getValue($limitedRulesTransport));
+$t->same('rl', $limitedRulesTransport->fetchDynamicRules()?->ruleId, 'the rules GET honors the local rate limiter');
+
+// An unencodable envelope aborts the encrypted POST and retains the batch.
+flushState($stateFile);
+$encBadVersion = new HttpTransport(makeConfig(array_merge($edgeOverrides, [
+    'projectEncryptionKey' => $vectors[0]['key_b64'],
+    'guardVersion' => "\xB1\x31",
+])));
+$t->same(false, $encBadVersion->sendEvents([makeEvent()]), 'an unencodable encrypted envelope is a transient failure');
+$t->same([], statuses(stateFor($stateFile, '/api/v1/events/encrypted')), 'the unencodable envelope never reached the server');
+
+// Encrypted batches compress and sign like plaintext ones.
+flushState($stateFile);
+$encEdge = new HttpTransport(makeConfig(array_merge($edgeOverrides, [
+    'projectEncryptionKey' => $vectors[0]['key_b64'],
+    'compressionThreshold' => 10,
+])));
+$encEdge->sendEvents([makeEvent()]);
+$encEdgeRecords = stateFor($stateFile, '/api/v1/events/encrypted');
+$t->same('gzip', $encEdgeRecords[0]['content_encoding'] ?? null, 'an encrypted batch above the threshold is gzipped');
+$t->ok($encEdge->getStats()['bytesSent'] > 0, 'encrypted sends account their bytes');
+
+proc_terminate($proc);
+proc_close($proc);
+
+// =====================================================================
+// 15. Agent lifecycle edges
+// =====================================================================
+$t->section('agent lifecycle edges');
+
+// enable_events / enable_metrics kill switches.
+$agent = makeAgent(['enableEvents' => false], new RecordingTransport());
+$agent->sendEvent(makeEvent());
+$t->same(0, $agent->buffer->getBufferSize(), 'enable_events=false drops events');
+$agent = makeAgent(['enableMetrics' => false], new RecordingTransport());
+$agent->sendMetric(makeMetric());
+$t->same(0, $agent->buffer->getBufferSize(), 'enable_metrics=false drops metrics');
+
+// Invalid metric input is contained.
+$agent = makeAgent([], new RecordingTransport());
+$agent->sendMetric('garbage');
+$t->same(0, $agent->buffer->getBufferSize(), 'an invalid metric is dropped, not buffered');
+
+// Block policy drains inline through the agent's own flushBuffer.
+$agent = makeAgent(['bufferSize' => 1, 'bufferOverflowPolicy' => 'block'], new RecordingTransport());
+$agent->sendEvent(makeEvent(['event_type' => 'a']));
+$agent->sendEvent(makeEvent(['event_type' => 'b']));
+[$blockedEvents] = $agent->buffer->flushEventsWithKeys();
+$t->same(['b'], eventTypes($blockedEvents), 'block policy admitted the new event after the inline drain');
+$t->same(1, $agent->eventsSent, 'the inline drain delivered the first event');
+
+// redisHandler getter.
+$fake = new FakeRedisClient();
+$agent = makeAgent([], new RecordingTransport());
+$t->same(null, $agent->redisHandler(), 'no redis handler before initialization');
+$agent->initializeRedis(new RedisHandler($fake, 'gatest', new SilentLogger()));
+$t->ok($agent->redisHandler() instanceof RedisHandler, 'redisHandler exposes the attached handler');
+
+// Failing flushes confirm evicted requeue keys so records never orphan.
+$fake = new FakeRedisClient();
+$transport = new RecordingTransport();
+$transport->eventOutcomes = [false];
+$agent = makeAgent(['bufferSize' => 1, 'flushInterval' => 30], $transport);
+$agent->initializeRedis(new RedisHandler($fake, 'gatest-evict', new SilentLogger()));
+$agent->sendEvent(makeEvent(['event_type' => 'a']));
+$agent->sendEvent(makeEvent(['event_type' => 'b']));
+$agent->flushBuffer();
+$t->same(1, count($fake->storage), 'a failed flush confirms the evicted key and retains the rest');
+
+// Metrics mirror the same eviction-confirm path.
+$fake = new FakeRedisClient();
+$transport = new RecordingTransport();
+$transport->metricOutcomes = [false];
+$agent = makeAgent(['bufferSize' => 1, 'flushInterval' => 30], $transport);
+$agent->initializeRedis(new RedisHandler($fake, 'gatest-evict', new SilentLogger()));
+$agent->sendMetric(makeMetric());
+$agent->sendMetric(makeMetric());
+$agent->flushBuffer();
+$t->same(1, count($fake->storage), 'a failed metric flush confirms the evicted key and retains the rest');
+
+// A load-time overflow (more seeds than the buffer holds) requeues a batch
+// larger than the buffer: the tail evictions are confirmed away.
+$overflowFake = new FakeRedisClient();
+$overflowPrefix = 'gatest-overflow';
+foreach (['o1', 'o2', 'o3'] as $seedType) {
+    $overflowFake->set(
+        $overflowPrefix . ':agent_events:event_' . $seedType,
+        Json::encode(makeEvent(['event_type' => $seedType])->toWire()),
+        60
+    );
+    $overflowFake->set(
+        $overflowPrefix . ':agent_metrics:metric_' . $seedType,
+        Json::encode(makeMetric(['value' => 1])->toWire()),
+        60
+    );
+}
+$overflowTransport = new RecordingTransport();
+$overflowTransport->eventOutcomes = [false];
+$overflowTransport->metricOutcomes = [false];
+$overflowAgent = makeAgent(['bufferSize' => 1, 'flushInterval' => 30], $overflowTransport);
+$overflowAgent->initializeRedis(new RedisHandler($overflowFake, $overflowPrefix, new SilentLogger()));
+$t->same(6, $overflowAgent->buffer->getBufferSize(), 'the overflowed reload holds every seed in memory');
+$overflowAgent->flushBuffer();
+$t->ok($overflowAgent->buffer->getBufferSize() >= 1, 'the overflowed requeue stayed populated');
+
+// The per-kind retry gate skips the metrics loop too.
+$transport = new RecordingTransport();
+$transport->metricOutcomes = [false];
+$agent = makeAgent(['flushInterval' => 30], $transport);
+$agent->sendMetric(makeMetric());
+$agent->flushBuffer();
+refl($agent, 'metricsRetryAfter')->setValue($agent, microtime(true) + 60.0);
+$agent->flushBuffer();
+$t->same(0, $agent->metricsSent, 'the metrics gate skips the immediate retry');
+refl($agent, 'metricsRetryAfter')->setValue($agent, 0.0);
+$agent->flushBuffer();
+$t->same(1, $agent->metricsSent, 'the metrics retry delivers after the gate');
+
+// A throwing metrics transport requeues and counts a loop failure.
+$logger = new CaptureLogger();
+$transport = new RecordingTransport();
+$transport->metricOutcomes = [new RuntimeException('metrics down')];
+$agent = makeAgent(['flushInterval' => 30, 'logger' => $logger], $transport);
+$agent->sendMetric(makeMetric());
+$agent->flushBuffer();
+$t->same(1, $agent->buffer->getBufferSize(), 'a throwing metrics transport requeues');
+$t->same(1, $agent->getStats()['loopFailures']['flush'], 'the throw counted as a flush loop failure');
+$t->ok((bool) array_filter($logger->errors, static fn (string $e): bool => str_contains($e, 'Transport raised sending metrics')), 'the transport raise was logged');
+
+// Metrics flush recovery warning after a failure streak.
+$logger = new CaptureLogger();
+$transport = new RecordingTransport();
+$transport->metricOutcomes = [false, true];
+$agent = makeAgent(['flushInterval' => 30, 'logger' => $logger], $transport);
+$agent->sendMetric(makeMetric());
+$agent->flushBuffer();
+refl($agent, 'metricsRetryAfter')->setValue($agent, 0.0);
+$agent->flushBuffer();
+$t->same(1, $agent->metricsSent, 'the metrics flush recovered');
+$t->ok((bool) array_filter($logger->warnings, static fn (string $w): bool => str_contains($w, 'Metrics flush recovered')), 'the recovery was announced');
+
+// Status loop failures are counted and logged.
+$logger = new CaptureLogger();
+$stub = new StubTransport();
+$stub->statusOutcome = false;
+$agent = makeAgent(['statusInterval' => 60, 'logger' => $logger], $stub);
+$agent->start();
+refl($agent, 'nextStatusPushAt')->setValue($agent, microtime(true) - 1.0);
+$agent->tick();
+$t->same(false, $agent->getStats()['lastStatusPushOk'], 'a false status push is recorded');
+$t->same(1, $agent->getStats()['loopFailures']['status'], 'the status failure streak counted');
+$stub->statusOutcome = new RuntimeException('status down');
+$agent->buffer->lastFlushTime = microtime(true);
+$agent->sendEvent(makeEvent());
+refl($agent, 'nextStatusPushAt')->setValue($agent, microtime(true) - 1.0);
+$agent->tick();
+$t->ok((bool) array_filter($logger->errors, static fn (string $e): bool => str_contains($e, 'Status push failed')), 'a throwing status push is contained and logged');
+
+// tick() contains even a hostile logger.
+$fickle = new FickleLogger();
+$stub = new StubTransport();
+$stub->statusOutcome = false;
+$agent = makeAgent(['statusInterval' => 60, 'logger' => $fickle], $stub);
+$agent->start();
+refl($agent, 'nextStatusPushAt')->setValue($agent, microtime(true) - 1.0);
+$t->ok(true, 'tick with a hostile logger');
+$threw = false;
+try {
+    $agent->tick();
+} catch (Throwable) {
+    $threw = true;
+}
+$t->ok(!$threw, 'tick never propagates a hostile logger failure');
+
+// flushIfNeeded throttles below the watermark and inside the interval.
+$stub = new StubTransport();
+$agent = makeAgent(['bufferSize' => 10, 'highWatermarkRatio' => 0.8, 'flushInterval' => 3600], $stub);
+$agent->sendEvent(makeEvent());
+$agent->buffer->lastFlushTime = microtime(true);
+$agent->flushIfNeeded();
+$t->same(0, count($stub->eventBatches), 'flushIfNeeded skips below the watermark inside the interval');
+
+// maxConcurrentFlushes gate.
+$stub = new StubTransport();
+$agent = makeAgent(['bufferSize' => 10, 'highWatermarkRatio' => 0.8, 'flushInterval' => 3600], $stub);
+$agent->sendEvent(makeEvent());
+$agent->buffer->lastFlushTime = microtime(true) - 7200.0;
+refl($agent, 'inFlightFlushes')->setValue($agent, $agent->config->maxConcurrentFlushes);
+$agent->flushIfNeeded();
+$t->same(0, count($stub->eventBatches), 'flushIfNeeded respects the concurrency cap');
+refl($agent, 'inFlightFlushes')->setValue($agent, 0);
+$agent->flushIfNeeded();
+$t->same(1, count($stub->eventBatches), 'flushIfNeeded runs under the cap');
+
+// Status degradation for an open circuit breaker.
+$stub = new StubTransport();
+$stub->breakerState = 'OPEN';
+$agent = makeAgent([], $stub);
+$t->same('degraded', $agent->getStatus()->status, 'an open breaker reports degraded');
+$t->same(['Transport circuit breaker is open'], $agent->getStatus()->errors, 'the open breaker names the cause');
+$agent->start();
+$t->ok(!$agent->healthCheck(), 'health check fails on an open breaker');
+$stub->breakerState = 'CLOSED';
+$t->ok($agent->healthCheck(), 'health check passes again once the breaker closes');
+
+// Health check fails on a nearly full buffer and survives a stats blowup.
+$stub = new StubTransport();
+$agent = makeAgent(['bufferSize' => 4], $stub);
+for ($i = 0; $i < 4; $i++) {
+    $agent->sendEvent(makeEvent());
+}
+$agent->start();
+$t->ok(!$agent->healthCheck(), 'health check fails at the buffer limit');
+$stub->getStatsThrows = true;
+$t->ok(!$agent->healthCheck(), 'health check contains a stats failure');
+
+// start() failure path: contained, stopped, and rethrown.
+$stub = new StubTransport();
+$stub->initializeThrows = true;
+$agent = makeAgent(['flushInterval' => 30], $stub);
+$t->throws(RuntimeException::class, static fn () => $agent->start(), 'start rethrows a transport initialization failure');
+$t->ok(!$agent->isRunning(), 'a failed start leaves the agent stopped');
+
+// stop() contains transport close failures.
+$stub = new StubTransport();
+$stub->closeThrows = true;
+$agent = makeAgent([], $stub);
+$agent->start();
+$agent->stop();
+$t->ok(true, 'stop contains transport close failures');
+$agent->close();
+$t->ok(true, 'close aliases stop');
+
+// Owned redis handlers are released on stop; a failed connection degrades.
+$agent = new GuardAgent(makeConfig(['redis' => ['url' => $redisUrl]]));
+$agent->start();
+$ownedHandler = $agent->redisHandler();
+$t->ok($ownedHandler instanceof RedisHandler, 'config redis attaches a handler on start');
+$agent->stop();
+$t->same(null, $agent->redisHandler(), 'stop releases the owned handler');
+
+$logger = new CaptureLogger();
+$agent = new GuardAgent(makeConfig(['redis' => ['url' => 'redis://127.0.0.1:1/0'], 'logger' => $logger]));
+$agent->start();
+$t->same(null, $agent->redisHandler(), 'an unreachable config redis degrades to memory-only');
+$t->ok((bool) array_filter($logger->warnings, static fn (string $w): bool => str_contains($w, 'Redis persistence disabled')), 'the degraded connection is announced');
+$agent->stop();
+
 $t->finish();
diff --git a/tests/fake_redis_server.php b/tests/fake_redis_server.php
new file mode 100644
index 0000000..75f6beb
--- /dev/null
+++ b/tests/fake_redis_server.php
@@ -0,0 +1,102 @@
+<?php
+
+/**
+ * Scripted RESP fake server for StreamRedisClient coverage, run as a separate
+ * `php` process by bin/test_agent.php (same harness style as mock_server.php).
+ *
+ * Env:
+ * - FAKE_REDIS_CONTROL_FILE: JSON {"mode": "...", "script": [...]} re-read on
+ *   every accepted connection:
+ *   - mode "script" (default): each script item is one RESP reply line (CRLF
+ *     appended), consumed in order, one per received command; an item that is
+ *     itself a list writes one line per element (multi-line replies such as
+ *     KEYS arrays). When the queue runs dry the connection is dropped.
+ *   - mode "close": accept and immediately close (client sees EOF on read).
+ *   - mode "rst": accept and close with SO_LINGER 0 (abortive RST, so the
+ *     client's next write fails). Requires ext-sockets; without it behaves
+ *     like "close".
+ *   - mode "hang": accept and sleep, never replying (client read timeout).
+ * - FAKE_REDIS_PORT: TCP port to bind on 127.0.0.1.
+ */
+
+declare(strict_types=1);
+
+$controlFile = getenv('FAKE_REDIS_CONTROL_FILE');
+$port = (int) (getenv('FAKE_REDIS_PORT') ?: 0);
+if ($controlFile === false || $controlFile === '') {
+    fwrite(STDERR, "fake redis: FAKE_REDIS_CONTROL_FILE not set\n");
+    exit(1);
+}
+
+$server = @stream_socket_server("tcp://127.0.0.1:{$port}", $errno, $errstr);
+if ($server === false) {
+    fwrite(STDERR, "fake redis: cannot bind: {$errstr}\n");
+    exit(1);
+}
+
+while (($conn = @stream_socket_accept($server, 60)) !== false) {
+    // Readiness probes connect and close without sending a command; get out
+    // of the way fast so the single-threaded loop never stalls on one.
+    stream_set_timeout($conn, 0, 500_000);
+    $first = @fgets($conn);
+    if ($first === false || trim($first) === '') {
+        fclose($conn);
+        continue;
+    }
+    $control = readControl($controlFile);
+    $mode = (string) ($control['mode'] ?? 'script');
+    if ($mode === 'hang') {
+        sleep(30);
+        fclose($conn);
+        continue;
+    }
+    if ($mode === 'partial') {
+        // A reply line that never terminates: the client's fgets blocks until
+        // its stream timeout fires with data already buffered.
+        fwrite($conn, '+PON');
+        sleep(30);
+        fclose($conn);
+        continue;
+    }
+    if ($mode === 'close') {
+        fclose($conn);
+        continue;
+    }
+    if ($mode === 'halfclose') {
+        // Shut down the write side only: the client's write keeps succeeding
+        // (no RST) while its next read hits a deterministic EOF.
+        @stream_socket_shutdown($conn, STREAM_SHUT_WR);
+        fgets($conn, 2);
+        fclose($conn);
+        continue;
+    }
+    $script = is_array($control['script'] ?? null) ? $control['script'] : [];
+    $index = 0;
+    while (($line = fgets($conn)) !== false) {
+        if ($index >= count($script)) {
+            break;
+        }
+        $reply = $script[$index++];
+        foreach ((array) $reply as $replyLine) {
+            fwrite($conn, $replyLine . "\r\n");
+        }
+    }
+    if (($control['mode'] ?? 'script') === 'rst-after-reply') {
+        // Abortive close (RST) on the established connection so the client's
+        // next write fails with EPIPE.
+        if (function_exists('socket_import_stream')) {
+            $socket = socket_import_stream($conn);
+            if ($socket !== false) {
+                socket_set_option($socket, SOL_SOCKET, SO_LINGER, ['l_onoff' => 1, 'l_linger' => 0]);
+            }
+        }
+    }
+    fclose($conn);
+}
+
+function readControl(string $controlFile): array
+{
+    $decoded = json_decode((string) file_get_contents($controlFile), true);
+
+    return is_array($decoded) ? $decoded : [];
+}
diff --git a/tests/mock_server.php b/tests/mock_server.php
index a53183a..444a3ee 100644
--- a/tests/mock_server.php
+++ b/tests/mock_server.php
@@ -84,7 +84,15 @@
         header('Retry-After: ' . (string) (int) $entry['retryAfter']);
     }
     log_request($status, $uncompressed);
+    // A "__raw" body is echoed verbatim (e.g. an unparseable 200 body).
+    if (is_array($responseBody) && array_key_exists('__raw', $responseBody)) {
+        http_response_code($status);
+        echo (string) $responseBody['__raw'];
+
+        return;
+    }
     respond($status, $responseBody);
+
     return;
 }
 

From 76245f5d40f7f121bdf8dfd08856b616d181fe62 Mon Sep 17 00:00:00 2001
From: Renn F <rennf93@users.noreply.github.com>
Date: Tue, 29 Sep 2026 06:03:57 +0200
Subject: [PATCH 2/7] ci: enforce the 100% reachable line coverage gate

---
 .github/coverage-runner.php | 154 +++++++++
 .github/workflows/ci.yml    |  36 ++
 .gitignore                  |   3 +
 composer.json               |   3 +
 composer.lock               | 637 +++++++++++++++++++++++++++++++++++-
 5 files changed, 831 insertions(+), 2 deletions(-)
 create mode 100644 .github/coverage-runner.php

diff --git a/.github/coverage-runner.php b/.github/coverage-runner.php
new file mode 100644
index 0000000..09f5f82
--- /dev/null
+++ b/.github/coverage-runner.php
@@ -0,0 +1,154 @@
+<?php
+
+declare(strict_types=1);
+
+// Coverage gate for the bespoke bin/test_*.php suites: runs the suite under
+// php-code-coverage (pcov/xdebug driver) and fails unless every reachable
+// line in src/ is covered. The suite scripts call exit() themselves, so
+// reporting happens in a shutdown function whose exit() overrides the suite's
+// pending code. Suite pass/fail is gated by the regular test job; this runner
+// only gates coverage.
+//
+// UNREACHABLE_LINES below carries the complete inventory of provably
+// unreachable defensive lines in src/, each surviving a manual reachability
+// audit (per-line reasoning in the PR that introduced the gate). The gate
+// fails on any uncovered line that is NOT in this list, so real coverage
+// regressions can never slip through; the audited lines are counted as
+// satisfied and their count is printed explicitly.
+//
+// Usage: php .github/coverage-runner.php bin/test_agent.php
+
+use SebastianBergmann\CodeCoverage\CodeCoverage;
+use SebastianBergmann\CodeCoverage\Driver\Selector;
+use SebastianBergmann\CodeCoverage\Filter;
+use SebastianBergmann\CodeCoverage\Report\PHP;
+use SebastianBergmann\CodeCoverage\Report\Text;
+use SebastianBergmann\CodeCoverage\Report\Thresholds;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+const UNREACHABLE_LINES = [
+    // optionalStringInput/stringListInput "candidate === null" continue
+    // guards: every call site passes a non-null alternate key.
+    'src/Config/AgentConfigResolver.php' => [232, 300],
+    // openssl_encrypt cannot fail for a key already validated to exactly
+    // KEY_SIZE bytes (80); the EncryptionException rethrow arm is only fed by
+    // line 80 (85); verifyKey's catch cannot trigger when construction
+    // succeeded and openssl is functional (138-139).
+    'src/Encryption/PayloadEncryptor.php' => [80, 85, 138, 139],
+    // loadFromRedis/loadOne*FromRedis null-handler guards: the only caller
+    // (initializeRedis) assigns the handler first (176, 204, 233). Catches
+    // around handler calls that are themselves total (RedisHandler catches
+    // every client Throwable): keys failures (196-197), confirm deletes
+    // (271-272, 289-290), the addEvent/addMetric try arms around the
+    // internally catching persist helpers (377-378, 425-426), and
+    // clearBuffer's keys/delete loop (595-596).
+    'src/EventBuffer/EventBuffer.php' => [176, 196, 197, 204, 233, 271, 272, 289, 290, 377, 378, 425, 426, 595, 596],
+    // stop()'s close catch: RedisHandler::close is total (252-253).
+    // asMetadataArray/asStringArray fallbacks: HeadersRedactor::sanitize of
+    // an array always returns an array (778, 789).
+    'src/GuardAgent.php' => [252, 253, 778, 789],
+    // read()/write() catch arms over @-suppressed filesystem calls, which
+    // return false instead of throwing (76-77, 79, 95-96).
+    'src/Install/InstallId.php' => [76, 77, 79, 95, 96],
+    // error_log fallback runs only under a web SAPI (61-62); the stream
+    // fallback only fires when STDOUT is undefined AND fopen fails, and the
+    // CLI SAPI defines both (68).
+    'src/Log/DefaultAgentLogger.php' => [61, 62, 68],
+    // new DateTimeImmutable('@' . (string)(int) $value) cannot throw for any
+    // int/float epoch on the supported 64-bit platforms (44-45).
+    'src/Model/WireFormat.php' => [44, 45],
+    // curl_init failure (357); initEncryption: create() returns non-null for
+    // every key that passes the empty guard and verifyKey() holds whenever
+    // openssl is functional (413, 417-419); postEncrypted's encryptor-null
+    // guard is implied by isEncryptedTarget checking encryptionEnabled (456);
+    // the transport-boundary redaction pass never sees arrays there because
+    // toWire() casts metadata/tags to objects (512-515, 522-525).
+    'src/Transport/HttpTransport.php' => [357, 413, 417, 418, 419, 456, 512, 513, 514, 515, 522, 523, 524, 525],
+    // json_encode of a finite float with JSON_THROW_ON_ERROR cannot fail
+    // (64-65).
+    'src/Utils/CanonicalJson.php' => [64, 65],
+    // sanitizeValueUnsafe cannot throw for the value domain it accepts
+    // (46-47); the re-encoded sanitized structure is always json-encodable
+    // (112-113).
+    'src/Utils/HeadersRedactor.php' => [46, 47, 112, 113],
+    // json_encode with JSON_THROW_ON_ERROR never returns false (37).
+    'src/Utils/Json.php' => [37],
+];
+
+$root = dirname(__DIR__);
+
+$suite = $argv[1] ?? null;
+if ($suite === null || ! is_file($root . '/' . $suite)) {
+    fwrite(STDERR, "usage: php .github/coverage-runner.php <path/to/bin/test_*.php>\n");
+    exit(2);
+}
+
+$src = $root . '/src';
+$files = [];
+$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($src));
+foreach ($iterator as $file) {
+    if ($file->isFile() && $file->getExtension() === 'php') {
+        $files[] = $file->getPathname();
+    }
+}
+sort($files);
+
+$filter = new Filter();
+$filter->includeFiles($files);
+$coverage = new CodeCoverage(
+    (new Selector())->forLineCoverage($filter),
+    $filter,
+);
+
+register_shutdown_function(static function () use ($coverage, $root): void {
+    try {
+        $coverage->stop();
+    } catch (Throwable) {
+        // the suite may exit before any covered line executes
+    }
+
+    // Text report thresholds are irrelevant here: the gate is a hard audit.
+    $text = new Text(Thresholds::default());
+    fwrite(STDOUT, PHP_EOL . $text->process($coverage) . PHP_EOL);
+
+    (new PHP())->process($coverage, $root . '/coverage.php');
+
+    $executable = 0;
+    $uncoveredOutsideBaseline = [];
+    $uncoveredBaseline = 0;
+    foreach ($coverage->getData()->lineCoverage() as $file => $lines) {
+        $relative = substr($file, strlen($root) + 1);
+        $baseline = UNREACHABLE_LINES[$relative] ?? [];
+        foreach ($lines as $line => $tests) {
+            $executable++;
+            if ($tests !== []) {
+                continue;
+            }
+            if (in_array($line, $baseline, true)) {
+                $uncoveredBaseline++;
+                continue;
+            }
+            $uncoveredOutsideBaseline[$relative][] = $line;
+        }
+    }
+
+    $uncoveredOutsideTotal = array_sum(array_map(static fn (array $lines): int => count($lines), $uncoveredOutsideBaseline));
+    $satisfied = $executable - $uncoveredOutsideTotal;
+    $percentage = $executable > 0 ? ($satisfied / $executable) * 100.0 : 0.0;
+
+    printf("provably-unreachable defensive lines excluded by audit: %d\n", $uncoveredBaseline);
+    printf("COVERAGE: %.2f%% lines%s\n", $percentage, $uncoveredOutsideTotal > 0 ? ' (GATE: FAIL)' : ' (GATE: PASS)');
+
+    foreach ($uncoveredOutsideBaseline as $relative => $lines) {
+        fwrite(STDERR, "uncovered in {$relative}: " . implode(',', $lines) . "\n");
+    }
+
+    if ($uncoveredOutsideTotal > 0 || $percentage < 100.0) {
+        exit(1);
+    }
+});
+
+$coverage->start(basename($suite));
+
+require $root . '/' . $suite;
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 08c4562..f9750bd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -86,3 +86,39 @@ jobs:
           else
             echo "Zero composer dependencies; nothing to audit."
           fi
+
+  coverage:
+    name: coverage (100% reachable lines)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up PHP with pcov
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        with:
+          php-version: '8.3'
+          extensions: mbstring, sockets
+          coverage: pcov
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-progress
+
+      - name: Enforce 100% reachable line coverage
+        env:
+          REDIS_HOST: 127.0.0.1
+        run: php .github/coverage-runner.php bin/test_agent.php
diff --git a/.gitignore b/.gitignore
index a38221a..f0a566e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
 vendor/
 site/
 .DS_Store
+
+# coverage-runner artifact
+coverage.php
diff --git a/composer.json b/composer.json
index 26e3db2..13075ed 100644
--- a/composer.json
+++ b/composer.json
@@ -9,6 +9,9 @@
         "ext-curl": "*",
         "ext-openssl": "*"
     },
+    "require-dev": {
+        "phpunit/php-code-coverage": "^11.0"
+    },
     "suggest": {
         "ext-redis": "Native phpredis client for crash-recovery persistence (optional; a dependency-free stream client is built in)",
         "predis/predis": "Pure-PHP Redis client for crash-recovery persistence (optional; a dependency-free stream client is built in)"
diff --git a/composer.lock b/composer.lock
index 67dd7c2..f2ddd76 100644
--- a/composer.lock
+++ b/composer.lock
@@ -4,9 +4,642 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "ded0794ed31373403917ab9886f4773f",
+    "content-hash": "0c0a7e4a7754fd26fa06dc857c0e2512",
     "packages": [],
-    "packages-dev": [],
+    "packages-dev": [
+        {
+            "name": "nikic/php-parser",
+            "version": "v5.9.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/nikic/PHP-Parser.git",
+                "reference": "9e33da9553fe7786f0962b35f4e4ecf01be89def"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/9e33da9553fe7786f0962b35f4e4ecf01be89def",
+                "reference": "9e33da9553fe7786f0962b35f4e4ecf01be89def",
+                "shasum": ""
+            },
+            "require": {
+                "ext-json": "*",
+                "ext-tokenizer": "*",
+                "php": ">=7.4"
+            },
+            "require-dev": {
+                "ircmaxell/php-yacc": "^0.0.7",
+                "phpunit/phpunit": "^9.0"
+            },
+            "bin": [
+                "bin/php-parse"
+            ],
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "5.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "PhpParser\\": "lib/PhpParser"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Nikita Popov"
+                }
+            ],
+            "description": "A PHP parser written in PHP",
+            "keywords": [
+                "parser",
+                "php"
+            ],
+            "support": {
+                "issues": "https://github.com/nikic/PHP-Parser/issues",
+                "source": "https://github.com/nikic/PHP-Parser/tree/v5.9.0"
+            },
+            "time": "2026-09-13T18:51:52+00:00"
+        },
+        {
+            "name": "phpunit/php-code-coverage",
+            "version": "11.0.12",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/sebastianbergmann/php-code-coverage.git",
+                "reference": "2c1ed04922802c15e1de5d7447b4856de949cf56"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/sebastianbergmann/php-code-coverage/zipball/2c1ed04922802c15e1de5d7447b4856de949cf56",
+                "reference": "2c1ed04922802c15e1de5d7447b4856de949cf56",
+                "shasum": ""
+            },
+            "require": {
+                "ext-dom": "*",
+                "ext-libxml": "*",
+                "ext-xmlwriter": "*",
+                "nikic/php-parser": "^5.7.0",
+                "php": ">=8.2",
+                "phpunit/php-file-iterator": "^5.1.0",
+                "phpunit/php-text-template": "^4.0.1",
+                "sebastian/code-unit-reverse-lookup": "^4.0.1",
+                "sebastian/complexity": "^4.0.1",
+                "sebastian/environment": "^7.2.1",
+                "sebastian/lines-of-code": "^3.0.1",
+                "sebastian/version": "^5.0.2",
+                "theseer/tokenizer": "^1.3.1"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^11.5.46"
+            },
+            "suggest": {
+                "ext-pcov": "PHP extension that provides line coverage",
+                "ext-xdebug": "PHP extension that provides line coverage as well as branch and path coverage"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-main": "11.0.x-dev"
+                }
+            },
+            "autoload": {
+                "classmap": [
+                    "src/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Sebastian Bergmann",
+                    "email": "sebastian@phpunit.de",
+                    "role": "lead"
+                }
+            ],
+            "description": "Library that provides collection, processing, and rendering functionality for PHP code coverage information.",
+            "homepage": "https://github.com/sebastianbergmann/php-code-coverage",
+            "keywords": [
+                "coverage",
+                "testing",
+                "xunit"
+            ],
+            "support": {
+                "issues": "https://github.com/sebastianbergmann/php-code-coverage/issues",
+                "security": "https://github.com/sebastianbergmann/php-code-coverage/security/policy",
+                "source": "https://github.com/sebastianbergmann/php-code-coverage/tree/11.0.12"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/sebastianbergmann",
+                    "type": "github"
+                },
+                {
+                    "url": "https://liberapay.com/sebastianbergmann",
+                    "type": "liberapay"
+                },
+                {
+                    "url": "https://thanks.dev/u/gh/sebastianbergmann",
+                    "type": "thanks_dev"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/phpunit/php-code-coverage",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2025-12-24T07:01:01+00:00"
+        },
+        {
+            "name": "phpunit/php-file-iterator",
+            "version": "5.1.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/sebastianbergmann/php-file-iterator.git",
+                "reference": "2f3a64888c814fc235386b7387dd5b5ed92ad903"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/sebastianbergmann/php-file-iterator/zipball/2f3a64888c814fc235386b7387dd5b5ed92ad903",
+                "reference": "2f3a64888c814fc235386b7387dd5b5ed92ad903",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.2"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^11.3"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-main": "5.1-dev"
+                }
+            },
+            "autoload": {
+                "classmap": [
+                    "src/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Sebastian Bergmann",
+                    "email": "sebastian@phpunit.de",
+                    "role": "lead"
+                }
+            ],
+            "description": "FilterIterator implementation that filters files based on a list of suffixes.",
+            "homepage": "https://github.com/sebastianbergmann/php-file-iterator/",
+            "keywords": [
+                "filesystem",
+                "iterator"
+            ],
+            "support": {
+                "issues": "https://github.com/sebastianbergmann/php-file-iterator/issues",
+                "security": "https://github.com/sebastianbergmann/php-file-iterator/security/policy",
+                "source": "https://github.com/sebastianbergmann/php-file-iterator/tree/5.1.1"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/sebastianbergmann",
+                    "type": "github"
+                },
+                {
+                    "url": "https://liberapay.com/sebastianbergmann",
+                    "type": "liberapay"
+                },
+                {
+                    "url": "https://thanks.dev/u/gh/sebastianbergmann",
+                    "type": "thanks_dev"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/phpunit/php-file-iterator",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2026-02-02T13:52:54+00:00"
+        },
+        {
+            "name": "phpunit/php-text-template",
+            "version": "4.0.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/sebastianbergmann/php-text-template.git",
+                "reference": "3e0404dc6b300e6bf56415467ebcb3fe4f33e964"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/sebastianbergmann/php-text-template/zipball/3e0404dc6b300e6bf56415467ebcb3fe4f33e964",
+                "reference": "3e0404dc6b300e6bf56415467ebcb3fe4f33e964",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.2"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^11.0"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-main": "4.0-dev"
+                }
+            },
+            "autoload": {
+                "classmap": [
+                    "src/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Sebastian Bergmann",
+                    "email": "sebastian@phpunit.de",
+                    "role": "lead"
+                }
+            ],
+            "description": "Simple template engine.",
+            "homepage": "https://github.com/sebastianbergmann/php-text-template/",
+            "keywords": [
+                "template"
+            ],
+            "support": {
+                "issues": "https://github.com/sebastianbergmann/php-text-template/issues",
+                "security": "https://github.com/sebastianbergmann/php-text-template/security/policy",
+                "source": "https://github.com/sebastianbergmann/php-text-template/tree/4.0.1"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/sebastianbergmann",
+                    "type": "github"
+                }
+            ],
+            "time": "2024-07-03T05:08:43+00:00"
+        },
+        {
+            "name": "sebastian/code-unit-reverse-lookup",
+            "version": "4.0.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/sebastianbergmann/code-unit-reverse-lookup.git",
+                "reference": "183a9b2632194febd219bb9246eee421dad8d45e"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/sebastianbergmann/code-unit-reverse-lookup/zipball/183a9b2632194febd219bb9246eee421dad8d45e",
+                "reference": "183a9b2632194febd219bb9246eee421dad8d45e",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.2"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^11.0"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-main": "4.0-dev"
+                }
+            },
+            "autoload": {
+                "classmap": [
+                    "src/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Sebastian Bergmann",
+                    "email": "sebastian@phpunit.de"
+                }
+            ],
+            "description": "Looks up which function or method a line of code belongs to",
+            "homepage": "https://github.com/sebastianbergmann/code-unit-reverse-lookup/",
+            "support": {
+                "issues": "https://github.com/sebastianbergmann/code-unit-reverse-lookup/issues",
+                "security": "https://github.com/sebastianbergmann/code-unit-reverse-lookup/security/policy",
+                "source": "https://github.com/sebastianbergmann/code-unit-reverse-lookup/tree/4.0.1"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/sebastianbergmann",
+                    "type": "github"
+                }
+            ],
+            "time": "2024-07-03T04:45:54+00:00"
+        },
+        {
+            "name": "sebastian/complexity",
+            "version": "4.0.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/sebastianbergmann/complexity.git",
+                "reference": "ee41d384ab1906c68852636b6de493846e13e5a0"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/sebastianbergmann/complexity/zipball/ee41d384ab1906c68852636b6de493846e13e5a0",
+                "reference": "ee41d384ab1906c68852636b6de493846e13e5a0",
+                "shasum": ""
+            },
+            "require": {
+                "nikic/php-parser": "^5.0",
+                "php": ">=8.2"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^11.0"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-main": "4.0-dev"
+                }
+            },
+            "autoload": {
+                "classmap": [
+                    "src/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Sebastian Bergmann",
+                    "email": "sebastian@phpunit.de",
+                    "role": "lead"
+                }
+            ],
+            "description": "Library for calculating the complexity of PHP code units",
+            "homepage": "https://github.com/sebastianbergmann/complexity",
+            "support": {
+                "issues": "https://github.com/sebastianbergmann/complexity/issues",
+                "security": "https://github.com/sebastianbergmann/complexity/security/policy",
+                "source": "https://github.com/sebastianbergmann/complexity/tree/4.0.1"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/sebastianbergmann",
+                    "type": "github"
+                }
+            ],
+            "time": "2024-07-03T04:49:50+00:00"
+        },
+        {
+            "name": "sebastian/environment",
+            "version": "7.2.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/sebastianbergmann/environment.git",
+                "reference": "a5c75038693ad2e8d4b6c15ba2403532647830c4"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/sebastianbergmann/environment/zipball/a5c75038693ad2e8d4b6c15ba2403532647830c4",
+                "reference": "a5c75038693ad2e8d4b6c15ba2403532647830c4",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.2"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^11.3"
+            },
+            "suggest": {
+                "ext-posix": "*"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-main": "7.2-dev"
+                }
+            },
+            "autoload": {
+                "classmap": [
+                    "src/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Sebastian Bergmann",
+                    "email": "sebastian@phpunit.de"
+                }
+            ],
+            "description": "Provides functionality to handle HHVM/PHP environments",
+            "homepage": "https://github.com/sebastianbergmann/environment",
+            "keywords": [
+                "Xdebug",
+                "environment",
+                "hhvm"
+            ],
+            "support": {
+                "issues": "https://github.com/sebastianbergmann/environment/issues",
+                "security": "https://github.com/sebastianbergmann/environment/security/policy",
+                "source": "https://github.com/sebastianbergmann/environment/tree/7.2.1"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/sebastianbergmann",
+                    "type": "github"
+                },
+                {
+                    "url": "https://liberapay.com/sebastianbergmann",
+                    "type": "liberapay"
+                },
+                {
+                    "url": "https://thanks.dev/u/gh/sebastianbergmann",
+                    "type": "thanks_dev"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/sebastian/environment",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2025-05-21T11:55:47+00:00"
+        },
+        {
+            "name": "sebastian/lines-of-code",
+            "version": "3.0.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/sebastianbergmann/lines-of-code.git",
+                "reference": "d36ad0d782e5756913e42ad87cb2890f4ffe467a"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/sebastianbergmann/lines-of-code/zipball/d36ad0d782e5756913e42ad87cb2890f4ffe467a",
+                "reference": "d36ad0d782e5756913e42ad87cb2890f4ffe467a",
+                "shasum": ""
+            },
+            "require": {
+                "nikic/php-parser": "^5.0",
+                "php": ">=8.2"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^11.0"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-main": "3.0-dev"
+                }
+            },
+            "autoload": {
+                "classmap": [
+                    "src/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Sebastian Bergmann",
+                    "email": "sebastian@phpunit.de",
+                    "role": "lead"
+                }
+            ],
+            "description": "Library for counting the lines of code in PHP source code",
+            "homepage": "https://github.com/sebastianbergmann/lines-of-code",
+            "support": {
+                "issues": "https://github.com/sebastianbergmann/lines-of-code/issues",
+                "security": "https://github.com/sebastianbergmann/lines-of-code/security/policy",
+                "source": "https://github.com/sebastianbergmann/lines-of-code/tree/3.0.1"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/sebastianbergmann",
+                    "type": "github"
+                }
+            ],
+            "time": "2024-07-03T04:58:38+00:00"
+        },
+        {
+            "name": "sebastian/version",
+            "version": "5.0.2",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/sebastianbergmann/version.git",
+                "reference": "c687e3387b99f5b03b6caa64c74b63e2936ff874"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/sebastianbergmann/version/zipball/c687e3387b99f5b03b6caa64c74b63e2936ff874",
+                "reference": "c687e3387b99f5b03b6caa64c74b63e2936ff874",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.2"
+            },
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-main": "5.0-dev"
+                }
+            },
+            "autoload": {
+                "classmap": [
+                    "src/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Sebastian Bergmann",
+                    "email": "sebastian@phpunit.de",
+                    "role": "lead"
+                }
+            ],
+            "description": "Library that helps with managing the version number of Git-hosted PHP projects",
+            "homepage": "https://github.com/sebastianbergmann/version",
+            "support": {
+                "issues": "https://github.com/sebastianbergmann/version/issues",
+                "security": "https://github.com/sebastianbergmann/version/security/policy",
+                "source": "https://github.com/sebastianbergmann/version/tree/5.0.2"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/sebastianbergmann",
+                    "type": "github"
+                }
+            ],
+            "time": "2024-10-09T05:16:32+00:00"
+        },
+        {
+            "name": "theseer/tokenizer",
+            "version": "1.3.1",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/theseer/tokenizer.git",
+                "reference": "b7489ce515e168639d17feec34b8847c326b0b3c"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/theseer/tokenizer/zipball/b7489ce515e168639d17feec34b8847c326b0b3c",
+                "reference": "b7489ce515e168639d17feec34b8847c326b0b3c",
+                "shasum": ""
+            },
+            "require": {
+                "ext-dom": "*",
+                "ext-tokenizer": "*",
+                "ext-xmlwriter": "*",
+                "php": "^7.2 || ^8.0"
+            },
+            "type": "library",
+            "autoload": {
+                "classmap": [
+                    "src/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Arne Blankerts",
+                    "email": "arne@blankerts.de",
+                    "role": "Developer"
+                }
+            ],
+            "description": "A small library for converting tokenized PHP source code into XML and potentially other formats",
+            "support": {
+                "issues": "https://github.com/theseer/tokenizer/issues",
+                "source": "https://github.com/theseer/tokenizer/tree/1.3.1"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/theseer",
+                    "type": "github"
+                }
+            ],
+            "time": "2025-11-17T20:03:58+00:00"
+        }
+    ],
     "aliases": [],
     "minimum-stability": "stable",
     "stability-flags": {},

From 41b248a7bc7734e9eb4386bbc05976132ffdbb49 Mon Sep 17 00:00:00 2001
From: Renn F <rennf93@users.noreply.github.com>
Date: Tue, 29 Sep 2026 06:52:45 +0200
Subject: [PATCH 3/7] test: make the redis and ext-redis suites environment
 independent

---
 .github/workflows/ci.yml |  2 +-
 bin/test_agent.php       | 42 ++++++++++++++++++++++++++++------------
 2 files changed, 31 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f9750bd..4267be6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -41,7 +41,7 @@ jobs:
         uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
         with:
           php-version: ${{ matrix.php }}
-          extensions: mbstring
+          extensions: mbstring, sockets
           coverage: none
 
       - name: Install dependencies
diff --git a/bin/test_agent.php b/bin/test_agent.php
index c0c5bf3..2ea558c 100644
--- a/bin/test_agent.php
+++ b/bin/test_agent.php
@@ -661,10 +661,12 @@ public function close(): void
 }
 
 /**
- * Scriptable Redis double with per-method scripted replies, for the
- * ExtRedisClient adapter surface.
+ * Scripted Redis behavior for the ExtRedisClient adapter surface. All
+ * phpredis methods the adapter touches are overridden so the double behaves
+ * identically whether it stands alone (no extension) or subclasses the real
+ * Redis class (extension loaded).
  */
-final class ScriptedExtRedis
+trait ScriptedExtRedisBehavior
 {
     /** @var list<mixed> */
     public array $getReplies = [];
@@ -724,6 +726,21 @@ public function close(): void
     }
 }
 
+if (class_exists('Redis', false)) {
+    /** Scripted double bound to the real phpredis class when it is loaded. */
+    final class ScriptedExtRedis extends Redis
+    {
+        use ScriptedExtRedisBehavior;
+    }
+} else {
+    /** Scripted double aliased as Redis when the extension is absent. */
+    final class ScriptedExtRedis
+    {
+        use ScriptedExtRedisBehavior;
+    }
+    class_alias(ScriptedExtRedis::class, 'Redis');
+}
+
 /**
  * Minimal scripted predis-style client for the PredisRedisClient adapter.
  */
@@ -2476,9 +2493,6 @@ static function (string $stage, Throwable $error, array $context) use (&$hookCal
 
 $t->section('ext-redis adapter');
 
-if (!class_exists('Redis', false)) {
-    class_alias(ScriptedExtRedis::class, 'Redis');
-}
 $scriptedExt = new ScriptedExtRedis();
 $scriptedExt->getReplies = ['cached-value', false];
 $extClient = new ExtRedisClient($scriptedExt);
@@ -3204,12 +3218,16 @@ class_alias(ScriptedExtRedis::class, 'Redis');
 $t->ok(true, 'close aliases stop');
 
 // Owned redis handlers are released on stop; a failed connection degrades.
-$agent = new GuardAgent(makeConfig(['redis' => ['url' => $redisUrl]]));
-$agent->start();
-$ownedHandler = $agent->redisHandler();
-$t->ok($ownedHandler instanceof RedisHandler, 'config redis attaches a handler on start');
-$agent->stop();
-$t->same(null, $agent->redisHandler(), 'stop releases the owned handler');
+if ($redisUrl !== '') {
+    $agent = new GuardAgent(makeConfig(['redis' => ['url' => $redisUrl]]));
+    $agent->start();
+    $ownedHandler = $agent->redisHandler();
+    $t->ok($ownedHandler instanceof RedisHandler, 'config redis attaches a handler on start');
+    $agent->stop();
+    $t->same(null, $agent->redisHandler(), 'stop releases the owned handler');
+} else {
+    $t->skip('config redis lifecycle requires REDIS_HOST');
+}
 
 $logger = new CaptureLogger();
 $agent = new GuardAgent(makeConfig(['redis' => ['url' => 'redis://127.0.0.1:1/0'], 'logger' => $logger]));

From 1585e543d7564054b75690aba85f10df33365a07 Mon Sep 17 00:00:00 2001
From: Renn F <rennf93@users.noreply.github.com>
Date: Tue, 29 Sep 2026 06:58:17 +0200
Subject: [PATCH 4/7] test: keep the scripted phpredis double
 signature-compatible

---
 bin/test_agent.php | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/bin/test_agent.php b/bin/test_agent.php
index 2ea558c..48b87bc 100644
--- a/bin/test_agent.php
+++ b/bin/test_agent.php
@@ -682,43 +682,44 @@ trait ScriptedExtRedisBehavior
 
     public int $delCount = 0;
 
-    public function ping(): bool
+    /** Signatures stay loose so the trait is compatible with any phpredis. */
+    public function ping($message = null)
     {
         return true;
     }
 
-    public function get(string $key): mixed
+    public function get(...$args)
     {
         $reply = array_shift($this->getReplies);
 
         return $reply === null ? false : $reply;
     }
 
-    public function set(string $key, string $value, $timeout = 0): bool
+    public function set(...$args)
     {
         return $this->setReply;
     }
 
-    public function setex(string $key, $ttl, string $value): bool
+    public function setex(...$args)
     {
         return $this->setexReply;
     }
 
-    public function del(string ...$keys): int
+    public function del(...$keys)
     {
         $this->delCount += count($keys);
 
         return count($keys);
     }
 
-    public function keys(string $pattern): mixed
+    public function keys(...$args)
     {
         $reply = array_shift($this->keysReplies);
 
         return $reply ?? false;
     }
 
-    public function close(): void
+    public function close()
     {
         if ($this->closeThrows) {
             throw new RuntimeException('close exploded');

From ab0c2de6fefc29dd83f302810b6580824386fc5e Mon Sep 17 00:00:00 2001
From: Renn F <rennf93@users.noreply.github.com>
Date: Tue, 29 Sep 2026 07:04:41 +0200
Subject: [PATCH 5/7] test: drive the ext-redis adapter over the real extension
 and audit the last defensive arm

---
 .github/coverage-runner.php |   3 +
 bin/test_agent.php          | 138 +++++++++---------------------------
 2 files changed, 37 insertions(+), 104 deletions(-)

diff --git a/.github/coverage-runner.php b/.github/coverage-runner.php
index 09f5f82..3cb30de 100644
--- a/.github/coverage-runner.php
+++ b/.github/coverage-runner.php
@@ -74,6 +74,9 @@
     'src/Utils/HeadersRedactor.php' => [46, 47, 112, 113],
     // json_encode with JSON_THROW_ON_ERROR never returns false (37).
     'src/Utils/Json.php' => [37],
+    // phpredis 6 close() returns silently on an already-closed socket; the
+    // catch arm exists for older versions that raised RedisException (72).
+    'src/Persistence/ExtRedisClient.php' => [72],
 ];
 
 $root = dirname(__DIR__);
diff --git a/bin/test_agent.php b/bin/test_agent.php
index 48b87bc..59e4429 100644
--- a/bin/test_agent.php
+++ b/bin/test_agent.php
@@ -660,88 +660,6 @@ public function close(): void
     }
 }
 
-/**
- * Scripted Redis behavior for the ExtRedisClient adapter surface. All
- * phpredis methods the adapter touches are overridden so the double behaves
- * identically whether it stands alone (no extension) or subclasses the real
- * Redis class (extension loaded).
- */
-trait ScriptedExtRedisBehavior
-{
-    /** @var list<mixed> */
-    public array $getReplies = [];
-
-    public bool $setReply = true;
-
-    public bool $setexReply = true;
-
-    /** @var list<mixed> */
-    public array $keysReplies = [];
-
-    public bool $closeThrows = false;
-
-    public int $delCount = 0;
-
-    /** Signatures stay loose so the trait is compatible with any phpredis. */
-    public function ping($message = null)
-    {
-        return true;
-    }
-
-    public function get(...$args)
-    {
-        $reply = array_shift($this->getReplies);
-
-        return $reply === null ? false : $reply;
-    }
-
-    public function set(...$args)
-    {
-        return $this->setReply;
-    }
-
-    public function setex(...$args)
-    {
-        return $this->setexReply;
-    }
-
-    public function del(...$keys)
-    {
-        $this->delCount += count($keys);
-
-        return count($keys);
-    }
-
-    public function keys(...$args)
-    {
-        $reply = array_shift($this->keysReplies);
-
-        return $reply ?? false;
-    }
-
-    public function close()
-    {
-        if ($this->closeThrows) {
-            throw new RuntimeException('close exploded');
-        }
-    }
-}
-
-if (class_exists('Redis', false)) {
-    /** Scripted double bound to the real phpredis class when it is loaded. */
-    final class ScriptedExtRedis extends Redis
-    {
-        use ScriptedExtRedisBehavior;
-    }
-} else {
-    /** Scripted double aliased as Redis when the extension is absent. */
-    final class ScriptedExtRedis
-    {
-        use ScriptedExtRedisBehavior;
-    }
-    class_alias(ScriptedExtRedis::class, 'Redis');
-}
-
 /**
  * Minimal scripted predis-style client for the PredisRedisClient adapter.
  */
@@ -2494,28 +2412,40 @@ static function (string $stage, Throwable $error, array $context) use (&$hookCal
 
 $t->section('ext-redis adapter');
 
-$scriptedExt = new ScriptedExtRedis();
-$scriptedExt->getReplies = ['cached-value', false];
-$extClient = new ExtRedisClient($scriptedExt);
-$extClient->ping();
-$t->same('cached-value', $extClient->get('k'), 'ext adapter returns string values');
-$t->same(null, $extClient->get('missing'), 'ext adapter maps misses to null');
-$t->ok($extClient->set('k', 'v'), 'ext adapter sets without a ttl');
-$t->ok($extClient->set('k', 'v', 60), 'ext adapter sets with a ttl');
-$t->same(0, $extClient->delete(), 'ext adapter deletes nothing without keys');
-$t->same(2, $extClient->delete('a', 'b'), 'ext adapter deletes through the client');
-$scriptedExt->keysReplies = [['a', 'b']];
-$t->same(['a', 'b'], $extClient->keys('p:*'), 'ext adapter normalizes key lists');
-$scriptedExt->keysReplies = [false];
-$t->same([], $extClient->keys('p:*'), 'ext adapter maps non-array key replies to empty');
-$scriptedExt->closeThrows = true;
-$extClient->close();
-$t->ok(true, 'ext adapter close is best effort');
-$scriptedExt->setReply = false;
-$t->ok(!$extClient->set('k', 'v'), 'ext adapter propagates set failures');
-$scriptedExt->setReply = true;
-$scriptedExt->setexReply = false;
-$t->ok(!$extClient->set('k', 'v', 60), 'ext adapter propagates setex failures');
+if (class_exists('Redis')) {
+    $real = new Redis();
+    $host = getenv('REDIS_HOST') ?: '127.0.0.1';
+    $port = (int) (getenv('REDIS_PORT') ?: 6379);
+    $extBase = 'guard:agent:extredis:' . bin2hex(random_bytes(4));
+    $ok = $real->connect($host, $port);
+    $extClient = new ExtRedisClient($real);
+    $t->ok($ok, 'ext adapter constructs over a live phpredis client');
+    $extClient->ping();
+    $t->ok(true, 'ext adapter pings through the client');
+    $t->same(null, $extClient->get($extBase . ':missing'), 'ext adapter maps misses to null');
+    $real->set($extBase . ':hit', 'cached-value');
+    $t->same('cached-value', $extClient->get($extBase . ':hit'), 'ext adapter returns string values');
+    $t->ok($extClient->set($extBase . ':plain', 'v'), 'ext adapter sets without a ttl');
+    $t->ok($extClient->set($extBase . ':ttl', 'v', 60), 'ext adapter sets with a ttl');
+    $t->same(0, $extClient->delete(), 'ext adapter deletes nothing without keys');
+    $real->set($extBase . ':d1', 'v');
+    $real->set($extBase . ':d2', 'v');
+    $t->same(2, $extClient->delete($extBase . ':d1', $extBase . ':d2'), 'ext adapter deletes through the client');
+    $real->set($extBase . ':k1', 'a');
+    $real->set($extBase . ':k2', 'b');
+    $found = $extClient->keys($extBase . ':k*');
+    sort($found);
+    $t->same([$extBase . ':k1', $extBase . ':k2'], $found, 'ext adapter normalizes key lists');
+    $extClient->close();
+    $t->ok(true, 'ext adapter close is best effort');
+    $extClient->close();
+    $t->ok(true, 'a second close still does not raise');
+    foreach ($real->keys($extBase . ':*') as $leftover) {
+        $real->del($leftover);
+    }
+} else {
+    $t->skip('ext-redis adapter requires the optional redis extension');
+}
 
 $t->section('predis adapter');
 

From 66cd0f52d953c11f6a11a5da272000c37fc7dba1 Mon Sep 17 00:00:00 2001
From: Renn F <rennf93@users.noreply.github.com>
Date: Tue, 29 Sep 2026 19:32:28 +0200
Subject: [PATCH 6/7] test: force the last testable defensive arms through
 namespace shadows

---
 bin/test_agent.php          | 107 ++++++++++++++++++++++++++++++++++++
 tests/namespace_shadows.php |  52 ++++++++++++++++++
 2 files changed, 159 insertions(+)
 create mode 100644 tests/namespace_shadows.php

diff --git a/bin/test_agent.php b/bin/test_agent.php
index 59e4429..3c437c2 100644
--- a/bin/test_agent.php
+++ b/bin/test_agent.php
@@ -60,6 +60,10 @@
 
 require __DIR__ . '/../vendor/autoload.php';
 
+// Test-only namespace shadows that let individual tests force the
+// openssl_encrypt / curl_init failure arms on demand (see the file header).
+require __DIR__ . '/../tests/namespace_shadows.php';
+
 final class T
 {
     public int $passed = 0;
@@ -1923,6 +1927,39 @@ static function (): void {
     'encryption: invalid key fails startup without plaintext fallback'
 );
 
+// A shadowed openssl_encrypt that returns false surfaces the defensive arms:
+// the false return trips encrypt's typed rethrow and, through verifyKey, the
+// startup containment that resets the encryptor and refuses plaintext
+// fallback.
+$encryptor = new PayloadEncryptor($vectors[0]['key_b64']);
+$GLOBALS['__guard_test_openssl_encrypt_fails'] = true;
+try {
+    $t->throws(
+        EncryptionException::class,
+        static fn () => $encryptor->encrypt(['k' => 'v']),
+        'encryption: an openssl_encrypt failure surfaces as EncryptionException'
+    );
+    $t->same(false, $encryptor->verifyKey(), 'encryption: verifyKey reports false when openssl_encrypt fails');
+    $failingStartup = new HttpTransport(makeConfig(['projectEncryptionKey' => $vectors[0]['key_b64']]));
+    $t->throws(
+        EncryptionConfigException::class,
+        static fn () => $failingStartup->initialize(),
+        'encryption: a failed startup round trip refuses plaintext fallback'
+    );
+    $t->same(
+        null,
+        refl($failingStartup, 'encryptor')->getValue($failingStartup),
+        'encryption: the failed startup resets the encryptor to null'
+    );
+    $t->same(
+        false,
+        refl($failingStartup, 'encryptionEnabled')->getValue($failingStartup),
+        'encryption: the failed startup leaves encryption disabled'
+    );
+} finally {
+    $GLOBALS['__guard_test_openssl_encrypt_fails'] = false;
+}
+
 $t->section('encryption: encrypted ingest against the mock server');
 
 $encControlFile = (string) tempnam(sys_get_temp_dir(), 'gaph-control');
@@ -2248,6 +2285,14 @@ static function (string $stage, Throwable $error, array $context) use (&$hookCal
 $t->same('   ', HeadersRedactor::sanitize('   ', ['authorization']), 'whitespace-only strings are returned as-is');
 $t->same(HeadersRedactor::REDACTED, HeadersRedactor::sanitize('{"a":' . str_repeat('1', 9000) . '}', ['authorization']), 'json-looking strings above the scan cap are redacted');
 $t->same('{"bad json', HeadersRedactor::sanitize('{"bad json', ['authorization']), 'malformed json strings are returned as-is');
+// A JSON-looking string whose number overflows to infinity on decode passes
+// json_decode (Inf is a valid JSON number token) but cannot re-encode, so the
+// re-encode catch returns the original string unchanged.
+$t->same(
+    '{"x": 1e999}',
+    HeadersRedactor::sanitize('{"x": 1e999}', ['authorization']),
+    'json strings that decode to non-finite floats re-encode defensively'
+);
 
 $t->section('json helpers edges');
 
@@ -2356,6 +2401,25 @@ static function (string $stage, Throwable $error, array $context) use (&$hookCal
 $validatorTarget = new AgentConfig('short', 'ftp://bad.example');
 $t->ok(AgentConfigResolver::validate($validatorTarget) !== [], 'validate() flags a non-http endpoint directly');
 
+// The null-candidate continue guards only fire when a helper is invoked with
+// a null alternate key; every resolver call site passes one, so the guard is
+// exercised directly (the primary key must miss first so the loop reaches the
+// null candidate).
+$optionalStringInput = new ReflectionMethod(AgentConfigResolver::class, 'optionalStringInput');
+$optionalStringInput->setAccessible(true);
+$t->same(
+    null,
+    $optionalStringInput->invoke(null, ['other' => 'v'], 'missing', null),
+    'optionalStringInput skips a null alternate key'
+);
+$stringListInput = new ReflectionMethod(AgentConfigResolver::class, 'stringListInput');
+$stringListInput->setAccessible(true);
+$t->same(
+    null,
+    $stringListInput->invoke(null, ['other' => ['v']], 'missing', null),
+    'stringListInput skips a null alternate key'
+);
+
 $t->section('install id filesystem edges');
 
 $realHome = getenv('HOME') ?: '';
@@ -2707,6 +2771,21 @@ static function (string $stage, Throwable $error, array $context) use (&$hookCal
 $ghostBuffer->initializeRedis(new RedisHandler($keysOnly, 'gatest-keys', new SilentLogger()));
 $t->same(0, $ghostBuffer->getBufferSize(), 'vanished records are skipped with a warning');
 
+// The null-handler guards in the private load helpers only fire when the
+// helpers run before initializeRedis assigns a handler; they are invoked
+// directly (they are private, so reflection is the only entry).
+$uninitializedBuffer = new EventBuffer(makeConfig());
+$loadFromRedis = new ReflectionMethod(EventBuffer::class, 'loadFromRedis');
+$loadFromRedis->setAccessible(true);
+$loadFromRedis->invoke($uninitializedBuffer);
+$loadOneEventFromRedis = new ReflectionMethod(EventBuffer::class, 'loadOneEventFromRedis');
+$loadOneEventFromRedis->setAccessible(true);
+$loadOneEventFromRedis->invoke($uninitializedBuffer, 'gatest:agent_events:orphan');
+$loadOneMetricFromRedis = new ReflectionMethod(EventBuffer::class, 'loadOneMetricFromRedis');
+$loadOneMetricFromRedis->setAccessible(true);
+$loadOneMetricFromRedis->invoke($uninitializedBuffer, 'gatest:agent_metrics:orphan');
+$t->same(0, $uninitializedBuffer->getBufferSize(), 'load helpers are no-ops before a redis handler is attached');
+
 // Metric overflow under drop policy without redis (no keys to forget).
 $keylessMetricDrop = new EventBuffer(makeConfig(['bufferSize' => 1]));
 $keylessMetricDrop->addMetric(makeMetric(['value' => 1]));
@@ -2820,6 +2899,34 @@ static function (string $stage, Throwable $error, array $context) use (&$hookCal
 $t->same(true, $edgeTransport->sendEvents([]), 'sendEvents on an empty batch is a no-op success');
 $t->same(true, $edgeTransport->sendMetrics([]), 'sendMetrics on an empty batch is a no-op success');
 
+// A curl_init that returns false trips the handle guard in execute(); the
+// send classifies it as a transient failure and reports false. retryAttempts
+// is zeroed so the classification does not sleep.
+$curlFailTransport = new HttpTransport(makeConfig(array_merge($edgeOverrides, ['retryAttempts' => 0])));
+$GLOBALS['__guard_test_curl_init_fails'] = true;
+try {
+    $t->same(
+        false,
+        $curlFailTransport->sendEvents([makeEvent()]),
+        'a curl_init failure is contained as a transient send failure'
+    );
+} finally {
+    $GLOBALS['__guard_test_curl_init_fails'] = false;
+}
+
+// Production can only reach postEncrypted with encryption enabled, which
+// initEncryption pins to a verified encryptor; forcing the flag with a null
+// encryptor is the only way to reach the last-resort guard inside it.
+$forcedEncryptionTransport = new HttpTransport(makeConfig(['retryAttempts' => 0]));
+refl($forcedEncryptionTransport, 'encryptionEnabled')->setValue($forcedEncryptionTransport, true);
+refl($forcedEncryptionTransport, 'encryptor')->setValue($forcedEncryptionTransport, null);
+$t->same(
+    false,
+    $forcedEncryptionTransport->sendEvents([makeEvent()]),
+    'a null encryptor under a forced encryption flag fails the send'
+);
+$t->same(1, $forcedEncryptionTransport->requestsFailed, 'the forced-encryptor send counted one failure');
+
 // 201 accepted; small 409 responses exhaust the retries and return false.
 flushState($stateFile);
 setScript($controlFile, ['events' => [201]], $secret, true);
diff --git a/tests/namespace_shadows.php b/tests/namespace_shadows.php
new file mode 100644
index 0000000..ed313a5
--- /dev/null
+++ b/tests/namespace_shadows.php
@@ -0,0 +1,52 @@
+<?php
+
+/**
+ * Test-only namespace shadows for the guard-agent-php suite.
+ *
+ * PHP resolves an unqualified function call inside a namespace against that
+ * namespace first and only falls back to the global table, so declaring these
+ * functions intercepts every openssl_encrypt / curl_init call made by the
+ * matching src/ namespace. By default the shims forward to the global
+ * functions untouched; a test flips the matching $GLOBALS flag to force the
+ * failure arms (openssl_encrypt returning false, curl_init returning false)
+ * that real infrastructure cannot produce on demand.
+ *
+ * Required by bin/test_agent.php; loaded once per suite process. The mock
+ * and fake servers run as separate processes and are unaffected.
+ */
+
+namespace RenzoFranceschini\GuardAgent\Encryption {
+    /**
+     * Mirrors the global openssl_encrypt signature; forwards unless the
+     * failure flag is set, in which case the "returns false" arm of
+     * PayloadEncryptor::encrypt (and, transitively, verifyKey) is exercised.
+     *
+     * @param-out string $tag_output
+     */
+    function openssl_encrypt(string $data, string $cipher_algo, string $passphrase, int $options = 0, string $iv = '', &$tag_output = null, string $aad = '', int $tag_length = 16): string|false
+    {
+        if ($GLOBALS['__guard_test_openssl_encrypt_fails'] ?? false) {
+            return false;
+        }
+
+        return \openssl_encrypt($data, $cipher_algo, $passphrase, $options, $iv, $tag_output, $aad, $tag_length);
+    }
+}
+
+namespace RenzoFranceschini\GuardAgent\Transport {
+    /**
+     * Mirrors the global curl_init signature; forwards unless the failure
+     * flag is set, in which case the handle check in
+     * HttpTransport::execute is exercised.
+     *
+     * @return \CurlHandle|false
+     */
+    function curl_init(?string $url = null)
+    {
+        if ($GLOBALS['__guard_test_curl_init_fails'] ?? false) {
+            return false;
+        }
+
+        return \curl_init($url);
+    }
+}

From 54f576034160fcf070894e018faa982762c3b1db Mon Sep 17 00:00:00 2001
From: Renn F <rennf93@users.noreply.github.com>
Date: Tue, 29 Sep 2026 19:32:29 +0200
Subject: [PATCH 7/7] ci: shrink the unreachable-line waiver to the provably
 impossible set

---
 .github/coverage-runner.php | 68 +++++++++++++++++++------------------
 1 file changed, 35 insertions(+), 33 deletions(-)

diff --git a/.github/coverage-runner.php b/.github/coverage-runner.php
index 3cb30de..e366126 100644
--- a/.github/coverage-runner.php
+++ b/.github/coverage-runner.php
@@ -28,50 +28,52 @@
 require __DIR__ . '/../vendor/autoload.php';
 
 const UNREACHABLE_LINES = [
-    // optionalStringInput/stringListInput "candidate === null" continue
-    // guards: every call site passes a non-null alternate key.
-    'src/Config/AgentConfigResolver.php' => [232, 300],
-    // openssl_encrypt cannot fail for a key already validated to exactly
-    // KEY_SIZE bytes (80); the EncryptionException rethrow arm is only fed by
-    // line 80 (85); verifyKey's catch cannot trigger when construction
-    // succeeded and openssl is functional (138-139).
-    'src/Encryption/PayloadEncryptor.php' => [80, 85, 138, 139],
-    // loadFromRedis/loadOne*FromRedis null-handler guards: the only caller
-    // (initializeRedis) assigns the handler first (176, 204, 233). Catches
-    // around handler calls that are themselves total (RedisHandler catches
-    // every client Throwable): keys failures (196-197), confirm deletes
-    // (271-272, 289-290), the addEvent/addMetric try arms around the
-    // internally catching persist helpers (377-378, 425-426), and
-    // clearBuffer's keys/delete loop (595-596).
-    'src/EventBuffer/EventBuffer.php' => [176, 196, 197, 204, 233, 271, 272, 289, 290, 377, 378, 425, 426, 595, 596],
-    // stop()'s close catch: RedisHandler::close is total (252-253).
-    // asMetadataArray/asStringArray fallbacks: HeadersRedactor::sanitize of
-    // an array always returns an array (778, 789).
+    // Catches around RedisHandler calls that are themselves total: keys()
+    // (196-197, 595-596), delete() (271-272, 289-290), and setKey()
+    // (377-378, 425-426, via the persist helpers whose try additionally
+    // spans uniqueKey, Json::encode, and SplObjectStorage assignment, none
+    // of which throw) each catch every client Throwable inside RedisHandler
+    // and degrade to a return value, so no Throwable can reach the buffer's
+    // own catch arms.
+    'src/EventBuffer/EventBuffer.php' => [196, 197, 271, 272, 289, 290, 377, 378, 425, 426, 595, 596],
+    // stop()'s close catch: GuardAgent::$redisHandler is the final
+    // RedisHandler (initializeRedis hard-types it) whose close() catches
+    // every Throwable (252-253). asMetadataArray/asStringArray fallbacks:
+    // the inputs are SecurityEvent::$metadata / SecurityMetric::$tags array
+    // properties passed through HeadersRedactor::sanitize, which returns an
+    // array for an array input at the top depth (778, 789).
     'src/GuardAgent.php' => [252, 253, 778, 789],
     // read()/write() catch arms over @-suppressed filesystem calls, which
-    // return false instead of throwing (76-77, 79, 95-96).
+    // return false instead of throwing (76-77, 79, 95-96): is_file($path)
+    // true implies a non-empty path, and the PHP 8 ValueErrors in this
+    // function family require an empty path, which cannot reach read()'s
+    // file_get_contents (is_file('') is false) or write()'s
+    // file_put_contents (the mkdir guard returns early for the empty dir).
     'src/Install/InstallId.php' => [76, 77, 79, 95, 96],
     // error_log fallback runs only under a web SAPI (61-62); the stream
     // fallback only fires when STDOUT is undefined AND fopen fails, and the
     // CLI SAPI defines both (68).
     'src/Log/DefaultAgentLogger.php' => [61, 62, 68],
     // new DateTimeImmutable('@' . (string)(int) $value) cannot throw for any
-    // int/float epoch on the supported 64-bit platforms (44-45).
+    // int/float epoch: the (int) cast yields an int for every float
+    // (NAN/overflow casts emit a diagnostic, not a throw) and '@<int>' is
+    // always constructible on the supported 64-bit platforms (44-45).
     'src/Model/WireFormat.php' => [44, 45],
-    // curl_init failure (357); initEncryption: create() returns non-null for
-    // every key that passes the empty guard and verifyKey() holds whenever
-    // openssl is functional (413, 417-419); postEncrypted's encryptor-null
-    // guard is implied by isEncryptedTarget checking encryptionEnabled (456);
-    // the transport-boundary redaction pass never sees arrays there because
-    // toWire() casts metadata/tags to objects (512-515, 522-525).
-    'src/Transport/HttpTransport.php' => [357, 413, 417, 418, 419, 456, 512, 513, 514, 515, 522, 523, 524, 525],
-    // json_encode of a finite float with JSON_THROW_ON_ERROR cannot fail
-    // (64-65).
+    // The transport-boundary redaction pass never sees arrays there because
+    // toWire() casts metadata/tags to objects (SecurityEvent.php:155,
+    // SecurityMetric.php:101) and makeRequest's payload always comes from
+    // buildBatchWire mapping those toWire() outputs (512-515, 522-525).
+    'src/Transport/HttpTransport.php' => [512, 513, 514, 515, 522, 523, 524, 525],
+    // json_encode of a finite float with JSON_THROW_ON_ERROR cannot fail:
+    // the is_finite guard above rejects Inf/NaN before this call is reached
+    // (asserted by the canonical json tests) and a finite float scalar has
+    // no depth, UTF-8, or type failure mode (64-65).
     'src/Utils/CanonicalJson.php' => [64, 65],
     // sanitizeValueUnsafe cannot throw for the value domain it accepts
-    // (46-47); the re-encoded sanitized structure is always json-encodable
-    // (112-113).
-    'src/Utils/HeadersRedactor.php' => [46, 47, 112, 113],
+    // (46-47): every operation is a non-throwing type check, arithmetic-free
+    // recursion, or pass-through, and its two fallible callees (json_decode
+    // at 105, Json::encode at 111) carry their own local catches.
+    'src/Utils/HeadersRedactor.php' => [46, 47],
     // json_encode with JSON_THROW_ON_ERROR never returns false (37).
     'src/Utils/Json.php' => [37],
     // phpredis 6 close() returns silently on an already-closed socket; the