fix: distinct lifecycle error codes and stricter required_features (#105 #111 #113)

- handleCancel/handleInterrupt return NOT_FOUND for an unknown job and reserve
  FAILED_PRECONDITION for an existing-but-terminal job.
- handleResume surfaces a buffer miss as a correlated nack (DATA_LOSS) instead
  of an out-of-context tool.error.
- HandshakeNegotiator rejects a non-string entry in required_features rather
  than silently skipping it.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: nficano

src/Internal/Runtime/HandshakeNegotiator.php

@@ -202,7 +202,10 @@ private function checkCapabilities(Capabilities $requested): ?string
         if (\is_array($required)) {
             $advertisedFeatures = $this->runtime->advertisedCapabilitiesForSession()->features;
             foreach ($required as $feature) {
-                if (\is_string($feature) && !\in_array($feature, $advertisedFeatures, true)) {
+                if (!\is_string($feature)) {
+                    return 'required_features entry must be string';
+                }
+                if (!\in_array($feature, $advertisedFeatures, true)) {
                     return 'feature unsupported: ' . $feature;
                 }
             }

src/Internal/Runtime/LifecycleHandler.php

@@ -23,7 +23,6 @@
 use Arcp\Messages\Control\Ping;
 use Arcp\Messages\Control\Pong;
 use Arcp\Messages\Control\Resume;
-use Arcp\Messages\Execution\ToolError;
 use Arcp\Messages\Human\HumanInputRequest;
 use Arcp\Messages\Human\HumanInputResponse;
 use Arcp\Messages\Permissions\LeaseExtended;
@@ -79,7 +78,11 @@ public function handleCancel(Session $session, Envelope $env, Cancel $msg): void
             return;
         }
         $job = $this->runtime->jobs->tryGet(new JobId($msg->targetId));
-        if (!$job instanceof Job || $job->state->isTerminal()) {
+        if (!$job instanceof Job) {
+            $this->nack($session, $env, 'NOT_FOUND', 'job not found');
+            return;
+        }
+        if ($job->state->isTerminal()) {
             $this->nack($session, $env, 'FAILED_PRECONDITION', 'job already terminal');
             return;
         }
@@ -95,8 +98,12 @@ public function handleCancel(Session $session, Envelope $env, Cancel $msg): void
     public function handleInterrupt(Session $session, Envelope $env, Interrupt $msg): void
     {
         $job = $this->runtime->jobs->tryGet(new JobId($msg->targetId));
-        if (!$job instanceof Job || $job->state->isTerminal()) {
-            $this->nack($session, $env, 'FAILED_PRECONDITION', 'job not interruptible');
+        if (!$job instanceof Job) {
+            $this->nack($session, $env, 'NOT_FOUND', 'job not found');
+            return;
+        }
+        if ($job->state->isTerminal()) {
+            $this->nack($session, $env, 'FAILED_PRECONDITION', 'job already terminal');
             return;
         }
         // Only the owning session may interrupt a job (cf. handleCancel).
@@ -159,11 +166,9 @@ public function handleResume(Session $session, Envelope $env, Resume $msg): void
                 $session->transport->send($past);
             }
         } catch (InvalidArgumentException) {
-            $this->runtime->emit($session, new ToolError(
-                new ErrorPayload('DATA_LOSS', 'after_message_id retention expired'),
-            ), [
-                'correlation_id' => $env->id,
-            ]);
+            // Resume is a lifecycle operation, not a tool invocation; surface
+            // the failure as a correlated nack like every other lifecycle path.
+            $this->nack($session, $env, 'DATA_LOSS', 'after_message_id retention expired');
             return;
         }
         $this->runtime->emit($session, new Ack('resumed'), ['correlation_id' => $env->id]);

tests/Unit/Internal/Runtime/HandshakeNegotiatorTest.php

@@ -151,6 +151,28 @@ public function invoke(array $arguments, JobContext $ctx, ?Cancellation $cancell
         $futureB->await();
     }
 
+    public function testNonStringRequiredFeatureIsRejected(): void
+    {
+        $runtime = new ARCPRuntime();
+        [$serverT, $clientT] = MemoryTransport::pair();
+        $serverFuture = $runtime->serveAsync($serverT);
+
+        $client = new ARCPClient($clientT);
+        try {
+            $client->open(
+                Auth::none(),
+                new PeerInfo('cli', '0.1'),
+                new Capabilities(anonymous: true, extra: ['required_features' => [123]]),
+            );
+            self::fail('expected UnimplementedException for non-string required feature');
+        } catch (UnimplementedException $e) {
+            self::assertStringContainsString('required_features entry must be string', $e->getMessage());
+        } finally {
+            $client->close();
+            $serverFuture->await();
+        }
+    }
+
     public function testMtlsAuthRouterReturnsUnimplemented(): void
     {
         // AuthRouter does not register mtls scheme; mtls is reserved -> UnimplementedException.

tests/Unit/Internal/Runtime/LifecycleHandlerTest.php

@@ -23,7 +23,6 @@
 use Arcp\Messages\Control\Interrupt;
 use Arcp\Messages\Control\Nack;
 use Arcp\Messages\Control\Resume;
-use Arcp\Messages\Execution\ToolError;
 use Arcp\Messages\Execution\ToolInvoke;
 use Arcp\Messages\Human\HumanChoiceRequest;
 use Arcp\Messages\Human\HumanChoiceResponse;
@@ -73,7 +72,7 @@ public function testCancelNonJobTargetIsNackedAsUnimplemented(): void
         $serverFuture->await();
     }
 
-    public function testCancelUnknownJobReturnsFailedPrecondition(): void
+    public function testCancelUnknownJobReturnsNotFound(): void
     {
         [, $client, $serverFuture] = $this->pair();
         $msgId = MessageId::random();
@@ -86,7 +85,7 @@ public function testCancelUnknownJobReturnsFailedPrecondition(): void
         $client->session->transport->send($env);
         $response = $client->pending->awaitResponse($msgId, 5.0);
         self::assertInstanceOf(Nack::class, $response);
-        self::assertSame('FAILED_PRECONDITION', $response->error->code);
+        self::assertSame('NOT_FOUND', $response->error->code);
 
         $client->close();
         $serverFuture->await();
@@ -157,7 +156,7 @@ public function testInterruptOnUnknownJobIsNacked(): void
         $client->session->transport->send($env);
         $response = $client->pending->awaitResponse($msgId, 5.0);
         self::assertInstanceOf(Nack::class, $response);
-        self::assertSame('FAILED_PRECONDITION', $response->error->code);
+        self::assertSame('NOT_FOUND', $response->error->code);
 
         $client->close();
         $serverFuture->await();
@@ -260,7 +259,7 @@ public function testResumeWithCheckpointIsNackedAsUnimplemented(): void
         $serverFuture->await();
     }
 
-    public function testResumeWithUnknownAfterMessageIdYieldsDataLossToolError(): void
+    public function testResumeWithUnknownAfterMessageIdYieldsDataLossNack(): void
     {
         [, $client, $serverFuture] = $this->pair();
 
@@ -273,7 +272,7 @@ public function testResumeWithUnknownAfterMessageIdYieldsDataLossToolError(): vo
         );
         $client->session->transport->send($env);
         $response = $client->pending->awaitResponse($msgId, 5.0);
-        self::assertInstanceOf(ToolError::class, $response);
+        self::assertInstanceOf(Nack::class, $response);
         self::assertSame('DATA_LOSS', $response->error->code);
 
         $client->close();