test: tighten assertions, add error-path tests, and document golden-envelope schemas

Author: ThomasK33

test/e2e/hello-prompt.test.ts

@@ -99,9 +99,10 @@ describe('hello-prompt e2e', { timeout: 30_000 }, () => {
     );
     expect(sendKeysEnvelope.ok).toBe(true);
     expect(sendKeysEnvelope.command).toBe('send-keys');
-    expect(sendKeysEnvelope.result).toMatchObject({
+    expect(sendKeysEnvelope.result).toEqual({
       accepted: ['Enter'],
       bytesWritten: 1,
+      seq: expect.any(Number) as number,
     });
     expect(sendKeysEnvelope.result.seq).toBeGreaterThanOrEqual(0);
 
@@ -146,9 +147,10 @@ describe('hello-prompt e2e', { timeout: 30_000 }, () => {
     );
     expect(sendExitEnterEnvelope.ok).toBe(true);
     expect(sendExitEnterEnvelope.command).toBe('send-keys');
-    expect(sendExitEnterEnvelope.result).toMatchObject({
+    expect(sendExitEnterEnvelope.result).toEqual({
       accepted: ['Enter'],
       bytesWritten: 1,
+      seq: expect.any(Number) as number,
     });
     expect(sendExitEnterEnvelope.result.seq).toBeGreaterThanOrEqual(0);
 
@@ -227,9 +229,10 @@ describe('hello-prompt e2e', { timeout: 30_000 }, () => {
     );
     expect(sendKeysEnvelope.ok).toBe(true);
     expect(sendKeysEnvelope.command).toBe('send-keys');
-    expect(sendKeysEnvelope.result).toMatchObject({
+    expect(sendKeysEnvelope.result).toEqual({
       accepted: ['Enter'],
       bytesWritten: 1,
+      seq: expect.any(Number) as number,
     });
     expect(sendKeysEnvelope.result.seq).toBeGreaterThanOrEqual(0);
 

test/e2e/resize-demo.test.ts

@@ -134,9 +134,10 @@ describe('resize-demo e2e', { timeout: 30_000 }, () => {
     );
     expect(sendKeysEnvelope.ok).toBe(true);
     expect(sendKeysEnvelope.command).toBe('send-keys');
-    expect(sendKeysEnvelope.result).toMatchObject({
+    expect(sendKeysEnvelope.result).toEqual({
       accepted: ['Enter'],
       bytesWritten: 1,
+      seq: expect.any(Number) as number,
     });
     expect(sendKeysEnvelope.result.seq).toBeGreaterThanOrEqual(0);
 

test/integration/lifecycle.test.ts

@@ -689,6 +689,28 @@ describe('lifecycle integration', { timeout: 30000 }, () => {
     expect(envelope.error.code).toBe('SESSION_NOT_FOUND');
   });
 
+  it('send-keys to non-existent session returns SESSION_NOT_FOUND', () => {
+    const result = runCli(['send-keys', 'NONEXISTENT', 'Enter', '--json'], {
+      AGENT_TERMINAL_HOME: testHome,
+    });
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toBe('');
+    const envelope = JSON.parse(result.stdout) as ErrorEnvelope;
+    expect(envelope.ok).toBe(false);
+    expect(envelope.error.code).toBe('SESSION_NOT_FOUND');
+  });
+
+  it('destroy non-existent session returns SESSION_NOT_FOUND', () => {
+    const result = runCli(['destroy', 'NONEXISTENT', '--json'], {
+      AGENT_TERMINAL_HOME: testHome,
+    });
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toBe('');
+    const envelope = JSON.parse(result.stdout) as ErrorEnvelope;
+    expect(envelope.ok).toBe(false);
+    expect(envelope.error.code).toBe('SESSION_NOT_FOUND');
+  });
+
   it('event log contains output and exit records', async () => {
     const createResult = runCli(
       [

test/unit/commands/golden-envelopes.test.ts

@@ -37,6 +37,10 @@ const VersionResultSchema = z
   })
   .strict();
 
+// CreateResultSchema is defined locally because create does not go through
+// the RPC layer — it constructs the result from the session manifest.
+// This schema acts as the golden contract lock for the create result shape.
+// If a protocol-level CreateResultSchema is added later, replace this.
 const CreateResultSchema = z
   .object({
     sessionId: NonEmptyStringSchema,
@@ -49,6 +53,10 @@ const CreateResultSchema = z
   })
   .strict();
 
+// SessionSummarySchema is defined locally because list returns session summaries
+// assembled from manifests rather than a shared protocol export. This schema
+// locks the expected per-session list payload used by the local ListResultSchema.
+// If a protocol-level SessionSummarySchema is added later, replace this.
 const SessionSummarySchema = z
   .object({
     sessionId: NonEmptyStringSchema,
@@ -60,6 +68,10 @@ const SessionSummarySchema = z
   })
   .strict();
 
+// ListResultSchema is defined locally because list does not go through the
+// RPC layer — it constructs the result from session manifests and summaries.
+// This schema acts as the golden contract lock for the list result shape.
+// If a protocol-level ListResultSchema is added later, replace this.
 const ListResultSchema = z
   .object({
     sessions: z.array(SessionSummarySchema),

test/unit/protocol/messages.test.ts

@@ -541,6 +541,14 @@ describe('RPC message schemas', () => {
     expect(result.success).toBe(false);
   });
 
+  it('accepts sendKeys params with multiple keys', () => {
+    const result = SendKeysParamsSchema.safeParse({
+      keys: ['Ctrl+L', 'g', 'g'],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
   it('rejects empty paste text', () => {
     const result = PasteParamsSchema.safeParse({
       text: '',