@@ -0,0 +1,10 @@
+---
+"@bradygaster/squad-sdk": minor
+"@bradygaster/squad-cli": patch
+---
+
+Linked teams now work with either `teamRoot` form: the team repository (what `squad link` writes) or the team's `.squad/` directory (what the docs show). `resolveSquadPaths()` adds `teamSquadDir`, the team's squad directory for both forms, and `resolveSquadState()` roots local-backend storage there. `squad loop`/`watch`, `squad cast`, and the state MCP server read team state from `teamSquadDir`, so `squad loop` no longer reports "No squad found" for the docs form, and `squad_decide` no longer writes decisions outside `.squad/` for the `squad link` form. Closes #2107.
+
+`teamSquadDir` is a required field on the exported `ResolvedSquadPaths` type, so code that constructs that type must now set it. `@bradygaster/squad-sdk/tools` also exports `MUTABLE_STATE_PATHS` and `isMutableStateKey()`, the list of state paths that the state tools can write.
+
+If you linked a team with `squad link`: state that the state MCP server wrote to the team repo root (`decisions.md`, `decisions/inbox/`, `casting/policy.json`, `agents/*/history.md`, `log/`, `orchestration-log/`, `sessions/`, `.scratch/`, `identity/`) now belongs in `<team>/.squad/`. Squad does not move it. Run `squad doctor` to find leftovers. It lists the `.md` and `.json` files to move to the same relative path under `<team>/.squad/` (for example `<team>/identity/now.md` to `<team>/.squad/identity/now.md`), and the files that already exist there, which you must merge by hand without overwriting the newer state. Do not replace the existing `<team>/.squad/` directories. Skills that `squad_skill` wrote went to `.github/skills/` in the folder that contains the team repo; move any you want to keep to `<team>/.github/skills/`. Doctor does not check that folder.
@@ -131,6 +131,8 @@ If your project links to a remote team repository:
 
 The path should be relative to your **project root** (where `.squad/` or `squad.config.ts` lives), not to the `.squad/` directory itself.
 
+`teamRoot` can name either the team repository (`"../team-repo"`, which is what `squad link` writes) or its `.squad/` directory (`"../team-repo/.squad"`). Squad resolves both forms to the same team directory.
+
 **Verify the fix:**
 ```bash
 squad doctor
 
@@ -25,13 +25,11 @@ export async function runCast(cwd: string): Promise<void> {
   }
 
   // Discover project agents.
-  // LocalAgentSource appends .squad/agents to its base path, so we must supply:
-  //   - local mode: parent of paths.projectDir (the repo root)
-  //   - remote mode: paths.teamDir (the team repo root, which itself contains .squad/agents)
-  const agentBase =
-    paths.mode === 'remote'
-      ? paths.teamDir
-      : path.resolve(paths.projectDir, '..');
+  // LocalAgentSource appends .squad/agents to its base path, so local mode
+  // supplies the parent of paths.projectDir (the repo root). Remote mode hands
+  // it the team's agents dir explicitly, because teamRoot may name either the
+  // team repo or its .squad/ dir (#2107).
+  const agentBase = path.resolve(paths.projectDir, '..');
   // #1399: when state is externalized, agents live at <externalStateDir>/agents
   // (no .squad nesting), so the base-path probing above can't reach them —
   // externalize sets teamRoot '.' which lands here as remote mode with a
@@ -42,7 +40,10 @@ export async function runCast(cwd: string): Promise<void> {
     paths.config?.stateLocation === 'external' && paths.config.projectKey
       ? path.join(resolveExternalStateDir(paths.config.projectKey, false), 'agents')
       : undefined;
-  const projectSource = new LocalAgentSource(agentBase, undefined, undefined, externalAgentsDir);
+  const agentsDir =
+    externalAgentsDir
+    ?? (paths.mode === 'remote' ? path.join(paths.teamSquadDir, 'agents') : undefined);
+  const projectSource = new LocalAgentSource(agentBase, undefined, undefined, agentsDir);
   const projectAgents = await projectSource.listAgents();
 
   // Discover personal agents
 
@@ -14,6 +14,8 @@ import path from 'node:path';
 import { execFile, execFileSync } from 'node:child_process';
 import { FSStorageProvider, resolveStateBackend, type StateBackendType } from '@bradygaster/squad-sdk';
 import { readCastingRegistryPair } from '@bradygaster/squad-sdk/casting';
+import { resolveSquadPaths, clearResolveSquadCache } from '@bradygaster/squad-sdk/resolution';
+import { isMutableStateKey, MUTABLE_STATE_PATHS } from '@bradygaster/squad-sdk/tools';
 import { resolveStateDir } from '../core/effective-squad-dir.js';
 
 const storage = new FSStorageProvider();
@@ -158,6 +160,77 @@ function checkTeamRootResolves(squadDir: string, teamRoot: string): DoctorCheck
   };
 }
 
+/** Squad writes state as .md and .json; other files in a code dir named log/ etc. are not ours. */
+const STRAY_STATE_FILE = /\.(md|json)$/;
+const STRAY_STATE_MAX_DEPTH = 4;
+const STRAY_STATE_LIST_LIMIT = 10;
+
+/** Push `/`-separated keys of files under `base/rel`. Skips dirs it cannot list. */
+function collectFileKeys(base: string, rel: string, depth: number, out: string[]): void {
+  let entries: string[];
+  try {
+    entries = storage.listSync(path.join(base, rel));
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    const key = `${rel}/${name}`;
+    const full = path.join(base, key);
+    if (isDirectory(full)) {
+      if (depth > 1) collectFileKeys(base, key, depth - 1, out);
+    } else {
+      out.push(key);
+    }
+  }
+}
+
+function formatKeyList(keys: string[]): string {
+  const shown = keys.slice(0, STRAY_STATE_LIST_LIMIT).join(', ');
+  return keys.length > STRAY_STATE_LIST_LIMIT ? `${shown}, and ${keys.length - STRAY_STATE_LIST_LIMIT} more` : shown;
+}
+
+/**
+ * Before #2107, a `squad link` project (teamRoot = the team repo) made the
+ * state MCP server write team state to `<teamRoot>/<key>` instead of
+ * `<teamRoot>/.squad/<key>`. Squad no longer reads those files. Report every
+ * state-tool path (MUTABLE_STATE_PATHS) found there, split into files to move
+ * and files to merge by hand because a newer copy exists. Read-only.
+ */
+function checkStrandedLinkedTeamState(squadDir: string): DoctorCheck | undefined {
+  // Doctor must see the current disk, not a walk cached by an earlier call.
+  clearResolveSquadCache();
+  const paths = resolveSquadPaths(path.dirname(squadDir));
+  if (!paths || paths.mode !== 'remote' || paths.projectDir !== path.resolve(squadDir)) return undefined;
+  if (paths.teamSquadDir === paths.teamDir) return undefined;
+
+  const candidates: string[] = [];
+  for (const { root, kind } of MUTABLE_STATE_PATHS) {
+    const full = path.join(paths.teamDir, root);
+    if (kind === 'file') {
+      if (fileExists(full) && !isDirectory(full)) candidates.push(root);
+    } else if (isDirectory(full)) {
+      collectFileKeys(paths.teamDir, root, STRAY_STATE_MAX_DEPTH, candidates);
+    }
+  }
+  // Match only what the state tools could write, so an unrelated code dir
+  // named agents/ or log/ does not trigger advice to move it.
+  const stray = candidates.filter(key => isMutableStateKey(key) && STRAY_STATE_FILE.test(key));
+  if (stray.length === 0) return undefined;
+
+  const toMerge = stray.filter(key => fileExists(path.join(paths.teamSquadDir, key)));
+  const toMove = stray.filter(key => !toMerge.includes(key));
+  const parts = [
+    `found ${stray.length} team state file(s) in ${paths.teamDir}, outside the team's squad dir. Squad now reads team state from ${paths.teamSquadDir}.`,
+  ];
+  // teamSquadDir normally has its own agents/ and decisions/, so tell the user
+  // to move files, not to move (and replace) the directories.
+  if (toMove.length > 0) parts.push(`Move each file to the same relative path under it: ${formatKeyList(toMove)}.`);
+  if (toMerge.length > 0) parts.push(`A file already exists at the same relative path for these; merge by hand and do not overwrite the newer state: ${formatKeyList(toMerge)}.`);
+  parts.push('Do not replace the existing directories there.');
+
+  return { name: 'linked team state location', status: 'warn', message: parts.join(' ') };
+}
+
 function checkTeamMd(squadDir: string): DoctorCheck {
   const teamPath = path.join(squadDir, 'team.md');
   if (!fileExists(teamPath)) {
@@ -717,6 +790,8 @@ export async function runDoctor(cwd?: string): Promise<DoctorCheck[]> {
   // 4. Remote team root resolution
   if (mode === 'remote' && teamRoot) {
     checks.push(checkTeamRootResolves(squadDir, teamRoot));
+    const strayState = checkStrandedLinkedTeamState(squadDir);
+    if (strayState) checks.push(strayState);
   }
 
   // 5–9 standard files (only if .squad/ exists)
 
@@ -69,7 +69,7 @@ export function createStateMcpToolRegistry(startDir: string): ToolRegistry {
   if (!context) {
     throw new Error(`No .squad directory found from ${startDir}`);
   }
-  return new ToolRegistry(context.paths.teamDir, undefined, context.storage);
+  return new ToolRegistry(context.paths.teamSquadDir, undefined, context.storage);
 }
 
 function normalizeToolResult(result: unknown): { content: Array<{ type: 'text'; text: string }>; isError?: boolean } {
 
@@ -7,7 +7,6 @@
  * @module cli/core/effective-squad-dir
  */
 
-import path from 'node:path';
 import { detectSquadDir, type SquadDirInfo } from './detect-squad-dir.js';
 import {
   loadDirConfig,
@@ -52,7 +51,7 @@ export function effectiveSquadDir(dest: string): EffectiveSquadDirs {
   const paths = resolveSquadPaths(dest);
   const teamSquadDir =
     paths?.mode === 'remote'
-      ? path.join(paths.teamDir, paths.name)
+      ? paths.teamSquadDir
       : local.path;
   return {
     local,
 
@@ -132,8 +132,19 @@ export interface ResolvedSquadPaths {
   mode: 'local' | 'remote';
   /** Project-local .squad/ (decisions, logs) */
   projectDir: string;
-  /** Team identity root (agents, casting, skills) */
+  /**
+   * Team identity root, exactly as configured. In remote mode this is the
+   * resolved `teamRoot`, which may be either the team repo (parent of
+   * `.squad/`) or the team's `.squad/` dir itself. Do not join team-state
+   * paths (`.squad`, `agents/`, `decisions/`) onto it — the result depends on
+   * which form the user wrote. Use {@link ResolvedSquadPaths.teamSquadDir}.
+   */
   teamDir: string;
+  /**
+   * The team's squad directory (team.md, agents/, casting/), whichever form
+   * `teamRoot` uses. Equals projectDir in local mode.
+   */
+  teamSquadDir: string;
   /** User's personal squad dir, null if not found or disabled */
   personalDir: string | null;
   config: SquadDirConfig | null;
@@ -344,6 +355,26 @@ export function isConsultMode(config: SquadDirConfig | null): boolean {
   return config?.consult === true;
 }
 
+/**
+ * Resolve the team's squad directory from a remote `teamRoot` (#2107).
+ *
+ * `squad link` writes `teamRoot` as the team repo (the parent of `.squad/`),
+ * while the docs show the team's `.squad/` dir itself; the coordinator accepts
+ * both. Prefer a nested squad dir; otherwise use teamDir when it already is
+ * one. Falls back to the nested path so a missing team reports "not found".
+ */
+function resolveTeamSquadDir(teamDir: string, name: '.squad' | '.ai-team'): string {
+  const names = name === '.squad' ? ['.squad', '.ai-team'] : ['.ai-team', '.squad'];
+  for (const candidate of names) {
+    const nested = path.join(teamDir, candidate);
+    if (storage.existsSync(nested) && storage.isDirectorySync(nested)) return nested;
+  }
+  if (names.includes(path.basename(teamDir)) || storage.existsSync(path.join(teamDir, 'team.md'))) {
+    return teamDir;
+  }
+  return path.join(teamDir, name);
+}
+
 /**
  * Resolve dual-root squad paths (projectDir / teamDir).
  *
@@ -377,6 +408,7 @@ export function resolveSquadPaths(startDir?: string): ResolvedSquadPaths | null
       mode: 'remote',
       projectDir,
       teamDir,
+      teamSquadDir: resolveTeamSquadDir(teamDir, name),
       personalDir: resolvePersonalSquadDir(),
       config,
       name,
@@ -389,6 +421,7 @@ export function resolveSquadPaths(startDir?: string): ResolvedSquadPaths | null
     mode: 'local',
     projectDir,
     teamDir: projectDir,
+    teamSquadDir: projectDir,
     personalDir: resolvePersonalSquadDir(),
     config,
     name,
@@ -851,12 +884,12 @@ export function resolveSquadState(startDir?: string, cliOverride?: StateBackendT
 
   // For local backend, use FSStorageProvider directly (more capable).
   // For git-notes/orphan, bridge via StateBackendStorageAdapter.
-  // rootDir is paths.teamDir (matches the squadRoot every local-backend
+  // rootDir is paths.teamSquadDir (matches the squadRoot every local-backend
   // caller — e.g. ToolRegistry in state-mcp.ts — builds its paths against),
   // so the traversal guard actually validates instead of no-op'ing on an
   // unset rootDir and letting a bad upstream path resolve silently.
   const stateStorage: StorageProvider = backend.name === 'local'
-    ? new FSStorageProvider(paths.teamDir)
+    ? new FSStorageProvider(paths.teamSquadDir)
     : new StateBackendStorageAdapter(backend, paths.projectDir);
 
   return { paths, backend, repoRoot, storage: stateStorage };
 
@@ -255,23 +255,31 @@ function normalizeStateToolDir(dir?: string): string {
   return normalized;
 }
 
-const MUTABLE_CASTING_STATE_KEYS = new Set([
-  'casting/policy.json',
-]);
+/**
+ * State paths, relative to the squad dir, that the state tools may write.
+ * `root` is a file or the directory to search; `pattern`, when set, is the
+ * only key shape allowed under that directory.
+ */
+export const MUTABLE_STATE_PATHS: ReadonlyArray<{ readonly root: string; readonly kind: 'file' | 'dir'; readonly pattern?: RegExp }> = [
+  { root: 'decisions.md', kind: 'file' },
+  { root: 'decisions/inbox', kind: 'dir' },
+  { root: 'casting/policy.json', kind: 'file' },
+  { root: 'agents', kind: 'dir', pattern: /^agents\/[a-zA-Z0-9_-]+\/history\.md$/ },
+  { root: 'log', kind: 'dir' },
+  { root: 'orchestration-log', kind: 'dir' },
+  { root: 'sessions', kind: 'dir' },
+  { root: '.scratch', kind: 'dir' },
+  { root: 'identity', kind: 'dir' },
+];
+
+/** True when the state tools may write `key` (a normalized, `/`-separated state key). */
+export function isMutableStateKey(key: string): boolean {
+  return MUTABLE_STATE_PATHS.some(({ root, kind, pattern }) =>
+    kind === 'file' ? key === root : key.startsWith(`${root}/`) && (!pattern || pattern.test(key)));
+}
 
 function validateMutableStateToolKey(key: string): void {
-  const isMutable =
-    key === 'decisions.md' ||
-    key.startsWith('decisions/inbox/') ||
-    MUTABLE_CASTING_STATE_KEYS.has(key) ||
-    /^agents\/[a-zA-Z0-9_-]+\/history\.md$/.test(key) ||
-    key.startsWith('log/') ||
-    key.startsWith('orchestration-log/') ||
-    key.startsWith('sessions/') ||
-    key.startsWith('.scratch/') ||
-    key.startsWith('identity/');
-
-  if (!isMutable) {
+  if (!isMutableStateKey(key)) {
     throw new Error(
       'State mutations are limited to mutable runtime state (decisions, inbox, casting policy, logs, sessions, scratch files, agent history, and identity). The casting registry/history pair must only be changed through the atomic casting protocol. Static config such as config.json, team.md, routing.md, charters, templates, and skills must not be changed with state tools.',
     );
 
@@ -4,7 +4,7 @@
  * Verifies the cast command correctly discovers project agents
  * by deriving the correct base path from resolveSquadPaths():
  *   - local mode:  parent of paths.projectDir (repo root)
- *   - remote mode: paths.teamDir (team repo root)
+ *   - remote mode: paths.teamSquadDir/agents (either teamRoot form, #2107)
  * Regression tests for #871 (double-nested .squad/.squad/agents path).
  */
 
@@ -151,6 +151,32 @@ describe('squad cast', () => {
     expect(output).toContain('Session Cast');
   });
 
+  it("discovers agents in remote mode when teamRoot names the team's .squad dir (#2107)", async () => {
+    const projectRoot = join(TEST_ROOT, 'project');
+    const teamRoot = join(TEST_ROOT, 'team');
+
+    const projectSq = join(projectRoot, '.squad');
+    await mkdir(projectSq, { recursive: true });
+    await writeFile(
+      join(projectSq, 'config.json'),
+      JSON.stringify({ version: 1, teamRoot: '../team/.squad' }),
+    );
+
+    await mkdir(join(teamRoot, '.squad', 'agents', 'remote-agent'), { recursive: true });
+    await writeFile(
+      join(teamRoot, '.squad', 'agents', 'remote-agent', 'charter.md'),
+      `## Identity\n\n**Name:** RemoteAgent\n**Role:** Remote Engineer\n`,
+    );
+
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    const { runCast } = await import('@bradygaster/squad-cli/commands/cast');
+    await runCast(projectRoot);
+
+    const output = logSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(output, 'teamRoot=../team/.squad').toContain('RemoteAgent');
+  });
+
   it('discovers agents from the external state dir when state is externalized (#1399)', async () => {
     const extGlobal = join(TEST_ROOT, 'global');
     const projectKey = `test-cast-ext-${randomBytes(4).toString('hex')}`;
Original file line number	Diff line number	Diff line change
`@@ -69,7 +69,7 @@ export function createStateMcpToolRegistry(startDir: string): ToolRegistry {`
`69`	`69`	`if (!context) {`
`70`	`70`	throw new Error(`No .squad directory found from ${startDir}`);
`71`	`71`	`}`
`72`		`- return new ToolRegistry(context.paths.teamDir, undefined, context.storage);`
	`72`	`+ return new ToolRegistry(context.paths.teamSquadDir, undefined, context.storage);`
`73`	`73`	`}`
`74`	`74`
`75`	`75`	`function normalizeToolResult(result: unknown): { content: Array<{ type: 'text'; text: string }>; isError?: boolean } {`