fix(scout): guide DeepSeek Harness connection

backend/__tests__/unit/config/nativeAgents.scoutKnowledge.test.js

@@ -70,16 +70,29 @@ describe('Scout onboarding knowledge', () => {
     expect(prompt).not.toMatch(/v4[ -]?flash/i);
   });
 
-  // 2026-10-19: a new person asked to connect DeepSeek Harness, heard that
-  // DeepSeek models could not be used here, and left within two minutes.
-  test('says yes to DeepSeek models and names both paths, without promising dsh', () => {
-    expect(prompt).toMatch(/DeepSeek models: yes, two ways\. "Run it here"/);
+  // A dsh visitor was turned away after the adapter shipped and the non-admin
+  // macOS walk passed. Keep Scout and the install guide in agreement.
+  test('says yes to DeepSeek Harness and gives its attach path', () => {
+    expect(prompt).toMatch(/DeepSeek models: yes\. If "Run it here" offers a DeepSeek model/);
     expect(prompt).toMatch(/their own OpenCode pointed at DeepSeek's API, through the OpenCode guide/);
-    expect(prompt).toMatch(/DeepSeek Harness \(dsh\), cannot connect yet; do not say when or whether it will/);
-    expect(prompt).toMatch(/lead with the yes: its models can work here today/);
+    expect(prompt).toMatch(/DeepSeek Harness \(dsh\) attached as their own agent in a private pod/);
+    expect(prompt).toMatch(/other OSs are unverified, not refused/);
+    expect(prompt).toMatch(/commonly agent attach dsh --pod <pod-id> --name <name> --env <environment\.json>/);
+    expect(prompt).toMatch(/commonly agent run <name>` to answer @mentions/);
+    expect(prompt).toContain('docs/cli/dsh.md');
+    expect(prompt).not.toMatch(/DeepSeek Harness \(dsh\), cannot connect yet/);
     expect(prompt).toMatch(/name it only when someone asks which model or runtime it uses/);
   });
 
+  test('the dsh guide gives the same attach step and the completed macOS walk', () => {
+    const guide = fs.readFileSync(path.resolve(__dirname, '../../../../docs/cli/dsh.md'), 'utf8');
+    expect(guide).toContain('commonly agent attach dsh --pod <pod-id> --name <name>');
+    expect(guide).toContain('commonly.me/v2/pods/<pod-id>');
+    expect(guide).toMatch(/DeepSeek Harness 0\.2\.1-rc\.2 was walked with a non-admin Commonly account/);
+    expect(guide).toMatch(/macOS using CLI 0\.1\.117/);
+    expect(guide).not.toContain('still required before this adapter merges');
+  });
+
   test('connects OpenCode through its guide, never through the connect card', () => {
     expect(prompt).toMatch(/OpenCode, on a model provider they choose .* connects from the command line, not from this page/);
     expect(prompt).toMatch(/do not propose a connect card for it: the card sets up Claude Code or Codex/);
@@ -90,7 +103,9 @@ describe('Scout onboarding knowledge', () => {
   // 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(/on a Mac, Claude Code or Codex\. On Linux \(WSL included\), Codex only\./);
+    expect(prompt).toMatch(/Claude Code on a Mac; Codex on Mac or Linux \(WSL included\)/);
+    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(/commonly_offer_hosted_agent, or say they can use the pod from their own Claude Code sessions/);
     expect(prompt).not.toMatch(/Windows is not verified yet/);
@@ -109,7 +124,10 @@ describe('Scout onboarding knowledge', () => {
 
   test('cites developer docs that exist in the repository', () => {
     const repo = path.resolve(__dirname, '../../../..');
-    for (const doc of ['docs/agents/BUILDING_AN_AGENT.md', 'docs/api/openapi.yaml', 'docs/cli/opencode.md']) {
+    for (const doc of [
+      'docs/agents/BUILDING_AN_AGENT.md', 'docs/api/openapi.yaml',
+      'docs/cli/opencode.md', 'docs/cli/dsh.md',
+    ]) {
       expect(prompt).toContain(doc);
       expect(fs.existsSync(path.join(repo, doc))).toBe(true);
     }

backend/config/native-agents/scout.ts

@@ -129,8 +129,10 @@ export const scoutApp = {
     // 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.
     + '- Where their own agent can be connected as a teammate that answers '
-    + '@mentions: on a Mac, Claude Code or Codex. On Linux (WSL included), Codex '
-    + 'only. On Windows itself, neither; Codex inside WSL counts as Linux. For '
+    + '@mentions: Claude Code on a Mac; Codex on Mac or Linux (WSL included); '
+    + '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 '
     + '"Run it here" with commonly_offer_hosted_agent, or say they can use the pod '
     + 'from their own Claude Code sessions with the MCP command on the connect '
@@ -148,17 +150,20 @@ export const scoutApp = {
     + 'that Commonly runs, on a model Commonly picks. Gemini can\'t join yet; do '
     + 'not say when or whether it will. So when someone asks for Claude and GPT '
     + 'together, the answer is yes: Claude Code plus Codex.\n'
-    // 2026-10-19: a new person asked to connect DeepSeek Harness and heard
-    // that DeepSeek models could not be used here; hosted agents already ran
-    // on DeepSeek, and OpenCode on DeepSeek had just been walked.
-    + '- DeepSeek models: yes, two ways. "Run it here" (the model is named in '
-    + 'commonly_offer_hosted_agent\'s description), or their own OpenCode pointed '
-    + 'at DeepSeek\'s API, through the OpenCode guide. DeepSeek\'s own command-line '
-    + 'tool, DeepSeek Harness (dsh), cannot connect yet; do not say when or '
-    + 'whether it will. When someone asks for it, lead with the yes: its models '
-    + 'can work here today.\n'
+    // The dsh adapter shipped in CLI 0.1.117 and a non-admin macOS walk
+    // passed 2026-10-21. A prior visitor was incorrectly told it could not join.
+    + '- DeepSeek models: yes. If "Run it here" offers a DeepSeek model (check '
+    + 'commonly_offer_hosted_agent\'s description), they can use that, their own OpenCode pointed '
+    + 'at DeepSeek\'s API, through the OpenCode guide, or DeepSeek Harness '
+    + '(dsh) attached as their own agent in a private pod. The non-admin dsh '
+    + 'walk passed on macOS; other OSs are unverified, not refused. For dsh, '
+    + 'point them to docs/cli/dsh.md in the github.com/Team-Commonly/commonly '
+    + 'repository. The attach step is `commonly agent attach dsh --pod <pod-id> '
+    + '--name <name> --env <environment.json>`, then `commonly agent run '
+    + '<name>` to answer @mentions. The pod id is the last part of its URL. '
+    + 'Lead with the yes when someone asks whether dsh can join.\n'
     + '- What connects as their own agent: Claude Code or Codex from the Bring '
-    + 'your own page, and OpenCode through its guide. Qwen Code and pi are not '
+    + 'your own page, and OpenCode or dsh through their guides. Qwen Code and pi are not '
     + 'ready for outside use; say so if asked. Do not claim any other tool '
     + 'connects.\n'
     + '- Developers building their own agent: Commonly agents use a small HTTP '

docs/cli/dsh.md

@@ -54,6 +54,7 @@ bearer, never the provider key.
 Use a pod that only its members can read. A private dsh seat runs with dsh's
 `workspace-write` permission mode. It is not a public-seat sandbox: the
 adapter refuses `sandbox.trust: public` and any declared `sandbox.mode`.
+The pod id is the last part of its URL: `commonly.me/v2/pods/<pod-id>`.
 
 ```bash
 commonly agent attach dsh --pod <pod-id> --name <name> --env /Users/you/agents/environment.json
@@ -78,6 +79,5 @@ The adapter starts only the Commonly MCP server, with a per-spawn credential
 file. dsh's session data lives under a private, persistent Commonly seat home
 outside the workspace; a second turn resumes only an id found in that home.
 
-The macOS spike confirmed a headless MCP tool call and resume against local
-stand-ins. The live DeepSeek and signed-in Commonly walk is still required
-before this adapter merges.
+DeepSeek Harness 0.2.1-rc.2 was walked with a non-admin Commonly account on
+macOS using CLI 0.1.117.