From 6253a93c82406e1246b37bdf6c5731ea044ddc9b Mon Sep 17 00:00:00 2001
From: Charles Packer <packercharles@gmail.com>
Date: Sun, 22 Feb 2026 23:31:14 -0800
Subject: [PATCH] fix: handle default conversation sentinel in headless startup
 (#1100)

---
 src/headless.ts                               |  6 ++-
 .../startup-flow.integration.test.ts          | 51 +++++++++++++++++++
 2 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/src/headless.ts b/src/headless.ts
index fa40062..4313d6b 100644
--- a/src/headless.ts
+++ b/src/headless.ts
@@ -735,8 +735,10 @@ export async function handleHeadlessCommand(
     }
   }
 
-  // Priority 0: --conversation derives agent from conversation ID
-  if (specifiedConversationId) {
+  // Priority 0: --conversation derives agent from conversation ID.
+  // "default" is a virtual agent-scoped conversation (not a retrievable conv-*).
+  // It requires --agent and should not hit conversations.retrieve().
+  if (specifiedConversationId && specifiedConversationId !== "default") {
     try {
       const conversation = await client.conversations.retrieve(
         specifiedConversationId,
diff --git a/src/integration-tests/startup-flow.integration.test.ts b/src/integration-tests/startup-flow.integration.test.ts
index d22195e..76a1bdf 100644
--- a/src/integration-tests/startup-flow.integration.test.ts
+++ b/src/integration-tests/startup-flow.integration.test.ts
@@ -229,6 +229,57 @@ describe("Startup Flow - Integration", () => {
     { timeout: 180000 },
   );
 
+  test(
+    "--agent + --conversation default succeeds and stays on default route",
+    async () => {
+      let agentIdForTest = testAgentId;
+      if (!agentIdForTest) {
+        const bootstrapResult = await runCli(
+          [
+            "--new-agent",
+            "-m",
+            "haiku",
+            "-p",
+            "Say OK",
+            "--output-format",
+            "json",
+          ],
+          { timeoutMs: 120000 },
+        );
+        expect(bootstrapResult.exitCode).toBe(0);
+        const bootstrapJsonStart = bootstrapResult.stdout.indexOf("{");
+        const bootstrapOutput = JSON.parse(
+          bootstrapResult.stdout.slice(bootstrapJsonStart),
+        );
+        agentIdForTest = bootstrapOutput.agent_id as string;
+        testAgentId = agentIdForTest;
+      }
+
+      const result = await runCli(
+        [
+          "--agent",
+          agentIdForTest,
+          "--conversation",
+          "default",
+          "-m",
+          "haiku",
+          "-p",
+          "Say OK",
+          "--output-format",
+          "json",
+        ],
+        { timeoutMs: 120000 },
+      );
+
+      expect(result.exitCode).toBe(0);
+      const jsonStart = result.stdout.indexOf("{");
+      const output = JSON.parse(result.stdout.slice(jsonStart));
+      expect(output.agent_id).toBe(agentIdForTest);
+      expect(output.conversation_id).toBe("default");
+    },
+    { timeout: 130000 },
+  );
+
   test(
     "--new-agent with --init-blocks none creates minimal agent",
     async () => {