lilyshen0722 · Oct 31, 2026 · Oct 26, 2026 · Oct 26, 2026 · Oct 31, 2026 · Oct 31, 2026
diff --git a/backend/__tests__/unit/config/nativeAgents.scoutKnowledge.test.js b/backend/__tests__/unit/config/nativeAgents.scoutKnowledge.test.js
@@ -119,13 +119,19 @@ describe('Scout onboarding knowledge', () => {
     expect(prompt).toMatch(/Do not claim any other tool connects/);
   });
 
-  // Linux run 38982219348: a Claude Code listener cannot run on Linux, WSL or
-  // Windows (#2288 refuses it), so a connect card for it there is a dead end.
-  test('offers a connect card for Claude Code on a Mac only, and says what works elsewhere', () => {
-    expect(prompt).toMatch(/Claude Code on a Mac; Codex on a Mac \(Linux and WSL not yet tested\)/);
+  // TASK-027: a Claude Code listener runs on Linux or WSL only in invite-only
+  // pods, and not at all on native Windows, so a card for it there is a dead end.
+  // Codex stays Mac only until a Linux walk (#2783).
+  test('offers a connect card for Claude Code on a Mac, or on Linux in an invite-only pod, and says what works elsewhere', () => {
+    expect(prompt).toMatch(/Claude Code on a Mac, or on Linux \(WSL included\) in an invite-only pod; Codex on a Mac \(Linux and WSL not yet tested\)/);
+    // CodeRabbit on #2823: the CLI checks the whole seat, so one open pod stops
+    // replies in every pod, not just that one.
+    expect(prompt).toMatch(/For Claude Code on Linux or WSL, say it answers only while every pod it is in is invite-only: if any one of them opens up, it stops answering in all of them until that pod is invite-only again\./);
+    expect(prompt).not.toMatch(/say it answers only in invite-only pods/);
     expect(prompt).toMatch(/DeepSeek Harness \(dsh\) through its attach guide, walked on macOS with other OSs unverified/);
     expect(prompt).not.toMatch(/On Linux \(WSL included\), Codex only/);
-    expect(prompt).toMatch(/For Claude Code on Linux, WSL or Windows, do not propose a connect card/);
+    expect(prompt).toMatch(/For Claude Code on native Windows, do not propose a connect card/);
+    expect(prompt).not.toMatch(/For Claude Code on Linux, WSL or Windows, do not propose a connect card/);
     expect(prompt).toMatch(/commonly_offer_hosted_agent, and also say they can use the pod from their own Claude Code sessions/);
     expect(prompt).not.toMatch(/Windows is not verified yet/);
   });
@@ -153,9 +159,9 @@ describe('Scout onboarding knowledge', () => {
 
   // The prompt is the only guard before the card, so the pairs
   // it may go out for are listed, not inferred.
-  test('proposes the card only for Claude Code on macOS and Codex on macOS', () => {
-    expect(prompt).toMatch(/The card may go out for exactly these pairs: Claude Code on macOS; Codex on macOS\./);
-    expect(prompt).toMatch(/Any other OS, such as Linux, WSL, native Windows, ChromeOS, iPad or iPhone, Android or FreeBSD, gets a text answer and no card/);
+  test('proposes the card only for Claude Code on macOS, Linux or WSL and Codex on macOS', () => {
+    expect(prompt).toMatch(/The card may go out for exactly these pairs: Claude Code on macOS, Linux or WSL; Codex on macOS\./);
+    expect(prompt).toMatch(/Any other pair, such as Codex on Linux or WSL, or any tool on native Windows, ChromeOS, iPad or iPhone, Android or FreeBSD, gets a text answer and no card/);
     ['ChromeOS', 'iPad', 'Android'].forEach((os) => expect(prompt).toContain(os));
   });
 
@@ -178,10 +184,11 @@ describe('Scout onboarding knowledge', () => {
     expect(prompt).toMatch(/For any other tool, or an OS where it does not run yet, never propose the card; answer in text\. OpenCode, Hermes and DeepSeek Harness have their own paths above: point them there\. Say plainly that it does not run there yet only for a tool with no path above, or an OS its path does not cover\./);
     // CodeRabbit on #2765: the no-card rule must not deny tools that do connect.
     expect(prompt).not.toMatch(/For any other tool, or an OS where it does not run yet, never propose the card; answer in text and say plainly that it does not run there yet/);
-    expect(prompt).toMatch(/For Claude Code on Linux, WSL or Windows, do not propose a connect card: offer "Run it here" with commonly_offer_hosted_agent, and also say they can use the pod from their own Claude Code sessions with the MCP command on the connect page \(on Windows the page gives it as two PowerShell lines\)/);
+    expect(prompt).toMatch(/For Claude Code on native Windows, do not propose a connect card: offer "Run it here" with commonly_offer_hosted_agent, and also say they can use the pod from their own Claude Code sessions with the MCP command on the connect page \(on Windows the page gives it as two PowerShell lines\)/);
     expect(prompt).toMatch(/For Codex on native Windows, do not propose a connect card either: offer "Run it here", or running Codex on a Mac\. Say plainly why/);
     const en = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../../../../frontend/src/i18n/locales/en.json'), 'utf8'));
     expect(en.agentByo.listen.unavailableClaude).toMatch(/Connect Claude Code from your own sessions with the command below, or choose “Run it here”/);
+    expect(en.agentByo.listen.unavailableClaudeLinux).toMatch(/only in an invite-only pod.*connect Claude Code from your own sessions with the command below, or choose “Run it here”/);
     expect(en.agentByo.listen.unavailableCodex).toMatch(/Choose “Run it here” for a hosted agent, or run the command on a Mac\. Linux is not tested yet\./);
   });
 

diff --git a/backend/config/native-agents/scout.ts b/backend/config/native-agents/scout.ts
@@ -166,15 +166,21 @@ export const scoutApp = {
     + '--instance <API URL of this instance> && commonly daemon register && commonly daemon install` registers their '
     + 'machine once (on commonly.me the API URL is https://api.commonly.me); after that they add agents to it from this page with no '
     + 'terminal.\n'
-    // Linux run 38982219348 (2026-10-16): the sandbox that keeps a connected
-    // agent to its own folder cannot start Claude Code on Linux or WSL, and
-    // the CLI refuses to try (#2288). Codex does not run in it.
+    // TASK-027: on Linux or WSL the CLI runs Claude Code only as a workspace
+    // seat, which needs every pod it answers in to be invite-only; a public
+    // Claude Code seat there is refused (Linux run 38982219348, #2288). The
+    // workspace made at signup and the pods Scout creates are invite-only.
     + '- Where their own agent can be connected as a teammate that answers '
-    + '@mentions: Claude Code on a Mac; Codex on a Mac (Linux and WSL not yet tested); '
+    + '@mentions: Claude Code on a Mac, or on Linux (WSL included) in an '
+    + 'invite-only pod; Codex on a Mac (Linux and WSL not yet tested); '
     + 'DeepSeek Harness (dsh) through its attach guide, walked on macOS with '
     + 'other OSs unverified. On native Windows, Claude Code and Codex are not '
-    + 'supported; Codex inside WSL counts as Linux. For '
-    + 'Claude Code on Linux, WSL or Windows, do not propose a connect card: offer '
+    + 'supported; Codex inside WSL counts as Linux. For Claude Code on Linux or '
+    + 'WSL, say it answers only while every pod it is in is invite-only: if any '
+    + 'one of them opens up, it stops answering in all of them until that pod is '
+    + 'invite-only again. Their own workspace and the pods you create are '
+    + 'invite-only. For '
+    + 'Claude Code on native Windows, do not propose a connect card: offer '
     + '"Run it here" with commonly_offer_hosted_agent, and also say they can use the pod '
     + 'from their own Claude Code sessions with the MCP command on the connect '
     + 'page (on Windows the page gives it as two PowerShell lines). For Codex on '
@@ -227,7 +233,7 @@ export const scoutApp = {
     // and adapter only).
     + '- You can SET UP their own agent for them, and the connect card is the '
     + 'answer whenever it can work. The card may go out for exactly these pairs: '
-    + 'Claude Code on macOS; Codex on macOS. Any other OS, such as Linux, WSL, '
+    + 'Claude Code on macOS, Linux or WSL; Codex on macOS. Any other pair, such as Codex on Linux or WSL, or any tool on '
     + 'native Windows, ChromeOS, iPad or iPhone, Android or FreeBSD, gets a text '
     + 'answer and no card. The tool must be the command-line one they run in a '
     + 'terminal: the Claude app (desktop or phone) and claude.ai are not Claude '

diff --git a/docs-site/bring-your-own/claude-code.mdx b/docs-site/bring-your-own/claude-code.mdx
@@ -1,16 +1,16 @@
 ---
 title: Connect Claude Code to a pod
 sidebarTitle: Claude Code
-description: Run a Claude Code listener on your Mac that answers @mentions in a Commonly pod and uses Commonly tools. Needs Node.js 20 or later.
+description: Run a Claude Code listener on your Mac, or on Linux in invite-only pods, that answers @mentions in a Commonly pod and uses Commonly tools. Needs Node.js 20 or later.
 ---
 
-This listener runs Claude Code on your Mac and uses Commonly tools. In invite-only pods it can read the folder you start it in, and `--allow` can let it edit files or fetch web pages: see [what the listener can reach](/bring-your-own/work-in-your-repo#what-the-listener-can-reach). For a session that edits your repository, use [Work in your repo](/bring-your-own/work-in-your-repo).
+This listener runs Claude Code on your Mac, or on Linux (WSL included) when every pod it answers in is invite-only, and uses Commonly tools. In invite-only pods it can read the folder you start it in, and `--allow` can let it edit files or fetch web pages: see [what the listener can reach](/bring-your-own/work-in-your-repo#what-the-listener-can-reach). For a session that edits your repository, use [Work in your repo](/bring-your-own/work-in-your-repo).
 
-You need Node.js 20 or later and Claude Code signed in on that Mac.
+You need Node.js 20 or later and Claude Code signed in on that computer. On Linux you also need bubblewrap (`bwrap`), and you run the command from your project folder, not your home folder.
 
 1. Open [Bring your own agent](https://commonly.me/v2/agents/byo) and choose **Use my own agent**.
 2. Name the agent and choose its pod.
-3. Select **Get my connect command**. Under **Setting up on**, keep **macOS**. Claude Code is the default. Copy the listener command shown on the page into Terminal on the Mac with Claude Code. The token is shown once.
+3. Select **Get my connect command**. Under **Setting up on**, keep **macOS**, or pick **Linux** for an invite-only pod. Claude Code is the default. Copy the listener command shown on the page into a terminal on that computer. The token is shown once.
 4. Keep Terminal running. Wait for the page to show that the agent is listening, then @mention it in the pod.
 
 The Connect page shows this command with your key and agent name filled in. Copy it from the page:

diff --git a/docs-site/bring-your-own/work-in-your-repo.mdx b/docs-site/bring-your-own/work-in-your-repo.mdx
@@ -32,7 +32,7 @@ The [Claude Code listener](/bring-your-own/claude-code) checks the pods its key
 - Read-only git never contacts a remote. In a partial clone, an object that was never downloaded stays missing, and git reports it as missing.
 - Anyone who can @mention it in those pods can ask what the files there say, so run it from a folder you would show them.
 
-Otherwise it reads only its own scratch folder, and the lines it prints when it starts say why. That happens when it runs anywhere but macOS, when a pod is publicly readable, listed in Community or open to join, or when you run it from your home directory, `/`, or a folder like `~/.ssh`. It checks its pods again before every turn. If one has become publicly readable, listed in Community or open to join, or the check fails, that turn runs in the scratch folder with a fresh session. It also gets none of the agent's saved memory and can't save any, because earlier turns may have stored what they read in your folder.
+Otherwise, on a Mac, it reads only its own scratch folder, and the lines it prints when it starts say why. That happens when a pod is publicly readable, listed in Community or open to join, or when you run it from your home directory, `/`, or a folder like `~/.ssh`. It checks its pods again before every turn. If one has become publicly readable, listed in Community or open to join, or the check fails, that turn runs in the scratch folder with a fresh session. On Linux, including WSL, Claude Code has no scratch-folder fallback: in those cases it refuses to start, or stops answering until every pod is invite-only again. It also gets none of the agent's saved memory and can't save any, because earlier turns may have stored what they read in your folder.
 
 ### Give it more with `--allow`
 

diff --git a/docs/design/readme-benchmark.md b/docs/design/readme-benchmark.md
@@ -89,7 +89,7 @@ Every row cites its source: `backend/config/native-agents/scout.ts` pinned at `b
 
 | Claim | Walked status |
 |---|---|
-| Your own Claude Code joins as a teammate that answers @mentions | **Mac only.** Not Linux, WSL or native Windows (sandbox, Linux run 38982219348). [scout.ts:140-148](https://github.com/Team-Commonly/commonly/blob/bf0bd593/backend/config/native-agents/scout.ts#L140-L148) |
+| Your own Claude Code joins as a teammate that answers @mentions | **Mac, and Linux or WSL in invite-only pods** (TASK-027). Not native Windows (no sandbox). Earlier: Mac only (Linux run 38982219348). [scout.ts:140-148](https://github.com/Team-Commonly/commonly/blob/bf0bd593/backend/config/native-agents/scout.ts#L140-L148) |
 | Your own Codex joins as a teammate | Mac and Linux, WSL included. Not native Windows. [scout.ts:144-147](https://github.com/Team-Commonly/commonly/blob/bf0bd593/backend/config/native-agents/scout.ts#L144-L147) |
 | OpenCode (any provider, e.g. DeepSeek) | Via `docs/cli/opencode.md`, walked on a Mac only. [scout.ts:114-123](https://github.com/Team-Commonly/commonly/blob/bf0bd593/backend/config/native-agents/scout.ts#L114-L123) |
 | DeepSeek Harness (dsh) | Attached as your own agent in a **private pod**, via its attach guide. Walked on macOS; other OSs unverified. [scout.ts:145-146](https://github.com/Team-Commonly/commonly/blob/bf0bd593/backend/config/native-agents/scout.ts#L145-L146), [scout.ts:165-171](https://github.com/Team-Commonly/commonly/blob/bf0bd593/backend/config/native-agents/scout.ts#L165-L171) |

diff --git a/frontend/src/content/guides.json b/frontend/src/content/guides.json
@@ -135,7 +135,7 @@
       },
       {
         "question": "Can I use Claude Code and Codex in the same team?",
-        "answer": "Yes. Set each one up from the Bring your own agent page on your own machine (Claude Code on a Mac; Codex on a Mac; Linux is not tested yet). Both join the same pod with their own identities, answer @mentions while their listener runs, and keep their runtime-specific tools."
+        "answer": "Yes. Set each one up from the Bring your own agent page on your own machine (Claude Code on a Mac, or on Linux, including WSL, in an invite-only pod; Codex on a Mac, not yet tested on Linux). Both join the same pod with their own identities, answer @mentions while their listener runs, and keep their runtime-specific tools."
       },
       {
         "question": "How do agents share context?",
@@ -792,7 +792,7 @@
       },
       {
         "question": "Will an MCP-connected agent respond automatically when mentioned?",
-        "answer": "An MCP-connected agent is reactive: it acts when you invoke it in its host tool. To have @mentions answered while you are away, run the listener command the Bring your own agent page gives you, commonly agent run <name>. While it runs, Claude Code (Mac only) or Codex (Mac only; Linux is not tested yet) answers on your machine. Start with MCP when you use Claude Code or Codex interactively."
+        "answer": "An MCP-connected agent is reactive: it acts when you invoke it in its host tool. To have @mentions answered while you are away, run the listener command the Bring your own agent page gives you, commonly agent run <name>. While it runs, Claude Code (on a Mac, or on Linux, including WSL, in an invite-only pod) or Codex (Mac only; Linux is not tested yet) answers on your machine. Start with MCP when you use Claude Code or Codex interactively."
       },
       {
         "question": "Can this replace GitHub, tests, or source control?",
@@ -5724,7 +5724,7 @@
     },
     "intro": [
       "An AI agent CLI wrapper turns a local command-line agent into a participant in a shared workspace: it polls collaboration events and drives the local CLI to respond. It does not move the agent into the workspace, make a laptop a hosted runtime, or give the agent permissions its runtime and connected systems did not already have.",
-      "Commonly (commonly.me), the shared workspace where humans and AI agents work together, offers a CLI path for the case where a team wants a local agent to stay present in a pod while the operator is away. The listener runs Claude Code (Mac only) or Codex (Mac only; Linux is not tested yet), set up from the Bring your own agent page, or OpenCode, attached from the command line with commonly agent attach opencode. The agent still runs on the machine that starts it. Commonly supplies the pod identity, collaboration surface, runtime events, memory, and task record; the local CLI supplies the reasoning and any host-level capabilities its operator has configured.",
+      "Commonly (commonly.me), the shared workspace where humans and AI agents work together, offers a CLI path for the case where a team wants a local agent to stay present in a pod while the operator is away. The listener runs Claude Code (on a Mac, or on Linux, including WSL, in an invite-only pod) or Codex (Mac only; Linux is not tested yet), set up from the Bring your own agent page, or OpenCode, attached from the command line with commonly agent attach opencode. The agent still runs on the machine that starts it. Commonly supplies the pod identity, collaboration surface, runtime events, memory, and task record; the local CLI supplies the reasoning and any host-level capabilities its operator has configured.",
       "That split is the useful part of the design, and the part worth being explicit about. A local agent can collaborate continuously without a public inbound endpoint, but a wrapper is not a security boundary, a repository permission system, or a substitute for review. This guide explains how to attach and run a CLI agent, where its authority begins and ends, how heartbeats fit into the operating model, and how to test one small workflow before handing the agent a larger role."
     ],
     "sections": [

diff --git a/frontend/src/content/landing-faq.json b/frontend/src/content/landing-faq.json
@@ -37,7 +37,7 @@
   },
   {
     "question": "how do I connect Claude Code to my team's chat so it answers @mentions",
-    "answer": "In a Commonly pod, choose \"Use my own agent\", then \"Get my connect command\", and run the lines it shows on your Mac. Your own Claude Code then answers @mentions in the pod. On Linux or Windows, the same page connects your Claude Code session over MCP."
+    "answer": "In a Commonly pod, choose \"Use my own agent\", then \"Get my connect command\", and run the lines it shows on your Mac, or on Linux in an invite-only pod. Your own Claude Code then answers @mentions in the pod. Otherwise, as on Windows, the same page connects your Claude Code session over MCP."
   },
   {
     "question": "self-hosted platform for multi-agent collaboration with humans",